Phoenix CD 2.0/Phoenix_CD.cdr/01e/max130.zip/DETAIL1.DOC

Text File | 1988-10-30 | 27KB | 845 lines

14.0    Builtin Function Description

The following section provides a brief synopsis of each builtin
function. Representative arguments are supplied to indicate the
calling sequence for each function and to provide a handle for discussion
of the argument in the description. The following suffixes are used
to describe the data type for the argument. This is the type of data
the variable should contain when the given builtin function is called.

    Suffix    Description

    _exp    Any expression that results in a character string,
        integer or floating point value.

    _num    Any expression that results in an integer or floating
        point value.

    _int    Any expression that results in an integer value.


    _flt    Any expression that results in a floating point    value.


    _str    Any expression that results in a character string value.


    _hex    Any expression that results in a hexadecimal value.


    _fn    Any builtin or user defined function reference.


    _bif    Any builtin function reference.


    _udf    Any user defined function reference.


    _var    Any variable name reference.


Each synopsis features the builtin function name followed by a
representative argument list. Ellipses are used to indicate that an
argument may be repeated an arbitrary number of times. Square brackets
are used to indicate the argument is optional. These should not be
confused with the use of square brackets elsewhere in Max. If the builtin
function has any synonyms they are listed below the name. All alphabetic
builtin functions are in lower case. A brief description of the function
follows the function name and argument list.

A logical TRUE is represented by any non-zero value. A logical FALSE
is represented by zero. A null string, or one that is not a number is
equal to zero when converted to a number.

acos (x_num)

    Acos returns the arc cosine of its argument. The argument must
    be between -1 and 1.

add (value_num...)
+

    Add returns the sum of its arguments. If only one argument
    is specified add returns the sum of the argument plus one.

and (mask_int...)
&&
    And returns the logical AND of its arguments. If all of its
    arguments are nonzero then one is returned, otherwise zero is
    returned.

any (input_exp valid_exp...)

    Any compares the value of input_exp with each of the values
    of valid_exp. If input_exp equals one of valid_exp the argument
    number of the matching valid_exp is returned. Otherwise zero is
    returned.

argc ()

    Argc returns the number of arguments passed to the containing
    user defined function.

argn (argnum_int)

    Argn returns the name of the symbol passed in the indicated
    argument position. The first argument is 1. The name of the
    argument is not necessarily the same as the value of the argument
    for arguments that are functions or variables, i.e. it does not
    evaluate the argument.

    Note: this function may not be passed to another user defined
    function. Set a variable to the result and pass it instead.

argt (argnum_int)

    Argt returns the type of symbol passed in the indicated
    argument position. Possible values are:

        1 - Variable
        2 - Function
        4 - Literal

    Note: this function may not be passed to another user defined
    function. Set a variable to the result and pass it instead.

argv (argnum_int)

    Argv evaluates the argument passed in the indicated position
    and returns the result. If the argument is a function or variable
    it is not evaluated until this function is used. Every time this
    function is executed the argument is evaluated. This can be used
    to implement new flow of control constructs.

    Note: this function may not be passed to another user defined
    function. Set a variable to the result and pass it instead.

arycre (size_int, [init_exp...])

    Arycre creates an array and returns an array descriptor. The
    array has the number of elements specified by size_int. An optional
    list of initializers may be specified to initialize elements of the
    array. If there are fewer initializers than elements the extra
    elements are uninitialized. If there are more initializers than
    elements the extra initializers are ignored. Each array is identified
    by its array descriptor and all array builtin functions require
    that the array descriptor be specified as the first argument.

aryfre (ad_int)

    Aryfre frees an array specified by the array descriptor argument.
    The array must have been created by an arycre or lstamap function
    call. Once the array is freed the storage it occupied may be
    reused and the array may not be referenced.

aryget (ad_int index_int)

    Aryget returns the element of the array specified by the array
    descriptor argument and index argument. The lowest valued index
    in an array is zero and the highest permissible value is one less
    than the array size specified in the arycre call. This function
    returns a null string if the element is uninitialized.

arykget (ad_int key_str)

    Arykget returns the element of the array specified by the array
    descriptor argument and the key argument. The key may be any
    character string key that was used to store an element in the
    array using arykput.

arykput (ad_int key_str data_str)

    Arykget stores data_str in an array specified by the array
    descriptor at a location defined by key_str. The key_str may be
    any arbitrary string and may be used to retrieve the data using
    arykget. This function returns the numeric index of the element
    specified by key_str.

    Note: it is possible to get the elements of the array sequentially
    by using a numeric index and aryget.

