Rexx
title bar
Classic Rexx FUNCTIONS
ABBREV COPIES FORMAT POS TRACE
ABS COUNTSTR FUZZ QUALIFY TRANSLATE
ADDRESS C2D INDEX QUEUED TRUNC
ARG C2X INSERT RANDOM USERID
BITAND DATATYPE JUSTIFY REVERSE VALUE
BITOR DATE LASTPOS RIGHT VERIFY
BITXOR DELSTR LEFT SIGN WORD
B2X DELWORD LENGTH SOURCELINE WORDINDEX
CENTER DIGITS LINEIN SPACE WORDLENGTH
CHANGESTR D2C LINEOUT STREAM WORDPOS
CHARIN D2X LINES STRIP WORDS
CHAROUT ERRORTEXT LINESIZE SUBSTR XRANGE
CHARS EXTERNALS MAX SUBWORD X2B
COMPARE FIND MIN SYMBOL X2C
CONDITION FORM OVERLAY TIME X2D

Go to INSTRUCTIONS

This chart covers ANSI-1996, TRL-2, z/OS, and z/VM Rexx.

Functions in boldface are supported only on z/OS and z/VM. They are not part of ANSI standard Rexx.

Excludes z/OS and z/VM external, DBCS, and console functions -- see IBM's product manuals for those.

Key -- Optionally encoded operands are surrounded by brackets [ ]. The "or" bar | means you encode either one operand or the other.

Send corrections to "WebmasterA" at-sign RexxInfo dot org. Thanks.


ABBREV

ABBREV(information, info [,length])

Returns 1 if info is equal to the leading characters of information and info is not less than the minimum length. Otherwise returns 0. If not specified, length defaults to the length of info.

Examples --

abbrev('Hello','He') == 1
abbrev('Hello','Hi')   == 0
abbrev('Hello','Hi',3) == 0          /* INFO does not meet minimum LENGTH. */


ABS

ABS(number)

Returns the absolute value of number, formatted according to the current setting of numeric digits and without a leading sign.

Examples --

abs(-0.47) == 0.47
abs(0)       == 0


ADDRESS

ADDRESS()

---or---

ADDRESS([option])


The first format returns the name of the environment to which commands are currently directed.

The second format is from the ANSI-1996 standard, which allows a new format for this function that specifies an option. z/OS and z/VM Rexx do not support this format.

The option returns information on the targets of command output and the sources of command input.

option may be any one of the following:

N (Normal) -- Returns the current default environment
(Input)    -- Returns the target details for input as three words:  position type resource
O (Output) -- Returns the target details for output as three words: position type resource
E (Error)    -- Returns the target details for errors as three words:  position type resource

Examples --

address()    == SYSTEM                      /* for example */
address()    == UNIX                            /* for example */
address('I')   == INPUT NORMAL         /* for example */
address('E') == REPLACE NORMAL   /* for example */


ARG

ARG([argnum [,option]])

If argnum and option are not specified, returns the number of comma-separated arguments passed to the program, subroutine, or function. Only comma-separated input arguments will be interpreted by ARG as different arguments. Space-separated strings are all considered as part of a single argument. Thus, programs called as commands (from the command line) can only have 0 or 1 argument strings.

If only argnum is specified, returns the nth argument string, or the null string if the argument does not exist. The option may be either:

E or e (Exists)   -- Returns 1 if the nth argument exists.
O or o (Omitted) -- Returns 1 if the nth argument was omitted.

Examples --

/* If issued from a routine invoked by: call routine 1, 2 */
arg()  == 2
arg(1) == 1
arg(2) == 2
arg(3) == ''           /* the null string */
arg(1,'e') == 1
arg(1,'E') == 1
arg(1,'o') == 0
arg(3,'o') == 1


BITAND

BITAND(string1 [,[string2] [,pad]])

Returns a string derived from logically AND'ing two input strings, bit by bit.

If pad is omitted, AND'ing terminates when the shorter string ends, and the remaining portion of the longer string is appended to the result. If pad is specified, the shorter string is padded on the right prior to the AND'ing.

Example --

bitand('00110011','00001111')  ==  00000011


BITOR

BITOR(string1 [,[string2] [,pad]])

Returns a string derived from logically OR'ing two strings, bit by bit.

If pad is omitted, OR'ing terminates when the shorter string ends, and the remaining portion of the longer string is appended to the result. If pad is specified, the shorter string is padded on the right prior to the OR'ing.

Example --

bitor('00110011','00001111')   ==  00111111


BITXOR

BITXOR(string1 [,[string2] [,pad]])

Returns a string derived from logically EXCLUSIVE OR'ing two strings, bit by bit.

