Character Data Representation Architecture

 

Chapter 5. CDRA Interface Definitions

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 Templates and Defined Conventions

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:

  1. PARAMETERS: used to specify the desired input and output elements based upon the function to be performed and the output desired.
    1. Parameters are positional.
    2. A comma (,) is used as a delimiter between parameters.
    3. No optional parameters are permitted.
    4. 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).
    5. 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.
    6. 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.
    7. 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.
    8. 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.
    9. 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.
    10. 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.
  2. 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) Figure 15. Structure of the Feedback Code (FB) 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:
      1. 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.
      2. No explicit attempt is made in the CDRA definition to classify the feedback codes into different classes such as INFORMATION, WARNING, or ERROR.
      3. 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'.
  3. 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
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.

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

Return 4 15 11
Second Call Invocation 4 15 11

Return 4 11 7
Third Call Invocation 4 11 7

Return 4 7 3
Fourth Call Invocation 4 7 3

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:

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)

Input:

CCSID1: this variable contains the CCSID value referenced; field-type: 32-bit two's complement binary; a positive number in the range 1 (X'00000001') to 65,279 (X'0000FEFF').

N1: this variable contains the size of the allocated area starting at CSCPL to contain the return data. N1 is specified as a number of elements, and each CS, CP pair is counted as two elements. Field type: 32-bit two's complement binary. It is an even number greater then or equal to 2.

Input/Output:

N2: this variable contains the number of values (each pair of CS and CP is counted as two values) associated with CCSID1 and returned in CSCPL providing that sufficient space (N1) was allocated; field-type: 32-bit two's complement binary. The first invocation of this function must have N2 initialized to zero. The function's handling of the output and value of N2 returned is explained in section "Data Overflow Convention".

Output:

ES:this variable contains the ES associated with CCSID1; field-type: 32-bit two's complement binary. It is a positive number in the range 4352 (X'00001100') to 65,534 (X'0000FFFE').

CSCPL:  the field type of variable CSCPL is an array of 32-bit two's complement binary numbers whose format is CS1, CP1, CS2, CP2,...CSn, CPn.

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 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. A caller can set N1 to 32, to accommodate 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
CDRSCSP (CSCPL, N1, ESIN, CCSIDR, ESR, FB)

Input:

CSCPL: this variable is an array of 32-bit two's compliment binary numbers whose format is CS1, CP1 CS2, CP2,...CSn, CPn. Each CS is a positive number in the range 1(X'00000001') to 65,535(X'0000FFFF'). Each CP is a positive number in the range 1(X'00000001') to 65,534 (X'0000FFFF'). Each is placed in a single CSCPL array element.

N1: this variable contains the number of elements in CSCPL; field-type: 32-bit two's complement binary; a positive number in the range 2 to 32 (can accommodate up to 16 CS and CP pairs).

ESIN: this variable contains the ES value referenced; field-type: 32-bit two's complement binary; a zero, or a positive number in the range 4352 (X'00001100') to 65,534 (X'0000FFFE').

ESIN Meaning
0 the caller does not know the ESID value; the CCSID returned is the first occurring in the CCSID resource repository whose CS and CP values match those specified in CSCPL.
Other the user specifies the ESID value. See Figure 9 for a complete list of ESIDs and their associated meanings.

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'). A value of 65,535 (X'0000FFFF') is returned when the function could not find the requested CCSID.

ESR:  this variable contains the ES value of the returned CCSID; field-type: 32-bit two's complement binary; a zero, or a positive number in the range 4352(X'00001100') to 65,534(X'0000FFFE').

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 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

  1. 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.
  2. 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. 
  3. 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 Sub-elements

Function Description
This function gets the values of the Encoding Scheme identifier (ESID) element and each of its sub-elements 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
CDRGESE (CCSID1, ESEL, FB)

Input:

CCSID1: this variable contains the CCSID value referenced; field-type: 32-bit two's complement binary; a positive number in the range 1 (X'00000001') to 65,279 (X'0000FEFF').

Output:

ESEL: the function returns the values of ES identifier and its three sub-elements in this array of four elements; each element is a 32-bit two's complement binary number:

ESEL
Element Content and Range
1 value of ESID 4352 (X'00001100') to 65,534 (X'0000FFFE')
2 value of basic encoding structure sub-element 1 to 15 (X'00000001' to X'0000000F')
3 value of number of bytes indicator sub-element 1 to 15 (X'00000001' to X'0000000F')
4 value of code extension method sub-element 0 to 254 (X'00000000' to X'000000FE')

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 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 Note

The caller selects 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 repository). The following control function definitions are defined in the CCSID resource repository model:

The SPACE (SP01) definition is included in this function. Each control function definition is found as a triplet consisting of:

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:

CCSID1: this variable contains the CCSID value referenced; field-type: 32-bit  two's complement binary; a positive number in the range 1                                         ('00000001') to 65,279 (X'0000FEFF').

SEL: this variable containing the selection specification; field-type: 32-bit two's complement binary; 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 triplet(s) 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
6 to 255 Reserved for CDRA

N1: 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. field-type: 32-bit two's complement binary. It is a non-zero positive number whose minimum value is 3.

Input/Output:

N2: this variable will contain the number of values returned in CTLFDF; field-type: 32-bit two's complement binary. 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. The function's handling of the output and value of N2 returned is explained in section "Data Overflow Convention".

Output:

CTLFDF: this variable contains the start of the area reserved for the return definition element(s). Each element is a triplet of 3, field-type: 32-bit two's complement binary. 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.

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 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

  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. An invoking 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 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 that 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

CDRSMXC (CPIN, ESIN, CCSIDR, ESR, FB)

Input:

