Document revision date: 19 July 1999

Converts characters in a file from one codeset to another codeset. The converted characters are written to an output file.

Format

ICONV CONVERT infile outfile

Parameters

infile

Required.

Name of the file that contains the characters to be converted. The /FROMCODE qualifier specifies the codeset of the characters in this file.

outfile

Required.

Name of the file created by ICONV CONVERT. The /TOCODE qualifier specifies the codeset of the characters in this file.

Qualifiers

/FROMCODE=fromcodeset

Required.

Specifies the codeset of the characters in infile.

/TOCODE=tocodeset

Required.

Specifies the codeset of the characters in outfile.

Description

The ICONV CONVERT command converts the characters in infile from the codeset identified by the /FROMCODE qualifier to the codeset identified by the /TOCODE qualifier. The converted file is written to outfile.

The conversion is done in one of two ways:

• Using a conversion table file to look up the converted characters. This is the default method. Conversion table files are created by the DCL command ICONV COMPILE.
• Using a shareable image file that implements the required conversion. This method can be used whenever the implementation of a converter by table is either not convenient, for example, huge virtual address space versus small space by algorithm, or not possible, for example, for state dependent encoding like ISO2022.

The converter's file naming convention, valid for both table or image file type of implementations, is:

fromcodeset_tocodeset.iconv

Note If you add conversion files to your system, they must use the same file-naming convention.

ICONV CONVERT searches your current directory for a converter file. If it cannot find the file, it then searches the system directory defined by the logical name SYS$I18N_ICONV.

Examples

$ ICONV CONVERT /FROMCODE=EUCTW /TOCODE=DECHANYU -
_$ FROMFILE.DAT TOFILE.DAT
 
      

This example shows a conversion from EUCTW characters to DECHANYU characters. The EUCTW characters in the file FROMFILE.DAT are converted to the corresponding DECHANYU characters. The converted characters are stored in the file TOFILE.DAT.

Converts a locale source file into a binary locale file. The binary locale file is used by those utilities and C routines that are dependent on the setting of the international environment logical names.

Format

LOCALE COMPILE sourcefile

Parameters

sourcefile

Required.

Name of the locale source file, which defines each category of the locale. The default file type for the source file is .LSRC. For the definition of the locale source file format, see Chapter 2.

Qualifiers

/CHARACTER_DEFINITIONS=filename

/NOCHARACTER_DEFINITIONS

Optional. Default: /NOCHARACTER_DEFINITIONS

Specifies a character-set description file (charmap) for the locale. This file maps characters to their actual character encodings.

If a charmap is not specified, no symbolic names (other than collating symbols defined in a collating symbol keyword) are allowed in the locale source file.

For a definition of the charmap file format, see Chapter 3. The default file type for a charmap is .CMAP.

/DISPLAY[=[NO]HOLE]

Optional. Default: /DISPLAY=NOHOLE

Used with certain Chinese locales and terminals to specify that 4-byte characters occupy four printing positions (columns) on the terminal display. The default value (/DISPLAY=NOHOLE) specifies that 4-byte characters occupy two printing positions.

/IGNORE=WARNINGS

/NOIGNORE

Optional. Default: /NOIGNORE

Generates an output file even if LOCALE COMPILE issues warning messages. Use the /IGNORE keyword cautiously because the warnings could indicate user errors that you might want to correct before using the resulting locale file.

/LISTING[=filename]

/NOLISTING

Optional. Batch default: /LISTING; interactive default: /NOLISTING

Name of the listing file. The /SHOW qualifier controls the information included in the listing file. If the file name is omitted, the default is sourcefile.LIS.

/OUTPUT=[filename]

/NOOUTPUT

Optional. Default: /OUTPUT=sourcefile.LOCALE

Name of the output file. Public locales are stored in the directory defined by the logical name SYS$I18N_LOCALE. If the output file is in any other location, the locale is private.

/NOOUTPUT results in no output file creation, even if the compilation succeeds.