If pad is omitted, EXCLUSIVE OR'ing terminates when the shorter string ends, and the remaining portion of the longer string is appended to the result. If pad is specified, the shorter string is padded on the right prior to the EXCLUSIVE OR'ing.

Example --

bitxor('123456'x,'3456'x)  ==  '266256'x

See this result on the display screen by entering:

say c2x(bitxor('123456'x,'3456'x))


B2X

B2X(binary_string)

Converts a binary string to its hexadecimal (base 16) equivalent. The hex string will consist of digits 0 to 9 and uppercase letters A through F.

Examples --

b2x('11000010') == C2
b2x('111')         == 7


CENTER or CENTRE

CENTER(string, length [,pad])

--or--

CENTRE(string, length [,pad])

Returns a string of the length specified by length with the string centered within it. Characters of type pad are added to achieve the required length. pad defaults to blanks.

Examples --

center('HELP!',9)    == ' HELP!  '              /* 2 spaces were added on each side of HELP!   */
center('HELP!',9,'x') == 'xxHELP!xx'       /* 2 x's are added on each side of HELP!               */


CHANGESTR       (not supported by z/OS or z/VM)

CHANGESTR(needle, haystack, newneedle)

This function was added by the ANSI-1996 standard. It replaces all occurrences of string needle in string haystack with string newneedle. Returns the haystack if needle is not found.

Examples --

changestr('x','abcx','d') == abcd
changestr('x','abcc','d') == abcc        /* needle was not found in haystack */


CHARIN       (supported by z/OS if the Stream I/O Package is installed)

CHARIN([name] [,[start] [,length]])

Returns up to length characters from the character input stream name. The default length is 1, and the default character stream is the default input stream.

start may be coded to move the read pointer of a persistent stream and explicitly specify where to start the read. A start position of 1 is the first character in the persistent stream. To move the read pointer for a persistent stream without reading any input, specify a read length of 0.

If length number of characters cannot be returned, the program waits until they become available, or else the NOTREADY condition is raised and charin returns with fewer characters than requested.

Examples --

charin('text_file',5)        /* reads the next five characters from file text_file */
charin('text_file',1,5)      /* reads first five characters from file text_file       */
charin('text_file',1,0)      /* positions the read pointer to the start of text_file and does not read in any characters */


CHAROUT      (supported by z/OS if the Stream I/O Package is installed)

CHAROUT([name] [,[string] [,start]])

Writes the characters of string to the output stream specified by name, starting at position start. Returns the number of characters remaining after the output attempt; a return of 0 means a successful write.

If start is omitted, characters are written at the current write pointer position (for example, appended to the end of the persistent stream or output file). If name is omitted, characters are written to the default output stream (normally the display screen).

To position the write pointer, specify start and omit string. A start value of 1 is the beginning of an output file.

The NOTREADY condition is raised if all characters cannot be written.

Examples --

charout('text_file','Hello')     /* writes 'Hello' to text_file and returns 0     */
charout(,'Hello')                  /* writes 'Hello' to default output, the display */
charout('text_file',,1)          /* positions the write file pointer to start of the text_file (& does not write anything) */


CHARS      (supported by z/OS if the Stream I/O Package is installed)

CHARS([name])     or     CHARS([name] [,option]}

The first format above returns the number of characters remaining to be read in stream name. In the ANSI-1996 standard, chars may alternatively return 1 when any number of characters remain to be read. Always returns 0 if there are no characters left to read. If name is omitted, the function applies to the default input stream.

The ANSI-1996 standard added option, which is coded as either C or N. C stands for Count, and returns the number of characters left in the input stream. N stands for Normal, the default, and returns 1 if there are one or more characters left in the input stream, or 0 otherwise.

Examples --

chars('text_file') == 90     /* 90 characters left to read from text_file.    */
chars('text_file') == 0      /* end of file on text_file                                */
chars('text_file') == 1      /* Either there is exactly 1 character left to    */
                                       /* read from text_file, or this is ANSI-1996,  */
                                      /* and there may be 1 or more left to read.     */

z/OS and z/VM only support the first format of the chars function (the one without the option). It returns 1 if there is at least one character available in the stream and 0 otherwise.


COMPARE

COMPARE(string1, string2 [,pad])

Returns 0 if the strings are the same. Otherwise, it returns the position of the first character that is not the same in both strings. If one string is shorter, pad is used to pad it for comparison. pad defaults to blanks.

Examples --

compare('Hello','Hello') == 0
compare('Hello','He')    == 3
compare('Hello','He','x') == 3


CONDITION

CONDITION([option])

Returns condition information concerning the current trapped condition, or the null string if no condition has been trapped. The option may be coded as follows:

(Condition name) -- Name of the currently trapped condition
(Description)       -- Descriptive string for the condition
(Instruction)          -- Returns the invoking instruction, either call or signal.
                                   This is the default if no option is specified.
