Ingres CL TM
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - TM
Abstract
This is the specification of the TM facility provided by the compatibility library.
Revision: 2.1, 07-Dec-1998
Document History
- Revision 2.1, 07-Dec-1998
- Add HRSYSTIME and TMhrnow().
- Convert to HTML.
- Revision 2.0, 30-Jul-94
- Substantial changes to the way timezones are handled were approved, including a GL TMGL component for mapping zones to corrections. All CL implementations must change to use the new scheme. TMzone() and TMinit() are removed, and calls to these routines must provoke link errors (18-sep-92).
- TMperfstat added (2-jul-93).
- Revision 1.0, last modified 29-Aug-91
- Documented TIMER struct only implied before.
- Documented TIMERSTAT structure used by CSstatistics.
- Added warning note about TMzone and historical times.
- Fixed typos.
Specification
Introduction
TM routines perform various time related functions. TM supports three types of times: SYSTIMES, timestamps and seconds. A timestamp is a high resolution clock sample. Seconds are used to represent low resolution events and dates.
Intended Uses
The TM routines are intended for for use by anyone needing time and/or date information.
Assumptions
A timestamp must fit into a 8-byte quantity.
A timestamp is required to be monotonically increasing within a single process and unique across all processes running on that system. Note that these timestamps are also used by the LG system to provide unique values.
Concepts
The conversion routines are used to display the timestamps, and for comparing user given timestamps to internally stored timestamps.
The format of the output/input string is fixed as:
dd-mmm-yyyy hh:mm:ss.cc
(The space between the yyyy and hh may be ':' on input, so that it can be easy typed on an INGRES command line.)
Timezones
TM requires information about the relationship of arbitrary local times to Greenwich Mean Time (GMT). The structure of time periods and their corresponding timezone offsets is managed in the GL by the functions TMtz_init(), TMtz_load(), TMtz_lookup, TMtz_search().
We do not rely on any operating system, machine specific or CL timezone manipulation. This is often incorrect and unsupportable in our product. The timezone information used by the GL functions is maintained in files that may be modified without relinking executables, and is in wide use in other systems**.
- We are using a derivitive of code originally published by Arthur David Olsen, now also used in SunOS, SVR4 and BSD4.3 and greater. For references, see the code in the GL.
When Ingres needs to convert between GMT and local time, it ensures that a TM_TZ_CB is loaded for the timezone named in the II_TIMEZONE_NAME NM symbol. It then looks up the time in the structure to determine the correct offset to apply to affect the conversion. This method of calculating time values guarantees that the returned time values to be the same even when time values are entered and retrieved in different Daylight Saving Time (DST) setting, or when the times being converted were under different rules than currently in effect.
To support this scheme, a new utility program, iizic has been added to the GL. The interface to iizic is under the control of the LRC, and is published in user documentation.
Header File <tm.h>
The header file <tm.h> must be included before using any of the functions provided. It also defines the following.
HRSYSTIME - nanoseconds from the 1-Jan-70 epoch
The HRSYSTIME structure contains an absolute date in the form of a count of seconds and nanoseconds since Jan. 1, 1970, 00:00:00 GMT.
typedef struct
{
i4 tv_secs; /* since 1/1/70, 00:00:00 GMT */
i4 tv_nsecs; /* number of nanoseconds since last second */
} HRSYSTIME;
SYSTIME - milliseconds from the 1-Jan-70 epoch
The SYSTIME structure contains an absolute date in the form of a count of seconds since Jan. 1, 1970, 00:00:00 GMT. The TM_msecs portion may be irrelevant on systems which do not have real time clocks with millisecond granularity. Those systems should always fill this item with 0.
typedef struct
{
i4 TM_secs; /* since 1/1/70, 00:00:00 GMT */
i4 TM_msecs; /* 0 - 999 */
} SYSTIME;
TM_STAMP - formatted time stamp
This structure represents the internal storage used to store a formatted timestamp.
typedef struct _TM_STAMP
{
char stamp[8];
#define TM_SIZE_STAMP 24
/* TM_SIZE_STAMP is the
** number of BYTES needed
** to contain a formatted
** timestamp. See
** TMstamp_str
*/
} TM_STAMP;
TMhuman - human readable time structure
The TMhuman structure contains a human-readable time format, broken up as follows:
- the first three characters of the day of the week, Sun Mon Tue Wed Thu Fri Sat
- the first three characters of the month, Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
- the two digit day of the month, 01 through 31
- the four digit year
- the two digit hour of the day, 00 through 23
- the two digit minutes past the hour, 00 through 59
- the two digit seconds past the minute, 00 through 59
struct TMhuman
{ char wday[4];
char month[4];
char day [3];
char year[5];
char hour[3];
char mins[3];
char sec[3];
};
TIMERSTAT - structure for one instant's statistics
This structure is used by the CSstatistics call.
typedef struct
{
integer-type stat_cpu; /* cpu time in milliseconds */
integer-type stat_dio; /* count of disk i/o requests */
integer-type stat_bio; /* count of comm i/o requests */
. . .
/* other statistics might be here as well */
} TIMERSTAT;
TIMER - structure for statistics
This structure is used with te TMstart, TMend, anf TMformat calls. It's contents are not known to client code.
typedef struct
{
. . .
} TIMER;
Header File <tmgl.h>
The <tmgl.h> header is used to define the system-independant TM_PERFSTAT structure, used as an argument to the TMperfstat function.
TM_PERFSTAT - single structure defining all perfstats available
This structure contains entries for all known interesting performance statistics available from the OS about a process. Not all statistics will be available on all OS's. Those stats which are unavailable will be set to "-1". Use the TMperfstat() routine to retrieve these stats from the OS.
Although the current set of fields are patterned after those available on BSD systems, it is expected that more fields will be added to this structure. Future proposals will add structure members. Clients should only reference structure members by name and not assume a particular order of members. Any changes to the structure will require recompile and relink of client and CL routines.
typedef struct
{
SYSTIME tmperf_utime; /* user time used */
SYSTIME tmperf_stime; /* system time used */
i4 tmperf_maxrss; /* maximum resident set size */
i4 tmperf_idrss; /* current resident set size */
i4 tmperf_minflt; /* pg flts not requiring physical I/O */
i4 tmperf_majflt; /* pg flts requiring physical I/O */
i4 tmperf_nswap; /* process swaps */
i4 tmperf_reads; /* read I/O's from disk */
i4 tmperf_writes; /* write I/O's to disk */
i4 tmperf_msgsnd; /* messages sent */
i4 tmperf_msgrcv; /* messages received */
i4 tmperf_nsignals; /* # of signals received */
i4 tmperf_nvcsw; /* # of voluntary context switches */
i4 tmperf_nivcsw; /* # of involuntary context switches */
} TM_PERFSTAT;
Executable Interface
The following functions are provided.
TMbreak - break SYSTIME into a TMhuman structure
Break an absolute date in the form of a SYSTIME into component pieces and place the results into a TMhuman structure. This routine fills in the following fields of the output TMhuman structure: day-of-the-week, month, day, year, hours, minutes, and seconds.
Inputs:
| tm | pointer to SYSTIME |
Outputs:
| human | pointer to TMhuman to fill in. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TMbreak( SYSTIME *tm, struct TMhuman *human );
TMcmp - compare SYSTIMEs
Compare time1 with time2. Returns positive if time1 greater than time2; zero if time1 equals time2; and negative if time1 less than time2.
Inputs:
| time1 | first time |
| time2 | second time to compare |
Outputs:
| None |
Returns:
| "< 0" | if time1 < time2 |
| "0" | if time1 == time2 |
| "> 0 " | if time1 > time2 |
Definition:
i4 TMcmp( SYSTIME *time1, SYSTIME *time2 );
TMcmp_stamp - compare TM_STAMPs
Compare two time stamps. Returns positive if time1 greater than time2; zero if time1 equals time2; and negative if time1 less than time2. Note, this routine is for the sole use of DMF for auditing and rollforward.
Inputs:
| time1 | First timestamp. |
| time2 | Second timestamp. |
Outputs:
| None |
Returns:
| "< 0" | if time1 < time2 |
| "0" | if time1 == time2 |
| "> 0 " | if time1 > time2 |
Definition:
i4 TMcmp_stamp( TM_STAMP *time1, TM_STAMP *time2 );
TMcpu - cpu milliseconds used by process
Get CPU time in milliseconds used by process. If a host operating system cannot support this, it must return a value that is monotonically increasing within a process, (e.g., elapsed time).
Inputs:
| None |
Outputs:
| None |
Returns:
| milliseconds | used by process so far |
Definition:
i4 TMcpu()
TMcvtsecs - convert seconds to native string
Convert seconds to a character string. The number of seconds passed in is assumed to be the number of seconds since Jan. 1, 1970. You must provide the buffer to put the string in and it is assumed the buffer is big enough (TM_SIZE_STAMP bytes). Format of the string may vary between systems.
Inputs:
| secs | number of seconds |
Outputs:
| buf | buffer to store the string in |
Returns:
| None |
Definition:
STATUS TMcvtsecs( i4 secs, char *buf );
TMend - set TIMER end values
Set ending values and difference values within the input TIMER structure.
Inputs:
| tm | ptr to time info |
Outputs:
| tm | ptr to time info |
Returns:
| None |
Definition:
VOID TMend( TIMER *tm );
TMformat - format TIMER statistics difference to string (obsolete)
Format the information of the TIMER struct to human readable form in buf. The value of mode determines whether the information formatted is for the start (TIMER_START), for the end (TIMER_END) or an intermediate (TIMER_VALUE) duration (TIMER_VALUE is the default action). ident is the user supplied identifier for the TIMER. Buf is assumed to be large enough to hold it. (TM_SIZE_TIMER) + length of 'ident' +1. This routine is obsolete.
Inputs:
| tm | ptr to time info to format mode |
| mode | one of the following values: |
| TIMER_START start time | |
| TIMER_END end time | |
| TIMER_VALUE intermediate duration | |
| ident | user supplied identifier for timer |
| decchar | decimal character to use |
Outputs:
| buf | formatted system measurements |
Returns:
| None |
Definition:
VOID TMformat( TIMER *tm, i4 mode, char *ident, char decchar, char *buf );
TMget_stamp - return unique timestamp
Return a unique TM_STAMP timestamp that is increasing within a process and unique across all active processes. Note, this routine is for the sole use of DMF for auditing and rollforward.
Inputs:
| None |
Outputs:
| time | Pointer to location to return stamp. |
Returns:
| None |
Definition:
VOID TMget_stamp( TM_STAMP *stamp );
TMhrnow - current High Resolution system time since 1-Jan-70 epoch
This routine simply returns the number of seconds and nanoseconds since 00:00:00 UTC, Jan. 1, 1970.
The exact granularity of the function may vary, depending on the granularity of the system functions available on the relevant platform, but the value is always expressed in nanoseconds, and the porting engineer should make every effort to find the most accurate time function available on their system.
Inputs:
| None |
Outputs:
| time | current UTC in seconds and nanoseconds since 1/1/70 |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TMhrnow( HRSYSTIME *stime );
TMinit - initialize time zone (removed)
This function has been removed from the CL; it's presence was a bug. Any attempts to link in this function should fail. The timezone function has been supeceded by a method that works correctly. See the introduction for details.
TM_lookup_month - Find a month number give it's name
Given an imput month of the form ("jan", "feb", ...) find the the month number. On success the month_num field will be set to the month number (1-12), and status will be OK. If no match is found FAIL is returned.
Inputs:
| month_str | Month string ("jan", "feb", ...) |
Outputs:
| month_num | On success set to the month number. |
Returns:
| OK | if operation succeeded |
| FAIL | if no match is found. |
Definition:
STATUS TM_lookup_month( char *month_str, i4 month_num );
TMnow - current SYSTIME since 1-Jan-70 epoch
This routine simply returns the number of seconds since 00:00:00 UTC, Jan. 1, 1970. Must return a unique value, like TMget_stamp does.
Inputs:
| None |
Outputs:
| stime | current UTC in seconds since 1/1/70 |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
VOID TMnow( SYSTIME *stime );
TMperfstat -- Return performance statistics available from the OS
Returns available performance statistics available from the OS for the current process. As best as is possible, per platform, TMperfstat() provides a snapshot of all performance statistics available and returns the statistics by filling in the TM_PERFSTAT structure passed in by the caller. Implimentations of this function will attempt to collect the data required with the minimum possible affect on the state being measured (ie. will try to make a single system call vs. multiple system calls where possible).
The members of the TM_PERFSTAT structure are public and are defined in <tmgl.h>; see <tmgl.h> for description of current members of TM_PERFSTAT structure.
Some statistics may not be available on some operating systems, if a statistic is not available then TMperfstat() will initialize the field to the value "-1". In the case of SYSTIME structure members one must test both members of the structure for -1.
It is expected that over time new CL proposals will add members to the TM_PERFSTAT structure as new OS performance statistics become available. Clients which access the structure members by name, and do not make structure order assumptions will be upward compatible with future structure definition changes.
Inputs:
| stat | pointer to a TM_PERFSTAT structure. |
Outputs:
| stat | TM_PERFSTAT structure is filled in by this routine with available OS statistics. Unavailable fields will be set to -1. |
| sys_err |
Returns:
| OK | success. |
| TM_NOSUPPORT | No support for gathering system statistics. |
| other | reportable error status. |
Exceptions:
| None |
Side Effects:
| None |
Definition:
STATUS TMperfstat( TM_PERFSTAT *stat, CL_SYS_ERR *sys_err );
TMsecs - current whole seconds since 1-Jan-70 epoch
Return the number of seconds since 00:00:00 UTC, Jan. 1, 1970.
Inputs:
| None |
Outputs:
| None |
Returns:
| Number of seconds since 00:00:00 UTC, Jan. 1, 1970. |
Definition:
i4 TMsecs()
TMstamp_str - copnvert TM_STAMP to a fixed format string
Convert a TM_STAMP timestamp to a string of the form: dd-mmm-yyyy hh:mm:ss.cc. Note, this routine is for the sole use of DMF for auditing and rollforward.
Inputs:
| time | Pointer to timestamp. |
Outputs:
| string | Pointer to output string. Must be TM_SIZE_STAMP bytes long. |
Returns:
| None |
Definition:
VOID TMstamp_str( TM_STAMP *time, char *string );
TMstart - set TIMER start information
Set starting values within the input TIMER structure. This routine is obsolete.
Inputs:
| tm | ptr to time info |
Outputs:
| tm | ptr to time info |
Returns:
| None |
Definition:
VOID TMstart( TIMER *tm );
TMstr - convert SYSTIME to native string
This routine converts a SYSTIME time value into a character string giving the
- Day of the week
- Month
- Date
- Hour, minutes, seconds
- year
of timeval in a system dependent character format. The buffer intended to hold the resultant string must be at least TM_SIZE_STAMP bytes.
Inputs:
| timeval | time value to convert to string |
Outputs:
| timestr | character representation of timeval |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
VOID TMstr( SYSTIME *timeval, char *timestr );
TMstr_stamp - convert fixed format string to TM_STAMP
Convert a string of the form: dd-mmm-yyyy:hh:mm:ss.cc to a TM_STAMP timestamp. Any partial suffix after the yyyy is legal. (I.E dd-mmm-yyyy means dd-mmm-yyy 00:00:00.00) Note, this routine is for the sole use of DMF for auditing and rollforward.
Inputs:
| string | String to convert. |
Outputs:
| time | Pointer to TM_STAMP structure. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TMstr_stamp( char *string, TM_STAMP *time );
TMyrsize - days in a year
Routine returns the number of days in a normal year (365) if year is not a leap year. 366 is returned for a leap year. This routine does not guarantee that it will work for all years before the 1900's.
Inputs:
| year | year (larger than 0) |
Outputs:
| daysinyear | number of days in year |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TMyrsize( i4 year, i4 *daysinyear );
TMzone - minutes west to Greenwich (removed)
This function has been removed from the CL; it's presence was a bug. Any attempts to link in this function should fail. The timezone function has been supeceded by a method that works correctly. See the introduction for details.
TMtz_init - initialize default TM_TZ_CB timezone table
This routine returns a pointer to the default TM_TZ_CB structure. If the default TM_TZ_CB is not loaded, this routine gets the II_TIMEZONE_NAME value and pass to TMtz_load() to load the the timezone information file into memory.
This routine is called during FE startup and server startup.
The handle to the TM_TZ_CB is a PTR so clients don't need to know the internals of the TM_TZ_CB.
Inputs:
| tz_cb | place to put a pointer to a TM_TZ_CB. |
Outputs:
| tz_cb | filled in with a handle to the default TM_TZ_CB. |
Returns:
| OK |
| TM_NO_TZNAME |
| TM_NO_TZFILE |
| TM_TZFILE_OPNERR |
| TM_TZFILE_RDERR |
| TM_TZFILE_BAD |
| TM_TZFILE_NOMEM |
Side Effects:
| Allocates memory with MEreqmem and uses SI to read files. |
Exceptions:
| None. |
Definition:
STATUS TMtz_init(PTR *tz_cb):
TMtz_load - load timezone info from external storage
This routine finds the corresponding timezone information file for the given timezone name by calling the PM routine. TM_tz_load then open and read the timezone information file using SI routines and allocates the required memory using MEreqmem() before populating and return the pointer to the TM_TZ_CB structure.
This routine guarantees that the internal TM_TZ_CB link list structure will be safe for read operation without the need for read semaphore (i.e. no pointer to un-initialized TM_TZ_CB structure during the load operation). In addition, no duplicate version of timezone information file will be loaded even in highly concurrent environment since this routine lookup the internal TM_TZ_CB link list structure for matching timezone name before the load operation.
Since this routine updates the internal TM_TZ_CB link list structure, calling client have to make sure semaphore protection is in place when operating in a multi-tread environment.
This routine is called by TMtz_init() as well as scs_initiate() during session startup if demand loading of non-default timezone is needed.
The handle to the TM_TZ_CB is a PTR so clients don't need to know the internals of the TM_TZ_CB.
Inputs:
| tz_name | the name of the timezone to get |
| tz_cb | pointer to a place to put the located control block pointer. |
Outputs:
| tz_cb | written if sucessfull |
Returns:
| OK |
| TM_NO_TZFILE |
| TM_TZFILE_OPNERR |
| TM_TZFILE_RDERR |
| TM_TZFILE_BAD |
| TM_TZFILE_NOMEM |
Exceptions:
| None |
Side Effects:
| Allocates memory with MEreqmem and uses SI to read files. |
Definition:
STATUS TMtz_load(char *tz_name, PTR *tz_cb):
TMtz_lookup - locate loaded TM_TZ_CB block by timezone name
This routine lookup the internal TM_TZ_CB link list structure and returns the PTR to the TM_TZ_CB if timezone name is found. Otherwise, it returns TM_TZLKUP_FAIL. No read semaphore is required since the TM_TZ_CB link list structure is guaranteed to be in good order during the load operation.
This routine is called by TMtz_load() as well as scs_initiate() during session startup if demand loading of non-default timezone is needed.
The handle to the TM_TZ_CB is a PTR so clients don't need to know the internals of the TM_TZ_CB.
Inputs:
| tz_name | name to lookup |
| tz_cb | pointer to place to put pointer to locate control block. |
Outputs:
| tz_cb | pointer to a place to put the located control block pointer. |
Returns:
| TM_TZLKUP_FAIL |
Exceptions:
| None |
Definition:
STATUS TMtz_lookup(char *tz_name, PTR *tz_cb):
TMtz_search - return timezone for a time in a zone
This routine returns the number of seconds from GMT by searching the timezone data structure TM_TZ_CB point to by tz_cb according to input timevalue and the timetype (TM_TIMETYPE_GMT or TM_TIMETYPE_LOCAL).
This routine is called by other TM routines, ADF date functions, FE and various DBMS facilities.
The handle to the TM_TZ_CB is a PTR so clients don't need to know the internals of the TM_TZ_CB.
Inputs:
| tz_cb | pointer to a previously located TM_TZ_CB. |
| timetype | Either TM_TIMETYPE_GMT or TM_TIMETYPE_LOCAL, to identify the time that is being converted. |
| timevalue | The time to convert, in seconds since the epoch, either local or GMT. |
Outputs:
| None |
Returns:
| Number of seconds to add to timevalue to get to the complementary timetype. |
Exceptions:
| None |
Definition:
i4 TMtz_search(PTR tz_cb, TM_TIMETYPE timetype, i4 timevalue)
|
Ingres Compatability Library |
