The following built-in functions are functions that deal with arguments/variables.

ARG Returns an argument passed to a script/subroutine.
CREATEOBJECT Creates a REXX object.
DATATYPE Checks a string's (or variable's) type.
EXISTS Checks if a variable has explicitly been assigned a value, or checks if a label is found.
STEMDELETE Deletes ordered items from a stem variable.
STEMINSERT Inserts the contents of one variable into another, ordered stem variable.
SYMBOL Determines whether a particular string is also the name of an existing variable.
VALUE Returns the value of a variable whose name is constructed dynamically.


ARG

Returns a count of how many arguments were passed to a script/subroutine. Can also be used to fetch the value of any one of those arguments, or test if a particular argument exists.

Synopsis

value = ARG(arg_number, option)

Args

arg_number is the argument number whose value is to be returned, where the first argument is 1. If arg_number is omitted, then a count of the number of passed args is returned.

option is valid only if arg_number is not omitted, and it can be one of the following:

Option Meaning
E (Exists) Returns '1' if the arg_number argument was passed, or '0' if it was omitted.
N (Normal) Returns the arg_number argument if it was passed, or an empty string if it was omitted.
O (Omitted) Returns '1' if the arg_number argument was omitted, or '0' if it was passed.

If option is omitted, it defaults to 'N'.

Returns

Depending upon what you pass to ARG(), it will return either:

  1. A count of the number of args passed to the current script/subroutine.

  2. If option is 'N' or omitted, then ARG() returns the value of one of those args (or an empty string if no such arg exists)

  3. If option is 'E' or 'O', then ARG() returns a '1 or '0' depending upon whether the argument in question was omitted.

Notes

This returns arguments for the current level. For example, if called from the main body of a REXX script, this returns the args passed to that REXX script. If called from some subroutine/Function within the REXX script, then it returns the args passed to that subroutine/Function.

Examples

Example use Return value
ARG()
/* Returns how many args have been passed */
ARG(1)
/* Returns the value of the first passed arg */
ARG(1, 'E')
/* Returns 1 if the first arg was not omitted, or 0 otherwise */

See also

PARSE ARG, USE ARG


CREATEOBJECT

Creates a REXX object.

Synopsis

value = CREATEOBJECT(Filename, VariableName, DllIndex, Args...)

Args

Filename is the name of the REXX script that you wish to load as an object. If the script is contained inside of a macro DLL, then Filename is the name of the DLL file, minus any .DLL extension.

VariableName is the name of the REXX variable that you wish to use to reference this object (ie, call its functions). You can specify either a simple variable name (ie. MyObject) or a stem name (MyObject.). If you use a stem name then you can both call the object's functions, as well as directly access the object's variables. Otherwise, you can only call the object's functions.

If VariableName is omitted, then by default the Filename arg is also used as the REXX variable name for the object, minus any extension. In this case, you should ensure that you name your object script without spaces or other characters that are illegal in a REXX variable name.

If the script is contained within a macro DLL, then DllIndex is which script to load within that DLL, where 1 is the first script, 2 is the second, 3 is the third, etc. Omit this argument if Filename is not a macro DLL.

All extra args that you pass to CreateObject are passed on to the object's Create() function. (ie, The fourth argument you pass will become the first argument passed to the object's Create() function).

Returns

Returns whatever the Create() function of the object returned. Note that the object may choose to return no value at all. You should be aware of what a particular object you use may return.

Notes

For more information, see REXX Objects.


DATATYPE

Checks a string's (or variable's) type. For example, this may be useful to check whether a variable has a numeric value before attempting to use it in a mathematical expression.

Synopsis

result = DATATYPE(value, type)

Args

value is the string whose type is to check. For example, this may be the value of some variable. If type is omitted, then DATATYPE() will return 'NUM' if value is numeric, or 'CHAR' otherwise.

type is which type that value should be checked for. It is one of the following:

Option Meaning
N (Number) Returns '1' if value is a numeric string (in base 10). This means that it contains only a leading '+' or '-' character, followed by the characters '0' to '9' inclusive, and perhaps one decimal point or one 'E' for an exponent.
A (Alphanumeric) Returns '1' if value contains only characters from 'a' to 'z', 'A' to 'Z', or '0' to '9', inclusive.
W (Whole) Returns '1' if value is a numeric string that is a whole number. This means that it has no fractional part (that is non-zero). For example, 25 is a valid whole number, but 25.5 is not. 25.0 would also be a valid whole number since its fractional part is 0. The NUMERIC settings are taken into consideration when checking if value is a whole number
B (Bits) Returns '1' if value is a valid binary string. This means that it contains only characters '0' or '1', inclusive. Spaces can be allowed inbetween nibbles or bytes (but not any leading or trailing spaces).
X (Hexadecimal) Returns '1' if value is a valid hexadecimal string. This means that it contains only characters from 'a' to 'z', 'A' to 'Z', or '0' to '9', inclusive. Spaces can be allowed inbetween bytes (but not any leading or trailing spaces).
S (Symbol) Returns '1' if value is a valid symbol (ie, tail) name. This is not necessarily a valid variable name. You should use SYMBOL() to test for a valid variable name.
L (Lower case) Returns '1' if value contains only characters from 'a' to 'z' (ie, lower case letters only).
U (Upper case) Returns '1' if value contains only characters from 'A' to 'Z' (ie, upper case letters only).
M (Mixed case) Returns '1' if value contains only characters from 'a' to 'z' or 'A' to 'Z', inclusive (ie, alphabetic characters only).
O (Mixed case) Returns '1' if value is the name of some object.

Returns

Either 'NUM' or 'CHAR' if type is omitted, or a 0 or 1 if type is specified.

Notes

For 'X' or 'B' type, if value is an empty string, then DATATYPE() will return a 1. For all other types, an empty string will return 0.

The result from 'A', 'L', 'M' and 'U' type may depend on the setting of language, if you are using an interpreter that supports national character sets.

Examples

Example use Return value
DATATYPE('100.5')
 'NUM'
DATATYPE(' - 1.35E-5 ')
 'NUM'
< PRE>DATATYPE('123.456')
'NUM'
< PRE>DATATYPE('123.456.789')
'CHAR' /* Because of two decimal points */
DATATYPE('')
 'CHAR'
DATATYPE('FooBar', 'A')
 1
DATATYPE('Foo Bar', 'A')
 0 /* Because of the space in 'Foo Bar' */
DATATYPE('0110 1101','B')
 1

See also

SYMBOL, VALUE, EXISTS


EXISTS

Checks if a variable has been explicitly assigned a value, or checks if a label is found in a script.

Synopsis

result = EXISTS(name, options)

Args

name is the name of a variable or label to check.

options is any of the following:

Option Meaning
L (Label) name is a label (instead of a variable) to search for.
P (Parent) Check parent levels also if the label/variable isn't found in the current level.

If omitted, options defaults to none of the above.

Returns

For a variable test, a 1 is returned if the variable has been explicitly assigned a value, or 0 if not. For a label, a 1 is returned if the label is found, or 0 if not.

Notes

If name is a compound variable name (ie, with tail names separated by dots), then tail name substitution may be performed upon the tails.

Make sure that you enclose name in quotes if you wish to check that particular name. Otherwise, EXISTS() will assume that you are specifying a variable whose value should be checked to see if it is an existing variable or label.

If a compound variable is not explicitly given a value, then EXISTS returns a 0, even if the stem has been given a value. For example:

DROP MyStem.MyTail
MyStem. = 'something'
test = EXISTS('MyStem.MyTail')
/* test = 0 */

Examples

Example use Return value
EXISTS('MyLabel', 'L')
1 if MyLabel is an existing label, or 0 if not.

See also

SYMBOL, DATATYPE


STEMDELETE

Deletes items from an ordered stem variable.

Synopsis

error = STEMDELETE(To, Options, Position, Count)

