Built-in Functions

REXX provides a rich set of built-in functions, including character manipulation, conversion, and information functions.

Other built-in and external functions are generally available--see section External Functions Provided in REXX/CICS.

The following are general notes on the built-in functions:

ABBREV (Abbreviation)

Read syntax diagramSkip visual syntax diagram>>-ABBREV(information,info--+---------+--)---------------------><
                            '-,length-'
 

returns 1 if info is equal to the leading characters of information and the length of info is not less than length. Returns 0 if either of these conditions is not met.

If you specify length, it must be a positive whole number or zero. The default for length is the number of characters in info.

Here are some examples:

ABBREV('Print','Pri')      ->    1
ABBREV('PRINT','Pri')      ->    0
ABBREV('PRINT','PRI',4)    ->    0
ABBREV('PRINT','PRY')      ->    0
ABBREV('PRINT','')         ->    1
ABBREV('PRINT','',1)       ->    0
Note:
A null string always matches if a length of 0 (or the default) is used. This allows a default keyword to be selected automatically if desired; for example:
say 'Enter option:';   pull option .
select  /* keyword1 is to be the default */
  when abbrev('keyword1',option) then ...
  when abbrev('keyword2',option) then ...
  ...
  otherwise nop;
end;

ABS (Absolute Value)

Read syntax diagramSkip visual syntax diagram>>-ABS(number)-------------------------------------------------><
 

returns the absolute value of number. The result has no sign and is formatted according to the current NUMERIC settings.

Here are some examples:

ABS('12.3')       ->    12.3
ABS(' -0.307')    ->    0.307

ADDRESS

Read syntax diagramSkip visual syntax diagram>>-ADDRESS()---------------------------------------------------><
 

returns the name of the environment to which commands are currently being submitted. The environment may be a name of a subcommand environment. See the ADDRESS instruction (page Purpose) for more information. Trailing blanks are removed from the result.

Here are some examples:

ADDRESS()    ->    'CICS'       /* default under CICS   */
ADDRESS()    ->    'EDITSVR'    /* default under CICS editor */

ARG (Argument)

Read syntax diagramSkip visual syntax diagram>>-ARG(--+----------------+--)---------------------------------><
         '-n--+---------+-'
              '-,option-'
 

returns an argument string or information about the argument strings to a program or internal routine.

If you do not specify n, the number of arguments passed to the program or internal routine is returned.

If you specify only n, the nth argument string is returned. If the argument string does not exist, the null string is returned. The n must be a positive whole number.

If you specify option, ARG tests for the existence of the nth argument string. The following are valid options. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.)

Exists
returns 1 if the nth argument exists; that is, if it was explicitly specified when the routine was called. Returns 0 otherwise.
Omitted
returns 1 if the nth argument was omitted; that is, if it was not explicitly specified when the routine was called. Returns 0 otherwise.

Here are some examples:

/*  following "Call name;" (no arguments) */
ARG()         ->    0
ARG(1)        ->    ''
ARG(2)        ->    ''
ARG(1,'e')    ->    0
ARG(1,'O')    ->    1

/*  following "Call name 'a',,'b';" */
ARG()         ->    3
ARG(1)        ->    'a'
ARG(2)        ->    ''
ARG(3)        ->    'b'
ARG(n)        ->    ''    /* for n>=4 */
ARG(1,'e')    ->    1
ARG(2,'E')    ->    0
ARG(2,'O')    ->    1
ARG(3,'o')    ->    0
ARG(4,'o')    ->    1

Notes:
  1. The number of argument strings is the largest number n for which ARG(n,'e') would return 1 or 0 if there are no explicit argument strings. That is, it is the position of the last explicitly specified argument string.
  2. Programs called as commands can have only 0 or 1 argument strings. The program has 0 argument strings if it is called with the name only and has 1 argument string if anything else (including blanks) is included with the command.
  3. You can retrieve and directly parse the argument strings to a program or internal routine with the ARG or PARSE ARG instructions. (See pages Purpose, ***, and ***.)

BITAND (Bit by Bit AND)

Read syntax diagramSkip visual syntax diagram>>-BITAND(string1--+--------------------------+--)-------------><
                   '-,--+---------+--+------+-'
                        '-string2-'  '-,pad-'
 

returns a string composed of the two input strings logically ANDed together, bit by bit. (The encodings of the strings are used in the logical operation.) The length of the result is the length of the longer of the two strings. If no pad character is provided, the AND operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is provided, it extends the shorter of the two strings on the right before carrying out the logical operation. The default for string2 is the zero length (null) string.

Here are some examples:

BITAND('12'x)                  ->    '12'x
BITAND('73'x,'27'x)            ->    '23'x
BITAND('13'x,'5555'x)          ->    '1155'x
BITAND('13'x,'5555'x,'74'x)    ->    '1154'x
BITAND('pQrS',,'BF'x)          ->    'pqrs'      /* EBCDIC  */

BITOR (Bit by Bit OR)

Read syntax diagramSkip visual syntax diagram>>-BITOR(string1--+--------------------------+--)--------------><
                  '-,--+---------+--+------+-'
                       '-string2-'  '-,pad-'
 

returns a string composed of the two input strings logically inclusive-ORed together, bit by bit. (The encodings of the strings are used in the logical operation.) The length of the result is the length of the longer of the two strings. If no pad character is provided, the OR operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is provided, it extends the shorter of the two strings on the right before carrying out the logical operation. The default for string2 is the zero length (null) string.

Here are some examples:

BITOR('12'x)                  ->    '12'x
BITOR('15'x,'24'x)            ->    '35'x
BITOR('15'x,'2456'x)          ->    '3556'x
BITOR('15'x,'2456'x,'F0'x)    ->    '35F6'x
BITOR('1111'x,,'4D'x)         ->    '5D5D'x
BITOR('pQrS',,'40'x)          ->    'PQRS' /* EBCDIC  */

BITXOR (Bit by Bit Exclusive OR)

Read syntax diagramSkip visual syntax diagram>>-BITXOR(string1--+--------------------------+--)-------------><
                   '-,--+---------+--+------+-'
                        '-string2-'  '-,pad-'
 

returns a string composed of the two input strings logically eXclusive-ORed together, bit by bit. (The encodings of the strings are used in the logical operation.) The length of the result is the length of the longer of the two strings. If no pad character is provided, the XOR operation stops when the shorter of the two strings is exhausted, and the unprocessed portion of the longer string is appended to the partial result. If pad is provided, it extends the shorter of the two strings on the right before carrying out the logical operation. The default for string2 is the zero length (null) string.

Here are some examples:

BITXOR('12'x)                     ->  '12'x
BITXOR('12'x,'22'x)               ->  '30'x
BITXOR('1211'x,'22'x)             ->  '3011'x
BITXOR('1111'x,'444444'x)         ->  '555544'x
BITXOR('1111'x,'444444'x,'40'x)   ->  '555504'x
BITXOR('1111'x,,'4D'x)            ->  '5C5C'x
BITXOR('C711'x,'222222'x,' ')     ->  'E53362'x  /* EBCDIC */

B2X (Binary to Hexadecimal)

Read syntax diagramSkip visual syntax diagram>>-B2X(binary_string)------------------------------------------><
 

returns a string, in character format, that represents binary_string converted to hexadecimal.

The binary_string is a string of binary (0 or 1) digits. It can be of any length. You can optionally include blanks in binary_string (at four-digit boundaries only, not leading or trailing) to aid readability; they are ignored.

The returned string uses uppercase alphabetics for the values A-F, and does not include blanks.

If binary_string is the null string, B2X returns a null string. If the number of binary digits in binary_string is not a multiple of four, then up to three 0 digits are added on the left before the conversion to make a total that is a multiple of four.

