Compaq C Run-Time Library Utilities Reference Manual
Compaq C Run-Time Library Utilities Reference
Manual
Order Number:
AA--R238C--TE
April 2001
This manual documents Compaq C Run-Time Library utilities used in
developing international software applications that manage localization
and time zone data.
Revision/Update Information:
This manual supersedes the Compaq C Run-Time Library Utilities Reference Manual, Version 7.1.
Software Version:
OpenVMS Alpha 7.3
OpenVMS VAX Version 7.3
Compaq Computer Corporation Houston, Texas
© 2001 Compaq Computer Corporation
Compaq, VAX, VMS, and the Compaq logo, Registered in U.S. Patent and
Trademark Office.
OpenVMS is a trademark of Compaq Information Technologies Group, L.P.
in the United States and other countries.
All other product names mentioned herein may be trademarks of their
respective companies.
Confidential computer software. Valid license from Compaq required for
possession, use, or copying. Consistent with FAR 12.211 and 12.212,
Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government
under vendor's standard commercial license.
Compaq shall not be liable for technical or editorial errors or
omissions contained herein.
The information in this document is provided "as is" without warranty
of any kind and is subject to change without notice. The warranties for
Compaq products are set forth in the express limited warranty
statements accompanying such products. Nothing herein should be
construed as constituting an additional warranty.
ZK6494
The Compaq OpenVMS documentation set is available on CD-ROM.
Preface
The Compaq C Run-Time Library Utilities Reference Manual provides detailed usage and reference information about
Compaq C Run-Time Library utilities for managing localization and time
zone data in international software applications.
Intended Audience
This manual is for programmers who use the Compaq C Run-Time Library to
develop applications that manage localization and time zone data.
Document Structure
This manual consists of four chapters.
- Chapter 1 introduces the GENGAT, ICONV, LOCALE, and ZIC
programming utilities.
- Chapter 2 explains the locale definition source file and
describes the standard locale categories that Compaq supports.
- Chapter 3 discusses the character set description (
charmap
) file, which defines character symbols as character encodings.
- Chapter 4 provides complete command descriptions for the XPG4
and ZIC utilities.
Related Documents
The following documents provide additional information about the Compaq
C Run-Time Library utilities:
- Compaq C Run-Time Library Reference Manual for OpenVMS Systems
- OpenVMS Version 7.0 New Features Manual
For additional information about Compaq OpenVMS products and
services, access the Compaq website at the following location:
http://www.openvms.compaq.com/
|
Reader's Comments
Compaq welcomes your comments on this manual. Please send comments to
either of the following addresses:
|
Internet
|
openvmsdoc@compaq.com
|
|
Mail
|
Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698
|
How to Order Additional Documentation
Use the following World Wide Web address to order additional
documentation:
http://www.openvms.compaq.com/
|
If you need help deciding which documentation best meets your needs,
call 800-282-6672.
Conventions
The following conventions are used in this manual:
|
Ctrl/
x
|
A sequence such as Ctrl/
x indicates that you must hold down the key labeled Ctrl while
you press another key or a pointing device button.
|
|
PF1
x
|
A sequence such as PF1
x indicates that you must first press and release the key
labeled PF1 and then press and release another key or a pointing device
button.
|
|
[Return]
|
In examples, a key name enclosed in a box indicates that you press a
key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as
brackets, rather than a box.
|
|
...
|
A horizontal ellipsis in examples indicates one of the following
possibilities:
- Additional optional arguments in a statement have been omitted.
- The preceding item or items can be repeated one or more times.
- Additional parameters, values, or other information can be entered.
|
.
.
.
|
A vertical ellipsis indicates the omission of items from a code example
or command format; the items are omitted because they are not important
to the topic being discussed.
|
|
( )
|
In command format descriptions, parentheses indicate that you must
enclose choices in parentheses if you specify more than one.
|
|
[ ]
|
In command format descriptions, brackets indicate optional choices. You
can choose one or more items or no items. Do not type the brackets on
the command line. However, you must include the brackets in the syntax
for OpenVMS directory specifications and for a substring specification
in an assignment statement.
|
|
|
|
In command format descriptions, vertical bars separate choices within
brackets or braces. Within brackets, the choices are optional; within
braces, at least one choice is required. Do not type the vertical bars
on the command line.
|
|
{ }
|
In command format descriptions, braces indicate required choices; you
must choose one of the options listed. Do not type the braces in the
command line.
|
|
bold text
|
This typeface represents the introduction of a new term. It also
represents the name of an argument, an attribute, or a reason.
|
|
italic text
|
Italic text indicates important information, complete titles of
manuals, or variables. Variables include information that varies in
system output (Internal error
number), in command lines (/PRODUCER=
name), and in command parameters in text (where
dd represents the predefined code for the device type).
|
|
UPPERCASE TEXT
|
Uppercase text indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
|
|
Monospace text
|
Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the
following elements: keywords, the names of independently compiled
external functions and files, syntax summaries, and references to
variables or identifiers introduced in an example.
|
|
-
|
A hyphen at the end of a command format description, command line, or
code line indicates that the command or statement continues on the
following line.
|
|
numbers
|
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
indicated.
|
Chapter 1
Overview
The Compaq C Run-Time Library utilities help you to manage localization
and time zone data for international software applications.
Localization and time zone data is defined separately from the
application and is bound to it only at run time.
The Compaq C Run-Time Library includes the following utilities:
1.1 Creating XPG4-Compliant Localizing Applications
To help you develop localizing applications for use internationally,
the OpenVMS operating system offers, as part of its Compaq C Run-Time
Library, several utilities that support the XPG4 model (X/Open
Portability Guide Issue 4) of internationalization. The following
XPG4-compliant utilities are provided:
These tools are useful only for applications written to the XPG4 model.
1.1.1 Creating and Invoking Message Catalogs
A message catalog is a binary file that contains the messages an
application displays or writes. This file includes all the messages
that the application issues, for example, error messages, information
messages, screen displays, and prompts. To create message catalogs, use
the GENCAT command.
GENCAT reads one or more input source files and the existing catalog
file, if one exists. The source file is a text file that you create to
hold the messages that your program might print. Use any text editor to
enter messages into the source file. If you identify multiple source
files, GENCAT processes them one after the other in the sequence that
you specify them. Each successive source file modifies the catalog.
Before you or your application issues GENCAT, create the required input
source file and, if appropriate at this time, the catalog file.
For more detailed information about the GENCAT command, see
Chapter 4.
1.1.1.1 Message Source File
When you create an input source file, follow these guidelines:
- Group your messages into sets to represent functional subsets of
the program.
- Give each message a numeric identifier, which must be unique
within its set.
- Add commands recognized by GENCAT for manipulating sets and
individual messages.
1.1.1.2 Message Catalog File
If a message catalog with the name catfile exists, GENCAT
creates a new version of the file that includes the contents of the
older version and then modifies it. If the catalog does not exist,
GENCAT creates it with the name catfile.
1.1.1.3 Retrieving Messages from a Message Catalog
OpenVMS applications retrieve messages from a message catalog using the
following Compaq C Run-Time Library routines:
For details, see the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.
1.1.2 Performing Codeset Conversions
The ICONV utility provides the following commands to create a
conversion table file from a conversion source file and, using this
file, to convert characters from one codeset to another:
- The ICONV COMPILE command creates a conversion table file.
- Using this conversion table file, the ICONV CONVERT command then
converts characters in another, specified file from one codeset to
another.
The ICONV commands support any 1- to 4-byte codesets that are state
independent.
Note
There is a restriction in the tocodeset encodings in this
implementation. The characters in tocodeset must not use 0XFF
in the fourth byte.
|
1.1.2.1 Creating Conversion Tables
To create a conversion table file, issue the DCL command ICONV COMPILE:
ICONV COMPILE sourcefile tablefile
See the description of the ICONV COMPILE command in Chapter 4 for
the format of the conversion source file.
See the description of the ICONV CONVERT command in Chapter 4 for
the tablefile naming convention.
1.1.2.2 Converting from One Codeset to Another
To convert characters in a file from one codeset to another codeset,
issue the ICONV CONVERT command:
ICONV CONVERT infile outfile
/FROMCODE=fromcodeset /TOCODE=tocodeset
The converted characters are written to the output file parameter
outfile.
1.1.3 Setting International Environment Logical Names
The LOCALE utility is an OpenVMS XPG4 localization utility that:
- Compiles a binary locale file for use by utilities and C routines
dependent on the setting of the international environment logical names
- Loads a locale name into system memory as shared, read-only global
data
- Displays a summary of the current international environment as
defined on your system and details of locales on your system
- Unloads a locale name from system memory
The LOCALE utility supports the following commands:
- The LOCALE COMPILE command converts a locale source file into a
binary locale file for use by utilities and C routines. This command
allows you to add new locales to your system in addition to those
specified by Compaq.
To compile a locale, the LOCALE COMPILE
command uses two source files:
- A locale definition source file that contains categories that
describe a locale.
Locale categories, described in Table 4-3, include LC_COLLATE,
LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME.
- A character set description (charmap) file that defines the
character set for the locale. The charmap, which defines character
symbols as character encodings, is the source file for a coded
character set (see Chapter 3).
- The LOCALE LOAD command loads a locale name into system memory as
several shared, read-only, global sections. All processes that access
the loaded locale use this one copy of the locale, thereby reducing
overall demand on system memory.
- The LOCALE UNLOAD command unloads a specified locale name from
system memory.
- 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. A
charmap file has the file type .CMAP.
- The LOCALE SHOW CURRENT command displays a summary of the current
international environment as defined by several logical names
representing locale categories. This command lists the settings for
each locale category and the values of the environment variables LC_ALL
and LANG. 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.
- The LOCALE SHOW PUBLIC command lists all the public locales on the
system, including locales listed in the directory defined by the
logical name SYS$118N_LOCALE as well as system locales supplied by the
Compaq C Run-Time Library.
- The LOCALE SHOW VALUE command displays the value of one or more
keywords from the current international environment. Locale categories
and keywords in each category are listed in Table 4-4.
For more information about LOCALE commands, see Chapter 4.
1.2 Creating Time Zone Conversion Information
Using the Zone Information Compiler (ZIC) utility, the ZIC compiler
creates binary files containing time zone conversion information. These
files are generated from the time zone source files that you specify.
The lines in the source files consist of fields. To create a valid time
zone source file, follow these formatting requirements:
- Any number of white space characters separate the fields.
- Leading and trailing white spaces on input lines are ignored.
- An unquoted number sign (#), the sharp character,
in the input line introduces a comment that extends to the end of the
line where this sign appears.
- White space characters and sharp characters can be enclosed in
double quotation marks (" ") if they are to be used as
part of a field.
- Any line that is blank after comment stripping is ignored.
- Non-blank lines are expected to be one of three types:
1.2.1 Rule Lines
A rule line has the following form:
Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
|
An example is as follows:
Rule USA 1969 1973 - Apr lastSun 2:00 1:00 D
|
The rule line consists of the following fields:
NAME
Gives the arbitrary name of the set of rules that this rule is part of.
FROM
Gives the first year in which the rule applies. The word minimum, or an
abbreviation, means the minimum year with a representable time value.
The word maximum, or an abbreviation, means the maximum year with a
representable time value.
TO
Gives the final year in which the rule applies. In addition to minimum
and maximum as defined in FROM, minimum or maximum (or an abbreviation)
only may be used to repeat the value of the FROM field.
TYPE
Gives the type of year in which the rule applies. If TYPE is - , then
the rule applies in all years between FROM and TO inclusively. ZIC
executes the following command to check the type of year:
An exit status of 1 means that the year is of the given type; an exit
status of 5 means that the year is not of the given type.
IN
Gives the month in which the rule takes effect. Month names may be
abbreviated.
ON
Gives the day on which the rule takes effect. Table 1-1 shows the
recognized forms.
Table 1-1 Day the Rule Becomes Effective
| Form |
Meaning |
|
5
|
Fifth of the month
|
|
lastSun
|
Last Sunday in the month
|
|
lastMon
|
Last Monday in the month
|
|
Sun>=8
|
First Sunday on or after the 8th
|
|
Sun<=25
|
Last Sunday on or before the 25th
|
Names of days of the week may be abbreviated or spelled out in full.
Note that there must be no spaces within the ON field.
AT
Gives the time of day when the rule takes effect. Table 1-2 shows
the recognized forms.
Any of these forms may be followed by the letter w if
the given time is local wall clock time, or the letter
s if the time is local standard time. In the
absence of either the letter w or the letter
s, wall clock time is assumed.
SAVE
Gives the amount of time to be added to local standard time when the
rule is in effect. This field has the same format as the AT field,
although, of course, the letter w and
s suffixes are not used.
LETTER/S
Gives the variable part of time zone abbreviations to be used
when this rule is in effect; as for example, the S or
D in EST or EDT. If this field is - , the
variable part is null.
1.2.2 Zone Lines
A zone line has the following form:
Zone NAME GMTOFF RULES/SAVE FORMAT UNTIL
|
An example is as follows:
Zone Australia/South-west 9:30 Aus CST 1987 Mar 15 2:00
|
The zone line consists of the following fields:
NAME
Gives the name of the time zone. This name is used in creating the time
conversion information file for the zone.
GMTOFF
Gives the amount of time to add to Greenwich mean time (GMT) to get
standard time in this zone. This field has the same format as the AT
and SAVE fields of rule lines. If time must be subtracted from GMT,
begin the field with a minus sign.
RULES/SAVE
Gives the name of the rule(s) that apply in the time zone, or
alternatively, an amount of time to add to local standard time. If this
field is - , standard time always applies in the time zone.
FORMAT
Gives the format for time zone abbreviations in this time zone. The
pair of characters %s is used to show where the
variable part of the time zone abbreviation goes.
UNTIL
Gives the time at which the GMT offset, or the rule(s) change for a
location. It is specified as the following:
A year
A month
A day
A time of day
If UNTIL is specified, the time zone information is generated from the
given GMT offset and rule change until the time specified.
If you specify UNTIL, the next line must be a continuation
line. The continuation line has the same form as the zone line except
that the string Zone and the name are omitted, for the
continuation line places information starting at the time specified in
the UNTIL field in the previous line in the file used by the previous
line. Continuation lines may contain an UNTIL field, just as zone lines
do, indicating that the next line is a further continuation.
|
