CP/M/CPM_CDROM.iso/jsage/znode3/z3lib/libhl45a.lbr/DSLIB.LBR/DSLIB.HZP/DSLIB.HLP

Text File | 1993-06-07 | 15.3 KB | 389 lines

 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