The CHRONOS Tool
CHRONOS is a library of procedures that manipulate date and time information in a variety of
formats. Information can easily be converted from one form to another, including forms that
permit arithmetic calculations. It is also possible to increment or decrement time or date values.
CHRONOS supports a date range from year 0 to 4095, offering an immediate solution to "turn of
the century" problems.
Operation
CHRONOS is most typically used to translate a date or time from a "stored" format in a data base
(i.e., 990331) to a "display" format on a screen or report (i.e., March 31, 1999), or to reformat a
date from a data entry field (i.e., 033199) to a "stored" format (i.e., 990331), or to recalculate the
amount of time between two events.
CHRONOS can be called like an MPE intrinsic. This means that the user intrinsic file,
CHRONOS.INTRIN.LPSTOOLS (in SYSINTR format), should be specified in your source along
with the CHRONOS intrinsic declaration. Parameter specifications are used to further define the
operation. Therefore calling CHRONOS boils down to determining what kind of operation you
want performed is specified in the CHRONOS mode parameter. There are literally hundreds of
possible configurations that you can specify. Appendix H, "CHRONOS Modes", provides a
comprehensive listing of all modes.
Because CHRONOS provides so many conventions, not all parameters may be required for each
call. Parameter omission is language dependent, and you should consult your language
documentation for details. HP C/iX, HP Pascal/iX, and SPLash! all use the comma to omit
parameters. For ANSI-C compatibility, use the keyword "NULL" to omit parameters.
The examples provided show you how to handle parameter specification. The syntax example
show you the ordering sequence of the parameters and the data type for each parameter.
Date and Time Formats
CHRONOS supports several date and time formats:
chronos-stamp
CHRONOS supports an internal format called chronos-stamp. The chronos-stamp is a 6-byte
time field with millisecond precision. For example, the 6-byte chronos-stamp for January 28,
1993 at precisely 4:38:00.1269 p.m. is (in hexadecimal) $7C90E4270F5 (see
"CHRONOS_STAMP", for a bit-level description).
Gregorian (formatted)
The formatted Gregorian date and time uses 8 byes of storage. The field separator for the date
defaults to the slash (/). The field separator for the time defaults to the colon (:). The standard US
formatting for the date and time for the last day of 1999 at noon would look like 12/31/99 12:00:00.
You may choose any symbol as a field separator when a call is made to CHRONOS.
The date can be returned in one of three ways:
year-month-day (i.e., 99/12/31)
day-month-year (i.e., 31/12/99)
month-day-year (i.e., 12/31/99)
Gregorian (unformatted)
The unformatted Gregorian date and time uses 6 byes of storage. The standard US -style for the
unformatted date and time for the last day of 1999 at noon would look like 123199 120000.
The date can be returned in one of three ways:
year-month-day (i.e., 991231)
day-month-year (i.e., 311299)
month-day-year (i.e., 123199)
Julian
The Julian year is returned in a 2-byte array and is not terminated with any special character.
Leading zero digits are padded with ASCII "0"not ASCII spaces. For example, for 1999 the Julian
year would return 99. The Julian day of the year is returned in a 3-byte array and is not terminated
with any special character. Leading zero digits are padded with ASCII "0" not ASCII spaces. For
example, the Julian day for Feb 1 would return 032.
String
CHRONOS provides four ways to format string output:
day-month-year
month-day-year
dayname-day-month-year
dayname-month-day-year
The length of the string output is always 30 and is not terminated with any special character.
Unused characters are set to ASCII spaces:
day-month-year looks like "28 January 1999 "
month-day-year looks like "January 28, 1999 "
dayname-day-month-year looks like "Thursday, 28 January 1999 "
dayname-month-day-year looks like "Thursday, January 28, 1999 "
CHRONOS can convert any of the above formats into any of the other formats. In addition, by
specifying an increment, CHRONOS can increment the time or date either forward or backward.
Providing the optional parameter day_of_week will cause CHRONOS to return the numerical day
of the week, where Sunday=0, Monday=1, and so forth.
Providing the optional parameter day_of_week allows the user to change the default century, or
to obtain the current century. For example, this parameter returns 1900 currently.
CHRONOS Intrinsic
CHRONOS Intrinsic performs the requested date/time conversion:
int chronos (parameter1, parameter2 [,parameter3, ... parameter15])
The Parameter Set is listed next where each parameter is either an integer, character array, or
byte:
Table 5.1 CHRONOS Parameter Set
|
Parameter
|
Name
|
Type
|
Comment
|
|
1
|
status
|
integer 32-bit signed
|
Required
|
|
2
|
mode
|
integer 32-bit signed
|
Required
|
|
3
|
chronos_stamp
|
character array
|
Optional
|
|
4
|
formatted_date
|
character array
|
Optional
|
|
5
|
formatted_time
|
character array
|
Optional
|
|
6
|
unformatted_date
|
character array
|
Optional
|
|
7
|
unformatted_time
|
character array
|
Optional
|
|
8
|
date_symbol
|
byte
|
Optional
|
|
9
|
time_symbol
|
byte
|
Optional
|
|
10
|
increment
|
integer 32-bit signed
|
Optional
|
|
11
|
chronos_string
|
character array
|
Optional
|
|
12
|
julian_year
|
character array
|
Optional
|
|
13
|
julian_date
|
character array
|
Optional
|
|
14
|
day_of_week
|
integer 32-bit signed
|
Optional
|
|
15
|
century
|
integer 32-bit signed
|
Optional
|
Return Value
CHRONOS returns a 32-bit integer encoded as follows:
|
< 0
|
:Error
-1 = bad parameter, check the status variable for more information.
-23 = conversion error, check the status variable for more information.
|
|
= 0
|
:No error
|
|
> 0
|
:Warning conversion probably worked, the status variable for more information.
|
Parameters
The following table describes the CHRONOS’s parameters.
Table 5.2 CHRONOS’s Parameters
|
Parameter
|
Description
|
|
status
|
Integer by reference (required). Contains the status of the call to CHRONOS. The sign of the return value describes the kind of status where a negative value denotes an error and a positive value denotes a warning. The absolute value of status is the number of the error or warning. A zero value means the call was successful.
|
|
mode
|
Integer by value (required). Contains the bit-encoded directions for the conversion. See "CHRONOS_MODE" for complete information.
|
|
chronos_stamp
|
Byte array by reference (optional). Contains the 6-byte CHRONOS time and date stamp. See "CHRONOS_STAMP" for complete information.
|
|
formatted_date
|
Byte array by references (optional). Contains the 8-byte string that represents the month, day and year in various formats. For example, 03/12/99. The number separator defaults to the slash (/). Use the date_symbol parameter to specify an alternate separator symbol.
|
|
formatted_time
|
Byte array by references (optional). Contains the 8-byte string that represents the hour, minute and second formatted as hh:mm:ss where hh is in 24 hour format. The number separator defaults to the colon (:). Use the time_symbol parameter to specify an alternate symbol.
|
|
unformatted_date
|
Byte array by references (optional). Contains the same information as formatted_date, except that the number separator has been omitted. The length of the array is 6 bytes.
|
|
unformatted_time
|
Byte array by references (optional). Contains the same information as formatted_time, except that the number separator has been omitted. The length of the array is 6 bytes.
|
|
date_symbol
|
Byte by value (optional). Contains the single ASCII character that will be used to separate the numbers in the formatted_date string.
|
|
time_symbol
|
Byte by value (optional). Contains the single ASCII character that will be used to separate the numbers in the formatted_time string.
|
|
increment
|
Byte array by references (optional). Contains the signed value that can be used to add or subtract values from the time or date as specified by the mode parameter.
|
|
chronos_string
|
Byte array by references (optional). The 30-byte array that contains the formatted date string in one of several formats as specified by the mode parameter. For example: Thursday, January 14, 1999.
|
|
julian_year
|
Byte array by references (optional). The 2-byte array that contains the last two digits of the year. For example: "99" for the year 1999.
|
|
julian_date
|
Byte array by references (optional). The 3-byte array that contains the Julian date of the current year. For example: "312" for the 312th day of the year.
|
|
day_of_week
|
Integer by reference (optional). If provided, this parameter returns the numerical day of the week. The number returned is in the range 0..6 where 0=Sunday, 1=Monday, and so forth.
|
|
century
|
Integer by reference (optional). Can be used to specify the century, or will return the current century if passed in with a value of zero (0).
|
Operation
This section provides how-to information for two key topics. First, information on how to specify
the CHRONOS mode parameter is discussed. This section is followed by chronos-stamp
specifications.
CHRONOS_MODE
The CHRONOS mode parameter is used to specify the type of operation you want performed.
The CHRONOS mode is a 32-bit integer where bits 0 to 18 should be zero and bits 19 through 31
are encoded as follows:
Each of the encoded bit fields (source, destination, source format, etc.) is discussed next.
Source (29:3) and Destination (26:3) Bit Mapping
|
000
|
System Local Time and Date from the CALENDAR intrinsic (Source only)
|
|
001
|
CHRONOS time and date stamp
|
Required parameter: chronos_stamp
|
|
010
|
Formatted string
|
Required parameter: formatted_date
Optional parameter: formatted_time
|
|
011
|
Unformatted string
|
Required parameter: unformatted_date
Optional parameter: formatted_time
|
|
100
|
Julian date and year
|
Required parameter: julian_year, julian_date
|
|
101
|
String
|
Required parameter: chronos_string (Destination only)
|
Source format (24:2) Bit Mapping
|
00
|
MDY
|
(month, day, year)
|
|
01
|
DMY
|
(day, month, year)
|
|
10
|
YMD
|
(year, month, day)
|
|
|
NOTE Only meaningful for formatted string and unformatted string modes.
|
Destination format (21:3) Bit Mapping
|
000
|
MDY
|
(month, day, year)
|
|
001
|
DMY
|
(day, month, year)
|
|
010
|
YMD
|
(year, month, day)
|
|
|
NOTE Only meaningful for formatted string and unformatted string modes.
|
For example, if the Destination field is 101 (STRING), then the Destination format is bit mapped
as follows:
|
000
|
dayname, monthname, day, year
|
(i.e., MON, JANUARY 21, 1995)
|
|
001
|
dayname, day, monthname, year
|
(i.e., MON, 21 JANUARY 1995)
|
|
010
|
monthname, day, year
|
(i.e., JANUARY 21, 1995)
|
|
011
|
day, monthname, year
|
(i.e., 21 JANUARY, 1995)
|
Increment Flag (20:1)
This bit is a flag that is used to determine if a time or date field should be incremented.
|
0
|
no increment
|
|
1
|
increment wanted
Check bit (19:1) to determine if source time or date increment is desired.
|
Increment Type (19:1)
This bit field is used in conjunction with bit field (20:1) and the increment parameter to specify an
increment value and type. If the value for this bit field is zero, then the increment parameter
contains the number of days to be added or subtracted to the source date. If the value for this bit
field is one, then the increment parameter contains the number of minutes to be added or
subtracted to the source time.
|
0
|
source date increment (in days)
|
|
1
|
source time increment (in minutes)
|
|
|
NOTE Some combination of mode values and parameters can result in superfluous information being passed to CHRONOS. If CHRONOS can detect such a case, a warning will be returned. See Appendix H, "CHRONOS Modes", for a complete list of all mode numbers. Because there are some "don’t care" cases, there are several mode numbers that produce the same results.
|
CHRONOS_STAMP
CHRONOS has a unique format for storing the precise "definition" of a moment in time, including
century through millisecond and all components in between. This is accomplished by using a "bit-
mapping" technique in a 6-byte field:
Figure 5.1 Defining CHRONOS_STAMP
When chronos_stamps are being stored as data, it may be desirable to zero out all or portions of
the time maps. For instance, if the chronos_stamps is being used as a Key into a data base
record based on date, the time portion would cause multiple entries for the same date to be
created.
If Keys are being set up based on the date and time of an entry, for instance in an auditing
situation for tracking when data was placed in the data base, the milliseconds might cause
multiple entries for the same minute.
CHRONOS Examples
Compile statement:
ccxl exam1,,$NULL;info="-Aa -Wc, -e"
Link statements (i.e., linking to the RL’s chronos.rl.lpstools and libcinit.lib.sys)
:link from=$OLDPASS;TO=exam1.pub;rl=chronos.rl.lpstools,
libcinit.lib.sys
Figure 5.2 shows how CHRONOS will use the system-local date and return the chronos-string in
dayname-month-day-year format:
Figure 5.2 System-Local Date
Figure 5.3 is an example of how to call CHRONOS twice, the first time to get the current date and
time and return it as formatted date and time. Then call CHRONOS again to subtract 2 hours from
the formatted time.
Figure 5.3 Calling CHRONOS Twice
Figure 5.4 is an example of rewriting the previous example to perform the same function with only
one call to CHRONOS:
Figure 5.4 Calling CHRONOS Once
The following figure shows how to call CHRONOS in Pascal (see the testchro.pascal file):
Figure 5.5 Pascal Sample Calling CHRONOS
