CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / jsage / zsus / z3help / y.lbr / DSLIB.HLP < prev next >

Wrap

Text File | 1991-01-13 | 25.4 KB | 579 lines

Introduction (Rev 5 Jan 91) 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 : 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! :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 B6 - 1=Don't reorder recs after sort, 0=Reorder | 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 DE = Address of Pointer (Order) Table | HL = Address of first file in buffer USES : HL,DE,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, reorder | 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 DDIRNPA ; 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