arylcur (ad_int index_int)

    Arylcur may only be used on a mapped array (see arylmap). It sets
    the current location in the corresponding list to the array element
    identified by the array descriptor and index.

arylmap (ad_int)

    Arylmap creates a list with a node for each element in the array
    and returns the list descriptor. The array and list refer to the
    same storage so modifying an element of the array results in a
    modification to the corresponding node in the list.

aryput (ad_int index_int data_str)

    Aryput stores the data data_str in the array specified by the
    argument descriptor ad_int at the location specified by index_int.

arysize (ad_int)

    Arysize returns the number of elements in the array specified
    by the array descriptor.

asin (x_num)

    Asin returns the arc sine of its argument. The value of the
    argument must be in the range of -1 to 1. The value of the result
    is in the range -pi/2 to pi/2.

atan (x_num)

    Atan returns the arc tangent of its argument. The value of the
    result is in the range -pi to pi.

auto (auto_var [size_int])

    Auto allocates size_int bytes (characters) of automatic storage
    for the variable specified by auto_var. If the size argument is
    omitted then the current system default number of bytes will
    allocated. The current system default may be read and set using
    the sys builtin function and the ds_unit variable.

bifbind (arg_bif)

    Bifbind binds the builtin function specified by arg_bif to its
    internal address. This function may be used to ensure that bif
    is bound to a builtin function and not a user defined function.
    It may also be used to check if bif is a valid builtin function
    name. Builtin functions are normally bound to their internal
    address the first time they are referenced.

    See also: bind, udfbind, unbind

bifdir ([bif...])

    Bifdir displays the internal address, name and syntax of each
    builtin function name specified in the argument list. If no names
    are specified it prints that information for all builtin functions.

bind (fn...)

    Bind binds the user defined or builtin functions specified by
    fn... to their internal addresse. The normal search order of
    internal user defined function, external user defined function,
    builtin function is used.

bitand (mask_int mask_int...)
&

    Bitand returns the bitwise AND of its arguments. A bitwise AND
    is a logical AND of each bit in each mask, aligned on the right
    and zero filling as necessary to accomodate differences in the
    length of each bit string. The maximum length of mask_int is
    32 bits.

    Truth Table:

        X    Y    AND
        ----------------------
        0    0    0
        0    1    0
        1    0    0
        1    1    1

bitls (mask_int shiftamt_int)
<<

    Bitls returns the value of mask_int left shifted by shiftamt_int.
    Spaces vacated on the right are filled with zeros. Bits shifted off
    the left are lost. The maximum length of mask_int is 32 bits.