/SHOW[=(keyword[,...])]

Optional. Default: /SHOW=(SOURCE,TERMINAL)

/SHOW, together with /LISTING, controls the information included in the listing file. You can specify the following keywords:

Keyword	Description
ALL	Include all information.
BRIEF	Include a summary of the symbol table.
[NO]CHARACTER_DEFINITIONS	Include or omit the charmap file.
NONE	Do not print any information. The listing file contains only the generated error messages.
[NO]SOURCE	Include or omit a listing of the source file.
[NO]STATISTICS	Include or omit compiler performance information.
[NO]SYMBOLS	Include or omit a listing of the charmap symbol table.
[NO]TERMINAL	Display compiler messages at the terminal.

Description

Use the LOCALE COMPILE command to add new locales to your system in addition to those supplied by Digital. To compile a locale, LOCALE COMPILE requires two files:

• A charmap file that defines the character set for the locale. If you do not specify a charmap file, symbolic names cannot be specified in the locale source file. If this happens, LOCALE COMPILE issues an error or warning message, depending on the category processed, and no output file is produced. (Also see the /IGNORE qualifier.)
• A locale source file. This file describes one or more of the locale categories: LC_CTYPE, LC_COLLATE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME.

errors

The following error messages are related to the LOCALE COMPILE command:

• %LOCALE-E-CASEALRDY, case conversion already exists for 'character'
  Where character is a character from the codeset. This error can occur when the locale compiler is processing the LC_CTYPE category. It indicates that more than one case conversion is specified for character.

• %LOCALE-E-PREOFCMAP, premature end of file in charmap file
  Occurs if there is no END CHARMAP statement in the charmap file.
• %LOCALE-E-PREEOFSRC, premature end of file in source file
  Occurs if there is an error with the END statements in the locale source file.
• %LOCALE-F-NOADDSYM, failed to add symbol to symbol table
  Occurs when there is insufficient memory to finish the compilation. Check the amount of memory available to your process.
• %LOCALE-F-NOINITSYM, failed to initialize symbol table
  Occurs if memory is insufficient to finish the compilation. Check the amount of memory available to your process.

Examples

$ LOCALE COMPILE EN_GB_ISO8859-1 /CHARACTER_DEFINITIONS=ISO8859-1 - 
_$ /LIST /SHOW=(CHARACTER_DEFINITIONS,SYMBOLS,STATISTICS)  
 
      

This example shows how to generate a locale file named EN_GB_ISO8859-1.LOCALE from the source file EN_GB_ISO8859-1.LSRC, using the charmap file ISO8859-1.CMAP. To use this locale file, copy it to the SYS$I18N_LOCALE directory and set the LANG logical to "EN_GB.ISO8859-1". The listing file contains a listing of the charmap file, the symbol table, performance information, and any error messages generated by the compiler.

Loads the specified locale name into the system's memory as shared, read-only global data.

Format

LOCALE LOAD locale_identifier

Parameters

locale_identifier

Required.

Character string that identifies the locale to be loaded. Specify one of the following:

• Name of the public locale
  Specifies the public locale. Use the format:

  language_country.codeset[@modifier]

  
  LOCALE LOAD searches for the public locale binary file in the location defined by the logical name SYS$I18N_LOCALE. The file type defaults to .LOCALE. The period (.) and at-sign (@) characters in the name specified are replaced by underscore (_) characters.
  For example, if the name specified is "zh_CN.dechanzi@radical", LOCALE LOAD searches for the following binary locale file:
  SYS$I18N_LOCALE:ZH_CN_DECHANZI_RADICAL.LOCALE

• Name of a file
  Specifies the binary locale file. This can be any valid file specification. If either the device or directory is not specified, LOCALE LOAD first applies the current caller's device and directory as defaults. If the file is not found, the device and directory defined by the SYS$I18N_LOCALE logical name are used as defaults. The file type defaults to .LOCALE.
  Wildcards are not valid. The binary locale file cannot reside on a remote node.

