PARSE

See Parsing.

The template_list is often a single template but may be several templates separated by commas. If specified, each template is a list of symbols separated by blanks or patterns or both.

Each template is applied to a single source string. Specifying multiple templates is never a syntax error, but only the PARSE ARG variant can supply more than one non-null source string. See Parsing multiple strings.

If you do not specify a template, no variables are set but action is taken to prepare the data for parsing, if necessary. Thus for PARSE EXTERNAL and PARSE PULL, a data string is removed from the queue, for PARSE LINEIN (and PARSE PULL if the queue is empty), a line is taken from the default input stream, and for PARSE VALUE, expression is evaluated. For PARSE VAR, the specified variable is accessed. If it does not have a value, the NOVALUE condition (if it is enabled) is raised.

If you specify the UPPER option, the data to be parsed is first translated to uppercase (that is, lowercase a-z to uppercase A-Z). Otherwise, no uppercase translation takes place during the parsing.

The following list describes the data for each variant of the PARSE instruction.

PARSE ARG

parses the string or strings passed to a program or internal routine as input arguments. (See ARG for details and examples.)

Note: You can also retrieve or check the argument strings to a REXX program or internal routine with the ARG built-in function (see ARG (Argument).)

PARSE EXTERNAL

This is a non-SAA subkeyword provided in REXX. The next string from the terminal input buffer is parsed. This queue may contain data that is the result of external asynchronous events such as user console input, or messages. If that queue is empty, a console read results. Note that this mechanism should not be used for typical console input, for which PULL is more general, but rather for special applications (such as debugging) where the program stack cannot be disturbed.

PARSE NUMERIC

This is a non-SAA subkeyword provided in REXX. The current numeric controls (as set by the NUMERIC instruction) are available. These controls are in the order DIGITS FUZZ FORM. For example:

Parse Numeric Var1

After this instruction, Var1 would be equal to: 9 0 SCIENTIFIC. See NUMERIC and the built-in functions in DIGITS, FORM, and FUZZ.

PARSE PULL

parses the next string from the external data queue. If the external data queue is empty, PARSE PULL reads a line from the default input stream (the user's terminal), and the program pauses, if necessary, until a line is complete. You can add data to the head or tail of the queue by using the PUSH and QUEUE instructions. You can find the number of lines currently in the queue with the QUEUED built-in function; see QUEUED. Other programs in the system can alter the queue and use it as a means of communication with programs written in REXX. See also the PULL instruction (PULL).

Note: PULL and PARSE PULL read from the program stack. If that is empty, they read from the terminal input buffer; and if that too is empty, they read from the console.

PARSE SOURCE

parses data describing the source of the program running. The language processor returns a string that is fixed (does not change) while the program is running. The PARSE SOURCE instruction returns a source string containing the following tokens:

1. The characters CICS®.
2. The string COMMAND, FUNCTION, or SUBROUTINE depending on whether the program was invoked as a host command, from a function call in an expression, by a CALL instruction, or as a server process.
3. The name of the exec in uppercase. The name of the file (RFS), or MVS partitioned dataset or DDNAME/member from which the exec was originally loaded. The three formats are:
   • DDNAME - member
   • RFS fully qualified file identifier
   • Dataset name (member)
4. Initial (default) host command environment that is always REXXCICS.
5. Identifier of the specific CICS environment, which in this case is CICS TS.

PARSE VALUE

parses the data that is the result of evaluating expression. If you specify no expression, the null string is used. Note that WITH is a subkeyword in this context and cannot be used as a symbol within expression.

Thus, the following example gets the current time and splits it into its constituent parts:

PARSE VALUE time() WITH  hours ':' mins ':' secs

PARSE VAR name

parses the value of the variable name. The name must be a symbol that is valid as a variable name (that is, it cannot start with a period or a digit). The variable name is not changed unless it appears in the template. For example the following instruction removes the first word from string, puts it in the variable word1, and assigns the remainder back to string:

PARSE VAR string word1 string

Similarly, the following example in addition translates the data from string to uppercase before it is parsed.

PARSE UPPER VAR string word1 string

PARSE VERSION

parses information describing the language level and the date of the language processor. This information consists of five words delimited by blanks:

1. The string REXX370, signifying the 370 implementation.
2. The language level description (for example, 3.48).
3. The language processor release date (for example, 05 April 2000).