| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C |
both | z/OS V1R2 |
#include <sys/layout.h>
int m_wtransform_layout(LayoutObject layout_object,
const wchar_t *InpBuf,
const size_t InpSize,
void *OutBuf,
size_t *Outsize,
size_t *InpToOut,
size_t *OutToInp,
unsigned char *Property,
size_t *InpBufIndex);The m_wtransform_layout() function is part of the support for handling of bidirectional (Bidi) conversion of data between Visual (MVS™) and Implicit (z/OS® UNIX) formats. Initial support is for Arabic and Hebrew data.
Both the input text and output text are wide-character strings. The m_wtransform_layout() function transforms the input text in InpBuf according to the current layout values in layout_object.
Any layout value whose value type is LayoutTextDescriptor describes the attributes of the InpBuf and OutBuf arguments. If the attributes are the same for both InpBuf and OutBuf, a NULL transformation is performed with respect to that specific layout value.
The InpBuf argument specifies the source text to be processed. The InpBuf may not be NULL, except when there is a need to reset the internal state.
The InpSize argument is the number of characters within InpBuf to be processed by the transformation. Its value will not have changed at the return from the transformation. InpSize set to -1 indicates that the text in InpBuf is delimited by a NULL code element. If InpSize is not set to -1, it is possible to have some NULL elements in the input buffer. This might be used, for example, for a one shot transformation of several strings, separated by NULLs.
Each byte will contain relevant property information of the corresponding element in InpBuf, starting from the element pointed by InpBufIndex.
The four rightmost bits of each property byte will contain information for bidirectional environments (when ActiveDirectional is True) and they will mean NestingLevels. The possible value from 0 to 15 represents the nesting level of the corresponding element in the InpBuf, starting from the element pointed by InpBufIndex. If ActiveDirectional is False, the content of NestingLevels bits will be ignored.
The leftmost bit of each property byte will contain a new cell indicator for composed character environments. It will be a value of either 1, for an element in InpBuf that is transformed to the beginning of a new cell, or 0, for the zero-length composing character elements, when these are grouped into the same presentation cell with a non-composing character. Here again, each element of property pertains to the elements in the InpBuf, starting from the element pointed by InpBufIndex. (Remember that this is not necessarily the beginning of InpBuf.)
If none of the transformation properties is required, the argument Property can be NULL.
The use of property can be enhanced in the future to pertain to other possible usage in other environments.
At the return from the transformation, InpBufIndex contains the offset to the first element in the InpBuf that has not been transformed. If the entire substring has been transformed successfully, InpBufIndex will be incremented by the amount defined by InpSize.
Each of these output arguments may be NULL to specify that no output is desired for the specific argument, but at least one of them should be set to non-NULL to perform any significant work.
In addition to the possible outputs above, the layout_object maintains a directional state across calls to the transform functions. The directional state is reset to its initial state whenever any of the layout values TypeOfText, Orientation or ImplicitAlg is modified by means of a call to m_setvalues_layout().
The layout_object argument specifies a LayoutObject returned by the m_create_layout() function.
The OutBuf argument contains the transformed data. This argument can be specified as a NULL pointer to indicate that no transformed data is required. The encoding of the OutBuf argument depends on the ShapeCharset layout value defined in layout_object. If the ActiveShapeEditing layout value is not set (False), the encoding of OutBuf is guaranteed to be the same as the codeset of the locale associated with the LayoutObject defined by layout_object.
On input, the OutSize argument specifies the size of the output buffer in number of wide characters. The output buffer should be large enough to contain the transformed result; otherwise, only a partial transformation is performed. If the ActiveShapeEditing layout value is set (True), the OutBuf should be allocated to contain at least the InpSize multiplied by ShapeCharsetSize.
When the OutSize argument is specified as zero, the function calculates the size of an output buffer large enough to contain the transformed text, and the result is returned in this field. The content of the buffers specified by InpBuf and OutBuf, and the value of InpBufIndex, remain unchanged.
If OutSize = NULL, the EINVAL error condition is returned.
If the InpToOut argument is not a NULL pointer, it points to an array of values with the same number of wide characters as InpBuf, starting with the one pointed by InpBufIndex and up to the end of the substring in the buffer.
On output, the nth value in InpToOut corresponds to the nth wide character in InpBuf. This value is the index (in units of wide characters) in OutBuf that identifies the transformed ShapeCharset element of the nth wide character in InpBuf.
InpToOut may be specified as NULL if no index array from InpBuf to OutBuf is desired.
If the OutToInp argument is not a NULL pointer, it points to an array of values with the same number of wide characters as contained in OutBuf. On output, the nth value in OutToInp corresponds to the nth wide character in OutBuf. This value is the index in InpBuf, starting with the wide character pointed to by InpBufIndex, that identifies the logical code element of the nth byte in OutBuf.
OutToInp may be specified as NULL if no index array from OutBuf to InpBuf is desired.
To perform shaping of a text string without reordering of code elements, the layout_object should be set with input and output layout value TypeOfText set to TEXT_VISUAL, and both in and out of Orientation set to the same value.
If successful, m_wtransform_layout() returns 0.