Qualifiers

None.

Description

The LOCALE LOAD command loads the specified locale name into the system's memory as several shared, read-only, global sections. All processes that access the loaded locale then use this one copy of the locale, thereby reducing overall demand on system memory.

This DCL command is privileged, typically issued by the system manager. The following privileges are required:

• SYSGBL
• PRMGBL

Examples

$ LOCALE LOAD JA_JP_DECKANJI
      

This example shows how to load the JA_JP_DECKANJI locale.

Unloads the specified locale name from system memory.

Format

LOCALE UNLOAD locale

Parameters

locale

Required.

Character string that identifies the locale to be unloaded. See the LOCALE LOAD command for acceptable formats for this parameter.

Qualifiers

None.

Description

The LOCALE UNLOAD command unloads the specified locale name from the system's memory. If a process is accessing the locale when the UNLOAD command is entered, the global sections are deleted after the process deaccesses the locale.

This DCL command is privileged, typically issued by the system manager. The following privileges are required:

• SYSGBL
• PRMGBL

Note You can unload only locale files loaded with the LOCALE LOAD command.

Examples

$ LOCALE UNLOAD JA_JP_DECKANJI
      

This example shows how to unload the JA_JP_DECKANJI locale.

Lists character set description files (charmaps).

Format

LOCALE SHOW CHARACTER_DEFINITIONS

Parameters

None.

Qualifiers

None.

Description

The LOCALE SHOW CHARACTER_DEFINITIONS command lists the names of the character set description files (charmaps) in the public directory defined by the logical name SYS$I18N_LOCALE.

A charmap defines the symbolic names and values of characters in a coded character set. Charmaps are used by the LOCALE COMPILE command when compiling a locale. A charmap file has the file type .CMAP.

Examples

$ LOCALE SHOW CHARACTER_DEFINITIONS
 
[SYS$I18N.LOCALES.SYSTEM]DECHANYU 
[SYS$I18N.LOCALES.SYSTEM]DECHANZI 
[SYS$I18N.LOCALES.SYSTEM]DECKANJI 
[SYS$I18N.LOCALES.SYSTEM]DECKOREAN 
[SYS$I18N.LOCALES.SYSTEM]EUCJP 
[SYS$I18N.LOCALES.SYSTEM]EUCTW 
[SYS$I18N.LOCALES.SYSTEM]ISO8859-1 
[SYS$I18N.LOCALES.SYSTEM]ISO8859-2 
[SYS$I18N.LOCALES.SYSTEM]ISO8859-3 
[SYS$I18N.LOCALES.SYSTEM]ISO8859-4 
[SYS$I18N.LOCALES.SYSTEM]ISO8859-5 
[SYS$I18N.LOCALES.SYSTEM]ISO8859-7 
[SYS$I18N.LOCALES.SYSTEM]ISO8859-8 
[SYS$I18N.LOCALES.SYSTEM]ISO8859-9 
[SYS$I18N.LOCALES.SYSTEM]MITACTELEX 
[SYS$I18N.LOCALES.SYSTEM]SDECKANJI 
[SYS$I18N.LOCALES.SYSTEM]SJIS 
 
      

This example displays the names of the charmap files, all in the SYS$I18N_LOCALE directory.

Displays a summary of the current international environment as defined by several international environment logical names.

Format

LOCALE SHOW [CURRENT]

Parameters

None.

Qualifiers

None.

Description

The LOCALE SHOW CURRENT command lists the settings for each locale category and the values of the environment variables LC_ALL and LANG.

The CURRENT keyword is the default and is, therefore, optional. The logical name that defines a category has the same name as the category. For example, the LC_MESSAGES logical name defines the setting for the LC_MESSAGES category. Table 4-3 describes the locale categories.

Table 4-3 Locale Categories

