.. Generated by merging the following
..    ../../neuron/general/function/obsolete/lw.rst
..    ../../neuron/general/function/mcran4.rst
..    ../../neuron/general/function/sscanf.rst
..    ../../neuron/general/function/0fun.rst         DONE
..    ../../neuron/general/function/sin.rst
..    ../../neuron/general/function/pwmplace.rst
..    ../../neuron/general/function/ocfunc.rst       DONE
..    ../../neuron/general/function/system.rst       DONE
..    ../../neuron/general/function/symbols.rst      DONE
..    ../../neuron/general/function/dialog.rst       DONE
..    ../../neuron/general/function/checkpnt.rst     DONE

functions
=========

PUT ALPHABETIC SEQUENCE JUMP TABLE HERE

argument-related
----------------

.. function:: numarg

    Syntax:
        ``n = numarg()``

    Description:
        Number of arguments passed to a user written hoc function. 

    .. seealso::
        :ref:`arguments`, :func:`argtype`
         

----

.. function:: argtype

    Syntax:
        ``itype = argtype(iarg)``

    Description:
        The type of the ith arg. The return value is 0 for numbers, 1 for objref, 
        2 for strdef, 3 for pointers to numbers, and -1 if the arg does not exist. 

    .. seealso::
        :ref:`arguments`, :func:`numarg`

----

.. function:: hoc_pointer_

    Syntax:
        ``hoc_pointer_(&variable)``

    Description:
        A function used by c and c++ implementations to request a pointer to 
        the variable from its interpreter name. Not needed by the user. 


code-executing
--------------

.. function:: execute

    Syntax:
        ``execute("statement")``

        ``execute("statement", objref)``

    Description:
        parse and execute the command in the context 
        of the object. If second arg not present then execute it at the 
        top level of the interpreter. 
        If command begins with a '~' then the tilda is removed and the rest 
        of the command is executed without enclosing it in {}. This allows 
        one to create a  func or proc dynamically. 

    .. seealso::
        :func:`execute1`


----

