Calling the bidi conversion services

This section describes how to use the bidi and character shaping services to transform character data to accommodate bidirectional texts. For example, you can transform text to a form suitable for display.

The bidi transformation works with character conversion. The character conversion service can perform CCSID conversions or CCSID conversions with bidi transformations.

The bidi support operates on CCSID 1200. If the source and target CCSIDs are not both 1200 (or equivalent CCSIDs), the bidi algorithm will cause a two-stage conversion to be performed regardless of any other considerations. The source buffer is first converted to CCSID 1200, bidi transformations are performed, and then the characters are converted to the target CCSID. The work buffer (Wrk_Buf) is required for this.

Note: Use of the extended bidi support for CCSIDs other than Arabic or Hebrew CCSIDs 00420, 00424, 00425, 00856, 00862, 00864, 00916, 01046, 01089, 01255, 01256 will result in a RC = CUN_RC_USER_ERR and a RS = CUN_RS_CCSID_NOT_SUPP.

The bidi support meets some of the standards set forth in the Unicode Consortium's Standard Annex #9. The annex can be found at the Unicode Consortium's website http://www.unicode.org/reports/tr9.

There are two different levels of bidi support:

The B technique. This support:
- Is requested by adding the letter B to the technique field.
- Uses parameters Bidi_Context and Bidi_ImpAlg in the Flag1 field in the character conversion parameter area (CUNBCPRM or CUN4BCPR).
- Invokes an older version of the bidi algorithm. This support is equivalent to the bidi transformation service (CUNLBIDI and CUN4LBID).
- Can be used only with parameter area versions 1 and 2.
The extended bidi support. This support:
- Is requested by setting the Extended_Bidi_Parm_Area_Ptr.
- Uses parameters in the extended bidi parameter area (CUNBDPRM or CUN4BDPR).
- Iinvokes a newer version of the bidi algorithm.
- Can be used beginning with parameter area version 3.

IBM does not intend to enhance the B technique support. Instead, it is recommended that you use the extended bidi support for all new development and those who want to use the highest level of bidi support.

If you have code that uses the B technique and you want to change your code to use parameter area version 3, you can no longer use the B technique. In this situation, you must also change your code to use the extended bidi support.

To change your code from the B technique to use the extended bidi support, do the following:

Use parameter area version 3 and provide the DDA size required for parameter area version 3.
Set the Extended_Bidi_Parm_Area_Ptr and remove B from the technique letters.
Instead of setting Flag1 bits Bidi_Context and Bidi_ImpAlg, use fields Context_Src and ImplicitAlg in the extended bidi parameter area.
Set all other fields in the extended bidi parameter area as appropriate.

Using the extended bidi support requires an extended bidi parameter area.

The extended bidi parameter area is defined by structures CUNBDPRM (for 31-bit service) and CUN4BDPR (for 64-bit service). This parameter area is different than the bidi parameter area defined by the bidi transformation service.

Many of the field names in the extended bidi parameter area specify attributes of either the source or target character string. This is denoted by Src or Targ in the field name. For example, Context_Targ specifies the context for the target string.