Converting national to alphanumeric or DBCS data (DISPLAY-OF)

Use the DISPLAY-OF intrinsic function to convert a national item to a character string represented in the code page that you specify as an argument or with the CCSID compiler option. If you specify an EBCDIC code page that combines SBCS and DBCS characters, the returned string might contain a mixture of SBCS and DBCS characters, with DBCS substrings delimited by shift-in and shift-out characters.

Overriding the default code page

In some cases, you might need to convert data to or from a CCSID that differs from the CCSID specified as the CCSID option value. To do this, use a conversion function in which you specify the code page for the item explicitly.

If you specify a code page as an argument to DISPLAY-OF and it differs from the code page that you specify with the CCSID compiler option, do not use the DISPLAY-OF function result in any operations that involve implicit conversion (such as an assignment to, or comparison with, a national data item). Such operations assume the EBCDIC code page that is specified with the CCSID compiler option.

Conversion exceptions

Implicit or explicit conversion between national and alphanumeric data could fail and generate a severity-40 error. Failures could occur if any of the following occur:
  • The code page that you specified (implicitly or explicitly) is not a valid code page
  • The combination of the CCSID that you specified explicitly or implicitly (such as by using the CCSID compiler option) and the UCS-2 Unicode CCSID (specified explicitly or implicitly such as by using the National CCSID compiler option) is not supported by the operating system.
A character that does not have a counterpart in the target CCSID does not result in a conversion exception. Such a character is converted to a substitution character of the target code page.

The following example shows the use of the NATIONAL-OF and DISPLAY-OF intrinsic functions and the MOVE statement for converting to and from Unicode strings. It also demonstrates the need for explicit conversions when you operate on strings encoded in multiple code pages in the same program.

  PROCESS CCSID(37)
   *...
    01  Data-in-Unicode          pic N(100) usage national.
    01  Data-in-Greek            pic X(100).
    01  other-data-in-US-English pic X(12) value "PRICE in $=".
   *...
        Read Greek-file into Data-in-Greek
        Move function National-of(Data-in-Greek, 00875)
            to Data-in-Unicode
   *...process Data-in-Unicode here ...
        Move function Display-of(Data-in-Unicode, 00875)
            to Data-in-Greek
        Write Greek-record from Data-in-Greek

The above example works correctly: Data-in-Greek is converted as data represented in CCSID 00875 (Greek) explicitly. However, the following statement would result in an incorrect conversion (unless all the characters in the item happen to be among those with a common representation in the Greek and the English code pages): 

 Move Data-in-Greek to Data-in-Unicode

Data-in-Greek is converted to Unicode by this MOVE statement based on the CCSID 00037 (U.S. English) to UCS-2 conversion. This conversion would fail because Data-in-Greek is actually encoded in CCSID 00875.

If you can correctly set the CCSID compiler option to CCSID 00875 (that is, the rest of your program also handles EBCDIC data in Greek), you can code the same example correctly as follows: 

  PROCESS CCSID(00875)
   *...
    01  Data-in-Unicode pic N(100) usage national.
    01  Data-in-Greek pic X(100).
        Read Greek-file into Data-in-Greek
   *... process Data-in-Greek here ...
   *... or do the following (if need to process data in Unicode)
        Move Data-in-Greek to Data-in-Unicode
   *... process Data-in-Unicode
        Move function Display-of(Data-in-Unicode) to Data-in-Greek
        Write Greek-record from Data-in-Greek