NATIONAL-OF

The NATIONAL-OF function returns a national character string consisting of the UCS-2 representation of the characters in argument-1. The type of the function is national.

Read syntax diagramSkip visual syntax diagram
Format 1: Specify source CCSID

>>-FUNCTION NATIONAL-OF--(--argument-1--+------------+--)------><
                                        '-argument-2-'      

argument-1
Must be of class alphabetic, alphanumeric, or DBCS. Argument-1 identifies the source string for the conversion.
IBM Extension
IBM Extension argument-2 End of IBM Extension
IBM Extension

Must be an integer. Argument-2 identifies the source code page for the conversion. Argument-2 must be a valid CCSID number identifying an EBCDIC, ASCII, UTF-8, or EUC code page. The EBCDIC or ASCII CCSID can identify a code page that is SBCS, DBCS, or mixed SBCS/DBCS.

If argument-2 is omitted, the source code page is the one in effect for the CCSID compiler option when the source code was compiled. If the source code page is 65535, then default CCSID 37 will be used.

End of IBM Extension
End of IBM Extension

The returned value is a national character string consisting of the characters of argument-1 converted to national character representation (UCS-2 CCSID specified in the National CCSID compiler option or in the NTLCCSID PROCESS option). See "Conversions and Precision" in the IBM® Rational® Development Studio for i: ILE COBOL Programmer's Guide for more information.

When a source character cannot be converted to a national character, the source character is converted to the system-defined substitution character X'FFFD'. No exception condition is raised.

The length of the returned value depends on the content of argument-1 and the characteristics of the source code page.

Exceptions: If the conversion fails, a severe run-time error occurs. Verify that the conversion from the source CCSID to the target CCSID (CCSID specified in the National CCSID compiler option or in the NTLCCSID PROCESS option) is supported on the operating system.

Read syntax diagramSkip visual syntax diagram
Format 2: Specify user substitution character

>>-FUNCTION NATIONAL-OF--(--argument-1--argument-3--)----------><

argument-1
Must be of class alphabetic, alphanumeric, or DBCS. Argument-1 identifies the source string for the conversion.
argument-3
Must be a national literal or national data item with one character position in length.

Argument-3 specifies a national substitution character used in conversion of alphanumeric characters for which there is no corresponding national character.

The source code page is the one in effect for the CCSID compiler option when the source code was compiled. If the CCSID compiler option is 65535, then default CCSID 37 will be used.

The returned value is a national character string consisting of the characters of argument-1 converted to national character representation (CCSID specified in the National CCSID compiler option or in the NTLCCSID PROCESS option). When a source character cannot be converted to a national character, the source character is converted to the user substitution character argument-3. No exception condition is raised.

The length of the returned value depends on the content of argument-1 and the characteristics of the source code page.

Exceptions: If the conversion fails, a severe run-time error occurs. Verify that the conversion from the source ccsid to the target CCSID (UCS-2) is supported on the operating system.