| Free-Form Syntax | (not allowed - use the + operator) |
| Code | Factor 1 | Factor 2 | Result Field | Indicators | ||
|---|---|---|---|---|---|---|
| CAT (P) | Source string 1 | Source string 2: number of blanks | Target string | |||
The CAT operation concatenates the string specified in factor 2 to the end of the string specified in factor 1 and places it in the result field. The source and target strings must all be of the same type, either all character, all graphic, or all UCS-2. If no factor 1 is specified, factor 2 is concatenated to the end of the result field string.
Factor 1 can contain a string, which can be one of: a field name, array element, named constant, data structure name, table name, or literal. If factor 1 is not specified, the result field is used. In the following discussion, references to factor 1 apply to the result field if factor 1 is not specified.
Factor 2 must contain a string, and may contain the number of blanks to be inserted between the concatenated strings. Its format is the string, followed by a colon, followed by the number of blanks. The blanks are in the format of the data. For example, for character data a blank is x'40', while for UCS-2 data a blank is x'0020'. The string portion can contain one of: a field name, array element, named constant, data structure name, table name, literal, or data structure subfield name. The number of blanks portion must be numeric with zero decimal positions, and can contain one of: a named constant, array element, literal, table name, or field name.
If a colon is specified, the number of blanks must be specified. If no colon is specified, concatenation occurs with the trailing blanks, if any, in factor 1, or the result field if factor 1 is not specified.
If the number of blanks, N, is specified, factor 1 is copied to the result field left-justified. If factor 1 is not specified the result field string is used. Then N blanks are added following the last non-blank character. Then factor 2 is appended to this result. Leading blanks in factor 2 are not counted when N blanks are added to the result; they are just considered to be part of factor 2. If the number of blanks is not specified, the trailing and leading blanks of factor 1 and factor 2 are included in the result.
The result field must be a string and can contain one of: a field name, array element, data structure name, or table name. Its length should be the length of factor 1 and factor 2 combined plus any intervening blanks; if it is not, truncation occurs from the right. If the result field is variable-length, its length does not change.
A P operation extender indicates that the result field should be padded on the right with blanks after the concatenation occurs if the result field is longer than the result of the operation. If padding is not specified, only the leftmost part of the field is affected.
At run time, if the number of blanks is fewer than zero, the compiler defaults the number of blanks to zero.
For more information, see String Operations.
*...1....+....2....+....3....+....4....+....5....+....6....+....7...+....
CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq....
*
* The following example shows leading blanks in factor 2. After
* the CAT, the RESULT contains 'MR. SMITH'.
*
C MOVE 'MR.' NAME 3
C MOVE ' SMITH' FIRST 6
C NAME CAT FIRST RESULT 9
*
* The following example shows the use of CAT without factor 1.
* FLD2 is a 9 character string. Prior to the concatenation, it
* contains 'ABC '; FLD1 contains 'XYZ
* After the concatenation, FLD2 contains 'ABC XYZ '.
*
C MOVEL(P) 'ABC' FLD2 9
C MOVE 'XYZ' FLD1 3
C CAT FLD1:2 FLD2*...1....+....2....+....3....+....4....+....5....+....6....+....7...+....
CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq....
*
* CAT concatenates LAST to NAME and inserts one blank as specified
* in factor 2. TEMP contains 'Mr. Smith'.
C MOVE 'Mr. ' NAME 6
C MOVE 'Smith ' LAST 6
C NAME CAT LAST:1 TEMP 9
*
* CAT concatenates 'RPG' to STRING and places 'RPG/400' in TEMP.
C MOVE '/400' STRING 4
C 'RPG' CAT STRING TEMP 7
*
* The following example is the same as the previous example except
* that TEMP is defined as a 10 byte field. P operation extender
* specifies that blanks will be used in the rightmost positions
* of the result field that the concatenation result, 'RPG/400',
* does not fill. As a result, TEMP contains 'RPG/400 '
* after concatenation.
C MOVE *ALL'*' TEMP 10
C MOVE '/400' STRING 4
C 'RPG' CAT(P) STRING TEMP
*
* After this CAT operation, the field TEMP contains 'RPG/4'.
* Because the field TEMP was not large enough, truncation occurred.
C MOVE '/400' STRING 4
C 'RPG' CAT STRING TEMP 5
*
* Note that the trailing blanks of NAME are not included because
* NUM=0. The field TEMP contains 'RPGIV '.
C MOVE 'RPG ' NAME 5
C MOVE 'IV ' LAST 5
C Z-ADD 0 NUM 1 0
C NAME CAT(P) LAST:NUM TEMP 10*...1....+....2....+....3....+....4....+....5....+....6....+....7...+....
*
* The following example shows the use of graphic strings
*
DName+++++++++++ETDsFrom+++To/L+++IDc.Functions+++++++++++++++++++++++++
* Value of Graffld is 'AACCBBGG'.
* Value of Graffld2 after CAT 'aa AACCBBGG '
* Value of Graffld3 after CAT 'AABBCCDDEEFFGGHHAACC'
*
D Graffld 4G INZ(G'oAACCBBGGi')
D Graffld2 10G INZ
D Graffld3 10G INZ(G'oAABBCCDDEEFFGGHHi')
CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq.
* The value 2 represents 2 graphic blanks as separators
C G'oaai' cat Graffld:2 Graffld2
C cat Graffld Graffld3