Review of Adager Date Functions
by
Shawn M. Gordon
President SMGA
Introduction
All the trade magazines are talking about it, it’s the doomsday foretold by Nostredamous centuries ago, it’s the year 2000, and it’s only about 800 days away. Are you ready for it? If you haven’t started yet, then you might be too late.
I hear the government is scheduled to finish testing in November of 1999. I do believe that 1999 will be the year to cheat on your taxes because the government is going to collapse. Personally I think I will take all my money out of
the bank the week before, and redeposit it on Jan 3, 2000.
Ok, I think I have scared you enough, so let’s talk about this months review. Most of you should be aware of the Adager company and product. It was the first, and still one of the finest, database transformation and management tools
available on the HP 3000. Recently some new functions were added to this tool to allow you to examine and change date values in your database. Since Adager is such a versatile and loaded tool, I am going to restrict this review to the
new date functions.
Adager runs on pretty much every version of MPE and MPE/iX with no problems.
Features
The two new Adager date functions give you essentially two abilities. The first is the ability to scan through a database and check for the validity of your date fields. Adager has gone to a lot of effort to identify any in use date
format out there, like using CALENDER or the CHRONOS format, or Powerhouse, etc. They also take into account things like the date representing an offset from a standard start date. I am one of those unfortunate people who just always
stored the whole date in YYYYMMDD format, or the output of CALENDER so I never realized how many peculiar ways people had come up with of storing dates. I did work at a place once that had stored their dates in DDMMYY format, which made
it impossible to do anything useful with them. No one could ever explain why, but no one wanted to fix them either.
Take a look at figure 1. Figure 1 shows an example dialog of examining a database for a date. What’s cool here is that based on the storage type of the date, Adager will intellegently give you the formats that make sense for that
storage type. I put in a sample entry with a zero date so we would have at least 1 bad item to report. The only thing here that I think requires explanation is the log report line, so here you go;
The log records, one per logged entry, with these meanings:
UNKNOWN 77286 * BLANK 0859:28.3 ^ ^ ^ ^ ^ ^ | | | | | | | | | | | | | | | | Timestamp | | | | | | | | | | | | | | | | | | | | | | | For "Change Date," the | | | | value written to the | | | | target date field. | | | | | | The value of the source field. It | | | is shown as a hex value if it's | | | non-ASCII. | | | | The subItem count. An * if the field is not | | a compound field. | | Entry number
A global description that indicates why the entry was logged. The possible values are UNKNOWN (if the entry is one of NULL, ZERO or BLANK), INVALID (if the entry is garbaged, i.e. a value that cannot be mapped into a date), INCORRECT (if
the entry is not a calendar date, e.g. April 31, or the 13th month of the year, etc.), INCLUDED or EXCLUDED (if the user is examining for a range), BADSQL (if the date format is “SQL date” and the value is not an SQL date).
A summary with the number of entries examined (or changed), the number of entries logged, the number of entries found to be INVALID, INCORRECT, ZERO (BLANKS) or BADSQL.
This brings us to the second function, which is CHANGE DATE. This will allow you to change the storage type, and convert the data to that new storage type. This is incredibly handy, and saves countless hours of coding. Take a look at
Figure 2, I decided to modify my date field from a J2 storing the date in Calendar format, which is a packed representation of YYDDD, to an J2 stored as YYYYMMDD in binary format. As you recall from our example, we still have the sample
zero date in one of the entries, so that is reported during the coversion.
Figure 3 has a before and after picture of the data in our dataset. You can see how everything was modified as required. This is obviously a very simple method to go through to correct your dates. The real challenge left is to modify
your code to make use of these date structures. It’s to bad the U.S. Government isn’t an HP shop, they might get their changes done in time otherwise.
Usability (also installation)
Adager basically pioneered ease of use from a command line interface, and that ease of use continues through these new functions. The installation process is very easy, but I wish they would automatically OCTCOMP their coprocessor
programs, but I suppose someone somewhere doesn’t want it done automatically, so you need to remember to do this to get maximum performance.
Reliability
Adager’s reliability is also legendary. The only other company I know that maintains this level of quality control is AICS. Sorry if I anger anyone with that, but I have never been put in a pinch by Adager, unlike some of their
competitors products.
Performance
Adager’s performance is very very fast, which is rather amazing since chunks of it are still in compatibility mode, which I guess is a testament to the effeciency of their code. I was very impressed with the times on my Examine and
Change functions.
Supportability (including Doc)
The documentation in the manual is rather terse on the new functions, and is basically limited to about a paragraph on each topic. The online descriptions of the functions is very complete however, so you won’t be missing anything. The
only downside to this is that you can’t take the manual to lunch and read through it, you have to run the program to get the details.
Support from Adager is top notch. Everyone there is friendly and knowledgable, and you almost always get someone immediatly.
Summary
Adager’s date functions are just a small subset of what Adager will do for you. As a matter of fact, the date functions are included as part of Adager. They aren’t charged for seperatly, and can’t be bought seperatly. I really can’t
find anything to fault here, other than the lack of printed documentation. If you already own Adager, then I suggest you start examining your dates ASAP, I know I am.
If you don’t own Adager, then you should get a demo, there is a lot of value beyond just saving your bacon in 2 1/2 years.
At-a-Glance box
Adager
Sun Valley, Idaho 83353-0030
800-533-7346
FAX 208-726-8191
http://www.adager.com
“Examine Date” is available for both Adager Model 1 and Model 2 users under current maintenance. “Change Date” is available to Adager Model 2 users under current maintenance.
Adager Model One US$ 2,300.00
Adager Model Two US$ 7,500.00
2. Annual maintenance after the first year for the first system
Adager Model One US$ 300.00
Adager Model Two US$ 1,000.00
Adager offers generous license and maintenance discounts for additional systems that belong to the same fiscal entity. Adager has an upgrade program that makes it easy to convert from Model 1 to Model 2. They also have a competitive
upgrade program.
Figure 1
Database [NO MORE] ? FYIDB
IMAGE/SQL Database FYIDB.PUB.SMGA: Consistency checking
Database FYIDB.PUB.SMGA. Adager command [EXIT] ? EXAMINE DATE
Do you need help on DATE formats and operations [NO] ?
DateExamine:
DataItem [NO MORE] ? DATE-ON
DATE-ON, J (This DataItem has 2 bytes)
If Adager's EXAMINE DATE function reports any problems, you MUST fix
them (via QUERY or your application programs) before attempting to use
CHANGE DATE (unless you like the default values to which I convert them).
LOG file for date-related operations [THIS TERMINAL] ?
Which is the current DATE format for this item of type J ?
1) Number of days starting with Jan 1, 1973
2) Number of days starting with Jan 1, 1930
3) Number of days starting with Jan 1, 1900
4) PowerHouse yymmdd bit-packed as [7/4/5]
5) HP Calendar yyddd bit-packed as [7/9]
Number of your choice [NONE] ? 5
Applications differ in their treatment of yy, which is between 0 and 127.
Some simply calculate yyyy as 1900 + yy, enabling dates to span 1900 to 2027.
I handle this case automatically for you.
Others check the yy value: Is it LESS than some cutoff (or threshold)?
If yy is LESS than the cutoff, yyyy becomes 2000 + yy.
If yy is greater than or equal to the cutoff, yyyy becomes 1900 + yy
Adager Function: Examine Date
Do you want to use a cutoff value [NO] ?
I always log entries with dates that are INVALID (choice number 1).
I can ALSO log entries according to other criteria (choices 2, 3, or 4).
Please specify your choice:
1) Only log entries with INVALID date values
2) Also log entries that have nulls, zeroes, or blanks as date values
3) Also log entries with dates that are WITHIN a range
4) Also log entries with dates that are OUTSIDE a range
Number of your choice [1] ? 2
DATE-ON is defined as a field in:
USER-M, M
DateExamine:
DataItem [NO MORE] ?
Database FYIDB.PUB.SMGA. Adager command [DO THE SCHEDULED TASKS] ?
FM Step 9 of 14: Review/transform datasets
SAT, MAY 31, 1997, 8:29'57 AM
USER-M
********************************************************************************
FWDate 19960909 SAT, MAY 31, 1997, 8:29 AM
Report of a Mode 2 EXAMINE DATE run processing the entries of the
dataset USER-M of the FYIDB.PUB.SMGA database.
The 'dates' in field DATE-ON are processed as Date Type 104
SPECIAL is DISABLED and LENIENT is DISABLED.
================================================================================
UNKNOWN 187 * ZERO 0829:58.6
--------------------------------------------------------------------------------
EXAMINE DATE SUMMARY SAT, MAY 31, 1997, 8:29 AM
I examined 17 dates in 17 entries.
No INVALID dates were detected.
No INCORRECT dates were detected.
1 date was NULL, ZERO or BLANK.
Figure 2
Database FYIDB.PUB.SMGA. Adager command [EXIT] ? CHANGE DATES
===============================================================================
I don't detect a current DBSTORE for this database. You MUST be able to
recover your information should we run into space or time limitations.
===============================================================================
Do you have an up-to-date backup of your database [NO] ? Y
Do you need help on DATE formats and operations [NO] ? Y
cc means century.
yy means year.
ccyy (or yyyy) means a 4-digit year.
mm means month.
dd means day of month.
ddd means day of year.
ddddd means a 16-bit integer count of days since a specific date.
ddddddd means a 32-bit integer count of days since a specific date.
DateChange:
DataItem [NO MORE] ? DATE-ON
DATE-ON, J (This DataItem has 2 bytes)
NOTE: Changing date-oriented values is IRREVERSIBLE. You MUST have a current
backup of your database. You should also use Adager's EXAMINE DATE on
this DataItem (to get a log file with bad date values on ALL datasets
that have this item as a field) BEFORE using CHANGE DATE on it.
If Adager's EXAMINE DATE function reports any problems, you MUST fix
them (via QUERY or your application programs) before attempting to use
CHANGE DATE (unless you like the default values to which I convert them).
Do you, INDEED, have a full backup of your database [NO] ? Y
Have you RECENTLY used EXAMINE DATE on DataItem DATE-ON [NO] ? Y
LOG file for date-related operations [THIS TERMINAL] ?
Which is the current DATE format for this item of type J ?
1) Number of days starting with Jan 1, 1973
2) Number of days starting with Jan 1, 1930
3) Number of days starting with Jan 1, 1900
4) PowerHouse yymmdd bit-packed as [7/4/5]
5) HP Calendar yyddd bit-packed as [7/9]
Number of your choice [NONE] ? 5
Applications differ in their treatment of yy, which is between 0 and 127.
Some simply calculate yyyy as 1900 + yy, enabling dates to span 1900 to 2027.
I handle this case automatically for you.
Others check the yy value: Is it LESS than some cutoff (or threshold)?
If yy is LESS than the cutoff, yyyy becomes 2000 + yy.
If yy is greater than or equal to the cutoff, yyyy becomes 1900 + yy
Do you want to use a cutoff value [NO] ?
To which date format would you like to convert DATE-ON?
1) ASCII yyyymmdd (8 bytes)
2) ASCII mmddyyyy (8 bytes)
3) ASCII ddmmyyyy (8 bytes)
4) Binary yyyymmdd (32 bits, 4 bytes)
5) Binary mmddyyyy (32 bits, 4 bytes)
6) Binary ddmmyyyy (32 bits, 4 bytes)
7) Number of days starting with Jan 1, 0000 (4 bytes)
8) ASCII ccyy, treated as ccyy0101 (4 bytes)
9) ASCII yyyymm (6 bytes)
10) ASCII yyyyddd (8 bytes)
11) Packed yyyyddd (8 nibbles, 4 bytes)
12) Binary yyyyddd (32 bits, 4 bytes)
13) Double HP Calendar yyyyddd bit-packed as [23/9] (4 bytes)
14) Binary IMAGE/SQL and ALLBASE/SQL format (16 bytes)
15) Double PowerHouse yyyymmdd bit-packed as [23/4/5] (4 bytes)
16) SRN Chronos bit-packed format (6 bytes)
Adager Function: Change Date
Number of your choice [NONE] ? 4
4) Binary yyyymmdd (32 bits, 4 bytes) [YES] ?
DATE-ON, J New definition [I2] ? J2
The item definition is now: J2
DATE-ON is defined as a field in:
USER-M, M
OK to change the date format for DATE-ON [NO] ? Y
Also:
Are you sure you want to change DATE-ON from J to J2 [NO] ? Y
I changed the date format for DATE-ON
Also, according to your request:
I changed DataItem DATE-ON from J to J2
DateChange:
DataItem [NO MORE] ?
At this point you may exit, leaving your database unchanged; or you may specify
more Adager commands; or you may apply the changes that you already specified:
Database FYIDB.PUB.SMGA. Adager command [APPLY CHANGES] ?
NP Step 4 of 14: Verify path tables
SAT, MAY 31, 1997, 8:34'10 AM
FM Step 9 of 14: Review/transform datasets
SAT, MAY 31, 1997, 8:34'10 AM
USER-M
I reblocked USER-M. Old BlockFactor: 4; new: 6
********************************************************************************
FWDate 19960909 SAT, MAY 31, 1997, 8:34 AM
Report of a Mode 5 CHANGE DATE run processing the entries of the
dataset USER-M of the FYIDB.PUB.SMGA database.
The 'dates' in field DATE-ON are processed as Date Type 104
SPECIAL is DISABLED and LENIENT is DISABLED.
These 'input' dates are converted to Date Type 200.
Output dates will have the same signs as the input dates.
================================================================================
--------------------------------------------------------------------------------
CHANGE DATE SUMMARY SAT, MAY 31, 1997, 8:34 AM
I converted 17 dates in 17 entries.
No INVALID dates were detected.
No INCORRECT dates were detected.
1 date was NULL, ZERO or BLANK and was converted to a ZERO date.
................................................................................
SAT, MAY 31, 1997, 8:34'11 AM
*** ***
We are committed now. Please do NOT disturb!
*** ***
PR Step 11 of 14: Update root file
SAT, MAY 31, 1997, 8:34'11 AM
CB Step 14 of 14: Close database
SAT, MAY 31, 1997, 8:34'12 AM
I have now closed database FYIDB.PUB.SMGA
Figure 3
before change
>B=FYIDB
PASSWORD = >>
MODE = >>1
>S=USER-M
>F ALL MAIL-NAME
USING SERIAL READ
16 ENTRIES QUALIFIED
>R
>>D1,DATE-ON,10;END
2173L
2173L
2173L
1676J
1676J
1825M
1676J
1606P
1676J
1676J
1676J
1606P
1620P
1579N
2173L
2173L
after change
HP32216N.03.07 QUERY/NM SAT, MAY 31, 1997, 10:34 AM
COPYRIGHT HEWLETT-PACKARD CO. 1976
>B=FYIDB
PASSWORD = >>
MODE = >>1
>S=USER-M
>F ALL MAIL-NAME
USING SERIAL READ
17 ENTRIES QUALIFIED
>R
>>D1,DATE-ON,10;END
19851010
19851010
19851010
19950515
19950515
19920626
19950515
19961112
19950515
19950515
19950515
19961112
19960625
19970318
19851010
0
19851010