Digital PDFs

AA-PHEQC-TE

November 1996

126 pages

Original

0.8MB

Document:	DECnet-Plus DECdts Programming
Order Number:	AA-PHEQC-TE
Revision:	0
Pages:	126
Original Filename:	dts_prg.PDF

OCR Text

DECnet-Plus
DECdts Programming
Order Number: AA–PHEQC–TE
November 1996
This manual contains Digital Distributed Time Service (DECdts) time
routine reference information and describes the time-provider interface
(TPI).

Revision/Update Information:

This manual supersedes the
DECnet/OSI DECdts Programming
guide.

Operating System:

OpenVMS VAX Version 7.1
OpenVMS Alpha Version 7.1
Digital UNIX Version 4.0

Software Version:

DECnet-Plus for OpenVMS Version 7.1
DECnet/OSI for Digital UNIX Version
4.0
DECdts Version 1.1

Digital Equipment Corporation
Maynard, Massachusetts

November 1996
Digital Equipment 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 Digital or an authorized sublicensor.
Digital conducts its business in a manner that conserves the environment and protects the safety
and health of its employees, customers, and the community.
© Digital Equipment Corporation 1996. All rights reserved.
The following are trademarks of Digital Equipment Corporation: Bookreader, DDCMP, DEC,
DECdirect, DECnet, DECNIS, DECserver, DECsystem, DECwindows, Digital, DNA, InfoServer,
OpenVMS, PATHWORKS, ULTRIX, VAX, VAX DOCUMENT, VAXcluster, VAXstation, VMS,
VMScluster, and the DIGITAL logo.
The following are third-party trademarks:
Motif, OSF, OSF/1, OSF/Motif, and Open Software Foundation are registered trademarks of the
Open Software Foundation, Inc.
OSI is a registered trademark of CA Management, Inc.
UNIX is a registered trademark in the United States and other countries, licensed exclusively
through X/Open Company Ltd.
Spectracom, Traconex, Hopf, and Heath are the registered trademarks of Spectracom Corporation,
Traconex Corporation, Hopf Elektronik GmbH, and the Heath Company, respectively.
All other trademarks and registered trademarks are the property of their respective holders.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vii

1 Introduction to the DECdts API
1.1
1.1.1
1.1.2
1.2
1.2.1
1.2.2
1.2.3
1.2.4
1.2.5
1.3
1.4
1.4.1
1.4.2

DECdts Time Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Absolute Time Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Relative Time Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Time Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The utc Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The tm Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The timespec Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The reltimespec Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The OpenVMS Time Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DECdts API Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking Programs with the DECdts API . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking Programs on DECnet-Plus for OpenVMS systems . . . . . . . . .
Linking Programs on DECnet-Plus for Digital UNIX systems . . . . . . .

1–1
1–2
1–3
1–5
1–6
1–6
1–7
1–7
1–7
1–7
1–7
1–8
1–8

2 DECdts Portable Applications Programming Interface
2.1

DECdts API Routine Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_abstime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_addtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_anytime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_anyzone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_ascanytime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_ascgmtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_asclocaltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_ascreltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_binreltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_bintime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_boundtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_cmpintervaltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_cmpmidtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_gettime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_getusertime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_gmtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_gmtzone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_localtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_localzone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkanytime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2–1
2–6
2–8
2–10
2–13
2–15
2–17
2–19
2–21
2–22
2–24
2–26
2–28
2–31
2–34
2–35
2–37
2–39
2–42
2–44
2–46

iii

utc_mkascreltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkasctime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkbinreltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkbintime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkgmtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mklocaltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkreltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkvmsanytime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkvmsgmtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mkvmslocaltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_mulftime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_multime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_pointtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_reltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_spantime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_subtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_vmsanytime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_vmsgmtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
utc_vmslocaltime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2–49
2–51
2–53
2–54
2–56
2–58
2–60
2–62
2–64
2–65
2–67
2–69
2–70
2–72
2–74
2–76
2–78
2–79
2–81

3 Using the DECdts API Routines
4 Time-Provider Interface
4.1
General TPI Control Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2
Message Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.1
The Time Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.2
Time Response Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.2.1
The Control Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.2.2
The Data Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3
Interprocess Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.1
Interprocess Communications on OpenVMS Systems . . . . . . . . . . . . .
4.3.2
Interprocess Communications on Digital UNIX Systems . . . . . . . . . . .
4.4
Time-Provider Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5
Time Server (DECdts Server Process) Algorithm . . . . . . . . . . . . . . . . . . . .
4.6
Running the Time-Provider Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7
Time-Provider Interface, User-Accessible Definitions . . . . . . . . . . . . . . . . .
4.8
Sample Time-Provider Programs and External Time-Provider Sources . . .

Glossary
Index

4–1
4–4
4–4
4–4
4–5
4–5
4–5
4–6
4–6
4–7
4–9
4–9
4–10
4–13

Figures
1–1
1–2
1–3
1–4
2–1
4–1

Time Display Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Time Display Format Variants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Relative Time Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Time Period Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DTS Portable Interface Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DECdts Server/TP Process Message Exchange . . . . . . . . . . . . . . . . . .

1–2
1–3
1–4
1–4
2–2
4–3

Absolute Time Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Relative Time Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Time-Provider Programs and Related Time-Provider Suppliers . . . . . .

1–5
1–5
4–14

Tables
1–1
1–2
4–1

Preface
The Digital Distributed Time Service (DECdts) is a networkwide service that
runs on OpenVMS and Digital UNIX operating systems. DECdts enables systems
to synchronize their clocks with all the other system clocks in the network.
This manual provides reference information about the DECdts application
programming interface (API) routines you can use to obtain, convert, and
calculate time values. The software interface between DECdts and external
time-provider programs is also described.

Intended Audience
This manual is intended for two audiences: programmers who use the DECdts
API to obtain timestamps or convert time values, and programmers who write
the software interface between time-provider (TP) hardware and DECdts. Both
audiences should have a sound understanding of DECdts concepts and the
programming interface before using the software.

Document Structure
This manual is organized into four chapters. The first chapter introduces DECdts
API. The second chapter describes each DECdts portable routine. The third
chapter contains a C programming example that shows a practical application
of the DECdts API programming routines, and the fourth chapter describes the
DECdts time-provider interface (TPI) for DECdts software on OpenVMS and
Digital UNIX operating systems.

Related Documents
For a list of additional documents that are available in support of this version of
the operating system, refer to the DECnet-Plus for OpenVMS Introduction and
User’s Guide or the DECnet-Plus for Digital UNIX Introduction and User’s Guide.
For additional information on the DECnet-Plus products and services, access the
Digital OpenVMS World Wide Web site. Use the following URL:
http://www.openvms.digital.com

Reader’s Comments
Digital welcomes your comments on this manual or any of the DECnet-Plus
documents. Send us your comments through any of the following channels:
Internet

openvmsdoc@zko.mts.dec.com

Fax

603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08

vii

Mail

OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation
Use the following table to order additional documentation or information.
If you need help deciding which documentation best meets your needs, call
800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Location

Call

Fax

Write

U.S.A.

DECdirect
800−DIGITAL
800−344−4825

Fax: 800−234−2298

Digital Equipment Corporation
P.O. Box CS2008
Nashua, NH 03061

Puerto Rico

809−781−0505

Fax: 809−749−8300

Digital Equipment Caribbean, Inc.
3 Digital Plaza, 1st Street, Suite 200
P.O. Box 11038
Metro Office Park
San Juan, Puerto Rico 00910−2138

Canada

800−267−6215

Fax: 613−592−1946

Digital Equipment of Canada, Ltd.
Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
Attn: DECdirect Sales
Local Digital subsidiary or
approved distributor

International
DTN: 264−4446
603−884−4446

Internal Orders

Fax: 603−884−3960

U.S. Software Supply Business
Digital Equipment Corporation
10 Cotton Road
Nashua, NH 03063−1260
ZK−7654A−GE

Conventions
The following conventions apply to this book.
Convention

Meaning

special type

Indicates a literal example of system output or user input. In
text, indicates command names, keywords, node names, file
names, directories, utilities, and tools. On a DECnet-Plus for
OpenVMS or Digital UNIX system, enter the word or phrase in
the exact case shown.
You can abbreviate command keywords to the smallest
number of characters that OpenVMS, Digital UNIX, NCL,
DECdns, DECdts, and the other utilities accept, usually three
characters.

italic

viii

Indicates a variable.

Convention

Meaning

bold

Indicates a new term defined either in the text or in the
DECnet-Plus Introduction and User’s Guide glossary or
important text.

Return

Indicates that you press the Return key.

Ctrl/x

Indicates that you press the Control key while you press the
key noted by x.

[]

In command format descriptions, indicates optional elements.
You can enter as many as you want.

{}

In command format descriptions, indicates you must enter at
least one listed element.

Note
The following conventions are for multiplatform documentation.

OpenVMS

UNIX

♦

Indicates information specific to DECnet-Plus for OpenVMS.

Indicates information specific to DECnet-Plus for Digital
UNIX.
Indicates the end of platform-specific information.

1
Introduction to the DECdts API
This chapter describes the Digital Distributed Time Service (DECdts)
programming routines. You can use these routines to obtain timestamps that
are based on Coordinated Universal Time (UTC). You can also use the DECdts
routines to translate among different timestamp formats and perform calculations
on timestamps. Applications can use the timestamps that DECdts supplies to
determine event sequencing, duration, and scheduling. Applications can call the
DECdts routines from DECdts server or clerk systems.
The Digital Distributed Time Service routines are written in the C programming
language. Be familiar with the basic DECdts concepts before you attempt to use
the applications programming interface (API).
The DECdts API routines offer the following basic functions:
•

Retrieve timestamp information

•

Convert between binary timestamps that use different time structures

•

Convert between binary timestamps and ASCII representations

•

Convert between UTC time and local time

•

Convert the binary time values in the OpenVMS (Smithsonian-based) format
to or from UTC-based binary timestamps (OpenVMS systems only)

•

Manipulate binary timestamps

•

Compare two binary time values

•

Calculate binary time values

•

Obtain time zone information

The following sections describe DECdts time representations, DECdts time
structures, API header files, and API routines.

1.1 DECdts Time Representation
UTC is the international time standard that has largely replaced Greenwich
Mean Time (GMT). The standard is administered by the International Time
Bureau (BIH) and is widely used. DECdts uses opaque binary timestamps that
represent UTC for all of its internal processes. You cannot read or disassemble
a DECdts binary timestamp; the DECdts API allows applications to convert or
manipulate timestamps, but they cannot be displayed. DECdts also translates
the binary timestamps into ASCII text strings, which can be displayed.

Introduction to the DECdts API 1–1

1.1.1 Absolute Time Representation
An absolute time is a point on a time scale. For DECdts, absolute times
reference the UTC time scale; absolute time measurements are derived from
system clocks or external time-providers. When DECdts reads a system clock
time, it records the time in an opaque binary timestamp that also includes the
inaccuracy and other information. When you display an absolute time, DECdts
converts the time to ASCII text, as shown in the following display:
1996-11-21-13:30:25.785-04:00I000.082
DECdts displays all times in a format that complies with the International
Standards Organization (ISO) 8601 (1988) standard. Note that the inaccuracy
portion of the time is not defined in the ISO standard (times that do not include
an inaccuracy are accepted). Figure 1–1 explains the ISO format that generated
the previous display.
Figure 1–1 Time Display Format
Calendar date and time
component

TDF
component

Inaccuracy
component

CCYY−MM−DD−hh:mm:ss.fff[+|−]hh:mmIsss.fff
Century
Year

fractions
seconds

Month
Day
hour
minute

Inaccuracy
designator
minutes
hours
+|− TDF

second
fraction

In Figure 1–1, the relative time preceded by the plus (+) or minus (-) character
indicates the hours and minutes that the calendar date and time are offset from
UTC. The presence of this time differential factor (TDF) in the string also
indicates that the calendar date and time are the local time of the system, not
UTC. Local time is UTC minus the TDF. The Inaccuracy designator I indicates
the beginning of the inaccuracy component associated with the time.
Although DECdts displays all times in the previous format, variations in the ISO
format shown in Figure 1–2 are also accepted as input for the ASCII conversion
routines.
In Figure 1–2, the Time designator T separates the calendar date from the time,
a comma separates seconds from fractional seconds, and the plus or minus
character indicates the beginning of the inaccuracy component.
The following examples show some valid time formats.

1–2 Introduction to the DECdts API

Figure 1–2 Time Display Format Variants
Calendar date and time
component

TDF
component

Inaccuracy
component

CCYY−MM−DDThh:mm:ss,fff[+|−]hh:mm +
− ss,fff
Century
fractions

Year
Month

seconds

Day

Inaccuracy
designator

Time
designator

minutes

hour

hours

minute

+|− TDF

second
fraction
ZK−4068A−GE

The following represents July 4, 1776 17:01 GMT and an infinite inaccuracy
(default).
1776-7-4-17:01:00
The following represents a local time of 12:01 (17:01 GMT) on July 4, 1776 with a
TDF of -5 hours and an inaccuracy of 100 seconds.
1776-7-4-12:01:00-05:00I100
Both of the following represent 12:00 GMT in the current day, month, and year
with an infinite inaccuracy.
12:00 and T12
The following represents July 14, 1792 00:00 GMT with an infinite inaccuracy.
1792-7-14

1.1.2 Relative Time Representation
A relative time is a discrete time interval that is usually added to or subtracted
from another time. A TDF associated with an absolute time is one example of a
relative time. A relative time is normally used as input for commands or system
routines.
The following example shows a relative time of 21 days, 8 hours, and 30 minutes,
25 seconds with an inaccuracy of 0.300 second.
21-08:30:25.000I00.300
The following example shows a negative relative time of 20.2 seconds with an
infinite inaccuracy (default).
-20.2
The following example shows a relative time of 10 minutes, 15.1 seconds with an
inaccuracy of 4 seconds.
10:15.1I4

Introduction to the DECdts API 1–3

Figure 1–3 Relative Time Syntax
Calendar date and time
component

TDF
component

Inaccuracy
component

CCYY−MM−DD−hh:mm:ss.fff[+|−]hh:mmIsss.fff
Century

fractions

Year

seconds

Month
Inaccuracy
designator

Day

minutes

hour

hours

minute

+|− TDF
second
fraction

Figure 1–3 shows the full syntax for a relative time.
Notice that a relative time does not use the calendar date fields, because these
fields concern absolute time. A positive relative time is unsigned; a negative
relative time is preceded by a minus (0) sign. A relative time is often subtracted
from or added to another relative or absolute time. The relative times that
DECdts uses internally are opaque binary timestamps. The DECdts API offers
several routines that can be used to calculate new times using relative binary
timestamps.
Representing Periods of Time
A given duration of a period of time can be represented by a data element of
variable length that uses the syntax shown in Figure 1–4.
Figure 1–4 Time Period Syntax

P n Y n M n W n D T n H n M n S In
Period Designator
Years/Year Designator
Months/Month Designator
Weeks/Week Designator

Inaccuracy Designator/Inaccuracy
Seconds/Second Designator
Minutes/Minute Designator
Hours/Hour Designator

Days/Day Designator

Time Designator
ZK−4985A−GE

The data element contains the following parts:
•

The designator P precedes the part that includes the calendar components,
including the following:
The number of years followed by the designator Y
The number of months followed by the designator M
The number of weeks followed by the designator W
The number of days followed by the designator D

1–4 Introduction to the DECdts API

•

The designator T precedes the part that includes the time components,
including the following:
The number of hours followed by the designator H
The number of minutes followed by the designator M
The number of seconds followed by the designator S

•

The designator I precedes the number of seconds of inaccuracy.

The following example represents a period of 1 year, 6 months, 15 days, 11 hours,
30 minutes, and 30 seconds and an infinite inaccuracy.
P1Y6M15DT11H30M30S
The following example represents a period of 3 weeks and an inaccuracy of 4
seconds.
P3WI4

1.2 Time Structures
DECdts can convert between several types of binary time structures that are
based on different base dates and time unit measurements. DECdts uses UTCbased time structures and can convert other types of time structures to its own
presentation of UTC-based time. The DECdts API routines are used to perform
these conversions for applications on your system.
Table 1–1 lists the absolute time structures that the DECdts API uses to modify
binary times for applications.
Table 1–1 Absolute Time Structures
Structure

Time Units

Base Date

Approximate Range

utc
tm
timespec

100-nanosecond

15 October 1582

A.D. 1 to A.D. 30,000

second

1 January 1900

A.D. 1 to A.D. 30,000

nanosecond

1 January 1970

A.D. 1970 to A.D. 2106

Table 1–2 lists the relative time structures that the DECdts API uses to modify
binary times for applications.
Table 1–2 Relative Time Structures
Structure

Time Units

Approximate Range

utc
tm
reltimespec

100-nanosecond

± 30,000 years

second

± 30,000 years

nanosecond

± 68 years

The remainder of this section explains the DECdts time structures in detail.

Introduction to the DECdts API 1–5

1.2.1 The utc Structure
Coordinated Universal Time (UTC) is useful for measuring time across local time
zones and for avoiding the seasonal changes (summer time or daylight saving
time) that can affect the local time. DECdts uses 128-bit binary numbers to
represent time values internally; throughout this manual, these binary numbers
representing time values are referred to as binary timestamps. The DECdts
utc structure determines the ordering of the bits in a binary timestamp; all
binary timestamps that are based on the utc structure contain the following
information:
•

The count of 100-nanosecond units since 00:00:00.00, 15 October 1582 (the
date of the Gregorian reform to the Christian calendar)

•

The count of 100-nanosecond units of inaccuracy applied to the above

•

The time differential factor (TDF), expressed as the signed quantity

