PARSE
Purpose
>>-PARSE--+-------+--+-ARG-------------------------+------------> '-UPPER-' +-EXTERNAL--------------------+ +-LINEIN----------------------+ +-NUMERIC---------------------+ +-PULL------------------------+ +-SOURCE----------------------+ +-VALUE--+------------+--WITH-+ | '-expression-' | +-VAR--name-------------------+ '-VERSION---------------------' >--+---------------+--;---------------------------------------->< '-template_list-'
PARSE assigns data (from various sources) to one or more variables according to the rules of parsing. (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 for information on parsing multiple source 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/CICS. 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 LINEIN
- This is the same as PARSE EXTERNAL.
- PARSE NUMERIC
- This is a non-SAA subkeyword provided in VM. The current numeric controls (as set by the NUMERIC instruction, see Purpose) are available. These controls are in the order DIGITS FUZZ FORM.
- 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. (See the PULL instruction (PULL) for further details.)
- 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. It returns
a source string containing the following tokens:
- The characters CICS.
- The string COMMAND, FUNCTION, or SUBROUTINE depending on whether the program was invoked as some kind of host command, from a function call in an expression, by a CALL instruction, or as a server process.
- The name of the exec in uppercase. The name of the file (RFS),
or VSE Librarian Sublibrary from which the exec was originally loaded.
The three formats are:
- Library.sublibrary(member)
- RFS fully qualified file identifier
- Dataset name (member)
- Initial (default) host command environment that is always REXXCICS.
- Identifier of the specific CICS/ESA environment, which in this case is REXX/CICS.
- 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, for 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). Note that the variable name is
not changed unless it appears in the template, so that for example:
removes the first word from string, puts it in the variable word1, and assigns the remainder back to string. SimilarlyPARSE VAR string word1 string
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:
- The string REXX370, signifying the 370 implementation.
- The language level description (for example, 3.48).
- The language processor release date (for example, 05 April 2000).