S (State)                 -- Returns state of the trapped condition, either ON, OFF, or DELAY.

Examples --

condition()    == CALL          /* if the trap was enabled by CALL         */
condition('C') == FAILURE  /* if the condition trapped was FAILURE */
condition('I')   == CALL       /* if the trap was enabled by CALL         */
condition('S') == OFF          /* if the state is now OFF                      */


COPIES

COPIES(string, times)

Returns a string copied the number of times specified by times.

Example --

copies('Hello',3)  ==  HelloHelloHello


COUNTSTR       (not supported by z/OS or z/VM)

COUNTSTR(needle, haystack)

This function was added by the ANSI-1996 standard. It returns the count of the number of times needle occurs within haystack. Returns 0 if the needle is not found.

Example --

countstr('a','abracadabra')  ==  5


C2D

C2D(string [,length])

Character to decimal conversion. Returns the decimal representation of a character string. Optional length specifies the number of characters of string to be converted. length defaults to the full string length, and string is considered an unsigned number.

Examples --

c2d('14'x) == 20       /* hexadecimal 14 converted to decimal is 20 */
c2d('hi')  == 26729   /* on ASCII machines only                              */


C2X

C2X(string)

Character to hexadecimal conversion. Returns the string of hex digits that represent string.

Examples --

c2x('123'x) == 0123
c2x('abc')   == 616263           /* on ASCII machines only */


DATATYPE

DATATYPE(string [,type])

If type is omitted, returns NUM if string is a valid Rexx number; returns CHAR otherwise. If type is specified, returns 1 if the string matches the type; returns 0 otherwise. Allowable type specifications are:

A (Alphanumeric)   --Returns 1 if string consists solely of alphanumeric characters 0-9, a-z, and A-Z
B (Binary)             -- Returns 1 if string contains only 0's and 1's
L (Lowercase)      --Returns 1 if string consists solely of characters a-z
M (Mixed case)     --Returns 1 if string consists of characters a-z and A-Z
N (Number)           --Returns 1 if string is a valid Rexx number
S (Symbol)           --Returns 1 if string consists of characters valid in Rexx symbols
U (Uppercase)      --Returns 1 if string consists of characters A-Z
W (Whole number) --Returns 1 if string is a Rexx whole number
X (HeXadecimal)    --Returns 1 if string is a hex number, containing only characters a-f, A-F, and digits 0-9

z/OS and z/VM add two more TYPES to the list:

C -- returns 1 if string is a mixed SBCS/DBCS string
D (Dbcs) -- returns 1 if string is a DBCS-only string enclosed by SO and SI bytes

Examples --

datatype(' 123 ')      == NUM        /* blanks are allowed within Rexx numbers */
datatype(' 123 ','N') == NUM         /* same test as omitting the 'N'                 */
datatype('0011','b') == 1               /* yes, the string is binary                           */
datatype('2f4a','x')   == 1              /* yes, the string is hex                               */


DATE

DATE( [option_out [,date [,option_in]]] )

If all options are omitted, returns the date in the format dd Mmm yyyy, for example: 14 Jun 2005.

If the first argument is supplied, it defines the format of the return string. The list below shows possible encodings for the option_out parameter:

B (Base)      -- Returns the number of complete days since the base date of January 1, 0001.
D (Days)       -- Returns the number of days so far in the year (includes the current day)
E (European) -- Returns the date in EU format, dd/mm/yy
M (Month)     -- Returns the full English name of the current month, for example: June
N (Normal)    -- Returns the date in the default format (see above)
O Ordered)    -- Returns the date in a sort-friendly format yy/mm/dd
S
(Standard)  -- Returns the date in the sort-friendly format yyyymmdd
U (USA)         -- Returns the date in American format, mm/dd/yy
W
(Weekday) -- Returns the English name for the day of the week, for example: Monday

z/OS and z/VM add two more parameters to this list:

C (Century) -- the number of days, including the current day, since and including January 1 of the last year that is a multiple of 100 in the form: ddddd (no leading zeros)
J (Julian) -- date in the format: yyddd

If the date option is encoded, the function converts that date. The parameter option_in specifies the format in which the date is supplied and option_out is the target format to which the date is converted.

The TRL-2 form of this function only allows for coding the first argument. ANSI-1996 adds the other two arguments (supported by z/OS and z/VM).

Examples --

date('d') == 166             /* This is the 166th day of the year, including today. */
date('u') == 06/14/05      /* today's date in USA format                                  */
date('s') == 20050614    /* today's date in standard format                            */


DELSTR

DELSTR(string, start [,length])

Deletes the substring of string that starts at position start for the specified length. If length is omitted, the rest of the string is deleted from position start to the end.

Examples --

