CONVERT TEXT

Syntax

CONVERT TEXT text INTO SORTABLE CODE hex.

Effect

The content of the data object text is converted to a sortable byte sequence and the result is assigned to the variable hex; the data object text remains unchanged.

The data object text must be of type c or string and the data object hex must be byte-type. The content of text must contain valid characters. The sortable byte sequence is defined platform-specifically such that a standard sorting of several such fields would result in an order in which the source fields text are sorted by the locale defined in the current text environment. The text environment is set when you open an internal session or by using the SET LOCALE statement.

If the data object hex is of type x and its length is not sufficient for the byte sequence, an exception that cannot be handled occurs. If the length is greater than that of the byte sequence, it is filled with hexadecimal 0 on the right. The minimum length for all platforms is calculated as 24 times the length of text plus 24, but can be significantly shorter for some platforms. If hex is of type xstring, its length is adapted automatically.

Notes

To ensure that the CONVERT TEXT statement works, the profile parameter install/collate/active cannot have the value 0.
The CONVERT TEXT statement is intended for filling an index column (in internal tables or extracts) by which the rows of the table or extracts can be sorted according to a locale. Since internal tables and extracts can also be directly sorted according to a locale by using the AS TEXT addition to the SORT statement, CONVERT TEXT is especially useful in the following cases:
An internal table is to be sorted according a locale and a binary search is then to be performed using the READ TABLE statement.
An internal table or extract is to be sorted several times according to a locale. Using a sortable byte sequence ensures better performance that when using the AS TEXT addition.
Indexes for database tables are to be set up according to a locale.

Example

In an internal table, a byte-type column is filled for a character-type column using a sort index created with CONVERT TEXT. The table is first sorted by the text column and then by the sort column, which gives you the same result as when sorting by the text column using the AS TEXT addition. This example generates the same output as the example of SORT for internal tables.

DATA: BEGIN OF text_line,
        sort_indx TYPE xstring,
        text      TYPE string,
      END OF text_line,
      text_tab LIKE HASHED TABLE OF text_line
               WITH UNIQUE KEY sort_indx.

text_line-text = `Muller`.
PERFORM fill_text_tab.
text_line-text = `Möller`.
PERFORM fill_text_tab.
text_line-text = `Moller`.
PERFORM fill_text_tab.
text_line-text = `Miller`.
PERFORM fill_text_tab.

SORT text_tab BY text.
PERFORM write_text_tab.

SET LOCALE LANGUAGE 'D'.
SORT text_tab BY sort_indx.
PERFORM write_text_tab.

FORM fill_text_tab.
  CONVERT TEXT text_line-text
          INTO SORTABLE CODE text_line-sort_indx.
  INSERT text_line INTO TABLE text_tab.
ENDFORM.

FORM write_text_tab.
  FIELD-SYMBOLS <line> LIKE text_line.
  LOOP AT text_tab ASSIGNING <line>.
    WRITE / <line>-text.
  ENDLOOP.
  SKIP.
ENDFORM.

Exceptions

Non-Catchable Exceptions

Cause: One of the operands has an invalid data type.
Runtime Error: CONVERT_TEXT_BAD_OP
Cause: The source field has invalid content.
Runtime Error: CONVERT_TEXT_BAD_SRC
Cause: The target field is too small.
Runtime Error: CONVERT_TEXT_DEST_TOO_SHORT