Here are some examples:

B2X('11000011')    ->   'C3'
B2X('10111')       ->   '17'
B2X('101')         ->   '5'
B2X('1 1111 0000') ->   '1F0'

You can combine B2X with the functions X2D and X2C to convert a binary number into other forms. For example:

X2D(B2X('10111'))  ->   '23'   /* decimal 23 */

CENTER/CENTRE

Read syntax diagramSkip visual syntax diagram>>-+-CENTER(-+--string,length--+------+--)---------------------><
   '-CENTRE(-'                 '-,pad-'
 

returns a string of length length with string centered in it, with pad characters added as necessary to make up length. The length must be a positive whole number or zero. The default pad character is blank. If the string is longer than length, it is truncated at both ends to fit. If an odd number of characters are truncated or added, the right-hand end loses or gains one more character than the left-hand end.

Here are some examples:

CENTER(abc,7)               ->    '  ABC  '
CENTER(abc,8,'-')           ->    '--ABC---'
CENTRE('The blue sky',8)    ->    'e blue s'
CENTRE('The blue sky',7)    ->    'e blue '
Note:
To avoid errors because of the difference between British and American spellings, this function can be called either CENTRE or CENTER.

COMPARE

Read syntax diagramSkip visual syntax diagram>>-COMPARE(string1,string2--+------+--)------------------------><
                            '-,pad-'
 

returns 0 if the strings, string1 and string2, are identical. Otherwise, returns the position of the first character that does not match. The shorter string is padded on the right with pad if necessary. The default pad character is a blank.

Here are some examples:

COMPARE('abc','abc')         ->    0
COMPARE('abc','ak')          ->    2
COMPARE('ab ','ab')          ->    0
COMPARE('ab ','ab',' ')      ->    0
COMPARE('ab ','ab','x')      ->    3
COMPARE('ab-- ','ab','-')    ->    5

CONDITION

Read syntax diagramSkip visual syntax diagram>>-CONDITION(--+--------+--)-----------------------------------><
               '-option-'
 

returns the condition information associated with the current trapped condition. (See Conditions and Condition Traps for a description of condition traps.) You can request the following pieces of information:

To select the information to return, use the following options. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.)

Condition name
returns the name of the current trapped condition.
Description
returns any descriptive string associated with the current trapped condition. If no description is available, returns a null string.
Instruction
returns either CALL or SIGNAL, the keyword for the instruction processed when the current condition was trapped. This is the default if you omit option.
Status
returns the status of the current trapped condition. This can change during processing, and is either:

If no condition has been trapped, then the CONDITION function returns a null string in all four cases.

Here are some examples:

CONDITION()            ->    'CALL'        /* perhaps */
CONDITION('C')         ->    'FAILURE'
CONDITION('I')         ->    'CALL'
CONDITION('D')         ->    'FailureTest'
CONDITION('S')         ->    'OFF'        /* perhaps */

Note:
The CONDITION function returns condition information that is saved and restored across subroutine calls (including those a CALL ON condition trap causes). Therefore, after a subroutine called with CALL ON trapname has returned, the current trapped condition reverts to the condition that was current before the CALL took place (which may be none). CONDITION returns the values it returned before the condition was trapped.

COPIES

Read syntax diagramSkip visual syntax diagram>>-COPIES(string,n)--------------------------------------------><
 

returns n concatenated copies of string. The n must be a positive whole number or zero.

Here are some examples:

COPIES('abc',3)    ->    'abcabcabc'
COPIES('abc',0)    ->    ''

C2D (Character to Decimal)

Read syntax diagramSkip visual syntax diagram>>-C2D(string--+----+--)---------------------------------------><
               '-,n-'
 

returns the decimal value of the binary representation of string. If the result cannot be expressed as a whole number, an error results. That is, the result must not have more digits than the current setting of NUMERIC DIGITS. If you specify n, it is the length of the returned result. If you do not specify n, string is processed as an unsigned binary number.

If string is null, returns 0.

Here are some examples:

C2D('09'X)      ->        9
C2D('81'X)      ->      129
C2D('FF81'X)    ->    65409
C2D('')         ->        0
C2D('a')        ->      129     /*  EBCDIC  */

If you specify n, the string is taken as a signed number expressed in n characters. The number is positive if the leftmost bit is off, and negative, in two's complement notation, if the leftmost bit is on. In both cases, it is converted to a whole number, which may, therefore, be negative. The string is padded on the left with '00'x characters (note, not "sign-extended"), or truncated on the left to n characters. This padding or truncation is as though RIGHT(string,n,'00'x) had been processed. If n is 0, C2D always returns 0.

Here are some examples:

C2D('81'X,1)      ->     -127
C2D('81'X,2)      ->      129
C2D('FF81'X,2)    ->     -127
C2D('FF81'X,1)    ->     -127
C2D('FF7F'X,1)    ->      127
C2D('F081'X,2)    ->    -3967
C2D('F081'X,1)    ->     -127
C2D('0031'X,0)    ->        0

Implementation maximum: The input string cannot have more than 250 characters that are significant in forming the final result. Leading sign characters ('00'x and 'FF'x) do not count toward this total.

C2X (Character to Hexadecimal)

Read syntax diagramSkip visual syntax diagram>>-C2X(string)-------------------------------------------------><
 

returns a string, in character format, that represents string converted to hexadecimal. The returned string contains twice as many bytes as the input string. For example, on an EBCDIC system, C2X(1) returns F1 because the EBCDIC representation of the character 1 is 'F1'X.

The string returned uses uppercase alphabetics for the values A-F and does not include blanks. The string can be of any length. If string is null, returns a null string.

Here are some examples:

C2X('72s')      ->    'F7F2A2' /* 'C6F7C6F2C1F2'X in EBCDIC */
C2X('0123'X)    ->    '0123'   /* 'F0F1F2F3'X     in EBCDIC */

DATATYPE

Read syntax diagramSkip visual syntax diagram>>-DATATYPE(string--+-------+--)-------------------------------><
                    '-,type-'
 

returns NUM if you specify only string and if string is a valid REXX number that can be added to 0 without error; returns CHAR if string is not a valid number.

If you specify type, returns 1 if string matches the type; otherwise returns 0. If string is null, the function returns 0 (except when type is X, which returns 1 for a null string). The following are valid types. (Only the capitalized and highlighted letter is needed; all characters following it are ignored. Note that for the hexadecimal option, you must start your string specifying the name of the option with x rather than h.)

Alphanumeric
returns 1 if string contains only characters from the ranges a-z, A-Z, and 0-9.
Binary
returns 1 if string contains only the characters 0 or 1 or both.
C
returns 1 if string is a mixed SBCS/DBCS string.
Dbcs
returns 1 if string is a DBCS-only string enclosed by SO and SI bytes.
Lowercase
returns 1 if string contains only characters from the range a-z.
Mixed case
returns 1 if string contains only characters from the ranges a-z and A-Z.
Number
returns 1 if string is a valid REXX number.
Symbol
returns 1 if string contains only characters that are valid in REXX symbols. (See page ***.) Note that both uppercase and lowercase alphabetics are permitted.
Uppercase
returns 1 if string contains only characters from the range A-Z.
Whole number
returns 1 if string is a REXX whole number under the current setting of NUMERIC DIGITS.
heXadecimal
returns 1 if string contains only characters from the ranges a-f, A-F, 0-9, and blank (as long as blanks appear only between pairs of hexadecimal characters). Also returns 1 if string is a null string, which is a valid hexadecimal string.

Here are some examples:

DATATYPE(' 12 ')         ->   'NUM'
DATATYPE('')             ->   'CHAR'
DATATYPE('123*')         ->   'CHAR'
DATATYPE('12.3','N')     ->    1
DATATYPE('12.3','W')     ->    0
DATATYPE('Fred','M')     ->    1
DATATYPE('','M')         ->    0
DATATYPE('Fred','L')     ->    0
DATATYPE('?20K','s')     ->    1
DATATYPE('BCd3','X')     ->    1
DATATYPE('BC d3','X')    ->    1
Note:
The DATATYPE function tests the meaning or type of characters in a string, independent of the encoding of those characters (for example, ASCII or EBCDIC).

DATE

Read syntax diagramSkip visual syntax diagram>>-DATE(--+--------+--)----------------------------------------><
          '-option-'
 

returns, by default, the local date in the format: dd mon yyyy (day month year--for example, 13 Mar 1992), with no leading zero or blank on the day. If the active language has an abbreviated form of the month name, then it is used (for example, Jan, Feb, and so on).

You can use the following options to obtain specific formats. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.)

Base
returns the number of complete days (that is, not including the current day) since and including the base date, 1 January 0001, in the format: dddddd (no leading zeros or blanks). The expression DATE('B')//7 returns a number in the range 0-6 that corresponds to the current day of the week, where 0 is Monday and 6 is Sunday.

Thus, this function can be used to determine the day of the week independent of the national language in which you are working.

Note:
The base date of 1 January 0001 is determined by extending the current Gregorian calendar backward (365 days each year, with an extra day every year that is divisible by 4 except century years that are not divisible by 400). It does not take into account any errors in the calendar system that created the Gregorian calendar originally.
Century
returns 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 format: ddddd (no leading zeros). Example: A call to DATE(C) on 13 March 1992 returns 33675, the number of days from 1 January 1900 to 13 March 1992. Similarly, a call to DATE(C) on 2 January 2000 returns 2, the number of days from 1 January 2000 to 2 January 2000.
Days
returns the number of days, including the current day, so far in this year in the format: ddd (no leading zeros or blanks).
European
returns date in the format: dd/mm/yy.
Julian
returns date in the format: yyddd.
Month
returns full English name of the current month, for example, August.
Normal
returns date in the format: dd mon yyyy. This is the default.
Ordered
returns date in the format: yy/mm/dd (suitable for sorting, and so forth).
Standard
returns date in the format: yyyymmdd (suitable for sorting, and so forth).
Usa
returns date in the format: mm/dd/yy.
Weekday
returns the English name for the day of the week, in mixed case, for example, Tuesday.

Here are some examples, assuming today is 13 March 1992:

DATE()         ->    '13 Mar 1992'
DATE('B')      ->    727269
DATE('C')      ->    33675
DATE('D')      ->    73
DATE('E')      ->    '13/03/92'
DATE('J')      ->    92073
DATE('M')      ->    'March'
DATE('N')      ->    '13 Mar 1992'
DATE('O')      ->    '92/03/13'
DATE('S')      ->    '19920313'
DATE('U')      ->    '03/13/92'
DATE('W')      ->    'Friday'
Note:
The first call to DATE or TIME in one clause causes a time stamp to be made that is then used for all calls to these functions in that clause. Therefore, multiple calls to any of the DATE or TIME functions or both in a single expression or clause are guaranteed to be consistent with each other.

DBCS (Double-Byte Character Set Functions)

The following are all part of DBCS processing functions:

DELSTR (Delete String)

Read syntax diagramSkip visual syntax diagram>>-DELSTR(string,n--+---------+--)-----------------------------><
                    '-,length-'
 

returns string after deleting the substring that begins at the nth character and is of length characters. If you omit length, or if length is greater than the number of characters from n to the end of string, the function deletes the rest of string (including the nth character). The length must be a positive whole number or zero. The n must be a positive whole number. If n is greater than the length of string, the function returns string unchanged.

Here are some examples:

DELSTR('abcd',3)       ->    'ab'
DELSTR('abcde',3,2)    ->    'abe'
DELSTR('abcde',6)      ->    'abcde'

DELWORD (Delete Word)

Read syntax diagramSkip visual syntax diagram>>-DELWORD(string,n--+---------+--)----------------------------><
                     '-,length-'
 

returns string after deleting the substring that starts at the nth word and is of length blank-delimited words. If you omit length, or if length is greater than the number of words from n to the end of string, the function deletes the remaining words in string (including the nth word). The length must be a positive whole number or zero. The n must be a positive whole number. If n is greater than the number of words in string, the function returns string unchanged. The string deleted includes any blanks following the final word involved but none of the blanks preceding the first word involved.

Here are some examples:

DELWORD('Now is the  time',2,2)  ->  'Now time'
DELWORD('Now is the time ',3)    ->  'Now is '
DELWORD('Now is the  time',5)    ->  'Now is the  time'
DELWORD('Now is   the time',3,1) ->  'Now is   time'

DIGITS

Read syntax diagramSkip visual syntax diagram>>-DIGITS()----------------------------------------------------><
 

returns the current setting of NUMERIC DIGITS. See the NUMERIC instruction on page Purpose for more information.

Here is an example:

DIGITS()    ->    9      /* by default */

D2C (Decimal to Character)

Read syntax diagramSkip visual syntax diagram>>-D2C(wholenumber--+----+--)----------------------------------><
                    '-,n-'
 

returns a string, in character format, that represents wholenumber, a decimal number, converted to binary. If you specify n, it is the length of the final result in characters; after conversion, the input string is sign-extended to the required length. If the number is too big to fit into n characters, then the result is truncated on the left. The n must be a positive whole number or zero.

If you omit n, wholenumber must be a positive whole number or zero, and the result length is as needed. Therefore, the returned result has no leading '00'x characters.

Here are some examples:

D2C(9)         ->   ' '    /* '09'x is unprintable in EBCDIC       */
D2C(129)       ->   'a'    /* '81'x is an EBCDIC 'a'               */
D2C(129,1)     ->   'a'    /* '81'x is an EBCDIC 'a'               */
D2C(129,2)     ->   ' a'   /* '0081'x is EBCDIC ' a'               */
D2C(257,1)     ->   ' '    /* '01'x is unprintable in EBCDIC       */
D2C(-127,1)    ->   'a'    /* '81'x is EBCDIC 'a'                  */
D2C(-127,2)    ->   ' a'   /* 'FF'x is unprintable EBCDIC;         */
                           /* '81'x is EBCDIC 'a'                  */
D2C(-1,4)      ->   '    ' /* 'FFFFFFFF'x is unprintable in EBCDIC */
D2C(12,0)      ->   ''     /* '' is a null string                  */

Implementation maximum: The output string may not have more than 250 significant characters, though a longer result is possible if it has additional leading sign characters ('00'x and 'FF'x).

D2X (Decimal to Hexadecimal)

Read syntax diagramSkip visual syntax diagram>>-D2X(wholenumber--+----+--)----------------------------------><
                    '-,n-'
 

returns a string, in character format, that represents wholenumber, a decimal number, converted to hexadecimal. The returned string uses uppercase alphabetics for the values A-F and does not include blanks.

If you specify n, it is the length of the final result in characters; after conversion the input string is sign-extended to the required length. If the number is too big to fit into n characters, it is truncated on the left. The n must be a positive whole number or zero.

If you omit n, wholenumber must be a positive whole number or zero, and the returned result has no leading zeros.

Here are some examples:

D2X(9)         ->    '9'
D2X(129)       ->    '81'
D2X(129,1)     ->    '1'
D2X(129,2)     ->    '81'
D2X(129,4)     ->    '0081'
D2X(257,2)     ->    '01'
D2X(-127,2)    ->    '81'
D2X(-127,4)    ->    'FF81'
D2X(12,0)      ->    ''

