RPG/400 Help

CAT (Concatenate Two Character Strings)

*---------*---------------*-----------------*----------------*---------------*
|   CODE  |    FACTOR 1   |     FACTOR 2    |     RESULT     |  INDICATORS   |
|         |               |                 |      FIELD     |               |
*---------*---------------*-----------------*----------------*---------------*
| CAT (P) | Source string | Source string   | Target         |               |
|         | 1             | 2: number of    | string         |               |
|         |               | blanks          |                |               |
*---------*---------------*-----------------*----------------*---------------*

The CAT operation concatenates the character string specified in factor 2 to the end of the character string specified in factor 1 and places it in the result field. If no factor 1 is specified, factor 2 is concatenated to the end of the result field string.

Factor 1 can contain a character 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 character string, and may contain the number of blanks to be inserted between the concatenated strings. Its format is the character string, followed by a colon, followed by the number of blanks. The character 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 nonblank 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. If the number of blanks is specified, however, the trailing blanks of factor 1 are ignored and only as many blanks as specified are included in the result between the last nonblank character in factor 1 and the first character of factor 2. Leading blanks in factor 2 are always included. For example, if you have:

   C      'bMIKEbb'  CAT  'bbSMITHb':1  Name

the value of the result field after this statement is executed is:

          'bMIKEbbbSMITHb'
Note:
The leading blanks in factors 1 and 2 and the trailing blanks in factor 2 are placed in the result unchanged. Since one was specified as the number of blanks, factor 1 was copied left justified to the result field, a blank was added following the rightmost nonblank character, and factor 2 was appended to the result. Since factor 2 had two leading blanks, the total number of blanks between the two now concatenated fields is three.

The result field must be character, 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.

A P specified in the operation extender field (position 53) 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.

Figurative constants cannot be used in the factor 1, factor 2, or result fields. No overlapping is allowed in a data structure for factor 1 and the result field, or for factor 2 and the result field.

See Figure "CAT Operation" for examples of the CAT operation.

CAT Examples

Figure 13. CAT Operation

*...1....+....2....+....3....+....4....+....5....+....6....+....7...
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++
C*
C* CAT concatenates LAST to NAME and inserts one blank as specified
C* in factor 2.  TEMP contains 'Mr.bSmith'.
C                     MOVE 'Mr.   '  NAME    6
C                     MOVE 'Smith '  LAST    6
C           NAME      CAT  LAST:1    TEMP    9
C*
C* CAT concatenates 'RPG' to STRING and places 'RPG/400' in TEMP.
C                     MOVE '/400'    STRING  4
C           'RPG'     CAT  STRING    TEMP    7
C*
C* The following example is the same as the previous example except
C* that TEMP is defined as a 10 byte field.  P in position 53
C* specifies that blanks will be used in the rightmost positions
C* of the result field that the concatenation result, 'RPG/400',
C* does not fill.  As a result, TEMP contains 'RPG/400bbb'
C* after concatenation.
C                     MOVE *ALL'*'   TEMP   10
C                     MOVE '/400'    STRING  4
C           'RPG'     CAT  STRING    TEMP      P
C*
C* After this CAT operation, the field TEMP contains 'RPG/4'.
C* Because the field TEMP was not large enough, truncation occurred.
C                     MOVE '/400'    STRING  4
C           'RPG'     CAT  STRING    TEMP    5
C*
C* Note that the trailing blanks of NAME are not included because
C* NUM=0.  The field TEMP contains 'RPGIIIbbbb'.
C                     MOVE 'RPG   '  NAME    5
C                     MOVE 'III   '  LAST    5
C                     Z-ADD0         NUM     10
C           NAME      CAT  LAST:NUM  TEMP    10P

Figure 14. CAT Operation

*...1....+....2....+....3....+....4....+....5....+....6....+....7...
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++
C*
C* The following example shows leading blanks in factor 2.  After
C* the CAT the RESULT contains 'MR.bSMITH'.
C*
C                     MOVE 'MR.'     NAME    3
C                     MOVE ' SMITH'  FIRST   6
C           NAME      CAT  FIRST     RESULT  9
C*
C*  The following example shows the use of CAT without factor 1.
C*  FLD2 is a 9 character string.  Prior to the concatenation, it
C*  contains 'ABCbbbbbb.' FLD1 contains 'XYZ'.  After the
C*  concatenation FLD2 contains 'ABCbbXYZb'.
C*
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++
C                     MOVE 'ABC'     FLD2    9 P
C                     MOVE 'XYZ'     FLD1
C                     CAT  FLD1:2    FLD2


[ Top of Page | Previous Page | Next Page | Table of Contents ]