Calling the case conversion services

This is a general description of how the case conversion services have to be called.

The 31 bit caller has to provide:

Source buffer pointer (31-bit pointer), ALET (4 byte), and length (8 byte)
Target buffer pointer (31-bit pointer), ALET (4 byte), and length (8 byte)
Dynamic data area pointer (31 bit pointer), ALET (4 byte), and length (8 byte)
Conversion type (or case conversion handle in subsequent calls)
- Simple casing to upper or to lower
- Locale independent special casing to upper or to lower
- Locale dependent special casing to upper or to lower
Flags

The 64-bit caller has to provide:

Source buffer pointer (64 bit pointer), ALET (4 byte), and length (8 byte)
Target buffer pointer (64 bit pointer), ALET (4 byte), and length (8 byte)
Dynamic data area pointer (64 bit pointer), ALET (4 byte), and length (8 byte)
Conversion type (or case conversion handle in subsequent calls)
- Simple casing to upper or to lower
- Locale independent special casing to upper or to lower
- Locale dependent special casing to upper or to lower
Flags

Note: A dynamic data area (DDA) must always be specified. The required length is defined by constant CUNBAPRM_DDA_Req for AMODE (31) and CUN4BAPR_DDA_Req for AMODE (64).

When the service returns, it replaces the source and target buffer pointers and lengths. Thus the caller can see how many bytes were converted and how much of the target buffer is filled up. Return codes and reason codes notify when a target buffer overflow was detected or any other critical case happened.

The conversion type is given initially. A call always returns a case conversion handle which is a fast path for the conversion services to the case conversion table and its properties. In subsequent calls, IBM® recommends that you provide the case conversion handle. If the caller wants to request the case conversion handle without converting any data, it can be done by specifying a source buffer length of 0.

The caller can put the conversion data in any dataspace. To allow the service to access the data, an ALET must be specified. An ALET of 0 indicates that the data is in the primary address space.