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.