 Introduction						25 Aug 92
 System Identity      - TIMINI, GETDOS, FINDCK, CKTDF
 Clock Reading        - RCLOCK, RDCLK
 File Stamp Routines  - GSTAMP, PSTAMP, GETTD, SETTD
 Directory Selection  - DDIRQS, DDIRQ, DDIRNPAK, DDIRPAK, DDIRSEL
 Time Conversions     - U2PTIM, P2UTIM, U2MTIM, M2UTIM
 Utility Routines     - BCD2BIN, BIN2BCD, DVERS
 DateStamper(tm) T&D  - OPENTD, CLOSTD, FSTNXT, RWTD
:		   Introduction to DSLIB 

This library contains a collection of routines to facilitate
addition of File Time and Date Stamping and Real Time Clock
features.  A common Date and Time format is used to exchange
date and time data with user programs.  It uses BCD digits as:

    Byte Offset  00  01  02  03  04  05
		 --  --  --  --  --  --
		 YY  MM  DD  hh  mm  ss

   Where YY = Year (78-99 is 1978-1999, 00-77 is 2000-2077),
MM = Month (1..12), DD = Day (1..28,30,31), hh = Hour (0..23),
mm = Minute (00..59), ss = Second (00..59).

Generalized routines are included which uniformly return Clock
time, as well as File Stamp data from ZSDOS/ZDDOS, CP/M 2.2 or
ZRDOS 1.x with Plu*Perfect Systems' DateStamper(tm), and
Digital Research's CP/M Plus (also known as CP/M 3).  The
common data structures are automatically converted to the
appropriate internal formats for the running system.
   As with the Clock structure, File Stamp data is handled in
a consistent DateStamper(tm)/ZSDOS format of packed BCD digits
in a 15-byte field as:

		|-- Create --|  |- L.Access -|  |-- Modify --|
 Byte Offset	00 01 02 03 04  05 06 07 08 09  10 11 12 13 14
		-- -- -- -- --  -- -- -- -- --  -- -- -- -- --
		YY MM DD hh mm  YY MM DD hh mm  YY MM DD hh mm

Where YY = Year (78-99 is 1978-1999, 00-77 is 2000-2077), MM =
Month (1..12), DD = Day (1..28,30,31), hh = Hour (0..23), mm =
Minute (00..59).

In addition to the generalized interface routines, entry points
exist for DateStamper(tm) specific routines.  Many of these
specific routines are automatically called from the generalized
routines when DateStamper is detected.

Conversion routines also exist to manage interfaces between
Date/Time fields of DateStamper(tm), the MS-DOS compatible
DosDisk(tm), and the CP/M Plus-compatible P2DOS format.
:		   System Identity 

TIMINI - See if there is a Clock we can read.

   TIMTYP - Byte variable for Type of Time/Date Stamping and
		clock in use ("3"=CP/M Plus, "S"=Internal ZSDOS
		or ZDDOS, "D"=DateStamper).

  ENTER: None
  EXIT : A = Time method, Zero Flag Clear (NZ) if Clock found
	   A = 0, Zero Flag Set (Z) if no clock found
  USES : AF

 Usage: This routine calls GETDOS setting DOSVER and DOSTYP,
  then looks for a clock to read, implying a File Stamp method.
  Types are: "S"=ZSDOS/ZDDOS Internal, "D"=DateStamper,
  "3"=CP/M Plus (CP/M 3.x, also termed P2DOS type).  This byte
  may be accessed when desired, and is used by GSTAMP and
  PSTAMP to Get and Set File Stamps respectively.

GETDOS - Determine DOS type & Version, set global variables.

   DOSTYP - Byte variable for DOS type ("S"=ZSDOS, "D"=ZDDOS,
		"1"=CP/M 1.x, "2"=CP/M 2.x, "3"=CP/M Plus (3.x),
		"R"=ZRDOS, 0=Unknown)
   DOSVER - Byte variable for DOS version # (vendor specific)

  ENTER: None
  EXIT : A = DOS Type Character, Zero Clear (NZ) if identified
	   A = 0, Zero Flag Set (Z) if Not identified
  USES : AF

 Usage: This routine is used to identify the running DOS type
  and version.  It is called from TIMINI, but may be called
  separately.  After it is called, DOSTYP and DOSVER globals
  may be directly accessed.