delstr('abcd',2)   == a
delstr('abcd',2,1) == acd


DELWORD

DELWORD(string, start [,length])

Deletes the substring of string that starts at position start and is of length length blank-delimited words. If length is omitted, it defaults to removing the rest of the words in string.

Examples --

delword('Roses are Red',2)   == Roses             /* deletes from word 2 to end */
delword('Roses are Red',2,1) == Roses Red    /* deletes 1 word at position 2 */


DIGITS

DIGITS()

Returns the current setting of numeric digits (which dictates the precision of calculations).

Example --

digits() == 9              /* the default if NUMERIC DIGITS has not been altered */


D2C

D2C(integer [,length])

Decimal-to-character conversion. Returns the character string representation of integer. If length is specified, the returned string will be length bytes long with sign extension.

Examples --

d2c(127) == '7F'x      /* to display a result enter: say c2x(d2c(127)) */
d2c(0)     == ''           /* returns the null string                                    */


D2X

D2X(integer [,length])

Decimal-to-hexadecimal conversion. Returns the hex representation of integer. length specifies the length of the resulting string.

Examples --

d2x(127) == 7F
d2x(0)     == 0


ERRORTEXT

ERRORTEXT(error_no)

Returns the textual error message associated with the given error number, error_no. The ANSI-1996 standard adds the ability to retrieve the text from error submessages. For example, you could retrieve the textual equivalent of error submessage 14.1.

Example --

say errortext(14)  ==  Incomplete DO/SELECT/IF


EXTERNALS     (Mainframe only)

EXTERNALS()

For z/VM, this returns the number of elements in the terminal input buffer (system external event queue).

In z/OS, there is no equivalent buffer. Therefore, in the TSO/E implementation of REXX, the externals function always returns a 0

Example --

externals()  ==  0     /* Under z/VM, only if no lines are present */
externals()  ==  0     /* Under z/OS, 0 is ALWAYS returned */


FIND     (Mainframe only)

FIND(string, phrase)

Returns the word number of the first occurrence of phrase in string. Returns 0 if phrase is not found. Multiple blanks between words are treated as one in comparisons. The ANSI-1996 standard function wordpos performs the same work and should be used instead when possible.

Examples --

find('now is the time','the')        == 3
find('now is the time','xxx')        == 0
find('now is the time','the time') == 3


FORM

FORM()

Returns the current form in which numbers are exponentially represented, either scientific or engineering.

Example --

say form() == SCIENTIFIC           /* this is the default if not altered by NUMERIC FORM */


FORMAT

FORMAT(number [,[before] [,[after]]])

---or---

FORMAT(number [,[before] [,[after] [,[expp] [,expt]]]])

The first format template above rounds and formats a number. before and after control the number of characters used for the integer and decimal parts, respectively.

Examples --

format('1',4)        == ' 1'                /* 3 blanks precede the 1. */
format('1.22',4,0) == ' 1'               /* 3 blanks precede the 1. */
format('1.22',4,2) == ' 1.22'          /* 3 blanks precede the 1. */
format('00.00')    == '0'


In the second format template above, expp and expt control the formatting of the exponential part of the result. expp is the number of digits used for the exponential part, while expt sets the trigger for the use of exponential notation.

Examples --

format('12345.67',,,2,3) == '1.234567E+04'
format('12345.67',,,4,4) == '1.234567E+0004'
format('12345.67',,2,,0) == '1.23E+4'
format('12345.67',,3,,0) == '1.235E+4'


FUZZ

FUZZ()

Returns the current setting of numeric fuzz.

Example --

fuzz() == 0            /* if the default of NUMERIC FUZZ was not altered */


INDEX       (Mainframe only)

INDEX(haystack, needle [,start])

Returns the character position of needle within string haystack. Returns 0 if needle is not found. If specified, start tells where in haystack to initiate the search. It defaults to 1 if not specified. The ANSI-1996 standard pos function can perform the same work and is preferred over index.

Examples --

index('this','x')            == 0             /* not found                                      */
index('this','hi')           == 2
index('thisthisthis','hi') == 2            /* returns position of first occurrence */


INSERT

INSERT(string, target [,[position] [,length] [,pad]])

Returns the result of inserting string into the target string. position specifies where the insertion occurs, with a default of 0 (prior to any characters of the target string). length pads with the pad character or truncates string before it is inserted into the target string, as necessary.

Examples --

insert('J.','Felix Unger',6,3) == 'Felix J. Unger'
insert('Happy!','I am',5)      == 'I am Happy!'


JUSTIFY       (Mainframe only)

JUSTIFY(string, length [,pad])

Evenly justifies words within a string. The length specifies the length of the returned string, while pad specifies what padding to insert (if necessary). pad defaults to blank. The ANSI-1996 standard right and left functions can be used as alternatives to justify.

