ARG([position][,option])
This function deals with the argument(s) passed into a REXX program,
function or subroutine. With no parameters, the result is the number of
arguments given; that is, the position of the last explicitly specified
argument. If the parameter "position" is given, then the result is the
"position"th argument string, or an empty string if the argument was
not supplied. If the option is supplied, its first character must be
"E" or "O", standing for "Exists" or "Omitted" respectively. The result
of the function is then 0 or 1, depending on whether the "position"th
argument string exists or was omitted, with 1 meaning that "option" is
true.
Example: if a rexx function was called by:
foo(5,,7)
then arg() = 3
arg(1) = 5
arg(2,'e') = 0
C2X, C2D, B2X, B2D, D2C, D2B, D2X, X2C, X2D
Each of these is a function taking an argument and possibly a count and
returning a conversion of that argument. Each function converts an
argument of a type indicated by the first character of the function name
(Character, heX, Binary or Decimal) into the type indicated by the last
character of the name.
Examples: c2x("abc") = "616263" d2x(286)="11E"
d2c(65)="A" d2b(65)="01000001"
BUG: Each of the conversion functions which deal with decimal numbers is
restricted to inputs which have a value of less than 2**31 when
converted to an unsigned integer.
Details of these functions are below:
.........................................................................
B2D(binary)
The binary input is converted into a non-negative decimal number. Spaces
are allowed in the binary string between four-digit sequences, and the
first "four-digit" sequence may contain fewer than four digits, in which
case up to three leading '0' digits will be assumed.
B2X(binary)
Each set of four binary digits in the input is converted to a hex digit
and these are concatenated together to form the result. Spaces are
allowed in the binary string between four-digit sequences, and the
first "four-digit" sequence may contain fewer than four digits, in
which case up to three leading '0' digits will be assumed.
D2B(decimal)
The decimal input is converted into binary. The length of the result is
the smallest possible multiple of 8.
C2X(string)
The n-character string is converted into 2n hex digits.
C2D(string[,length])
The string is converted into a decimal number, interpreting the leftmost
character as the most significant byte. If length is omitted, then the
whole string is converted and the result is positive. If the length is
given, then the string is truncated or padded with zero bytes on the
left to give a string of this length, and is then taken to be a twos
complement number. In this case the result may therefore be negative.
D2C(decimal[,length])
The decimal number is converted into a string of characters (with the
leftmost character being the most significant). If the length is given,
then the result is truncated or sign-extended on the left to be of this
length. Otherwise the length of the result is such that the leftmost
character is not '00'x (for positive numbers) or 'FF'x (for negative
numbers) except in the case of zero, which is converted to '00'x.
D2X(decimal[,length])
The decimal number is converted into a hex number. If the length is
given, then the result is truncated or sign-extended on the left to be
of this length. Otherwise the length of the result is such that for
positive numbers there is no leading zero, and for negative numbers
there is no leading 'F' except in the case when the next hex digit is
less than 8. D2X(0) returns a single zero digit.
X2B(hex)
Each digit in the given hex string is converted to four binary digits and
these are concatenated together. Spaces are optional between pairs of
hex digits, and the first "pair" of digits may contain only one digit.
X2C(hex)
The hex string is converted to characters, just as when 'hex'x is typed.
Spaces are optional between pairs of hex digits, and the first byte of
the string may optionally contain only one digit, in which case a
leading '0' is assumed.
X2D(hex[,length])
The hex string, which should contain only hex digits (and no spaces) is
first truncated or extended with zeros on the left to be of the given
length if necessary, and then converted into a decimal number. If the
length is given, then the hex is assumed to be in twos complement
notation. Otherwise the result will always be nonnegative.
.........................................................................
CENTER(s,length[,pad]) or CENTRE(s,length[,pad])
This function returns a string of the given length containing s. If s
contains fewer than the required number of characters, then pad
characters (pad, or by default, blanks) are added on each side to
centre s in the result, otherwise characters are taken away from each
side of s leaving the middle block of characters. If an odd number of
characters needs to be added or taken away, then the right-hand side
loses or gains one more than the left.
CONDITION([option])
This function returns information about the current trapped condition
(see "SIGNAL ON" and "CALL ON" for more information). If there is no
such condition, then an empty string is returned. If the option is
present, it must be one of the following:
'C': Returns the condition which was trapped (one of "SYNTAX",
"ERROR", "HALT", "NOVALUE", "FAILURE" or "NOTREADY").
'D': Returns a description of the event which caused the condition.
For "ERROR" and "FAILURE", this is the command string which
resulted in error or failure. For "NOTREADY" it is the name of
the stream which was not ready. For "NOVALUE" it is the
derived name of the variable which has no value. For "HALT" it
is the Unix name of the signal which caused the interruption.
For "SYNTAX" it is the error message which would have been
displayed on the terminal if the error had not been trapped.
'I': Returns the instruction name "CALL" or "SIGNAL" as appropriate
to describe how the condition was trapped.
'S': Returns the current status of the condition as "ON", "OFF" or
"DELAY".
If the option is omitted then 'I' is assumed.
DATATYPE(string[,option])
This function tests the datatype of the string. If the function is called
with just one argument, then the function returns "NUM" if the argument
is a valid number, and "CHAR" otherwise.
If both arguments are supplied, then the answer is a logical value
(0 or 1) indicating whether or not string is of the type given by the
option. Is s is an empty string then the answer is always 0 unless
testing for a hex constant (the null string is a valid hex constant).
The option must be one of the following:
'A': s is alphanumeric (containing characters only from the ranges
"a-z", "A-Z" and "0-9")
'B': s contains bits (all characters 0 or 1)
'L': s is lower case (containing only "a-z")
'M': s is mixed case (containing only "a-z" and "A-Z")
'N': s is a valid number
'S': s contains characters valid in symbols (variables)
'U': s is upper case (containing only "A-Z")
'W': s is a whole number
'X': s satisfies the rules for a hex constant (i.e. contains only
"0-9", "a-f", "A-F" and blanks in appropriate places).
DATE([option][,date[,option]])
When used with zero or one arguments, the DATE function returns the
current date in a user-defined format. When used with two or three
arguments, it converts the date given in the second parameter from
one format to another.
The format in which the date will be output is given by the first
parameter, whose first letter must match that of one of the options
listed below. If the parameter is omitted then 'N' is assumed.
Base - the theoretical number of days in the common era (i.e. since
1/1/1 AD). On 1/1/1900 the result would be 693595.
Century - the number of days so far since the zero year of the most
recent century (so on 1/1/1900 or 1/1/2000 the result would be
1). This option is deprecated and was not adopted by ANSI; use
the Base option instead.
Days - the number of days so far in this year (so on 12 Jan 1986 the
result would be 12).
European- the date in the format dd/mm/yy.
Julian - the date in the format yyddd (where ddd is as in "Days" above).
This option is deprecated and was not adopted by ANSI.
Month - the full name of the current month, e.g. August.
Normal - the date in the format dd Mmm yyyy, e.g. 27 Aug 1982 (with no
leading zero).
Ordered - the date in the format yy/mm/dd.
Standard- the date in the format yyyymmdd.
USA - the date in the format mm/dd/yy.
Weekday - the full name of the current day, e.g. Tuesday.
If a date is given in the second parameter, the third parameter must
state what format it is in (if the third parameter is omitted then 'N'
is assumed). The possible values for the third parameter are the same
as listed above, with the exception that options 'W' and 'M' are not
allowed. If the input date has a two-digit year then the century is
chosen so as to make the year no more than 49 years before or 50 years
after the current year.
On the first call to DATE or TIME in an expression, a time stamp is
made which is then used for all calls to these functions within that
expression. Hence if multiple calls to these functions are made within
a single expression, they are guaranteed to be consistent with each
other.
BUG: The DATE function only works within the limits defined for Unix
dates (usually approximately 1902-2037), and in any case the
DATE('C') function only works between 1900 and 2099. Using 'C' for
the input format may occasionally result in the wrong century being
chosen if the given date is very close to 50 years from this
year.
BUG: The DATE function is slightly lenient in what it accepts as a valid
date from the second parameter. For instance, "30 Feb 1997" would
be accepted as if it said "2 Mar 1997".
FORMAT(number [,[before] [,[after] [,[expp] [,expt]]]] )
The given number is rounded and formatted according to the information
given, as described below (note that the number is always rounded
according to NUMERIC DIGITS, if necessary, before being processed by
this function):
If just `number' is specified, then it is formatted according to the
usual rules for REXX numerics.
The number is formatted, possibly in exponential form, with `before'
digits before the decimal point and `after' digits after. `before' must
be strictly positive and includes any leading minus sign. `after' must
be non-negative. If `after' is zero, then there will be no decimal
point in the output. If either `before' or `after' is omitted, then
as many places as required are used. If `before' is too small then an
error results. If it is too large, then leading spaces are used to fill
the extra places. The number is rounded or extended with zeros as
necessary in order to have `after' digits after the decimal point
(note that this is not the same as TRUNC, which truncates the number
rather than rounding it). The rounding rules are as usual - the first
digit which is not required is checked and if it is 5 or more, the last
required digit is incremented.
`expt' specifies the trigger for exponential form. Exponential form is
used whenever the number would otherwise require more than `expt'
digits before or more than twice `expt' digits after the decimal point.
If `expt' is zero, exponential form is always used. The number will be
formatted according to NUMERIC FORM, and may need up to three places
before the decimal point if ENGINEERING form is in effect. The default
value for `expt' is the current setting of NUMERIC DIGITS.
`expp' specifies the number of digits (excluding the letter E and the
sign) used for the exponent. If it is zero, exponential form is never
used (this overrides the setting of `expt' if necessary). Otherwise, if
exponential form needs to be used, the exponent must fit in the specified
width, or an error results. Leading zeros are added as necessary to make
the exponent the correct width. A zero exponent, however, always causes
`expp+2' spaces to be added instead of the exponent (but no spaces if
expp is omitted, or is zero). If `expp' is omitted, then as many places
as required are used for the exponent.
Examples: (with NUMERIC FORM SCIENTIFIC and NUMERIC DIGITS 9)
format('3',4) == ' 3'
format('1.73',4,0) == ' 2'
format('1.73',4,3) == ' 1.730'
format('-.76',4,1) == ' -0.8'
format('0.000') == '0'
format('12345.73',,,2,2) == '1.234573E+04'
format('12345.73',,3,,0) == '1.235E+4'
format('1.2345',,3,2,0) == '1.235 '
format('1234567e5',,3,0) == '123456700000.000'
LASTPOS(needle,haystack[,position])
This function finds the last occurrence, if any, of the needle within
haystack. The answer is the position of the last occurrence if there is
one (numbering from 1 to the length of haystack), or zero if needle does
not occur in haystack. If the optional position is supplied, the search
starts from this position instead of the end of haystack. If the
needle is the empty string, zero is returned.
LEFT(string,length[,pad])
The first two mandatory parameters are a string and a length. The result
of this function is the leftmost "length" characters of string. If
string has fewer than this many characters, then it is padded up to the
required length with spaces on the right, or, if the pad character is
given, with this character.
Examples: left("12345",2) = "12" left("123",5,"0") = "12300"
RANDOM([min][,[max][,seed]])
A pseudo-random number is returned. If no arguments are supplied, the
number will be between 0 and 999 (inclusive). If one argument is supplied
then the result will be between 0 and that number. If both min and max
are given, then the result will be between min and max inclusive.
min must be no greater than max and the magnitude of the range (that is,
max - min) must not exceed 100000. min, max and seed must be whole
numbers if they are specified.
Usually the third argument (the seed) is not supplied. In this case, on
the first call to this function the random number generator is seeded
from the system clock, and the seed is not affected on further calls, so
that a `good' sequence of random numbers is obtained.
The seed may be set to a specific value on each call by supplying the
third argument. To gain a predictable sequence of random numbers, the
seed is specified on the first call but not on subsequent calls.
RXFUNCADD(rexxname,module,sysname)
This function attempts to register a function stored in a shared object
and returns zero if it was successful. (This is simply an interface to
the API call RexxRegisterFunctionDll - see the technical reference - and
the possible return values are the same as those returned by that API
call.)
The "rexxname" parameter gives the name by which the function will
henceforth be known in Rexx. The "module" parameter gives the name of
the shared object containing the function, and the "sysname" parameter
gives the name by which the function entry point is known in the shared
object. The object will be searched for in the path given by the
environment variable REXXLIB or (if that is not set) REXXFUNC; if these
are not set then the compile-time default is used. The module name will
be used unamended; if this is not found then ".rxfn" will be appended and
the search repeated.
NOTE: Since registered functions in REXX/imc are case sensitive, this
function will register the function twice: once with the given name and
once with an uppercased version of the given name (unless the given name
was already in upper case). This allows you to say, for example:
call RxFuncAdd "SysLoadFuncs","rxsysfn","SysLoadFuncs"
call SysLoadFuncs
which would not otherwise work because the first line registers a
function called "SysLoadFuncs" whereas the second line looks for
"SYSLOADFUNCS". The return value will be zero only if both operations
succeeded.
NOTE: Unlike the OS/2 version of this function, the REXX/imc version
attempts to load the function immediately and will return non-zero if the
function could not be found.
STRIP(string[,[option][,char]])
Up to three parameters may be supplied. The first is a string upon which
the operation is performed - this normally consists of stripping leading
and trailing spaces. The second parameter, if supplied, must start with
one of the letters "L", "T" or "B". This means strip leading spaces,
trailing spaces, or both, respectively. The third parameter, if
supplied, must be a single character, in which case this character is
stripped instead of spaces.
Example: strip("000123450","l","0") = "123450"
SUBSTR(string,position[,length[,pad]])
This function makes a substring of string. Usually the parameters
string, position and length are supplied and the result is the
substring of string of length "length" starting at the "position"th
character - so
substr("abcdefg",3,2) = "cd".
If the length is omitted, then the substring continues to the end of the
string - so
substr("abcdefg",4) = "defg".
If part of the substring requested is outside of string, then spaces are
added - or if the parameter pad is given, this character is used to pad
the result. Thus
substr("abc",2,4,"0") = "bc00" and substr("abc",-1) = " abc".
LOCAL: REXX/imc allows the position to be a negative whole number.
SUBWORD(string,position[,count])
A substring of the given string is returned, starting at the
"position"th blank-delimited word, and of length "count" words. If
"count" is not specified, then the rest of the string, starting at the
"position"th word, is returned. The result never contains leading or
trailing blanks, but it contains all spaces between the words extracted.
SYMBOL(name)
The argument is interpreted as a symbol (or a number); it is uppercased,
and if it is a compound symbol, any simple symbol components of the tail
are substituted in as with the VALUE function. The result is the three
character string "BAD", indicating that the name is not a valid symbol,
"VAR", indicating that the name is a variable (i.e. a symbol which has
been assigned a value), or "LIT", indicating that the name is either a
constant symbol or a symbol without a value. For example, the program:
b='*'; a.b=5
say symbol('a') symbol('b') symbol('a.B') symbol(A.b)
say symbol('a.*') symbol('b.a') symbol('b.*')
would say "LIT VAR VAR LIT" and "BAD LIT BAD".
TIME([option][,time[,option]])
The TIME function has three uses:
- to return information about the current local time;
- to operate an elapsed time counter, and
- to convert a time from one format to another.
In order to return information about the current local time, a single
optional parameter is supplied whose first letter must match that of one
of the formatting options listed below. If the parameter is omitted then
'N' is assumed.
Civil - The time in the format hh:mmxx where hh is the hour in 12-hour
notation (no leading zero), mm is the minute, and xx is either
am or pm.
Normal - The time in 24-hour clock format as hh:mm:ss.
Long - The time in 24-hour clock format as hh:mm:ss.uuuuuu where
uuuuuu is the number of microseconds.
Hours - the number of hours since midnight.
Minutes - the number of minutes since midnight.
Seconds - the number of seconds since midnight.
Offset - the current difference (if known) between GMT and local time
measured in seconds (positive if local time is ahead).
If two or three parameters are supplied then the second parameter is a
time which must be in one of the above formats (with the exception that
'O' format is not allowed) and the optional third parameter must state
which format it is in. If the third parameter is omitted then 'N' is
assumed. If the input time is in 'M' or 'H' format then the seconds
and/or minutes values in the result will be filled in with zeros as
necessary. This form of the TIME function makes straight conversions and
does not take account of any changes in daylight savings time.
The elapsed time counter is operated by calling the TIME function with
a single parameter whose first letter matches that of either of the
following.
Elapsed - On the first call the result is 0 and on subsequent calls
the result is the elapsed time since then in the format
sssss.uuuuuu (no leading zeros).
Reset - same as Elapsed, but after the time is calculated, the timer
is reset to zero.
On the first call to TIME or DATE in an expression, a time stamp is made
which is then used for all calls to these functions within that
expression. Hence if multiple calls to these functions are made within
a single expression, they are guaranteed to be consistent with each
other. Note that this means that:
say time(e) sleep(2) time(e) x
exit
sleep:'sleep' arg(1)
x=time(e)
return ""
will type "0 0 2.062564" (perhaps) even though over two seconds elapse
during evaluation of sleep(2). Also, the timestamp only applies to
time() calls within a single expression, so the line "x=time(e)" is not
affected by the timestamp.
The elapsed time counter is saved across function calls. This means that
although a procedure inherits the elapsed time counter from its caller,
if it should reset the clock, this does not affect any timing which may
be in progress by the caller.
NOTE: The time is subject to the accuracy of the system clock, which may
not give a very reliable number of microseconds. The TIME('O')
function relies on the operating system to return the correct
offset and this may be unknown or inaccurate. The TZ environment
variable may have an effect on determining the current timezone.
TRANSLATE(string[,[tableo][,[tablei][,pad]]])
This function translates characters in string to other characters, or
may be used to change the order of characters in a string.
If neither translate table is specified, then the string is translated
into uppercase. Otherwise each character of string which is found in
tablei is translated into the corresponding character in tableo -
characters which are not found in tablei remain unchanged. The default
input table is XRANGE('00'x,'ff'x) and the default output table is the
null string. The output table is padded or truncated in order to make
it the same length as the input table, the default pad character being
a blank.
Examples:
translate('abc123DEF') == 'ABC123DEF'
translate('abbc','&','b') == 'a&&c'
translate('abcdef','12','ec') == 'ab2d1f'
translate('abcdef','12','abcd','.') == '12..ef'
translate('4123','abcd','1234') == 'dabc'
VALUE(s[,[newvalue][,selector]])
s is treated as a symbol, and if it has a value, that value is returned.
If s is not a valid symbol then an error results. Otherwise the result
is just as for a symbol appearing in a program. For compound symbols,
substitution occurs as normal, except that string constants and
expressions (types 4 and 5 in the description of symbols above) are not
allowed.
If the newvalue parameter is provided, then this value is assigned to
the symbol described above. The symbol's old value will be returned.
If the selector is provided, then this indicates an alternative
variable pool to use instead of the REXX variable pool (except that the
word "REXX" is accepted as a valid name for the usual REXX variable
pool). The only selector recognised by REXX/imc is the word
"ENVIRONMENT", which allows the value() function to examine and alter
environment variables. Note that the names and values of environment
variables may not contain NUL characters.
Example: the following program
a=1; b='*'
c.a=1; c.b=2
say value("a") value("c.a") value("c.b") value("d.b",6)
say value("d.*")
will output "1 1 2 D.*" then give an error, because "*" is not allowed
as a component of a symbol (however "b" is, even if b="*"). The value
of d.b after executing these lines will be 6.
The instructions
a=value("FOO","ENVIRONMENT")
call value "FOO","bar","ENVIRONMENT"
are similar to the instructions
a=getenv("FOO")
call putenv "FOO=bar"
respectively.
VERIFY(string,reference[,[option][,position]])
This verifies that the string contains only characters from reference
and returns 0 if this is true. Otherwise the result is the position of
the first character in string which is not in reference.
If the option is specified, its first letter must be either 'N'
(nomatch) or 'M' (match). The action for 'N' is as described above.
If 'M' is specified then the result is the position of the first
character which matches a character from the reference, and 0 if no
character from reference was found in the string.
If the position is given, the verification starts from this position
in the string instead of from the beginning.
Examples:
verify('123','1234567890') = 0
verify('1Z3','1234567890') = 2
verify('AB4T','1234567890','M') = 3
verify('1P3Q4','1234567890',,3) = 4
SYSTEM(s)
This function takes the string s, passes it to a bourne shell, and
returns as a result all text produced by that shell command on the
standard output. This function has a side effect, namely that the
variable `rc' is set to the exit status of the shell, or -1 if the shell
couldn't be invoked for some reason. This may in turn cause the
condition "ERROR" or "FAILURE" to be trapped (see the SIGNAL ON and
CALL ON instructions). Except in the case that a "SIGNAL" occurs,
there will always be a result whatever the return code, but it may be
the null string if an error occurred (or if the command produced no
output).