Built-In Functions

More than 50 functions are built into the language processor. The built-in functions fall into the following categories:

The following tables briefly describe the functions in each category. For a complete description of these functions, see Functions.

Arithmetic Functions

Function Description
ABS Returns the absolute value of the input number.
DIGITS Returns the current setting of NUMERIC DIGITS.
FORM Returns the current setting of NUMERIC FORM.
FUZZ Returns the current setting of NUMERIC FUZZ.
MAX Returns the largest number from the list specified, formatted according to the current NUMERIC settings.
MIN Returns the smallest number from the list specified, formatted according to the current NUMERIC settings.
RANDOM Returns a quasi-random, non-negative whole number in the range specified.
SIGN Returns a number that indicates the sign of the input number.
TRUNC Returns the integer part of the input number and optionally a specified number of decimal places.

Comparison Functions

Function Description
COMPARE Returns 0 if the two input strings are identical. Otherwise, returns the position of the first character that does not match.
DATATYPE Returns a string indicating the input string is a particular data type, such as a number or character.
SYMBOL Returns VAR, LIT, or BAD to indicate the state of the symbol (variable, literal, or bad).

Conversion Functions

Function Description
B2X Returns the hexadecimal representation of the input binary string. (Binary to Hexadecimal).
C2D Returns the decimal representation of the input character string. (Character to Decimal).
C2X Returns the hexadecimal representation of the input character string. (Character to Hexadecimal).
D2C Returns the character representation of the input decimal string. (Decimal to Character).
D2X Returns the hexadecimal representation of the input decimal string. (Decimal to Hexadecimal).
X2B Returns the binary representation of the input hexadecimal string. (Hexadecimal to Binary).
X2C Returns the character representation of the input hexadecimal string. (Hexadecimal to Character).
X2D Returns the decimal representation of the input hexadecimal string. (Hexadecimal to Decimal).

Formatting Functions

Is a non-SAA built-in function REXX/CICS provides.

Function Description
CENTER or CENTRE Returns a string of a specified length with the input string centered in it, with pad characters added as necessary to make up the length.
COPIES Returns the specified number of concatenated copies of the input string.
FORMAT Returns the input number, rounded and formatted.
JUSTIFY Returns a specified string formatted by adding pad characters between words to justify to both margins.
LEFT Returns a string of the specified length, truncated or padded on the right as needed.
RIGHT Returns a string of the specified length, truncated or padded on the left as needed.
SPACE Returns the words in the input string with a specified number of pad characters between each word.

String Manipulating Functions

Function Description
ABBREV Returns a string indicating if one string is equal to the specified number of leading characters of another string.
DELSTR Returns a string after deleting a specified number of characters, starting at a specified point in the input string.
DELWORD Returns a string after deleting a specified number of words, starting at a specified word in the input string.
FIND Returns the word number of the first word of a specified phrase found within the input string.
INDEX Returns the character position of the first character of a specified string found in the input string.
INSERT Returns a character string after inserting another input string into it from a specified character position.
LASTPOS Returns the starting character position of the last occurrence of one string in another.
LENGTH Returns the length of the input string.
OVERLAY Returns a string that is the target string overlaid by a second input string.
POS Returns the character position of one string in another.
REVERSE Returns a character string that is the reverse of the original.
STRIP Returns a character string after removing leading or trailing characters or both from the input string.
SUBSTR Returns a portion of the input string beginning at a specified character position.
SUBWORD Returns a portion of the input string starting at a specified word number.
TRANSLATE Returns a character string with each character of the input string translated to another character or unchanged.
VERIFY Returns a number indicating whether an input string is composed only of characters from another input string or returns the character position of the first unmatched character.
WORD Returns a word from an input string as a specified number indicates.
WORDINDEX Returns the character position in an input string of the first character in the specified word.
WORDLENGTH Returns the length of a specified word in the input string.
WORDPOS Returns the word number of the first word of a specified phrase in the input string.
WORDS Returns the number of words in the input string.

Miscellaneous Functions

Function Description
ADDRESS Returns the name of the environment to which commands are currently being sent.
ARG Returns an argument string or information about the argument strings to a program or internal routine.
BITAND Returns a string composed of the two input strings logically ANDed together, bit by bit.
BITOR Returns a string composed of the two input strings logically ORed together, bit by bit.
BITXOR Returns a string composed of the two input strings eXclusive ORed together, bit by bit.
CONDITION Returns the condition information, such as name and status, associated with the current trapped condition.
DATE Returns the date in the default format (dd mon yyyy) or in one of various optional formats.
ERRORTEXT Returns the error message associated with the specified error number.
EXTERNALS This function always returns a 0.
LINESIZE Returns the width of the current output device.
QUEUED Returns the number of lines remaining in the external data queue at the time when the function is called.
SOURCELINE Returns either the line number of the last line in the source file or the source line a number specifies.
TIME Returns the local time in the default 24-hour clock format (hh:mm:ss) or in one of various optional formats.
TRACE Returns the trace actions currently in effect.
USERID Returns the current user ID. This is the last user ID specified on the SETUID command, the user ID of the calling REXX program if one program calls another, the user ID under which the job is running, or the job name.
VALUE Returns the value of a specified symbol and optionally assigns it a new value.
XRANGE Returns a string of all 1-byte codes (in ascending order) between and including specified starting and ending values.

Testing Input with Built-In Functions

Some of the built-in functions provide a convenient way to test input. When a program uses input, the user might provide input that is not valid. For instance, in the example of using comparison expressions on page ***, the program uses a dollar amount in the following instruction.

PARSE PULL yesterday  /* Gets yesterday's price from input stream */

If the program pulls only a number, the program processes that information correctly. However, if the program pulls a number preceded by a dollar sign or pulls a word, such as nothing, the program returns an error. To avoid getting an error, you can check the input with the DATATYPE function as follows.

IF DATATYPE(yesterday) \= 'NUM'
THEN DO
       SAY 'The input amount was in the wrong format.'
       EXIT
     END

Other useful built-in functions to test input are WORDS, VERIFY, LENGTH, and SIGN.

Exercise - Writing a program with Built-In Functions

Write a program that checks a file name for a length of 8 characters. If the name is longer than 8 characters, the program truncates it to 8 and sends a message indicating the shortened name. Use the built-in functions LENGTH, see page LENGTH, and SUBSTR, see page SUBSTR (Substring).

ANSWER

Figure 28. Possible Solution
/***************************** REXX *********************************/
/*  This program tests the length of a file name.                   */
/*  If the name is longer than 8 characters, the program truncates  */
/*  extra characters and sends a message indicating the shortened   */
/*  name.                                                           */
/********************************************************************/
PULL name                     /* Gets name from input stream        */

IF LENGTH(name) > 8 THEN      /* Name is longer than 8 characters   */
  DO
    name = SUBSTR(name,1,8)   /* Shorten name to first 8 characters */
    SAY 'The name you specified was too long.'
    SAY  name 'will be used.'
  END
ELSE NOP