Examples --

justify('this is it',18)     == 'this is it'                      /* 5 blanks between words */
justify('this is it',18,'x') == 'thisxxxxxisxxxxxit'      /* 5 x's between words      */
justify(' this is it',18,'x') == 'thisxxxxxisxxxxxit'    /* 5 x's between words      */
                                                                            /* ignores leading/trailing blanks           */
justify('this is it',3) == 'thi'                                   /* truncation occurs, LENGTH too short */


LASTPOS

LASTPOS(needle, haystack [,start])

Returns the last occurrence of one string, the needle, within another, the haystack. The search starts at the last position within the haystack, or may be set by start. Returns 0 if the needle string is not found in the haystack.

Examples --

lastpos('abc','abcdef')        == 1
lastpos('abc','abcabcabc') == 7
lastpos('abcd',abcabcabc') == 0                    /* The needle was not found in the haystack. */


LEFT

LEFT(string, length [,pad])

Returns the length leftmost characters in string. Pads with the pad character if length is greater than the length of string.

Examples --

left('Hi there',2)       == 'Hi'
left('Hi there',10)      == 'Hi there  '                   /* 2 blanks trail! */
left('Hi there',10,'x') == 'Hi therexx'


LENGTH

LENGTH(string)

Returns the length of string.

Examples --

length('Me first!')  == 9
length('')             == 0                 /* length of the null string is 0 */


LINEIN       (supported by z/OS if the Stream I/O Package is installed)

LINEIN([name] [,[line] [,count]])

Returns lines from the input stream name. count may be 0 or 1, and it defaults to 1. name defaults to the default input stream. line positions to the given line number prior to the read. count may be specified as 0 with a line number to position the read pointer to a particular line in a persistent input file without reading data.

Examples --

linein('text_file')            /* reads the next line from the input file text_file     */
linein()                         /* reads the next line from the default input stream   */
linein('text_file',5,0)      /* positions read pointer to the 5th line in the file      */
                                    /* and reads no data due to the count of 0               */


LINEOUT     (supported by z/OS if the Stream I/O Package is installed)

LINEOUT([name] [,[string] [,line]])

Writes string to output stream name and returns either 0 on a successful write or 1 on failure.

May be used to position the write pointer before a specified line number on persistent streams or files. If string and line are omitted, the write position is set to the end of stream. In most Rexxes, this closes the file specified by name.

Examples --

lineout(,'Hi!')                  /* writes Hi! to default output stream, normally returns 0 */
lineout('text_file','Hi!')     /* writes Hi! to text_file, normally returns 0                     */
lineout('text_file')           /* positions write pointer to end of file,                         */
                                      /* and closes the file in most Rexxes                           */


LINES       (supported by z/OS if the Stream I/O Package is installed)

LINES([name])

---or---

LINES([name] [,option])

The first format above returns 0 if no lines remain to be read from the name input stream. Otherwise, it returns 1 or the actual number of lines in the input stream. In z/VM, the function returns the number of completed lines remaining in the character input stream. z/OS only supports the first format above, and only if the Stream I/O Package is installed.

Examples --

lines('text_file') == 0      /* end of file, no lines left to read  */
lines('text_file') == 127  /* 127 lines left to read on input   */
lines('text_file') == 1      /* 1 (or more) lines left to read     */

The second above format for lines function was added by the ANSI-1996 standard. z/VM does not support it. This new format adds an option to control whether or not the user wants the interpreter to return an exact line count at the cost of performance overhead:

In this format, the option may be either:

C (Count)   -- Returns the exact number of lines left in the input stream
N (Normal) -- Default. Returns 1 if there are one or more lines left in input stream

Examples --

lines('text_file')     == 1          /* 1 (or more) lines left to read */
lines('text_file','N') == 1        /* 1 (or more) lines left to read */
lines('text_file','C') == 1        /* EXACTLY 1 line left to read */


LINESIZE     (Mainframe only)

LINESIZE()

Under z/VM -- returns the current terminal line width (the point at which the language processor breaks lines displayed by the say instruction). It returns 0 in any of these cases:

*  Terminal line size cannot be determined.
*  Virtual machine is disconnected.
*  The command CP TERMINAL LINESIZE OFF is in effect.

Examples --

linesize()           /* returns the current terminal width                      */
linesize() == 0    /* one of the three conditions listed above pertains */

Under z/OS TSO/E -- if the script runs in foreground, returns the current terminal line width minus 1 (the point at which the language processor breaks lines displayed by the say instruction). If the script runs in background, this function always returns 131. In non-TSO/E address spaces, this function returns the logical record length of the OUTDD file (default is SYSTSPRT).

Examples --

linesize()             /* if the script is running in foreground, returns terminal width */
linesize() == 131  /* script is running in background                                       */


MAX

MAX(number1 [,number2]...)

Returns the largest number from the given list of numbers.

Example --

max(-9,14,0)   ==  14


MIN

MIN(number1 [,number2]...)

Returns the smallest number from the given list of numbers.

Example --

min(-9,14,0)   ==  -9


OVERLAY

OVERLAY(string1, string2 [,[start] [,[length] [,pad]]])

Returns a copy of string2, partially or fully overwritten by string1. start specifies the starting position of the overlay, and defaults to the first position, 1. length truncates or pads string1 prior to the operation, using pad as the pad character.

Examples --

overlay('not','this is really right',9,6,'.')  == 'this is not... right'
overlay('eous','this is right',14)             == 'this is righteous'


POS

POS(needle, haystack [,start])

Returns the first position of the string needle within the string haystack. The scan starts at the first position in the haystack, unless start is coded as some number other than 1. Returns 0 if needle does not occur within haystack.

Examples --

pos('abc','abcdef')          == 1
pos('ab','abracadabra')    == 1
pos('abd','abracadabra') == 0         /* needle was not found in the haystack */


QUALIFY       (not supported by z/OS or z/VM)

QUALIFY([streamid])

This function was added by the ANSI-1996 standard. It returns a name for the streamid that will be associated with the persistent stream or file and can be used in future references to that resource.

Example --

qualify('text_file') ==   C:\regina\pgms\text_file
                                 /* Text_file was located and its fully */
                                 /* qualified path name was returned. */


QUEUED

QUEUED()

Returns the number of lines remaining in the external data queue (the stack).

Example --

queued()   ==  5           /* five reads will process the stack */


RANDOM

RANDOM(max)

---or---

RANDOM([min] [,[max] [,seed]])

Returns a pseudo-random integer. In the first format, this number will be between 0 and max. The second format allows the dictating of the eligible range of numbers and the seeding of the operation.

Examples --

random(5)                /* returns a pseudo-random number between 0 and 5 */
random(1,6)              /* simulate the roll of one die                                      */


REVERSE

REVERSE(string)

Returns a copy of a string with its characters reversed.

Example --

reverse('abc') == 'cba'


RIGHT

RIGHT(string, length [,pad])

Returns a string of length length containing the rightmost characters of string, padded with the pad character or truncated to fit the length.

Examples --

right('abc',7)     == ' abc'                      /* 4 spaces precede: abc */
right('abc',7,'x') == 'xxxxabc'                /* 4 x's precede: abc       */


SIGN

SIGN(number)

Returns 1 if the number is positive, 0 if the number is 0, and -1 if the number is negative.

Examples --

sign(-88)  == -1
sign(88)   == 1
sign(+0)   == 0


SOURCELINE

SOURCELINE([line_number])

With no argument, sourceline returns the number of lines in the script. If line_number is given, that specific line is returned from the script.

Examples --

sourceline(2)        /* returns the second line in the script                         */
sourceline()           /* returns the line number of the last line in the script */


SPACE

SPACE(string [,[length] [,pad]])

Formats a string by replacing internal blanks with length occurrences of the pad character. The default pad character is blank and the default length is 1. Leading and trailing blanks are always removed. If length is 0, all blanks are removed.


Examples --

space('abc abc')           == 'abc abc'      /* reduces 3 internal spaces to 1        */
space('abc abc',1,'x')   == 'abcxabc'      /* reduces 3 internal spaces to one x */
space('abc abc',0)       == 'abcabc'         /* LENGTH of 0 removes spaces       */


STREAM     (supported by z/OS if the Stream I/O Package is installed)

STREAM(name [,option [,command]])

name is the stream to which to apply an option and optionally a command. Typical options include:

C (Command)   -- Issues the command (implementation-dependent)
D (Description) -- Returns textual description of the stream's state
S (State)         -- Returns the stream's state, which will be either: ERROR, NOTREADY, READY, or UNKNOWN.

The commands that can be encoded on the STREAM function depend on the interpreter. Even the format of the stream function may vary.

See your interpreter's reference guide to see what commands it supports. Many interpreters permit such operations as explicitly opening, closing, and flushing files; moving the file position pointers; returning detailed stream information; and setting and/or changing the file's processing mode.

Examples --

stream('text_file','s')  ==  READY           /* stream state is good for I/O            */
stream('text_file','c','open read')            /* issues a COMMAND on the stream                                   */
                                                               /* The allowable commands are implementation-dependent */


STRIP

STRIP(string [,option] [,char]])