•

The timestamp version number

The binary timestamps that are derived from the DECdts utc structure have an
opaque format. This format is a cryptic character sequence that DECdts uses and
stores internally. The opaque binary timestamp is designed for use in programs,
protocols, and databases.
Note
Applications use the opaque binary timestamps when storing time values
or when passing them to DECdts.

The API provides the necessary routines for converting between opaque binary
timestamps and character strings that can be displayed and read by users.

1.2.2 The tm Structure
The tm structure is based on the time in years, months, days, hours, minutes, and
seconds since 00:00:00 GMT (Greenwich Mean Time), 1 January 1900. The tm
structure is defined in the <time.h> header file.
The tm structure declaration follows:
struct tm {
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday;
int tm_yday;
int tm_isdst;

/* Seconds (0 - 59)
/* Minutes (0 - 59)
/* Hours (0 - 23)
/* Day of Month (1 - 31)
/* Month of Year (0 - 11)
/* Year - 1900
/* Day of Week (Sunday = 0)
/* Day of Year (0 - 364)
/* Nonzero if Daylight Savings Time
/* is in effect

*/
*/
*/
*/
*/
*/
*/
*/
*/
*/

};
Not all of the tm structure fields are used for each routine that converts between
tm structures and utc structures. See the parameter descriptions that accompany
the routines in Chapter 2 for additional information about which fields are used
for specific routines.

1–6 Introduction to the DECdts API

