Rational Developer for System z
COBOL for Windows, Version 7.5, Language Reference


UNSTRING statement

The UNSTRING statement causes contiguous data in a sending field to be separated and placed into multiple receiving fields.

Format
Read syntax diagramSkip visual syntax diagram>>-UNSTRING--identifier-1--------------------------------------->
 
>--+-------------------------------------------------------------------------------------+-->
   '-DELIMITED--+----+--+-----+--+-identifier-2-+--+-----------------------------------+-'  
                '-BY-'  '-ALL-'  '-literal-1----'  | .-------------------------------. |    
                                                   | V                               | |    
                                                   '---OR--+-----+--+-identifier-3-+-+-'    
                                                           '-ALL-'  '-literal-2----'        
 
>--INTO--------------------------------------------------------->
 
   .------------------------------------------------------------------------------------.  
   V                                                                                    |  
>----identifier-4--+---------------------------------+--+-----------------------------+-+-->
                   '-DELIMITER--+----+--identifier-5-'  '-COUNT--+----+--identifier-6-'    
                                '-IN-'                           '-IN-'                    
 
>--+---------------------------------+-------------------------->
   '-+------+--POINTER--identifier-7-'  
     '-WITH-'                           
 
>--+--------------------------------+--------------------------->
   '-TALLYING--+----+--identifier-8-'  
               '-IN-'                  
 
>--+------------------------------------------+----------------->
   '-+----+--OVERFLOW--imperative-statement-1-'  
     '-ON-'                                      
 
>--+-----------------------------------------------+------------>
   '-NOT--+----+--OVERFLOW--imperative-statement-2-'  
          '-ON-'                                      
 
>--+--------------+--------------------------------------------><
   '-END-UNSTRING-'  
 
identifier-1
Represents the sending field. Data is transferred from this field to the data receiving fields (identifier-4).

identifier-1 must reference a data item of category alphabetic, alphanumeric, alphanumeric-edited, DBCS, national, or national-edited.

identifier-2, literal-1, identifier-3, literal-2
Specifies one or more delimiters.

identifier-2 and identifier-3 must reference data items of category alphabetic, alphanumeric, alphanumeric-edited, DBCS, national, or national-edited.

literal-1 or literal-2 must be of category alphanumeric, DBCS, or national and must not be a figurative constant that begins with the word ALL.

identifier-4
Specifies one or more receiving fields.

identifier-4 must reference a data item of category alphabetic, alphanumeric, numeric, DBCS, or national. If the referenced data item is of category numeric, its picture character-string must not contain the picture symbol P, and its usage must be DISPLAY or NATIONAL.

identifier-5
Specifies a field to receive the delimiter associated with identifier-4.

Identifier-5 must reference a data item of category alphabetic, alphanumeric, DBCS, or national.

identifier-6
Specifies a field to hold the count of characters that are transferred to identifier-4.

identifier-6 must be an integer data item defined without the symbol P in its PICTURE character-string.

identifier-7
Specifies a field to hold a relative character position during UNSTRING processing.

identifier-7 must be an integer data item defined without the symbol P in the PICTURE string.

identifier-7 must be described as a data item of sufficient size to contain a value equal to 1 plus the number of character positions in the data item referenced by identifier-1.
identifier-8
Specifies a field that is incremented by the number of delimited fields processed.

identifier-8 must be an integer data item defined without the symbol P in its PICTURE character-string.

The following rules apply

Count fields (identifier-6) and pointer fields (identifier-7) are incremented by number of character positions (alphanumeric, DBCS, or national), not by number of bytes.

One UNSTRING statement can take the place of a series of MOVE statements, except that evaluation or calculation of certain elements is performed only once, at the beginning of the execution of the UNSTRING statement. For more information, see Values at the end of execution of the UNSTRING statement.

The rules for moving are the same as those for a MOVE statement for an elementary sending item of the category of identifier-1, with the appropriate identifier-4 as the receiving item (see MOVE statement). For example, rules for moving a DBCS item are used when identifier-1 is a DBCS item.

DELIMITED BY phrase

This phrase specifies delimiters within the data that control the data transfer.

Each identifier-2, identifier-3, literal-1, or literal-2 represents one delimiter.

If the DELIMITED BY phrase is not specified, the DELIMITER IN and COUNT IN phrases must not be specified.

ALL
Multiple contiguous occurrences of any delimiters are treated as if there were only one occurrence; this one occurrence is moved to the delimiter receiving field (identifier-5), if specified. The delimiting characters in the sending field are treated as an elementary item of the same usage and category as identifier-1 and are moved into the current delimiter receiving field according to the rules of the MOVE statement.

When DELIMITED BY ALL is not specified, and two or more contiguous occurrences of any delimiter are encountered, the current data receiving field (identifier-4) is filled with spaces or zeros, according to the description of the data receiving field.

Delimiter with two or more characters

A delimiter that contains two or more characters is recognized as a delimiter only if the delimiting characters are both of the following:

Two or more delimiters

When two or more delimiters are specified, an OR condition exists, and each nonoverlapping occurrence of any one of the delimiters is recognized in the sending field in the sequence specified.

For example:

DELIMITED BY “AB” or “BC”

An occurrence of either AB or BC in the sending field is considered a delimiter. An occurrence of ABC is considered an occurrence of AB.

INTO phrase

This phrase specifies the fields where the data is to be moved.

identifier-4 represents the data receiving fields.

DELIMITER IN
This phrase specifies the fields where the delimiters are to be moved.

identifier-5 represents the delimiter receiving fields.

The DELIMITER IN phrase must not be specified if the DELIMITED BY phrase is not specified.

COUNT IN
This phrase specifies the field where the count of examined character positions is held.

