Start of change

%CHAR built-in function

%CHAR converts logical, decimal, integer, or unsigned integer data to character format. The converted value can be assigned to a CL variable, passed as a character constant to another program or procedure, or specified as a value for a command parameter of a CL command run from compiled CL.

The %CHAR built-in function can be used anywhere that CL supports a character expression. %CHAR can be used alone or as part of a more complex character expression. For example, %CHAR can be used to compare a numeric CL variable to a character CL variable in the COND parameter of an IF or WHEN command. %CHAR can also be used to set the value of a CL command parameter, if the associated command object defines the parameter with EXPR(*YES) and TYPE of *CHAR, *NAME, *SNAME, *CNAME, *PNAME, *GENERIC, *DATE, *TIME, or *X.

The format of the convert to character data built-in function is:
%CHAR(convert-argument)

The convert-argument must be a CL variable with TYPE of *LGL, *DEC, *INT or *UINT.

For logical data, the result will be ether '0' or '1'.

For numeric data, the result will be in decimal format, left-adjusted with a leading negative sign if the value is negative, and without leading zeros. A decimal point is inserted if needed, and the character used for any decimal point will be the character indicated by the decimal format (QDECFMT) system value (default is '.'). For example, %CHAR of a CL variable declared with TYPE(*DEC) and LEN(7,3) CL variable might return the value '-1.234'. The decimal format (QDECFMT) system value also determines the type of zero suppression of the conversion result.

The following are examples of using the %CHAR built-in function:

  • Convert packed decimal variable
    DCL VAR(&MSG) TYPE(*CHAR) LEN(26)
    DCL VAR(&ANSWER) TYPE(*DEC) LEN(10 5) VALUE(-54321.09876)
    
    /* &MSG will have the value 'The answer is -54321.09876' */
    CHGVAR VAR(&MSG) VALUE('The answer is' *BCAT %CHAR(&ANSWER))
  • Convert integer or unsigned integer variable
    DCL VAR(&MSG) TYPE(*CHAR) LEN(60)
    DCL VAR(&LENGTH) TYPE(*UINT) LEN(2) VALUE(50)
    DCL VAR(&TEMP) TYPE(*INT) LEN(2) VALUE(-10)
    
    /* &MSG will have the value 'The length of this box is 50 centi+
    meters.                   ' */
    CHGVAR VAR(&MSG) VALUE('The length of this box is' *BCAT %CHAR(&LENGTH) + 
    *BCAT 'centimeters.') 
    /* &MSG will have the value 'The temperature dropped to -10 degrees +
    Centigrade.          ' */
    CHGVAR VAR(&MSG) VALUE('The temperature dropped to' *BCAT %CHAR(&TEMP) + 
    *BCAT 'degrees Centigrade.')
  • Convert logical variable
    DCL VAR(&ENDOFFILE) TYPE(*LGL) VALUE('1')
    SNDPGMMSG MSG('End of file?' *BCAT %CHAR(&ENDOFFILE))
  • Leading zeros will be suppressed but all decimal position zeros will be kept
    DCL &AMOUNT TYPE(*DEC) LEN(7 4) VALUE(099.5)
    /* &MSG will have the value "Your amount comes to 99.5000" */
    SNDPGMMSG MSG('Your amount comes to' *BCAT %CHAR(&AMOUNT))
  • Decimal format and zero suppression
    DCL VAR(&MSG) TYPE(*CHAR) LEN(20)
    DCL VAR(&ANSWER) TYPE(*DEC) LEN(10 2) VALUE(-0.45)
    
    /* &MSG will have the value 'The answer is -.45  ', while +
    CHGJOB DECFMT(*BLANK) */
    /* &MSG will have the value 'The answer is -0,45 ', while CHGJOB DECFMT(J) */
    /* &MSG will have the value 'The answer is -,45  ', while CHGJOB DECFMT(I) */
    CHGVAR VAR(&MSG) VALUE('The answer is' *BCAT %CHAR(&ANSWER))
End of change