bitnot (mask_int)
~

    Bitnot returns the bitwise NOT (one's complement) of its argument.
    The maximum length of mask_int is 32 bits.

    Truth Table:

        X    NOT
        --------------
        0    1
        1    0

bitor (mask_int mask_int...)
|

    Bitor returns the bitwise OR of its arguments. A bitwise OR
    is a logical OR of each bit in each mask, aligned on the right
    and zero filling as necessary to accomodate differences in the
    length of each bit string. The maximum length of mask_int is
    32 bits.

    Truth Table:

        X    Y    OR
        ----------------------
        0    0    0
        0    1    1
        1    0    1
        1    1    1

bitrs (mask_int shiftamt_int)
>>

    Bitrs returns the value of mask_int right shifted by shiftamt_int.
    Spaces vacated on the left are filled with zeros. Bits shifted off
    the right are lost. The maximum length of mask_int is 32 bits.

bitxor (mask_int mask_int...)
^

    Bitxor returns the bitwise XOR (exclusive or) of its arguments. A
    bitwise XOR is a logical XOR of each bit in each mask, aligned on
    the right and zero filling as necessary to accomodate differences
    in the length of each bit string. The maximum length of mask_int
    is 32 bits.

    Truth Table:

        X    Y    XOR
        ----------------------
        0    0    0
        0    1    1
        1    0    1
        1    1    0

break (handler_fn)

    Break establishes a function to be executed whenever Control-C
    is entered from the integrated or interactive environment. The
    function may execute a non-local goto to a label in a user defined
    function that is still active (has not returned). Any other return
    causes execution to resume at the point where it was interrupted.

case (case_exp
    when (option_exp
    option_fn
    ...
    )
    ...
    [default (
    default_fn
    ...
    )]
)

      Case is a flow of control construct. It compares case_exp to each
    option_exp. The first option_exp which is equal to the case_exp
    causes execution of that block of functions. When the block is done
    control resumes at the function following the case argument list
    terminator. If no option_exp equals case_exp and a default block
    is specified then it is evaluated.

    See also: do, exit, for, goto, if, label, leave, loop,
          return, select, quit, until, while

chdir (dir_str)

    Chdir changes the current directory to that specified by the
    directory path argument dir_str.

close (fd_int)

    Close closes the file descriptor specified by fd_int. Once a
    file is closed it may not be accessed again.

copy (oldfile_str newfile_str)

    Copy copies the file specified by the pathname oldfile_str to
    the pathname specified by newfile_str.

cos (value_num)

    Cos returns the cosine of its argument, value_num. The argument
    should be expressed in radians. The result is in the range -1
    to 1.

date ()

    Date returns the current system date in MM:DD:YY format:

    Where:    MM - month (01-12)
        DD - day (01-31)
        YY - year

    See also: day, seconds, time

day ([seconds])

    Day returns the complete day and date in the following format:

        DDD MMM NN HH:MM:SS YYYY

    Where:  DD    Day of the week.
        MMM    Month of the year.
        NN    Day of the month.
        HH    Hours (0-23).
        MM    Minutes (0-59).
        SS    Seconds (0-59).
        YYYY    Year (1980-2030).

    If the optional argument is specified then seconds_int is
    converted to the indicated format.

    See also: date, seconds, time

dbgbc (stepnum_int...)

    Dbgbc clears the breakpoints specified by the list of
    arguments stepnum_int... The breakpoints values are the program
    step numbers previously used in a set breakpoint (dbgbs)
    command or as returned by list breakpoint (dbgbl).

dbgbl ()

    Dbgbl lists all breakpoints that are currently set. This
    list includes a count of the number of times that breakpoint
    has been executed as well as the step number and the function
    name associated with the step.

dbgbs (stepnum_int...)

    Dbgbs sets a breakpoint at each program step specified by
    the list stepnum_int... Breakpoints may only be set at steps that
    reference a function name. Literals and variables are not
    allowed. To find out the step number use the list function
    (udflist). Don't forget to turn on debug mode (dbgon) to
    enable all the breakpoints that have been set.

dbgcont ()

    Dbgcont disables single step mode (dbgstep) and enables
    normal execution of user defined functions.

dbgoff ()

    Dbgoff disables the Max debugger. Debugging information such
    as breakpoints is not discarded and can be re-established using
    dbgon.

dbgon ()

    Dbgon enables the Max debugger. No trace, single step or
    breakpoint processing is performed until debug mode is turned
    on.

dbgsd ()

    Dbgsd displays the evaluator stack. This shows how Max got to
    the current step by displaying the name of each function that has
    called another function that has not yet returned.

dbgstep ()

    Dbgstep enables single step mode. This causes Max to print each
    step name and pause prior to executing it. A command may be
    entered. Pressing carriage returns continues to the next step.
    Don't forget to turn on debug mode (dbgon) to enable single
    step processing.

dbgtroff ()

    Dbgtroff disables step tracing.

dbgtron ()

    Dbgtron enables step tracing. This results in Max displaying
    the step name prior to executing each step. Don't forget to turn
    on debug mode (dbgon) to enable step tracing.

dbgvd (disp_var level_int)

    Dbgvd displays the contents of the variable specified by disp_var,
    optionally at the level of the stack given by level_int. If a stack
    level is not specified then the current stack frame is used.

define (new_udf)

    Define defines a new user defined function. The body of the user
    defined function is specified as arguments to the new function's
    name. To define a simple function to print the time:

        define (
            simple_function (
                print (time ())
            )
        )

    where simple_function is the name of the new user defined
    function.

defint (new_udf)

    Defint defines an internal user defined function. It must be
    used inside a user defined function. The new internal user
    defined function cannot be recursive. It may reference any of
    the variables already defined in the containing function. Any
    variables that the internal udf defines are not visible to the
    containing function. The storage required for the internal
    user defined function is freed when the containing function
    returns.

delete (path_str)

    Delete deletes the file specified by the pathname path_str.

dirlst (wildcard_str [attr_int])

    Dirlst reads the directory specified by wildcard_str (which
    must contain the ? and * wildcards) into a new list and returns
    the list descriptor. The optional attribute argument may be
    used to select system files (4), hidden files (2) or the volume
    file.

div (val_exp val_exp...)
/

    Div divides its arguments from left to right and returns the
    result.

do (
    [fn
    ...]
)

    Do is a flow of control construct. It may be used to group
    a block of functions. The functions are executed sequentially.
    A break function causes the rest of the functions in the block
    to be skipped and control resumes following the argument list
    terminator associated with do.

    See also: case, do, exit, for, goto, if, label, leave, loop,
          return, select, quit, until, while

eof (fd_int)

    Eof returns true if the file represented by the specified file
    descriptor is at end-of-file, otherwise it returns false.

errcode ([error_int])

    Errcode returns the current error code, optionally re-setting it
    to the value specified by error_int. Setting the error code to zero
    allows processing to continue for severity level 0 (warnings)
    or 1 (errors). Errcode should only be used in an error handler.

errfn ([handler_fn])

    Errfn specifies an error handling function. This function is
    not evaluated until an error occurs. Control is then transferred
    to it instead of performing the default processing of displaying
    an error message. If handler_fn is not specified the default
    error handling is restored.

errinfo (code_int, desc_str, step_int)

    Errinfo *returns* via its argument list the current error
    code, a descriptive error message string and the step in the
    user defined function that caused the error. It should only
    be called from an error handler.

errlevel (newlevel_int)

    Errlevel specifies a new error level. Errors with a severity
    greater than the specified level cause the default message to
    be displayed. This function has no affect on a user defined
    error handler. Valid newlevel_int's are 0 to enable warning
    messages (the default) and 1 to disable warning messages.

errmsg ()

    Errmsg returns an error message string indicating the cause
    of the current error. It should only be called from an error
    handler.

errsig (code_int msg_str step_int)

    Errsig signals an error. It may be used for testing an error
    handler or for signalling errors in user defined functions.

eval (function_str...)

    Eval evaluates each of its arguments by passing it to the Max
    translator and then to the Max interpreter. The result is just
    as if the function_str had been typed as a command or entered
    from a file.

    See also: feval

exit ()

    Exit is a flow of control construct. It causes the currently
    executing user defined function to terminate and return control
    to the Max command level.

    See also: case, do, for, goto, if, label, leave, loop,
          return, select, quit, until, while

exp (x_num)

    Exp returns the exponential value of its argument, or e raised
    to the power of x_num.

export (exp_var [to_udf])

    Export exports the storage associated with the variable specified
    by exp_var to the user defined function specified by to_udf. If
    to_udf is not specifed then the variable is exported to any user
    defined function that wants it.

    See also: import

feval (path_str)

    Feval evaluates the file specified by path_str. Each line in the
    file is passed to the Max translator and then to the Max interpreter.
    The result is just as if the contents of the file had been typed
    at command level. This is the standard method of loading a library
    of Max user defined functions.

    See also: eval

fmhex (val_hex)

    Fmhex converts a hex value to decimal. The maximum precision of
    the conversion is 32 bits. The hex value may be preceded by 0x.

    See also: format

for (init_exp exit_exp iterate_exp [block_fn...])

    For is a flow of control construct. The first three arguments
    are analogous to the control expressions used in the for loop
    in C or BASIC. The first is an initialization expression that
    is evaluated first. Next is an exit expression. It is evaluated
    for every iteration of the loop. If it returns true then the list
    of functions specified by block_fn... is executed in order. If
    it returns false then control resumes following the argument
    list terminator. The third and final control argument is evaluated
    for every iteration of the loop and usually changes the values
    of variables used in exit_exp.

    See also: case, do, exit, goto, if, label, leave, loop,
          return, select, quit, until, while

format (template_str [substitution_exp...])

    Format produces a formatted string by substituting arguments
    into locations in the templatate. The substitution uses C style
    escape sequences:

        %s - string
        %d - integer
        %x - hex integer
        %f - floating point
        etc.

free (static_var)

    Free frees the storage allocated to the static variable specified
    by static_var and undefines the variable. The storage is reused
    after it is freed and can no longer be referenced through the
    variable.

    See also: static

ge (value_num...)
>=

    Ge performs a greater than or equal to comparison of its
    arguments from left to right and returns true if each argument
    passes the comparison, otherwise false. If only one argument is
    specified it compares it to zero and returns the result.

genfre (sd_int)

    Genfre frees the structure specified by the structure descriptor
    sd_int, regardless of the type of structure (array, list, pattern,
    etc).

get ([input_var])
input

    Get reads a line of input from the command source and returns
    it. If an input variable is specified it also returns it via the
    argument list.

    See also: put

get_arg (step_int)

    Get_arg returns the argument step associated with a function
    step.

get_step (udfname_str)

    Get_node returns the the first program step in the user defined
    function specified by udfname_str.

get_nxt (step_int)

    Get_nxt returns the step that follows step_int in a user defined
    function.

get_sym (step_int)

    Get_sym returns the name of the step specified by step_int.

getcwd ()

    Getcwd returns the pathname of the current working directory.

getenv (name_str)

    Getenv returns the value of the environement variable specified
    by name_str.

goto (label_var)

    Goto is a flow of control construct. It transfers control to
    the label specified by label_var. Label_var must have previously
    been set by a call to label. This function may be used to perform
    a non-local goto to a function that is still active on the stack (i.e. has
    not returned) provided the label has been imported to the current
    function. This function will produce bizarre results if the
    function that defined label_var has returned.

    See also: case, do, exit, for, if, label, leave, loop,
          return, select, quit, until, while

gt (value_num...)
>

    Gt performs a greater than comparison of its arguments from left
    to right and returns true if each argument passes the comparison,
    otherwise false. If only one argument is specified it compares it
    to zero and returns the result.

if (cond_exp
    then (then_fn...)
    else (else_fn...)
)

    If is a flow of control construct. The first argument, cond_exp,
    is evaluated. If it returns true the list of functions specified
    by then_fn... is executed. If it returns false the list of functions
    specified by else_fn... is executed. Either block may be prematurely
    terminated by a leave function.

    See also: case, do, exit, for, goto, label, leave, loop,
          return, select, quit, until, while

import (imp_var [from_udf])

    Import imports the storage associated with the variable specified
    by imp_var from the user defined function specified by form_udf. If
    from_udf is not specifed then the variable is imported from the
    first function that exported it to this function or for general
    use. Once a variable has been exported from one function and
    imported from another it is considered shared. Note that a
    function may export a static variable for later import.

    See also: export

inkey ()

    Inkey reads a key from the keyboard without echoing it. It should
    not be used with the Max integrated environment.

inp (port_int)

    Inp returns a value read from the port specified by port_int.

label (label_var)

    Label establishes the current location as a target for a goto.
    The containing function must be active on the stack (i.e. have not
    returned) when the goto is executed. A label may be exported to
    another function to allow a non-local goto. This is useful for
    error or control-c handlers.

    See also: case, do, exit, for, goto, if, leave, loop,
          return, select, quit, until, while

le (value_num...)
<=

    Le performs a less than or equal to comparison of its
    arguments from left to right and returns true if each argument
    passes the comparison, otherwise false. If only one argument is
    specified it compares it to zero and returns the result.

leave ()

    Leave is a flow of control construct. It is used to leave a
    block of functions by transferring control to the function following
    the argument list terminator of the block. It may be used inside
    do, for, loop, default, then, else and when blocks.

    See also: case, do, exit, for, goto, if, label, loop,
          return, select, quit, until, while

ln (value_num)

    Ln returns the natural logarithm of its argument.

log (value_num)

    Log returns the base 10 logarithm of its argument.

loop (
    block_fn
    ...
)

    Loop is a flow of control construct. It repeatedly executes
    the list of functions in block_fn... until terminated by a leave,
    exit, return, etc.

    See also: case, do, exit, for, goto, if, label, leave,
          return, select, quit, until, while

lstacur (ld_int)

    Lstacur may only be used on a mapped list (see lstamap). It
    returns the array index    associated with the current list node.

lstamap (ld_int)

    Lstamap maps the list specified by the list descriptor ld_int to
    an array and returns the new array descriptor. The data in the list
    is then accessable from either the list or the array. The array and
    list refer to the same storage so modifying an element of the array
    results in a modification to the corresponding node in the list.

    See also: lstacur, aryget, argput, arysize

lstcget (ld_int)

    Lstcget returns the value at the current location in the list. The
    current location must have previously been set.

    See also: lsthead, lsttail, lstprev, lstnext, lstsub

lstcpop (ld_int)

    Lstcpop removes the current node from the list and returns the
    value of the node. Once a node is removed from a list it is no
    longer accessable. The current location pointer is moved to the
    next node in the list if there is one, otherwise it becomes
    undefined.

    See also: lsthead, lsttail, lstprev, lstnext, lstsub

lstcpsh (ld_int value_exp)

    Lstcpsh creates and inserts a new list node following the current
    location and initializes its value to value_exp. The new node
    becomes the new current location.

    See also: lsthead, lsttail, lstprev, lstnext, lstsub