HP 3000 Manuals

HP COBOL II/XL Reference Manual

STRING Statement 

The STRING statement concatenates the partial or complete contents of two
or more data items into a single data item.

Syntax 


            

Parameters 

literal-1 and           any figurative constant or any nonnumeric literal
literal-2               except ALL; none of them may be numeric literals.

identifier-1 and        described implicitly or explicitly as USAGE
identifier-2            DISPLAY. If any of these identifiers represent an
                        elementary numeric data item, it must be
                        described as an integer without the 'P' symbol in
                        its PICTURE character string.

identifier-3            must represent an alphanumeric data item without
                        editing symbols or JUSTIFIED clause, and must
                        have a USAGE IS DISPLAY (implied or explicit) in
                        its description.  It may not be reference
                        modified.

identifier-4            must represent an elementary numeric integer data
                        item of sufficient size to contain a value equal
                        to the size, plus 1, of the area referenced by
                        identifier-3.  The symbol P must not be used in
                        the PICTURE of identifier-4. 

imperative-statement-1  one or more imperative statements.
and
imperative-statement-2 

Description 

All references to identifier-1, identifier-2, identifier-3, literal-1,
and literal-2 apply equally to identifier-4, respectively, and all
recursions thereof.  Thus, to aid in the description of the STRING
statement, the format is rewritten as follows:


            

First sending items and second sending items represent the groups of
literals and the data items named by the identifiers appearing between
the STRING and DELIMITED keywords, or between a delimiter (or the keyword
SIZE) and the next use of the DELIMITED keyword.  These are the items
that are juxtaposed into identifier-3, the receiving data item.

Delimiter-1 and delimiter-2 indicate the character or characters
delimiting the characters moved from first sending items and second
sending items, respectively.  If the SIZE phrase is used, the complete
group of sending items is moved.

If a figurative constant is used as a delimiter, it stands for single
character numeric literal, whose USAGE is DISPLAY. If a figurative
constant is used for a literal in a group of sending items, it refers to
an implicit one character data item whose USAGE is DISPLAY.

Execution of the STRING Statement 

When the STRING statement executes, the characters in the first sending
items are transferred to the contents of identifier-3 in accordance with
the rules of alphanumeric to alphanumeric moves, except that no space
filling takes place.

If the DELIMITED phrase is specified using delimiter-1, the contents of
the first sending items are moved to the contents of identifier-3 in the
sequence specified in the STRING statement, starting with the leftmost
character and continuing until all character positions of identifier-3 
have been filled, or until the character or characters that make up
delimiter-1 are encountered.  The characters of delimiter-1 are not
transferred.

If delimiter-1 is found in the first sending items before identifier-3 is
filled, the second sending items are processed in the same way as the
first and transferring ceases in the same way, using delimiter-2 rather
than delimiter-1.

If the DELIMITED phrase contains the word SIZE rather than delimiter-1 or
delimiter-2, then either all characters in the sending items are
transferred to identifier-3, or as many characters as possible are
transferred before the end of the data area reserved for identifier-3 has
been reached.

The POINTER phrase is available for you to define the starting position
of identifier-3 to which data is to be moved.  For example, if the phrase
WITH POINTER COUNT is used and the value of COUNT is 10, the first
character transferred from the sending items is placed in the tenth
character position (from the left) of identifier-3.  Not using the
POINTER phrase is equivalent to specifying WITH POINTER 1.

After a character is moved into the data item referenced by identifier-3,
the pointer value is incremented by one.  Thus, the value of identifier-4 
at the end of a STRING statement is equal to its initial value, plus the
number of characters transferred.

If the value of identifier-4 is less than one, or exceeds the number of
character positions in the data item referenced by identifier-3, and
execution of the STRING statement is not complete, an overflow condition
occurs.  At this point, regardless of whether or not any data has already
been moved to the data item referenced by identifier-3, no more data is
moved.

Furthermore, if the ON OVERFLOW statement is specified in the STRING
statement, the imperative statement in the phrase is executed.

If the ON OVERFLOW phrase is not specified when an overflow condition is
encountered, control is transferred to the end of the STRING statement,  
or to the end of the  NOT ON OVERFLOW phrase, if specified. 

At the end of execution of the STRING statement, only the portion of the
data item referenced by identifier-3 that was referenced during the
execution of the STRING statement is changed.  All other portions of the
data item contain the data that was present before this execution of the
STRING statement.

Examples 

     WORKING-STORAGE SECTION.
     01 RECEIVER         PIC X(20)  VALUE SPACES.
     01 SENDER-1         PIC X(5)   VALUE "FIRST".
     01 SENDER-2.
        02  SUB-2A       PIC A(3)   VALUE "ONE".
        02  SUB-2B       PIC 99V99  VALUE ZERO.
     O1 SENDER-A         PIC X(15)  VALUE "ALPHABETICALLY".
     77 CHAR-COUNT       PIC 99     VALUE 1.
     77 LIMITER          PIC X      VALUE "T".
          :
     PROCEDURE DIVISION.
          :
          ADD 1 TO CHAR-COUNT.
          STRING SENDER-1, SPACE, SPACE DELIMITED BY SIZE,
              SUB-2A, SENDER-A DELIMITED BY LIMITER
              INTO RECEIVER WITH POINTER CHAR-COUNT
              ON OVERFLOW DISPLAY "OVERFLOW IN RECEIVER",
              " VALUE OF COUNTER IS ", CHAR-COUNT.
                   :

With the definitions of data names as described in the WORKING-STORAGE
SECTION, and with CHAR-COUNT set to 2, the STRING statement fills
RECEIVER as follows:


            

If the three statements below are used instead, an overflow condition is
caused.

     MOVE SPACES TO RECEIVER.
     MOVE 10 TO CHAR-COUNT
     STRING SENDER-A DELIMITED BY SIZE
           INTO RECEIVER WITH POINTER CHAR-COUNT
           ON OVERFLOW DISPLAY "OVERFLOW IN RECEIVER"
                       DISPLAY "VALUE OF COUNTER IS ", CHAR-COUNT.

The STRING statement now fills RECEIVER as follows:


            

When this overflow occurs, the following message is sent to the terminal
from which the program was initiated:

     OVERFLOW IN RECEIVER
     VALUE OF COUNTER IS 21

MPE/iX 5.0 Documentation