Get Short Form with Maximal CS for Specified ES and CP (QTQSMXC2) API


  Required Parameter Group:

1 CPIN Input Int(4)
2 ESIN Input Int(4)
3 CCSIDR Output Int(4)
4 ESR Output Int(4)
5 FB Output Feedback

  Default Public Authority: *USE

  Threadsafe: Yes

The Get Short Form with Maximal CS for Specified ES and CP (QTQSMXC2) API gets the CCSID with the maximal character set (CS) for a given code page (CP) value. The encoding scheme (ES) parameter can be specified to distinguish between usage of the same CP with two different encoding schemes, such as PC Display compared to PC Data.

The CS element that is associated with the returned CCSID is the largest in size of all the character sets that are contained in the associated code page for that CS element in the CCSID resource installed on the system.

The QTQSMXC2 API acts as an extension of the functions of the CDRSMXC API in that you can specify more code pages. The additional code pages are as follows:

Note: Not all the registered code pages are full, leaving room for possible future additions. The term maximal is used to distinguish it from a full code page. Over time, when new larger character sets are registered for a code page (this can happen until the code page is full), the maximal character set also changes, leading to a new CCSID returned by this function.


Authorities and Locks

None.


Required Parameters

CPIN
INPUT; INT(4)

A variable that contains the CP value referenced. This value must be a positive number in the range 1 to 65 534.

ESIN
INPUT; INT(4)

A variable that contains the ES value referenced.

Possible values follow:

0 The caller does not know the ES value, and expects the first CCSID encountered in the CCSID repository, with the specified CP and the full or maximal CS, to be returned.
4352-65 534 The caller specifies the encoding scheme value. Only encoding schemes that have a single (CS, CP) pair associated with them are valid for this function.

CCSIDR
OUTPUT; INT(4)

A variable that contains the returned CCSID value. This value must be a positive number in the range 1 to 65 279.

ESR
OUTPUT; INT(4)

A variable that contains the ES value of the returned CCSID. This value must be zero or a positive number in the range 4352 to 65 534.

FB
OUTPUT; FEEDBACK

In this feedback array this function returns the processing status (and any associated reason) for this function. The field type is an array of three 32-bit two's complement binary values (12 bytes or 96 bits). The status code is a non-negative number in the first 16 bits, and the reason code is a non-negative number in the second 16 bits. The following are specific meanings of the status code and associated reason code values (in hexadecimal) contained in the first 32 bits of FB. The other 64 bits are reserved.


Feedback Codes and Conditions

Status Reason Meaning
0000 0000 The function completed successfully.
0001 0001 No entry was found in the CCSID resource repository for the specified CPIN, ESIN combination.
0001 0003 The ESIN was specified as 0. The first CCSID encountered in the CCSID repository, with the specified CP and the full or maximal CS, was returned. Additional CCSIDs meeting the criteria may exist.
0001 0009 The ESIN specified indicates that more than one pair of CS, CPs are associated with it, which is incorrect for this function.
0002 0001 The CPIN value is 0.
0003 0001 The CPIN value is 65 535 (X'0000FFFF').
0006 0001 The CCSID resource repository was not found.
0006 0002 The CCSID resource repository is currently unavailable.
0007 0001 The system CCSID resource repository accessed by the function was found to be incorrect in the structure.
0008 0001 The CPIN value is not in the range 0 (X'00000000') to 65 535. (X'0000FFFF').
0008 0009 The ESIN value is nonzero and not in the range 4352 (X'00001100') to 65 534 (X'0000FFFE').


Usage Notes

  1. Often it is required to find the CCSID when the ES, CS, and CP values are known. CS and CP (also known as CGCSGID or GCID) are used in many existing IBM® architectures, data streams, and supporting products. Together with the CDRSCSP API, this function aids in the coexistence and migration for products that have to deal with the short form (CCSID) of identification on one side and the intermediate form (the code page global identifier) on the other. Because the intermediate forms are, by themselves, incomplete when used in some encoding schemes, the function can return only a default value as defined in the installation's resources, when the ESIN information is unknown.

  2. When an ESIN value of zero is specified, the feedback code is never returned as zero. Absence of an error results in a 0001 0003 feedback code.
API introduced: V4R1

[ Back to top | National Language Support APIs | APIs by category ]