FINDCK - Check for DateStamper(tm) clock and set read status

  ENTER: None
  EXIT :  A <> 0, Zero Flag Clear (NZ) if Clock Found
	 HL = pointer to Clock starting address if Found
	    A = 0, Zero Flag Set (Z), HL = - if Not Found
  USES : AF,BC,DE,HL

 Usage: Used with DateStamper(tm)-specific interfaces.  Call
  this routine near the beginning of a program to determine
  clock status.  This routine is not needed if the recommended
  TIMINI/RCLOCK generalized routines are used.

CKTDF - Check for DateStamper(tm) Time&Date File on drive

  ENTER: None
  EXIT : A <> 0, Zero Flag Reset (NZ) if T&D file located Ok
	   A = 0, Zero Flag Set (Z) if NO T&D file present
  USES : AF,BC,DE,HL
  REQUIREMENTS: User must log desired drive before calling

 Usage: This routine is used with DateStamper(tm)-specific File
  Stamp routines only, or with routines where individual file
  stamp access is too slow.  It should be called before any
  attempt is made to access File Stamp information.  A common
  use is to set flags for mode changing between Stamp and Non-
  Stamp operations.

:RCLOCK - Read clock identified by TIMINI to specified addr

  ENTER: HL = Address of 6-byte area to receive time string
  EXIT :  A = 0, Zero Flag Set (Z) if Ok, Time String filled
	    A <> 0, Zero Flag Clear (NZ) if Error
  USES : HL,DE,BC,AF

 Usage: This routine forms a generalized Clock Read for ZSDOS,
  DateStamper or CP/M Plus clocks identified by TIMINI.  It
  reads clock data to the specified address in the standard
  format.  Since CP/M Plus does not return a valid read flag,
  the status is always assumed to be True, for a good read.
  Note: You must insure that a valid clock is installed and
  working before calling this routine.

Example:
	EXT	TIMINI,RCLOCK	; Always declare both routines
	...			; preliminary code
	CALL	TIMINI		; Initialize and identify clock
	...			; other program code
	LD	HL,TIMSTR	; Place the time here
	CALL	RCLOCK		; and read the clock
	JR	NZ,BADCLK	; Jump if error reading clock
	...			; else proceed to use it
 TIMSTR: DEFS	6		; Date/Time: YY MM DD HH MM SS

RDCLK - Read DateStamper(tm) clock to specified buffer

  ENTER: HL = Pointer to 6-byte buffer location
  EXIT : HL = Pointer to last byte of Date/Time string if Ok
	  A <> 0, Zero Flag Clear (NZ) if Ok
	    A = 0, Zero Set (Z), HL = 0 if Bad Clock Read
  USES : AF,BC,DE,HL
  REQUIREMENTS:  FINDCK must have been previously called.

 Usage: This routine is used to read a DateStamper(tm)-specific
  clock.  Date and Time information is returned in the same
  format as other routines in this library.

Example:
	EXT	RDCLK,FINDCK	; Declare the routine
	...			; initial program code
	CALL	FINDCK		; Call this early in program
	...			; intervening program code
	LD	HL,TIMSTR	; Set addr for 6-byte buffer
	CALL	RDCLK		; Read the clock.
	JR	Z,NOGOOD	; jump if bad read
:		   File Stamp Routines 

GSTAMP - Return File Date Stamp data for specified file
PSTAMP - Set File Date Stamp data for specified file

  ENTER: DE = Pointer to FCB for file of interest
	 HL = Pointer to 15-byte buffer for/with Stamp data
  EXIT :  A <> 0 Zero Flag Clear (NZ) if Operation Successful
            A = 0, Zero Flag Set (Z) on Error
  USES : AF,BC,HL
  SIDE EFFECTS: Current DMA address is altered by this routine.
  REQUIREMENTS: TIMINI must have been called to set global
	variables.  Drive and User area for the specified file
	must be set prior to calling either of these routines.

 Usage: These routines are recommended for File Stamp access in
  CP/M-compatible systems.  They use the DOSTYP and TIMTYP
  variables to determine stamp method in effect, and will read
  and write File Stamps under ZSDOS and DateStamper with CP/M
  2.2 or ZRDOS, and will read stamps from CP/M Plus (CP/M 3.x).