Category	Description
LC_COLLATE	Information about collating sequences
LC_CTYPE	Information about character classification
LC_MESSAGES	Information about the language of program messages and the format of yes/no prompts
LC_MONETARY	Information about monetary formatting
LC_NUMERIC	Information about formatting numbers
LC_TIME	Information about time and date

Each locale category is defined by scanning the following logical names in the order shown, until a logical name is found. If the logical name found does not represent a valid locale file, LOCALE SHOW displays the string "C" for all the categories.

1. LC_ALL
2. Logical names corresponding to the categories specified in the table (For example, if LC_NUMERIC is specified as a valid locale category, the LOCALE SHOW CURRENT command displays the name of the category and the locale name it defines.)
3. LANG
4. SYS$LC_ALL
5. The system default for the locale categories as specified by the SYS$* logical names. (For example, the default for the category LC_NUMERIC is defined by the SYS$LC_NUMERIC logical name.)
6. SYS$LANG

The system manager can choose to define SYS$* logicals in the site-specific system startup files to set the default locale. If no definition is provided, programs operate using the built-in "C" locale, in which case the LOCALE SHOW CURRENT command displays the string "C" for the current locale categories.

errors

If any logical names that define the environment are improperly defined, no warning message is issued. However, the actual international environment is listed exactly as it would be seen by an application that uses the DEC C Run-Time Library routine setlocale (for instance, if in the previous example the SPECIAL.LOCALE file does not exist, then the display for the LC_MESSAGES category would show LC_MESSAGES="C").

Examples

$ DEFINE LC_COLLATE EN_US.ISO8859-1 ! NOTE: the collate category in unquoted 
$ DEFINE LANG EN_GB_ISO8859-1 
$ DEFINE LC_MESSAGES PRIVATE$DISK:[APPL.LOCALES]SPECIAL.LOCALE 
$ LOCALE SHOW CURRENT 
 
LANG="EN_GB_ISO8859-1" 
LC_CTYPE="EN_GB_ISO8859-1" 
LC_COLLATE=EN_US_ISO8859-1 
LC_TIME="EN_GB_ISO8859-1" 
LC_NUMERIC="EN_GB_ISO8859-1" 
LC_MONETARY="EN_GB_ISO8859-1" 
LC_MESSAGES=PRIVATE$DISK:[APPL.LOCALES]SPECIAL.LOCALE;1 
LC_ALL= 
 
      

This example shows a process where all locale categories except LC_COLLATE and LC_MESSAGES have defaulted to the same locale, EN_GB.ISO8859-1. A setting enclosed in double quotation marks indicates that the setting is implied by the setting of one of the following logical names: LANG, LC_ALL, SYS$LC_ALL, or SYS$LANG. A setting not enclosed by double quotes indicates that the logical name for that category defines the international environment. This example also shows that if a locale category is specified by a complete file specification, then the complete file specification is displayed.

Lists all the public locales on the system.

Format

LOCALE SHOW PUBLIC

Parameters

None.

Qualifiers

None.

Description

The LOCALE SHOW PUBLIC command lists all the public locales on the system. The set of public locales contains all the locales that reside in the directory defined by the logical name SYS$I18N_LOCALE as well as the system's built-in locales supplied with the DEC C Run-Time Library.

Examples

$ LOCALE SHOW PUBLIC
 
C (Built-in) 
POSIX (Built-in) 
[SYS$I18N.LOCALES.SYSTEM]EN_GB_ISO8859_1 
[SYS$I18N.LOCALES.SYSTEM]EN_US_ISO8859_1 
[SYS$I18N.LOCALES.SYSTEM]FR_CA_ISO8859_1 
[SYS$I18N.LOCALES.SYSTEM]GRBAGE_LOCALE (bad file header checksum) 
[SYS$I18N.LOCALES.SYSTEM]JA_JP_DECKANJI (Permanently Loaded) 
 
      

This example shows a system with three locale files in the SYS$I18N_LOCALE directory. The C and POSIX locales are built in with the system and, therefore, cannot be found in the SYS$I18N_LOCALE directory.

