%CONCAT (Concatenate with Separator)

Edit online
%CONCAT(separator : string1 : string2 { : string3 ... { : *NATURAL | *STDCHARSIZE})

%CONCAT returns the concatenation of string1, string2, string3, and so on, separated by the separator operand.

The operands must have type alphanumeric, UCS-2, or graphic. They cannot be hexadecimal literals or have CCSID(*HEX).

If no separator is required, specify *NONE as the separator operand.

If a single blank is required as the separator, specify *BLANK or *BLANKS as the separator operand.

There must be at least three operands. There is no practical upper limit for the number of operands.

The last parameter can be *NATURAL or *STDCHARSIZE to override the current CHARCOUNT mode for the statement.
  • Specify *NATURAL to indicate that %CONCAT operates in CHARCOUNT NATURAL mode.
  • Specify *STDCHARSIZE to indicate that %CONCAT operates in CHARCOUNT STDCHARSIZE mode.

For information on how the CHARCOUNT mode affects concatenation, see Concatenation of data with different character sizes.

The data type and CCSID of the value returned by the built-in function depends on the data type of the operands. See Determining the Common Type of Multiple Operands.

To concatenate the elements of an array, use %CONCATARR.

Examples of %CONCAT

  1. Concatenate two operands with a separator 
    
   DCL-S result VARCHAR(50);

   result = %CONCAT(', ' : 'cat' : 'dog');
   // result = "cat, dog"
  2. Concatenate two operands with a blank separator 
    
   DCL-S result VARCHAR(50);

   result = %CONCAT(*blanks : 'cat' : 'dog');
   // result = "cat dog"
  3. Concatenate two operands without a separator 
    
   DCL-S result VARCHAR(50);

   result = %CONCAT(*none : 'cat' : 'dog');
   // result = "catdog"
  4. Concatenate sevaral operands 
    
   DCL-S sep VARCHAR(5) INZ('|');
   DCL-DS arr QUALIFIED DIM(*AUTO : 10);
      item varchar(20);
      type varchar(20);
      quantity int(10);
      price packed(7 : 2);
   END-DS;
   DCL-S header VARCHAR(100);
   DCL-S line VARCHAR(100);

   arr(1).item = 'chair';
   arr(1).type = 'furniture';
   arr(1).quantity = 5;
   arr(1).price = 79.99;

   arr(2).item = 'telephone';
   arr(2).type = 'appliance';
   arr(2).quantity = 2;
   arr(2).price = 49.99;

   header = %CONCAT(sep : 'item' : 'type' : 'quantity' : 'price');
   snd-msg header;
   for i = 1 to %elem(arr);
      line = %CONCAT(sep
                   : arr(i).item
                   : arr(i).type
                   : %char(arr(i).quantity)
                   : %char(arr(i).price));
      snd-msg line;
   endfor;

   // SND-MSG sends the following strings to the joblog:
   //   "item|type|quantity|price"
   //   "chair|furniture|5|79.99"
   //   "telephone|appliance|2|49.99"