Implementation maximum: The output string may not have more than 500 significant hexadecimal characters, though a longer result is possible if it has additional leading sign characters (0 and F).

ERRORTEXT

Read syntax diagramSkip visual syntax diagram>>-ERRORTEXT(n)------------------------------------------------><
 

returns the REXX error message associated with error number n. The n must be in the range 0-99, and any other value is an error. Returns the null string if n is in the allowed range but is not a defined REXX error number. See Appendix A. Error Numbers and Messages for a complete description of error numbers and messages.

Here are some examples:

ERRORTEXT(16)    ->    'Label not found'
ERRORTEXT(60)    ->    ''

EXTERNALS

Read syntax diagramSkip visual syntax diagram>>-EXTERNALS()-------------------------------------------------><
 

always returns a 0. For example:

EXTERNALS()    ->    0    /* Always */

The EXTERNALS function returns the number of elements in the terminal input buffer (system external event queue). In CICS, there is no equivalent buffer. Therefore, in the CICS implementation of REXX, the EXTERNALS function always returns a 0.

FIND

WORDPOS is the preferred built-in function for this type of word search. See page WORDPOS (Word Position) for a complete description.

Read syntax diagramSkip visual syntax diagram>>-FIND(string,phrase)-----------------------------------------><
 

returns the word number of the first word of phrase found in string or returns 0 if phrase is not found or if there are no words in phrase. The phrase is a sequence of blank-delimited words. Multiple blanks between words in phrase or string are treated as a single blank for the comparison.

Here are some examples:

FIND('now is the time','is the time')    ->    2
FIND('now is  the time','is    the')     ->    2
FIND('now is  the time','is  time ')     ->    0

FORM

Read syntax diagramSkip visual syntax diagram>>-FORM()------------------------------------------------------><
 

returns the current setting of NUMERIC FORM. See the NUMERIC instruction on page Purpose for more information.

Here is an example:

FORM()    ->    'SCIENTIFIC'  /* by default */

FORMAT

Read syntax diagramSkip visual syntax diagram>>-FORMAT(number------------------------------------------------>
 
>--+--------------------------------------------+--)------------>
   '-,--+--------+--+-------------------------+-'
        '-before-'  '-,--+-------+--| expnt |-'
                         '-after-'
 
>--| expnt: |--+------------------------------+----------------><
               '-,--+------+--+-------------+-'
                    '-expp-'  '-,--+------+-'
                                   '-expt-'
 

returns number, rounded and formatted.

The number is first rounded according to standard REXX rules, just as though the operation number+0 had been carried out. The result is precisely that of this operation if you specify only number. If you specify any other options, the number is formatted as follows.

The before and after options describe how many characters are used for the integer and decimal parts of the result, respectively. If you omit either or both of these, the number of characters used for that part is as needed.

If before is not large enough to contain the integer part of the number (plus the sign for a negative number), an error results. If before is larger than needed for that part, the number is padded on the left with blanks. If after is not the same size as the decimal part of the number, the number is rounded (or extended with zeros) to fit. Specifying 0 causes the number to be rounded to an integer.

Here are some examples:

FORMAT('3',4)            ->    '   3'
FORMAT('1.73',4,0)       ->    '   2'
FORMAT('1.73',4,3)       ->    '   1.730'
FORMAT('-.76',4,1)       ->    '  -0.8'
FORMAT('3.03',4)         ->    '   3.03'
FORMAT(' - 12.73',,4)    ->    '-12.7300'
FORMAT(' - 12.73')       ->    '-12.73'
FORMAT('0.000')          ->    '0'

The first three arguments are as described previously. In addition, expp and expt control the exponent part of the result, which, by default, is formatted according to the current NUMERIC settings of DIGITS and FORM. The expp sets the number of places for the exponent part; the default is to use as many as needed (which may be zero). The expt sets the trigger point for use of exponential notation. The default is the current setting of NUMERIC DIGITS.

If expp is 0, no exponent is supplied, and the number is expressed in simple form with added zeros as necessary. If expp is not large enough to contain the exponent, an error results.

If the number of places needed for the integer or decimal part exceeds expt or twice expt, respectively, exponential notation is used. If expt is 0, exponential notation is always used unless the exponent would be 0. (If expp is 0, this overrides a 0 value of expt.) If the exponent would be 0 when a nonzero expp is specified, then expp+2 blanks are supplied for the exponent part of the result. If the exponent would be 0 and expp is not specified, simple form is used. The expp must be less than 10, but there is no limit on the other arguments.

Here are some examples:

FORMAT('12345.73',,,2,2)    ->    '1.234573E+04'
FORMAT('12345.73',,3,,0)    ->    '1.235E+4'
FORMAT('1.234573',,3,,0)    ->    '1.235'
FORMAT('12345.73',,,3,6)    ->    '12345.73'
FORMAT('1234567e5',,3,0)    ->    '123456700000.000'

FUZZ

Read syntax diagramSkip visual syntax diagram>>-FUZZ()------------------------------------------------------><
 

returns the current setting of NUMERIC FUZZ. See the NUMERIC instruction on page Purpose for more information.

Here is an example:

FUZZ()    ->    0     /* by default */

INDEX

POS is the preferred built-in function for obtaining the position of one string in another. See page POS (Position) for a complete description.

Read syntax diagramSkip visual syntax diagram>>-INDEX(haystack,needle--+--------+--)------------------------><
                          '-,start-'
 

returns the character position of one string, needle, in another, haystack, or returns 0 if the string needle is not found or is a null string. By default the search starts at the first character of haystack (start has the value 1). You can override this by specifying a different start point, which must be a positive whole number.

Here are some examples:

INDEX('abcdef','cd')      ->    3
INDEX('abcdef','xd')      ->    0
INDEX('abcdef','bc',3)    ->    0
INDEX('abcabc','bc',3)    ->    5
INDEX('abcabc','bc',6)    ->    0

INSERT

Read syntax diagramSkip visual syntax diagram>>-INSERT(new,target-------------------------------------------->
 
>--+---------------------------------------+--)----------------><
   '-,--+---+--+-------------------------+-'
        '-n-'  '-,--+--------+--+------+-'
                    '-length-'  '-,pad-'
 

inserts the string new, padded or truncated to length length, into the string target after the nth character. The default value for n is 0, which means insert before the beginning of the string. If specified, n and length must be positive whole numbers or zero. If n is greater than the length of the target string, padding is added before the string new also. The default value for length is the length of new. If length is less than the length of the string new, then INSERT truncates new to length length. The default pad character is a blank.

Here are some examples:

INSERT(' ','abcdef',3)         ->    'abc def'
INSERT('123','abc',5,6)        ->    'abc  123   '
INSERT('123','abc',5,6,'+')    ->    'abc++123+++'
INSERT('123','abc')            ->    '123abc'
INSERT('123','abc',,5,'-')     ->    '123--abc'

JUSTIFY

Read syntax diagramSkip visual syntax diagram>>-JUSTIFY(string,length--+------+--)--------------------------><
                          '-,pad-'
 

returns string formatted by adding pad characters between blank-delimited words to justify to both margins. This is done to width length (length must be a positive whole number or zero). The default pad character is a blank.

The first step is to remove extra blanks as though SPACE(string) had been run (that is, multiple blanks are converted to single blanks, and leading and trailing blanks are removed). If length is less than the width of the changed string, the string is then truncated on the right and any trailing blank is removed. Extra pad characters are then added evenly from left to right to provide the required length, and the pad character replaces the blanks between words.

Here are some examples:

JUSTIFY('The blue sky',14)       ->    'The  blue  sky'
JUSTIFY('The blue sky',8)        ->    'The blue'
JUSTIFY('The blue sky',9)        ->    'The  blue'
JUSTIFY('The blue sky',9,'+')    ->    'The++blue'

