TOCPREVNEXTINDEX

Lund Performance Solutions


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

Figure 5.2, Figure 5.3 and Figure 5.4 in this section were compiled with HP’s C/iX compiler using the following command statements:
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
Figure 5.6 shows how to call CHRONOS in SPLash! (See the testchro.spl file):


Figure 5.6 SPLash! Sample Calling CHRONOS
Figure 5.7 shows how to call CHRONOS in COBOL (See the testchro.cobol file):


Figure 5.7 COBOL Sample Calling CHRONOS

CHRONOS Error Messages

In the next table are listed the CHRONOS error message numbers and their respective meaning:
Table 5.3 CHRONOS Error Messages
Number
Meaning
2
Source (29:3) not in bit range 000..101
3
Missing source parameter chronos_stamp
4
Missing source parameter formatted_time or formatted_date
5
Missing source parameter unformatted_time or unformatted_date
6
Missing source parameter julian_time or julian_date
7
chronos_string cannot be used as source
8
System Local cannot be used as source
9
Missing destination parameter chronos_string
10
Destination (26:3) not in bit range 000..101
11
chronos_string destination format not in bit range 000..011
12
Destination format not in bit range 000..010
13
Source format not in bit range 00..10
14
*NOT USED*
15
Missing destination parameter julian_time or julian_date
16
Missing destination parameter formatted_time or formatted_date
17
Missing destination parameter unformatted_time or unformatted_date
18
Missing destination parameter chronos_stamp
19
Bad source numbers in one or both unformatted parameters
20
Bad source numbers in one or both julian parameters
21
Bad source numbers in one or both formatted parameters
22
Returned when something is wrong with the source or destination parameters (which was initially undetected), causing a conversion error.
Errors 19 - 21
are triggered when the following conditions apply:
For unformatted, formatted, or Julian conversions, these errors result when the numbers are not in range or are not formatted correctly. The CHRONOS function will return ASCII zeros in the destination field.
Error 22
is returned by CHRONOS when it finds a source or destination field that it does not understand.

Lund Performance Solutions
www.lund.com
Voice: (541) 812-7600
Fax: (541) 81207611
info@lund.com
TOCPREVNEXTINDEX