Returns string stripped of leading and/or trailing blanks or any other char specified. option values determine the action:

L (Leading) -- Strip off leading blanks or char if specified.
T (Trailing)  -- Strip off trailing blanks or char if specified.
B (Both)      -- Strip off both leading and trailing blanks or char if specified. This is the default.

Examples --

strip(' abc ')                 == 'abc'             /* strip off both leading & trailing blanks */
strip('xxxabcxxx',,'x')    == 'abc'            /* strip off both leading & trailing x's      */
strip('xxxabcxxx','t','x') == 'xxxabc'       /* strip off only trailing x's                      */


SUBSTR

SUBSTR(string, start [,[length] [,pad]])

Returns a substring from string. start is the starting character position in string, defaulting to 1. length is how many characters to take, defaulting to the remainder of the string from start. If length is longer than the string, padding occurs with the pad character, which defaults to the blank.

Examples --

substr('Roses are Red',7,3)      == 'are'
substr('Roses are Red',55)       == ''                    /* null string, START is too big */
substr('Roses are Red',11,5,'x') == 'Redxx'          /* padded with x's                   */


SUBWORD

SUBWORD(string, start [,length])

Returns the substring that begins at blank-delimited word start. If length is omitted, it defaults to the remainder of the string.

Examples --

subword('Violets are due',3)   == 'due'
subword('Violets are due',4)   == ''                        /* null string, no fourth word */


