PARSE

Purpose

Read syntax diagramSkip visual syntax diagram
>>-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 page 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 az to uppercase AZ). 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 the ARG instruction on page 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 page ARG (Argument)). function.
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 page Purpose) are available. These controls are in the order DIGITS FUZZ FORM.
Example:
Parse Numeric Var1
After this instruction, Var1 would be equal to: 9 0 SCIENTIFIC. See section NUMERIC and the built-in functions in section DIGITS, and section FORM, and section 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 page 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 on page 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, on page Purpose, 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:
  1. The characters CICS.
  2. 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.
  3. 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)
  4. Initial (default) host command environment that is always REXXCICS.
  5. 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:
PARSE VALUE time() WITH  hours ':' mins ':' secs
gets the current time and splits it into its constituent parts.
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:
PARSE VAR string word1 string
removes the first word from string, puts it in the variable word1, and assigns the remainder back to string. Similarly
PARSE UPPER VAR string word1 string
in addition translates the data from string to uppercase before it is parsed.
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).

Reference Reference

Feedback


Timestamp icon Last updated: Tuesday, 7 January 2014


http://pic.dhe.ibm.com/infocenter/cicsts/v5r1/topic/com.ibm.cics.rexx.doc//dfhrx/dfhrxal.html