|
|
|
Provides generalized parsing functions for tokenizing data into variables.
&PARSE [ { DELIM={ c | 'cccccccc' | ”cccccccc” } | SEGMENT } ]
{ VARS=name | VARS=( name, name1, ..., namen ) |
VARS=prefix* [ RANGE=( start, end ) ] |
ARGS [ RANGE=( start, end ) ] }
[ REMSTR=varname ]
[ OPT={ option | ( option, ..., option ) } ]
[ INPUT={ CHAR | HEX | HEXEXP } ]
[ DATA=text ]
&PARSE is a verb that allows a data string to be split into sections identified by delimiters or segmented according to length. Each section is placed into a separate target variable. On completion of &PARSE, the system variable &ZVARCNT is set to the number of variables created or modified by the operation.
Operands:
Specifies the delimiter character or a series of individual delimiter characters that will be used as the argument for the parsing process. Every occurrence of a DELIM character in the DATA string that is being parsed represents the end of a section of the data. The section, minus the delimiter character, is placed in the next target variable and the parsing process continues. Special case processing takes place when a blank is detected as the only delimiter character (see Notes following the examples).
If DELIM is omitted the default delimiter character is a blank.
The delimiter series may be 1 to 8 characters long. Series of 2 or more characters must be enclosed in single or double quotes.
Specifies that there is no delimiter character but that the parsed string will be placed into the receiving variables in segments that correspond to the length of the individual variables. The length defaults to the maximum variable length unless overridden by length specifications in a variable list.
Specifies the target variables that are to be assigned the parsed sections of the DATA. The format of the VARS operands may be:
The name of a variable, excluding the ampersand (&).
As name, but n denotes the length of the data to be placed in the variable. If necessary, the data is truncated.
Denotes a skip operation, where n represents the number of units to be skipped during the tokenization process. On VARS= statements, n denotes 'skip this number of words'. An asterisk (*) by itself is the same as *(1).
If SEGMENT is specified, then n denotes 'skip this number of characters'. An asterisk (*) by itself is the same as *(1).
Denotes that variables are generated automatically during the parsing process, and that variable names will be prefix1 .. prefix2, and so on. The RANGE= operand is specified to indicate a starting and ending suffix number. prefix* cannot be used with other variable names.
Specifies that &1 through &n are the variables to be assigned the parsed sections of data. The RANGE= operand may be coded to designate start and end numbers to delimit the number of variables generated.
Nominates a variable that is to be assigned the remainder of the DATA string that is being parsed if insufficient target variables are specified to hold the entire parsed string. This option is mutually exclusive with the SEGMENT operand.
Specifies one or more additional options that are to apply to the results of the &PARSE statement. Supported options are:
Which specifies that leading and trailing blanks are to be preserved when text is assigned into the target variables. If ASIS is not specified, then leading and trailing blanks are stripped from the parsed string sections as they are placed in the target variables.
Specifies the action to be taken if two consecutive delimiters are found within the DATA being parsed or if the data starts with a delimiter. In this case there is an implied null section, that is, a section of zero length. If NONULLS is specified, then the zero length section is ignored and no null variable is created. If NONULLS is omitted, then a null variable is created.
Describes the expected data input and mode of processing. The default of character mode should be used for standard character data. HEX and HEXEXP should be used when the input contains non-character hexadecimal data. HEXEXP indicates that the hexadecimal data be expanded into display characters in the resulting target variables.
The string of data that is to be parsed. The string may be present in one or more variables or may be coded explicitly.
DATA= must be specified as the last keyword on the statement since the data string is regarded as being everything to the right of the DATA= keyword to the end of the statement.
Examples: &PARSE
&PARSE DELIM=, ARGS OPT=ASIS DATA=123, 456,789
results in:
&1 = 123 &2 = 456 &3 = 789
&PARSE DELIM=':,' VARS=(A,B,C,D) REMSTR=REST +
DATA=aaa:bbb, ,ccc,ddd:eee
results in:
&A = aaa &B = bbb &C = -* null value &D = ccc &REST = ddd:eee
&PARSE DELIM=',:' VARS=(A,B,C,D) REMSTR=REST +
OPT=NONULLS DATA=aaa:bbb, ,ccc,ddd:eee
results in:
&A = aaa &B = bbb &C = ccc &D = ddd &REST = eee
&PARSE ARGS DATA=this is a variable msg.
results in:
&1 = this &2 = is &3 = a &4 = variable &5 = msg.
&INPUT=AABBBCCCCCCC &PARSE SEGMENT VARS=(A(2),B(3),C) DATA=&INPUT
results in:
&A = AA &B = BBB &C = CCCCCCC
Notes:
The parse process proceeds from left to right through the data, until either all data has been parsed or all target variables have been assigned a value. Where data remains to be parsed it may be optionally assigned to a variable as specified by the REMSTR operand.
Characters recognized as delimiter characters are never included in the result variables. The only exception is a variable nominated in the REMSTR operand.
Where blank has been specified, or has defaulted, as a delimiter, it is never recognized as a delimiter when found following a recognized delimiter. Additionally, once this condition has occurred, a blank is not recognized as a delimiter until a non-blank, non-delimiter character is next encountered.
If OPT=ASIS was not specified and a segment has been isolated which contains only blanks, a null value is assigned to the corresponding target variable, unless OPT=NONULLS has been specified.
| Copyright © 2009 CA. All rights reserved. |
|