
               *  *  *  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)