CPIN: this variable contains the CP value referenced; field-type: 32-bit two's complement binary; a positive number in the range 1 (X'00000001') to 65,534 (X'0000FFFE').

ESIN:  this variable contains the ES value referenced;

ESIN Meaning
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.
Other the invoker specifies the ESID value; field-type: 32-bit two's complement binary; a positive number in the range 4352 (X'00001100') to 65,534 (X'0000FFFE'). Only ESIDs that have a single (CS, CP) pair associated with them are valid for this function. See Figure 9 for a complete list of ESIDs and their associated meanings.

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')
ESR:  this variable contains the ES value of the returned CCSID; field-type: 32-bit two's complement binary; a zero, or a positive number in the range 4352 (X'00001100') to 65,534 (X'0000FFFE').

FB: the function returns in this feedback array the processing status (and any associated reason) for this function; field type: array of three-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 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
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. 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.
  2. 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. There 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:

CCSID1: this variable contains the CCSID value referenced; field-type: 32-bit two's complement binary; a positive number in the range 1 (X'00000001') to 65,279 (X'0000FEFF').

ESIN: this variable contains the ES value referenced; field-type: 32-bit two's complement binary; a positive number in the range 4352 (X'00001100') to 65,534 (X'0000FFFE'). See Figure 9 for the list of valid ESIDs and their associated meanings.

SEL: This variable is reserved to identify any specific selection criteria as additional input, for example, to select among two equally valid related defaults; field-type: 32-bit two's complement binary; a non-negative number in the range 0 to 255.

SEL Meaning
0 Installation default
1 to 127 Reserved for use by CDRA
128 to 255 Reserved for customer use

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:

Status Reason Meaning
0000 0000 the function completed successfully
0001 0001 no entry was found in the Related Default CCSID Table(RDCT) resource for the CCSID1, ESIN, and SEL combination specified. The CCSID1 value is copied and returned in CCSIDR.
0002 0001 the CCSID1 value is 0, which is reserved for indicating a default in a hierarchy. It must be resolved before this function is called.
0003 0001 CCSID1 has one of the special- purpose CCSID values in the range 65,280 (X'0000FF00') to 65,535 (X'0000FFFF'); it cannot have a related default
0005 0001 the value of SEL specified is not supported
0006 0001 the RDCT resource was not found
0006 0002 the RDCT resource is currently unavailable
0007 0001 the system RDCT resource accessed by the function is found to be invalid in structure
0008 0001 the CCSID1 value is not in the range 0 (X'0000000') to 65,535 (X'0000FFFF')
0008 0002 the ESIN value is not in the range 4352 (X'00001100') to 65,534 (X'0000FFFE'). The CCSID1 value is copied and returned in CCSIDR.
0008 000B the SEL value is not in the range 0 to 255.

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)

Input:

CCSID1: this variable contains the CCSID value referenced; field-type: 32-bit two's complement binary; a positive number in the range 1 (X'00000001') to 65,279 (X'0000FEFF').

CCSID2: this variable contains the second CCSID value referenced; field-type: 32-bit two's complement binary; a positive number in the range 1 (X'00000001') to 65,279 (X'0000FEFF').

Output:

CCSIDN: this variable contains the returned CCSID value for normalization; field-type: 32-bit two's complement binary; a positive number in the range 1 (X'00000001') to 65,279 (X'0000FEFF').

HINTV: the function returns in this variable a number (field-type: 32-bit two's complement binary) that conveys information to assist the calling function in its subsequent processing. The following values and meanings are defined:

HINTV Meaning
0 No hints
1 CCSID1 and CCSID2 have both the same value for their CP element. The returned CCSIDN has a character set which is a superset of or equals the larger of the character sets of CCSID1 and CCSID2.
2 CCSIDN has the same CP element as CCSID2. The character set of CCSIDN is a superset of or equals the character set of CCSID2. Only the string with CCSID1 needs to be converted to CCSIDN.
3 CCSIDN has the same CP element as CCSID1. The character set of CCSIDN is a superset of or equals the character set of CCSID1. Only the string with CCSID2 needs to be converted to CCSIDN.
4-127 Reserved for use by CDRA.
128-255 Reserved for customer use.

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 there is no entry in the resource -- Normalization Support CCSID Table (NSCT) -- for the pair CCSID1, CCSID2
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')
0006 0001 the NSCT resource was not found
0006 0002 the NSCT resource is currently unavailable
0007 0001 the system NSCT resource accessed by the function is found to be invalid in structure
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')

Usage Notes

The values returned by this function are implementation specific and may vary from system to system.

Functions for character data conversion

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

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:

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-9 are reserved for future allocation by CDRA.
10-55 are reserved to select other CDRA-defined alternatives; each conversion table selected is created using the round trip mismatch management criterion.
56-101 are reserved to select other CDRA-defined alternatives; each conversion table selected is created using the enforced subset mismatch management criterion.
102-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-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
• vST1=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

  1. 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.
  2. 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.
  3. 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:

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

Function Syntax

CDRMSCI (CCSID1, ST1, CCSID2, ST2, GCCASN, TOKEN, 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

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-9 are reserved for future allocation by CDRA.
10-55 are reserved to select other CDRA-defined alternatives; each conversion table selected is created using the round trip mismatch management criterion.
56-101 are reserved to select other CDRA-defined alternatives; each conversion table selected is created using the enforced subset mismatch management criterion.
102-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-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: 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 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: 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
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")

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: 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
0006 0006 the token is invalid in structure

Usage Notes

An invalid token condition can be caused by:

Function 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) contained in the first 32 bits of FB:

Status Reason Meaning
0000 0000 the function completed successfully

Usage Notes

None

Contact IBM

Need assistance with your globalization questions?