identifier-6 is the data count field for each data transfer. Each field holds the count of examined character positions in the sending field, terminated by the delimiters or the end of the sending field, for the move to this receiving field. The delimiters are not included in this count.

The COUNT IN phrase must not be specified if the DELIMITED BY phrase is not specified.

POINTER phrase

When the POINTER phrase is specified, the value of the pointer field, identifier-7, behaves as if it were increased by 1 for each examined character position in the sending field. When execution of the UNSTRING statement is completed, the pointer field contains a value equal to its initial value plus the number of character positions examined in the sending field.

When this phrase is specified, the user must initialize the pointer field before execution of the UNSTRING statement begins.

TALLYING IN phrase

When the TALLYING phrase is specified, the area count field, identifier-8, contains (at the end of execution of the UNSTRING statement) a value equal to the initial value plus the number of data receiving areas acted upon.

When this phrase is specified, the user must initialize the area count field before execution of the UNSTRING statement begins.

ON OVERFLOW phrases

An overflow condition exists when:

When an overflow condition occurs

An overflow condition results in the following actions:

  1. No more data is transferred.
  2. The UNSTRING operation is terminated.
  3. The NOT ON OVERFLOW phrase, if specified, is ignored.
  4. Control is transferred to the end of the UNSTRING statement or, if the ON OVERFLOW phrase is specified, to imperative-statement-1.
imperative-statement-1
Statement or statements for dealing with an overflow condition.

If control is transferred to imperative-statement-1, execution continues according to the rules for each statement specified in imperative- statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred according to the rules for that statement. Otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the UNSTRING statement.

When an overflow condition does not occur

When, during execution of an UNSTRING statement, conditions that would cause an overflow condition are not encountered, then:

  1. The transfer of data is completed.
  2. The ON OVERFLOW phrase, if specified, is ignored.
  3. Control is transferred to the end of the UNSTRING statement or, if the NOT ON OVERFLOW phrase is specified, to imperative-statement-2.
imperative-statement-2
Statement or statements for dealing with an overflow condition that does not occur.

If control is transferred to imperative-statement-2, execution continues according to the rules for each statement specified in imperative- statement-2. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred according to the rules for that statement. Otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the UNSTRING statement.

 

END-UNSTRING phrase

This explicit scope terminator serves to delimit the scope of the UNSTRING statement. END-UNSTRING permits a conditional UNSTRING statement to be nested in another conditional statement. END-UNSTRING can also be used with an imperative UNSTRING statement.

For more information, see Delimited scope statements.

Data flow

When the UNSTRING statement is initiated, data is transferred from the sending field to the current data receiving field, according to the following rules:

Stage 1: Examine

  1. If the POINTER phrase is specified, the field is examined, beginning at the relative character position specified by the value in the pointer field.

    If the POINTER phrase is not specified, the sending field character-string is examined, beginning with the leftmost character position.

  2. If the DELIMITED BY phrase is specified, the examination proceeds from left to right, examining character positions one-by-one until a delimiter is encountered. If the end of the sending field is reached before a delimiter is found, the examination ends with the last character position in the sending field. If there are more receiving fields, the next one is selected; otherwise, an overflow condition occurs.

    If the DELIMITED BY phrase is not specified, the number of character positions examined is equal to the size of the current data receiving field, which depends on its data category, as shown in Treatment of the content of data items (Table 41).

    Table 54. Character positions examined when DELIMITED BY is not specified
    If the receiving field is ... The number of character positions examined is ...
    Alphanumeric or alphabetic Equal to the number of alphanumeric character positions in the current receiving field
    DBCS Equal to the number of DBCS character positions in the current receiving field
    National Equal to the number of national character positions in the current receiving field
    Numeric Equal to the number of character positions in the integer portion of the current receiving field
    Described with the SIGN IS SEPARATE clause 1 less than the size of the current receiving field
    Described as a variable-length data item Determined by the size of the current receiving field at the beginning of the UNSTRING operation

    Stage 2: Move

  3. The examined character positions (excluding any delimiter characters) are treated as an elementary data item of the same data category as the sending field except for the cases shown in the table below.
    Category of identifier-1 (sending-field) Category of elementary data item
    Alphanumeric-edited Alphanumeric
    National-edited National
    That elementary data item is moved to the current data receiving field according to the rules for the MOVE statement for the categories of the sending and receiving fields as described in MOVE statement.
  4. If the DELIMITER IN phrase is specified, the delimiting characters in the sending field are treated as an elementary alphanumeric item and are moved to the current delimiter receiving field, according to the rules for the MOVE statement. If the delimiting condition is the end of the sending field, the current delimiter receiving field is filled with spaces.
  5. If the COUNT IN phrase is specified, a value equal to the number of examined character positions (excluding any delimiters) is moved into the data count field, according to the rules for an elementary move.

    Stage 3: Successive iterations

  6. If the DELIMITED BY phrase is specified, the sending field is further examined, beginning with the first character position to the right of the delimiter.

    If the DELIMITED BY phrase is not specified, the sending field is further examined, beginning with the first character position to the right of the last character position examined.

  7. For each succeeding data receiving field, this process of examining and moving is repeated until either of the following occurs:

Values at the end of execution of the UNSTRING statement

The following operations are performed only once, at the beginning of the execution of the UNSTRING statement:

Therefore, if identifier-4, identifier-5, identifier-6, identifier-7, or identifier-8 is used as a subscript, reference-modifier, or function argument in the UNSTRING statement, or affects the length or location of any of the identifiers in the UNSTRING statement, these values are determined at the beginning of the UNSTRING statement, and are not affected by any results of the UNSTRING statement.

Example of the UNSTRING statement

The following figure shows the execution results for an example of the UNSTRING statement.

Begin figure description. This figure shows an UNSTRING statement example. End figure description.

Link to more detail.

Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)