SYMBOL

SYMBOL(name)

Returns the state of symbol name. Returns:

BAD -- name is not a valid symbol.
VAR -- name is a symbol and has been assigned a value.
LIT   -- name is valid symbol but is assigned no value (or it is a constant symbol).

Examples --

/* execute these lines of code in sequence */
a  = 'valid!'
symbol('a')  ==  VAR
symbol('b')  ==  LIT                 /* b has not been assigned. */


TIME

TIME( [option_out [,time [,option_in]] ] )

The TRL-2 form of this function allows for coding the first argument only. z/OS and z/VM follow this convention. The ANSI-1996 standard adds the other two arguments.

If only the first parameter is encoded, the function returns the system time in 24-hour clock format: hh:mm:ss, for example: 19:19:50. Options include:

C (Civil)       -- Returns hh:mmxx civil-format time. xxis amor pm.
E (Elapsed) -- Returns elapsed time since the clock was started or reset, in the format sssssssss.uuuuuu
H (Hours)   -- Returns the number of completed hours since midnight in the format hh. Values range from 0 to 23.
L (Long)    -- Returns the time in long format: hh:mm:ss.uuuuuu
M
(Minutes) - Returns the number of completed minutes since midnight in the format mmmm
N (Normal)  -- Returns the time in the default format (hh:mm:ss)
R (Reset)   -- Returns elapsed time since the clock was started or reset in the format sssssssss.uuuuuu
S (Seconds) -- Returns the number of complete seconds since midnight

Examples --

time('C')  ==  7:25pm        /* for example */
time('m')  ==  1166            /* for example */

To use the elapsed timer, make a first call to time('e') or time('r'). This returns 0. Subsequent calls to time('e') and time('r') will return the elapsed interval since the first call or since the last call to time('r').

Examples --

time('e')  ==  0                       /* first call always returns 0    */
time('e')  ==  46.172000         /* time elapsed since first call */

In the ANSI-1996 version of this function, if the time option is encoded, the function converts that time. The parameter option_in specifies the format in which the time is supplied and option_out is the target format to which the time is converted.


TRACE

TRACE([setting])

Returns the trace setting. If setting is specified, it sets the trace to that level (and returns the old trace value). The settings are:

A (All)               -- Trace all clauses before execution.
C (Commands)  -- Trace all host commands before execution.
E (Errors)          -- Trace host commands that result in error or failure.
F (Failure)         -- Trace host commands that fail.
I (Intermediates) -- Trace all clauses before execution, with intermediate results.
L (Labels)        -- Trace labels.
N (Normal)        -- Default, trace only host commands that fail.
O (Off)             -- Trace nothing.
R (Results)       -- Trace clauses before execution and expression results.
? (interactive)   -- Toggles the interactive trace on or off. May precede any of the preceding letters.
!                      -- Inhibits host command execution (on z/OS, z/VM, and certain other implementations only).
S (Scan)           -- Traces clauses but does not process them (z/OS and z/VM only)

Unlike the trace instruction, whole numbers may not be coded on the trace function.

Examples --

trace()            /* returns current trace setting            */
trace('I')         /* turns on the Intermediate-level trace */

(Note that the ANSI standard does allow for slightly differing implementations in regards to trace behavior, output content, and format of that output.)


TRANSLATE

TRANSLATE(string [,[tableout] [,[tablein] [,pad]]])

Returns a translated copy of string. Characters are translated according to the input translation table tablein and its output equivalent, tableout. If tablein and tableout are not coded, all characters in string are translated to uppercase. If tableout is shorter than tablein, it is padded with the pad character or its default, blanks.

