General concepts when using the z/OS Unicode Services programming interfaces

z/OS Unicode Services provides services in the form of programming interfaces. These are sometimes referred to as application programming interfaces, or APIs. An example of one is the "character conversion service".

Many of these interfaces use the same concepts and field types, such as:
Parameter area
Each programming interface defines a parameter area or an area of storage provided by the caller and used to pass data to the service and to get results back from the service.
Parameter area defaults
Each service defines a constant to initialize the parameter area to default values.
Note: The default value is not necessarily all binary zeroes.

A typical use for the default initializer constant is to initialize the parameter area before changing it to reflect the specific inputs required.

Dynamic Data Area (DDA) required
Some of the services require callers to define a DDA or an area of storage needed and used by the service to perform its function. This storage should be on a word boundary, but does not have to be initialized because it will be modified by the service. The size of the DDA required depends on things such as the parameter area version used, the function selected, and details such as the character data in the source buffer. Most services define a DDA length that is sufficient to accommodate all requests. It is recommended that this length be used.
Parameter area version
Most of the parameter areas define a "version" parameter. The initial version is typically 1 and then incrementally advanced as the parameter area gets larger to accommodate more parameters. The version level controls things such as how big the parameter area is, how much DDA is required, the functions that are available, and what parameter values are valid. It is recommended that new applications be written to use the latest Unicode Services parameter area version.
ALET support
z/OS Unicode Services interfaces generally allow its DDA and buffers to reside in any address space located by an Access List Entry Token (ALET).
Abstract character data
Abstract character data is a stream of bytes that represent abstract characters. For example, in EBCDIC CCSIDs, the abstract character data bytes x'C9C2D4' represent the abstract characters 'IBM'. Abstract character data is usually referred to as character data or character strings.
Buffers
z/OS Unicode Services that operate on abstract character data have parameters for a source buffer and target buffer. Some services also require a work buffer to store intermediate results. Each buffer is defined by three parameters: a pointer to the buffer, the buffer's ALET, and the buffer's length in bytes.
Note: z/OS Unicode Services typically increment the pointer and decrement the length to indicate how much of the buffer has been used.
Buffer sizes
z/OS Unicode Services that operate on abstract character data have different requirements for target buffer size. The recommended target buffer size is typically a function of the source buffer size and the function requested. For example, when converting from 1-byte Unicode to 2-byte Unicode, the target buffer is typically twice the size of the source buffer. Each API documents its buffer size requirements. The same example applies to the size required for work buffers. Maximum buffer size is limited only by system resources.
Conversion data
Conversion data refers to the data z/OS Unicode Services needs to perform a conversion, such as tables that map from ASCII to EBDCIC. It does not refer to the caller's source buffer. For example, when the character conversion service is called to convert from CCSID 00037 to CCSID 00437, it needs a control block with information about the conversion (information such as both CCSIDs are single-byte) and it needs a 256 byte table to translate the character data. Conversion data is not normally exposed by Unicode Services. The conversion data is stored within the Unicode environment and various interfaces use a 'conversion handle' to refer to conversion data.
Return and reason codes
Generally, z/OS Unicode Services communicate by setting return code and reason code parameters. These values should always be checked when the API returns control.
Note: The parameter area may be left in an inconsistent state when there is a program interrupt.
See Unicode return and reason codes for return and reason codes.
Parameters not validated
z/OS Unicode Services do not validate the parameter area before using it. If the parameter area is not filled in properly, unexpected results may occur, including incorrect results, bad return codes, or program interrupts. Unicode Services does not generally monitor for internal errors. The caller is responsible for handling errors.
Page-fixed storage
Callers running with key 0-7 can request that conversion data be loaded into page-fixed storage within the Unicode environment as a way to improve performance by reducing the number of page faults. However, there is no guarantee that the conversion request will result in conversion data being loaded because the conversion data may already be loaded into non-page-fixed storage. To ensure your conversion is loaded into page-fixed storage, you need to work with your system programmer to implement with a PARMLIB member.
Using page-fixed storage is not recommended. There is no guarantee that performance will improve if the conversion is page-fixed.
Note: Callers are free to page-fix the storage they pass into z/OS Unicode Services APIs. Also, z/OS Unicode Services modules themselves are not-page fixed and z/OS Unicode Services is not guaranteed to run with dynamic address translation (DAT) off.
Invoking the z/OS Unicode Services interfaces
z/OS Unicode Services are normally invoked by calling a routine provided by linking a stub routine into application code. These stub routines are located in SYS1.CSSLIB. Some interfaces can be invoked by branching to a control offset, as shown in System control offsets. This technique may improve performance by eliminating some parameter checking. It is recommended that most customers use the stub routines provided.