This chapter contains the specifications of the CDRA-defined functions (Application Programming Interfaces or APIs). These functions are provided as procedure calls that are independent of programming languages.

Function Definition Template

The CDRA functions are described using a common template containing the following information:

CDRXXXX - Descriptive Function Name

A single line title for the function definition, consisting of a short name and a descriptive name for the function.

Function Description

A short description of what the function does.

Resources Used

A list of any resources used by the function.

Function Syntax

Conventions used for syntax are detailed in the next section. The following information is included:

CDRXXXX (Input and Output Parameters, Feedback)

Input:

List of Input parameters
IPARM1: a description, variable type, and permitted values
IPARM2: - - - - -
- - - : - - - - -

Input/Output

List of Input/Output parameters
IOPARM1: a description, variable type, and permitted values
IOPARM2: - - - - -
- - - : - - - - -

Output:

List of Output parameters
OPARM1: a description, variable type, and permitted values
OPARM2: - - - - -
- - - : - - - - -

FB:

Feedback codes and their meanings

Status	Reason	Meaning
0000	0000	the function completed successfully
0001	0001	description of condition reported

Usage Notes

Information that is considered to be useful to the caller of the function to provide a better understanding of the function.

Syntax Conventions

The syntax for the CDRA functions has been defined in general terms so that the functions and their associated parameters can be coded using all IBM high-level languages (HLLs).

The following conventions are used:

FUNCTION-NAME (Parameters, Feedback)

with the following explanations:

FUNCTION NAME: name of the function to be performed The function names all begin with the prefix "CDR" standing for "Character Data Representation"
Function names can be up to seven characters, consisting only of uppercase letters A to Z and digits 0 to 9. The first character of the name cannot be a digit. This restriction accommodates the limitation on function names of all known HLLs.
PARAMETERS: used to specify the desired input and output elements based upon the function to be performed and the output desired.

