Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]
DEC C Run-Time Library Utilities Reference Manual

DEC C Run-Time Library Utilities Reference Manual

Order Number: AA--R238B--TE


January 1999

This manual documents DEC C Run-Time Library utilities used in developing international software applications that manage localization and time zone data.

Revision/Update Information: This is a new manual.

Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1 The content of this document has not changed since OpenVMS Version 7.1.

Compaq Computer Corporation
Houston, Texas


Reprinted January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

© Compaq Computer Corporation 1999. All rights reserved.

The following are trademarks of Compaq Computer Corporation:

Bookreader, DECdirect, DECwindows, Digital, OpenVMS, VAX, VAX DOCUMENT, VAXcluster, VMS, VMScluster, and the DIGITAL logo.

The following are third-party trademarks:

Display POSTSCRIPT and POSTSCRIPT are registered trademarks of Adobe Systems Incorporated.

X/Open is a trademark of X/Open Company Limited.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6494

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index


Preface

The DEC C Run-Time Library Utilities Reference Manual provides detailed usage and reference information about DEC 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 DEC C Run-Time Library to develop applications that manage localization and time zone data.

Document Structure

This manual consists of four chapters.

Related Documents

The following documents provide additional information about the DEC C Run-Time Library utilities:

For additional information on the Open Systems Software Group (OSSG) products and services, access the following OpenVMS World Wide Web address:


http://www.openvms.digital.com 

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:
Internet openvmsdoc@zko.mts.dec.com
Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
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.digital.com:81/ 

If you need help deciding which documentation best meets your needs, call 800-344-4825.

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.)
... 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, if you choose more than one option, you must enclose the choices in parentheses.
[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ } In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
bold text This text style represents the introduction of a new term or 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 device-name contains up to five alphanumeric characters).
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 DEC 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 DEC 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 DEC 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:

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 DEC C Run-Time Library routines:

For details, see the DEC 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 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:

The LOCALE utility supports the following commands:

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:

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:


yearistype year type 

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.

Table 1-2 Time of Day the Rule Becomes Effective
Form Meaning
2 Time in hours
2:00 Time in hours and minutes
15:00 24-hour format time (for times after noon)
1:28:14 Time in hours, minutes, and seconds

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:

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.


Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6494PRO.HTML