Category
Portability and migration
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.
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.