Parameters are positional.
A comma (,) is used as a delimiter between parameters.
No optional parameters are permitted.
All the parameter values are passed by reference. The parameters are of the type "variable" or "address" (of a location in the caller's address space). Passing constants as parameters is not permitted (for example, X'01F4' or 500 as CCSID parameter value, or a literal string).
Space for variables and buffers is allocated by the "caller" of the function. The caller always specifies the variable names or buffer names in the function call. Any data that is exchanged between the caller and the function is always passed in these variables or buffer areas.
Parameters that contain the input values are in general kept separate from those that contain the output values or feedback code.

Note:

If the same variable or buffer name is used for more than one call parameter, the results of the function are not predictable.

The parameters are passed (in the input output stack between the caller and the function) in the same order (sequentially from first to last) as they appear in the function call.
The terms Input, Output, and Input/Output in the syntax descriptions are based on what generates the data that is passed across the function interface in the parameters -- variables or buffers.
1. Input variables or buffers contain data that is supplied by the caller for use by the function.
2. Output variables or buffers contain data that is generated by the function and returned to the caller.
3. Input/Output variables or buffers contain data that is supplied by the caller for use by the function, and data that may be modified and returned by the function.
CDRA does not place any restrictions on the number of characters or the characters used in parameter names. The rules specified by the appropriate programming language or other syntax parser used to parse the caller's program source statements apply.
Parameter variables containing an integer value will be of the type "32-bit, signed, two's complement, binary". This type is supported across HLLs.
Length values (data-typed as integers) interchanged across a call interface are constrained by programming language support considerations to a maximum of +999,999,999.

FEEDBACK: The feedback code, FB, is a 96-bit structure (it can also be viewed as an array of 12 bytes or an array of three 32-bit two's complement binary numbers). It is used to communicate to the caller the conditions arising during the execution of the function. FB is a required parameter in all function calls.
1. Of the 12 bytes of FB (see Figure 15), the first four are used to indicate a status code (also known as a class code) and reason code (also known as a cause code) associated with each condition that may arise. The remaining eight are reserved for use by CDRA.
2. Figure 15. Structure of the Feedback Code (FB)
3. The status code conventions are described starting on page "Status Code Convention". The reason codes are function-specific. See the list of status and reason code combinations under each function interface definition.
4. A zero value for each of the status and reason codes indicates that the function performed as expected with no detected conditions. If the status code is zero, the reason code must also be zero. A nonzero value in the first 16 bits indicates there was some condition in execution and the function may not have completed successfully.
5. The status code part of the feedback code indicates the class of problem encountered. The associated reason code part of the feedback code gives more information for error analysis and reporting.
6. Note:
  - The level of severity of the error and the follow-on action to be taken are determined by the caller, depending on the specific nature of the problem associated with the called function.
  - No explicit attempt is made in the CDRA definition to classify the feedback codes into different classes such as INFORMATION, WARNING, or ERROR.
  - Depending on the function and the feedback code value, the calling function is responsible for handling the feedback code and taking appropriate action, such as making the appropriate values available to a message service: for example, CCSID= X'5234' was not found.
7. All the feedback codes defined in CDRA are non-negative numbers. As a result, the status code value that forms the most significant 16 bits of the feedback code is restricted to a maximum of X'7FFF'.
Violations of the syntax for the functions are expected to be detected and handled by the appropriate parser that is used to parse the function call statements of the caller. An indication of a parsing error is expected to be returned by the parser.

Status Code Convention

The status codes have the following generic meanings, and each function description expands on the specifics of their use.

Status (Hex) Meaning

0000 to 00FF

Common to several functions and environments; specific values used in this document are described later.
The following are specific values in this range with their assigned meanings:

Status (Hex) Meaning
0000: function completed successfully
0001: an element or value was not found during the function execution
0002: a CCSID, CP, or CS value of 0 was encountered
0003: CCSID encountered is one of the Special-Purpose CCSIDs in the range 65,280 (X'FF00') to 65,535 (X'FFFF'). This feedback code is also used to show a CP value of 65,535 (X'FFFF').
0004: an overflow situation was encountered
0005: syntactical error(s) in parameter(s)
0006: the function encountered a condition that prevents it from proceeding (for example, the CCSID repository is not found, or there is insufficient memory to be able to copy or load a resource or logic)
0007: one or more CDRA resources supporting the function are damaged and unusable
0008: some parameter value is outside the specified valid range(s)
0009 to 00FF: reserved for future allocation by CDRA

0100 to 07FF

Common to all environments but function-specific; use of these status code values is documented in this chapter, along with the feedback code values of the functions that use them.

0800 to 17FF

Common to all functions but environment-specific; if values from this range are used in the CDRA-defined services, appropriate product documentation will describe their meaning, along with any associated reason codes for each function.

1800 to 7FFF

Function-specific and environment-specific; if values from this range are used in the CDRA-defined services, appropriate product documentation will describe their meaning, along with any associated reason codes for each function.

8000 to FFFF

Not used (causes feedback code to become negative).

Depending on the function, the status code is accompanied by a function-specific reason code. The reason codes are detailed along with each function. A nonzero status code is always accompanied by a nonzero reason code.

An attempt has been made to assign unique feedback codes for significantly different conditions across the APIs. There are, however, several exceptions due to changes in the architecture specifications.

Note:

Status and reason code values that are not specifically listed under each function are reserved for future allocation by CDRA.

Data Overflow Convention

Parameter lists for routines that have caller-allocated areas or arrays for receipt of data (or for variable-length character strings) must contain a minimum of two counts: one for the space allocated by the caller, and one for the space used by the function. The size of the allocated area is passed to the called function, and the function returns the size actually used in the caller-allocated area for the returned data.

When there is insufficient space allocated, a methodology is needed to deal with the overflow situation. A common convention (followed by both the caller and the function implementation) to deal with overflow situations is assumed for most CDRA callable functions (the exceptions are conversion-related functions where an overflow situation is dealt with by returning a truncated converted string).

The method described below is suitable for handling overflows when all of the data to be returned by the function is available to the function, and is static data as opposed to dynamically computed data. (For example, it is information from a CCSID resource definition versus the result of a conversion process, which is dynamically generated.)

For dynamically generated data, the output will have to be computed from the beginning in order to return the next piece of data, especially since the assumptions for the CDRA callable functions are that input and output data transferred across the call interface is all in the caller-allocated area (except for some local storage needs of the function). Such re-computations can cause severe degradation of performance for operations, such as the conversion of a long string. For this reason, the overflow-handling method described here is applied only to those CDRA functions that deal with static data.

In the following example the allocated space (variable N1) is 4, and the required space is 15. The variable N2 contains the actually-used space. The resource has N2max (N2max = 15 in this example) elements to to be returned. Figure 16 shows the values of N1, N2, and the remaining number of elements to be retrieved.

Figure 16. Example of Data Overflow Handling

Event		N1	N2	Remaining
First Call	Invocation	4	0	0
First Call	Return	4	15	11
Second Call	Invocation	4	15	11
Second Call	Return	4	11	7
Third Call	Invocation	4	11	7
Third Call	Return	4	7	3
Fourth Call	Invocation	4	7	3
Fourth Call	Return	4	3	-

The variable N2 in this example acts as an input/output variable. N2 is initialized to zero by the caller. The roles of the performing function and that of the caller are explained below:

The role of the performing function:
It examines the value of N2 to determine where to start the output. If N1 is insufficient to hold all of the returned data, the data will be returned in segments of size N1 until all of the data to be returned is exhausted.
The function should see one of the following two relationships between N1 and N2 when it is called:

N2 is zero (set by the caller). The function returns the first piece of maximum N1 elements of data and returns the value N2max in N2. N2max is the total required space (N2max = 15 in the example shown in Figure 16). When the returned value of N2 is greater than N1, there is more data to be returned. A nonzero feedback code is returned, indicating that there is more data to be returned.
N2 is greater than N1. The function returns the next piece of maximum N1 elements of requested data starting at S, where "S = N2max - (N2 - N1) + 1" (elements are numbered starting at 1), and decrements N2 by N1. If the resultant N2 is greater than N1, a nonzero feedback code indicates that there is more data to be returned. If N2 is less than or equal to N1, the last block of data containing N2 elements is returned, along with a zero feedback code.

The caller has the following role:

It calls the function with N2 initialized to zero.
When the returned value of N2 is greater than N1 (along with the corresponding nonzero feedback code indicating that there is more data), the caller processes the returned segment of N1 elements and calls the function again for the remaining data.
The caller must not change the values of N1 or N2 between function calls.
When the returned value of N2 is less than or equal to N1, the function has returned all the remaining elements (consisting of N2 valid elements) of requested data. The feedback code returned with the last block of data should be zero (unless some error condition other than overflow is encountered by the function).
The caller should examine the feedback code from each call to ensure that there are no other conditions reported by the performing function. It is insufficient to merely rely on the relationship between N1 and N2.

Error situations can arise. Specific errors are documented with the individual function definitions.

Functions for Querying CCSID Information

CDRGESP - Get Encoding Scheme, Character Set, and Code Page Elements

Function Description: The most frequently accessed elements of a CCSID are the Encoding Scheme and the CS/CP elements. This function returns the value of the Encoding Scheme associated with CCSID1 in ES, and the values of the CS and CP elements in CSCPL.
Resources Used: CCSID Resource (see section CCSID Resource).
Function Syntax: CDRGESP (CCSID1, N1, N2, ES, CSCPL, FB)

Status	Reason	Meaning
0000	0000	the function completed successfully
0001	0001	CCSID1 value is not in the CCSID resource repository
0002	0001	CCSID1 value is 0, which is reserved for indicating a default in a hierarchy. The invoker must resolve the default before invoking this function.
0003	0001	CCSID1 has one of the special-purpose CCSID values in the range 65,280 (X'0000FF00') to 65,535 (X'0000FFFF').
0004	0001	the allocated length (value of N1) for the area to contain returned values was insufficient to contain all the output data that is to be returned. See "Data Overflow Convention"
0005	0002	N2 is greater than N1; however, the start of the next block of data to be returned is outside the valid range 1 to N2max
0005	000A	N2 is less than or equal to N1, but is not 0
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 invalid in structure
0007	0004	there was no ES element definition in the CCSID resource for CCSID1
0007	0006	there was no definition for CS, CP elements in the CCSID resource for CCSID1
0008	0001	CCSID1 value is not in the range 0 (X'00000000') to 65,535 (X'0000FFFF')
0008	0002	N1 value is greater than the maximum allowed in this implementation, or N1 is odd
0008	0003	N1 is less than 2

Usage Notes

The maximum number of CS, CP values depends on the ES. Most CCSIDs have only one CS,CP pair. See Encoding Scheme Identifier for further information. Acaller can set N1 to 32, to accomodate up to 16 CS, CP pairs without overflow.

CDRSCSP - Get Short Form (CCSID) from Specified ES (CS, CP)

Function Description: This function gets the CCSID associated with the specified (CS,CP) pair(s) and ES. It aids in coexistence and migration for products that have to deal with the short form (CCSID) of identification on one side and the intermediate form (CGCSGID) on the other. The ES is further required to distinguish between usage of the same CS, CP with two different encoding schemes, (such as CS 00697 and CP 00850, with ES values of X'2100' and X'3100'), and when more than one CGCSGID is associated with a CCSID (such as with ES X'1301', X'2300', X'2305' and X'3300', for the CCSIDs registered to date -- See Appendix C: CCSID Repository for access to a complete list of CCSIDs.
Resources Used: Repository of CCSID Resources (see section CCSID Resource).
Function Syntax

Status	Reason	Meaning
0000	0000	the function completed successfully
0001	0001	no entry was found in the CCSID resource repository for the specified ESIN and CS, CP pair(s)
0001	0002	a single CCSID value with the specified CSCPL was found, but not with the specified ESIN. The values of the CCSID found and its associated ES are returned.
0002	0001	a CP value in CSCPL is zero
0002	0002	a CS value in CSCPL is zero
0003	0001	a CP value in CSCPL is 65,535 (X'0000FFFF')
0003	0002	Reserved
0005	0001	N1 is odd
0006	0001	the CCSID resource repository was not found
0006	0002	the CCSID repository is currently unavailable
0007	0001	the system CCSID resource repository accessed by the function was found to be invalid in structure
0008	0001	a CS or CP value in CSCPL array is not in the range 0 (X'00000000') to 65,535 (X'0000FFFF')
0008	0002	N1 is greater then the maximum permitted in this implementation
0008	0003	N1 is less then 2
0008	0004	ESIN value is nonzero and not in the range 4352 (X'00001100') to 65,534 (X'0000FFFE')

Usage Notes: Often it is required to find the CCSID when the ES and (CS, CP) values are known. CS, CP (also known as CGCSGID or GCID) is used in many existing IBM architectures and data streams and supporting products. Together with Get Character Set and Code Page Elements (CDRGCSP), this function aids in coexistence and migration for products that have to deal with the short form (CCSID) of identification on one side and the intermediate form (CGCSGID) on the other. Because of 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 not known.; For the CCSIDs defined to date, the maximum number of CS, CP pairs is 4 (up to eight values can be specified in CSCPL). Future CCSIDs may have more CS, CP pairs. :insnew acrnum=0095. Text to be inserted follows; When an ESIN value of zero is specified the function will return the first CCSID encountered in the resource repository with matching CS, CP pairs. There may be additional CCSIDs that meet the specified criteria.

CDRGESE - Get Encoding Scheme Element and its Subelements

Function Description: This function gets the values of the Encoding Scheme identifier (ESID) element and each of its subelements for a given CCSID value (CCSID1) from the CCSID resource repository (see section "CCSID Resource"). ESID has a two-byte hexadecimal format. The two bytes are decomposed as follows: the first nibble (first 4 bits of the first byte) is the basic encoding structure, the second nibble is the number of bytes indicator, and the second byte contains the code extension mechanism. The first two are defined in terms of X'0' to X'F', and the third as X'00' to X'FF'. The composite field is documented as its hexadecimal value and its unsigned decimal equivalent (see section "Encoding Scheme Identifier" for possible values).
Resources Used: CCSID Resource (see section CCSID Resource).
Function Syntax

Status	Reason	Meaning
0000	0000	the function completed successfully
0001	0001	the CCSID1 value is not in the CCSID resource repository
0002	0001	the CCSID1 value is 0, which is reserved for indicating a default in hierarchy. The caller must resolve the default before calling this function.
0003	0001	CCSID1 has one of the special-purpose CCSID values in the range 65,280 (X'0000F00') to 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 invalid in structure
0007	0004	there was no ES element definition in the CCSID resource for CCSID1
0008	0001	the CCSID1 value is not in the range 0 (X'00000000') to 65,535 (X'0000FFFF')

Usage Notes: The caller selevts the appropriate element(s) of ESEL array for his or her purposes.

CDRGCTL - Get Control Function Definition

Function Description

This function gets a requested control function definition associated with a given CCSID from the CCSID resource repository (see CCSID Resource for a model of the respository). The following control function definitions are defined in the CCSID resource repository model:

Substitute
New Line
Line Feed
Carriage Return
End of File

The SPACE (SP01) definition is included in this function. Each control function definition is found 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

A triplet for each control function may be defined for each of the possible code extention switching states associated with the CCSID.

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

Resources Used

CCSID Resource (see section CCSID Resource).

Function Syntax

CDRGCTL (CCSID1, SEL, N1, N2, CTLFDF, FB)

Input:
Input/Output:
Output:

Status	Reason	Meaning
0000	0000	the function completed successfully
0001	0001	the CCSID1 value is not in the CCSID resource repository
0001	0004	one or more of the requested control function definitions are undefined (as indicated by a zero value for its corresponding state number in CTLFDF)
0001	000A	the requested control function definition element in the CCSID resource for CCSID1 was not found
0002	0001	the CCSID1 value is 0, which is reserved for indicating a default in a hierarchy. The invoker must resolve the default before invoking this function.
0003	0001	CCSID1 has one of the special-purpose CCSID values in the range 65,280 (X'0000FF00') to 65,535 (X'0000FFFF')
0004	0001	the allocated length (value of N1) for the area to contain returned values was insufficient to contain all the output data that is to be returned. See "Data Overflow Convention".
0005	0002	N2 is greater than N1; however, the start of the next block of data to be returned is outside the valid range 1 to N2max
0005	0003	the value specified in the SEL parameter is not supported
0005	000A	N2 is less than or equal to N1, but is not 0
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 invalid in structure
0008	0001	CCSID1 value is not in the range 0 (X'00000000') to 65,535 (X'0000FFFF')
0008	0002	N1 is greater than the maximum permitted in this implementation
0008	000A	N1 is less than 3.
0008	000B	the SEL value is not in the range 0 to 255.

Usage Notes

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. An invoking function can set N1 to 48, to accommodate up to 16 triplets of information without overflow.
The code point value for any control function definition can be in the range X'00000000' to X'7FFFFFFF' , only up to four byte code points can be defined. The code point width values can be 1 to 4 (bytes).

CDRSMXC - Get Short Form (CCSID) with Maximal CS for Specified ES, CP

Function Description: This function gets the CCSID with the largest CS, either maximal or full, for a given CP. The function aids in coexistence and migration; it allows a caller to get an appropriate CCSID when only the CP is known. The ES parameter may be specified to distinguish between usage of the same CP with two different encoding schemes, such as PC Display and PC Data.; The function is restricted to pure single-byte pure double-byte CCSIDs taht have only one CS, CP pair associated with them (for those registered to date).; The CCSID value returned by the function may differ from one implementation to another, as it is dependant on the content of the CCSID resource and the various implementations may support different CCSIDs.
Resources Used: Repository of CCSID Resources (see section CCSID Resource).
Function Syntax

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	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 invalid 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 invalid in structure :insnew acrnum=0055. Text to be inserted follows
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

Some code page identifiers in use in the Far East refer to "pseudo" or "combined" code pages with the PC Mixed and Host Mixed encoding schemes. These identifiers are to be used as CCSIDs rather than CPGIDs. The CDRSMXC function will not return the corresponding CCSIDs for these combined code page identifier values.
When an ESIN value of zero is specified the function will return the first CCSID in the resource with the specified CP and a Full or Maximal size. These may be additional CCSIDs that meet the specified criteria.

Functions for Querying CCSID Relationships

CDRGRDC - Get Related Default CCSID

Function Description

A given CCSID may not be directly usable in many situations. This function allows the invoker to get a nearest equivalent or best-fit related CCSID. The related default is made available in the form of a resource table called Related Default CCSID Table (RDCT) (see section "Related Default CCSID Table (RDCT) Resource" for details). The caller supplies an ES value as an additional key to select the appropriate related CCSID.

Resources Used

Related Default CCSID Table (RDCT) -- see section "Related Default CCSID Table (RDCT) Resource".

Function Syntax

CDRGRDC (CCSID1, ESIN, SEL, CCSIDR, FB)

Input:

Output:

CCSIDR:: this variable contains the returned CCSID value; field-type: 32-bit two's complement binary; a positive number in the range 1 (X'00000001') to 65,279 (X'0000FEFF'). If no related default is found, CCSIDR is set to CCSID1.
FB:: the function returns in this feedback array the processing status (and any associated reason) for this function; field type: 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 Hex) contained in the first 32 bits of FB:

Usage

This function gets a CCSID that is pre-determined to be the "best fit" from a resource table supporting this function , Related Default CCSID Table (RDCT). An ES value is supplied as a key to identify the local environment's needs or characteristic.
The values returned by this function are implementation specific and may vary from system to system.

CDRGCCN - Get CCSID for Normalization

Function Description: When certain operations, such as concatenation or comparison, are performed on graphic character strings, the two strings are both in the same CCSID, or they are normalized first to a single CCSID before concatenation. This function assists in determining the CCSID for normalization given two CCSIDs. The returned CCSID may equal one or both the input CCSIDs.
Resources Used: Normalization Support CCSID Table (NSCT) (see section "Normalization Support CCSID Table (NSCT) Resource").
Function Syntax: CDRGCCN (CCSID1, CCSID2, CCSIDN, HINTV, FB)
Usage Notes: The values returned by this function are implementation specific and may vary from system to system.

Functions Related to Difference Management

CDRCVRT - Convert a Graphic Character String

Function Description

This function converts a graphic character data string of the identified string type (ST1) represented in a specified "from" CCSID (CCSID1) to a graphic character data string of the required string type (ST2) that is represented in another specified "to" CCSID (CCSID2).

The function assumes that the entire string to be converted is known and is passed to the function. Also, the caller has provided sufficient space for the returned converted string. In case of an overflow situation, an orderly truncation would result.

To perform the conversion, a (CCSID1, ST1) to (CCSID2, ST2) entry must exist in the Graphic Character Conversion Selection Table (GCCST), along with the conversion method and conversion tables (see Figure 35 for a model of this table).

An installation may need to support more than one conversion method or conversion table(s) from a given (CCSID1, ST1) to (CCSID2, ST2). Each of these alternatives must have an entry in the GCCST. The Graphic Character Conversion Alternative Selection Number (GCCASN) differentiates the alternatives, if available, for pairs (CCSID1, ST1) to (CCSID2, ST2) from one another.

Note:

The GCCASN is not to be confused with the options used in creating the conversion tables following different criteria for mismatch management; it is used for selecting the appropriate conversion method and associated table(s).

Resources Used

CCSID Resource
Graphic Character Conversion Table (GCCT) repository
Graphic Character Conversion Selection Table (GCCST)

Function Syntax

CDRCVRT (CCSID1, ST1, S1, L1, CCSID2, ST2, GCCASN, L2, S2, L3, L4, FB)

Input

CCSID1:

this variable contains the CCSID value for the input graphic character data string being converted; field-type: 32-bit two's complement binary; a positive value in the range 1 (X'00000001') to 65,279 (X'0000FEFF').

ST1:

this variable contains the type of input string (see "Types of Strings"); field-type: 32-bit two's complement binary; a non-negative number in the range 0 to 255. The following types are defined:

Type Explanation
0: A Graphic Character String, as semantically defined by CCSID1.
1: A Graphic Character String, as semantically defined by CCSID1, and null-terminated. See "Null-terminated string" for the semantics.
2: A Graphic Character String, as semantically defined by CCSID2, and SPACE-padded. See "Padded string" for the semantics.
3: Special Newline Nextline Handling, a complete description is found under Types of Strings.
4-15: String types for bi-directional languages. Details of the characteristics of these string types are found under Types of Strings
16-255: Reserved for future use by CDRA

S1:

this variable contains the starting address of the area in the caller's address space containing the graphic character data to be converted

L1:

this variable contains the length (in number of bytes) of:

the string to be converted when ST1=0 or
the input buffer when ST1=1

contained in the area starting at S1; field-type: 32-bit two's complement binary; a positive number whose maximum value is implementation-specific

CCSID2:

this variable contains the CCSID value for the converted graphic character data string; field-type: 32-bit two's complement binary; a positive value in the range 1 (X'00000001') to 65,279 (X'0000FEFF').

ST2:

this variable contains the type of output string (see "Types of Strings"); field-type: 32-bit two's complement binary; a non-negative number in the range 0 to 255. The following types are defined:

Type Explanation
0: A Graphic Character String, as semantically defined by CCSID2.
1: A Graphic Character String, as semantically defined by CCSID2, and null-terminated. See "Null-terminated string" for the semantics.
2: A Graphic Character String, as semantically defined by CCSID2, and SPACE-padded. See "Padded string" for the semantics.
3: Special Newline Nextline Handling, a complete description is found under Types of Strings.
4-15: String types for bi-directional languages. Details of the characteristics of these string types are found under Types of Strings
16-255: Reserved for future use by CDRA

GCCASN:

this variable contains a number that identifies which conversion alternative is to be selected to convert graphic character data from (CCSID1, ST1) to (CCSID2, ST2); field-type: 32-bit two's complement binary; a non-negative number in the range 0 to 255.

Value Nature of the Conversion Alternative Selected
0: is used to select the designated "installation default" conversion method and table(s) (see GCCASN column definition and Def column definition for a model).
1: is used to select the CDRA-defined default method and associated conversion table(s). The difference management criterion used in the creation of the selected tables is based on country requirements to serve the majority of applications using the selected CCSID pairs.
2 to 9: are reserved for future allocation by CDRA.
10 to 55: are reserved to select other CDRA-defined alternatives; each conversion table selected is created using the round trip mismatch management criterion.
56 to 101: are reserved to select other CDRA-defined alternatives; each conversion table selected is created using the enforced subset mismatch management criterion.
102 to 147: are reserved to select other CDRA-defined alternatives. These alternatives may include conversions where:
148 to 255: are reserved for selecting customer-defined alternatives. A customer organization may establish and control ranges of GCCASN to distinguish between different mismatch management criteria, similar to the IBM-defined ones described above.

L2:

this variable contains the byte-length of the allocated area starting at S2 to contain the converted graphic character data; field-type: 32-bit two's complement binary; a positive number whose maximum value is implementation-specific.

Output

S2:

the converted graphic character data is placed in the area (in the invoker's address space), whose starting address is specified by the invoker in S2; the area's allocated length is given in L2.

Under certain error conditions the output may contain the results of converting only a part of the input string.

L3:

this variable contains the byte-length of the converted string returned in S2; field-type: 32-bit two's complement binary; a positive number whose maximum value is implementation-specific.

The byte-length includes any null termination or padding characters necessary to retain the semantics of CCSID2 and ST2.

L4:

this variable contains a byte-number in the input string; field-type: 32-bit two's complement binary; a non-negative number whose maximum value is implementation-specific. The value of L4 is dependent upon the manner in which the convert function terminates. The values that may be returned are as follows:

When the function detects an output buffer overflow condition, L4 is set to the first byte of the code point representing the next character to be converted in the input string S1.
If the function detects an error in the input string, L4 contains the byte number in the input string S1 that is being processed when the error is detected.
When the conversion is error-free, a value of zero is returned in L4.

FB:

the function returns in this feedback array the processing status (and any associated reason) for this function; field type: 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 Hex) contained in the first 32 bits of FB:

Status	Reason	Meaning
0000	0000	the function completed successfully
0001	0001	the requested conversion is not supported (there is no entry in GCCST for the specified (CCSID1, ST1), (CCSID2, ST2), GCCASN combination)
0001	0005	the requested conversion algorithm specified by GCCASN does not support the specified (CCSID1, ST1) to (CCSID2, ST2) combination
0001	0006	the GCCASN value is 0; but an "installation default" was not found in the GCCST for the pair (CCSID1, ST1) to (CCSID2, ST2)
0002	0001	the CCSID1 value is 0, which is reserved to indicate defaulting to a higher level in a hierarchy. The caller must resolve the default before calling this function.
0002	0002	the CCSID2 value is 0, which is reserved to indicate defaulting to a higher level in a hierarchy. The caller must resolve the default before calling this function.
0003	0001	CCSID1 has one of the special-purpose CCSID values in the range 65,280 (X'0000FF00') to 65,535 (X'0000FFFF')
0003	0002	CCSID2 has one of the special-purpose CCSID values in the range 65,280 (X'0000FF00') to 65,535 (X'0000FFFF')
0004	0001	the length value in L2 allocated for area S2 was too small for the output data. A properly truncated and terminated converted string that fits within the allocated maximum is returned in the area starting at S2 with its byte-length in L3. The value in L4 is set to the first byte of the code point representing the next character to be converted in the input string S1.
0004	0002	the encoding scheme of CCSID1 is X'1301' (mixed Host SB/DB encoding). The length value in L2 allocated for area S2 was too small for the output data. A properly truncated and terminated converted string that fits within the allocated maximum is returned in the area starting at S2 with its byte-length in L3. The value in L4 is set to the first byte of a double-byte character (between SO and SI code points) that would have been converted next in the input buffer.
0005	0001	a pure double-byte CCSID1 was specified and either ST1=0 and L1 is odd, or ST1=1 and an orphan byte was found
0005	0004	ES of CCSID1 is X'1301', and a malformed string -- an odd number of bytes between SO, SI code points -- was encountered
0005	0005	a null-terminated input string was specified using ST1=1; however, there was no null-termination character in S1 within the length L1 specified.
0005	0006	a null-terminated output string was specified using ST2=1; however, the output string contains one or more characters matching the null-termination character, resulting from using the selected conversion tables and methods.
0005	0007	a SPACE-padded output string was specified using ST2=2; however, the definition for SPACE character could not be obtained (the CCSID resource definition did not have an entry for SPACE character definition, or the CCSID resource definition could not be found).
0005	0008	a pure double-byte CCSID2 with ST2=1 was specified, and an odd value was specified for length L2 of the output buffer. The convert function returns only an even number of bytes (maximum L2-1 bytes), including the null-termination character in S2.
0005	0009	a pure double-byte CCSID2 with ST2=2 (SPACE-padded string) was specified, and an odd value was specified for length L2 of the output buffer. The convert function returns L2-1 bytes, including the SPACE-padding characters, in S2.
0005	000C	ES of CCSID1 is X'1301', and a trailing SI bracket is missing.
0005	000D	ES of CCSID1 is X'1301', and a trailing SI code point was encountered without first encountering its corresponding leading SO code point (the number of intervening code points may have been odd or even; the code points would have been treated as single-byte code points because the leading SO was missing)
0006	0001	the selection table (GCCST) could not be found.
0006	0002	a CDRA resource is currently unavailable.
0006	0003	the conversion method identified in the GCCST for the specified selection is currently unavailable.
0006	0004	a conversion table identified in the GCCST for the specified selection could not be found.
0007	0001	the system GCCST resource accessed by the function is found to be invalid in structure.
0007	0002	the system GCCT resource accessed by the function is found to be invalid in structure.
0007	0003	the table type of GCCT does not match the method selected from GCCST.
0008	0001	the CCSID1 value is not in the range 0 (X'00000000') to 65,535 (X'0000FFFF').
0008	0002	the CCSID2 value is not in the range 0 (X'00000000') to 65,535 (X'0000FFFF').
0008	0003	the ST1 value is not in the range 0 to 255.
0008	0004	the ST2 value is not in the range 0 to 255.
0008	0005	L1 is outside the range permitted by this implementation.
0008	0006	L2 is outside the range permitted by this implementation.
0008	0007	GCCASN is not in the range 0 to 255.
0100	0001	one or more input graphic characters were replaced with a "SUB" character specified for the output string.
0100	0002	the conversion specified has resulted in character mismatches.

Usage Notes

Some of the above status and reason code values are possible only when the method selected and the tables used have the capabilities to indicate that a character replacement has occurred (using shadow flags or other equivalent means) or that a substitution with a SUB character was done.
When CDRCVRT terminates with a feedback code indicating that the area allocated for output was insufficient, it is the responsibility of the caller to insure that the remaining portion of the input string is semantically correct prior to making a subsequent call to complete the conversion. For example, in the case of input data with an encoding scheme of X'1301' (mixed Host SB/DB encoding), an SI is added at the end of the truncated output string if required; however, no alteration is made to the input string. If a subsequent call is made with the remainder of the input string, the function will terminate unsuccessfully as an SI will be encountered without a leading SO.
When the encoding associated with a CCSID is such that all graphic character code points are a fixed number of bytes (for example, two for pure double-byte), the assumption is that there are no characters (control or graphic) with a code point width different from that called for by the encoding scheme (other than the termination characters appropriate for the specified input string type) in the input string. The caller is responsible for filtering out any such characters or sequences before calling the function.

CDRMSCI - Multiple-Step Convert Initialize

Function Description

This function is part of the triplet of functions used in a multiple step conversion. It is the initializing function, CDRMSCP is the actual conversion function, and CDRMSCC is the cleanup function.

CDRMSCI performs initialization in preparation for subsequent calls to CDRMSCP. Initialization-related steps performed by the function include:

Locate the appropriate method and conversion table(s)
Allocate workspace
Retrieve and move the method or tables into the execution workspace
Resolve all of the default values that are needed to perform the conversion, applying any specified overrides for them
Initialize all pointers, state flags, or other controlling information associated with the conversion method.

In order for the conversion to be performed, an entry must exist for the specified set of:

From CCSID, To CCSID, From ST, To ST, and GCCASN

in the Graphic Character Conversion Selection Table (GCCST), along with the conversion method and conversion table(s). This function returns a token, which can be used to convert graphic character strings in subsequent calls to CDRMSCP (perform conversion). The token corresponds to a control block (or other equivalent mechanism) in the conversion service. The control block and all the allocated resources and pointers are made available to the invoker for performing conversion without incurring any initialization overhead.

Resources Used

CCSID Resource (see section CCSID Resource)
Graphic Character Conversion Table (GCCT) repository (see section "Graphic Character Conversion Table (GCCT) Resource")
Graphic Character Conversion Selection Table (GCCST) (see section "Graphic Character Conversion Selection Table (GCCST) Resource")

Function Syntax

CDRMSCI (CCSID1, ST1, CCSID2, ST2, GCCASN, TOKEN, FB)

Input

CCSID1:

ST1:

this variable contains the type of input string (see "Types of Strings"); field-type: 32-bit two's complement binary; a non-negative number in the range 0 to 255. The following types are defined:

Type Explanation
0: A Graphic Character String, as semantically defined by CCSID1.
1: A Graphic Character String, as semantically defined by CCSID1, and null-terminated. See "Null-terminated string" for the semantics.
2: A Graphic Character String, as semantically defined by CCSID2, and SPACE-padded. See "Padded string" for the semantics.
3: Special Newline Nextline Handling, a complete description is found under Types of Strings.
4-15: String types for bi-directional languages. Details of the characteristics of these string types are found under Types of Strings
16-255: Reserved for future use by CDRA

CCSID2:

ST2:

this variable contains the type of output string (see "Types of Strings"); field-type: 32-bit two's complement binary; a non-negative number in the range 0 to 255. The following types are defined:

Type Explanation
0: A Graphic Character String, as semantically defined by CCSID2.
1: A Graphic Character String, as semantically defined by CCSID2, and null-terminated. See "Null-terminated string" for the semantics.
2: A Graphic Character String, as semantically defined by CCSID2, and SPACE-padded. See "Padded string" for the semantics.
3: Special Newline Nextline Handling, a complete description is found under Types of Strings.
4-15: String types for bi-directional languages. Details of the characteristics of these string types are found under Types of Strings
16-255: Reserved for future use by CDRA

GCCASN:

Value Nature of the Conversion Alternative Selected

0

is used to select the designated "installation default" conversion method and table(s) (see GCCASN column definition and Def column definition for a model).

1

is used to select the CDRA-defined default method and associated conversion table(s). The difference management criterion used in the creation of the selected tables is based on country requirements to serve the majority of applications using the selected CCSID pairs.

2 to 9

are reserved for future allocation by CDRA

10 to 55

are reserved to select other CDRA-defined alternatives; each conversion table selected is created using the round trip mismatch management criterion.

56 to 101

are reserved to select other CDRA-defined alternatives; each conversion table selected is created using the enforced subset mismatch management criterion.

102 to 147

are reserved to select other CDRA-defined alternatives. These alternatives may include conversions where:

the mismatch management criterion used in creating any of the selected tables is other than round trip or enforced subset
more than one conversion table is selected and unequal criteria have been used when creating the different tables.

148 to 255

are reserved for selecting customer-defined alternatives. A customer organization may establish and control ranges of GCCASN to distinguish between different mismatch management criteria, similar to the IBM-defined ones described above.

Output

TOKEN:

a 256-bit (eight 32-bit two's complement binary numbers) array to contain the value of a token returned by the initialize function. This token must be passed unchanged as an input parameter to subsequent CDRMSCP (Multiple-Step Convert Perform) calls and a closing CDRMSCC (Multiple-Step Convert Clean Up) call.

FB:

Status	Reason	Meaning
0000	0000	the function completed successfully
0001	0001	requested conversion is not supported (there is no entry in GCCST for the specified CCSID1, ST1, CCSID2, ST2, GCCASN combination)
0001	0005	the requested conversion algorithm specified by GCCASN does not support the specified (CCSID1, ST1) to (CCSID2, ST2) combination
0001	0006	the GCCASN value is 0; but an "installation default" was not found in the GCCST, for the pair (CCSID1, ST1) to (CCSID2, ST2)
0002	0001	CCSID1 value is 0, which is reserved to indicate defaulting to a higher level in a hierarchy. The invoker must resolve the default before invoking this function.
0002	0002	CCSID2 value is 0, which is reserved to indicate defaulting to a higher level in a hierarchy. The invoker must resolve the default before invoking this function.
0003	0001	CCSID1 has one of the special-purpose CCSID values in the range 65,280 (X'0000FF00') to 65,535 (X'0000FFFF')
0003	0002	CCSID2 has one of the special-purpose CCSID values in the range 65,280 (X'0000FF00') to 65,535 (X'0000FFFF')
0005	0007	a SPACE-padded output string was specified using ST2=2; however, the definition for SPACE character could not be obtained -- the CCSID resource definition did not have an entry for SPACE character definition, or the CCSID resource definition could not be found.
0006	0001	the selection table (GCCST) was not found
0006	0002	a CDRA resource is currently unavailable
0006	0003	the conversion method identified in the GCCST for the specified selection is currently unavailable
0006	0004	a conversion table identified in the GCCST for the specified selection could not be found.
0006	0007	unable to generate TOKEN as requested
0007	0001	the system GCCST resource accessed by the function is found to be invalid in structure
0007	0002	the system GCCT resource accessed by the function is found to be invalid in structure
0007	0003	the table type of GCCT does not match the method selected from GCCST.
0008	0001	the CCSID1 value is not in the range 0 (X'00000000') to 65,535 (X'0000FFFF')
0008	0002	CCSID2 value is not in the range 0 (X'00000000') to 65,535 (X'0000FFFF')
0008	0003	ST1 value is not in the range 0 to 255
0008	0004	ST2 value is not in the range 0 to 255
0008	0007	GCCASN is not in the range 0 to 255

Usage Notes

See Usage Notes under CDRCVRT.

CDRMSCP - Multiple-Step Convert Perform

Function Description

This function is part of the triplet of functions used in a multiple-step conversion. CDRMSCI is the initializing function, this is the actual conversion function, and CDRMSCC is the cleanup function.

CDRMSCP converts a graphic character data string using the previously allocated control block (along with all the associated resources needed to perform the conversion). The token received from a previous invocation of CDRMSCI (Multiple-Step Convert Initialize) is the mechanism to access the allocated control block.

Resources Used

Graphic Character Conversion Table (GCCT) (see section "Graphic Character Conversion Table (GCCT) Resource")

Function Syntax

CDRMSCP (TOKEN, S1, L1, L2, S2, L3, L4, FB)

Input

TOKEN:

a 256-bit (eight 32-bit binary) array that contains the value of a token obtained by invoking the initialize function CDRMSCI (Multiple-Step Convert Initialize).

S1:

this variable contains the starting address of the area in the invoker's address space containing the graphic character data to be converted

L1:

this variable contains the length (in number of bytes) of:

the string to be converted when ST1=0 or
the input buffer when ST1=1

contained in the area starting at S1; field-type: 32-bit two's complement binary; a positive number whose maximum value is implementation-specific

L2:

Output

S2:

the converted graphic character data is placed in the area (in the invoker's address space), whose starting address is specified by the invoker in S2; the area's allocated length is given in L2.

Under certain error conditions the output may contain the results of converting only a part of the input string.

L3:

this variable contains the byte-length of the converted string returned in S2; field-type: 32-bit two's complement binary; a positive number whose maximum value is implementation-specific.

The byte-length includes any null termination or padding characters necessary to retain the semantics of CCSID2 and ST2.

L4:

When the function detects an output buffer overflow condition, L4 is set to the first byte of the code point representing the next character to be converted in the input string S1.
If the function detects an error in the input string, L4 contains the byte number in the input string S1 that is being processed when the error is detected.
When the conversion is error-free, a value of zero is returned in L4.

FB:

Status	Reason	Meaning
0000	0000	the function completed successfully
0004	0001	the length value in L2 allocated for area S2 was too small for the output data. A properly truncated and terminated converted string that fits within the allocated maximum is returned in the area starting at S2 with its byte-length in L3. The value in L4 is set to the first byte of the code point representing the next character to be converted in the input string S1.
0004	0002	the encoding scheme of CCSID1 is X'1301' (mixed Host SB/DB encoding). The length value in L2 allocated for area S2 was too small for the output data. A properly truncated and terminated converted string that fits within the allocated maximum is returned in the area starting at S2 with its byte-length in L3. The value in L4 is set to the first byte of a double-byte character (between SO and SI brackets) that would have been converted next in the input buffer.
0005	0001	a pure double-byte CCSID1 was specified and either ST1=0 and L1 is odd, or ST1=1 and an orphan byte was found
0005	0004	ES of CCSID1 is X'1301', and a malformed string -- an odd number of bytes between SO, SI bracket -- was encountered
0005	0005	a null-terminated input string was specified using ST1=1; however, there was no null-termination character in S1 within the length L1 specified.
0005	0006	a null-terminated output string was specified using ST2=1; however, the output string contains one or more characters matching the null-termination character, resulting from using the selected conversion tables and methods.
0005	0008	a pure double-byte CCSID2 with ST2=1 was specified, and an odd value was specified for length L2 of the output buffer. The convert function returns only an even number of bytes (maximum L2-1 bytes), including the null-termination character in S2.
0005	0009	a pure double-byte CCSID2 with ST2=2 (SPACE-padded string) was specified, and an odd value was specified for length L2 of the output buffer. The convert function returns L2-1 bytes, including the SPACE-padding characters, in S2.
0005	000C	ES of CCSID1 is X'1301', and a trailing SI bracket is missing.
0005	000D	ES of CCSID1 is X'1301', and a trailing SI code point was encountered without first encountering its corresponding leading SO code point (the number of intervening code points may have been odd or even; the code points would have been treated as single-byte code points because the leading SO was missing)
0006	0006	the token is invalid in structure.
0008	0005	L1 is outside the range permitted by this implementation.
0008	0006	L2 is outside the range permitted by this implementation.
0100	0001	one or more input graphic characters were replaced with a "SUB" character specified for the output string.
0100	0002	the conversion specified have resulted in character mismatches.

Usage Notes

None

CDRMSCC - Multiple-Step Convert Clean Up

Function Description

This function is part of the triplet of functions used in a multiple-step conversion. CDRMSCI is the initializing function, CDRMSCP is the actual c conversion function, and this function is the cleanup function.

CDRMSCC releases the control block and all the allocated resources associated with TOKEN, on behalf of the invoker. All intermediate state or other control information for the conversion methods are also released once the control block (or equivalent internal structures in the common service implementation) is released.

Resources Used

Graphic Character Conversion Table (GCCT) (see "Graphic Character Conversion Table (GCCT) Resource") (for deallocation)

Function Syntax

CDRMSCC (TOKEN, FB)

Input/Output

TOKEN:: a 256-bit (eight 32-bit binary) array that contains the value of a token that was generated by an earlier invocation of the initialize function CDRMSCI (Multiple-Step Convert Initialize). The token is filled with zeros and returned from a successful cleanup.

Output

FB:

Status	Reason	Meaning
0000	0000	the function returned successfully
0006	0006	the token is invalid in structure

Usage Notes

An invalid token condition can be caused by:

The caller did not call CDRMSCI to initialize conversion
The TOKEN value got garbled in the invoker's address space between the CDRMSCI call and the CDRMSCC call
Some system service such as an idle or hung TOKEN cleanup routine may have removed that token value from a list of active tokens.

Functions for Identifying Exception Conditions

CDRXSRF - Extract Status and Reason Codes from Feedback Code

Function Description

This function extracts the values of status and reason codes contained in the 96-bit structure of an input Feedback code. Its purpose is to assist the caller of a function dealing with the status and reason codes as individual values during error handling. An error condition is indicated by a nonzero value in the first 32 bits (the first array element) of the feedback code.

Resources Used

None.

Function Syntax

CDRXSRF (INFB, STATUS, REASON, FB)

Input:

INFB:: this variable is the start of the area containing the input Feedback Code; it is an array of three 32-bit two's complement binary values (96 bits) (see Figure 15).

Output:

STATUS:

this variable contains the status code (value in the first 16 bits of INFB); field type: 32-bit two's complement binary.

REASON:

this variable contains the reason code (value in the second 16 bits of INFB); field type: 32-bit two's complement binary.

FB:

the function returns in this array the processing status (and any associated reason) for this function; field type: array of three 32-bit two's complement binary values (12 bytes, or 96 bits); the status code is a positive number in the first 16 bits and the reason code is a positive number in the second 16 bits. The following are specific meanings of the status code and associated reason code values (in Hex) cont.

Status	Reason	Meaning
0000	0000	the function completed successfully

Usage Notes

None

Back to top