PARSE

The PARSE instruction separates a character string variable into other variables, based on a specified range. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

source

Required. A previously defined Character String Variable that is moved to the {dest} operand.

sep

Required. A comma or one of the following prepositions: BY, TO, OF, FROM, USING, WITH, IN, or INTO.

dest

Required. A previously defined Character String Variable that receives the {source} operand.

range

Required. A previously defined Character String Variable or Literal defining the range of {source} characters allowed.

keywords

Optional. Keywords defined below that determine how the transfer is handled.

Flags Affected: EOS, LESS, OVER, ZERO

Note the following:

1. The transfer process is exactly like a MOVE character string to character string once any {source} string matching the specified {range} of characters has been identified.

2. If {source} is a Null String, {dest} is not changed.

3. Leading blanks (or spaces) in the {source} string are bypassed unless the NOSKIP keyword {option} is specified.

4. String evaluation for transfer begins at the current Form Pointed character and terminates at the first invalid character or the end of the {source} Logical String whichever occurs first.

5. Upon completion of the transfer, the {source} Form Pointer is set to the last character transferred (if the end of the matching {source} string is found) or to the invalid character that caused the transfer to terminate.

6. Transfer into the {dest} operand begins with the first physical character. However, how the transfer is treated when the {source} is larger than the {dest} depends on the keyword {option} in effect. If the TRUNCATE keyword is given, only those bytes that fit are transferred. If the TRUNCATE keyword is not given (the default), those characters that fit are transferred. The last character of the matching {source} string over stores the last character of the {dest} physical string that was received.

7. Once the transfer is complete, the {dest} Form Pointer is set to one (1) and the Length Pointer is set to the last character transferred. If BLANKFILL is specified, any remaining bytes in the {dest} variable are blank filled and the Length Pointer is set to the Physical Length.

8. Invalid characters are characters that do not fall within the specified {range}.

9. The valid {range} is specified as pairs of values representing a limit that is transferred, e.g.:
   
   RANGE      INIT      "AZ09::"
   
   In this example, the valid range would be any uppercase alpha characters (A through Z), the decimal numbers (0 through 9), and a colon (:). Any character outside this range is invalid and would terminate the transfer. NOTE: If the number sign '#' is used in a literal then two number signs are required, since the number sign is the literal Forcing Character. To specify a single character range, {range} should include the character as both the beginning and ending values (i.e., "AZaz09..::\\").

10. {keywords} are optional, are separated by commas and operate as follows:

 

Keyword	Specifies ...
TRUNCATE	how the transfer is handled if the {dest} variable is smaller than the matching {source} string. Normally, if a 10 byte matching {source} string is transferred into an 8 byte {dest} variable, the first 7 bytes and the last (10th) byte would be transferred. If TRUNCATE is specified, only the first 8 bytes would be transferred.
UPPERCASE	that any lower case alpha characters coming from the {source} are converted to upper case before being transferred to the {dest} variable. This keyword does not affect the matching criteria, only the data transferred.
BLANKFILL	that once the matching data has been transferred into the {dest} variable, all trailing bytes in the receiving variable, through the Physical Length, are filled with spaces. Normally, the {dest} variable's Length Pointer is set to the last character transferred and the remaining bytes remain unchanged. With this keyword, the remaining positions are blank filled and the Length Pointer is set to the Physical Length of the destination variable.
NOSKIP	how leading spaces from the matching {source} string are treated. Normally, leading spaces in data transferred to the {dest} field are discarded. This keyword does not skip any leading spaces in the data and handles them according the given range of characters.

 

11. The EOS Condition Flag is set if the {source} string is null or blank filled.

12. The EQUAL Condition Flag is set if characters are transferred.

13. The LESS Condition Flag is set if the end of the {source} Logical String is reached before encountering an invalid character.

14. If the {dest} string is too small to contain all bytes transferred, the OVER Condition Flag is set.

See Also: Example Code, UNPACK, Character String Instructions