Conversion handle use

Some z/OS Unicode Services define a 'conversion handle' parameter. Conversion handles are generated automatically by the conversion service and are available as a way to improve performance.

When a conversion service is invoked, it attempts to locate the conversion data needed:

If a conversion handle is not provided (for example, it is set to all binary zero), the service resolves the resources needed, then generates a handle to them and stores the handle in the parameter area.
If a conversion handle is provided, the service checks if the conversion handle is valid. If it is valid, the service does not resolve to the resources specified because it already has this information.

Once the conversion handle is either generated or validated, the service uses it to perform the conversion.

One use of the conversion handle is when you have multiple conversions with the same conversion data and want to optimize performance. For example, when you have multiple buffers that all require the same conversion. Unicode Services lets you re-use conversion handles, saving the effort of re-generating the conversion handle. However, re-using conversion handles requires more from the caller.

The sophisticated usage pattern is:

Set the conversion handle to all binary 0.
Optional: Invoke the conversion service with an empty source buffer, only to generate the conversion handle. If this step is omitted, the handle will be generated in the next step.
Set values into the parameter area, leaving alone the conversion handle. Next, invoke the conversion service and check the return code.
Repeat the previous step, making sure to reset any values changed by the conversion service. If you have a different conversion to perform (such as a different source CCSID or target CCSID), also set those values into the parameter area and zero out the conversion handle before repeating the previous step.

Note:

If a handle is provided, it is used regardless of the settings of the parameters used to generate it (such as the From CCSID).
If the handle needs to be re-generated, the parameter area values will be used to re-generate the handle. It is recommended that you do not modify these key parameters if you are also re-using handles.
Handles are invalidated when the Unicode environment changes, such as when adding or deleting a conversion. For example, with the SETUNI DELETE,ALL,FORCE=YES command that may be needed when conversion data is updated via a PTF. Conversion handles are not valid between IPLs of the system. When the conversion service is given an invalid handle, it either returns with an error or generates a valid conversion handle and continues, depending on the setting of the Inv_Handle flag in the Flag1 parameter. It is recommended that most customers set the Inv_Handle flag to 1 to regenerate a new handle.