Example:
	EXT	GSTAMP,PSTAMP,TIMINI	; Declare routines
	...			; preceding code
	CALL	TIMINI		; Set the Time sybsystem early
	...			; other program code
	CALL	SETFCB		; Set an FCB to a desired file
	LD	DE,FCB		; point to it
	LD	HL,TBUFF	; and to buffer for Stamps
	CALL	GSTAMP		; Get stamp for this file
	JR	Z,NOSTAMP	; go to error handler if bad
	...			; Use the data
	CALL	SETDAT		; Set stamp data in buffer
	LD	DE,FCB		; point to FCB for file
	LD	HL,TBUFF	; and to buffer with Stamps
	CALL	PSTAMP		; Stamp file with TBUFF values
	JR	Z,NOSTAMP	; jump Error if bad return
	...			; Else carry on.

 FCB:	DEFS	36		; FCB for file of interest
 TBUFF:	DEFS	15		; Buffer for Stamp data
GETTD - Get DateStamper(tm) File Stamp for specified file

  ENTER:  A - Contains T&D Sector Index (0..7) (from FSTNXT)
	 DE - Contains Random Record Number    (from FSTNXT)
	 HL = Pointer to 15-byte buffer for Date/Time info
  EXIT :  A <> 0, Zero Flag Clear (NZ) if OK
	    A = 0, Zero Set (Z) if No File or Read Error
  USES : AF,BC,DE,HL
  REQUIREMENTS: User must log onto drive containg File & Stamp
  SIDE EFFECTS: DMA is altered by this routine

 Usage: This is a DateStamper(tm)-specific routine returning
  file stamp data for a file using FSTNXT call parameters.

Example:
	EXT	GETTD		; Declare the routine
	...			; check DateStamper
	...			; Log drive, Call FSTNXT
	LD	HL,USRDAT	; Put 15-byte Stamp data here
	CALL	GETTD		; Fill in destination string
	JR	Z,NODATA	; jump if bad/no stamp
	...			; Else process the stamp
SETTD - Set DateStamper File Stamp into for specified file.

  ENTER:  A - Contains T&D Sector Index (0..7) (from FSTNXT)
	 DE - Contains Random Record Number    (from FSTNXT)
	 HL = Pointer to Stamp data in 15-byte buffer
  EXIT :  A <> 0, Zero Flag Clear (NZ) if OK
	    A = 0, Zero Set (Z) if No File or Read Error
  USES : AF,BC,DE,HL
  REQUIREMENTS: You must log onto drive containing file & Stamp
  SIDE EFFECTS: DMA is altered by this routine

 Usage: This DateStamper(tm)-specific routine sets File Stamp
  data for a specified file to user-supplied values.

Example:
	EXT	SETTD		; Declare the routine
	...			; Validate DateStamper
	...			; log drive, call FSTNXT
	LD	HL,USRDAT	; Point to 15-byte Stamp field
	CALL	SETTD		; Set DateStamper File Stamp
	JR	Z,BADSET	; jump if if Error
	...			; Else carry on!
::DSLIB1.HLP
:U2PTIM - Convert ZSDOS/DateStamper Time to P2DOS (CP/M Plus)

  ENTER: DE = Points to Universal Time string (Source)
	 HL = Points to P2DOS Time string (Destination)
  EXIT :  A = 0, Zero Set (Z) if Ok, Dest time set (less secs)
	    A <> 0, Zero Clear (NZ) if error, Dest zeroed
	 DE = Pointer to Secs byte in Source string (not moved)
	 HL = Pointer to Secs byte in Dest string (not filled)
  USES : HL,DE,BC,AF

 Usage: Utility conversion of Time from ZSDOS/DateStamper(tm)
  to CP/M Plus type.  Only the Date, Hour and Minute fields are
  converted, but registers are returned such that a single LDI
  move instruction after the routine will move any seconds
  information.  Years 78-99 are assumed to be 1978-1999, 0-77
  as 2000-2077.  This routine would commonly be used in
  programs such as Library Utilities which internally use a
  CP/M Plus type of stamp.

Example:
	EXT	U2PTIM		; Declare the variable
	...			; Read a clock or stamp
	LD	DE,UTIM		; Set source time spec address
	LD	HL,PTIM		; ..and dest time spec addr
	CALL	U2PTIM		; Do the conversion
	JR	NZ,ERROR	; ..jump if conversion error
	...			; Else use the P2DOS string

P2UTIM - Convert P2DOS (CP/M Plus) Time spec to Standard

  ENTER: HL = Points to P2DOS (CP/M Plus) Time string (Source)
	 DE = Points to Universal Time string (Destination)
  EXIT :  A = 0, Zero Set (Z), Dest string filled (less secs)
		Errors only due to bad entry.  (Check YY=MM=0)
	 HL = Points to Secs byte in Source string (Not moved)
	 DE = Points to Secs byte in Dest string (not filled)
  USES : HL,DE,BC,AF

 Usage: Commonly used to provide interface from CP/M Plus
  systems to CP/M 2.2, or in Library Utility routines to
  provide time interface.  Source stamp is P2DOS (CP/M Plus
  compatible), destination is ZSDOS/DateStamper(tm) standard.
  A single LDI move instruction after conversion will move the
  seconds byte.  Only dates from 1 Jan 1978 thru 31 Dec 2077
  will be properly converted.  Other dates will set Year and
  Month bytes to zero.  Check this state for error condition.

