ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/BEEHIVE/ZSUS/Z3HELP-2.LBR/D.LBR/DSLIB.HZP/DSLIB.HLP

Text File | 2000-06-30 | 21KB | 534 lines

 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     - FSTNXT, BCD2BIN, BIN2BCD, DVERS

 DateStamper(tm) T&D  - OPENTD, CLOSTD, RWTD
:                    
 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!
:
DDIRQS - Return sorted directory with file stamps and sizing
 
DDIRQ  - Return sorted directory with file stamps

  ENTER: HL = Address of TPA buffer start
     DE = Points to FCB entry to match directory entries
      A = Select character
        B7 - 1 = Select SYStem files
        B6 - 1 = Select Non-SYStem files
        B5 - 1 = Select All users
      C = Secondary select
        B7 - 1=Sort Type then Name, 0=Name then Type
        B0 - 1=Search DateStamper first, then DosDisk
            then P2DOS stamps; 0=Skip DateStamper
  EXIT :  A <> 0, Zero Flag Clear (NZ) if Ok,
          A = 0, Zero Set (Z) if TPA Overflow
     BC = Number of files in Sorted Directory Array
     HL = Address of first file in buffer
  USES : HL,BC,AF
  SIDE EFFECT: Dos DMA Address is set to 80H

 Usage: These routines provide a replacement for the SYSLIB
  routines DIRQS and DIRQ.  File Stamps are automatically
  appended to Directory data from DateStamper(tm), P2DOS (CP/M
  Plus), and Plu*Perfect Systems' DosDisk.  The Last Access
  field is nulled in P2DOS, and the single DosDisk stamp is
  returned in the Last Modified field.  Each entry is 31 char-
  acters long (16 for file entry, 15 for stamp).

Example:
    EXT    DDIRQS        ; ..or DDIRQ.  DON'T use both
    ...
    CALL    CODEND        ; Get lower TPA value in HL
    LD    DE,MYFCB    ; Match this file spec
    LD    C,01H        ; Sort Name/Type, DS first
    LD    A,0E0H        ; SYS & Non-SYS, all user areas
    CALL    DDIRQS        ; Do the call (or to DDIRQ)
    JP    Z,ERROR        ; ..error if not enough space
    LD    A,B        ; Do we have any files?
    OR    C        ; ..BC has number of files
    JP    Z,NOFILS    ; Jump if no files in array
    ...            ; ..use the files in the array

 MYFCB:    DEFB    0,'???????????',0,0,0,0        ; FCB to match
    DEFB    0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0


DDIRNPAK - Negate selection markings in Directory Buffer

  ENTER: HL = Points to Directory Buffer from DDIRQ/DDIRQS
     BC = Number of entries in the Buffer
  EXIT : BC = Number of entries in Buffer after select/packing
  USES : BC

 Usage: This routine is used to delete file entries from DDIRQS
  or DDIRQ directory routines.  Upon completion, only entries
  previously unmarked remain, and the table is compressed to
  only these entries. This is similar to the SYSLIB routine
  DIRNPAK, but tailored to Time/Date Stamped Directory lists.

Example:
    EXT    DDIRNPAK    ; Declare the routine
    ...            ; Build dir table (DDIRQ(S))
    ...            ; ..and select entries
    LD    HL,(BUFF)    ; Buffer start (DDIRQ/DDIRQS)
    LD    BC,(COUNT)    ; ..# of entries (DDIRQ/DDIRQS)
    CALL    DDIRNPAK    ; Keep unselected & pack Buffer
    ...            ; ..continue w/ new file count


DDIRPAK - Pack Directory Buffer from DDIRQ/DDIRQS

  ENTER: HL = Points to Directory Buffer from DDIRQ/DDIRQS
     BC = Number of entries in the Buffer
  EXIT : BC = New Number of Buffer entries after select/pack
  USES : BC

 Usage: Compress File ID array from Directory Sort routine
  retaining only marked file entries.  This routine is similar
  to the SYSLIB routine DIRPAK, but functions with Time/Date
  Stamped Directory lists.

Example:
    EXT    DDIRPAK        ; Declare the routine
    ...            ; build dir tbl (DDIRQ/DDIRQS)
    ...            ; ..and select entries
    LD    HL,(BUFF)    ; Buffer start (DDIRQ/DDIRQS)
    LD    BC,(COUNT)    ; ..# of entries (DDIRQ/DDIRQS)
    CALL    DDIRPAK        ; Keep selected entries & pack
    ...            ; ..continue w/new file count