LASTPOS (Last Position)

Read syntax diagramSkip visual syntax diagram>>-LASTPOS(needle,haystack--+--------+--)----------------------><
                            '-,start-'
 

returns the position of the last occurrence of one string, needle, in another, haystack. (See also the POS function.) Returns 0 if needle is the null string or is not found. By default the search starts at the last character of haystack and scans backward. You can override this by specifying start, the point at which the backward scan starts. start must be a positive whole number and defaults to LENGTH(haystack) if larger than that value or omitted.

Here are some examples:

LASTPOS(' ','abc def ghi')      ->    8
LASTPOS(' ','abcdefghi')        ->    0
LASTPOS('xy','efgxyz')          ->    4
LASTPOS(' ','abc def ghi',7)    ->    4

LEFT

Read syntax diagramSkip visual syntax diagram>>-LEFT(string,length--+------+--)-----------------------------><
                       '-,pad-'
 

returns a string of length length, containing the leftmost length characters of string. The string returned is padded with pad characters (or truncated) on the right as needed. The default pad character is a blank. length must be a positive whole number or zero. The LEFT function is exactly equivalent to:

Read syntax diagramSkip visual syntax diagram>>-SUBSTR(string,1,length--+------+--)-------------------------><
                           '-,pad-'
 

Here are some examples:

LEFT('abc d',8)        ->    'abc d   '
LEFT('abc d',8,'.')    ->    'abc d...'
LEFT('abc  def',7)     ->    'abc  de'

LENGTH

Read syntax diagramSkip visual syntax diagram>>-LENGTH(string)----------------------------------------------><
 

returns the length of string.

Here are some examples:

LENGTH('abcdefgh')    ->    8
LENGTH('abc defg')    ->    8
LENGTH('')            ->    0

LINESIZE

Read syntax diagramSkip visual syntax diagram>>-LINESIZE()--------------------------------------------------><
 

returns the current terminal line width (the point at which the language processor breaks lines displayed using the SAY instruction). Returns a default value of 80 if:

Note:
To determine if a terminal is attached, specify the REXX/CICS command SCRNINFO. The values for screen height and screen width are 0 if there is no terminal attached.

MAX (Maximum)

Read syntax diagramSkip visual syntax diagram         .-,------.
         V        |
>>-MAX(----number-+--)-----------------------------------------><
 

returns the largest number from the list specified, formatted according to the current NUMERIC settings.

Here are some examples:

MAX(12,6,7,9)                                                     ->    12
MAX(17.3,19,17.03)                                                ->    19
MAX(-7,-3,-4.3)                                                   ->    -3
MAX(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,MAX(20,21))   ->    21

Implementation maximum: You can specify up to 20 numbers, and can nest calls to MAX if more arguments are needed.

MIN (Minimum)

Read syntax diagramSkip visual syntax diagram         .-,------.
         V        |
>>-MIN(----number-+--)-----------------------------------------><
 

returns the smallest number from the list specified, formatted according to the current NUMERIC settings.

Here are some examples:

MIN(12,6,7,9)                                                     ->   6
MIN(17.3,19,17.03)                                                ->  17.03
MIN(-7,-3,-4.3)                                                   ->  -7
MIN(21,20,19,18,17,16,15,14,13,12,11,10,9,8,7,6,5,4,3,MIN(2,1))   ->  1

Implementation maximum: You can specify up to 20 numbers, and can nest calls to MIN if more arguments are needed.

OVERLAY

Read syntax diagramSkip visual syntax diagram>>-OVERLAY(new,target------------------------------------------->
 
>--+---------------------------------------+--)----------------><
   '-,--+---+--+-------------------------+-'
        '-n-'  '-,--+--------+--+------+-'
                    '-length-'  '-,pad-'
 

returns the string target, which, starting at the nth character, is overlaid with the string new, padded or truncated to length length. (The overlay may extend beyond the end of the original target string.) If you specify length, it must be a positive whole number or zero. The default value for length is the length of new. If n is greater than the length of the target string, padding is added before the new string. The default pad character is a blank, and the default value for n is 1. If you specify n, it must be a positive whole number.

Here are some examples:

OVERLAY(' ','abcdef',3)         ->    'ab def'
OVERLAY('.','abcdef',3,2)       ->    'ab. ef'
OVERLAY('qq','abcd')            ->    'qqcd'
OVERLAY('qq','abcd',4)          ->    'abcqq'
OVERLAY('123','abc',5,6,'+')    ->    'abc+123+++'

POS (Position)

Read syntax diagramSkip visual syntax diagram>>-POS(needle,haystack--+--------+--)--------------------------><
                        '-,start-'
 

returns the position of one string, needle, in another, haystack. (See also the INDEX and LASTPOS functions.) Returns 0 if needle is the null string or is not found or if start is greater than the length of haystack. By default the search starts at the first character of haystack (that is, the value of start is 1). You can override this by specifying start (which must be a positive whole number), the point at which the search starts.

Here are some examples:

POS('day','Saturday')       ->    6
POS('x','abc def ghi')      ->    0
POS(' ','abc def ghi')      ->    4
POS(' ','abc def ghi',5)    ->    8

QUEUED

Read syntax diagramSkip visual syntax diagram>>-QUEUED()----------------------------------------------------><
 

returns the number of lines remaining in the external data queue when the function is called. If no lines are remaining, a PULL or PARSE PULL reads from the terminal input buffer. If no terminal input is waiting, this causes a console read.

Here is an example:

QUEUED()    ->    5    /* Perhaps */

RANDOM

Read syntax diagramSkip visual syntax diagram>>-RANDOM(--+------------------------------+--)----------------><
            +-max--------------------------+
            '-+-min,-+--+-----+--+-------+-'
              '-,----'  '-max-'  '-,seed-'
 

returns a quasi-random nonnegative whole number in the range min to max inclusive. If you specify max or min or both, max minus min cannot exceed 100000. The min and max default to 0 and 999, respectively. To start a repeatable sequence of results, use a specific seed as the third argument, as described in Note 1. This seed must be a positive whole number ranging from 0 to 999999999.

Here are some examples:

RANDOM()          ->    305
RANDOM(5,8)       ->      7
RANDOM(2)         ->      0  /*  0  to  2    */
RANDOM(,,1983)    ->    123  /* reproducible */

Notes:
  1. To obtain a predictable sequence of quasi-random numbers, use RANDOM a number of times, but specify a seed only the first time. For example, to simulate 40 throws of a 6-sided, unbiased die:
    sequence = RANDOM(1,6,12345)  /* any number would */
                                  /* do for a seed    */
    do 39
       sequence = sequence RANDOM(1,6)
       end
    say sequence
    The numbers are generated mathematically, using the initial seed, so that as far as possible they appear to be random. Running the program again produces the same sequence; using a different initial seed almost certainly produces a different sequence. If you do not supply a seed, the first time RANDOM is called, the microsecond field of the time-of-day clock is used as the seed; and hence your program almost always gives different results each time it is run.
  2. The random number generator is global for an entire program; the current seed is not saved across internal routine calls.

REVERSE

Read syntax diagramSkip visual syntax diagram>>-REVERSE(string)---------------------------------------------><
 

returns string, swapped end for end.

Here are some examples:

REVERSE('ABc.')    ->    '.cBA'
REVERSE('XYZ ')    ->    ' ZYX'

Read syntax diagramSkip visual syntax diagram>>-RIGHT(string,length--+------+--)----------------------------><
                        '-,pad-'
 

returns a string of length length containing the rightmost length characters of string. The string returned is padded with pad characters (or truncated) on the left as needed. The default pad character is a blank. The length must be a positive whole number or zero.

Here are some examples:

