CONVLIT | NOCONVLIT

Pragma equivalent

Purpose

Turns on string literal code page conversion.

When the CONVLIT option is in effect, the compiler changes the assumed code page for character and string literals within the compilation unit.

When the NOCONVLIT option is in effect, the default code page, or the code page specified by the LOCALE option is used.

Syntax


   .-NOCONV-.                                          
>>-+-CONV---+--+-----------------------------------+-----------><
               |                  .-, NOWCHAR-.    |   
               '-(--+----------+--+-----------+--)-'   
                    '-codepage-'  +-, WCHAR---+        
                                  '-, UNICODE-'

Defaults

NOCONVLIT(, NOWCHAR)

Parameters

codepage: You can use an optional suboption to specify the code page that you want to use for string literals.
NOWCHAR: The default is NOWCHAR. Only wide character constants and string literals made up of single byte character set (SBCS) characters are converted. If there are any shift-out (SO) and shift-in (SI) characters in the literal, the compilation will end with an error message.
WCHAR: Instructs the compiler to change the code page for wide character constants and string literals declared with the L'' or L"" prefix.
UNICODE: The z/OS® XL C/C++ compiler interprets the CONVLIT(, UNICODE) suboption as a request to convert the wide string literals and wide character constants (wchar_t) to Unicode (UCS-2) regardless of the code page used for conversion of string literals and character constants (char). The conversion is supported for wide string literals and wide character constants that are coded using characters from the basic character set defined by the Programming languages - C (ISO/IEC 9899:1999) standard. The behavior is undefined if wide string literals and wide character constants are coded using characters outside the basic character set.

Usage

The CONVLIT option affects all the source files that are processed within a compilation unit, including user header files and system header files. All string literals and character constants within a compilation unit are converted to the specified codepage unless you use #pragma convlit(suspend) and #pragma convlit(resume) to exclude sections of code from conversion. See z/OS XL C/C++ Language Reference for more information on #pragma convlit.

The CONVLIT option only affects string literals within the compilation unit. The following determines the code page that the program uses:

If you specified a LOCALE, the remainder of the program will be in the code page that you specified with the LOCALE option.
If you specify the CONVLIT option with empty sub option list, CONVLIT() or -qconvlit=, the compiler preserves any previous settings of the suboptions. It will not use the default code page, or the code page specified by the LOCALE option. For example, -Wc,'CONVLIT(IBM-273) CONVLIT()' is interpreted as CONVLIT(IBM-273,NOWCHAR).

The CONVLIT option does not affect the following types of string literals:

literals in the #include directive
literals in the #pragma directive
literals used to specify linkage, for example, extern "C"
literals used for the __func__ variables

If #pragma convlit(suspend) is in effect, no string literals or character constants (wide included) will be converted.

If #pragma convert is in effect, string literals and character constants will be converted, but wide string literals and wide character constants are not affected by #pragma convert, even when the CONVLIT(, UNICODE) suboption is specified.

If you specify PPONLY with CONVLIT, the compiler ignores CONVLIT.

If you specify the CONVLIT option, the codepage appears after the locale name and locale code set in the Prolog section of the listing. The option appears in the END card at the end of the generated object module.

Notes:

Although you can continue to use the __STRING_CODE_SET__ macro, you should use the CONVLIT option instead. If you specify both the macro and the option, the compiler diagnoses it and uses the option regardless of the order in which you specify them
The #pragma convert directive provides similar functionality to the CONVLIT option. It has the advantage of allowing more than one character encoding to be used for string literals in a single compilation unit. For more information on the #pragma convert directive, see z/OS XL C/C++ Language Reference.

IPA effects

The CONVLIT option only controls processing for the IPA step for which you specify it.

During the IPA compile step, the compiler uses the code page that is specified by the CONVLIT option to convert the character string literals.

Predefined macros

None.

Examples

The result of the following specifications is the same:

NOCONV(IBM-1027) CONV
CONV(IBM-1027)

Related information

For more information on the LOCALE compiler option, see LOCALE | NOLOCALE.