DDIRSEL - Select entries from DDIRQ/DDIRQS Directory Buffer

  ENTER: HL = Points to Directory Buffer from DDIRQ/DDIRQS
     DE = FCB entry to select against
     BC = Number of entries in the Buffer
      A = Select flag: Bit 7 - Select Non-SYStem files
               Bit 6 - Select SYStem files
               Bit 5 - Select All Users
               Bits 4..0 - User Number
  EXIT : None.  Selected files are marked
  USES : None

 Usage: Select file entries by setting the MSB of the first
  byte (User #) based on file name and type in FCB, and
  selection flags.  This routine is similar to the SYSLIB
  routine DIRSEL, but accomodates Time/Date Stamped Directory
  lists.

Example:
    EXT    DDIRSEL        ; Declare the routine
    ...            ; Build Dir (DDIRQ/DDIRQS)
    LD    HL,(BUFF)    ; Buffer start (DDIRQ/DDIRQS)
    LD    DE,MYFCB    ; .FCB criteria for selection
    LD    BC,(COUNT)    ; ..and # entries (from DDIRQ)
    LD    A,01100000B    ; SYS files in All User Areas
    CALL    DDIRSEL        ; Mark matching entries
    ...            ; ..continue on
:
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

:
FSTNXT - File search returning DateStamper(tm) Indices

  ENTER:  C - Search First (17) or Search Next (18) DOS command
     DE - Points to FCB containg the target Filename.type
  EXIT :  A = Dir Index (0..3), Carry Flag Clear (NC) If Found
          A indeterminate, Carry Flag Set (C) If NOT Found
     DE - Contains random Sector number in !!!TIME&.DAT
      B - Index into T&D sector (0..7)
  USES : AF,BC,DE,HL
  REQUIREMENTS: User must log Drive and User before calling

 Usage: This routine is used in DateStamper-specific systems to
  perform File searches and return indices into the Time & Date
  file.  Use this call for Function 17 and 18 Search calls in
  lieu of a direct call to the BDOS vector at location 5.

Example:
    EXT    FSTNXT        ; Declare the routine
    ...            ; Log Drive/User & Set FCB
    LD    C,17        ; Set for Search First command
    LD    DE,FCB        ; ..addr FCB for desired name
    CALL    FSTNXT        ; Search for the desired file
    JR    NC,FOUND    ; ..jump if file found
    ...            ; Else do not found things


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.

:
OPENTD - Open DateStamper(tm) Time & Date file for Read/Write

  ENTER: A = 0 for Read, A = 0FFH for Write
  EXIT : A <> 0, Zero Flag Clear (NZ) if OK
         A = 0, Zero Flag Set (Z) if Open Error
  USES : AF,BC,DE,HL
  REQUIREMENTS: You must select the drive before calling

 Usage: This DateStamper-specific routine is used to access
  large numbers of stamps, or where performance penalties in
  per-file stamp accesses are undesireable.  This routine Opens
  the TIME&DAT file in User 0 on the current drive.  If opened
  for writing, the R/O attribute is cleared.  The User Number
  is restored on exit.


CLOSTD - Close DateStamper(tm) Time & Date file

  ENTER: None
  EXIT : A <> 0, Zero Flag Clear (NZ) if OK
         A = 0, Zero flag Set (Z) if Error
  USES : AF,BC,DE,HL

 Usage: This DateStamper-specific routine closes the TIME&DAT
  file in user 0 of current drive, and sets the R/O bit.  It is
  used in conjunction with OPENTD above.


RWTD - Read or write to Time & Date file on current drive.

  ENTER:  A = 0 to Read, A = 0FFH to Write
     DE - Contains Random Record to Read or Write
  EXIT : HL - Addresses the start of T&D sector Read/Written
      A <> 0, Zero Flag Clear (NZ) if OK
          A = 0, Zero Flag Set (Z) if Error
  USES : AF,BC,DE,HL and BDOS DMA Address

 Usage: DateStamper(tm)-specific routine normally used only for
  Directory list, Catalog or Archive programs where access to
  blocks of Date Stamps is desired.
  
NOTE: You must reset DMA address after call if needed.

Example:
    EXT    RWTD        ; Declare the routine
    ...            ; Log drive, Set DMA addr
    LD    DE,(RECNUM)    ; Get T&D Rec # from FSTNXT or
                ; ..specified Random rec number
    LD    A,MODE        ; A=0 for read, A=FF for write
    CALL    RWTD        ; Perform the action
    JR    NZ,RWOK        ; ..jump if OK
    ...            ; Else perform error activity
 RWOK:    ...            ; Sector has been read/written