HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

This is a user-written routine that is used in place of the TPU$FILE_SEARCH routine.

Format

FILE_SEARCH result-string ,flags ,filespec ,default-spec ,related-spec

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. If an odd numeric value is returned, the next call to the built-in procedure FILE_SEARCH automatically sets the TPU$M_REPARSE bit in the flags longword. TPU$M_REPARSE is also set if the result-string has a length of 0.

Arguments

result-string

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

Return value for the built-in procedure FILE_SEARCH. Your program should fill in this descriptor with a dynamic string allocated by the string routines such as the Run-Time Library routine LIB$SGET1_DD. DECTPU frees this string when necessary.

The TPU$M_REPARSE bit is set in the flags longword if the result-string has a length of zero. The bit is intended to reset the file search when wildcard searches are performed.

flags

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The following table shows the flags used for specifying the file components:

Flag1	Function
TPU$M_NODE	Requests for the node component of the file specification.
TPU$M_DEV	Requests for the device component of the file specification.
TPU$M_DIR	Requests for the directory component of the file specification.
TPU$M_NAME	Requests for the name component of the file specification.
TPU$M_TYPE	Requests for the type component of the file specification.
TPU$M_VER	Requests for the version component of the file specification.
TPU$M_REPARSE	Reparses the file specification before processing. This is intended as a way to restart the file search. This flag will automatically be set by DECTPU if on a previous call to the FILE_SEARCH user routine the result-string has a zero length or the routine returns a odd (noneven) status.
TPU$M_HEAD	Requests for the NODE, DEVICE, and DIRECTORY components of the file specification.
TPU$M_TAIL	Requests for the NAME, TYPE, and VERSION component of the file specification.

filespec

default-spec

The value 0 is passed if there is no default-spec.

related-spec

The value 0 is passed if there is no related-spec.

Description

The FILE_SEARCH user routine allows an application to replace the TPU$FILE_SEARCH routine with its own file-searching routine. The calling program passes the address of the routine to the TPU$INITIALIZE routine using the TPU$_FILE_SEARCH item code.

When the DECTPU built-in procedure FILE_SEARCH is called from TPU code, DECTPU calls either the user-written FILE_SEARCH routine (if one was passed to TPU$INITIALIZE) or the TPU$FILE_SEARCH routine. The return value of the built-in procedure is the string returned in the result-string argument.

To ensure proper operation of the user's ON_ERROR handlers, errors in the user-written FILE_PARSE routine should be signaled using the TPU$SIGNAL routine.

The user-written HANDLER routine performs condition handling.

Format

HANDLER signal_vector ,mechanism_vector

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value.

Arguments

signal_vector

OpenVMS usage:	arg_list
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Signal vector. See the OpenVMS System Services Reference Manual for information about the signal vector passed to a condition handler.

mechanism_vector

OpenVMS usage:	arg_list
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Mechanism vector. See the OpenVMS System Services Reference Manual for information about the mechanism vector passed to a condition handler.

Description

If you need more information about writing condition handlers and programming concepts, refer to OpenVMS Programming Interfaces: Calling a System Routine.

Instead of writing your own condition handler, you can use the default condition handler, TPU$HANDLER. If you want to write your own routine, you must call TPU$HANDLER with the same parameters that your routine received to handle DECTPU internal signals.

The user-written initialization callback routine is passed to TPU$INITIALIZE as a bound procedure value and called to supply information needed to initialize DECTPU.

Format

INITIALIZE [user_arg]

RETURNS

OpenVMS usage:	item_list
type:	longword (unsigned)
access:	read only
mechanism:	by reference

This routine returns the address of an item list.

Arguments

user_arg

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

User argument.

Description

The user-written initialization callback routine is passed to TPU$INITIALIZE as a bound procedure value and called to supply information needed to initialize DECTPU.

If the user_arg parameter was specified in the call to TPU$INITIALIZE, the initialization callback routine is called with only that parameter. If user_arg was not specified in the call to TPU$INITIALIZE, the initialization callback routine is called with no parameters.

The user_arg parameter is provided to allow an application to pass information through TPU$INITIALIZE to the user-written initialization routine. DECTPU does not interpret this data in any way.

The user-written callback routine is expected to return the address of an item list containing initialization parameters. Because the item list is used outside the scope of the initialization callback routine, it should be allocated in static memory.

The item list entries are discussed in the section about TPU$INITIALIZE. . Most of the initialization parameters have a default value; strings default to the null string, and flags default to false. The only required initialization parameter is the address of a routine for file I/O. If an entry for the file I/O routine address is not present in the item list, TPU$INITIALIZE returns with a failure status.

The user-written USER routine allows your program to take control during a DECTPU editing session (for example, to leave the editor temporarily and perform a calculation).

Format

USER integer ,stringin ,stringout

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value.

Arguments

integer

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

First parameter to the built-in procedure CALL_USER. This is an input-only parameter and must not be modified.

stringin

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Second parameter to the built-in procedure CALL_USER. This is an input-only parameter and must not be modified.

stringout

OpenVMS usage:	char_string
type:	character string
access:	modify
mechanism:	by descriptor

Return value for the built-in procedure CALL_USER. Your program should fill in this descriptor with a dynamic string allocated by the string routines (such as LIB$SGET1_DD) provided by the Run-Time Library. The DECTPU editor frees this string when necessary.

Description

This user-written routine is invoked by the DECTPU built-in procedure CALL_USER. The built-in procedure CALL_USER passes three parameters to this routine. These parameters are then passed to the appropriate part of your application to be used as specified. (For example, they can be used as operands in a calculation within a Fortran program.) Using the string routines provided by the Run-Time Library, your application fills in the stringout parameter in the call-user routine, which returns the stringout value to the built-in procedure CALL_USER.

The description of the built-in procedure CALL_USER in the DEC Text Processing Utility Reference Manual shows an example of a BASIC program that is a call-user routine.

See Section 8.5 for a description of how to create an executeable image for the USER routine and how to call the routine from a C program in the DECTPU environment.

You can use the DIGITAL Distributed Time Service (DECdts) programming 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. You should be familiar with the basic DECdts concepts before you attempt to use the applications programming interface (API).

The DECdts API routines can perform 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

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.

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

9.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.

9.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 9-1 explains the ISO format that generated the previous display.

Figure 9-1 Time Display Format

In Figure 9-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 9-2 are also accepted as input for the ASCII conversion routines.

Figure 9-2 Time Display Format Variants

In Figure 9-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.

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

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.

Figure 9-3 shows the full syntax for a relative time.

Figure 9-3 Relative Time Syntax

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 ( - ) 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.

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

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 9-4.

Figure 9-4 Time Period Syntax

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
• 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

DECdts can convert between several types of binary time structures that are based on different base dates 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. The DECdts API routines are used to perform these conversions for applications on your system.

Table 9-1 lists the absolute time structures that the DECdts API uses to modify binary times for applications.

Table 9-2 lists the relative time structures that the DECdts API uses to modify binary times for applications.

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