Args

To is the name of the stem variable from which the contents will be deleted. This should be in quotes.

Options can be any or all of the following:

Option Meaning
E (Empty) Remove empty items. Count is ignored.

If omitted, Options defaults to none of the above.

Position is the item number in To at which to start deleting. For example, a 3 would start deleting at To.3 onward (ie, To.1 and To.2 will be undisturbed). If omitted, then a position of 1 is assumed.

Count is the number of items in To to delete (starting from Position). If there are less items than Count + Position, then only that many existing items are deleted. If omitted, Count defaults to 1.

Returns

1 if successful, or 0 if an error.

See also

LOADTEXT, STEMINSERT


STEMINSERT

Inserts the contents of one variable into another, ordered stem variable.

Synopsis

error = STEMINSERT(To, From, Options, ToPosition, FromPosition, Count)

Args

To is the name of the stem variable where the contents will be inserted. This should be in quotes.

From is the name of the stem variable containing the contents to be inserted. It can be a stem variable or otherwise. This should be in quotes.

Options can be any or all of the following:

Option Meaning
U (Upper) Upper case the inserted items.
D (Delete) Delete the items from From after inserting.
L (Leading) Trim leading spaces from inserted items.
T (Trailing) Trim trailing spaces from inserted items.
O (Overlay) Overlay the inserted items over existing items in To.

If omitted, Options defaults to none of the above.

ToPosition is the item number in To at which to start inserting. For example, a 3 would start inserting at To.3 onward (ie, To.1 and To.2 will be undisturbed, or if they have no values, will be set to empty items). If omitted, then a position of 1 is assumed.

If From is a stem variable, then this is the item number in From to start inserting from. For example, a 4 would start inserting from From.4 onward (ie, would skip From.1, From.2, and From.3). If From is not a stem variable, then FromPosition is the character offset within From to starting inserting from (where 1 is the first character). If omitted, then a position of 1 is assumed.

Count is the number of items in From to insert (starting from From.FromPosition). If there are less items in From than Count + FromPosition, then only that many existing items (or characters if From is not a stem variable) are inserted (and From.0 must contain a count of the total items in From, if a stem variable). If omitted, Count defaults to however many items/characters are in From.

Returns

1 if successful, or 0 if an error.

See also

LOADTEXT, STEMDELETE


SYMBOL