This example also shows the effect of having a bad file or a nonlocale file in the public directory and the effect of having a locale file loaded into the system's memory by the LOCALE LOAD command.

Displays the value of one or more keywords from the current international environment.

Format

LOCALE SHOW VALUE name

Parameters

name

Required. Specifying more than one name is valid.

Name of one of the following:

• Keyword
  • If you specify a keyword, the value of that keyword in the current locale is displayed.
  • For integer keywords that have no value assigned, the value CHAR_MAX (127) is displayed.
  • When a keyword value includes semicolons, double quotes, backslashes, or control characters, they are preceded by an escape character (usually a backslash).
• Category
  If you specify a category, the values of the keywords in that category are displayed.

Table 4-4 lists the categories and keywords you can specify.

Table 4-4 Locale Categories and Keywords

Category	Keyword	Keyword Description
LC_CTYPE		Character classification names
LC_TIME	DAY	Full weekday names
	ABDAY	Abbreviated weekday names
	MON	Full month names
	ABMON	Abbreviated month names
	D_T_FMT	Date and time format
	D_FMT	Date format
	T_FMT	Time format
	T_FMT_AMPM	Time format in the 12-hour clock
	AM_PM	Defines how the ante meridiem (a.m.) and post meridiem (p.m.) strings are represented
	ERA	Defines how years are counted and displayed for eras in a locale
	ERA_D_FMT	Era date format
	ERA_D_T_FMT	Era date and time format
	ERA_T_FMT	Era time format
	ALT_DIGITS	String defining alternative symbols for digits
LC_NUMERIC	DECIMAL_POINT	Character used as a decimal delimiter
	THOUSANDS_SEP	Character used to group digits to the left of the decimal delimiter
	GROUPING	Defines how characters to the left of the decimal delimiter are grouped
LC_MONETARY	INT_CURR_SYMBOL	Character string representing the international currency symbol.
	CURRENCY_SYMBOL	String used as the local currency symbol.
	MON_DECIMAL_POINT	Character used as a decimal delimiter when formatting monetary quantities.
	MON_THOUSANDS_SEP	Character used as a separator for groups of digits to the left of the decimal delimiter.
	POSITIVE_SIGN	String used to represent positive monetary quantities.
	NEGATIVE_SIGN	String used to represent negative monetary quantities.
	INT_FRAC_DIGITS	Number of digits displayed to the right of the decimal delimiter when formatting monetary quantities using the international currency symbol.
	FRAC_DIGITS	Number of digits displayed to the right of the decimal delimiter when formatting monetary quantities using the local currency symbol.
	P_CS_PRECEDES	For positive monetary values, this is set to 1 if the local currency symbol precedes the number and 0 if the symbol follows the number.
	N_CS_PRECEDES	For negative monetary values, this is set to 1 if the local currency symbol precedes the number and 0 if the symbol follows the number.
	P_SEP_BY_SPACE	For positive monetary values, this is set to 0 if there is no space between the currency symbol and the value, 1 if there is a space, and 2 if there is a space between the symbol and the sign string.
	N_SEP_BY_SPACE	For negative monetary values, this is set to 0 if there is no space between the currency symbol and the value, 1 if there is a space, and 2 if there is a space between the symbol and the sign string.
	P_SIGN_POSN	Integer used to indicate where the POSITIVE_SIGN string should be placed.
	N_SIGN_POSN	Integer used to indicate where the NEGATIVE_SIGN string should be placed.
	MON_GROUPING	Defines how digits are grouped when formatting monetary values.
LC_MESSAGES	YESSTR	String representing YES in the current locale.
	NOSTR	String representing NO in the current locale.
	YESEXPR	Expression representing an affirmative response in the current locale.
	NOEXPR	Expression representing a negative response in the current locale.

---

Previous

Next

Contents

Index

	privacy and legal statement
6494PRO_005.HTML