1. STRING

The STRING statement creates a single data item by combining the partial or complete contents of multiple data item or literals. A single STRING statement can be used instead of using multiple MOVE statements.

figure pd string
STRING Statement Format

The following items are specified in the statement.

  • identifier-1, literal-1

    • Specifies the source data field. It must be a data item that is explicitly or implicitly specified as usage DISPLAY or usage DISPLAY-1. It can be a special register of alphanumeric type.

    • literal-1 must be alphanumeric. Any figurative constant except NULL that does not begin with the word ALL can be specified. Each figurative constant is regarded as a one-character alphanumeric literal.

  • DELIMITED BY phrase

    • Specifies the delimiter used to establish the limits of the string.

    • Sets the following items.

      Item Description

      identifier-2, literal-2

      The delimiter used to establish the limits of the string.

      Used to delimit the data to be moved. If SIZE is specified, all data items specified in identifier-1 or literal-1 are moved.

      If a figurative constant except ALL is specified, it is represented as a one-byte string. literal-2 must be alphanumeric.

      SIZE

      Indicates that the complete string is specified.

  • INTO phrase

    • Specifies the destination field.

    • Sets the following item.

      Item Description

      identifier-3

      Represents the destination string. Specifies a data item where the last created string will be included. The JUSTIFIED clause cannot be specified.

      If identifier-3 is usage DISPLAY, identifier-1 and identifier-2 are usage DISPLAY, and all literals must be alphanumeric literals. Any figurative constant except for ALL can be specified. A figurative constant is treated as an alphanumeric literal with 1 character.

      If identifier-3 is usage DISPLAY-1, identifier-1 and identifier-2 must be usage DISPLAY-1 and all literals must be DBCS literals. Only figurative constant that can be specified is SPACE.

  • WITH POINTER phrase

    • Indicates the length of a string in the data field that contains result data. The POINTER field is the length of a relative string when the source string’s usage is DISPLAY or DISPLAY-1.

    • The POINTER field specifies a data field of sufficient size that can contain a value equal to the length of the result data plus 1.

    • Sets the following item.

      Item Description

      identifier-4

      Specifies the pointer field. If specified, the programmer can explicitly use it, and a proper initial value needs to be specified.

      The initial value of identifier-4 must be a positive integer.

All items except for identifier-4 must be either usage DISPLAY or usage DISPLAY-1.

If identifier-1 or identifier-2 references a numeric category data item, each numeric item must be described as an integer that does not specify the symbol P in its PICTURE string.

If identifier-1 or identifier-2 references an elementary data of the usage DISPLAY and of the category numeric, numeric-edited, or alphanumeric-edited item, it is treated as an alphanumeric item.

Evaluation of subscript, reference modification, variable-length, function identifier, etc. is performed at the start of the STRING statement execution.

  • ON OVERFLOW phrase

    • An overflow occurs in the following cases.

      • The value of the pointer field is less than 1.

      • The value of the pointer field is greater than the entered data field.

        If an overflow occurs, data is no longer moved. When an overflow occurs, control is transferred to the command that was specified with ON OVERFLOW.

    • If the command that explicitly transfers control is executed, control is passed according to the rules for the command. Otherwise, the end of the STRING statement is executed after the execution of the command is completed.

    • If an overflow condition did not occur when the STRING statement was executed, ON OVERFLOW is ignored. Control is passed to the end of the STRING statement, or to the command in NOT ON OVERFLOW, if it is specified.

    • Sets the following item.

      Item Description

      imperative-statement-1

      Specifies a statement to be executed when an overflow condition occurs.

  • END-STRING phrase

    • Explicitly indicates the end of the STRING statement.

    • The END-STRING phrase can be used to nest a STRING statement as a conditional expression in another conditional statement.

Data Flow

The STRING statement transmits characters from the source fields to the target field that contains the final result. The source fields are processed in the order they are specified in the STRING statement.

The following rules apply.

  • Characters are transferred from the source fields to the receiving field in the following ways.

    • For a two-byte character, the rules of the MOVE statement between two-byte characters are applied.

    • For other characters, the rules of the MOVE statements for elementary moves between alphanumeric characters are applied.

  • If DELIMITED BY identifier-2 or literal-2 is specified, each character in each source field is moved, beginning from the leftmost character, until one of the following things occurs.

    • A delimiter for the source field is encountered. The delimiter itself is not moved.

    • The rightmost character in the source field has been moved.

  • If DELIMITED BY SIZE is specified, each entire source field is moved.

  • If the receiving field is filled, or all the source fields have been processed, the data transfer operation is completed.

  • If the POINTER phrase is specified, the user must explicitly set the pointer value of the source field.

If data processing is completed in the STRING statement, only the part of the target field into which data is moved is modified. The remaining unmodified part of the target field still contains the data that was stored before executing the STRING statement.