%CHAR(character | graphic | UCS2 {: ccsid})

%CHAR can convert the value of a character, graphic, or UCS-2 expression to type character with a specific character CCSID. The CCSID operand specifies the CCSID of the result of the %CHAR built-in function.

If the CCSID operand is specified, it can be *HEX, *JOBRUN, *JOBRUNMIX, *UTF8, a numeric value representing an EBCDIC or ASCII CCSID, the value 65535 which is the same as *HEX, or the value 1208 which is the same as *UTF8.

If the CCSID operand is not specified, it defaults to the default character CCSID of the module as specified by control keyword CCSID(*CHAR).

If the character operand has CCSID *HEX, no conversion is done. The data in the operand is assumed to have the CCSID specified by the CCSID operand. See Character Format for information on character data with CCSID *HEX.

See Conversions for information about the possibility that converting data to some character CCSIDs may not be able to convert all the data successfully.

For graphic data, if the CCSID for the %CHAR return value is an EBCDIC CCSID, the value returned includes the shift-in and shift-out characters. For example, if a 5 character graphic field is converted, the returned value is 12 characters (10 bytes of graphic data plus the two shift characters). If the value of the expression has a variable length, the value returned is in varying format.

For more information, see Conversion Operations or Built-in Functions.

%CHAR Examples with Character, Graphic, and UCS-2 operands

Note: The graphic literal in this example is not a valid graphic literal. See Graphic Format for more information.


D graphicName     S             20G   VARYING INZ(G'oXXYYZZi')
D greeting        S             20A   VARYING CCSID(*UTF8) INZ('Hello')
D message         S             30C   INZ('Successful operation')
D result          S            100A   VARYING

This example converts a graphic value to character. The CCSID parameter is not specified, so the result of the %CHAR built-in function has the default character CCSID of the module.


   result = 'The customer''s name is ' + %CHAR(graphicName) + '.';
   // result = 'The customer's name is oXXYYZZi.'

This example converts a UTF-8 value to character in the job CCSID


   result = %CHAR(greeting : *JOBRUN);
   // result = 'Hello'

This example converts a UCS-2 value to character in the job CCSID


   result = %CHAR(message : *JOBRUN);
   // result = 'Successful operation'