Determines whether a particular string is also the name of an existing variable (ie, one that has been explicitly assigned a value -- not one that is DROP'ed or never was assigned a value). Also can be used to check for a legal variable name.

Synopsis

result = SYMBOL(name)

Args

name is the string to check if it is a valid variable name with an assigned value.

Returns

Returns 'VAR' if name is the name of an existing variable that has been assigned a value. Returns 'BAD' if name is not a legal variable name, nor a numeric string. Returns 'LIT' if name is either a numeric string, or a legal variable name that has not yet been assigned any value.

Notes

If name is a compound variable name (ie, with tail names separated by dots), then tail name substitution may be performed upon the tails.

Make sure that you enclose name in quotes if you wish to check that particular name. Otherwise, SYMBOL() will assume that you are specifying a variable whose value should be checked to see if it is an existing variable's name.

If name is a compound variable, and has been assigned a value via its stem, then SYMBOL will produce "VAR", as so:

DROP MyStem.MyTail
/* Assign a default value to all variables using MyStem. */
MyStem. = 100
SAY SYMBOL('MyStem.MyTail') /* Displays "VAR" */
If you really need to know whether a compound has been explicitly assigned a valure then use EXISTS.

Examples

Assume that 'MyVar' has been assigned the value '100'.

Example use Return value
SYMBOL('MyVar')
 'VAR'
SYMBOL(MyVar)
 'LIT' /* MyVar's value is '100', which is not a legal variable name */

See also

DATATYPE, EXISTS


VALUE

Returns the value of a variable. Can also optionally set that variable to a new value. Furthermore, VALUE() allows setting/querying the value of an environment variable.

Synopsis

value = VALUE(name, new_value, environment)

Args

name is the variable's name.

new_value is the new value for the variable. If omitted, then the variable's value is not changed.

If environment is specified, then it is assumed that name is the name of some external variable (ie, a variable not maintained by REXX, and not contained in the REXX script itself). environment would be the name of the entity that maintains that variable. Possibilities for environment are 'SYSTEM', 'OS2ENVIRONMENT', or 'ENVIRONMENT' to set or query environment variables (ie, operating system variables). If environment is omitted, then the variable is assumed to be one of REXX's internal variables (ie, a variable in the REXX script).

Returns

The current value of the variable. If new_value is supplied, then the returned value is the previous value of the variable (ie, before its value is changed).

Notes

If you know the name of a REXX variable, then you can assign it a value just by using an equal sign. So too, you can use a variable's value just by specifying its name (unquoted) anywhere that you want to use its value. So, VALUE() is not needed for REXX variables whose name is known at the time that a script is being written.

The VALUE() built-in is used primary to set/fetch values of either environment variables, or REXX variables whose names aren't known ahead of time. For example, perhaps your script will ask the user to type the name of some variable. Your script will not know ahead of time what he will type. Let's assume that you store the variable name he types in another variable called 'TheName'. Here's how you would set his variable (whose name he provided) to the value 'something':

/* Get a variable name from the user */
SAY "Enter a variable name:"
PARSE PULL TheName
/* Set that variable's value to 'something' */
old = VALUE(TheName, 'something')

Assume that the user types 'MyVar' at the prompt. VALUE() does not set the variable 'TheName' to the value 'something'. Instead, it sets 'MyVar' to 'something'. It may be helpful to think of 'TheName' as being analogous to a "handle" in another language such as C. REXX doesn't have handles. So, the VALUE() function allows you to treat a variable as if it were a handle (ie, points to another variable) -- by assigning the name of the other variable to the "handle" and then using that "handle" with VALUE(). Above, 'TheName' is used like a handle to 'MyVar'.

Reginald supports a special environment name of "PARENT" to access a variable in a parent level (from a subroutine that uses a PROCEDURE statement to protect its variables). In this way, if your subroutine needs to query the value of some variable set in any higher level, then the VALUE() function will allow you to do this. For example, let's say we have a subroutine that will query the value of a variable named "SomeVar" that is set in some higher level. Here's how you may do that:

/* Initialize SomeVar */
SomeVar = "Hello"

/* Call a subroutine */
CALL MySub1
RETURN

/* Here's the subroutine. It uses the PROCEDURE statement,
 * so it doesn't have access to the caller's variables
 * unless we EXPOSE them.
 */
MySub1: PROCEDURE

/* Get the value of "SomeVar" set in a higher level */
something = VALUE("SomeVar", , "PARENT")
IF something \= "Hello" THEN SAY  "ERROR"

/* Now call another level */
CALL MySub2

RETURN

MySub2: PROCEDURE

/* Get the value of "SomeVar" set in a higher level. Note:
 * If SomeVar existed in Sub1, then we would get its value
 * there. But it doesn't exist in MySub (because we never
 * used it in that PROCEDURE), so VALUE() goes the next level
 * higher and finds the variable in the main level.
 */
another = VALUE("SomeVar", , "PARENT")
IF another \= "Hello" THEN SAY "ERROR"

RETURN
On Windows, Reginald supports creating/querying/setting/deleting the values of registry keys and values via VALUE(). See Windows Registry for further details.

If an external variable hasn't yet been assigned a value or doesn't exist, then VALUE() returns an empty string.

If a REXX internal variable hasn't yet been assigned a value, then the value returned will be the variable's name upper-cased. For example, if you query the value of the REXX variable 'Blort', and that variable has not yet been assigned any value, the return string from VALUE() is 'BLORT'.

If name is a compound variable name (ie, with tail names separated by dots), then tail name substitution may be performed upon the tails.

See also

GETENV, SYMBOL, USE ARG