ILE COBOL Language Reference


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.

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--------------------------------+

argument-2

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----------------------------+

The returned value is a national character string consisting of the characters of argument-1 converted to national character representation (CCSID 13488).

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 (13488) is supported on the operating system.

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 13488). 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.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]