.. function:: execute1

    Syntax:
        ``err = execute1("statement")``

        ``err = execute1("statement", objref)``

        ``err = execute1("statement", show_err_mes)``

        ``err = execute1("statement", objref, show_err_mes``

    Description:
        Same as :func:`execute` but returns 0 if there was an interpreter error 
        during execution of the statement and returns 1 if successful. 
        Does not surround the command with {}. 
         
        If the show_err_mes arg is present and equal to 0 then the normal 
        interpreter error message printing is turned off for the scope of the 
        statement. 
         
        Error messages can be turned on even inside the statement 
        with :func:`show_errmess_always`. 
         
        Parse and execute the command in the context 
        of the object. If second arg not present then execute it at the 
        top level of the interpreter. 
         
    Example:
        Execute1 is heavily used in the construction of the fitter widgets. 
        It is also useful to objects in gaining information about the outside with 
        the idiom 

        .. code-block::
            none

            sprint(cmd, "%s.var = outside_var", this) 
            execute1(cmd) 

        Here, outside_var is unavailable from within the object and so 
        a command is constructed which can be executed at the top level where that 
        variable is available and sets the public var in the object. 


code-loading
------------

.. function:: load_proc

    Syntax:
        ``load_proc("name1", ...)``

        ``load_func("name1", ...)``

        ``load_template("name1", ..._``

    Description:
        Load the file containing a definition. 
         
        For each name in the list 
        all the :file:`*.oc` and :file:`*.hoc` files will be searched and the first file that 
        contains the appropriate proc, func, or begintemplate will be loaded. 
        Loading only takes place if the name has not previously been defined. 
        The search path consists of the current working directory, followed by 
        the paths in the environment variable HOC_LIBRARY_PATH (space separated), 
        followed by :file:`$NEURONHOME/lib/hoc`. 
        Remember that only entire files are loaded-- not just the definition of 
        the name. And nothing is loaded if the name is already defined. 
        Inadvertent recursion will use up all the file descriptors. 
        For efficiency, on the first load, all the names are cached in a 
        temporary file and the file is scanned on subsequent loads for that session. 
         
    .. warning::
        This command is very slow under mswindows. Therefore it is often 
        useful to explicitly load the standard run library with the statement: 

        .. code-block::
            none

            xopen("$(NEURONHOME)/lib/hoc/noload.hoc") 


----

.. function:: load_file

    Syntax:
        ``load_file("filename")``

        ``load_file("filename", "name")``

        ``load_file(0or1, "filename")``

    Description:
        Similar to :func:`load_proc` but loads files and so does not have the 
        search overhead. Suitable for loading packages of files. 
         
        The functionality is identical to :func:`xopen` except that the xopen takes 
        place only if 
        if a file of that name has not already been loaded with the load_file, 
        :func:`load_proc`, :func:`load_template`, or :func:`load_func` functions. 
        The file is searched for in the current working 
        directory, $HOC_LIBRARY_PATH (a colon or space separated list of directories), 
        and :file:`$NEURONHOME/lib/hoc` directories (in that order) for 
        the file if there is no directory prefix. 
        Before doing the xopen on the file the current working directory is 
        temporarily changed to the directory containing the file so 
        that it can xopen files relative to its location. 
         
        If the second string arg exists, the file is xopen'ed only if the 
        name is not defined as a variable AND the file has not been loaded 
        with load_file. This is useful in those cases where the package was 
        first xopen'ed without going through the load_file function. 
         
        If the first arg is a number and is 1, then the file is loaded again even 
        if it has already been loaded. 


    Description:


----

.. function:: load_func

        see :func:`load_proc` 

----

.. function:: load_template

        see :func:`load_proc` 


equation-related
----------------

.. function:: prmat

        Prints the form of the matrix defined by :ref:`eqn <keyword_eqn>` statements. Each nonzero 
        element is printed as an "*". 


----

.. function:: solve

        Does one iteration of the non-linear system defined by :ref:`eqn <keyword_eqn>` statements. 
        Returns the linear norm of the difference between left and right hand sides 
        plus the change in the dependent variables. 


----

.. function:: eqinit

        Throws away previous dependent variable and equation specifications 
        from :ref:`eqn <keyword_eqn>` statements. 


error-handling
--------------

.. function:: coredump_on_error

    Syntax:
        ``coredump_on_error(1 or 0)``

    Description:
        On unix machines, sets a flag which requests (1) a coredump in case 
        of memory or bus errors. 


----

.. function:: show_errmess_always

    Syntax:
        ``show_errmess_always(boolean)``

    Description:
        Sets or turns off a flag which, if on, always prints the error message even 
        if normally turned off by an :func:`execute1` statement or other call to the 
        interpreter. 


----

.. function:: execerror

    Syntax:
        ``execerror("message1", "message2")``

    Description:
        Raise an error and print the messages along with an interpreter stack
        trace. If there are no arguments, then nothing is printed.


interpreter management
----------------------

.. function:: saveaudit

        Not completely implemented at this time. Saves all commands executed 
        by the interpreter. 


----

.. function:: retrieveaudit

        Not completely implemented at this time. See :func:`saveaudit` . 


----

.. function:: quit

        Exits the program. Can be used as the action of a button. If edit buffers 
        are open you will be asked if you wish to save them before the final exit.


math
----

.. toctree::
    :maxdepth: 2

    ../../neuron/general/function/math.rst


mcell_ran4
----------

.. toctree::
    :maxdepth: 2

    ../../neuron/general/function/mcran4.rst


namespace-related
-----------------

.. function:: name_declared

    Syntax:
        ``type = name_declared("name")``

        ``type = name_declared("name", 1)``

    Description:
        Return 0 if the name is not in the symbol table. The first form looks 
        for names in the top level symbol table. The second form looks in the 
        current object context. 
         
        If the name exists return 
         
        2 if an :func:`objref` . 
         
        3 if a Section 
         
        4 if a :ref:`strdef <keyword_strdef>` 
         
        5 if a scalar or :ref:`double <keyword_double>` variable. 
         
        1 otherwise 
         
        Note that names can be (re)declared only if they do not already 
        exist or are already of the same type. 
        This is too useful to require the user to waste an objref in creating a 
        :class:`StringFunctions` class to use :meth:`~StringFunctions.is_name`. 

        .. code-block::
            none

            name_declared("nrnmainmenu_") 
            {object_push(nrnmainmenu_) print name_declared("ldfile", 0) object_pop()} 
            {object_push(nrnmainmenu_) print name_declared("ldfile", 1) object_pop()} 


----

.. function:: symbols

    Name:
        symbols --- type the names of HOC functions and variables 

    Syntax:
        ``symbols()``

    Description:
        Types a list of functions and variable names defined in HOC.  Dimensions 
        of arrays are also indicated. 

    .. warning::
        No longer works. The nearest replacement is :func:`SymChooser` . 


----

object-related
--------------

.. function:: object_id

    Syntax:
        ``object_id(objref)``

        ``object_id(objref, 1)``

    Description:
        Returns 0 if the object reference does not point to an object instance. 
        (Otherwise returns the pointer cast to a double, not a very useful number) 
         
        If the second argument is 1, it returns the index of the object name. Returns 
        -1 if the object is the NULLObject. 


----

.. function:: allobjectvars

    Syntax:
        ``allobjectvars()``

    Description:
        Prints all the object references (objref variables) that have been 
        declared along with the class type of the object they reference and the 
        number of references. 

    .. warning::
        Instead of printing the address of the object in hex format, it ought 
        also to print the object_id and/or the internal instance name. 

----

.. function:: allobjects

    Syntax:
        ``allobjects()``

        ``allobjects("templatename")``

        ``nref = allobjects(objectref)``

    Description:
        Prints the internal names of all class instances (objects) available 
        from the interpreter along with the number of references to them. 
         
        With a templatename the list is restricted to objects of that class. 
         
        With an object variable, nothing is printed but the reference count 
        is returned. The count is too large by one if the argument was of the 
        form templatename[index] since a temporary reference is created while 
        the object is on the stack during the call. 


----

.. function:: object_push

    Syntax:
        ``object_push(objref)``

    Description:
        Enter the context of the object referenced by objref. In this context you 
        can directly access any variables or call any functions, even those not 
        declared as :ref:`public <keyword_public>`. Do not attempt to create any new symbol names! 
        This function is generally used by the object itself to save its state 
        in a session. 


----

.. function:: object_pop

    Syntax:
        ``object_pop()``

    Description:
        Pop the last object from an :func:`object_push` . 


session-related
---------------

.. function:: print_session

    Syntax:
        ``0 = print_session(useprinter, "name")``

        ``0 = print_session(useprinter, "name", useselected)``

        ``0 = print_session()``

    Description:
        Print a postscript file consisting of certain windows on the screen. 
         
        If useprinter==1 postscript is piped to the filter given by "name" 
        which should be able to deal with standard input (UNIX). If useprinter==0 
        the postscript is saved in the file specified by "name". 
         
        If there is a third arg equal to 1 then the printed windows are those 
        selected and arranged on the paper icon of the :ref:`PWM` and calling this function 
        is equivalent to pressing the :ref:`PWM_Print` button. Otherwise all 
        printable windows are printed in landscape mode with a size such that 
        the screen fits on the paper. 
         
        If there are no arguments then all the windows are printed in way that 
        works for mac, mswin, and unix. 


----

.. function:: save_session

    Syntax:
        ``0 = save_session("filename")``

        ``0 = save_session("filename", "header")``

    Description:
        Save all the (saveable) windows on the screen to filename. 
        This is equivalent to pressing the :ref:`Session_SaveAll` button 
        on the :ref:`pwm`.
        If the header argument exists, it is copied to the beginning of 
        the file. 

    .. seealso::
        :meth:`PWManager.save`


----

.. function:: pwman_place

    Syntax:
        ``pwman_place(left, top)``

        ``pwman_place(left, top, 0)``

    Description:
        moves the PrintWindowManager to the indicated location in pixel 
        coordinates where 0,0 is the top left corner of the screen. 
        It is intended that if you build an interface by placing windows 
        near the top and build right then the session you save will 
        be portable to other window managers and other systems with 
        different screen sizes. 
         
        If the third argument is 0, then the window is placed but hidden. 


----

.. function:: checkpoint

    Syntax:
        :samp:`checkpoint("{filename}")`

    Description:
        saves the current state of the system in a portable file to 
        allow one to take up where you left off -- possibly on another 
        machine. Returning to this state is accomplished by running the 
        program with the checkpoint file as the first argument. 
        If the checkpoint file is inconsistent with the executable the 
        program prints an error message and exits. 
         
        At this time many portions of the computer state are left out of the 
        checkpoint file, i.e. it is not as complete as a core dump. 
        Some things that ARE included are: 
        all interpreter symbols with definitions and values, 
        all hoc instructions, 
        all neuron state/parameters with mechanisms. 
        Many aspects of the GUI are not included. 
         
    .. warning::
        There is not enough implementation at this time to make this 
        facility useful. Use the :class:`SaveState` class instead.


stopwatch
---------

.. function:: startsw

        Initializes a stopwatch with a resolution of 1 second or 0.01 second if 
        gettimeofday system call is available. See :func:`stopsw` . 


----

.. function:: stopsw

        Returns the time in seconds since the stopwatch was last initialized with a :func:`startsw` . 

        .. code-block::
            none

            startsw() 
            for i=1,1000000 { x = sin(.2) ] 
            stopsw() 

    .. warning::
        Really the idiom 

        .. code-block::
            none

            x = startsw() 
            //... 
            startsw() - x 

        should be used since it allows nested timing intervals. 


string
------

.. function:: sprint

    Syntax:
        ``sprint(strdef, "format", args)``

    Description:
        Prints to a string. See :func:`printf` 


----

.. function:: strcmp

    Syntax:
        ``x = strcmp("string1", "string2")``

    Description:
        return negative, 0, or positive value 
        depending on how the strings compare lexicographically. 
        0 means they are identical. 


system
------

.. function:: chdir

    Syntax:
        ``chdir("path")``

    Description:
        Change working directory to the indicated path. Returns 0 if successful 
        otherwise -1, ie the usual unix os shell return style. 
         

----

.. function:: getcwd

    Syntax:
        ``string = getcwd()``

    Description:
        Returns absolute path of current working directory in unix format. 
        The last character of the path name is '/'. 
        Must be less than 
        1000 characters long. 


----

.. function:: machine_name

    Syntax:
        ``strdef name``

        ``machine_name(name)``

    Description:
        returns the hostname of the machine. 


----

.. function:: system

    Name:
        system --- issue a shell command 

    Syntax:
        ``exitcode = system(cmdstr)``

        ``exitcode = system(cmdstr, stdout_str)``

    Description:
        Executes *cmdstr* as though it had been typed as 
        command to a unix shell from the terminal.  HOC waits until the command is 
        completed. If the second strdef arg is present, it receives the stdout stream 
        from the command. Only available memory limits the line length and 
        number of lines. 

    Example:

        \ ``system("ls")`` 
            Prints a directory listing in the console terminal window. 
            will take up where it left off when the user types the \ ``exit`` 
            command 

    .. warning::
        Fully functional on unix, mswin under cygwin, and mac osx. 
         
        Does not work on the mac os 9 version. 
         
        Following is obsolete: 
        Under mswin, executes the string under the cygwin sh.exe in :file:`$NEURONHOME/bin`
        via the wrapper, :file:`$NEURONHOME/lib/nrnsys.sh`. Normally, stdout is directed to 
        the file :file:`tmpdos2.tmp` in the working directory and this is copied to the 
        terminal. The neuron.exe busy waits until the nrnsys.sh script creates 
        a tmpdos1.tmp file signaling that the system command has completed. 
        Redirection of stdout to a file can only be done with the idiom 
        "command > filename". No other redirection is possible except by modifying 
        :file:`nrnsys.sh`. 
         

----

.. function:: neuronhome

    Name:
        neuronhome -- installation path 

    Syntax:
        ``string = neuronhome()``

    Description:
        Returns the full installation path in unix format or, if it exists, the 
        NEUROHOME environment variable in unix format. 
         
        Note that for unix, it isn't exactly the installation path 
        but the 
        --prefix/share/nrn directory where --prefix is the 
        location specified during installation. For the mswin version it is the location 
        selected during installation and the value is derived from the location 
        of neuron.exe in neuronhome()/bin/neuron.exe. 
        For mac it is the folder that contains the neuron 
        executable program. 
         

----

.. function:: show_winio

    Syntax:
        ``show_winio(0or1)``

    Description:
        MSWin and Mac version only. Hides or shows the console window. 
         

----

.. function:: WinExec

    Syntax:
        ``WinExec("mswin command")``

    Description:
        MSWin version only. 
         

----

.. function:: unix_mac_pc

    Syntax:
        ``type = unix_mac_pc()``

    Description:
        Return 1 if unix, 2 if mac, 3 if mswin, or 4 if mac osx darwin 
        is the operating system. This 
        is useful when deciding if a machine specific function can be called or 
        a dll can be loaded. 
         

----

.. function:: nrn_load_dll

    Syntax:
        ``nrn_load_dll(dll_file_name)``

    Description:
        Loads a dll containing membrane mechanisms. This works for mswin, mac, 
        and linux. 
         

----

.. function:: nrnversion

    Syntax:
        ``versionstring = nrnversion()``

        ``string = nrnversion(i)``

    Description:
        Returns a string consisting of version information. 
        When this function was introduced the majorstring was "5.6" 
        and the branch string was "2004/01/22 Main (36)". 
        Now the arg can range from 0 to 6. The value of 6 returns 
        the args passed to configure. When this function was last changed 
        the return values were 

        .. code-block::
            none

            oc>nrnversion() 
            NEURON -- VERSION 7.1 (296:ff4976021aae) 2009-02-27 
            oc>for i=0,6 print i,": ", nrnversion(i) 
            0 : 7.1 
            1 : NEURON -- VERSION 7.1 (296:ff4976021aae) 2009-02-27 
            2 : VERSION 7.1 (296:ff4976021aae) 
            3 : ff4976021aae 
            4 : 2009-02-27 
            5 : 296 
            6 : '--prefix=/home/hines/neuron/nrnmpi' '--srcdir=../nrn' '--with-paranrn' '--with-nrnpython' 
            oc> 

    .. warning::
        An arg of 7 now returns a space separated string of the arguments used 
        during launch. 
        e.g. 

        .. code-block::
            none

            $ nrniv -nobanner -c 'nrnversion()' -c 'nrnversion(7)' 
            NEURON -- VERSION 7.2 twophase_multisend (534:2160ccb31406) 2010-12-09 
            nrniv -nobanner -c nrnversion() -c nrnversion(7) 
            $  

        An arg of 8 now returns the host-triplet. E.g.

        .. code-block::
          none

          $ nrniv -nobanner -c 'nrnversion(8)'
          x86_64-unknown-linux-gnu

        An arg of 9 now returns "1" if the neuron main program was launched,
        "2" if the library was loaded by Python, and "0" if the launch
        progam is unknown

        .. code-block::
          none

          $ nrniv -nobanner -c 'nrnversion(9)'
          1

        .. code-block::
          none

          $ python 2</dev/null
          >>> from neuron import h
          >>> h.nrnversion(9)
          '2'


user interface
--------------

.. function:: ivoc_style

    Syntax:
        ``ivoc_style("name", "attribute")``

    Description:
        Gives the style attribute to name. Any property listed in the file 
        :file:`$(NEURONHOME)/lib/nrn.defaults` or :file:`$(NEURONHOME)/src/ivoc/ivocmain.c`
        can be changed although it may be that a few of them have already been 
        used by the time the interpreter is invoked. 

    Example:

        .. code-block::
            none

            // 7 decimal places in value field editors. Must be done prior to any panel. 
            ivoc_style("*xvalue_format", "%.7g") 
            // large fonts in unix. Takes effect on next panel. 
            ivoc_style("*font", "*helvetica-medium-r-normal*--24*") 
            ivoc_style("*MenuBar*font", "*helvetica-medium-r-normal*--24*") 
            ivoc_style("*MenuItem*font", "*helvetica-medium-r-normal*--24*") 


----

.. function:: variable_domain

    Syntax:
        ``variable_domain(&variable, lower_limit, upper_limit)``

        ``variable_domain("varname", lower_limit, upper_limit)``

    Description:
        Define the domain limits for any variable for which one can take its address. 
        At this time only field editors check the variable domain. If one 
        attempts to enter a value into a field editor which is not in the domain, the 
        value will be set to the upper or lower limit. Important NEURON 
        variables such as dt, L, diam, and Ra have reasonable default domains. 
        Many parameters defined in model description files also have reasonable domains. 
         
        This function is most useful when a variable makes sense only as a 
        non-negative or positive number. 
         
        One can specify different domains only on a per name basis. Thus there 
        is only one domain specification for L and one for all the instances of 
        IClamp.amp but one can have a different specification 
        for IClamp.amp and VClamp.amp . 


----

.. function:: units

    Syntax:
        ``current_units = units(&variable)``

        ``current_units = units(&variable, "units string")``

        ``"on or off" = units(1 or 0)``

        ``current_units = units("varname", ["units string"])``

    Description:
        When units are on (default on) value editor buttons display the units 
        string (if it exists) along with the normal prompt string. Units for 
        L, diam, Ra, t, etc are built-in and units for membrane mechanism variables 
        are declared in the model description file. See modlunit . 
        Note that units are NOT saved in a session. Therefore, any user defined 
        variables must be given units before retrieving a session that shows them 
        in a panel. 
         
        The units display may be turned off with \ ``units(0)`` or by setting the 
        \ ``*units_on_flag: off`` in the nrn/lib/nrn.defaults file. 
         
        \ ``units(&variable)`` returns the units string for any 
        variable for which an address can be taken. 
         
        \ ``units(&variable, "units string")`` sets the units for the indicated 
        variable. 
         
        If the first arg is a string, it is treated as the name of the variable. 
        This is restricted to hoc variable names of the style, "name", or "classname.name". 
        Apart from the circumstance that the string arg style must be used when 
        executed from Python, a benefit is that it can be used when an instance 
        does not exist (no pointer to a variable of that type). 
        If there are no units specified for the variable name, or the variable 
        name is not defined, the return value is the empty string. 

    Example:

        .. code-block::
            none

            units(&t) // built in as "ms" 
            units("t") 
            units("ExpSyn.g") // built in as "uS" 
            x = 1 
            {units(&x, "mA/cm2")}	// declare units for variable x 
            units(&x)		// prints mA/cm2 
            proc p () { 
            	xpanel("Panel") 
            	xvalue("t") 
            	xvalue("prompt for x", "x", 1) 
            	xpanel() 
            } 
            p()		//shows units in panel 
            units(0) 	// turn off units 
            p()		// does not show units in panel 

    .. warning::
        In the Python world, the first arg must be a string as the pointer style will 
        raise an error. 


----

.. function:: boolean_dialog

    Syntax:
        ``boolean_dialog("label", ["accept", "cancel"])``

    Description:
        Pops up a dialog window at the center of the screen and blocks
        everything until dealt with.
        Returns 1 or 0.

.. seealso::
    :class:`SymChooser`, :meth:`VBox.dialog`

----

.. function:: continue_dialog

    Syntax:
        ``continue_dialog("label")``

    Description:
        Provides info to the user.
        Like :func:`boolean_dialog`, blocks everything until dealt with.


----

.. function:: string_dialog

    Syntax:
        ``string_dialog("label", strdef)``

    Description:
        Returns 0 if canceled and *strdef* remains unchanged.
        Like :func:`boolean_dialog`, blocks everything until dealt with.

