Category : Miscellaneous Language Source Code
Archive   : MAX.ZIP
Filename : DETAIL1.DOC

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 (bp_int...)

Dbgbc clears the breakpoints specified by the list of
arguments bp_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.

dbgbs (bp_int...)

Dbgbs sets a breakpoint at each program step specified by
the list bp_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 is not 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.

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
%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])

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.

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 may
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.

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.

lstcpsh (ld_int value_exp)

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