ZSLIB Version 2.1 Documentation February 2, 1990 by Carson Wilson One of the most attractive features of ZSDOS from a programming point of view is built-in file datestamping. For the first time, a standard set of functions has been implemented which make file datestamp maintenance fast, transparent, and secure. ZSLIB provides assembly language programs with the low-level tools to handle most routine datestamp tasks under ZSDOS. Several parallel routines for CP/M Plus have also been added in the interest of maintaining program compatibility with that system. For a demonstration of the ZSLIB routines under ZSDOS or CP/M Plus, run the ZSLIBDEM program included in this package by typing "ZSLIBDEM //". I have provided ZSLIB in two library formats: the standard Microsoft library format and the newer and faster SLR format. I have named the SLR format library ZSLIB21S to signify the SLR format; the Microsoft format version is named ZSLIB21M. ZSLIB is designed to work along with SYSLIB to provide standard assembly language interfaces and maximize efficiency by removing redundant code. Therefore, several of ZSLIB's routines, like those of Z3LIB and VLIB, reference SYSLIB routines, requiring that SYSLIB be linked to the program after ZSLIB. Except where otherwise specified, all code is copyright 1989, 1990 by Carson Wilson, all rights reserved. These routines are released for non-commercial use. Any commercial use of ZSLIB, defined as any situation where the duplicator receives revenue by duplicating or distributing ZSLIB by itself or in conjunction with any hardware or software product, is expressly prohibited unless authorized in writing by Carson Wilson. You may redistribute ZSLIB20.LBR in its present form only. I encourage you to explore the source code, suggest improvements, and document errors. However, please obtain permission from me before redistributing any of these files in altered form. Although I use these routines in my own programs and have made every effort to make them as reliable as possible, I cannot guarantee that they are completely free of errors. Please be on the lookout for mistakes in the source code, and notify me so that I can update the library and prevent others from encountering them. Carson Wilson may be reached via Antelope Freeway Remote Access System, Chicago Chicago, 312/764-5162 300-1200-2400 Baud, 24 Hours Unregistered callers may leave messages for me in their new user application, as I am sysop of Antelope Freeway. The following briefly describes the functions performed by the separate ZSLIB modules. Calling any of the routines in a module as an external automatically adds all other routines in the module to the program's code. For example, calling PHL2DC below automatically includes PHL4DC, PHL5DC, PHLDC, and the SYSLIB routine COUT. For assembly language examples which use the ZSLIB routines, see the ZSLIBDEM program, or my DIFF30.LBR, CPA12.LBR, or NT44.LBR. ------------------------------------------------------------------ Module: BCD2JUL Prog Size 0058 Data Size 0000 Public Symbols Defined: BCD2JUL BIN2JUL External Symbols Referenced: DPERMO JBCD2BN Authors: Bridger Mitchell & Howard Goldstein. BCD2JUL - BCD to Julian date routine. Entry: points to date expressed as yy mm dd in BCD. Exit: contains Julian date in binary (1/1/1978 = 1). Uses: . Notes: If the year is less than 1978 this routine wraps to the next century. This routine covers dates from 1/1/1978 through 12/31/2077. BIN2JUL - Binary to Julian Date routine. Entry: points to date expressed as yy mm dd in binary. Exit: contains Julian date in binary (1/1/78 = 1). Uses: . ------------------------------------------------------------------ Module: JBCD2BN Prog Size 0012 Data Size 0000 Public Symbols Defined: JBCD2BN External Symbols Referenced: None Authors: Bridger Mitchell & Howard Goldstein. JBCD2BN - BCD to Binary digit routine. Entry: in BCD. Exit: in binary. Uses: , ..pa ------------------------------------------------------------------ Module: JUL2BIN Prog Size 0037 Data Size 0000 Public Symbols Defined: JUL2BIN External Symbols Referenced: DPERMO Authors: Bridger Mitchell & Howard Goldstein. JUL2BIN - Julian to binary date routine. Entry: = Days since 12/31/1977 (Julian date). Exit: = Binary month (1=Jan...). = Binary year (78...). = Binary day (1...31). = . Uses: ,,. ------------------------------------------------------------------ Module: SB2H Prog Size 000D Data Size 0000 Public Symbols Defined: @B2HH @B2HL External Symbols Referenced: None @B2HH - Convert the high nybble of a byte to a hexidecimal digit in ASCII. Entry: - contains byte in high nybble. Exit: - contains hexidecimal equivalent in ASCII. Uses: . Examples: if A contains 2B hex on entry, A will contain the ASCII character '2' on exit. @B2HL - Convert the low nybble of a byte to a hexidecimal digit in ASCII. Entry: - contains byte in low nybble. Exit: - contains hexidecimal equivalent in ASCII. Uses: . Examples: if A contains 2B hex on entry, A will contain the ASCII character 'B' on exit. ------------------------------------------------------------------ Module: SMHL5DC+ Prog Size 0073 Data Size 0000 Public Symbols Defined: MHL2DC MHL4DC MHL5DC MHLDC External Symbols Referenced: MOUT MHL2DC -- Store HL as 2 decimal characters. On return DE points to byte following buffer. MHL4DC -- Store HL as 4 decimal characters. On return DE points to byte following buffer. MHL5DC -- Store HL as 5 decimal characters. On return DE points to byte following buffer. MHLDC -- Store HL as decimal characters w/leading spaces in 5- char field. On return DE points to byte following buffer. Notes: For examples of output, see SPHL5DC+, below. ------------------------------------------------------------------ Module: SPHL5DC+ Prog Size 005D Data Size 0000 Public Symbols Defined: PHL2DC PHL4DC PHL5DC PHLDC External Symbols Referenced: COUT Notes: This is my enhancement of Richard Conn's SPHL5DC module which adds routines to print the value in HL as 2 and 4 decimal characters. Useful when displaying user areas and relative date stamps. PHL2DC - Print number as 2 decimal characters with leading zeroes. Entry: - contains number to print Exit: Number printed. Uses: None. Examples: "00" "01" "10" PHL4DC - Print number as 4 decimal characters with leading zeroes. Entry: - contains number to print Exit: Number printed. Uses: None. Examples: "0000" "0001" "0010" PHL5DC - Print number as 5 decimal characters with leading zeroes. Entry: - contains number to print Exit: Number printed. Uses: None. Examples: "00000" "00001" "00010" PHLDC - Print number as up to five decimal characters with leading spaces in 5-char field. Entry: - contains number to print Exit: Number printed with leading spaces. Uses: None. Examples: " 0" " 1" " 10" ------------------------------------------------------------------ Module: ZSBINBCD Prog Size 0013 Data Size 0000 Public Symbols Defined: BINBCD External Symbols Referenced: None BINBCD - Convert binary number to BCD. Entry: - contains binary number. Exit: - contains BCD number. Uses: . Notes: Adapted from BYE510.ASM. ------------------------------------------------------------------ Module: ZSDOSTYP Prog Size 001F Data Size 0002 Public Symbols Defined: CPMVER DOSTYP DOSVER External Symbols Referenced: None DOSTYP - Determine BDOS type. Entry: None. Exit: - Zero flag reset (NZ) if extended BDOS present. - Contains extended BDOS identifier, or 0FFh if none. (CPMVER) - Contains the CP/M version (22h = CP/M 2.2). Uses: . Notes: For convenience, (DOSVER) = A on exit. The only extended BDOS identifiers currently in use are: 0 - ZRDOS 'S' - ZSDOS 'D' - ZDDOS ------------------------------------------------------------------ Module: ZSGSSTP Prog Size 0053 Data Size 0027 Public Symbols Defined: GETSTP SETSTP External Symbols Referenced: DOSTYP GETSTP - Get ZSDOS file datestamp to 128-byte buffer. Entry: - points to file's FCB. - points to 128-byte datestamp buffer. Exit: - Zero flag set (Z) and A=0 if buffer filled, - Zero flag reset (NZ) if error. Uses: . Notes: Buffer is filled with 15-byte datestamp as yy,mm,dd,hh,min of file creation, last access, and last modification, respectively. If file is not at default drive, FCB must be initialized with drive. If file is not at default user, FCB must be initialized with user number and ZSDOS error mode set to non-zero. SETSTP - Set file datestamp from 128-byte buffer Entry: - points to file's FCB. - points to 128-byte datestamp buffer. Exit: - Zero flag set (Z) and A=0 if file stamped, - Zero flag reset (NZ) if error. Uses: . Notes: See GETSTP, above. ------------------------------------------------------------------ Module: ZSGSTIME Prog Size 0020 Data Size 0000 Public Symbols Defined: GETTIM SETTIM External Symbols Referenced: DOSTYP GETTIM - Get current ZSDOS time to 6-byte BCD buffer. Entry: - points to 6-byte time buffer. Exit: - Zero flag set (Z) and A=0 if buffer filled, - Zero flag reset (NZ) if error. Uses: . Notes: Time expressed as yy,mm,dd,hh,min,ss. SETTIM - Set current ZSDOS time from 6-byte BCD buffer. Entry: - points to 6-byte time buffer. Exit: - Zero flag set (Z) and A=0 if clock set, - Zero flag reset (NZ) if error. Uses: . Notes: See GETTIM, above. ------------------------------------------------------------------ Module: ZSGSTIMP Prog Size 0060 Data Size 0000 Public Symbols Defined: GTIMEP STIMEP External Symbols Referenced: BCD2JUL BINBCD CPMVER DOSTYP JUL2BIN GTIMEP - Get current CP/M Plus time to 6-byte BCD buffer. Entry: - points to 6-byte time buffer. Exit: - Zero flag set (Z) and A=0 if buffer filled, - Zero flag reset (NZ) if error. Uses: . Notes: Time expressed as yy,mm,dd,hh,min,ss. STIMEP - Set current CP/M Plus time from 6-byte BCD buffer. Entry: - points to 6-byte time buffer. Exit: - Zero flag set (Z) and A=0 if clock set, - Zero flag reset (NZ) if error. Uses: . Notes: See GTIMEP, above. ------------------------------------------------------------------ Module: ZSGSTPCP Prog Size 0090 Data Size 0024 Public Symbols Defined: GSTPCP External Symbols Referenced: BINBCD CPMVER DOSTYP JUL2BIN GSTPCP - Get file datestamp from CP/M Plus to 128-byte buffer. Entry: - points to file's FCB. - points to 128-byte datestamp buffer. Exit: - Zero flag set (Z) and A=0 if buffer filled, - Zero flag reset (NZ) if error. Uses: . Notes: If file is not at default drive, FCB must be initialized with drive. File must be at default user. File stamp is converted to DateStamper format (yy,mm,dd,hh,min of file creation, last access, and last modification, respectively, in BCD). The CP/M Plus create/access stamp is copied to both the create and access fields of the caller's buffer. The calling program must examine the disk label to determine which field(s) are valid. On exit, only the first 15 bytes of data in the caller's buffer are valid. ------------------------------------------------------------------ Module: ZSISBCDD Prog Size 0048 Data Size 0000 Public Symbols Defined: ISBCDD ISBCD External Symbols Referenced: None. ISBCDD - Test BCD date/time at HL for validity Enter: - points to possible YY,MM,DD,hh,mm in BCD. Exit: (Z) means date/time ok: A = '*' (2Ah) if wildcards used. A = 00h if no wildcards used. (NZ) and = 0FFh means date/time invalid Uses: ISBCD - Test if byte in A is BCD Enter: holds byte to test Exit: (C) means byte is BCD (NC) means byte is invalid< Uses: ------------------------------------------------------------------ Module: ZSLIBVER Prog Size 0000 Data Size 0000 Public Symbols Defined: VERSxx External Symbols Referenced: None. VERSxx - Last two characters are the ZSLIB version (viewable with a librarian). ------------------------------------------------------------------ Module: ZSMAFHC Prog Size 0013 Data Size 0000 Public Symbols Defined: MAFHC External Symbols Referenced: @B2HH @B2HL MOUT MAFHC - Store A as up to 2 hex characters to memory at DE. Entry: - Contains number to be stored - points to memory area (2 bytes max.) Exit: - points to byte after output. Uses: . ------------------------------------------------------------------ Module: ZSMAHC Prog Size 0017 Data Size 0000 Public Symbols Defined: MAHC External Symbols Referenced: @B2HH @B2HL MOUT MAHC - Store A as up to 2 hex characters with leading spaces to memory at DE. Entry: - contains value to put. - points to memory area (2 bytes max.) Exit: - points to byte after output. Uses: . ------------------------------------------------------------------ Module: ZSMDAT1 Prog Size 00B2 Data Size 0000 Public Symbols Defined: MDAT1 External Symbols Referenced: MA2HC MAFHC MOUT MSTR MDAT1 - Store long form of date, e.g., "March 2, 1988" to memory at DE Entry: - points to date as BCD yy mm dd. - points to memory (18 bytes max.) Exit: - points to byte after output. Uses: - . ------------------------------------------------------------------ Module: ZSMDAT2 Prog Size 0059 Data Size 0000 Public Symbols Defined: MDAT2 External Symbols Referenced: MA2HC MAHC MOUT MDAT2 - Store intermediate form of date, e.g., " 2 Mar 88" to memory at DE. Entry: - points to date as BCD yy mm dd. - points to (9 bytes). Exit: - points to byte after output. Uses: - . ------------------------------------------------------------------ Module: ZSMDAT3 Prog Size 0021 Data Size 0000 Public Symbols Defined: MDAT3 External Symbols Referenced: MA2HC MOUT MDAT3 - Store short form of date, e.g., "03/02/88" to memory at DE. Entry: - points to date as BCD yy mm dd. - points to memory (8 bytes). Exit: - points to byte after output. Uses: - . ------------------------------------------------------------------ Module: ZSMOUT Prog Size 0003 Data Size 0000 Public Symbols Defined: MOUT External Symbols Referenced: MOUT - Store A to memory at DE. Entry: - contains value to store. - points to memory area (1 byte) Exit: - points to byte after output. Uses: . ------------------------------------------------------------------ Module: ZSMSTR Prog Size 000D Data Size 0000 Public Symbols Defined: MSTR External Symbols Referenced: MOUT MSTR - Store zero-terminated string at HL to memory at DE Entry: - points to 0-terminated string. - points to memory area for output. Exit: - points to byte after output. - points to byte following the terminating 0. Uses: , . ------------------------------------------------------------------ Module: ZSMTIMC1 Prog Size 0046 Data Size 0000 Public Symbols Defined: MTIMC1 External Symbols Referenced: MA2HC MHL4DC MOUT MTIMC1 - Store civilian time as "hh:mm ", or "hh:mmp" if p.m. to memory at DE. Store relative time as "+nnnn " to memory at DE. Entry: - points to date as BCD yy mm dd hh mm - points to memory (6 bytes) Exit: - points to byte after output Uses: - ------------------------------------------------------------------ Module: ZSMTIMC2 Prog Size 0046 Data Size 0000 Public Symbols Defined: MTIMC2 External Symbols Referenced: MA2HC MAHC MHL4DC MOUT MTIMC2 - Store civilian time as "hh:mm " or " h:mm " if a.m., "hh:mmp" or " h:mmp" if p.m., to memory at DE. Store relative time as "+nnnn " to memory at DE. Entry: - points to date as BCD yy mm dd hh mm - points to memory (6 bytes) Exit: - points to byte after output. Uses: - ------------------------------------------------------------------ Module: ZSMTIMC3 Prog Size 0046 Data Size 0000 Public Symbols Defined: MTIMC3 External Symbols Referenced: MA2HC MAFHC MHL4DC MOUT MTIMC3 - Store civilian time as "hh:mm " or "h:mm " if a.m., "hh:mmp" or "h:mmp" if p.m., to memory at DE. Store relative time as "+nnnn " to memory at DE. Entry: - points to date as BCD yy mm dd hh mm - points to memory (6 bytes max.) Exit: - points to byte following output Uses: - ------------------------------------------------------------------ Module: ZSMTIMM1 Prog Size 002C Data Size 0000 Public Symbols Defined: MTIMM1 External Symbols Referenced: MA2HC MHL4DC MOUT MTIMM1 - Store military time as "hh:mm" to memory at DE. Store relative time as "+nnnn" to memory at DE. Entry: - points to date as BCD yy mm dd hh mm - points to memory (5 bytes). Exit: - points to byte after output. Uses: - . ------------------------------------------------------------------ Module: ZSMTIMM2 Prog Size 002A Data Size 0000 Public Symbols Defined: MTIMM2 External Symbols Referenced: MA2HC MAHC MHL4DC MOUT MTIMM2 - Store military time as "hh:mm" or " h:mm" Store relative time as "+nnnn". Entry: - points to date as BCD yy mm dd hh mm - points to memory (5 bytes). Exit: - points to byte after output. Uses: - ..pa ------------------------------------------------------------------ Module: ZSMTIMM3 Prog Size 002A Data Size 0000 Public Symbols Defined: MTIMM3 External Symbols Referenced: MA2HC MAFHC MHL4DC MOUT MTIMM3 - Store military time as "hh:mm" or "h:mm" Store relative time as "+nnnn". Entry: - points to date as BCD yy mm dd hh mm - points to memory (5 bytes). Exit: - points to byte following output. Uses: - . ------------------------------------------------------------------ Module: ZSPAFHC Prog Size 0013 Data Size 0000 Public Symbols Defined: PAFHC External Symbols Referenced: @B2HH @B2HL COUT PAFHC - Print number as up to 2 hex characters. Entry: - Contains number to be printed. Exit: Number printed to screen as 1 or 2 hex chars. Uses: None. ------------------------------------------------------------------ Module: ZSPAHC Prog Size 0017 Data Size 0000 Public Symbols Defined: PAHC External Symbols Referenced: @B2HH @B2HL COUT PAHC - Print number as up to 2 hex characters with leading spaces. Entry: - Contains number to be printed. Exit: Number printed. Uses: None. ------------------------------------------------------------------ Module: ZSPARSDS Prog Size 009C Data Size 0000 Public Symbols Defined: PARSDS External Symbols Referenced: EVAL10 EVAL16 ISBCDD PARSDS - Parse command line datespec. Entry: - points to null-terminated datespec (14 characters or less). - points to memory area (5 bytes). Exit: (Z) if memory at DE initialized to BCD date/time: A = '*' (2Ah) if wildcards used. A = 00h if no wildcards used. (NZ) and A = 0FFh if entry or parsed datespec was invalid (out of range). Uses: . Notes: The command line datespec takes the following forms: [dd[.mm[.yy[ hh[:mm]]]]] - real time OR [dd[.mm[.yy[ +nnnn]]]] - relative time All items in square brackets are optional. Each date or time item may be two ASCII digits or less. If no digits are entered, the entry buffer values are checked for validity and returned. Wildcards ("*", "?", or "??") are also allowed. If wildcards are detected, they are stored as ASCII "*" (2A hex) and A = 2A hex on return. ------------------------------------------------------------------ Module: ZSPRDAT1 Prog Size 00B2 Data Size 0000 Public Symbols Defined: PRDAT1 External Symbols Referenced: COUT PA2HC PAFHC PSTR PRDAT1 - Print long form of date, e.g., "March 2, 1988". Entry: - points to date as BCD yy mm dd. Exit: - Zero flag set (Z) and A=0 if date printed, - Zero flag reset (NZ) and A=0FFh if day was out of range 1..31h. Uses: . ------------------------------------------------------------------ Module: ZSPRDAT2 Prog Size 0059 Data Size 0000 Public Symbols Defined: PRDAT2 External Symbols Referenced: COUT PA2HC PAHC PRDAT2 - Print intermediate form of date, e.g., " 2 Mar 88". Entry: - points to date as BCD yy mm dd. Exit: - Zero flag set (Z) and A=0 if date printed, - Zero flag reset (NZ) and A=0FFh if day was out of range 1..31h. Uses: . ------------------------------------------------------------------ Module: ZSPRDAT3 Prog Size 0021 Data Size 0000 Public Symbols Defined: PRDAT3 External Symbols Referenced: COUT PA2HC PRDAT3 - Print short form of date, e.g., "03/02/88". Entry: - points to date as BCD yy mm dd. Exit: - Zero flag set (Z) and A=0 if date printed, - Zero flag reset (NZ) and A=0FFh if day was out of range 1..31h. Uses: . ------------------------------------------------------------------ Module: ZSPTIMC1 Prog Size 0046 Data Size 0000 Public Symbols Defined: PTIMC1 External Symbols Referenced: COUT PA2HC PHL4DC PTIMC1 - Print civilian (12-hour) time as "hh:mm ", or "hh:mmp" if p.m., or print relative time as "+nnnn ". Entry: - points to date as BCD yy mm dd hh min. Exit: Time printed. Uses: None. ------------------------------------------------------------------ Module: ZSPTIMC2 Prog Size 0046 Data Size 0000 Public Symbols Defined: PTIMC2 External Symbols Referenced: COUT PA2HC PAHC PHL4DC PTIMC2 - Print civilian time with padded hours as "hh:mm " or " h:mm " if a.m., "hh:mmp" or " h:mmp" if p.m. Print relative time as "+nnnn ". Entry: - points to date as BCD yy mm dd hh min. Exit: Time printed. Uses: None. ------------------------------------------------------------------ Module: ZSPTIMC3 Prog Size 0046 Data Size 0000 Public Symbols Defined: PTIMC3 External Symbols Referenced: COUT PA2HC PAFHC PHL4DC PTIMC3 - Print civilian time with formatted hours as "hh:mm " or "h:mm " if a.m., "hh:mmp" or "h:mmp" if p.m. Print relative time as "+nnnn ". Entry: - points to date as BCD yy mm dd hh min. Exit: Time printed. Uses: None. ------------------------------------------------------------------ Module: ZSPTIMM1 Prog Size 002C Data Size 0000 Public Symbols Defined: PTIMM1 External Symbols Referenced: COUT PA2HC PHL4DC PTIMM1 - Print military (24-hour) time as "hh:mm". Print relative time as "+nnnn". Entry: - points to date as BCD yy mm dd hh min. Exit: Time printed. Uses: None. ------------------------------------------------------------------ Module: ZSPTIMM2 Prog Size 002A Data Size 0000 Public Symbols Defined: PTIMM2 External Symbols Referenced: COUT PA2HC PAHC PHL4DC PTIMM2 - Print military time with padded hours as "hh:mm" or " h:mm". Print relative time as "+nnnn". Entry: - points to date as BCD yy mm dd hh min. Exit: Time printed. Uses: None. ------------------------------------------------------------------ Module: ZSPTIMM3 Prog Size 002A Data Size 0000 Public Symbols Defined: PTIMM3 External Symbols Referenced: COUT PA2HC PAFHC PHL4DC PTIMM3 - Print military time with formatted hours as "hh:mm" or "h:mm". Print relative time as "+nnnn". Entry: - points to date as BCD yy mm dd hh min. Exit: Time printed. Uses: None. ------------------------------------------------------------------ Module: ZSSSTPCP Prog Size 02B0 Data Size 002A Public Symbols Defined: SSTPCP External Symbols Referenced: BCD2JUL CPMVER DOSTYP SSTPCP - Set file datestamp to CP/M Plus from 128-byte buffer. Entry: - points to file's FCB. - points to 128-byte datestamp buffer. - points to 1024-byte DMA buffer. Exit: - zero flag set and A=0 if stamp set. - zero flag reset (NZ) if error, error in : FF - file not found. 06 - not CP/M Plus. 05 - no stamps on disk. 04 - BIOS sector size > 1024 bytes. 03 - drive invalid. 02 - BIOS read error. 01 - BIOS write error. Uses: Notes: The datestamp buffer should be filled on entry to BCD yy,mm,dd,hh,min of file creation, last access, and last modification, respectively. If valid, (month <> 0) the BCD creation field is copied to the CP/M Plus Create/Access field. Otherwise, the BCD last access field is used, or the CP/M Plus Create/Access field is zeroed if neither are valid. Similarly, the BCD last modification field is copied to the CP/M Plus Update field, or the Update field is zeroed if the BCD stamp is invalid. The file whose stamp is to be set must either be on the current drive or at the drive specified by FCB byte 0. Only files at the current user number will be matched. To allow a reasonable interface standard, this routine will NOT work under systems configured with BIOS sectors larger than 1k. No systems exceeding this size have yet been encountered, but BIOS sectors of 2k and 4k are technically legal under CP/M Plus. No wildcards are allowed in the file's FCB. The End