Get Control Function Definition (CDRGCTL, QTQGCTL) API

The Get Control Function Definition (CDRGCTL, QTQGCTL) API gets a requested control function definition associated with a given CCSID. The following control function definitions are defined in the CCSID resource repository model:

• Substitute
• New Line
• Line Feed
• Carriage Return
• End of File

Additionally, the following other definitions are included in this repository:

• Space
• String Type

Each control function definition is defined as a triplet consisting of:

• The code point value allocated to the requested control function definition
• Its width in number of bytes
• The state number in which the code point is to be used

Each control function may be defined for each of the possible code extension switching states associated with the CCSID. There is, at most, one code point definition for a control function within a switching state.

If the string type definition is selected it's value will be returned in the first value of the triplet. The remaining two values of the triplet will be returned as 0.

A selection parameter (SEL) is used to identify which control function definition is to be returned by the function.

Authorities and Locks

None.

Required Parameter Group

CCSID1

INPUT; INT(4)

This variable contains the CCSID value referenced; a positive number in the range 1 to 65,279.

SEL

INPUT; INT(4)

This variable contains the selection specification, a non-negative number in the range 0 to 255. If the selected control function element is available in the resource definition for CCSID1, the triplets are returned in the area starting at CTLFDF. The following values are currently defined for SEL:

SEL	Selected Control Function
0	Space
1	Substitute
2	New Line
3	Line Feed
4	Carriage Return
5	End of File
100	String Type

N1

INPUT; INT(4)

This variable contains the size of the allocated area starting at CTLFDF to contain the returned data. N1 is specified as a number of elements. Each triplet is counted as 3 elements. It is a positive number whose minimum value is 3.

N2

I/O; INT(4)

This variable contains the number of values returned in CTLFDF. The first invocation of this function must have N2 initialized to zero. It is a non-negative integer and is a multiple of 3 (corresponding to each triplet in CTLFDF). If no definition is found in the CCSID resource for the requested element, a value of 0 is returned in N2.

CTLFDF

OUTPUT; INT(4)

The start of the area to contain the selected definition elements. Each element is a triplet of 3 binary(4) values. For each triplet, the first value is the code point, the second is the code point width, and the third value contains the switching state number. There is one triplet returned for each switching state for CCSID1. An undefined element is indicated by a zero state number in the corresponding CTLFDF entry.

If the string type definition is selected it's value will be returned in the first value of the triplet. The remaining two values of the triplet will be returned as 0. The following table provides a definition of each of the string types:

String Type	Text Type	Numeric Shaping	Orientation	Text Shaping	Symmetrical Swapping
4	Visual	Passthrough	LTR	Shaped	Off
5	Implicit	Arabic	LTR	Unshaped	On
6	Implicit	Arabic	RTL	Unshaped	On
7(*)	Visual	Passthrough	Contextual *	Unshaped-Ligatures	Off
8	Visual	Passthrough	RTL	Shaped	Off
9	Visual	Passthrough	RTL	Shaped	On
10	Implicit		Contextual LTR		On
11	Implicit		Contextual RTL		On

(*) Field orientation is left to right (LTR), when first alphabetic character is a Latin one, and right to left (RTL) when it is a Bidi (RTL) character; characters are unshaped, but LamAlef ligatures are kept, and not broken into constituents.

FB

OUTPUT; Feedback

The function returns in this feedback array 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.

Feedback Codes and Conditions

Exceptions issued: CPF9872 - Program &1 in library &2 ended.

Usage Notes

1. The maximum number of code extension states (and the associated corresponding code pages) for the CCSID depends on the ES. Most CCSIDs have only one state. The maximum is four for the CCSIDs registered to date, though some future CCSIDs may have more. A calling function can set N1 to 48, to accommodate up to 16 triplets of information without overflow.
   
   
2. The code point value for any control function definition can be in the range X'00000000' to X'7FFFFFFF' -- only up to 4-byte code points can be defined. The code point width values can be 1 to 4 (bytes).

   For example, for CCSID 00037, the return value, if the space was asked for, would be X'00000040'. This is interpreted as a 1 byte value of X'40'.

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