Convert CASE or CCSID (CLCONVERT)

Where allowed to run:
  • Batch program (*BPGM)
  • Interactive program (*IPGM)
  • Batch ILE CL module (*BMOD)
  • Interactive ILE CL module (*IMOD)
Threadsafe: No 		Parameters
Examples
Error messages

The CL Convert command converts between letter case or between CCSID (character sets). The converted value is copied to the designated CL variable.

Restrictions:

Top

Parameters

Keyword Description Choices Notes
VAR CL var for converted data Not restricted Required, Positional 1
VALUE Data to convert Character value Required, Positional 2
XLATE Type of Translation *TOUPPER, *TOLOWER, *CCSID, *UPPER, *LOWER Optional, Positional 3
FROMCCSID Convert from CCSID 0-65535, *JOB, *EBCDIC37, *ASCII, *UTF8 Optional, Positional 4
TOCCSID Convert to CCSID 0-65535, *JOB, *EBCDIC37, *ASCII, *UTF8 Optional, Positional 5
Top

CL var for converted data (VAR)

Specifies the TYPE(*CHAR) CL variable to receive the converted data. The CL variable may be up to 5000 bytes in length.

This is a required parameter.

CL Variable
Specify the CL variable to receive the converted data. The shorter of the data specified on the VALUE parameter and this CL variable's length is used to determine the number of characters that are translated.
Top

Data to be converted (VALUE)

Specifies the data to be converted. A literal, or a CL variable may be specified. When a CL variable is specified the length of the CL variable is used as the data length unless that CL variable is wrapped in the %TRIMR built-in function. Use caution when using %TRIMR on non-EBCDIC character strings as it may not produce the results you expect (that is, blanks in ASCII are X'20' not X'40')

This is a required parameter.

character-value
Specify the data to be translated or a CL variable containing the data to be translated.
Top
Top

Convert from CCSID (FROMCCSID)

Specifies the CCSID of the data specified on the VALUE parameter. This parameter is used for all conversions.

*JOB
The CCSID of the job running the command is used as the FROMCCSID value.
*EBCDIC37
CCSID 37, USA EBCDIC, is used as the from value's CCSID.
*ASCII
CCSID 819, PC ASCII, is used as the from value's CCSID.
*UTF8
CCSID 1208, UTF-8, is used as the from value's CCSID.
CCSID
Specify an valid CCSID value. This should be the CCSID of the data stored in the CL variable or text string specified on the VALUE parameter.
Top

Convert to CCSID (TOCCSID)

Specifies the target CCSID identifier. This parameter is used only for CCSID conversions.

*JOB
The CCSID of the job running the command is used as the FROMCCSID value.
*EBCDIC37
CCSID 37, USA EBCDIC, is used as the from value's CCSID.
*ASCII
CCSID 819, PC ASCII, is used as the from value's CCSID.
*UTF8
CCSID 1208, UTF-8, is used as the from value's CCSID.
CCSID
Specify an valid CCSID value. This should be the CCSID of the data stored in the CL variable or text string specified on the VALUE parameter.
Top

Examples for CLCONVERT

Example 1: Simple Command Example 

DCL      VAR(&ASCII) TYPE(*CHAR) LEN(50)
DCL      VAR(&MYNAME) TYPE(*CHAR) LEN(30)
CHGVAR   VAR(&MYNAME) VALUE('Bob Cozzi')
CLCONVERT  VAR(&ASCII) VALUE(&MYNAME) TOCCSID(*ASCII)

This command translates the content of the &MYNAME CL variable to PC ASCII (CCISD 819) and stores it in the &ASCII CL variable. The content of &MYNAME is expected to be in the CCSID of the job.

Example 2: More Complex Command Example 

PGM      PARM(&IFSDIR)
DCL      VAR(&IFSDIR) TYPE(*CHAR) LEN(640)
DCL      VAR(&FOLDER) TYPE(*CHAR) LEN(640)
CLCONVERT  VAR(&FOLDER) VALUE(%TRIMR( &IFSDIR X'20'))  +
           FROMCCSID(*ASCII) TOCCSID(*JOB)

This command translates an IFS directory name from ASCII to the job CCSID so it can be used on subsequent IFS, PASE commands from within CL or passed to an RPG program. The IBM i v7R1 TR5 %TRIMR built-in function is used to trim off trailing ASCII spaces (i.e., blanks) from the &IFSDIR variable.

Top

Error messages for CLCONVERT

*ESCAPE Messages

CPF9801
Object &2 in library &3 not found.
CPF9802
Not authorized to object &2 in &3.
CPF9803
Cannot allocate object &2 in library &3.
CPF9807
One or more libraries in library list deleted.
CPF9808
Cannot allocate one or more libraries on library list.
CPF9810
Library &1 not found.
CPF9811
Program &1 in library &2 not found.
CPF9812
File &1 in library &2 not found.
CPF9820
Not authorized to use library &1.
CPF9830
Cannot assign library &1.
CPF9899
Error occurred during processing of command.
Top