Example:
	EXT	P2UTIM		; Declare the variable
	...			; Read a clock or Stamp
	LD	DE,UTIM		; Point to the Dest string
	LD	HL,PTIM		; .and the Source string
	CALL	P2UTIM		; Do the conversion
	LDI			; Move the seconds (if desired)
	LD	HL,UTIM		; Check for errors
	LD	A,(HL)		; Get years byte
	INC	HL		; ..advance to Months
	OR	L		; ...and check for errors
	JR	Z,ERROR		; Jump if error
	...			; ..continue on
U2MTIM - Convert Universal Time Spec to MS-DOS/DosDisk(tm)

  ENTER: DE = Points to Universal Time string (Source)
	 HL = Points to MS-DOS format Time string (Destination)
  EXIT :  A = 0, Zero Set (Z) if Ok, Dest time set (less secs)
	    A <> 0, Zero Clear (NZ) if error, Dest str zeroed
	 DE = Pointer to Secs byte in Source string (not moved)
	 HL = Pointer to High-order time byte in MS-DOS field
		(low-order byte has secs field nulled)
  USES : HL,DE,BC,AF

 Usage: Commonly used to convert from internal time format to
  External form for writing to MS-DOS disk formats.  Conversion
  of seconds data to the format used in the MS-DOS Time spec is
  a user program responsibility.  Dates from 1 January 1980 to
  31 December 2077 will be properly converted.

Example:
	EXT	U2MTIM		; Declare the variable
	...			; Read a clock or stamp
	LD	DE,UTIM		; Source time spec string addr
	LD	HL,MTIM		; ..dest time spec string addr
	CALL	U2MTIM		; Do the conversion
	JR	NZ,ERROR	; ..jump if conversion error
	...			; Else use P2DOS string
M2UTIM - Convert MS-DOS/DosDisk(tm) Time to Universal

  ENTER: HL = Points to MS-DOS Time string (Source)
	 DE = Points to Universal Time string (Destination)
  EXIT :  A = 0, Zero Set (Z), Dest string filled (less secs)
	    A <> 0, Zero Clear (NZ) if Error, Dest Nulled
	 HL = Points to Second (hi-order) byte in MS-DOS string
	 DE = Points to Secs byte in Dest string (not filled)
  USES : HL,DE,BC,AF

 Usage: Commonly used to convert MS-DOS time to internal format
  for internal program manipulation.  Conversion of seconds is
  your responsibility.  Dates from 1 Jan 1980 thru 31 Dec 2077
  will be properly converted.  Others produce null date.

Example:
	EXT	M2UTIM		; Declare the variable
	...			; Read a clock or stamp
	LD	DE,UTIM		; Point to the Dest string
	LD	HL,MTIM		; ..and the Source string
	CALL	M2UTIM		; Do the conversion
	JR	NZ,ERROR	; ..handle error if bad
	...			; Else convert secs & continue

:BCD2BIN - Convert Binary Coded Decimal (BCD) byte to binary

  ENTER: A = BCD digit to convert (0-99 value)
  EXIT : A = binary byte representation of digit(s) (00-63H)
  USES : AF

 Usage: This routine is primarily used in conversions of dates
  used by DSLIB routines but is available for other uses.  It
  converts a packed BCD byte in the range of 0 to 99 to a
  binary byte of 0..63H.

BIN2BCD - Convert binary byte to packed BCD.

  ENTER: A = Binary digit to convert (00-63H, 0-99 decimal)
  EXIT : A = Packed BCD byte (1 or 2 digits)
  USES : AF

 Usage: This routine is commonly used to convert bytes in the
  range of 0-99 (00-63H) to a packed BCD byte.  It is primarily
  used in date conversion routines in DSLIB but is available
  for other uses.

DVERS - Return the DSLIB version number

  ENTER: None
  EXIT : HL - Contains the Version Number (H=major, L=minor)
  USES : HL.  Other registers unaffected

 Usage: This routine is most often used for control or
  debugging purposes to embed the linked library version.

::DSLIB2.HLP