1.2.3 The timespec Structure
The timespec structure is normally used in combination with or in place of the
tm structure to provide finer resolution for binary times. The timespec structure
is similar to the tm structure, but the timespec structure specifies the number of
seconds and nanoseconds since the base time of 00:00:00 GMT, 1 January 1970.
You can find the structure in the <utc.h> header file.
The timespec structure declaration follows:
struct timespec {
unsigned long tv_sec; /* Seconds since 00:00:00 GMT,
/* 1 January 1970
long tv_nsec;
/* Additional nanoseconds since
/* tv_sec
}

*/
*/
*/
*/

timespec_t;

1.2.4 The reltimespec Structure
The reltimespec structure represents relative time. This structure is similar to
the timespec structure, except that the first field is signed in the reltimespec
structure. (The field is unsigned in the timespec structure.) You can find the
reltimespec structure in the <utc.h> header file.
The reltimespec structure declaration follows:
struct reltimespec {
long tv_sec; /* Seconds of relative time
long tv_nsec; /* Additional nanoseconds of
/* relative time
}

*/
*/
*/

reltimespec_t;

1.2.5 The OpenVMS Time Structure
OpenVMS

The OpenVMS time structure is based on Smithsonian time, which has a base
date of November 17, 1858. The binary OpenVMS structure is a signed, 64-bit
integer that has a positive value for absolute times. You can use the DECdts API
to translate an OpenVMS structure representing an absolute time to or from the
DECdts UTC-based binary timestamp ♦.

1.3 DECdts API Header Files
The <time.h> and <utc.h> header files contain the data structures, type
definitions, and define statements that are referenced by the DECdts API
routines. The <time.h> header file is present on all OpenVMS systems and is a
standard Digital UNIX file as well. The <utc.h> header file includes <time.h>
and contains the timespec, reltimespec, and utc structures.
On OpenVMS systems, the header files are located in the sys$library directory;
on Digital UNIX systems, these header files are located in /usr/include.

1.4 Linking Programs with the DECdts API
The DECdts API is implemented by a shared image (OpenVMS) or object library
(Digital UNIX); to use the API with your program, you must link the program
with the shared image or object library. The procedure for linking a program
differs according to the operating system running on a given node. The following
sections describe how to link programs with the DECdts API on DECnet-Plus for
OpenVMS and DECnet-Plus for Digital UNIX systems.

Introduction to the DECdts API 1–7

1.4.1 Linking Programs on DECnet-Plus for OpenVMS systems
OpenVMS

On DECnet-Plus for OpenVMS systems, the DECdts API is implemented by the
shared image sys$library:dtss$shr.exe. The following example shows how to
link a program with the DECdts shared image:
$ cc myprogram.c/output=myprogram.obj
$ link myprogram.obj, sys$input:/options Return
sys$library:dtss$shr.exe/share Ctrl-z
$
♦

1.4.2 Linking Programs on DECnet-Plus for Digital UNIX systems
UNIX

On DECnet-Plus for Digital UNIX systems, the DECdts API is implemented by
the object library usr/lib/libutc.a. The following example shows how to link a
program with the DECdts object library:
# cc myprogram.c -lutc -o myprogram
#
♦

1–8 Introduction to the DECdts API

2
DECdts Portable Applications Programming
Interface
The Digital Distributed Time Service programming routines can obtain
timestamps that are based on Coordinated Universal Time (UTC), translate
between different timestamp formats, and perform calculations on timestamps.
Applications can call the DECdts routines from DECdts server or clerk systems
and use the timestamps that DECdts supplies to determine event sequencing,
duration, and scheduling.
The DECdts routines can perform the following basic functions:
•

Retrieve the current (UTC-based) time from DECdts.

•

Convert binary timestamps expressed in the utc time structure to or from tm
structure components.

•

Convert the binary timestamps expressed in the utc time structure to or from

timespec structure components.
•

Convert the binary timestamps expressed in the utc time structure to or from
ASCII strings.

•

Convert the binary time values in the 64-bit OpenVMS (Smithsonian-based)
format to or from UTC-based binary timestamps (OpenVMS systems only).

•

Compare two binary time values.

•

Calculate binary time values.

•

Obtain time zone information.

DECdts can convert between several types of binary time structures that
are based on different calendars and time unit measurements. DECdts uses
UTC-based time structures and can convert other types of time structures to its
own presentation of UTC-based time.

2.1 DECdts API Routine Functions
Figure 2–1 categorizes the DECdts portable interface routines by function.

DECdts Portable Applications Programming Interface 2–1

Figure 2–1 DTS Portable Interface Categories

Retrieving Time ...
utc_gettime
utc_getusertime
Converting Formats ...
To/From
ASCII text:

To/From
VMS time:

utc_ascanytime
utc_ascgmtime
utc_asclocaltime
utc_ascreltime
utc_mkasctime
utc_mkascreltime

utc_mkvmsanytime
utc_mkvmsgmtime
utc_mkvmslocaltime
utc_vmsanytime
utc_vmsgmtime
utc_vmslocaltime

To/From
tm Structures:

To/From
timespec Structures:

Converting Structures ...

utc_anytime
utc_gmtime
utc_localtime
utc_mkanytime
utc_mkgmtime
utc_mklocaltime
utc_mkreltime
utc_reltime

utc_binreltime
utc_bintime
utc_mkbinreltime
utc_mkbintime

Manipulating Times ...
utc_boundtime
utc_spantime
utc_pointtime
Comparing Times ...
utc_cmpintervaltime
utc_cmpmidtime
Calculating Times ...
utc_abstime
utc_addtime
utc_mulftime
utc_multime
utc_subtime
Obtaining Timezone
Information ...
utc_anyzone
utc_gmtzone
utc_localzone
ZK−4986A−GE

2–2 DECdts Portable Applications Programming Interface

An alphabetical listing of the DECdts portable interface routines and a brief
description of each one follows:

utc_abstime
utc_addtime

Computes the absolute value of a binary relative time.

utc_anytime

Converts a binary timestamp into a tm structure, using the
TDF information contained in the timestamp to determine the
TDF returned with the tm structure.

utc_anyzone

Gets the time zone label and offset from GMT, using the TDF
contained in the input utc.

utc_ascanytime

Converts a binary timestamp into an ASCII string that
represents an arbitrary time zone.

utc_ascgmtime

Converts a binary timestamp into an ASCII string that
expresses a GMT time.

utc_asclocaltime

Converts a binary timestamp to an ASCII string that
represents a local time.

utc_ascreltime

Converts a binary timestamp that expresses a relative time to
its ASCII representation.

utc_binreltime

Converts a relative binary timestamp into timespec
structures that express relative time and inaccuracy.

utc_bintime
utc_boundtime

Converts a binary timestamp into a timespec structure.

utc_cmpintervaltime

Compares two binary timestamps or two relative binary
timestamps.

utc_cmpmidtime

Compares two binary timestamps or two relative binary
timestamps, ignoring inaccuracies.

utc_gettime

Returns the current system time and inaccuracy as an opaque
binary timestamp.

utc_getusertime

Returns the time and process-specific TDF, rather than the
system-specific TDF.

utc_gmtime

Converts a binary timestamp into a tm structure that
expresses GMT or the equivalent UTC.

utc_gmtzone
utc_localtime

Gets the time zone label and zero offset from GMT, given utc.

utc_localzone
utc_mkanytime

Computes the sum of two binary timestamps; the timestamps
can be two relative times or a relative time and an absolute
time.

Given two UTC times, one before and one after an event,
returns a single UTC time whose inaccuracy includes the
event.

Converts a binary timestamp into a tm structure that
expresses local time.
Gets the time zone label and offset from GMT, given utc.
Converts a tm structure and TDF (expressing the time in an
arbitrary time zone) into a binary timestamp.

utc_mkascreltime

Converts a null-terminated character string, which represents
a relative timestamp to a binary timestamp.

utc_mkasctime

Converts a null-terminated character string, which represents
an absolute timestamp, to a binary timestamp.

utc_mkbinreltime

Converts a timespec structure expressing a relative time to a
binary timestamp.

utc_mkbintime
utc_mkgmtime

Converts a timespec structure into a binary timestamp.
Converts a tm structure that expresses GMT or UTC to a
binary timestamp.

DECdts Portable Applications Programming Interface 2–3

utc_mklocaltime

Converts a tm structure that expresses local time to a binary
timestamp.

utc_mkreltime

Converts a tm structure that expresses relative time to a
binary timestamp.

utc_mkvmsanytime

Converts a binary OpenVMS format time and TDF (expressing
the time in an arbitrary time zone) to a binary timestamp.

utc_mkvmsgmtime

Converts a binary OpenVMS format time expressing GMT (or
the equivalent UTC) into a binary timestamp.

utc_mkvmslocaltime

Converts a local binary OpenVMS format time to a binary
timestamp, using the host system’s TDF.

utc_mulftime

Multiplies a relative binary timestamp by a floating-point
value.

utc_multime
utc_pointtime

Multiplies a relative binary timestamp by an integer factor.

utc_reltime

Converts a binary timestamp that expresses a relative time
into a tm structure.

utc_spantime

Given two (possibly unordered) UTC timestamps, returns a
single UTC time interval whose inaccuracy spans the two
input timestamps.

utc_subtime

Computes the difference between two binary timestamps that
express two relative times (an absolute time and a relative
time, two relative times, or two absolute times).

utc_vmsanytime

Converts a binary timestamp to a binary OpenVMS-format
time, using the TDF contained in the binary timestamp.

utc_vmsgmtime

Converts a binary timestamp to a binary OpenVMS-format
time expressing GMT or the equivalent UTC.

utc_vmslocaltime

Converts a binary timestamp to a local binary OpenVMS
format time, using the host system’s time differential factor.

Converts a binary timestamp to three binary timestamps that
represent the earliest, most likely, and latest time.

Notes
Absolute time is a point on a time scale; absolute time measurements
are derived from system clocks or external time-providers. For DECdts,
absolute times reference the UTC standard and include the inaccuracy
and other information. When you display an absolute time, DECdts
converts the time to ASCII text, as shown in the following display:
1996-11-21-13:30:25.785-04:00I000.082
Relative time is a discrete time interval that is usually added to or
subtracted from an absolute time. A time differential factor (TDF)
associated with an absolute time is one example of a relative time. Note
that a relative time does not use the calendar date fields, because these
fields concern absolute time.
Coordinated Universal Time (UTC) is the international time standard
that DECdts uses. The zero hour of UTC is based on the zero hour of
Greenwich Mean Time (GMT). The documentation consistently refers to
the time zone of the Greenwich Meridian as GMT. However, this time
zone is also sometimes referred to as UTC.
The time differential factor (TDF) is the difference between UTC and
the time in a particular time zone.
The user’s environment determines the time zone rule (details are system
dependent):

2–4 DECdts Portable Applications Programming Interface

OpenVMS

UNIX

The user selects a time zone by
defining sys$timezone_rule during the
sys$manager:net$configure.com procedure,
or by explicitly defining sys$timezone_rule. See
the DECdts section of the configuration guide
for information on how to construct a time zone
rule.♦
The user selects a time zone by specifying the
time zone environment variable. (The reference
page for the utc_localtime( ) system call
provides additional information.) ♦

If the user’s environment does not specify a time zone rule, the system’s
rule is used (details of the rule are system dependent).
OpenVMS

UNIX

OpenVMS systems do not have a default
time zone rule. You must run the
sys$manager:net$configure procedure to
specify a time zone. ♦
The rule in /etc/zoneinfo/localtime applies.
♦

Chapter 1, Introduction to the DECdts API, provides additional
information about UTC and GMT, TDFs and time zones, and relative and
absolute times.
Unless otherwise specified, the default input and output parameters are
as follows:
•

If utc is not specified as an input parameter, the current time is used.

•

If inacc is not specified as an input parameter, infinity is used.

•

If no output parameter is specified, no result (or an error) is returned.

The following section is a command reference, which includes all DECdts API
routines.

DECdts Portable Applications Programming Interface 2–5

utc_abstime

utc_abstime
Computes the absolute value of a relative binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_abstime(result, *utc1)
utc_t result;
const utc_t *utc1;

PARAMETERS
Input
utc1
Relative binary timestamp.
Output
result
Absolute value of the input relative binary timestamp.

DESCRIPTION
The Absolute Time routine computes the absolute value of a relative binary
timestamp. The input timestamp represents a relative (delta) time.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid results.

EXAMPLE
The following example scales a relative time, computes its absolute value, and
prints the result.
utc_t
char

relutc, scaledutc;
timstr[UTC_MAX_STR_LEN];

/*
* Make sure relative timestamp represents a positive interval...
*/
utc_abstime(&relutc,
&relutc);

/* Out: Abs-value of rel time */
/* In: Relative time to scale */

/*
* Scale it by a factor of 17...
*/
utc_multime(&scaledutc,
&relutc,
17L);

2–6 DECdts Portable Applications Programming Interface

/* Out: Scaled relative time */
/* In: Relative time to scale */
/* In: Scale factor
*/

utc_abstime

utc_ascreltime(timstr,
UTC_MAX_STR_LEN,
&scaledutc);

/* Out: ASCII relative time
*/
/* In: Length of input string */
/* In: Relative time to
*/
/*
convert
*/

printf("%s\n",timstr);
/*
* Scale it by a factor of 17.65...
*/
utc_mulftime(&scaledutc,
&relutc,
17.65);

/* Out: Scaled relative time */
/* In: Relative time to scale */
/* In: Scale factor
*/

utc_ascreltime(timstr,
UTC_MAX_STR_LEN,
&scaledutc);

/* Out: ASCII relative time
*/
/* In: Length of input string */
/* In: Relative time to
*/
/*
convert
*/

printf("%s\n",timstr);

DECdts Portable Applications Programming Interface 2–7

utc_addtime

utc_addtime
Computes the sum of two binary timestamps; the timestamps can be two relative
times or a relative time and an absolute time.

SYNOPSIS
#include <utc.h>
int utc_addtime(result, *utc1, *utc2)
utc_t result;
const utc_t *utc1;
const utc_t *utc2;

PARAMETERS
Input
utc1
Binary timestamp or relative binary timestamp.
utc2
Binary timestamp or relative binary timestamp.
Output
result
Resulting binary timestamp or relative binary timestamp, depending on the
operation performed:
•

relative time + relative time = relative time

•

absolute time + relative time = absolute time

•

relative time + absolute time = absolute time

•

absolute time + absolute time is undefined. See NOTES.

DESCRIPTION
The Add Time routine adds two binary timestamps, producing a third binary
timestamp whose inaccuracy is the sum of the two input inaccuracies. One or
both of the input timestamps typically represent a relative (delta) time. The TDF
in the first input timestamp is copied to the output.

NOTES
Although no error is returned, do not use the combination absolute time +
absolute time.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid results.

2–8 DECdts Portable Applications Programming Interface

utc_addtime

EXAMPLE
The following example shows how to compute a timestamp that represents a time
at least 5 seconds in the future.
utc_t
reltimespec_t
timespec_t

now, future, fivesec;
tfivesec;
tzero;

/*
* Construct a timestamp that represents 5 seconds...
*/
tfivesec.tv_sec = 5;
tfivesec.tv_nsec = 0;
tzero.tv_sec = 0;
tzero.tv_nsec = 0;
utc_mkbinreltime(&fivesec,
/* Out: 5 secs in binary timestamp
&tfivesec, /* In: 5 secs in timespec
&tzero);
/* In: 0 secs inaccuracy in timespec

*/
*/
*/

/*
* Get the maximum possible current time...
*
(The NULL input parameter is used to specify the current time.)
*/
utc_pointtime((utc_t *)0,
/* Out: Earliest possible current time */
(utc_t *)0,
/* Out: Midpoint of current time
*/
&now,
/* Out: Latest possible current time */
(utc_t *)0);
/* In: Use current time
*/
/*
* Add 5 seconds to get future timestamp...
*/
utc_addtime(&future,
/* Out: Future binary timestamp
&now,
/* In: Latest possible time now
&fivesec);
/* In: 5 secs

*/
*/
*/

RELATED INFORMATION
Functions: utc_subtime

DECdts Portable Applications Programming Interface 2–9

utc_anytime

utc_anytime
Converts a binary timestamp to a tm structure, using the time differential factor
(TDF) information contained in the timestamp to determine the TDF returned
with the tm structure.

SYNOPSIS
#include <utc.h>
int utc_anytime(timetm, *tns, *inacctm, *ins, *tdf, *utc)
struct tm timetm;
long *tns;
struct tm *inacctm;
long *ins;
long *tdf;
const utc_t *utc;

PARAMETERS
Input
utc
Binary timestamp.
Output
timetm
Time component of the binary timestamp expressed in the timestamp’s local time.
tns
Nanoseconds since time component of the binary timestamp.
inacctm
Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is
finite, then tm_mday returns a value of –1 and tm_mon and tm_year return values
of 0. The field tm_yday contains the inaccuracy in days. If the inaccuracy is
infinite, all tm structure fields return values of –1.
ins
Nanoseconds of inaccuracy component of the binary timestamp.
tdf
TDF component of the binary timestamp in units of seconds east or west of GMT.

DESCRIPTION
The Any Time routine converts a binary timestamp to a tm structure. The TDF
information contained in the timestamp is returned with the time and inaccuracy
components; the TDF component determines the offset from GMT and the local
time value of the tm structure. Additional returns include nanoseconds since
Time and nanoseconds of inaccuracy.

2–10 DECdts Portable Applications Programming Interface

utc_anytime

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
The following example converts a timestamp, using the TDF information in the
timestamp, then prints the result.
utc_t
struct tm
timespec_t
char

evnt;
tmevnt;
tevnt, ievnt;
tznam[80];

/*
* Assume evnt contains the timestamp to convert...
*
* Get time as a tm structure, using the time zone information in
* the timestamp...
*/
utc_anytime(&tmevnt,
/* Out: tm struct of time of evnt
(long *)0,
/* Out: nanosec of time of evnt
(struct tm *)0,
/* Out: tm struct of inacc of evnt
(long *)0,
/* Out: nanosec of inacc of evnt
(int *)0,
/* Out: tdf of evnt
&evnt);
/* In: binary timestamp of evnt

*/
*/
*/
*/
*/
*/

/*
* Get the time and inaccuracy as timespec structures...
*/
utc_bintime(&tevnt,
/* Out: timespec of time of evnt
&ievnt,
/* Out: timespec of inacc of evnt
(int *)0,
/* Out: tdf of evnt
&evnt);
/* In: Binary timestamp of evnt

*/
*/
*/
*/

/*
* Construct the time zone name from time zone information in the
* timestamp...
*/
utc_anyzone(tznam,
/* Out: Time zone name
80,
/* In: Size of time zone name
(long *)0,
/* Out: tdf of event
(long *)0,
/* Out: Daylight saving flag
&evnt);
/* In: Binary timestamp of evnt

*/
*/
*/
*/
*/

/*
* Print timestamp in the format:
*
*
1991-03-05-21:27:50.023I0.140 (GMT-5:00)
*
1992-04-02-12:37:24.003Iinf (GMT+7:00)
*
*/
printf("%d-%02d-%02d-%02d:%02d:%02d.%03d",
tmevnt.tm_year+1900, tmevnt.tm_mon+1, tmevnt.tm_mday,
tmevnt.tm_hour, tmevnt.tm_min, tmevnt.tm_sec,
(tevnt.tv_nsec/1000000));
if ((long)ievnt.tv_sec == -1)
printf("Iinf");
else
printf("I%d.%03d", ievnt.tv_sec, (ievnt.tv_nsec/1000000));

DECdts Portable Applications Programming Interface 2–11

utc_anytime

printf(" (%s)\n", tznam);

RELATED INFORMATION
Functions: utc_mkanytime, utc_anyzone, utc_gettime, utc_getusertime,
utc_gmtime, utc_localtime

2–12 DECdts Portable Applications Programming Interface

utc_anyzone

utc_anyzone
Gets the time zone label and offset from GMT, using the TDF contained in the
input utc.

SYNOPSIS
#include <utc.h>
int utc_anyzone(tzname, tzlen, *tdf, isdst, *utc)
char tzname;
size_t tzlen;
long *tdf;
int *isdst;
const utc_t *utc;

PARAMETERS
Input
tzlen
Length of the tzname buffer.
utc
Binary time.
Output
tzname
Character string that is long enough to hold the time zone label.
tdf
Longword with differential in seconds east or west of GMT.
isdst
Integer with a value of –1, indicating that no information is supplied as to
whether it is standard time or daylight saving time. A value of –1 is always
returned.

DESCRIPTION
The Any Zone routine gets the time zone label and offset from GMT, using the
TDF contained in the input utc. The label returned is always of the form GMT
+ n or GMT 0 n, where n is the TDF expressed in hours:minutes. (The label
associated with an arbitrary time zone is not known; only the offset is known.)

NOTES
All of the output parameters are optional. No value is returned and no error
occurs if the pointer is null.

DECdts Portable Applications Programming Interface 2–13

utc_anyzone

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or an insufficient buffer.

EXAMPLE
See the sample program in the Examples section of the utc_anytime routine.

RELATED INFORMATION
Functions: utc_anytime, utc_gmtzone, utc_localzone

2–14 DECdts Portable Applications Programming Interface

utc_ascanytime

utc_ascanytime
Converts a binary timestamp to an ASCII string that represents an arbitrary
time zone.

SYNOPSIS
#include <utc.h>
int utc_ascanytime(*cp, stringlen, *utc)
char *cp;
size_t stringlen;
const utc_t *utc;

PARAMETERS
Input
stringlen
The length of the cp buffer.
utc
Binary timestamp.
Output
cp
ASCII string that represents the time.

DESCRIPTION
The ASCII Any Time routine converts a binary timestamp to an ASCII string
that expresses a time. The TDF component in the timestamp determines the
local time used in the conversion.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid results.

EXAMPLE
The following example converts a time to an ASCII string that expresses the time
in the time zone where the timestamp was generated.
utc_t
char

evnt;
localTime[UTC_MAX_STR_LEN];

/*
* Assuming that evnt contains the timestamp to convert, convert
* the time to ASCII in the following format:
*
*
1991-04-01-12:27:38.37-8:00I2.00
*/

DECdts Portable Applications Programming Interface 2–15

utc_ascanytime

utc_ascanytime(localtime,
UTC_MAX_STR_LEN,
&evnt);

/* Out: Converted time
/* In: Length of string
/* In: Time to convert

RELATED INFORMATION
Functions: utc_ascgmtime, utc_asclocaltime

2–16 DECdts Portable Applications Programming Interface

*/
*/
*/

utc_ascgmtime

utc_ascgmtime
Converts a binary timestamp to an ASCII string that expresses a GMT time.

SYNOPSIS
#include <utc.h>
int utc_ascgmtime(*cp, stringlen, *utc)
char *cp;
size_t stringlen;
const utc_t *utc;

PARAMETERS
Input
stringlen
Length of the cp buffer.
utc
Binary timestamp.
Output
cp
ASCII string that represents the time.

DESCRIPTION
The ASCII GMT Time routine converts a binary timestamp to an ASCII string
that expresses a time in GMT.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid results.

EXAMPLE
The following example converts the current time to GMT format.
char

gmTime[UTC_MAX_STR_LEN];

/*
* Convert the current time to ASCII in the following format:
*
*
1991-04-01-12:27:38.37I2.00
*/
utc_ascgmtime(gmTime,
UTC_MAX_STR_LEN,
(utc_t*) NULL);

/* Out: Converted time
/* In: Length of string
/* In: Time to convert
/* Default is current time

*/
*/
*/
*/

DECdts Portable Applications Programming Interface 2–17

utc_ascgmtime

RELATED INFORMATION
Functions: utc_ascanytime, utc_asclocaltime

2–18 DECdts Portable Applications Programming Interface

utc_asclocaltime

utc_asclocaltime
Converts a binary timestamp to an ASCII string that represents a local time.

SYNOPSIS
#include <utc.h>
int utc_asclocaltime(*cp, stringlen, *utc)
char *cp;
size_t stringlen;
const utc_t *utc;

PARAMETERS
Input
stringlen
Length of the cp buffer.
utc
Binary timestamp.
Output
cp
ASCII string that represents the time.

DESCRIPTION
The ASCII Local Time routine converts a binary timestamp to an ASCII string
that expresses local time.
The user’s environment determines the time zone rule (details are system
dependent).
OpenVMS

UNIX

The user selects a time zone by defining
sys$timezone_rule, which is created when the
sys$manager:net$configure.com is run.♦
The user selects a time zone by specifying the time
zone environment variable. (The reference page
for the localtime( ) system call provides additional
information.) ♦

If the user’s environment does not specify a time zone rule, the system’s rule is
used (details of the rule are system dependent).
OpenVMS

UNIX

OpenVMS systems do not have a default time zone
rule. You must run the sys$manager:net$configure
procedure to specify a time zone. ♦
The rule in /etc/zoneinfo/localtime applies. ♦

DECdts Portable Applications Programming Interface 2–19

utc_asclocaltime

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid results.

EXAMPLE
The following example converts the current time to local time.
char

localTime[UTC_MAX_STR_LEN];

/*
* Convert the current time...
*/
utc_asclocaltime(localTime,
/* Out:
UTC_MAX_STR_LEN, /* In:
(utc_t*) NULL); /* In:
/*

RELATED INFORMATION
Functions: utc_ascanytime, utc_ascgmtime

2–20 DECdts Portable Applications Programming Interface

Converted time
Length of string
Time to convert
Default is current time

*/
*/
*/
*/

utc_ascreltime

utc_ascreltime
Converts a relative binary timestamp to an ASCII string that represents the
time.

SYNOPSIS
#include <utc.h>
int utc_ascreltime(*cp, stringlen, *utc)
char *cp;
const size_t stringlen;
const utc_t *utc;

PARAMETERS
Input
utc
Relative binary timestamp.
stringlen
Length of the cp buffer.
Output
cp
ASCII string that represents the time.

DESCRIPTION
The ASCII Relative Time routine converts a relative binary timestamp to an
ASCII string that represents the time.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid results.

EXAMPLE
See the sample program in the Examples section of the utc_abstime routine.

RELATED INFORMATION
Functions: utc_mkascreltime

DECdts Portable Applications Programming Interface 2–21

utc_binreltime

utc_binreltime
Converts a relative binary timestamp to two timespec structures that express
relative time and inaccuracy.

SYNOPSIS
#include <utc.h>
int utc_binreltime(*timesp, *inaccsp, *utc)
reltimespec_t *timesp;
timespec_t *inaccsp;
const utc_t *utc;

PARAMETERS
Input
utc
Relative binary timestamp.
Output
timesp
Time component of the relative binary timestamp, in the form of seconds and
nanoseconds since the base time (1970-01-01:00:00:00.0 + 00:00I0).
inaccsp
Inaccuracy component of the relative binary timestamp, in the form of seconds
and nanoseconds.

DESCRIPTION
The Binary Relative Time routine converts a relative binary timestamp to two

timespec structures that express relative time and inaccuracy. These timespec
structures describe a time interval.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
The following example measures the duration of a process, then prints the
resulting relative time and inaccuracy.
utc_t
reltimespec_t
timespec_t

before, duration;
tduration;
iduration;

/*
* Get the time before the start of the operation...
*/
utc_gettime(&before);

/* Out: Before binary timestamp

2–22 DECdts Portable Applications Programming Interface

utc_binreltime

/*
*
*
*
*
*
*/

...Later...
Subtract, getting the duration as a relative time.
NOTE: The NULL argument is used to obtain the current time.

utc_subtime(&duration,
(utc_t *)0,
&before);
/*
*
*/

Convert the relative times to timespec structures...

utc_binreltime(&tduration,
&iduration,
&duration);
/*
*
*/

/* Out: Duration rel bin timestamp */
/* In: After binary timestamp
*/
/* In: Before binary timestamp
*/

/* Out: Duration time timespec
*/
/* Out: Duration inacc timespec
*/
/* In: Duration rel bin timestamp */

Print the duration...

printf("%d.%04d", tduration.tv_sec, (tduration.tv_nsec/10000));
if ((long)iduration.tv_sec == -1)
printf("Iinf\n");
else
printf("I%d.%04d\n", iduration.tv_sec, (iduration.tv_nsec/100000));

RELATED INFORMATION
Functions: utc_mkbinreltime

DECdts Portable Applications Programming Interface 2–23

utc_bintime

utc_bintime
Converts a binary timestamp to a timespec structure.

SYNOPSIS
#include <utc.h>
int utc_bintime(*timesp, *inaccsp, *tdf, *utc)
timespec_t *timesp;
timespec_t *inaccsp;
long *tdf;
const utc_t *utc;

PARAMETERS
Input
utc
Binary timestamp.
Output
timesp
Time component of the binary timestamp, in the form of seconds and nanoseconds
since the base time.
inaccsp
Inaccuracy component of the binary timestamp, in the form of seconds and
nanoseconds.
tdf
TDF component of the binary timestamp in the form of signed number of seconds
east or west of GMT.

DESCRIPTION
The Binary Time routine converts a binary timestamp to a timespec structure.
The TDF information contained in the timestamp is returned.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
See the sample program in the Examples section of the utc_anytime routine.

2–24 DECdts Portable Applications Programming Interface

utc_bintime

RELATED INFORMATION
Functions: utc_binreltime, utc_mkbintime

DECdts Portable Applications Programming Interface 2–25

utc_boundtime

utc_boundtime
Given two UTC times, one before and one after an event, returns a single UTC
time whose inaccuracy includes the event.

SYNOPSIS
#include <utc.h>
int utc_boundtime(*result, *utc1, *utc2)
utc_t *result;
const utc_t *utc1;
const utc_t *utc2;

PARAMETERS
Input
utc1
Before binary timestamp or relative binary timestamp.
utc2
After binary timestamp or relative binary timestamp.
Output
result
Spanning timestamp.

DESCRIPTION
Given two UTC times, the Bound Time routine returns a single UTC time
whose inaccuracy bounds the two input times. This is useful for timestamping
events; the routine gets the utc values before and after the event, then calls
utc_boundtime to build a timestamp that includes the event.

NOTES
The TDF in the output UTC value is copied from the utc2 input. If one or both
input values have infinite inaccuracies, the returned time value also has an
infinite inaccuracy and is the average of the two input values.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid parameter order.

2–26 DECdts Portable Applications Programming Interface

utc_boundtime

EXAMPLE
The following example records the time of an event and constructs a single
timestamp, which includes the time of the event. Note that the utc_getusertime
routine is called so the time zone information that is included in the timestamp
references the user’s environment rather than the system’s default time zone.
The user’s environment determines the time zone rule (details are system
dependent).
The user selects a time zone by defining
sys$timezone_rule, which is created when the
sys$manager:net$configure.com is run. ♦

OpenVMS

The user selects a time zone by specifying the time
zone environment variable. (The reference page
for the localtime( ) system call provides additional
information.)♦

UNIX

If the user’s environment does not specify a time zone rule, the system’s rule is
used (details of the rule are system dependent).
OpenVMS systems do not have a default time zone
rule. You must run the sys$manager:net$configure
procedure to specify a time zone.♦

OpenVMS

The rule in /etc/zoneinfo/localtime applies. ♦

UNIX

utc_t

before, after, evnt;

/*
* Get the time before the event...
*/
utc_getusertime(&before);

/* Out: Before binary timestamp

/*
* Get the time after the event...
*/
utc_getusertime(&after);

/* Out: After binary timestamp

/*
* Construct a single timestamp that describes the time of the
* event...
*/
utc_boundtime(&evnt,
&before,
&after);

/* Out: Timestamp that bounds event */
/* In: Before binary timestamp
*/
/* In: After binary timestamp
*/

RELATED INFORMATION
Functions: utc_gettime, utc_pointtime, utc_spantime

DECdts Portable Applications Programming Interface 2–27

utc_cmpintervaltime

utc_cmpintervaltime
Compares two binary timestamps or two relative binary timestamps.

SYNOPSIS
#include <utc.h>
int utc_cmpintervaltime(*relation, *utc1, *utc2)
enum utc_cmptype *relation;
const utc_t *utc1;
const utc_t *utc2;

PARAMETERS
Input
utc1
Binary timestamp or relative binary timestamp.
utc2
Binary timestamp or relative binary timestamp.
Output
relation
Receives the result of the comparison of utc1:utc2, where the result is an
enumerated type with one of the following values:
•

utc_equalTo

•

utc_lessThan

•

utc_greaterThan

•

utc_indeterminate

DESCRIPTION
The Compare Interval Time routine compares two binary timestamps and
returns a flag indicating that the first time is greater than, less than, equal to,
or overlapping with the second time. Two times overlap if the intervals (time 0
inaccuracy, time + inaccuracy) of the two times intersect.
The input binary timestamps express two absolute or two relative times. Do
not compare relative binary timestamps and binary timestamps. If you do, no
meaningful results and no errors are returned.
This routine does a temporal ordering of the time intervals.
utc1 is utc_lessThan utc2 iff
utc1.time + utc1.inacc < utc2.time - utc2.inacc
utc1 is utc_greaterThan utc2 iff
utc1.time - utc1.inacc > utc2.time + utc2.inacc
utc1 utc_equalTo utc2 iff
utc1.time == utc2.time and
utc1.inacc == 0 and
utc2.inacc == 0
2–28 DECdts Portable Applications Programming Interface

utc_cmpintervaltime

utc1 is utc_indeterminate with respect to utc2 if the intervals
overlap.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument.

EXAMPLE
The following example checks to see if the current time is definitely after 1:00 P.M.
today GMT.
struct tm
enum utc_cmptype
utc_t

tmtime, tmzero;
relation;
testtime;

/*
* Zero the tm structure for inaccuracy...
*/
memset(&tmzero, 0, sizeof(tmzero));
/*
* Get the current time, mapped to a tm structure...
*
*
NOTE: The NULL argument is used to get the current time.
*/
utc_gmtime(&tmtime,
(long *)0,
(struct tm *)0,
(long *)0,
(utc_t *)0);

/* Out: Current GMT time in tm struct */
/* Out: Nanoseconds of time
*/
/* Out: Current inaccuracy in tm struct */
/* Out: Nanoseconds of inaccuracy
*/
/* In: Current timestamp
*/

/*
* Construct a tm structure that corresponds to 1:00 PM...
*/
tmtime.tm_hour = 13;
tmtime.tm_min = 0;
tmtime.tm_sec = 0;
/*
* Convert to a binary timestamp...
*/
utc_mkgmtime(&testtime,
&tmtime,
0,
&tmzero,
0);

/* Out: Binary timestamp of 1:00 PM
/* In: 1:00 PM in tm struct
/* In: Nanoseconds of time
/* In: Zero inaccuracy in tm struct
/* In: Nanoseconds of inaccuracy

*/
*/
*/
*/
*/

/*
* Compare to the current time, noting the use of the
* NULL argument...
*/
utc_cmpintervaltime(&relation,
(utc_t *)0,
&testtime);

/* Out: Comparison relation
/* In: Current timestamp
/* In: 1:00 PM timestamp

*/
*/
*/

/*
* If it is not later - wait, print a message, etc.
*/
if (relation != utc_greaterThan) {
DECdts Portable Applications Programming Interface 2–29

utc_cmpintervaltime

/*
*
*
*
*/
}

Note: It could be earlier than 1:00 PM or it could be
indeterminate. If indeterminate, for some applications
it might be worth waiting.

RELATED INFORMATION
Functions: utc_cmpmidtime

2–30 DECdts Portable Applications Programming Interface

utc_cmpmidtime

utc_cmpmidtime
Compares two binary timestamps or two relative binary timestamps, ignoring
inaccuracies.

SYNOPSIS
#include <utc.h>
int utc_cmpmidtime(*relation, *utc1, *utc2)
enum utc_cmptype *relation;
const utc_t *utc1;
const utc_t *utc2;

PARAMETERS
Input
utc1
Binary timestamp or relative binary timestamp.
utc2
Binary timestamp or relative binary timestamp.
Output
relation
Result of the comparison of utc1:utc2, where the result is an enumerated type
with one of the following values:
•

utc_equalTo

•

utc_lessThan

•

utc_greaterThan

DESCRIPTION
The Compare Midpoint Times routine compares two binary timestamps and
returns a flag indicating that the first timestamp is greater than, less than,
or equal to the second timestamp. Inaccuracy information is ignored for this
comparison; the input values are, therefore, equivalent to the midpoints of the
time intervals described by the input binary timestamps.
The input binary timestamps express two absolute or two relative times. Do
not compare relative binary timestamps and binary timestamps. If you do, no
meaningful results and no errors are returned.
The following routine does a lexical ordering on the time interval midpoints.
utc1 is utc_lessThan utc2 iff
utc1.time < utc2.time
utc1 is utc_greaterThan utc2 iff
utc1.time > utc2.time
utc1 is utc_equalTo utc2 iff
utc1.time == utc2.time

DECdts Portable Applications Programming Interface 2–31

utc_cmpmidtime

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument.

EXAMPLE
The following example checks if the current time (ignoring inaccuracies) is after
1:00 P.M. today local time.
struct tm
enum utc_cmptype
utc_t

tmtime, tmzero;
relation;
testtime;

/*
* Zero the tm structure for inaccuracy...
*/
memset(&tmzero, 0, sizeof(tmzero));
/*
* Get the current time, mapped to a tm structure...
*
*
NOTE: The NULL argument is used to get the current time.
*/
utc_localtime(&tmtime,
(long *)0,
(struct tm *)0,
(long *)0,
(utc_t *)0);

/* Out: Current local time in tm struct */
/* Out: Nanoseconds of time
*/
/* Out: Current inacc in tm struct
*/
/* Out: Nanoseconds of inaccuracy
*/
/* In: Current timestamp
*/

/*
* Construct a tm structure that corresponds to 1:00 P.M....
*/
tmtime.tm_hour = 13;
tmtime.tm_min = 0;
tmtime.tm_sec = 0;
/*
* Convert to a binary timestamp...
*/
utc_mklocaltime(&testtime,
&tmtime,
0,
&tmzero,
0);

/* Out: Binary timestamp of 1:00 P.M.
/* In: 1:00 P.M. in tm struct
/* In: Nanoseconds of time
/* In: Zero inaccuracy in tm struct
/* In: Nanoseconds of inaccuracy

*/
*/
*/
*/
*/

/*
* Compare to the current time, noting the use of the
* NULL argument...
*/
utc_cmpmidtime(&relation,
(utc_t *)0,
&testtime);

/* Out: Comparison relation
/* In: Current timestamp
/* In: 1:00 P.M. timestamp

/*
* If the time is not later - wait, print a message, etc.
*/
if (relation != utc_greaterThan) {

2–32 DECdts Portable Applications Programming Interface

*/
*/
*/

utc_cmpmidtime

/*
*
*/
}

It is not later then 1:00 P.M. local time. Note that
this depends on the setting of the user’s environment.

RELATED INFORMATION
Functions: utc_cmpintervaltime

DECdts Portable Applications Programming Interface 2–33

utc_gettime

utc_gettime
Returns the current system time and inaccuracy as a binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_gettime(*utc)
utc_t *utc;

PARAMETERS
Input
None.
Output
utc
System time as a binary timestamp.

DESCRIPTION
The Get Time routine returns the current system time and inaccuracy in a
binary timestamp. The routine takes the TDF from the operating system’s
kernel; the TDF is specified in a system-dependent manner.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Generic error that indicates the time service cannot be accessed.

EXAMPLE
See the sample program in the Examples section of the utc_binreltime routine.

2–34 DECdts Portable Applications Programming Interface

utc_getusertime

utc_getusertime
Returns the time and process-specific TDF, rather than the system-specific TDF.

SYNOPSIS
#include <utc.h>
int utc_getusertime(*utc)
utc_t *utc;

PARAMETERS
Input
None.
Output
utc
System time as a binary timestamp.

DESCRIPTION
The Get User Time routine returns the system time and inaccuracy in a binary
timestamp. The routine takes the TDF from the user’s environment, which
determines the time zone rule (details are system dependent).
OpenVMS

UNIX

If the user’s environment does not specify a TDF, the system’s TDF is used. The
system’s time zone rule is applied (details of the rule are system dependent).
OpenVMS

UNIX

OpenVMS systems do not have a default time zone
rule. You must run the sys$manager:net$configure
procedure to specify a time zone.♦
The rule in /etc/zoneinfo/localtime applies. ♦

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Generic error that indicates the time service cannot be accessed.

DECdts Portable Applications Programming Interface 2–35

utc_getusertime

EXAMPLE
See the sample program in the Examples section of the utc_boundtime routine.

RELATED INFORMATION
Functions: utc_gettime

2–36 DECdts Portable Applications Programming Interface

utc_gmtime

utc_gmtime
Converts a binary timestamp to a tm structure that expresses GMT or the
equivalent UTC.

SYNOPSIS
#include <utc.h>
int utc_gmtime(*timetm, *tns, *inacctm, *ins, *utc)
struct tm *timetm;
long *tns;
struct tm *inacctm;
long *ins;
const utc_t *utc;

PARAMETERS
Input
utc
Binary timestamp to be converted to tm structure components.
Output
timetm
Time component of the binary timestamp.
tns
Nanoseconds since time component of the binary timestamp.
inacctm
Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is
finite, then tm_mday returns a value of –1 and tm_mon and tm_year return values
of zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is
infinite, all tm structure fields return values of –1.
ins
Nanoseconds of inaccuracy component of the binary timestamp. If the inaccuracy
is infinite, ins returns a value of –1.

DESCRIPTION
The Greenwich Mean Time (GMT) routine converts a binary timestamp to a

tm structure that expresses GMT (or the equivalent UTC). Additional returns
include nanoseconds since time and nanoseconds of inaccuracy.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

DECdts Portable Applications Programming Interface 2–37

utc_gmtime

EXAMPLE
See the sample program in the Examples section of the utc_cmpintervaltime
routine.

RELATED INFORMATION
Functions: utc_anytime, utc_gmtzone, utc_localtime, utc_mkgmtime

2–38 DECdts Portable Applications Programming Interface

utc_gmtzone

utc_gmtzone
Gets the time zone label for GMT.

SYNOPSIS
#include <utc.h>
int utc_gmtzone(*tzname, tzlen, *tdf, *isdst, *utc)
char *tzname;
size_t tzlen;
long *tdf;
int *isdst;
const utc_t *utc;

PARAMETERS
Input
tzlen
Length of buffer tzname.
utc
Binary timestamp. This parameter is ignored.
Output
tzname
Character string long enough to hold the time zone label.
tdf
Longword with differential in seconds east or west of GMT. A value of zero is
always returned.
isdst
Integer with a value of zero, indicating that daylight saving time is not in effect.
A value of zero is always returned.

DESCRIPTION
The Greenwich Mean Time Zone routine gets the time zone label and zero
offset from GMT. Outputs are always tdf = 0 and tzname = GMT. This routine
exists for symmetry with the Any Zone (utc_anyzone) and the Local Zone
(utc_localzone) routines.

NOTES
All of the output parameters are optional. No value is returned and no error
occurs if the tzname pointer is NULL.

RETURN VALUES
0

Indicates that the routine executed successfully (always returned).

DECdts Portable Applications Programming Interface 2–39

utc_gmtzone

EXAMPLE
The following example prints out the current time in both local time and GMT
time.
utc_t
struct tm
long
int
char

now;
tmlocal, tmgmt;
tzoffset;
tzdaylight;
tzlocal[80], tzgmt[80];

/*
* Get the current time once, so both conversions use the same
* time...
*/
utc_gettime(&now);
/*
* Convert to local time, using the process TZ environment
* variable...
*/
utc_localtime(&tmlocal,
/* Out: Local time tm structure
(long *)0,
/* Out: Nanosec of time
(struct tm *)0, /* Out: Inaccuracy tm structure
(long *)0,
/* Out: Nanosec of inaccuracy
&now);
/* In: Current binary timestamp

*/
*/
*/
*/
*/

/*
* Get the local time zone name, offset from GMT, and current
* daylight savings flag...
*/
utc_localzone(tzlocal,
80,
&tzoffset,
&tzdaylight,
&now);

/* Out: Local time zone name
*/
/* In: Length of loc time zone name */
/* Out: Loc time zone offset in secs */
/* Out: Local time zone daylight flag */
/* In: Current binary timestamp
*/

/*
* Convert to GMT...
*/
utc_gmtime(&tmgmt,
(long *)0,
(struct tm *)0,
(long *)0,
&now);

/* Out: GMT tm structure
/* Out: Nanoseconds of time
/* Out: Inaccuracy tm structure
/* Out: Nanoseconds of inaccuracy
/* In: Current binary timestamp

*/
*/
*/
*/
*/

/*
* Get the GMT time zone name...
*/
utc_gmtzone(tzgmt,
80,
(long *)0,
(int *)0,
&now);

/* Out: GMT time zone name
/* In: Size of GMT time zone name
/* Out: GMT time zone offset in secs
/* Out: GMT time zone daylight flag
/* In: Current binary timestamp

/*
* Print out times and time zone information in the following
* format:
*
*
12:00:37 (EDT) = 16:00:37 (GMT)
*
EDT is -240 minutes ahead of Greenwich Mean Time.
*
Daylight savings time is in effect.
*/

2–40 DECdts Portable Applications Programming Interface

*/
*/
*/
*/
*/

utc_gmtzone

printf("%d:%02d:%02d (%s) = %d:%02d:%02d (%s)\n",
tmlocal.tm_hour, tmlocal.tm_min, tmlocal.tm_sec, tzlocal,
tmgmt.tm_hour, tmgmt.tm_min, tmgmt.tm_sec, tzgmt);
printf("%s is %d minutes ahead of Greenwich Mean Time\n", tzlocal, tzoffset/60);
if (tzdaylight != 0)
printf("Daylight savings time is in effect\n");

RELATED INFORMATION
Functions: utc_anyzone, utc_gmtime, utc_localzone

DECdts Portable Applications Programming Interface 2–41

utc_localtime

utc_localtime
Converts a binary timestamp to a tm structure that expresses local time.

SYNOPSIS
#include <utc.h>
int utc_localtime(*timetm, *tns, *inacctm, *ins, *utc)
struct tm *timetm;
long *tns;
struct tm *inacctm;
long *ins;
const utc_t *utc;

PARAMETERS
Input
utc
Binary timestamp.
Output
timetm
Time component of the binary timestamp, expressing local time.
tns
Nanoseconds since time component of the binary timestamp.
inacctm
Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is
finite, then tm_mday returns a value of –1 and tm_mon and tm_year return values
of zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is
infinite, all tm structure fields return values of –1.
ins
Nanoseconds of inaccuracy component of the binary timestamp. If the inaccuracy
is infinite, ins returns a value of –1.

DESCRIPTION
The Local Time routine converts a binary timestamp to a tm structure that
expresses local time.
The user’s environment determines the time zone rule (details are system
dependent).
OpenVMS

The user selects a time zone by defining
sys$timezone_rule, which is created when the
sys$manager:net$configure.com is run. ♦

2–42 DECdts Portable Applications Programming Interface

utc_localtime

UNIX

The user selects a time zone by specifying the time
zone environment variable. (The reference page
for the localtime( ) system call provides additional
information.)♦

If the user’s environment does not specify a time zone rule, the system’s rule is
used (details of the rule are system dependent).
OpenVMS

UNIX

OpenVMS systems do not have a default time zone
rule. You must run the sys$manager:net$configure
procedure to specify a time zone.♦
The rule in /etc/zoneinfo/localtime applies. ♦

Additional returns include nanoseconds since time and nanoseconds of inaccuracy.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
See the sample program in the Examples section of the utc_gmtzone routine.

RELATED INFORMATION
Functions: utc_anytime, utc_gmtime, utc_localzone, utc_mklocaltime

DECdts Portable Applications Programming Interface 2–43

utc_localzone

utc_localzone
Gets the local time zone label and offset from GMT, given utc.

SYNOPSIS
#include <utc.h>
int utc_localzone(*tzname, tzlen, *tdf, *isdst, *utc)
char *tzname;
size_t tzlen;
long *tdf;
int *isdst;
const utc_t *utc;
#include <utc.h>
int utc_localzone(*tzname, tzlen, *tdf, *isdst, *utc)

PARAMETERS
Input
tzlen
Length of the tzname buffer.
utc
Binary timestamp.
Output
tzname
Character string long enough to hold the time zone label.
tdf
Longword with differential in seconds east or west of GMT.
isdst
Integer with a value of zero if standard time is in effect or a value of 1 if daylight
savings time is in effect.

DESCRIPTION
The Local Zone routine gets the local time zone label and offset from GMT, given

utc.
The user’s environment determines the time zone rule (details are system
dependent).
OpenVMS

UNIX

2–44 DECdts Portable Applications Programming Interface

utc_localzone

If the user’s environment does not specify a time zone rule, the system’s rule is
used (details of the rule are system dependent).
OpenVMS

UNIX

OpenVMS systems do not have a default time zone
rule. You must run the sys$manager:net$configure
procedure to specify a time zone.♦
The rule in /etc/zoneinfo/localtime applies. ♦

NOTES
All of the output parameters are optional. No value is returned and no error
occurs if the pointer is null.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or an insufficient buffer.

EXAMPLE
See the sample program in the Examples section of the utc_gmtzone routine.

RELATED INFORMATION
Functions: utc_anyzone, utc_gmtzone, utc_localtime

DECdts Portable Applications Programming Interface 2–45

utc_mkanytime

utc_mkanytime
Converts a tm structure and TDF (expressing the time in an arbitrary time zone)
to a binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_mkanytime(*utc, *timetm, tns, *inacctm, ins, tdf)
utc_t *utc;
const struct tm *timetm;
long tns;
const struct tm *inacctm;
long ins;
long tdf;

PARAMETERS
Input
timetm
A tm structure that expresses the local time; tm_wday and tm_yday are ignored on
input.
tns
Nanoseconds since time component.
inacctm
A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If
tm_yday is negative, the inaccuracy is considered to be infinite; tm_mday, tm_mon,
tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored on input.
ins
Nanoseconds of inaccuracy component.
tdf
Time differential factor to use in conversion.
Output
utc
Resulting binary timestamp.

DESCRIPTION
The Make Any Time routine converts a tm structure and TDF (expressing the
time in an arbitrary time zone) to a binary timestamp. Required inputs include
nanoseconds since time and nanoseconds of inaccuracy.

2–46 DECdts Portable Applications Programming Interface

utc_mkanytime

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
The following example converts a string ISO format time in an arbitrary time
zone to a binary timestamp. This may be part of an input timestamp routine,
although a real implementation will include range checking.
utc_t
struct tm
float
double
long
int
char

utc;
tmtime, tminacc;
tsec, isec;
tmp;
tnsec, insec;
i, offset, tzhour, tzmin, year, mon;
*string;

/* Try to convert the string...

if(sscanf(string, "%d-%d-%d-%d:%d:%e+%d:%dI%e",
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
&tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) {
/* Try again with a negative TDF...

if (sscanf(string, "%d-%d-%d-%d:%d:%e-%d:%dI%e",
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
&tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) {
/* ERROR

exit(1);
}
/* TDF is negative

tzhour = -tzhour;
tzmin = -tzmin;
}
/* Fill in the fields...

tmtime.tm_year = year - 1900;
tmtime.tm_mon = --mon;
tmtime.tm_sec = tsec;
tnsec = (modf(tsec, &tmp)*1.0E9);
offset = tzhour*3600 + tzmin*60;
tminacc.tm_sec = isec;
insec = (modf(isec, &tmp)*1.0E9);
/* Convert to a binary timestamp...

utc_mkanytime(&utc,
&tmtime,
tnsec,
&tminacc,
insec,
offset);

*/
*/
*/
*/
*/
*/

/* Out: Resultant binary timestamp
/* In: tm struct that represents input
/* In: Nanoseconds from input
/* In: tm struct that represents inacc
/* In: Nanoseconds from input
/* In: TDF from input

DECdts Portable Applications Programming Interface 2–47

utc_mkanytime

RELATED INFORMATION
Functions: utc_anytime, utc_anyzone

2–48 DECdts Portable Applications Programming Interface

utc_mkascreltime

utc_mkascreltime
Converts a null-terminated character string that represents a relative timestamp
to a binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_mkascreltime(*utc, *string)
utc_t *utc;
char *string;

PARAMETERS
Input
string
A null-terminated string that expresses a relative timestamp in its ISO format.
Output
utc
Resulting binary timestamp.

DESCRIPTION
The Make ASCII Relative Time routine converts a null-terminated string,
which represents a relative timestamp, to a binary timestamp.

NOTES
The ASCII string must be null-terminated.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid results.

EXAMPLE
The following example converts an ASCII relative time string to its binary
equivalent.
utc_t
char

utc;
str[UTC_MAX_STR_LEN];

/*
* Relative time of 333 days, 12 hours, 1 minute, 37.223 seconds
* Inaccuracy of 50.22 seconds in the format: -333-12:01:37.223I50.22
*/
(void)strcpy((void *)str,
"-333-12:01:37.223I50.22");

DECdts Portable Applications Programming Interface 2–49

utc_mkascreltime

utc_mkascreltime(&utc,
str);

/* Out: Binary utc
/* In: String

RELATED INFORMATION
Functions: utc_ascreltime

2–50 DECdts Portable Applications Programming Interface

*/
*/

utc_mkasctime

utc_mkasctime
Converts a null-terminated character string that represents an absolute time to a
binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_mkasctime(*utc, *string)
utc_t *utc;
char *string;

PARAMETERS
Input
string
A null-terminated string that expresses an absolute time.
Output
utc
Resulting binary timestamp.

DESCRIPTION
The Make ASCII Time routine converts a null-terminated string that represents
an absolute time to a binary timestamp.

NOTES
The ASCII string must be null-terminated.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time parameter or invalid results.

EXAMPLE
The following example converts an ASCII time string to its binary equivalent.
utc_t
char

utc;
str[UTC_MAX_STR_LEN];

/*
* July 4, 1776, 12:01:37.223 local time
* TDF of -5:00 hours
* Inaccuracy of 3600.32 seconds
*/
(void)strcpy((void *)str,
"1776-07-04-12:01:37.223-5:00 I 3600.32");
utc_mkasctime(&utc,
str);

/* Out: Binary utc
/* In: String

*/
*/

DECdts Portable Applications Programming Interface 2–51

utc_mkasctime

RELATED INFORMATION
Functions: utc_ascanytime, utc_ascgmtime, utc_asclocaltime

2–52 DECdts Portable Applications Programming Interface

utc_mkbinreltime

utc_mkbinreltime
Converts a timespec structure expressing a relative time to a binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_mkbinreltime(*utc, *timesp, *inaccsp)
utc_t *utc;
const reltimespec_t *timesp;
const timespec_t *inaccsp;

PARAMETERS
Input
timesp
A reltimespec structure that expresses a relative time.
inaccsp
A timespec structure that expresses inaccuracy. If tv_sec is set to a value of –1,
the inaccuracy is considered to be infinite.
Output
utc
Resulting relative binary timestamp.

DESCRIPTION
The Make Binary Relative Time routine converts a timespec structure that
expresses relative time to a binary timestamp.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
See the sample program in the Examples section of the utc_addtime routine.

RELATED INFORMATION
Functions: utc_binreltime, utc_mkbintime

DECdts Portable Applications Programming Interface 2–53

utc_mkbintime

utc_mkbintime
Converts a timespec structure to a binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_mkbintime(*utc, *timesp, *inaccsp)
utc_t *utc;
const timespec_t *timesp;
const timespec_t *inaccsp;
long tdf;

PARAMETERS
Input
timesp
A timespec structure that expresses time since 1970-01-01:00:00:00.0+0:00I0.
inaccsp
A timespec structure that expresses inaccuracy. If tv_sec is set to a value of –1,
the inaccuracy is considered to be infinite.
tdf
TDF component of the binary timestamp.
Output
utc
Resulting binary timestamp.

DESCRIPTION
The Make Binary Time routine converts a timespec structure time to a binary
timestamp. The TDF input is used as the TDF of the binary timestamp.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
The following example obtains the current time from time( ), converts it to a
binary timestamp with an inaccuracy of 5.2 seconds, and specifies GMT.
timespec_t
utc_t

ttime, tinacc;
utc;

/*
* Obtain the current time (without the inaccuracy)...
*/

2–54 DECdts Portable Applications Programming Interface

utc_mkbintime

ttime.tv_sec = time((time_t *)0);
ttime.tv_nsec = 0;
/*
* Specify the inaccuracy...
*/
tinacc.tv_sec = 5;
tinacc.tv_nsec = 200000000;
/*
* Convert to a binary timestamp...
*/
utc_mkbintime(&utc,
&ttime,
&tinacc,
0);

/* Out: Binary timestamp
/* In: Current time in timespec
/* In: 5.2 seconds in timespec
/* In: TDF of GMT

*/
*/
*/
*/

RELATED INFORMATION
Functions: utc_bintime, utc_mkbinreltime

DECdts Portable Applications Programming Interface 2–55

utc_mkgmtime

utc_mkgmtime
Converts a tm structure that expresses GMT or UTC to a binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_mkgmtime(*utc, *timetm, tns, *inacctm, ins)
utc_t *utc;
const struct tm *timetm;
long tns;
const struct tm *inacctm;
long ins;

PARAMETERS
Input
timetm
A tm structure that expresses GMT. On input, tm_wday and tm_yday are ignored.
tns
Nanoseconds since time component.
inacctm
A tm structure that expresses days, hours, minutes, and seconds of inaccuracy.
If tm_yday is negative, the inaccuracy is considered to be infinite. On input,
tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored.
ins
Nanoseconds of inaccuracy component.
Output
utc
Resulting binary timestamp.

DESCRIPTION
The Make Greenwich Mean Time routine converts a tm structure that
expresses GMT or UTC to a binary timestamp. Additional inputs include
nanoseconds since the last second of time and nanoseconds of inaccuracy.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

2–56 DECdts Portable Applications Programming Interface

utc_mkgmtime

EXAMPLE
See the sample program in the Examples section of the utc_cmpintervaltime
routine.

RELATED INFORMATION
Functions: utc_gmtime

DECdts Portable Applications Programming Interface 2–57

utc_mklocaltime

utc_mklocaltime
Converts a tm structure that expresses local time to a binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_mklocaltime(*utc, *timetm, tns, *inacctm, ins)
utc_t *utc;
const struct tm *timetm;
long tns;
const struct tm *inacctm;
long ins;

PARAMETERS
Input
timetm
A tm structure that expresses the local time. On input, tm_wday and tm_yday are
ignored.
tns
Nanoseconds since time component.
inacctm
A tm structure that expresses days, hours, minutes, and seconds of inaccuracy.
If tm_yday is negative, the inaccuracy is considered to be infinite. On input,
tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored.
ins
Nanoseconds of inaccuracy component.
Output
utc
Resulting binary timestamp.

DESCRIPTION
The Make Local Time routine converts a tm structure that expresses local time
to a binary timestamp.
The user’s environment determines the time zone rule (details are system
dependent).
OpenVMS

UNIX

2–58 DECdts Portable Applications Programming Interface

utc_mklocaltime

If the user’s environment does not specify a time zone rule, the system’s rule is
used (details of the rule are system dependent).
OpenVMS

UNIX

OpenVMS systems do not have a default time zone
rule. You must run the sys$manager:net$configure
procedure to specify a time zone.♦
The rule in /etc/zoneinfo/localtime applies. ♦

Additional inputs include nanoseconds since the last second of time and
nanoseconds of inaccuracy.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
See the sample program in the Examples section of the utc_cmpmidtime routine.

RELATED INFORMATION
Functions: utc_localtime

DECdts Portable Applications Programming Interface 2–59

utc_mkreltime

utc_mkreltime
Converts a tm structure that expresses relative time to a relative binary
timestamp.

SYNOPSIS
#include <utc.h>
int utc_mkreltime(*utc, *timetm, tns, *inacctm, ins)
utc_t *utc;
const struct tm *timetm;
long tns;
const struct tm *inacctm;
long ins;

PARAMETERS
Input
timetm
A tm structure that expresses a relative time. On input, tm_wday and tm_yday are
ignored.
tns
Nanoseconds since time component.
inacctm
A tm structure that expresses seconds of inaccuracy. If tm_yday is negative, the
inaccuracy is considered to be infinite. On input, tm_mday, tm_mon, tm_year,
tm_wday, tm_isdst, and tm_zone are ignored.
ins
Nanoseconds of inaccuracy component.
Output
utc
Resulting relative binary timestamp.

DESCRIPTION
The Make Relative Time routine converts a tm structure that expresses relative
time to a relative binary timestamp. Additional inputs include nanoseconds since
the last second of time and nanoseconds of inaccuracy.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

2–60 DECdts Portable Applications Programming Interface

utc_mkreltime

EXAMPLE
The following example converts a string relative time in the format (1991-04-0112:12:12.12I12.12) to a binary timestamp. This may be part of an input relative
timestamp routine, though a real implementation will include range checking.
utc_t
struct tm
float
double
long
int
char

utc;
tmtime, tminacc;
tsec, isec;
tmp;
tnsec, insec;
i, tzhour, tzmin, year, mon;
*string;

/*
* Try to convert the string...
*/
if(sscanf(string, "%d-%d-%d-%d:%d:%eI%e",
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
&tmtime.tm_min, &tsec, &isec) != 7) {
/*
* ERROR...
*/
exit(1);
}
/*
* Fill in the fields...
*/
tmtime.tm_year = year - 1900;
tmtime.tm_mon = --mon;
tmtime.tm_sec = tsec;
tnsec = (modf(tsec, &tmp)*1.0E9);
tminacc.tm_sec = isec;
insec = (modf(isec, &tmp)*1.0E9);
/*
* Convert to a binary timestamp...
*/
utc_mkreltime(&utc,
&tmtime,
tnsec,
&tminacc,
insec);

/* Out: Resultant binary timestamp
/* In: tm struct that represents input
/* In: Nanoseconds from input
/* In: tm struct that represents inacc
/* In: Nanoseconds from input

*/
*/
*/
*/
*/

RELATED INFORMATION
Functions: utc_reltime

DECdts Portable Applications Programming Interface 2–61

utc_mkvmsanytime

utc_mkvmsanytime
OpenVMS

Converts a binary OpenVMS format time and TDF (expressing the time in an
arbitrary time zone) to a binary timestamp.

SYNOPSIS
#include <utc.h>
int utc_mkvmsanytime(*utc, *timadr, tdf)
utc_t *utc;
const long *timadr;
const long tdf;

PARAMETERS
Input
*timadr
Binary OpenVMS format time.
tdf
Time differential factor to use in conversion.
Output
*utc
Binary timestamp.

DESCRIPTION
The Make VMS Any Time routine converts a binary time in the OpenVMS
(Smithsonian) format and an arbitrary TDF to a UTC-based binary timestamp.
Because the input and output values are based on different time standards, any
input representing a value after A.D. 30,000 returns an error.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
The following example shows how to convert between OpenVMS format binary
timestamps and UTC binary timestamps, while specifying the TDF for each. The
TDF value determines the offset from GMT and the local time.
/*****
start example mkvmsanytime,vmsanytime
*****/
#include <utc.h>

2–62 DECdts Portable Applications Programming Interface

utc_mkvmsanytime

main()
{
struct utc utcTime;
int vmsTime[2];
SYS$GETTIM(vmsTime);

/* read the current time */

/*
* convert the VMS local time to a UTC, applying a TDF of
* -300 minutes (the timezone is -5 hours from GMT)
*/
if (utc_mkvmsanytime(&utcTime,vmsTime,-300))
exit(1);
/*
* convert UTC back to VMS local time. A TDF of -300 is applied
* to the UTC, since utcTime was constructed with that same value.
* This effectively gives us the same VMS time value we started
* with.
*/
if (utc_vmsanytime(vmsTime,&utcTime))
exit(2);
}
/****
end example
****/

RELATED INFORMATION
Function: utc_vmsanytime ♦

DECdts Portable Applications Programming Interface 2–63

utc_mkvmsgmtime

utc_mkvmsgmtime
OpenVMS

Converts a binary OpenVMS format time expressing GMT (or the equivalent
UTC) into a binary timestamp.

SYNOPSIS
PARAMETERS
Input
*timadr
Binary OpenVMS format time representing GMT or the UTC equivalent.
Output
*utc
Binary timestamp.

DESCRIPTION
The Make VMS Greenwich Mean Time routine converts an OpenVMS format
binary time representing GMT to a binary timestamp with the equivalent UTC
value. Since the input and output values are based on different time standards,
any input representing a value after A.D. 30,000 returns an error.

RETURN VALUES

EXAMPLE
See the sample program in the Examples section of the vmsgmtime routine.

RELATED INFORMATION
Function: utc_vmsgmtime ♦

2–64 DECdts Portable Applications Programming Interface

utc_mkvmslocaltime

utc_mkvmslocaltime
OpenVMS

Converts a local binary OpenVMS format time to a binary timestamp, using the
host system’s time differential factor.

SYNOPSIS
#include <utc.h>
int utc_mkvmslocaltime(*utc, *timadr)
const long *timadr;
utc_t *utc;

PARAMETERS
Input
*timadr
Binary OpenVMS format time expressing local time.
Output
*utc
Binary timestamp expressing the system’s local time.

DESCRIPTION
The Make VMS Local Time routine converts a binary OpenVMS
format time, representing the local time of the host system, to a binary
timestamp. The system’s local time value is defined by the time zone rule
in sys$timezone_rule, which is created by the system configuration process
sys$manager:net$configure.com.

NOTES
If the routine call is made during a seasonal time zone change when the local
time is indeterminate, an error is returned. For example, if the time zone change
occurs at the current local time of 2:00 A.M. to a new local time of 1:00 A.M., and
the routine is called between 1:00 A.M. and 2:00 A.M., it cannot be determined
which TDF applies.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument, invalid results, or invalid routine call
during a time zone change.

DECdts Portable Applications Programming Interface 2–65

utc_mkvmslocaltime

EXAMPLE
The following example shows how to retrieve the current local time of the
system in the binary OpenVMS format, convert the OpenVMS format time to
a UTC-based binary timestamp (using the system’s TDF), and print an ASCII
representation of the binary timestamp.
/*********
start example mkvmslocaltime
*********/
#include <utc.h>
main()
{
char outstring[UTC_MAX_STR_LEN];
struct utc utcTime;
int vmsTime[2];
SYS$GETTIM(vmsTime);

/* read curr time

if (utc_mkvmslocaltime(&utcTime,vmsTime)) /* convert the local time */
exit(1);
/* vmsTime to UTC using */
/* the system tdf.

utc_asclocaltime(outstring,UTC_MAX_STR_LEN,&utcTime); /* convert to ISO ascii*/
printf("Current time=> %s\n",outstring);
/* format and print */
}
/*****
end example
*****/

RELATED INFORMATION
Function: utc_vmslocaltime ♦

2–66 DECdts Portable Applications Programming Interface

utc_mulftime

utc_mulftime
Multiplies a relative binary timestamp by a floating-point value.

SYNOPSIS
#include <utc.h>
int utc_mulftime(*result, *utc1, factor)
utc_t *result;
const utc_t *utc1;
const double factor;

PARAMETERS
Input
utc1
Relative binary timestamp.
factor
Real scale factor (double-precision floating-point) (G format floating-point on VAX
systems).
Output
result
Resulting relative binary timestamp.

DESCRIPTION
The Multiply a Relative Time by a Real Factor routine multiplies a relative
binary timestamp by a floating-point value. Either or both may be negative;
the resulting relative binary timestamp has the appropriate sign. The unsigned
inaccuracy in the relative binary timestamp is also multiplied by the absolute
value of the floating-point value.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

The following example scales and prints a relative time.
utc_t
struct tm
char

relutc, scaledutc;
sacledreltm;
timstr[UTC_MAX_STR_LEN];

/*
* Assume relutc contains the time to scale. Scale it by a factor of 17...
*/
utc_multime(&scaledutc,
&relutc,
17L);

/* Out: Scaled rel time
/* In: Rel time to scale
/* In: Scale factor

*/
*/
*/

DECdts Portable Applications Programming Interface 2–67

utc_mulftime

utc_ascreltime(timstr,
UTC_MAX_STR_LEN,
&scaledutc);

/* Out: ASCII rel time
*/
/* In: Length of input str */
/* In: Rel time to convert */

printf("%s\n",timstr);
/*
* Scale it by a factor of 17.65...
*/
utc_mulftime(&scaledutc,
&relutc,
17.65);

/* Out: Scaled rel time
/* In: Rel time to scale
/* In: Scale factor

*/
*/
*/

utc_ascreltime(timstr,
UTC_MAX_STR_LEN,
&scaledutc);

/* Out: ASCII rel time
*/
/* In: Input str length
*/
/* In: Rel time to convert */

printf("%s\n",timstr);
/*
*
*/

Convert it to a tm structure and print it.

utc_reltime(&scaledreltm,
(long *)0,
(struct tm *)0,
(long *)0,
&scaledutc);

/* Out: Scaled rel tm
*/
/* Out: Scaled rel nano-sec */
/* Out: Scaled rel inacc tm */
/* Out: Scd rel inacc nanos */
/* In: Rel time to convert */

printf("Approximately %d days, %d hours and %d minutes\n",
scaledreltm.tm_yday, scaledreltm.tm_hour, scaledreltm.tm_min);

RELATED INFORMATION
Functions: utc_multime

2–68 DECdts Portable Applications Programming Interface

utc_multime

utc_multime
Multiplies a relative binary timestamp by an integer factor.

SYNOPSIS
#include <utc.h>
int utc_multime(*result, *utc1, factor)
utc_t *result;
const utc_t *utc1;
long factor;

PARAMETERS
Input
utc1
Relative binary timestamp.
factor
Integer scale factor.
Output
result
Resulting relative binary timestamp.

DESCRIPTION
The Multiply Relative Time by an Integer Factor routine multiplies a
relative binary timestamp by an integer. Either or both may be negative; the
resulting binary timestamp has the appropriate sign. The unsigned inaccuracy in
the binary timestamp is also multiplied by the absolute value of the integer.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
See the sample program in the Examples section of the utc_mulftime routine.

RELATED INFORMATION
Functions: utc_mulftime

DECdts Portable Applications Programming Interface 2–69

utc_pointtime

utc_pointtime
Converts a binary timestamp to three binary timestamps that represent the
earliest, most likely, and latest time.

SYNOPSIS
#include <utc.h>
int utc_pointtime(*utclp, *utcmp, *utchp, *utc)
utc_t *utclp;
utc_t *utcmp;
utc_t *utchp;
const utc_t *utc;

PARAMETERS
Input
utc
Binary timestamp or relative binary timestamp.
Output
utclp
Lowest (earliest) possible time that the input binary timestamp or shortest
possible relative time that the relative binary timestamp can represent.
utcmp
Midpoint of the input binary timestamp or the midpoint of the input relative
binary timestamp.
utchp
Highest (latest) possible time that the input binary timestamp or the longest
possible relative time that the relative binary timestamp can represent.

DESCRIPTION
The Point Time routine converts a binary timestamp to three binary timestamps
that represent the earliest, latest, and most likely (midpoint) times. If the input
is a relative binary time, the outputs represent relative binary times.

NOTES
All outputs have zero inaccuracy. An error is returned if the input binary
timestamp has an infinite inaccuracy.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument.

2–70 DECdts Portable Applications Programming Interface

utc_pointtime

EXAMPLE
See the sample program in the Examples section of the utc_addtime routine.

RELATED INFORMATION
Functions: utc_boundtime, utc_spantime

DECdts Portable Applications Programming Interface 2–71

utc_reltime

utc_reltime
Converts a relative binary timestamp to a tm structure.

SYNOPSIS
#include <utc.h>
int utc_reltime(*timetm, *tns, *inacctm, *ins, *utc)
struct tm *timetm;
long *tns;
struct tm *inacctm;
long *ins;
const utc_t *utc;

PARAMETERS
Input
utc
Relative binary timestamp.
Output
timetm
Relative time component of the relative binary timestamp. The field tm_mday
returns a value of –1 and the fields tm_year and tm_mon return values of zero.
The field tm_yday contains the number of days of relative time.
tns
Nanoseconds since time component of the relative binary timestamp.
inacctm
Seconds of inaccuracy component of the relative binary timestamp. If the
inaccuracy is finite, then tm_mday returns a value of –1 and tm_mon and tm_year
return values of zero. The field tm_yday contains the inaccuracy in days. If the
inaccuracy is infinite, all tm structure fields return values of –1.
ins
Nanoseconds of inaccuracy component of the relative binary timestamp.

DESCRIPTION
The Relative Time routine converts a relative binary timestamp to a tm
structure. Additional returns include nanoseconds since time and nanoseconds of
inaccuracy.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

2–72 DECdts Portable Applications Programming Interface

utc_reltime

EXAMPLE
See the sample program in the Examples section of the utc_mulftime routine.

RELATED INFORMATION
Functions: utc_mkreltime

DECdts Portable Applications Programming Interface 2–73

utc_spantime

utc_spantime
Given two (possibly unordered) binary timestamps, returns a single UTC time
interval whose inaccuracy spans the two input binary timestamps.

SYNOPSIS
#include <utc.h>
int utc_spantime(*result, *utc1, *utc2)
utc_t *result;
const utc_t *utc1;
const utc_t *utc2;

PARAMETERS
Input
utc1
Binary timestamp.
utc2
Binary timestamp.
Output
result
Spanning timestamp.

DESCRIPTION
Given two binary timestamps, the Span Time routine returns a single UTC time
interval whose inaccuracy spans the two input timestamps (that is, the interval
resulting from the earliest possible time of either timestamp to the latest possible
time of either timestamp).

NOTES
The tdf in the output UTC value is copied from the utc2 input. If either input
binary timestamp has an infinite inaccuracy, an error is returned.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument.

2–74 DECdts Portable Applications Programming Interface

utc_spantime

EXAMPLE
The following example computes the earliest and latest times for an array of 10
timestamps.
utc_t
int

time_array[10], testtime, earliest, latest;
i;

/*
* Set the running timestamp to the first entry...
*/
testtime = time_array[0];
for (i=1; i<10; i++) {
/*
* Compute the minimum and the maximum against the next
* element...
*/
utc_spantime(&testtime,
/* Out: Resultant interval
&testtime,
/* In: Largest previous interval
&time_array[i]); /* In: Element under test
}

*/
*/
*/

/*
* Compute the earliest possible time...
*/
utc_pointtime(&earliest,
(utc_t *)0,
&latest,
&testtime);

/* Out: Earliest poss time in array */
/* Out: Midpoint
*/
/* Out: Latest poss time in array */
/* In: Spanning interval
*/

RELATED INFORMATION
Functions: utc_boundtime, utc_gettime, utc_pointtime

DECdts Portable Applications Programming Interface 2–75

utc_subtime

utc_subtime
Computes the difference between two binary timestamps that express either an
absolute time and a relative time, two relative times, or two absolute times.

SYNOPSIS
#include <utc.h>
int utc_subtime(*result, *utc1, *utc2)
utc_t *result;
const utc_t *utc1;
const utc_t *utc2;

absolute time 0 absolute time = relative time
relative time 0 relative time = relative time

absolute time 0 relative time = absolute time

relative time 0 absolute time is undefined. See NOTES.

DESCRIPTION
The Subtract Time routine subtracts one binary timestamp from another.
The resulting timestamp is utc1 minus utc2. The inaccuracies of the two input
timestamps are combined and included in the output timestamp. The TDF in the
first timestamp is copied to the output.

NOTES
Although no error is returned, do not use the combination relative time 0
absolute time.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

2–76 DECdts Portable Applications Programming Interface

utc_subtime

EXAMPLE
See the sample program in the Examples section of the utc_binreltime routine.

RELATED INFORMATION
Functions: utc_addtime

DECdts Portable Applications Programming Interface 2–77

utc_vmsanytime

utc_vmsanytime
OpenVMS

Converts a binary timestamp to a binary OpenVMS format time. The TDF
encoded in the input timestamp determines the TDF of the output.

SYNOPSIS
#include <utc.h>
int utc_vmsanytime(*timadr, *utc)
const utc_t *utc;
long *timadr;

PARAMETERS
Input
*utc
Binary timestamp.
Output
*timadr
Binary OpenVMS format time.

DESCRIPTION
The VMS Any Time routine converts a UTC-based binary timestamp to a 64-bit
binary time in the OpenVMS (Smithsonian) format. Because the input and
output values are based on different time standards, any input representing a
value before the Smithsonian base time of November 17, 1858 returns an error.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
See the sample program in the Examples section of the mkvmsanytime routine.

RELATED INFORMATION
Function: utc_mkvmsanytime ♦

2–78 DECdts Portable Applications Programming Interface

utc_vmsgmtime

utc_vmsgmtime
OpenVMS

Converts a binary timestamp to a binary OpenVMS format time expressing GMT
or the equivalent UTC.

SYNOPSIS
#include <utc.h>
int utc_vmsgmtime(*timadr, *utc)
const utc_t *utc;
long *timadr;

PARAMETERS
Input
*utc
Binary timestamp to be converted.
Output
*timadr
Binary OpenVMS format time representing GMT or the UTC equivalent.

DESCRIPTION
The OpenVMS Greenwich Mean Time routine converts a UTC-based binary
timestamp to a 64-bit binary time in the OpenVMS (Smithsonian) format. The
OpenVMS format time represents Greenwich Mean Time or the equivalent UTC.
Because the input and output values are based on different time standards, any
input representing a value before the Smithsonian base time of November 17,
1858 returns an error.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
The following example shows the following time zone and time format
conversions:
1. Retrieve a binary timestamp representing UTC with the sys$getutc system
service.
2. Convert the binary timestamp to a OpenVMS format binary time representing
GMT
3. Convert the OpenVMS format binary time representing GMT back to a
UTC-based binary timestamp with a TDF of 0 (zero)

DECdts Portable Applications Programming Interface 2–79

utc_vmsgmtime

4. Convert the UTC-based binary time to a binary OpenVMS format time
representing the local time; use the TDF from the system
/*****
start example vmsgmtime, mkvmsgmtime, vmslocaltime
*****/
#include <utc.h>
main()
{
int status;
struct utc utcTime;
int vmsTime[2];
if (!((status=SYS$GETUTC(&utcTime))&1))
exit(status);
/* read curr time as a utc */
/*
* convert the utcvalue into a vms time, with a timezone of 0
* (GMT). Printing the resultant vmstime yields the time at
* the prime meridian in Greenwich, not (necessarily) the local time.
*/
if (utc_vmsgmtime(vmsTime,&utcTime))
exit(1);
/*
* Convert the vmstime (which is in GMT) to a utc
*/
if (utc_mkvmsgmtime(&utcTime, vmsTime))
exit(2);
/*
* convert the UTC to local 64-bit time. Note that this is the
* value we would have read if we had issued a ’SYS$GETTIM’ in
* the initial statement.
*/
if (utc_vmslocaltime(vmsTime, &utcTime))
exit(3);
}
/*****
end example
*****/

RELATED INFORMATION
Function: utc_mkvmsgmtime ♦

2–80 DECdts Portable Applications Programming Interface

utc_vmslocaltime

utc_vmslocaltime
OpenVMS

Converts a binary timestamp to a local binary OpenVMS format time, using the
host system’s time differential factor.

SYNOPSIS
#include <utc.h>
int utc_vmslocaltime(*timadr, *utc)
const utc_t *utc;
long *timadr;

PARAMETERS
Input
*utc
Binary timestamp.
Output
*timadr
Binary OpenVMS format time expressing local time.

DESCRIPTION
The VMS Local Time routine converts a binary timestamp to a binary OpenVMS
format time; the output value represents the local time of the host system. The
system’s offset from UTC and the local time value are defined by the time zone
rule in sys$timezone_rule, which is created by the system configuration process
sys$manager:net$configure.com.

RETURN VALUES
0
–1

Indicates that the routine executed successfully.
Indicates an invalid time argument or invalid results.

EXAMPLE
See the sample program in the Examples section of the vmsgmtime routine.

RELATED INFORMATION
Function: utc_vmsmklocaltime ♦

DECdts Portable Applications Programming Interface 2–81

3
Using the DECdts API Routines
This chapter contains a C programming example showing a practical application
of the DECdts API programming routines. The program performs the following
actions:
•

Prompts the user to enter time coordinates.

•

Stores those coordinates in a tm structure.

•

Converts the tm structure to a utc structure.

•

Determines which event occurred first.

•

Determines if Event 1 may have caused Event 2 by comparing the intervals.

•

Prints out the utc structure in ISO text format.

#include <time.h>
#include <utc.h>

/* time data structures
/* utc structure definitions

*/
*/

void ReadTime();
void PrintTime();
/*
* This program requests user input about events, then prints out
* information about those events.
*/
main()
{
struct utc event1,event2;
enum utc_cmptype relation;
/*
* Read in the two events.
*/
ReadTime(&event1);
ReadTime(&event2);
/*
* Print out the two events.
*/
printf("The first event is : ");
PrintTime(&event1);
printf("\nThe second event is : ");
PrintTime(&event2);
printf("\n");
/*
* Determine which event occurred first.
*/
if (utc_cmpmidtime(&relation,&event1,&event2))
exit(1);

Using the DECdts API Routines 3–1

switch( relation )
{
case utc_lessThan:
printf("comparing midpoints: Event1 < Event2\n");
break;
case utc_greaterThan:
printf("comparing midpoints: Event1 > Event2\n");
break;
case utc_equalTo:
printf("comparing midpoints: Event1 == Event2\n");
break;
default:
exit(1);
break;
}
/*
* Could Event 1 have caused Event 2? Compare the intervals.
*/
if (utc_cmpintervaltime(&relation,&event1,&event2))
exit(1);
switch( relation )
{
case utc_lessThan:
printf("comparing intervals: Event1 < Event2\n");
break;
case utc_greaterThan:
printf("comparing intervals: Event1 > Event2\n");
break;
case utc_equalTo:
printf("comparing intervals: Event1 == Event2\n");
break;
case utc_indeterminate:
printf("comparing intervals: Event1 ? Event2\n");
default:
exit(1);
break;
}
}
/*
* Print out a utc structure in ISO text format.
*/
void PrintTime(utcTime)
struct utc *utcTime;
{
char

string[50];

/*
* Break up the time string.
*/
if (utc_ascgmtime(string,
50,
utcTime))
exit(1);
printf("%s\n",string);

/* Out: Converted time
/* In: String length
/* In: Time to convert

*/
*/
*/

}
/*
* Prompt the user to enter time coordinates. Store the coordinates
* in a tm structure and then convert the tm structure to a utc structure.
*/

3–2 Using the DECdts API Routines

void ReadTime(utcTime)
struct utc *utcTime;
{
struct tm tmTime,tmInacc;
(void)memset((void *)&tmTime, 0,sizeof(tmTime));
(void)memset((void *)&tmInacc, 0,sizeof(tmInacc));
(void)printf("Year? ");
(void)scanf("%d",&tmTime.tm_year);
tmTime.tm_year -= 1900;
(void)printf("Month? ");
(void)scanf("%d",&tmTime.tm_mon);
tmTime.tm_mon -= 1;
(void)printf("Day? ");
(void)scanf("%d",&tmTime.tm_mday);
(void)printf("Hour? ");
(void)scanf("%d",&tmTime.tm_hour);
(void)printf("Minute? ");
(void)scanf("%d",&tmTime.tm_min);
(void)printf("Inacc Secs? ");
(void)scanf("%d",&tmInacc.tm_sec);
if (utc_mkanytime(utcTime,
&tmTime,
(long)0,
&tmInacc,
(long)0,
(long)0))
exit(1);
}
OpenVMS

Assume the preceding program is named compare_events.c. To compile and
link the program on a DECnet-Plus for OpenVMS system, enter the following
command:
$ cc compare_events.c/output=compare_events.obj
$ link compare_events.obj, sys$input:/options Return
sys$library:dtss$shr.exe/share Ctrl-z
$
♦

UNIX

To compile and link the program on a DECnet-Plus for Digital UNIX system,
enter the following command:
# cc compare_events.c -lutc -o compare_events
#
♦

Using the DECdts API Routines 3–3

4
Time-Provider Interface
This chapter describes the Digital Distributed Time Service (DECdts)
time-provider interface (TPI) for DECdts software on systems running the
DECnet-Plus for Digital UNIX and DECnet-Plus for OpenVMS operating
systems. The chapter begins with a brief overview of the TPI and explains how to
use external time-providers with DECdts; the rest of the chapter describes the
data structures and message protocols that make up the TPI.
Coordinated Universal Time (UTC) is disseminated throughout the world by
various standards organizations. Several manufacturers supply devices that can
acquire UTC time values via radio, satellite, or telephone; these devices can then
provide standardized time values to computer systems. Typically, one of these
devices is connected to a computer system; a process runs on the system and
interacts with the device to interpret signals and translate them to time values,
which can either be displayed or be provided to a server process running on a
connected system.
To synchronize its system clock with UTC using an external time-provider
device, a DECdts server needs a software interface to the device to periodically
obtain UTC. This interface is the intermediary between the DECdts server and
external time-provider processes. The server requires the interface to obtain
UTC time values and to determine the associated inaccuracy of each value. The
interface between the DECdts server and the time-provider process is called the
Time-Provider Interface.
The remainder of this chapter describes the TPI and its attendant processes
in detail. The following section describes the control flow between the DECdts
server process, the TPI, and the time-provider process.

4.1 General TPI Control Flow
When you use a time-provider with a system running DECdts, an external timeprovider is implemented as an independent process that exchanges messages
with DECdts (mailbox messages with OpenVMS, socket messages with Digital
UNIX). The DECdts server and the time-provider process (TP process) must both
be running on the same system. The DECdts server initiates communication with
the TP process by sending a connection request to the TP process.
OpenVMS

UNIX

At each system synchronization, a DECdts server
contacts the TP process by issuing a connect request to
a well known OpenVMS mailbox, which is identified by
the system logical name DTSS$_TSTP_MBX (also referred
to as the request mailbox).♦
The connect request is issued to a well known UNIX
domain socket, which is identified by the name /usr/var
/tmp/dssTSTP (also referred to as the request socket).♦

Time-Provider Interface 4–1

If the TP process is active, it immediately acknowledges the connect request and
writes the initial control response message to one of the following:
OpenVMS

UNIX

A second well known OpenVMS mailbox, which is
identified by the system logical name DTSS$_TPTS_MBX
(also referred to as the response mailbox).♦
A second UNIX domain socket, which is identified by
the name /usr/var/tmp/dssTPTS (also referred to as the
response socket).♦

When the DECdts server is enabled on the system, it creates this mailbox/socket.
If the DECdts server cannot write its request message to the request mailbox
/socket (because the TP process is not available) or does not immediately receive a
control message from the TP process, the DECdts server synchronizes with other
servers instead of with the external time-provider.
If the initial message exchange is successful, the DECdts server waits for a
second response message (data message) that contains the timestamp values read
from the external time source. The length of time the server process waits for the
data message is specified by the TP process in the initial control message. When
the TP process writes a data message to the response mailbox/socket, the DECdts
server uses the timestamp in the data message to complete its synchronization.
Figure 4–1 shows the message exchange between the DECdts server and the TP
process.

4–2 Time-Provider Interface

Figure 4–1 DECdts Server/TP Process Message Exchange

VMS

DTSS$_TSTP_MBX

request mailbox

1
DECdts server

ULTRIX

dssTSTP

request socket

4
3

VMS

DTSS$_TPTS_MBX

response mailbox

TP process

dssTPTS

ULTRIX

response socket

time source
ZK−4987A−GE

The following steps describe the process illustrated in Figure 4–1:
1

The DECdts server sends a request message to the request mailbox/socket
(DTSS$_TSTP_MBX or dssTSTP).

The TP process receives the message from the request mailbox/socket.

The TP process sends the initial response message (control message) to the
response mailbox/socket (DTSS$_TPTS_MBX or dssTPTS).

The DECdts server receives the control message, extracts three data fields
(next poll time, TP response timeout, noclockset) and waits for the arrival of
the data message.

The TP process polls its external time source (the time-provider hardware).

The TP process stores the UTC time values it obtains from the external
time source in a data message and then sends the message to the response
mailbox/socket.

The DECdts server reads the data message from the response mailbox/socket
and extracts the timestamps to complete a synchronization.

Section 4.2 describes the message types that are exchanged by the DECdts server
and the TP process during the previous sequence.

Time-Provider Interface 4–3

4.2 Message Types
The DECdts TPI uses request and response messages/sockets to exchange
information between the DECdts server and the TP process. The following
sections describe the message functions, the functions of the settable fields in
each message, and the range of settings for each field. The definitions for the
TP process message types can be found in dtssprovider.h. See Section 4.7 for
additional information about these definitions.

4.2.1 The Time Request Message
Time request messages are issued by the DECdts server to initiate a
synchronization with the TP process. Each message contains the current
synchronization serial number and a TPI version number field.
The TPI version number field defines the major and minor version numbers of the
TPI:
•

The TPI major version subfield must be set to K_TPI_MAJOR_VERS.

•

The minor version subfield must be set to K_TPI_MINOR_VERS.

The TP process ignores any message with a version number field that does not
contain the correct TPI version number.

4.2.2 Time Response Messages
The TPI uses two types of time response messages: control messages and
data messages. The TP process sends both types of messages to the response
mailbox/socket when replying to a request message from the DECdts server. The
following data fields are common to both time response messages:
•

Synchronization ID
Contains the current DECdts synchronization serial number. The current
synchronization ID is obtained from the synchID field of the request message
from the DECdts server.

•

Time-Provider Status
Contains either the value K_TPI_SUCCESS(1) or K_TPI_FAILURE(0). If the TP
process attempts to terminate a synchronization, it writes a response message
to the response mailbox/socket with a status of K_TPI_FAILURE; otherwise, the
status field contains K_TPI_SUCCESS.

•

Message Type
Distinguishes the two types of response messages. The message type field
contains one of two values; K_TPI_TIME_MESSAGE specifies a data message,
and K_TPI_CTL_MESSAGE specifies a control message.

•

TPI Versions
Contains the major and minor version numbers of the TPI. The major version
subfield must be set to K_TPI_MAJOR_VERS; the minor version subfield must
be set to K_TPI_MINOR_VERS. Any message received by the DECdts server is
ignored.

The control and data response messages also have unique fields. Section 4.2.2.1
describes control messages; Section 4.2.2.2 describes data messages.

4–4 Time-Provider Interface

4.2.2.1 The Control Message
The TP process initially writes a control message to the response mailbox/socket
in reply to a request message from the DECdts server. Control messages contain
the following fields:
•

Next Poll Value
Contains an integer in the range K_MIN_NEXTPOLL to K_MAX_NEXTPOLL. If
the current synchronization is successful, DECdts issues the next request
message in nextPoll seconds.

•

Timeout Value
Contains an integer in the range K_MIN_TIMEOUT to K_MAX_TIMEOUT. DECdts
waits a maximum of timeout seconds for the arrival of a data message before
asserting that the TP process is no longer available.

•

No Set Value
Specifies whether or not the service is allowed to alter the system clock. If
noSet is set to the value 0x01 (true), the DECdts server does not adjust or set
the clock during the current synchronization. DECdts does, however, assert
the inaccuracy returned in the data message.

4.2.2.2 The Data Message
The TP process writes a data message to the response mailbox/socket within
timeout seconds after it writes a control message. The data message contains two
fields:
•

The timestamp array

•

The timestamp count

The timestamp array contains one or more timestamps. Each timestamp consists
of three utc time values:
•

The system clock time immediately before the TP process polls the external
time source. (The TP process normally obtains the time from the utc_gettime
DECdts API routine.)

•

The time value returned to the TP process by the external time source.

•

The system clock time immediately after the external time source was read.
(The TP process again obtains the time from the utc_gettime DECdts API
routine.)

The other unique data message field contains the timestamp count.
The timestamp count is an integer in the range K_MIN_TIMESTAMPS to
K_MAX_TIMESTAMPS. The integer equals the number of timestamps contained
in the data message.

4.3 Interprocess Communication
Interprocess communication between the DECdts server and the TP process is
accomplished by using two OpenVMS mailboxes or two UNIX domain sockets.

Time-Provider Interface 4–5

4.3.1 Interprocess Communications on OpenVMS Systems
OpenVMS

The TP process creates the request mailbox (DTSS$_TSTP_MBX) and the DECdts
server creates the response mailbox (DTSS$_TPTS_MBX). The time-provider uses
the SYS$CREMBX system service to create its mailbox. The arguments to the
SYS$CREMBX system service follow:
SYS$CREMBX(
prmflg = 1,
maxmsg = sizeof( TPreqMsg ),
bufquo = 2 * sizeof( TPreqMsg ),
promsk = 0xFF00,

acmode = PSL$C_USER
lognam = "DTSS$_TSTP_MBX"
)

/* permanent mail box
*/
/* size of each message
*/
/* allow a maximum of 2
*/
/* messages at any time
*/
/* no access to world
*/
/* w:xxx=111=0xF
*/
/* g:xxx=111=0xF
*/
/* o:lprw=0000=0x0
*/
/* s:lprw=0000=0x0
*/
/* nonprivileged access mode */
/* well-known logical name */

The DECdts server attempts to assign a channel to this mailbox by using the
mailbox’s well-known logical name. The TP process only reads and never writes
to this mailbox. The DECdts server only writes to this mailbox. The TP process
uses the sys$assign system service command to attach to the mailbox created by
the DECdts server.
The arguments to the sys$assign service follow:
SYS$ASSIGN(
devnam = "DTSS$_TPTS_MBX",
channel = (specified by user),
acmode = PSL$C_USER,
mbxnam = 0,
)
The TP process writes data to the response mailbox; it must never attempt to
read data from response mailbox.♦

4.3.2 Interprocess Communications on Digital UNIX Systems
UNIX

A communication domain is identified by a manifest constant defined in the
file <sys/socket.h>. UNIX domain sockets (AF_UNIX) are used for communication
within the system. The TP process creates the request socket (dssTSTP); the
DECdts server creates the response socket (dssTPTS). Both sockets are of the
socket type SOCK_STREAM (stream sockets), which are full-duplex, reliable byte
streams that have no record boundaries. Stream sockets are available if your
system includes TCP/IP.
You can create Digital UNIX sockets with the socket call. This call yields an
unconnected socket descriptor, which must be made ready to accept connections
by binding it to a name within the communications domain. The bind call
accomplishes this process. Once the socket is bound to a name in the domain, the
socket must listen for connections through the listen call. When a connection is
requested from the DECdts server, the TP process must be ready to accept the
connection. The arguments to these calls follow:

4–6 Time-Provider Interface

socket_id = socket (AF_UNIX,
SOCK_STREAM,
0
);

/* UNIX domain path names
/* socket type
/* protocol - set to zero

*/
*/
*/

bind (socket_id,
sock_name,

/* Descriptor that refers to the created socket */
/* Name that is assigned to the created socket; */
/* in the case of the TP: /usr/var/tmp/dssTSTP */
sizeof(sock_name)
);

listen (socket_id,
back_log
);

/* Descriptor that refers to the created socket */
/* Maximum number of pending connections in
*/
/* the queue
*/

accept (socket_id, /* Descriptor that refers to the created socket */
address,
/* Address of the connecting entity
*/
address_len /* Address length
*/
);
The DECdts server makes a connection to the request socket (socket created by
the TP process) by issuing a connect call. The DECdts server only writes to this
socket; the TP process should only read (never write to) the socket. Conversely,
the TP process communicates with the DECdts server by connecting to and then
sending messages to the response socket. The TP process only writes to (never
reads from) this socket. The arguments to the connect call follow:
connect (socket_id, /* Descriptor that refers to the created socket */
sock_name, /* Name of the socket to establish connection; */
/* in the case of the TP: /usr/var/tmp/dssTPTS */
sizeof(sock_name)
);
♦

4.4 Time-Provider Algorithm
The algorithm to create a generic time-provider follows:
1. Create the request mailbox/socket (DTSS$_TSTP_MBX or dssTSTP).
2. Perform the step that corresponds to your operating system:
OpenVMS

UNIX

Post a synchronous read to the request mailbox. The TP
process remains in LEF state until the DECdts server
writes a request to the mailbox.♦
Issue a connect system call to connect to the request
socket. If the connection is unsuccessful, then exit the
program with an error.♦

3. Perform the step that corresponds to your operating system:
OpenVMS

UNIX

The DECdts server writes a request message to the
request mailbox. The outstanding synchronous read
completes. If the TPI version number is correct, accept
the message; otherwise return to step 2, ignoring the
received message.♦
Issue a select system call to the TSTP socket. When
the selection is completed, issue an accept system call
to respond to the connection request from the DECdts
server. ♦
Time-Provider Interface 4–7

4. Perform the step that corresponds to your operating system:
OpenVMS

UNIX

Assign a channel to the response mailbox using its well
known logical name DTSS$_TPTS_MBX.♦
Post a (synchronous) blocking read to the TSTP socket
and wait for the request message from the DECdts
server.♦

5. Initialize a control message by setting:
•

The TPI version number field to the appropriate value
(K_TPI_MAJOR_VERS, K_TPI_MINOR_VERS).

•

The time-provider status to K_TPI_SUCCESS.

•

The synchronization ID equal to synchId (from the request message).

•

The variables nextPoll, timeout, and noSet to valid integer values.

6. Perform the step that corresponds to your operating system:
OpenVMS

UNIX

Write the control message to the response mailbox using
an asynchronous write.♦
Write the TP process control message to the response
socket. ♦

7. Read the system time using the utc_gettime DECdts API routine.
8. Poll the external time source, reading a UTC value. Convert the time value
to a binary timestamp using the API.
9. Read the system time using the utc_gettime DECdts API routine.
10. Repeat steps 7, 8, and 9 between K_MIN_TIMESTAMPS times to
K_MAX_TIMESTAMPS times.
11. Initialize a data message using the timestamps and the correct TPI version
numbers.
12. If steps 7, 8, or 9 return erroneous data, initialize the TP status field
(TPstatus) of the data message to K_TPI_FAILURE; otherwise, initialize the
data message timestamps.
13. Perform the step that corresponds to your operating system:
OpenVMS

UNIX

Write the data message to the DTSS$_TPTS_MBX
mailbox.♦
Write the data message to the response socket and
issue a close system call to close all interprocess
communication connections to the TSTP and TPTS
sockets. Do not delete the TSTP socket. ♦

14. Go to step 2 (loop forever).

4–8 Time-Provider Interface

4.5 Time Server (DECdts Server Process) Algorithm
The time server algorithm follows:
1. At startup time, create the response mailbox/socket.
2. At synchronization time, attempt to connect to the response mailbox/socket,
assumed to have been created by the TP process. If the connection attempt
fails, synchronize with peer servers. Otherwise continue.
3. Initialize a request message with the current synchronization serial ID and
correct time-provider interface (TPI) version number, then send the message
to the request mailbox/socket.
4. Wait for a control message response from the TP process. If no message
arrives within the elapsed time specified by the LAN_QUERY_TIMEOUT DECdts
management parameter, synchronize with peer servers and ignore any
subsequent TP process messages. Otherwise, go to step 5.
5. Read the arriving control message and verify the following:
•

The message type (it should not be a data message).

•

The state of the TP process is K_TPI_SUCCESS.

•

The current synchronization ID matches synchID.

•

The TPI version numbers are correct.

If any values are incorrect, ignore this message and go to step 4.
6. Wait for a data message response from the TP process. If no message arrives
within the elapsed time specified by the control message (timeout), then
synchronize with peer servers. Schedule the next synchronization based on
the applicable DECdts management parameters, ignoring nextPoll.
7. When the next message arrives, read the message type to verify that it is a
data message. Also verify that the state of the TP process is K_TPI_SUCCESS
and that the TPI version numbers are correct; otherwise, synchronize with
peer servers and schedule the next synchronization as in step 6.
8. Extract the timestamps from the data message and synchronize using the
timestamps.
9. Close all interprocess communication (IPC) connections with the DECdts
server. Do not delete the DTSS$_TPTS_MBX mailbox or the TPTS socket.
10. Schedule the next synchronization time by adding the value of nextPoll
seconds to the current time. At the next synchronization, go to step 2.

4.6 Running the Time-Provider Process
OpenVMS

UNIX

The TP process and the DECdts server must both
be in the same UIC group. Only processes in the
DECdts server’s process group can write to the response
mailbox.♦
Both the DECdts server and the TP process must run on
the same node and have root privileges. The response
and request sockets are created such that only root can
write to them. ♦

Time-Provider Interface 4–9

Restricting writes prevents unauthorized users from supplying incorrect times to
the DECdts server process and from sending requests to the time-provider. The
TP process can always exit without affecting the DECdts server. The DECdts
server dynamically reestablishes communications with the TP process.

4.7 Time-Provider Interface, User-Accessible Definitions
The following constant definitions written in the ANSI C programming language
define the time ranges (in seconds) for time-provider (TP) control parameters.
The constant definitions are in the following file:

OpenVMS

sys$common:[syshlp.examples.dtss]dtss$provider.h
♦
The constant definitions are in the file /usr/include

UNIX

/dtssprovider.h. ♦

/*
* Valid range for NextPoll. If a time-provider exists, it must be
* polled within a 31-day interval.
*/
#define K_MAX_TP_POLL (31*24*60*60)

/* Maximum 31 days to the next
/* next time-provider poll.

*/
*/

#define K_MIN_TP_POLL (1)

/* Minimum 1 second between
/* time-provider polls.

*/
*/

/*
* Valid range for TimeOut...
*
The DECdts server process waits a maximum of 5 minutes for a data
*
message from the TP process to arrive.
*/
#define K_MAX_TP_TMO

(5*60)

/* Maximum 5 minutes to wait for */
/* the TP process to respond.
*/

#define K_MIN_TP_TMO

(1)

/* Minimum 1 second to wait for */
/* the TP process to respond.
*/

The following constant definition limits the number of timestamp triplets the TP
process can transmit:
/*
*
*
*/

Maximum number of time stamp triplets returned by the
TP process...

#define K_MIN_TIMESTAMPS
#define K_MAX_TIMESTAMPS
/*
*
*/

1
6

TPI version numbers...

#define K_TPI_MAJOR_VERS
#define K_TPI_MINOR_VERS

1
0

The time-provider process message types are defined by the following definitions
written in the ANSI C language.

4–10 Time-Provider Interface

/*
*
*
*/

The status of the TP process is either K_TPI_SUCCESS or
K_TPI_FAILURE...

#define
#define
/*
*
*
*
*/

0
1

Two types of messages...
- Control messages (TPctlMessage)
- Time or Data messages (TPtimeMessage)

#define
#define
/*
*
*/

K_TPI_FAILURE
K_TPI_SUCCESS

K_TPI_TIME_MESSAGE
K_TPI_CTL_MESSAGE

DECdts version identifier...

typedef struct VersionType
{
unsigned short dtss_major;
unsigned short dtss_minor;
} VersionType;
/*
*
*
*
*
*
*/

0
1

/* major version
/* minor version

*/
*/

A single time stamp...
Contains a reading of the local clock just before the external
time source is queried, the UTC value returned by the external
time source, and a reading of the local clock just after the
external time source is queried.

typedef struct TimeResponseType
{
struct utc beforeTime; /* local clk just before getting UTC
utc TPtime;
/* external source UTC
utc afterTime;
/* local clk just after getting UTC
} TimeResponseType;
/*
*
*
*
*/

*/
*/
*/

TP process control message type...
The initial message returned by the TP process in response to
a time service request.

typedef struct TPctlMsg
{
unsigned long nextPoll;
unsigned long timeout;
unsigned long noSet;
} TPctlMsg;
/*
*
*
*
*/

TP process data message type...
The time stamp values returned by the TP process after it sends
its initial response.

typedef struct TPtimeMsg
{
unsigned long timeStampCount;
TimeResponseType timeStampList[K_MAX_TIMESTAMPS];
} TPtimeMsg;

Time-Provider Interface 4–11

/*
*
TP process response message...
*
Contains either a control message or a data message. Issued by
*
the TP process, directing the DECdts server to transmit data or
*
control information.
*
* TPI Control Message (304 bytes) :
*
* 31
0
* +--------------------+--------------------+
* | TPI Minor Version | TPI Major Version |
* +-----------------------------------------+
* |
Message Type
|Time-Provider Status|
* +-----------------------------------------+
* |
Synchronization ID
|
TPI Control Message
* +-----------------------------------------+
* |
Next Poll Delta
|
* +-----------------------------------------+
* |
Message Time Out
|
* +-----------------------------------------+
* |
NoSet
|
* +-----------------------------------------+
* |
|
* v
Not Used
v
*
* TPI Data Message (304 bytes) :
* 31
0
* +--------------------+--------------------+
* |
TPI Minor Vers | TPI Major Vers
|
* +-----------------------------------------+
* |
Message Type
|Time-Provider Status|
* +-----------------------------------------+
* |
Synchronization ID
| TPI Time Message
* +-----------------------------------------+
* |
Time Stamp Count
|
* +-----------------------------------------+
* |
|
* |
| Time Stamp One,
* |
|
48 bytes
* |
|
.
* +-----------------------------------------+
.
* |
|
.
* v
v
.
*
* |
| Time Stamp Six,
* +-----------------------------------------+
48 bytes
*
*
Total = 48 * 6 = 288 bytes
*
in timestamp/data portion
*
* A single Time Stamp (48 bytes):
*
* 128
0
* +-----------------------------------------+
* |
Before Time
|
* +-----------------------------------------+
* |
TP time
|
* +-----------------------------------------+
* |
After Time
|
* +-----------------------------------------+
*/

4–12 Time-Provider Interface

typedef struct TPrspMsg
{
VersionType
TPIversion;
unsigned short status;
unsigned short TPmsgType;
unsigned long TPsyncID;
union
{
TPctlMsg
TPctlMsg;
TPtimeMsg
TimeMsg;
} TPdata;
} TPrspMsg;

/* Time-provider major & minor versions */
/* Status of the TP process
*/
/* Message Type: control or data
*/
/* Synchronization Serial Number
*/
/* Control message data
/* Data message data

*/
*/

/*
* Request message sent from the DECdts server process to the
* TP process.
*/
typedef struct TPreqMsg
{
VersionType TPIversion;
unsigned long TPsyncID;
} TPreqMsg;

/* TPI major, minor version number
*/
/* service synchronization Serial Number */

/*
* TPI Request Message : 8 bytes.
*
* 31
0
* +--------------------+--------------------+
* |
TPI Minor Vers | TPI Major Vers
|
* +-----------------------------------------+
* |
Synchronization ID
|
* +-----------------------------------------+
*/

TPI Time Message

4.8 Sample Time-Provider Programs and External Time-Provider
Sources
OpenVMS

UNIX

See sys$common:[syshlp.examples.dtss] for examples
of time-provider programs you can use with various
types of external time-provider devices.♦
See /usr/examples/dtss for examples of time-provider
programs you can use with various types of external
time-provider devices.♦

The DECdts Management manual provides additional information about
commercial sources of external time-provider devices.
Table 4–1 lists the time-provider programs and related time-provider hardware
/software suppliers that are currently available for DECnet-Plus for OpenVMS
and for DECnet-Plus for Digital UNIX systems.

Time-Provider Interface 4–13

Table 4–1 Time-Provider Programs and Related Time-Provider Suppliers
OpenVMS

DECnet-Plus for OpenVMS Systems
File Name

Related Supplier

Time-Provider Type

dtss$provider_acts.c

U.S. NIST
(North America)

Time-provider
program for data
communications

dtss$provider_acts.com

U.S. NIST
(North America)

Command procedure
for the ACTS timeprovider program

dtss$provider.c

Traconex, Spectracom,
Heath, and Hopf
(North America and Europe)

Time-provider
program for RF
receivers ♦

DECnet-Plus for Digital UNIX Systems
UNIX

File Name

Related Supplier

Time-Provider Type

dtss_acts_provider.c

U.S.NIST
(North America)

Time-provider
program for
data
communications

dtss_spectracom_provider.c

Spectracom
(North America and Europe)

Time-provider
program for
RF receiver

dtss_traconex_provider.c

Traconex
(North America)

Time-provider
program for
RF receiver

dtss_hopf_provider.c

Hopf
(Europe)

Time-provider
program for
RF receiver

dtss_ntp_provider.c

Various

Time-provider
program for
Internet Network
Time Protocol

dtss_null_provider.c

Digital

Local server clock ♦

4–14 Time-Provider Interface

Glossary
The following terms are important for managing DECdts software.
absolute time
A point on a time scale. For the Digital Distributed Time Service (DECdts),
absolute times reference the Coordinated Universal Time (UTC) standard.
adjustment
The DECdts process of changing the system clock time by modifying the
incremental value that is added to the clock’s software register for a specified
duration.
advertisement
The process by which a server makes its address and attributes known to other
servers and clerks in a local area network.
binary timestamps
Opaque 128-bit (16-octet) binary sequence that represents time values.
clerk
A DECdts process that synchronizes the clock for its client system by requesting
time values from servers, computing a new time from the values, and supplying
the computed time to client applications, such as the operating system.
clock
The combined hardware interrupt timer and software register that maintain the
system time. The hardware timer sends interrupts to the operating system; at
each interrupt, the operating system adds an increment to a software register
which contains the time value.
computed time
The result of the synchronization process: the time value that the clerk or server
process computes according to the values it receives from several servers.
Coordinated Universal Time (UTC)
An international time standard maintained by the International Time Bureau.
courier
A local server that requests a time value from a randomly selected global server
each time it synchronizes.
computed time
The intersection of several time intervals, used to adjust the system clock time.

Glossary–1

DECdts entity
The DECdts server or clerk software on a system.
drift
A clock’s constantly increasing error rate.
entity
A specific software implementation on a system.
entity type
The subgrouping of an entity that determines its relationship to other DECdts
components: clerk or server.
epoch number
An identifier that a server appends to the time values it sends to other servers.
Servers only use time values from other servers with whom they share epoch
numbers.
error
The difference between a system’s clock value and the computed time.
error tolerance
The amount of system clock error to which the DECdts entity responds by
abruptly setting the system clock to the computed time, rather than gradually
adjusting the clock.
global server
A DECdts server that frequently provides its clock value to courier servers on
other LANs, or infrequently provides its clock value to systems that have failed
to obtain the specified number of servers locally.
global set
All of the global servers in a network.
global server directory
The name service directory where DECdts global servers are stored.
inaccuracy
The bounded uncertainty of a clock value as compared to the UTC standard.
interval
The combination of a clock’s value and the inaccuracy associated with it. The
range of values contained in the clock value minus its inaccuracy and the clock
value plus its inaccuracy.
leap seconds
Infrequent adjustment to UTC to account for the irregularity of the earth’s
rotation.
local set
All of the servers in a particular local area network (LAN).

Glossary–2

local server
A server that synchronizes with its peers and provides its clock value to other
servers and clerks on the same LAN.
relative time
A discrete time interval that is usually added to or subtracted from an absolute
time.
server
A DECdts entity that synchronizes with its peers and provides its clock value to
clerks and their client applications.
skew
The time difference between two clocks or clock values.
synchronization
The process by which a DECdts entity requests clock values from other systems,
computes a new time from the values, and adjusts its system clock to the new
time.
synchronization list
The list of servers that a DECdts entity has discovered; the entity sends requests
for clock values to the servers on the list.
system time
The time value the operating system maintains according to its reading of the
system’s hardware clock.
tick
The clock timer interrupt that causes the operating system to increment the
system time.
time differential factor (TDF)
The difference between UTC and the time in a particular time zone.
time-provider
A hardware device that monitors UTC time and forwards it to a time-provider
process.
TP process
A user-written program connected to a time-provider that supplies UTC times to
a DECdts server.
TP server
A DECdts server system connected to a time-provider.
TDF
See time differential factor.
UTC
See Coordinated Universal Time.

Glossary–3

Index
A

Absolute time
defined, 1–2
example of, 1–2
ISO representation of, 1–2
variations on ISO representation of, 1–2
Absolute Time routine, 2–6
accept system call, 4–6
accept system call arguments, 4–6
Add Time routine, 2–8
Any Time routine, 2–10
Any Zone routine, 2–13
Applications
linking DECdts shared image with, 1–7
linking object library with
on Digital UNIX systems, 1–8
linking shared image with
on OpenVMS systems, 1–8
ASCII Any Time routine, 2–15
ASCII GMT Time routine, 2–17
ASCII Local Time routine, 2–19
ASCII Relative Time routine, 2–21
ASCII text strings
binary timestamps translated to, 1–1

DECdts absolute time structures
listing, 1–5
DECdts API header files, 1–7
<time.h>, 1–7
<utc.h>, 1–7
DECdts API routines
description, 1–1
sample C program, 3–1
DECdts relative time structures
listing, 1–5
DECdts routines
basic functions, 1–1
DECdts server/TP process message exchange
illustration, 4–3
step-by-step description, 4–3
dssTPTS (response socket), 4–1
dssTSTP (request socket), 4–1
DTSS$_TPTS_MBX (response mailbox), 4–1
DTSS$_TSTP_MBX (request mailbox), 4–1

B
BIH, 1–1
Binary Relative Time routine, 2–22
Binary Time routine, 2–24
Binary timestamp, 1–6
bind system call, 4–6
bind system call arguments, 4–6
Bound Time routine, 2–26

C
Communication domain, 4–6
Compare Interval Time routine, 2–28
Compare Midpoint Times routine, 2–31
connect system call, 4–7
connect system call arguments, 4–7
Coordinated Universal Time, 1–1, 4–1

G
Get Time routine, 2–34
Get User Time routine, 2–35
Greenwich Mean Time (GMT), 1–1
Greenwich Mean Time routine, 2–37
Greenwich Mean Time Zone routine, 2–39

I
Inaccuracy, 1–2
International Standards Organization
8601 standard, 1–2
International Time Bureau, 1–1
Interprocess communication, 4–5
ISO format, 1–2
commas as separators in, 1–2
example, 1–2
example of, 1–2
example showing variations, 1–2
specifying inaccuracy, 1–2
TDF in, 1–2
use of I delineator, 1–2
use of plus (+) or minus (-) characters, 1–2
use of the T delineator, 1–2

Index–1

ISO format (cont’d)
variations to, 1–2

K
K_MAX_TIMESTAMPS, 4–5
K_MAX_TIMESTAMPS setting, 4–7
K_MIN_TIMESTAMPS, 4–5
K_MIN_TIMESTAMPS setting, 4–7
K_TPI_FAILURE time-provider status, 4–7, 4–9
K_TPI_MAJOR_VERS TPI version number field
setting, 4–7, 4–9
K_TPI_MINOR_VERS TPI version number field
setting, 4–7, 4–9
K_TPI_SUCCESS time-provider status, 4–7, 4–9

Object Library
DECdts, 1–7
OpenVMS Greenwich Mean Time routine, 2–79
OpenVMS Local Time routine, 2–81
OpenVMS time structure, 1–7

P
Point Time routine, 2–70
Programs
linking DECdts shared image with, 1–7
linking object library with
on Digital UNIX systems, 1–8
linking shared image with
on OpenVMS systems, 1–8

LAN_QUERY_TIMEOUT DECdts management
parameter setting, 4–9
LEF state, 4–7
Library
DECdts, 1–7
on OpenVMS systems, 1–8
listen system call, 4–6
listen system call arguments, 4–6
Local Time routine, 2–42
Local Zone routine, 2–44

Relative time
calendar date field, 1–4
defined, 1–3
example of, 1–3
negative, 1–4
positive, 1–4
Relative Time routine, 2–72
reltimespec structure declaration, 1–7
reltimespec time structure, 1–7
Request mailbox, 4–1, 4–5
DTSS$_TSTP_MBX, 4–5, 4–7, 4–9
Request socket, 4–1, 4–6
dssTSTP, 4–6, 4–7
Response mailbox, 4–1, 4–5
DTSS$_TPTS_MBX, 4–5, 4–7, 4–9
Response socket, 4–1, 4–6
dssTPTS, 4–6, 4–7
root privileges, 4–9

M
Make Any Time routine, 2–46
Make ASCII Relative Time routine, 2–49
Make ASCII Time routine, 2–51
Make Binary Relative Time routine, 2–53
Make Binary Time routine, 2–54
Make Greenwich Mean Time routine, 2–56
Make Local Time routine, 2–58
Make Relative Time routine, 2–60
Make VMS Any Time routine, 2–62
Make VMS Greenwich Mean Time routine, 2–64
Make VMS Local Time routine, 2–65
Multiply a Relative Time by a Real Factor routine,
2–67
Multiply Relative Time by an Integer Factor
routine, 2–69

N
nextPoll variable setting, 4–7, 4–9
noSet variable setting, 4–7

O
Object library
on Digital UNIX systems, 1–8

Index–2

S
Sample C program, 3–1
compiling and linking
ULTRIX systems, 3–3
VMS systems, 3–3
using routines
utc_ascgmtime, 3–1
utc_asclocaltime, 3–1
utc_cmpintervaltime, 3–1
utc_cmpmidtime, 3–1
utc_mkanytime, 3–1
utc_mkasctime, 3–1
Server and TP processes
privileges required to run the, 4–9
Shared image
DECdts, 1–7
on OpenVMS systems, 1–8
socket system call, 4–6

socket system call arguments, 4–6
Socket type
SOCK_STREAM, 4–6
Span Time routine, 2–74
Stream sockets, 4–6
Subtract Time routine, 2–76
synchId synchronization ID setting, 4–7, 4–9
synchId variable setting, 4–7
sys$assign system service command, 4–6
sys$assign system service command arguments,
4–6
SYS$CREMBX system service, 4–6
SYS$CREMBX system service arguments, 4–6

T
TDF, 1–2
Time Differential Factor, 1–2
Time representation
by DECdts, 1–1
Time request message, 4–4
location, 4–4
Time response data message data fields (unique)
timestamp array, 4–5
timestamp count, 4–5
Time response data messages
description, 4–5
Time response message
control, 4–4
data, 4–4
data field (common), 4–4
message type, 4–4
synchronization ID, 4–4
time-provider status, 4–4
TPI versions, 4–4
data field (unique)
next poll value, 4–5
no set value, 4–5
timeout value, 4–5
description, 4–5
location, 4–4
Time server
algorithm for creating, 4–9
Time structures, 1–5
OpenVMS, 1–7
reltimespec, 1–7
timespec, 1–7
tm, 1–6
utc, 1–6
Time-provider
algorithm, 4–7
generic
algorithm for creating, 4–7
procedure for creating, 4–7
Time-Provider Interface
See TPI.

<time.h> header file, 1–6, 1–7
timeout variable setting, 4–7, 4–9
timespec structure declaration, 1–7
timespec time structure, 1–7
tm structure declaration, 1–6
tm time structure, 1–6
TPI, 4–1
control flow, 4–1
description, 4–1
description, 4–1
user accessible definitions
location, 4–10
time range, 4–10
timestamp limit, 4–10
TP process message types, 4–10

U
UNIX domain socket
AF_UNIX, 4–6
UTC, 1–1, 4–1
utc time structure, 1–6
<utc.h> header file, 1–7
utc_abstime, 2–6
utc_addtime, 2–8
utc_anytime, 2–10
utc_anyzone, 2–13
utc_ascanytime, 2–15
utc_ascgmtime, 2–17
utc_asclocaltime, 2–19
utc_ascreltime, 2–21
utc_binreltime, 2–22
utc_bintime, 2–24
utc_boundtime, 2–26
utc_cmpintervaltime, 2–28
utc_cmpmidtime, 2–31
utc_gettime, 2–34
utc_gettime routine
use in creating a generic time-provider, 4–7
utc_getusertime, 2–35
utc_gmtime, 2–37
utc_gmtzone, 2–39
utc_localtime, 2–42
utc_localzone, 2–44
utc_mkanytime, 2–46
utc_mkascreltime, 2–49
utc_mkasctime, 2–51
utc_mkbinreltime, 2–53
utc_mkbintime, 2–54
utc_mkgmtime, 2–56
utc_mklocaltime, 2–58
utc_mkreltime, 2–60
utc_mkvmsanytime, 2–62
utc_mkvmsgmtime, 2–64
utc_mkvmslocaltime, 2–65
utc_mulftime, 2–67

Index–3

utc_multime, 2–69
utc_pointtime, 2–70
utc_reltime, 2–72
utc_spantime, 2–74
utc_subtime, 2–76
utc_vmsanytime, 2–78
utc_vmsgmtime, 2–79
utc_vmslocaltime, 2–81

V
VMS Any Time routine, 2–78

Index–4