RIGHT('abc  d',8)     ->    '  abc  d'
RIGHT('abc def',5)    ->    'c def'
RIGHT('12',5,'0')     ->    '00012'

SIGN

Read syntax diagramSkip visual syntax diagram>>-SIGN(number)------------------------------------------------><
 

returns a number that indicates the sign of number. The number is first rounded according to standard REXX rules, just as though the operation number+0 had been carried out. Returns -1 if number is less than 0; returns 0 if it is 0; and returns 1 if it is greater than 0.

Here are some examples:

SIGN('12.3')       ->     1
SIGN(' -0.307')    ->    -1
SIGN(0.0)          ->     0

SOURCELINE

Read syntax diagramSkip visual syntax diagram>>-SOURCELINE(--+---+--)---------------------------------------><
                '-n-'
 

returns the line number of the final line in the program if you omit n, or returns the nth line in the program if you specify n. If specified, n must be a positive whole number and must not exceed the number of the final line in the program.

Here are some examples:

SOURCELINE()    ->   10
SOURCELINE(1)   ->   '/* This is a 10-line REXX program */'

SPACE

Read syntax diagramSkip visual syntax diagram>>-SPACE(string--+--------------------+--)---------------------><
                 '-,--+---+--+------+-'
                      '-n-'  '-,pad-'
 

returns the blank-delimited words in string with n pad characters between each word. If you specify n, it must be a positive whole number or zero. If it is 0, all blanks are removed. Leading and trailing blanks are always removed. The default for n is 1, and the default pad character is a blank.

Here are some examples:

SPACE('abc  def  ')          ->    'abc def'
SPACE('  abc def',3)         ->    'abc   def'
SPACE('abc  def  ',1)        ->    'abc def'
SPACE('abc  def  ',0)        ->    'abcdef'
SPACE('abc  def  ',2,'+')    ->    'abc++def'

STORAGE

See section External Functions Provided in REXX/CICS.

STRIP

Read syntax diagramSkip visual syntax diagram>>-STRIP(string--+--------------------------+--)---------------><
                 '-,--+--------+--+-------+-'
                      '-option-'  '-,char-'
 

returns string with leading or trailing characters or both removed, based on the option you specify. The following are valid options. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.)

Both
removes both leading and trailing characters from string. This is the default.
Leading
removes leading characters from string.
Trailing
removes trailing characters from string.

The third argument, char, specifies the character to be removed, and the default is a blank. If you specify char, it must be exactly one character long.

Here are some examples:

STRIP('  ab c  ')        ->    'ab c'
STRIP('  ab c  ','L')    ->    'ab c  '
STRIP('  ab c  ','t')    ->    '  ab c'
STRIP('12.7000',,0)      ->    '12.7'
STRIP('0012.700',,0)     ->    '12.7'

SUBSTR (Substring)

Read syntax diagramSkip visual syntax diagram>>-SUBSTR(string,n--+-------------------------+--)-------------><
                    '-,--+--------+--+------+-'
                         '-length-'  '-,pad-'
 

returns the substring of string that begins at the nth character and is of length length, padded with pad if necessary. The n must be a positive whole number. If n is greater than LENGTH(string), then only pad characters are returned.

If you omit length, the rest of the string is returned. The default pad character is a blank.

Here are some examples:

SUBSTR('abc',2)          ->    'bc'
SUBSTR('abc',2,4)        ->    'bc  '
SUBSTR('abc',2,6,'.')    ->    'bc....'
Note:
In some situations the positional (numeric) patterns of parsing templates are more convenient for selecting substrings, especially if more than one substring is to be extracted from a string. See also the LEFT and RIGHT functions.

SUBWORD

Read syntax diagramSkip visual syntax diagram>>-SUBWORD(string,n--+---------+--)----------------------------><
                     '-,length-'
 

returns the substring of string that starts at the nth word, and is up to length blank-delimited words. The n must be a positive whole number. If you omit length, it defaults to the number of remaining words in string. The returned string never has leading or trailing blanks, but includes all blanks between the selected words.

Here are some examples:

SUBWORD('Now is the  time',2,2)    ->    'is the'
SUBWORD('Now is the  time',3)      ->    'the  time'
SUBWORD('Now is the  time',5)      ->    ''

SYMBOL

Read syntax diagramSkip visual syntax diagram>>-SYMBOL(name)------------------------------------------------><
 

returns the state of the symbol named by name. Returns BAD if name is not a valid REXX symbol. Returns VAR if it is the name of a variable (that is, a symbol that has been assigned a value). Otherwise returns LIT, indicating that it is either a constant symbol or a symbol that has not yet been assigned a value (that is, a literal).

As with symbols in REXX expressions, lowercase characters in name are translated to uppercase and substitution in a compound name occurs if possible.

Note:
You should specify name as a literal string (or it should be derived from an expression) to prevent substitution before it is passed to the function.

Here are some examples:

/* following: Drop A.3;  J=3 */
SYMBOL('J')      ->   'VAR'
SYMBOL(J)        ->   'LIT' /* has tested "3"     */
SYMBOL('a.j')    ->   'LIT' /* has tested A.3     */
SYMBOL(2)        ->   'LIT' /* a constant symbol  */
SYMBOL('*')      ->   'BAD' /* not a valid symbol */

TIME

Read syntax diagramSkip visual syntax diagram>>-TIME(--+--------+--)----------------------------------------><
          '-option-'
 

returns the local time in the 24-hour clock format: hh:mm:ss (hours, minutes, and seconds) by default, for example, 04:41:37.

You can use the following options to obtain alternative formats, or to gain access to the elapsed-time clock. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.)

Civil
returns the time in Civil format: hh:mmxx. The hours may take the values 1 through 12, and the minutes the values 00 through 59. The minutes are followed immediately by the letters am or pm. This distinguishes times in the morning (12 midnight through 11:59 a.m.--appearing as 12:00am through 11:59am) from noon and afternoon (12 noon through 11:59 p.m.--appearing as 12:00pm through 11:59pm). The hour has no leading zero. The minute field shows the current minute (rather than the nearest minute) for consistency with other TIME results.
Elapsed
returns sssssssss.uuuuuu, the number of seconds.microseconds since the elapsed-time clock (described later) was started or reset. The number has no leading zeros or blanks, and the setting of NUMERIC DIGITS does not affect the number. The fractional part always has six digits.
Hours
returns up to two characters giving the number of hours since midnight in the format: hh (no leading zeros or blanks, except for a result of 0).
Long
returns time in the format: hh:mm:ss.uuuuuu (uuuuuu is the fraction of seconds, in microseconds). The first eight characters of the result follow the same rules as for the Normal form, and the fractional part is always six digits.
Minutes
returns up to four characters giving the number of minutes since midnight in the format: mmmm (no leading zeros or blanks, except for a result of 0).
Normal
returns the time in the default format hh:mm:ss, as described previously. The hours can have the values 00 through 23, and minutes and seconds, 00 through 59. All these are always two digits. Any fractions of seconds are ignored (times are never rounded up). This is the default.
Reset
returns sssssssss.uuuuuu, the number of seconds.microseconds since the elapsed-time clock (described later) was started or reset and also resets the elapsed-time clock to zero. The number has no leading zeros or blanks, and the setting of NUMERIC DIGITS does not affect the number. The fractional part always has six digits.
Seconds
returns up to five characters giving the number of seconds since midnight in the format: sssss (no leading zeros or blanks, except for a result of 0).

Here are some examples, assuming that the time is 4:54 p.m.:

TIME()       ->   '16:54:22'
TIME('C')    ->   '4:54pm'
TIME('H')    ->   '16'
TIME('L')    ->   '16:54:22.123456'   /* Perhaps */
TIME('M')    ->   '1014'           /* 54 + 60*16 */
TIME('N')    ->   '16:54:22'
TIME('S')    ->   '60862'  /* 22 + 60*(54+60*16) */
The elapsed-time clock:

