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
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. |
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. |
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 and SUBSTR.
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