The Upper Case using XCL (UPRCASEXCL) command returns a character string in all upper case.

This function is also available with command UPRCASE in library VC2XCL. Any use of this alternative command name should be library qualified in case the i operating system were to use this command name in a future release.

Parameters

Character variable (VAR)

Specifies the CL variable to receive the upper cased character string. When the BASVAR parameter is not specified this CL variable is also used to determine the character string to be upper cased.

character-value

Specify the name of the CL variable to receive the upper cased value.

Base variable (BASVAR)

Specifies the initial character string to upper cased. If this parameter is not specified then the VAR parameter is used to determine the initial character string.

character-value

Specify the initial character string to be upper cased.

Length of data to case (BASLEN)

Specifies the number of bytes from the initial character string that are to be upper cased.

The length specified must include full characters that are to be upper cased. For instance a BASLEN of 5 is invalid if the CCSID parameter is *UCS2 or *UTF16 as these CCSIDs require an even number of bytes.

*ALL

All bytes of the initial character string are to be upper cased. If the allocated length of the VAR variable is less than the allocated length of the initial value then only those characters that would fit into the VAR variable will be upper cased.

integer

Specify the number of bytes to be upper cased.

Fill character (FILLCHR)

Specifies if excess bytes in the VAR variable should be set to a specific value when the length of the initial character string is less than the allocated length of the VAR variable.

*BLANK

Any bytes of the VAR variable that were not upper cased due to the BASLEN value will be set to blanks. The blanks will be in the CCSID specified by the CCSID parameter.

*NONE

Any bytes of the VAR variable that were not upper cased due to the BASLEN value will be left as is.

*NULL

Any bytes of the VAR variable that were not upper cased due to the BASLEN value will be set to null bytes.

CCSID of data (CCSID)

Specifies the CCSID of the character data being upper cased. The CCSID can be EBCDIC, ASCII, or Unicode.

This value is also used to properly encode blank characters when FILLCHR is *BLANK.

*JOB

The CCSID of the job is used to determine the CCSID of the data to be upper cased. If the job CCSID is 65535, the default job CCSID will be used.

*ASCII

The data to be upper cased is in CCSID 819 (ISO Latin 1).

*UCS2

The data to be upper cased is in CCSID 13488 (Unicode UCS2).

*UTF16

The data to be upper cased is in CCSID 1200 (Unicode UTF16).

*UTF8

The data to be upper cased is in CCSID 1208 (Unicode UTF8).

integer

Specify a valid CCSID in the range of 1 to 65533.

Examples for UPRCASEXCL

Example 1: Upper Case Job Character Data

Dcl        Var(&Tgt_Var) Type(*Char) Len(20)
Dcl        Var(&Src_Var) Type(*Char) Len(20) +
             Value('A Mixed String')
UprCaseXCL Var(&Tgt_Var) BasVar(&Src_Var)

This command upper cases the contents of the CL variable &Src_Var and returns the result in CL variable &Tgt_Var. After the UPRCASEXCL command runs the value of &Tgt_Var is 'A MIXED STRING'.

Example 2: Upper Casing ASCII Data

Dcl        Var(&Tgt_Var)   Type(*Char) Len(20)
Dcl        Var(&Src_Small) Type(*char) Len(6)
ChgVar     Var(&Src_Small) Value(x'616263646566')
UprCaseXCL Var(&Tgt_Var) BasVar(&Src_Small) CCSID(*ASCII)

This command upper cases the contents of CL variable &Src_Small and returns the result in CL variable &Tgt_Var. The value of &Src_Small is 'abcdef' in ASCII. After the UPRCASEXCL command runs the value of &Tgt_Var is 'ABCDEF' in upper case ASCII with 14 trailing ASCII blank characters. The trailing characters are set to ASCII blanks as the allocated size of &Src_Small is only 6 bytes while the allocated size of &Tgt_Var is 20 bytes. The default for the fill character parameter FILLCHR is *BLANK - set excess bytes in the VAR parameter to blanks based on the CCSID parameter.

Error messages for UPRCASEXCL

*ESCAPE Messages

XCL500A

BASLEN value of &1 is greater than the BASVAR declared size of &2.

XCL500B

CCSID value of &1 is not supported.

XCL500C

Encoding scheme &1 not supported.

XCL500D

Function did not complete. See previously listed messages related to possible user errors.

XCL9002

Function did not complete. See previously listed messages related to possible user errors.

XCL9003

Function did not complete. See previously listed messages for possible cause.

XCL9004

Function did not complete. See previously listed messages for possible cause.

XCL9005

Function did not complete. Contact your service provider.