Built-In functions

More than 50 functions are built into the language processor.

The built-in functions fall into the following categories:

Arithmetic functions: Evaluate numbers from the argument and return a particular value.
Comparison functions: Compare numbers, or strings, or both and return a value.
Conversion functions: Convert one type of data representation to another type of data representation.
Formatting functions: Manipulate the characters and spacing in strings supplied in the argument.
String manipulating functions: Analyze a string supplied in the argument (or a variable representing a string) and return a particular value.
Other functions: Do not clearly fit into any of the other 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

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.

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

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.

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

Other 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.

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

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 in Comparison operators , 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 function and SUBSTR (Substring) function.

ANSWER

Figure 1. 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