You can use the TIME function to measure real (elapsed) time intervals. On the first call in a program to TIME('E') or TIME('R'), the elapsed-time clock is started, and either call returns 0. From then on, calls to TIME('E') and to TIME('R') return the elapsed time since that first call or since the last call to TIME('R').

The clock is saved across internal routine calls, which is to say that an internal routine inherits the time clock its caller started. Any timing the caller is doing is not affected, even if an internal routine resets the clock. An example of the elapsed-time clock:

time('E')    ->    0          /* The first call */
/* pause of one second here */
time('E')    ->    1.002345   /* or thereabouts */
/* pause of one second here */
time('R')    ->    2.004690   /* or thereabouts */
/* pause of one second here */
time('R')    ->    1.002345   /* or thereabouts */
Note:
See the note under DATE about consistency of times within a single clause. The elapsed-time clock is synchronized to the other calls to TIME and DATE, so multiple calls to the elapsed-time clock in a single clause always return the same result. For the same reason, the interval between two usual TIME/DATE results may be calculated exactly using the elapsed-time clock.
Implementation maximum:
If the number of seconds in the elapsed time exceeds nine digits (equivalent to over 31.6 years), an error results.

TRACE

Read syntax diagramSkip visual syntax diagram>>-TRACE(--+--------+--)---------------------------------------><
           '-option-'
 

returns trace actions currently in effect and, optionally, alters the setting.

If you specify option, it selects the trace setting. It must be one of the valid prefixes ? or ! or one of the alphabetic character options associated with the TRACE instruction (that is, starting with A, C, E, F, I, L, N, O, R, or S) or both.

Unlike the TRACE instruction, the TRACE function alters the trace action even if interactive debug is active. Also unlike the TRACE instruction, option cannot be a number.

Here are some examples:

TRACE()       ->   '?R' /* maybe */
TRACE('O')    ->   '?R' /* also sets tracing off    */
TRACE('?I')   ->   'O'  /* now in interactive debug */

TRANSLATE

Read syntax diagramSkip visual syntax diagram>>-TRANSLATE(string--------------------------------------------->
 
>--+--------------------------------------------+--)-----------><
   '-,--+--------+--+-------------------------+-'
        '-tableo-'  '-,--+--------+--+------+-'
                         '-tablei-'  '-,pad-'
 

returns string with each character translated to another character or unchanged. You can also use this function to reorder the characters in string.

The output table is tableo and the input translation table is tablei. TRANSLATE searches tablei for each character in string. If the character is found, then the corresponding character in tableo is used in the result string; if there are duplicates in tablei, the first (leftmost) occurrence is used. If the character is not found, the original character in string is used. The result string is always the same length as string.

The tables can be of any length. If you specify neither translation table and omit pad, string is simply translated to uppercase (that is, lowercase a-z to uppercase A-Z), but, if you include pad, the language processor translates the entire string to pad characters. tablei defaults to XRANGE('00'x,'FF'x), and tableo defaults to the null string and is padded with pad or truncated as necessary. The default pad is a blank.

Here are some examples:

TRANSLATE('abcdef')                    ->    'ABCDEF'
TRANSLATE('abbc','&','b')              ->    'a&&c'
TRANSLATE('abcdef','12','ec')          ->    'ab2d1f'
TRANSLATE('abcdef','12','abcd','.')    ->    '12..ef'
TRANSLATE('APQRV',,'PR')               ->    'A Q V'
TRANSLATE('APQRV',XRANGE('00'X,'Q'))   ->    'APQ  '
TRANSLATE('4123','abcd','1234')        ->    'dabc'
Note:
The last example shows how to use the TRANSLATE function to reorder the characters in a string. In the example, the last character of any four-character string specified as the second argument would be moved to the beginning of the string.

TRUNC (Truncate)

Read syntax diagramSkip visual syntax diagram>>-TRUNC(number--+----+--)-------------------------------------><
                 '-,n-'
 

returns the integer part of number and n decimal places. The default n is 0 and returns an integer with no decimal point. If you specify n, it must be a positive whole number or zero. The number is first rounded according to standard REXX rules, just as though the operation number+0 had been carried out. The number is then truncated to n decimal places (or trailing zeros are added if needed to make up the specified length). The result is never in exponential form.

Here are some examples:

TRUNC(12.3)           ->    12
TRUNC(127.09782,3)    ->    127.097
TRUNC(127.1,3)        ->    127.100
TRUNC(127,2)          ->    127.00
Note:
The number is rounded according to the current setting of NUMERIC DIGITS if necessary before the function processes it.

USERID

Read syntax diagramSkip visual syntax diagram>>-USERID()----------------------------------------------------><
 

returns the CICS signon user ID if the user is signed onto CICS or the CICS region default user ID (if one was specified by the CICS systems programmer). User IDs are padded on the right with blanks so that the returned value is always eight bytes long.

Here is an example:

USERID()    ->    'ARTHUR' /* Maybe */

VALUE

Read syntax diagramSkip visual syntax diagram>>-VALUE(name--+--------------------------------+--)-----------><
               '-,--+----------+--+-----------+-'
                    '-newvalue-'  '-,selector-'
 

returns the value of the symbol that name (often constructed dynamically) represents and optionally assigns it a new value. By default, VALUE refers to the current REXX-variables environment, however, if you want to specify selector the value must be RLS. If the selector of RLS is specified, then the variable operated on is a REXX List System (RLS) variable, rather than a REXX variable. If you use the function to refer to REXX variables, then name must be a valid REXX symbol. (You can confirm this by using the SYMBOL function.) Lowercase characters in name are translated to uppercase. Substitution in a compound name (see section Compound Symbols) occurs if possible.

If you specify newvalue, then the named variable is assigned this new value. This does not affect the result returned; that is, the function returns the value of name as it was before the new assignment.

Here are some examples:

/* After: Drop A3; A33=7; K=3; fred='K'; list.5='Hi' */
VALUE('a'k)     ->  'A3' /* looks up A3     */
VALUE('a'k||k)  ->  '7'  /* looks up A33    */
VALUE('fred')   ->  'K'  /* looks up FRED   */
VALUE(fred)     ->  '3'  /* looks up K      */
VALUE(fred,5)   ->  '3'  /* looks up K and  */
                         /* then sets K=5   */
VALUE(fred)     ->  '5'  /* looks up K      */
VALUE('LIST.'k) ->  'Hi' /* looks up LIST.5 */

The following example returns the VALUE of the REXX variable FRED that has been stored in an RLS variable.

/* REXX EXEC - ASSIGN FIND VALUE OF FRED  */
FRED = 7
'RLS VARPUT FRED \USERS\userid\'
X = VALUE(FRED,,RLS)
SAY X
/* X now = 7                              */

Notes:
  1. If the VALUE function refers to an uninitialized REXX variable then the default value of the variable is always returned; the NOVALUE condition is not raised. A reference to RLS variables never raises NOVALUE.
  2. If you specify the name as a single literal string and omit newvalue and selector, the symbol is a constant and so the string between the quotation marks can usually replace the whole function call. (For example, fred=VALUE('k'); is identical with the assignment fred=k;, unless the NOVALUE condition is being trapped. See Conditions and Condition Traps.)

VERIFY

Read syntax diagramSkip visual syntax diagram>>-VERIFY(string,reference--+---------------------------+--)---><
                            '-,--+--------+--+--------+-'
                                 '-option-'  '-,start-'
 

returns a number that, by default, indicates whether string is composed only of characters from reference; returns 0 if all characters in string are in reference, or returns the position of the first character in string not in reference.

