The UNSTRING statement causes contiguous data in a sending field to be separated and placed into multiple receiving fields. UNSTRING statement does the task of several MOVE statements. UNSTRING used to separate single string into multiple based on the delimiter provided.

UNSTRING requires minimum two receiving fields to separate sending field data. UNSTRING statement only separates alphabetic and alpha-numeric items. UNSTRING statement can’t separate numeric and floating-point items. UNSTRING allows SPACE only from figurative constants.

DELIMITED BY, TALLYING, WITH POINTER, ON OVERFLOW and NOT ON OVERFLOW clauses is optional in UNSTRING. END-UNSTRING used as a scope terminator for UNSTRING statement.

Syntax -

UNSTRING Syntax

identifier-1 -

Specifies the sending field. Data is transferred from this field to the data receiving fields. identifier-1 must reference a data item of category alphabetic, alphanumeric or alphanumeric-edited.

identifier-2, literal-1, identifier-3, literal-2 -

Specifies one or more delimiters. identifier-2 and identifier-3 must be data items of category alphabetic, alphanumeric or alphanumeric-edited. literal-1 or literal-2 must be of category alphanumeric and must not be a figurative constant that begins with the word ALL.

identifier-4 -

Specifies one or more receiving fields. identifier-4 must be a data item of category alphabetic, alphanumeric or numeric. If the data item is numeric, its picture character-string must not contain the picture symbol P and its usage must be DISPLAY.

identifier-5 -

Specifies a field to receive the delimiter associated with identifier-4. identifier-5 must be a data item of category alphabetic or alphanumeric.

identifier-6 -

Specifies a field to hold the count of characters 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 a numeric data item defined without the symbol P in the PICTURE string.

identifier-7 must be a data item of enough 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 a numeric data item defined without the symbol P in its PICTURE character-string.

None of the identifiers in an UNSTRING statement can be date fields. Count fields (identifier-6) and pointer fields (identifier-7) are incremented by number of character positions (alphanumeric) 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.

DELIMITED BY phrase -

Specifies delimiters within the data that used to separate the data. 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 -

If DELIMITED BY ALL is specified, multiple occurrences of any delimiters are treated as one occurrence and is moved to the receiving field (identifier-5) if specified.

The delimiting characters in the sending field are treated as an elementary item 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 receiving field (identifier-4) is filled with spaces or zeros according to the definition of the receiving field.

A delimiter contains two or more characters is recognized as a delimiter only if the characters are contiguous and in sequence.

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 "MT" OR "TH" . An occurrence of either MT or TH in the sending field is considered a delimiter. An occurrence of MTH is considered an occurrence of AB.

INTO phrase -

Specifies the receiving fields along with it. identifier-4 represents the data receiving fields.

DELIMITER IN -

Specifies the receiving fields for the delimiters. identifier-5 represents the delimiter receiving fields. The DELIMITER IN phrase should not be specified if the DELIMITED BY phrase is not specified.

COUNT IN -

Specifies the field where the count to be stored. identifier-6 is the data count field for each data transfer. Each field holds the count of examined character positions in the sending field that are terminated by the delimiters or the end of the sending field. The delimiters are not included in the count. The COUNT IN phrase should not be specified if the DELIMITED BY phrase is not specified.

POINTER phrase -

POINTER option is used to points the next character of delimiter item in the source data item. When the POINTER phrase is specified, the pointer field value 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 POINTER phrase is specified, the user must initialize the pointer field before execution of the UNSTRING statement.

TALLYING IN phrase -

TALLYING clause holds the count of destination strings affected by UNSTRING. When the TALLYING phrase is specified, the area count field contains value equal to the initial value plus the number of receiving areas.

When TALLYING 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 -

  • The pointer value (explicit or implicit) is less than 1.
  • The pointer value (explicit or implicit) exceeds a value equal to the length of the sending field.
  • All receiving fields have been full of examined characters but the sending field still contains unexamined characters.

When an overflow condition occurs, the below actions might occur -

  • No more data is transferred.
  • The UNSTRING operation is terminated.
  • The NOT ON OVERFLOW phrase is ignored if specified.
  • 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 -

Specifies the statement or statements for dealing with an overflow condition. Upon completion of the execution of imperative-statement-1, control is transferred to the end of the UNSTRING statement.

NOT ON OVERFLOW phrase -

When during execution of an UNSTRING statement, if the overflow is not occurred then -

  • The transfer of data is completed.
  • The ON OVERFLOW phrase is ignored.
  • Control is transferred to the end of the UNSTRING statement or to imperative-statement-2 if the NOT ON OVERFLOW phrase is specified.

imperative-statement-2 -

Statement or statements for dealing with an overflow condition that does not occur. Upon completion of the execution of imperative-statement-2, control is transferred to the end of the UNSTRING statement.

END-UNSTRING phrase -

The END-UNSTRING used to end the scope of the UNSTRING statement. END-UNSTRING is not required when UNSTRING statement ended with period. END-UNSTRING can also be used with an imperative UNSTRING statement. END-UNSTRING permits conditional UNSTRING to be nested in another conditional statement.

Practical Example:

Below program shows the UNSTRING coding in the COBOL program.

Code:


IDENTIFICATION DIVISION.                                       
PROGRAM-ID. UNSTRFUN.                                           
ENVIRONMENT DIVISION.                                           
DATA DIVISION.                                                  
WORKING-STORAGE SECTION.                                        
01 WS-DATA		PIC X(70)                              
VALUE ‘MAINFRAMESTECHHELP, IS A MAINFRAME COMMUNITY'.          
01 WS-OUTPUT-DATA1       PIC X(20).                             
01 WS-OUTPUT-DATA2       PIC X(50).                             
PROCEDURE DIVISION.                                             
    DISPLAY 'UNSTRING EXAMPLE....'.                             
    UNSTRING WS-DATA DELIMITED BY ","                          
      INTO  WS-OUTPUT-DATA1,  WS-OUTPUT-DATA2                   
      ON OVERFLOW DISPLAY "ERROR OCCURED"                       
      NOT ON OVERFLOW DISPLAY "NO ERROR".                       
    DISPLAY 'DATA1 AFTER UNSTRING FUNCTION : ' WS-OUTPUT-DATA1. 
    DISPLAY 'DATA2 AFTER UNSTRING FUNCTION : ' WS-OUTPUT-DATA1. 
    STOP RUN.