STRING Statement

The STRING statement concatenates data items.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

STRING { {source} ... [DELIMITED BY {delimiter}] } ...
                      [             {SIZE     }]

     INTO destination

   [ WITH POINTER ptr-var ]

   [ ON OVERFLOW statement-1 ]

   [ NOT ON OVERFLOW statement-2 ]

   [ END-STRING ]

Syntax Rules

  1. Source and delimiter are nonnumeric literals or data items with USAGE DISPLAY. The ALL literal construct may not be used.
  2. The compiler allows source to be a numeric literal, in which case it treats source as a string literal, displaying the following Warning at compilation time: 
    Warning: Literal is numeric - treated as alphanumeric

    In such cases, leading zeros are stripped from the numeric literal to form the string literal.

  3. Destination is a data item with USAGE DISPLAY. It may not be JUSTIFIED or edited, but may be reference modified.
  4. ptr-var is an integer numeric data item.
  5. statement-1 and statement-2 are imperative statements.
  6. The size of ptr-var must allow it to contain a value one greater than the size of destination.
  7. The DELIMITED phrase may be omitted only immediately before the INTO phrase. If omitted, DELIMITED BY SIZE is implied.

General Rules

  1. The STRING statement concatenates the source values and places the result in destination. There are no limitations (other than available memory) on the number of source items allowed.
  2. The STRING statement moves characters from source to destination according to the rules for alphanumeric to alphanumeric moves. However, no space filling occurs.
  3. The contents of each source item are moved to destination in the order they appear. Data is moved from the left, character by character, until the end of source is reached. The end point of each source item is determined by the DELIMITED phrase according to the following rules:
    1. Transfer stops when the end of source is reached.
    2. Transfer stops when the end of destination is reached.
    3. If delimiter is specified, transfer stops when the characters specified by delimiter are found in source. The delimiter is not included in the characters transferred.
    4. If the SIZE option is used, transfer ends only when the end of source or destination is reached.
    5. When source or delimiter is a figurative constant, it represents a size of one character.
    6. If source is a variable size item, the current size is used to determine the end of source. If the current size is zero characters, no transfer occurs for that source item.
  4. When the POINTER phrase is specified, ptr-var must be set by the program to a value greater than zero before the STRING statement executes. The transfer to destination starts at the character position in destination indicated by ptr-var. The leftmost character of destination is position 1. If no POINTER phrase is used, an implied pointer is created and set to the value 1.
  5. ptr-var (or the implied pointer) is incremented by one for each character transferred to destination. The transfer to destination always occurs at the character position indicated by the current pointer value.
  6. When the STRING statement ends, only those parts of destination referenced during execution change.
  7. Before moving each character to destination, the STRING statement tests the value of ptr-var (or the implied pointer if ptr-var is not specified). If this value is less than one or greater than the size of destination, the overflow condition is set and the following happens:
    1. No more data is transferred to destination.
    2. If the ON OVERFLOW phrase is used, statement-1 executes.
    3. The STRING statement ends.
  8. If the NOT ON OVERFLOW phrase is specified, statement-2 executes after the STRING statement is finished if the overflow condition has not occurred (see general rule 7).
  9. Subscripting for source and delimiter occurs just before the corresponding item is used.
  10. Subscripting for ptr-var and destination occurs just before the STRING statement executes.

Code Example

Assume the following data items: 

01  CLAIM-CODE   PIC X(20).  |destination data item,
                             |initialize before use
01  CUSTOMER-ID  PIC X(8).   |source data item
01  ORDER-NO     PIC X(10).  |source data item
01  ORDER-DATE   PIC 9(6).   |source data item
01  STRING-PTR   PIC 99.     |concatenation pointer,
                             |initialize before use

Assume the program assigns the following values before the STRING statement executes: 

CLAIM-CODE  = SPACES
(destination item gets space filled)
CUSTOMER-ID = C077/W12 
(customer number "/" region code)
ORDER-NO    = W12-A00234
(region code "-" order number)
ORDER-DATE  = 060199
(mmddyy)

Use the STRING statement to concantenate: 

STRING ORDER-DATE DELIMITED BY SIZE
       ORDER-NO   DELIMITED BY SIZE
       INTO CLAIM-CODE
END-STRING.
*CLAIM-CODE = "060199W12-A00234    "
*spaces appear at the end of concatenated string
*because CLAIM-CODE was assigned SPACES before the
*STRING concatenation statement executed

Use POINTER to coordinate multiple STRING statements into a common concatenation object. 

SET STRING-PTR TO 1.
MOVE SPACES TO CLAIM-CODE.
STRING ORDER-DATE DELIMITED BY SIZE
    INTO CLAIM-CODE
    POINTER STRING-PTR
END-STRING.
*CLAIM-CODE now contains: "060199"
*Reassign the value of STRING-PTR so as to 
*eliminate the year digits by overwriting 
*positions 5 & 6 in the destination string
SUBTRACT 2 FROM STRING-PTR.
...
*build the remainder of the string
*start by adding a hyphen delimiter,
*add all characters before "/" in CUSTOMER-ID
*add another hyphen delimiter
*add all of ORDER-NO
STRING "-",
       CUSTOMER-ID DELIMITED BY "/",
       "-",
       ORDER-NO    DELIMITED BY SIZE
   INTO CLAIM-CODE
   POINTER STRING-PTR
   ON OVERFLOW
      DISPLAY "Claim-Code OVERFLOW"
   NOT ON OVERFLOW
      PERFORM PROCESS-CLAIM-CODE
END-STRING.
*CLAIM-CODE = "0601-C077-W12-A00234"

Highlights for First-time Users

  1. A clear, concise description of the concatenation transfer process is contained in entry 3 of the preceding General Rules section.
  2. Use DELIMITED BY to concatenate a portion of the source item up to, but not including, the delimiter. The delimiter may be a single character or a string.
  3. Use OVERFLOW to do special processing in the event that the size of the concatenation overflows the destination data item. The OVERFLOW phrase should always be included when an overflow condition is possible.
  4. Use NOT ON OVERFLOW to do special processing in the event that the concatenation succeeds (does not result in an overflow).
  5. Use POINTER to place data into a common destination when concatenation requires multiple STRING statements. See code example 2, above.
  6. The STRING statement does not space fill the target data item. You must initialize the destination data item. For example: 
    01 CLAIM-CODE  PIC X(20)  VALUE ALL SPACES.
Parent topic: Procedure Division Statements