| Previous | Contents | Index |
This is a user-written routine that is used in place of the TPU$FILE_SEARCH routine.
FILE_SEARCH result-string ,flags ,filespec ,default-spec ,related-spec
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.
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.
| OpenVMS usage: | char_string |
| type: | character string |
| access: | read only |
| mechanism: | by descriptor |
| OpenVMS usage: | char_string |
| type: | character string |
| access: | read only |
| mechanism: | by descriptor |
The value 0 is passed if there is no default-spec.
| OpenVMS usage: | char_string |
| type: | character string |
| access: | read only |
| mechanism: | by descriptor |
The value 0 is passed if there is no related-spec.
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.
HANDLER signal_vector ,mechanism_vector
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value.
signal_vector
OpenVMS usage: arg_list type: longword (unsigned) access: modify mechanism: by reference
Signal vector. See the HP 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 HP OpenVMS System Services Reference Manual for information about the mechanism vector passed to a condition handler.
If you need more information about writing condition handlers and programming concepts, refer to HP OpenVMS Programming Concepts Manual.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.
INITIALIZE [user_arg]
OpenVMS usage: item_list type: longword (unsigned) access: read only mechanism: by reference
This routine returns the address of an item list.
user_arg
OpenVMS usage: user_arg type: longword (unsigned) access: read only mechanism: by value
User argument.
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).
USER integer ,stringin ,stringout
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value.
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.
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:
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 |
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 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.
| Structure | Time Units | Base Date | Approximate Range |
|---|---|---|---|
| utc | 100-nanosecond | 15 October 1582 | A.D. 1 to A.D. 30,000 |
| tm | second | 1 January 1900 | A.D. 1 to A.D. 30,000 |
| timespec | nanosecond | 1 January 1970 | A.D. 1970 to A.D. 2106 |
Table 9-2 lists the relative time structures that the DECdts API uses to modify binary times for applications.
| Structure | Time Units | Approximate Range |
|---|---|---|
| utc | 100-nanosecond | ± 30,000 years |
| tm | second | ± 30,000 years |
| reltimespec | nanosecond | ± 68 years |
The remainder of this section explains the DECdts time structures in detail.
| Previous | Next | Contents | Index |