The option can be either Nomatch (the default) or Match. (Only the capitalized and highlighted letter is needed. All characters following it are ignored, and it can be in upper- or lowercase, as usual.) If you specify Match, the function returns the position of the first character in string that is in reference, or returns 0 if none of the characters are found.

The default for start is 1; thus, the search starts at the first character of string. You can override this by specifying a different start point, which must be a positive whole number.

If string is null, the function returns 0, regardless of the value of the third argument. Similarly, if start is greater than LENGTH(string), the function returns 0. If reference is null, the function returns 0 if you specify Match; otherwise the function returns the start value.

Here are some examples:

VERIFY('123','1234567890')             ->    0
VERIFY('1Z3','1234567890')             ->    2
VERIFY('AB4T','1234567890')            ->    1
VERIFY('AB4T','1234567890','M')        ->    3
VERIFY('AB4T','1234567890','N')        ->    1
VERIFY('1P3Q4','1234567890',,3)        ->    4
VERIFY('123','',N,2)                   ->    2
VERIFY('ABCDE','',,3)                  ->    3
VERIFY('AB3CD5','1234567890','M',4)    ->    6

WORD

Read syntax diagramSkip visual syntax diagram>>-WORD(string,n)----------------------------------------------><
 

returns the nth blank-delimited word in string or returns the null string if fewer than n words are in string. The n must be a positive whole number. This function is exactly equivalent to SUBWORD(string,n,1).

Here are some examples:

WORD('Now is the time',3)    ->    'the'
WORD('Now is the time',5)    ->    ''

WORDINDEX

Read syntax diagramSkip visual syntax diagram>>-WORDINDEX(string,n)-----------------------------------------><
 

returns the position of the first character in the nth blank-delimited word in string or returns 0 if fewer than n words are in string. The n must be a positive whole number.

Here are some examples:

WORDINDEX('Now is the time',3)    ->    8
WORDINDEX('Now is the time',6)    ->    0

WORDLENGTH

Read syntax diagramSkip visual syntax diagram>>-WORDLENGTH(string,n)----------------------------------------><
 

returns the length of the nth blank-delimited word in string or returns 0 if fewer than n words are in string. The n must be a positive whole number.

Here are some examples:

WORDLENGTH('Now is the time',2)       ->    2
WORDLENGTH('Now comes the time',2)    ->    5
WORDLENGTH('Now is the time',6)       ->    0

WORDPOS (Word Position)

Read syntax diagramSkip visual syntax diagram>>-WORDPOS(phrase,string--+--------+--)------------------------><
                          '-,start-'
 

returns the word number of the first word of phrase found in string or returns 0 if phrase contains no words or if phrase is not found. Multiple blanks between words in either phrase or string are treated as a single blank for the comparison, but otherwise the words must match exactly.

By default the search starts at the first word in string. You can override this by specifying start (which must be positive), the word at which to start the search.

Here are some examples:

WORDPOS('the','now is the time')              ->  3
WORDPOS('The','now is the time')              ->  0
WORDPOS('is the','now is the time')           ->  2
WORDPOS('is   the','now is the time')         ->  2
WORDPOS('is   time ','now is   the time')     ->  0
WORDPOS('be','To be or not to be')            ->  2
WORDPOS('be','To be or not to be',3)          ->  6

WORDS

Read syntax diagramSkip visual syntax diagram>>-WORDS(string)-----------------------------------------------><
 

returns the number of blank-delimited words in string.

Here are some examples:

WORDS('Now is the time')    ->    4
WORDS(' ')                  ->    0

XRANGE (Hexadecimal Range)

Read syntax diagramSkip visual syntax diagram>>-XRANGE(--+-------+--+------+--)-----------------------------><
            '-start-'  '-,end-'
 

returns a string of all valid 1-byte encodings (in ascending order) between and including the values start and end. The default value for start is '00'x, and the default value for end is 'FF'x. If start is greater than end, the values wrap from 'FF'x to '00'x. If specified, start and end must be single characters.

Here are some examples:

XRANGE('a','f')      ->   'abcdef'
XRANGE('03'x,'07'x)  ->   '0304050607'x
XRANGE(,'04'x)       ->   '0001020304'x
XRANGE('i','j')      ->   '898A8B8C8D8E8F9091'x  /* EBCDIC */
XRANGE('FE'x,'02'x)  ->   'FEFF000102'x

X2B (Hexadecimal to Binary)

Read syntax diagramSkip visual syntax diagram>>-X2B(hexstring)----------------------------------------------><
 

returns a string, in character format, that represents hexstring converted to binary. The hexstring is a string of hexadecimal characters. It can be of any length. Each hexadecimal character is converted to a string of four binary digits. You can optionally include blanks in hexstring (at byte boundaries only, not leading or trailing) to aid readability; they are ignored.

The returned string has a length that is a multiple of four, and does not include any blanks.

If hexstring is null, the function returns a null string.

Here are some examples:

X2B('C3')        ->  '11000011'
X2B('7')         ->  '0111'
X2B('1 C1')      ->  '000111000001'

You can combine X2B with the functions D2X and C2X to convert numbers or character strings into binary form.

Here are some examples:

X2B(C2X('C3'x))  ->  '11000011'
X2B(D2X('129'))  ->  '10000001'
X2B(D2X('12'))   ->  '1100'

X2C (Hexadecimal to Character)

Read syntax diagramSkip visual syntax diagram>>-X2C(hexstring)----------------------------------------------><
 

returns a string, in character format, that represents hexstring converted to character. The returned string is half as many bytes as the original hexstring. hexstring can be of any length. If necessary, it is padded with a leading 0 to make an even number of hexadecimal digits.

You can optionally include blanks in hexstring (at byte boundaries only, not leading or trailing) to aid readability; they are ignored.

If hexstring is null, the function returns a null string.

Here are some examples:

X2C('F7F2 A2')    ->    '72s'       /*  EBCDIC                     */
X2C('F7f2a2')     ->    '72s'       /*  EBCDIC                     */
X2C('F')          ->    ' '         /*  '0F' is unprintable EBCDIC */

X2D (Hexadecimal to Decimal)

Read syntax diagramSkip visual syntax diagram>>-X2D(hexstring--+----+--)------------------------------------><
                  '-,n-'
 

returns the decimal representation of hexstring. The hexstring is a string of hexadecimal characters. If the result cannot be expressed as a whole number, an error results. That is, the result must not have more digits than the current setting of NUMERIC DIGITS.

You can optionally include blanks in hexstring (at byte boundaries only, not leading or trailing) to aid readability; they are ignored.

If hexstring is null, the function returns 0.

If you do not specify n, hexstring is processed as an unsigned binary number.

Here are some examples:

X2D('0E')        ->    14
X2D('81')        ->    129
X2D('F81')       ->    3969
X2D('FF81')      ->    65409
X2D('c6 f0'X)    ->    240          /*  EBCDIC  */

If you specify n, the string is taken as a signed number expressed in n hexadecimal digits. If the leftmost bit is off, then the number is positive; otherwise, it is a negative number in two's complement notation. In both cases it is converted to a whole number, which may, therefore, be negative. If n is 0, the function returns 0.

If necessary, hexstring is padded on the left with 0 characters (note, not "sign-extended"), or truncated on the left to n characters.

Here are some examples:

X2D('81',2)      ->    -127
X2D('81',4)      ->    129
X2D('F081',4)    ->    -3967
X2D('F081',3)    ->    129
X2D('F081',2)    ->    -127
X2D('F081',1)    ->    1
X2D('0031',0)    ->    0

Implementation maximum: The input string may not have more than 500 hexadecimal characters that will be significant in forming the final result. Leading sign characters (0 and F) do not count towards this total.