* * * README file for clunk routines * * * Last edit: 6-NOV-1987 18:08:57 This UIC contains a set of routines which allow you convert between DEC style date and time to a clunk style ( 64 bit unsigned integer ) date and time and visa versa. There are also routines which allow you to manipulate clunk values which in turn allow you to manipulate dates and times. The rudimentary routines to add, subtract, multiply and divide 64 bit unsigned integers are also accessable. A "clunk" is 100 nanoseconds (10 million clunks = 1 second). A clunk date is defined as the number of clunks (herein expressed as a 64 bit integer) since November 17,1858 - the date that the first photographic plate was exposed at the Smithsonian Astrophysical Laboratory ushering in the age of modern astronomy. DEC uses clunk dates for recording time in VMS. Likewise VMS Datatrieve and RSX Datatrieve store and work with clunk dates. Uses include converting Datatrieve stored dates into ASCII dates, converting ASCII dates into clunk dates so that Datatrieve can read them, and creating a continuous numeric date/time for time stamping events and easily calculating time intervals. This routine for converting between ASCII date and time (between 1900 and 1999) and clunks was obtained from an '82 Multitasker article by Bob Rock of Northern Telecom Inc. (APR-81) and modified by Phil Hannay here at Cargill to detect illegal year input and correct the second and minute conversion of the time input. On testing it was discovered that as originally submitted the routine exhibited discontinuities in the clunk times. Investigation revealed two sources of error. The first was an error in the definitions that were used for 1 second, 1 minute and 1 hour in clunks, and the second was a problem in the routine for adding two 64 bit numbers. These problems have all been corrected and the clunk software has been expanded on since Bob Rock's original submission. The orginal version contained four routines. The routine 'D2CLNK' will take a DEC style date and time and convert it into a 64 bit clunk value. The routine 'C2DATE' will take a 64 bit clunk value and convert it to a DEC style date and time. Two other routines included allowed the addition of two 64 bit clunk values and the other routine subtracted two clunk values. These last two routines were not accessable by high level languages though. The clunk package now consists of nine routines that are all accessable by higher level languages via the DEC standard call site. These routines are: D2CLNK - Converts a DEC style date to a clunk value. C2DATE - Converts a clunk value to a DEC style date. A2CLNK - Adds a specificed amount of time to a clunk value. S2CLNK - Computes the difference in time between two clunk values. C2WDAY - Tells you what day of the week the clunk value represents. ADD64 - Adds two clunk values. SUB64 - Subtracts two clunk values. MUL64 - Multiplies two clunk values. DIV64 - Divides two clunk values returning a quotient and remainder. All of the above routines are written in MACRO-11 with all parameters being passed via the DEC standard call site. See the source code listings for more details. The routinea are written as position independent code with the stack providing all buffer space. This allows the routines to be placed in a shared resident or cluster library. A resident library called 'CLURES' is contained in this UIC. The routines are also written as pure code with no read/write or data psects. This enables a supervisor mode library to be built, but a small problem developed when this was first attempted. Two of the syslib routines being called could not be included in a supervisor mode library because they violated one of the many rules for supervisor mode libraries. This UIC also contains two other MACRO routines 'CATBX' and 'EDDATX' which are modified copies of the syslib routines 'CATB' and 'EDDAT'. They are only used for building the supervisor mode library 'CLUFSL'. The task build file 'C2DATETST.TKB' gives a good example of building a task with a resident or supervisor mode library. Also, the file 'CLUNK.OLB' is an object module library of the nine routines. This UIC contains a test program for each of the nine routines written in OMSI V2.1 Pascal. The files with the extension '.EXT' are the external procedure declarations for each routine. The test program names always end with 'xxxxxTST.PAS'. The task build file names always use the extension '.TKB'. The UIC also contains the original 'CLUNK.MAC' file with the problems corrected and a Fortran program for testing it, and command files to compile and build both programs. The Fortran program also provides a method of converting the four- integer clunk date into a single double-precision value, which is adequate when working to the nearest second. When you run "TSTTIM", it will ask for the date and time to be converted in standard RSX-11 notation (e.g. 27-AUG-86 17:58:52) and report back: 1. the date and time as entered, 2. the clunk time expressed as four words and as a decimal number divided by 10,000,000 (i.e. seconds ), 3. the difference between the current time and the previously entered time in seconds (back calculated from the clunk time) and finally, 4. the clunk routine return status. The program will exit on a negative return status (e.g. a null date and time entry). Example: Date Time Word1 2 3 4 Clunk Time(secs) Diff Stat 22-AUG-86 00:00:00 0 7230 15547 143 4031769600.000 4031769600. 1 22-AUG-86 00:00:01 -27008 7382 15547 143 4031769601.000 1. 1 22-AUG-86 00:01:01 -9088 16537 15547 143 4031769661.000 60. 1 Points at which the previous submission was discontinuous were at the transition from hours to days (i.e. 22-AUG-86 23:59:59 to 23-AUG-86 00:00:00) and at unique times when a special cascading carry bit condition occurred in the 64 bit addition (e.g. 05-JUN-86 17:09:27). This was modified by Bob Thomas,AMI/Research Bldg.,Cargill inc.,P.O. Box 9300,Mpls, MN 55440, (612) 475-5432. Directory: ADD64 - Adds two clunk values. A2CLNK - Adds a specificed amount of time to a clunk value. CATBX - Modified syslib routine CATB. CLUFSL - Supervisor mode library support CLUNK.MAC - Original conversion subroutines. CLUNK.OLB - Object module library of clunk routines. CLUOLB.CMD - Command file to build CLUNK.OLB. CLURES - Resident library support. C2DATE - Converts a clunk value to a DEC style date. C2WDAY - Tells you what day of the week the clunk value represents. DIV64 - Divides two clunk values returning a quotient and remainder. D2CLNK - Converts a DEC style date to a clunk value. EDDATX - Modified syslib routine EDDAT. HELP.HLP - Some notes. MUL64 - Multiplies two clunk values. README.CLU - this file. SUB64 - Subtracts two clunk values. S2CLNK - Computes the difference in time between two clunk values. TSTCLU - Old pascal test program. TSTTIM.FTN - F77 source for testing conversion routines TSTTIM.CMD - Command file to build TSTTIM TSTTIM.TKB - Task build command file for TKB to build TSTTIM Some important constants concerning the clunk routines: NOTE: FORMAT OF LONG WORDS IS LSW,...,MSW A SECOND - 10,000,000 CLUNKS OR OCTAL 113200,000230,000000,000000 A MINUTE - 600,000,000 CLUNKS OR OCTAL 043000,021703,000000,000000 AN HOUR - 36,000,000,000 CLUNKS OR OCTAL 064000,060704,000010,000000 A DAY - 864,000,000,000 CLUNKS OR OCTAL 140000,025151,000311,000000 A WEEK - 6,048,000,000,000 CLUNKS OR OCTAL 040000,024344,002600,000000 28 DAYS - 24,192,000,000,000 CLUNKS OR OCTAL 000000,121621,013000,000000 29 DAYS - 25,056,000,000,000 CLUNKS OR OCTAL 140000,146772,013311,000000 30 DAYS - 25,920,000,000,000 CLUNKS OR OCTAL 100000,174144,013622,000000 31 DAYS - 26,787,000,000,000 CLUNKS OR OCTAL 040000,021316,014134,000000 NON-LEAP YEAR (365 DAYS) - 306,600,000,000,000 CLUNKS OR OCTAL 140000,074306,017321,000001 LEAP YEAR (366 DAYS) - 307,440,000,000,000 CLUNKS OR OCTAL 100000,121460,017632,000001 OFFSET FROM 17-NOV-1858 TO 1-JAN-1900 IS OCTAL 000000,072215,015304,000056 History of clunk software package: --- ORIGINALLY --- --- AUTHORED BY --- BOB ROCK NORTHEAST ELECTRONICS DIV. NORTHERN TELECOM INC. AIRPORT RD. CONCORD, N.H. 03301 (603) 224-6511 EXT 347 THIS ROUTINE HAS BEEN MODIFIED BY PHILIP HANNAY, CARGILL GRAIN LAB, 3444 DIGHT AV S, MINNEAPOLIS, MN. 55407, (612)-721-8531, FOR OUR USE. THE MODIFICATIONS ARE ACTUALLY CORRECTIONS, ONE TO DETECT ILLEGAL CHARACTERS IN THE ASCII YEAR INPUT, THE OTHER TO DO CORRECT DECIMAL TO BINARY CONVERSION OF THE MINUTES AND SECONDS OF THE ASCII TIME INPUT. JULY 6, 1982. THIS ROUTINE USES THE STANDARD DEC CALL SITE SO IT CAN BE CALLED BY FORTRAN OR BY OMSI PASCAL V2.0 WITH NO CHANGES. IT WAS FURTHER MODIFIED BY BOB THOMAS,CARGILL,INC.,P.O. BOX 9300 MPLS,MN,55440, (612)475-5432. THOSE FURTHER MODIFICATIONS WERE TO CORRECT THE VALUES FOR 1 SEC, 1 MIN AND 1 HOUR. IN ADDITION THE ADD64 ROUTINE WAS REWRITTEN TO PROVIDE FOR CASCADING CARRY BITS (SUCH AS THOSE THAT OCCUR ON 05-JUN-86 17:09:27). THE PROGRAM CLUNK.MAC WAS BROKEN INTO NINE SEPERATE ROUTINES. MODIFIED TO USE ALL ITS BUFFER SPACE ON THE STACK AND GENERATE ONLY PURE CODE. WROTE ROUTINES 'CATBX' AND 'EDDATX' FROM SYSLIB TO BUILD CLUNK ROUTINES INTO SUPERVISOR MODE LIBRARY. ALSO WROTE ROUTINES 'A2CLNK', 'S2CLNK','C2WDAY','MUL64', AND 'DIV64'. PUT DEC STANDARD CALL SITE ON ALL ADDITIONAL ROUTINES AS WELL AS 'ADD64' AND 'SUB64'. THEN PACKAGED THE WORKS UP AND SUBMITTED TO DECUS SIG TAPES DEC-87. PETER STADICK, CARGILL INC., P.O. DRAWER AR, RESERVE, LA 70084. (504)-536-4111. (MODIFICATIONS MADE MAY,OCT,NOV 1987)