Examples --

translate('abc')           == 'ABC'             /* translates to uppercase */
translate('abc','xy','ab') == 'xyc'            /* a and b were translated */


TRUNC

TRUNC(number [,length])

Returns number truncated to length decimal places. If not specified, length is 0, meaning that a whole number is returned.

Examples --


trunc(27.33)   == 27                       /* returns a whole number        */
trunc(27.23,1) == 27.2                   /* truncated to 1 decimal place */
trunc(27.23,3) == 27.230               /* 3 places past decimal place  */


USERID     (Mainframe only)

USERID()

Returns the name of the current user (his or her userid).

Example --

userid() == ZHBF01                     /* if the login id were ZHBF01 */

Under z/OS, if the script is running in a non-TSO/E address space, this function returns either the userid specified, the stepname, or the jobname.


VALUE

VALUE(symbol [,[newvalue] [,pool]])

Returns the value of the variable specified by symbol. If newvalue is specified, this value is assigned to the named variable. pool references an implementation-dependent variable collection or pool to search for the symbol. This function performs an extra level of variable interpretation. z/OS does not support this parameter.

Examples --

/* assume these statements are executed in sequence */
a  = 2
b = 'a'
value('b') == a                                          /* looks up b */
value(b)   == 2                                          /* looks up a */

/* this second example shows updating an environmental variable via VALUE */
/* The variable to update is called REXXPATH, and the value it will be             */
/* assigned is in the second argument. ENVIRONMENT is the pool name.       */

call value 'REXXPATH','/afs/slac/www/slac/www/tool/cgi-rexx','ENVIRONMENT'


VERIFY

VERIFY(string, reference [,[option] [,start]])

Verifies that all characters in string are members of the reference string. Returns the position of the first character in string that is not in reference, or 0 if all characters in string are in reference.

start specifies where in string to start the search, the default is 1. The option may be:

N (Nomatch) -- Default. Works as described earlier.
M (Match)    -- Returns the position of the first character in string that is in reference.

Examples --

verify('ab12','abcdefgh')  == 3               /* 1 is the first character not in REFERENCE */
verify('dg','abcdefgh')      == 0              /* all STRING characters are in REFERENCE */
verify('dg','abcdefgh','m') == 1             /* d is first character found in REFERENCE      */


WORD

WORD(string, wordno)

Returns the blank-delimited word number wordno from the string string, or the null string, if the word does not exist in string.

Examples --

word('tis the time',2)   ==  'the'
word('tis the time,4)    == ''                     /* The null string is returned. */


WORDINDEX

WORDINDEX(string, wordno)

Returns the character position of the first character of the blank-delimited word given by word number wordno within string. Returns 0 if the word numbered wordno does not exist in the string.

Example --

wordindex('tis the time',2)  ==  5             /* 'the' starts in position 5 */


WORDLENGTH

WORDLENGTH(string, wordno)

Returns the length of blank-delimited word wordno within the string. Returns 0 for a nonexistent word.

Example --

wordlength('tis the time',2) == 3          /* 'the' has three characters */


WORDPOS

WORDPOS(phrase, string [,start])

If phrase is a substring of string, returns the word number position at which it begins. Otherwise returns 0. start is an optional word number within string at which the search starts. It defaults to 1.

Examples --

wordpos('time of','tis the time of the season')  == 3
wordpos('never','tis the time of the season')    == 0                  /* phrase not found */


WORDS

WORDS(string)

Returns the number of blank-delimited words within the string.

Examples --

words('tis the time of the season for love') == 8
words('tis the time of the season')             == 6


XRANGE

XRANGE([start] [,end])

Returns a string composed of all the characters between start and end inclusive. start defaults to '00'x, and end defaults to 'FF'x.

Examples --

xrange('a','d')  ==  'abcd'
xrange()                                       /* returns the entire character set from '00'x thru 'FF'x */


X2B

X2B(hexstring)

Hexadecimal to binary string conversion.

Examples --

x2b('FF')    ==  '11111111'
x2b('ff')      ==  '11111111'
x2b('0d0a') == '0000110100001010'


X2C

X2C(hexstring)

Hexadecimal-to--character string conversion.

Examples --

c2x('Hello')             == 48656C6C6F
x2c(48656C6C6F)  == Hello                    /* verify the result by inverting back */


X2D

X2D(hexstring [,length])

Hexadecimal-to-decimal conversion. Returns the whole number string that is the decimal representation of hexstring. Omitting length means hexstring will be interpreted as an unsigned number. Coding length means the leftmost bit of hexstring determines the sign.

Examples --

x2d('FFFF')    == 65535
x2d('FFFF',4) == -1                                /* LENGTH means signed interpretation */

 

Top of Page