Overview of the layout functions

The layout functions are used to handle bidirectional languages correctly, to transform text from a format readable for the user to a format suitable for processing, and vice-versa. The layout functions include the following:

m_create_layout(): called at the beginning of the application to create the layout object that will be used by the other layout functions.
m_setvalues_layout(): sets the values that will be used inside the transform. m_setvalues_layout() must be called before calling m_transform_layout or m_wtransform_layout. This function is optional. Use this function if you need to change the values for the bidirectional attributes. You can eliminate it from the application, and use a modifier instead.
m_getvalues_layout(): queries the current layout values within a layout object.
m_transform_layout(): does the actual processing to convert the text format between different bidirectional layouts, according to the settings of the LayoutObject. Nothing will change if this function (or its wide character equivalent) is not called inside the application.
m_wtransform_layout(): works the same as m_transform_layout(), except that it handles Unicode wide characters (wchar_t) .
m_destroy_layout(): called at the end of the application to destroy the layout object, and free up the allocated memory used by the layout object.

Those functions can be used to convert text from logical (implicit) unshaped forms to visual (display) shaped forms and vice versa. The layout functions also handle conversion of numerals.

Table 1 lists supported layout attributes and their corresponding values. These are the attributes most commonly used to provide Bidi support. Each attribute has input and output values that can be specified for the layout transformation process. The default value for each attribute is indicated in the table.

A full list of attributes and values is available in X/Open Portable Layout Services: Context-dependent and Directional Text. Some attributes listed in Table 1 are specific to the z/OS implementation and are noted with an asterisk (*) symbol.

You can set Bidi Layout Values in two ways:

The m_setvalues_layout() function requires the Layout Attribute Names and Values to be specified by using keywords presented in columns 1 and 2.
The m_create_layout() function allows a string to be passed to set the values. This string is preceded with the "@ls" characters and requires the names and values to be used as displayed in column 3. Multiple attribute and value pairs can be separated by commas in the following form:
```
@ls <attribute_name1>=<input1>:<output1>,
<attribute_name2>=<input2>:<output2>...
```
Example:
```
@ls orientation=ltr:ltr,typeoftext=implicit:visual,
numerals=nominal:national, swapping=no:yes,
bidiroundtrip=true
```

Table 1. Layout attribute and values
Attribute Name	Attribute values	Modifier layout string names and values (@ls)		Description
Orientation	ORIENTATION_CONTEXTUAL ORIENTATION_LTR (Default) ORIENTATION_RTL	Name:	orientation=	The direction of the text.
Orientation		Values:	contextual ltr rtl	The direction of the text.
Context	CONTEXT_LTR (Default) CONTEXT_RTL	Name:	context=	Contextual orientation when the orientation attribute is set to `ORIENTATION_CONTEXTUAL`
Context	CONTEXT_LTR (Default) CONTEXT_RTL	Values:	ltr rtl
TypeofText	TEXT_EXPLICIT TEXT_IMPLICIT (Input default) TEXT_VISUAL (Output default)	Name:	typeoftext=	Type of the text.
TypeofText		Values:	explicit implicit visual	Type of the text.
Swapping	SWAPPING_NO (Input default) SWAPPING_YES (Output default)	Name:	swapping=	Specifies if symmetric swapping is enabled.
Swapping	SWAPPING_NO (Input default) SWAPPING_YES (Output default)	Values:	no yes	Specifies if symmetric swapping is enabled.
Numerals	NUMERALS_CONTEXTUAL (Output default in Arabic locale) NUMERALS_NATIONAL NUMERALS_NOMINAL (Input default, Output default in Hebrew locale)	Name:	numerals=	How numerals are shaped. (Only valid for Arabic.)
Numerals		Values:	contextual national nominal	How numerals are shaped. (Only valid for Arabic.)
TextShaping	TEXT_NOMINAL (Input default, Output default in Hebrew locale) TEXT_SHAPED (Output default in Arabic locale)	Name:	shaping=	Specifies if text is to be shaped. (Only valid for Arabic.)
TextShaping		Values:	nominal shaped	Specifies if text is to be shaped. (Only valid for Arabic.)
ShapeCharset	IBM-1046 IBM-1089 IBM-1256 IBM-420 IBM-424 IBM-425 IBM-53668 IBM-864 ISO8859-6 UCS-2 (Default)	Name:	shapcharset=	Code set of the output buffer to result from layout transformation.
ShapeCharset		Values	IBM-1046 IBM-1089 IBM-1256 IBM-420 IBM-424 IBM-425 IBM-53668 IBM-864 ISO8859-6 UCS-2 (Default)
InputCharset*	IBM-1046 IBM-1089 IBM-1256 IBM-420 IBM-424 IBM-425 IBM-53668 IBM-864 ISO8859-6 UCS-2	N/A		Code set of the input buffer to use in layout transformation. The default value is the code set of the loaded locale.
BidiRoundTrip*	BIDIROUNDTRIP_OFF (Default) BIDIROUNDTRIP_ON	Name:	bidiroundtrip=	Specifies if the Bidi roundtrip algorithm is enabled. To take proper effect, BidiRoundTrip must be enabled in both legs of the layout transformations that complete the roundtrip.
BidiRoundTrip*	BIDIROUNDTRIP_OFF (Default) BIDIROUNDTRIP_ON	Values:	false true