home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / ENTERPRS / CPM / UTILS / S / Z80DOS10.ARC / Z80DPROG.NOT < prev    next >
Text File  |  1989-09-15  |  14KB  |  324 lines
  1.  
  2.                - Programming Notes for Z80DOS -
  3.  
  4.                    October 1, 1987
  5.                       by
  6.                 Carson Wilson
  7.  
  8.  
  9.  
  10.                    CONTENTS
  11.  
  12.  
  13.       1.  Format of date/time stamps under Z80DOS
  14.  
  15.       2.  Time stamping protocol of Z80DOS
  16.  
  17.       3.  Get Stamp and Use Stamp
  18.           - General description
  19.           - Z80DOS function 54 -- Get Stamp
  20.           - Z80DOS function 55 -- Use Stamp
  21.  
  22.       4.  Using Get Stamp and Use Stamp
  23.           - Programming example
  24.  
  25.  
  26.  
  27.  
  28. 1.  Format of date/time stamps under Z80DOS
  29.  
  30.  
  31.      Z80DOS uses 10 bytes to represent date of file creation, date and time of
  32. last modification, and date and time of last file access.  This is the same
  33. format used by C. B. Falconer's DOS+25.  The format is as follows:
  34.  
  35.      Byte      Meaning
  36.      ----      -------
  37.      1           Low byte of date of creation
  38.      2           High "     "  "    "     "
  39.  
  40.      3           Low byte of date of last modification
  41.      4           High "     "  "    "    "         "
  42.      5           Hour     "  "    "    "         "         in BCD.
  43.      6           Minute     "  "    "    "         "          "   "
  44.  
  45.      7           Low byte of date of last access
  46.      8           High "     "  "    "    "       "
  47.      9           Hour     "  "    "    "       "    in BCD.
  48.     10           Minute     "  "    "    "       "     "   "
  49.  
  50.      Following a successful Open File, Search First, or Search Next BDOS call
  51. (see below), a call to function 55 (Get Stamp) returns a pointer in the HL
  52. register to a 10-byte buffer in the above format containing the full date and
  53. time stamp of the file referenced in the Open or Search call.  If the file had
  54. no time stamp, the buffer is filled with zeroes.
  55.  
  56.      A ten-byte date and time code of the above format is maintained for each
  57. file by Z80DOS.  The code for each file is stored at the fourth entry of the
  58. directory sector containing the file's first directory extent.    The fourth
  59. directory entry of each sector is flagged for date and time stamping by
  60. setting the user-number field of the directory entry to 21 hex (INITDIR.COM
  61. performs this function).
  62.  
  63.      For example, here is the directory sector for TIMEZCCP.EX, which was
  64. created on May 20, 1987 at 11:46 a.m.:
  65.  
  66.      00  0054494D 4542494F  53455820 00000045  |.TIMEBIOSEX ...E|
  67.      10  7778797A 7B000000  00000000 00000000  |wxyz{...........|
  68.      20  0054494D 455A4343  50455820 0000000D  |.TIMEZCCPEX ....|
  69.      30  7C000000 00000000  00000000 00000000  ||...............|
  70.      40  0054494D 455A4350  52434F4D 0000005C  |.TIMEZCPRCOM...\|
  71.      50  144698A1 A2A50000  00000000 00000000  |.F.!"%..........|
  72.      60  2100630D 630D1307     --> 630D630D  |!.c.c...c...c.c.|
  73.      70  1146630D 1146 <--  620D2232 620D2232  |.Fc..Fb.b."2b."2|
  74.  
  75. The fourth entry of the directory sector contains the stamps for the files
  76. described by the previous three entries, in order.  The first byte of this
  77. entry is 21 hex.  Starting at the third byte of the third directory entry are
  78. the three date and time stamps of the files described by the previous three
  79. directory entries.
  80.  
  81.      Between the arrows (added for clarity) are the date of creation, date and
  82. time of modification, and date and time of access for TIMEZCCP.EX,
  83. respectively.  In this example, the creation, modification, and access date
  84. stamps are all the same.  The date stamp bytes are 63h and 0Dh, because
  85. December 31, 1977 was exactly 0D63 hex days before May 20, 1987.  The time
  86. stamp bytes are 11h and 46h--the 24-hour time (11:53) in binary coded decimal.
  87.  
  88.  
  89.  
  90. 2.  Time stamping protocol of Z80DOS
  91.  
  92.      By selectively modifying the three fields of a file's stamp, Z80DOS
  93. maintains an active record of when various operations were last performed on
  94. the file.  This is done by selectively updating fields of the stamp depending
  95. on which standard DOS function is being called by a program.  The three
  96. standard DOS functions which affect the stamps of files under Z80DOS are Make
  97. File (function 22), Open File (function 15), and Close File (function 16).
  98. The fields of the time stamp affected are as follows:
  99.  
  100.  
  101.               Create       Last Modified    Last Access
  102.  
  103.      Make file        X          X            X
  104.      Open file                            X
  105.      Close file               X
  106.  
  107.  
  108.      All three fields are initialized when a file is created.  Each time a
  109. file is opened for reading or writing, its Last Access field is updated, while
  110. the Create and Last Modified fields remain the same.  Under Z80DOS, as with
  111. CP/M, the Close File call simply returns and has no effect if a file has not
  112. been modified.    Therefore calls to function 16 will update the Last Modified
  113. field only if the file has been written to, and the Create and Last Access
  114. fields will remain the same.
  115.  
  116.      No other function calls affect a file's time and date stamp.  This means
  117. that files can be renamed or have their attributes changed without affecting
  118. file stamps.  In fact, even unerased files will retain their full time and
  119. date stamps.
  120.  
  121.      When the fields of the file's stamp are being updated, Z80DOS normally
  122. gets the values to use from the system clock (i.e., the current real time and
  123. date).    Z80DOS' Use Stamp call instructs Z80DOS to access a dedicated internal
  124. buffer rather than the system clock for the next function call, allowing
  125. greater control over a file's time stamps for programs which copy files.
  126.  
  127.  
  128.  
  129. 3.  Get Stamp and Use Stamp
  130.  
  131. 3.1  General Description
  132.  
  133.      The problem addressed by the Get Stamp and Use Stamp functions is that of
  134. preserving time and date stamps when files are copied.    Under CP/M, files are
  135. normally copied by creating a destination file of the same name as the source
  136. file on another disk or user area, and then copying the contents of the source
  137. file to the destination file.  As noted above, however, each time a file is
  138. created, all three fields of its time and date stamp are normally initialized
  139. to the current system time.  The result is that each time a file is copied,
  140. its actual dates of creation and last modification are lost.
  141.  
  142.      The Get Stamp and Use Stamp functions of Z80DOS address this problem by
  143. allowing the calling program more control over the file stamping process.  By
  144. selective use of these two functions, programs can copy the creation date and
  145. modification time and date of the source file along with its contents.    The
  146. Get Stamp function is used following successful File Open, Search First, or
  147. Search Next calls to store the full time stamp of a file in an internal DOS
  148. buffer.  This buffer remains intact until the next call to Get Stamp or until
  149. the next system cold or warm boot.
  150.  
  151.      The Use Stamp function is then used before functions affecting file
  152. stamping, and instructs the BDOS to substitute the values from its internal
  153. buffer during these functions.    The buffer values are initialized to zeroes
  154. after a warm boot or if the previous Get Stamp call referenced a file in an
  155. unstamped directory, and are initialized to the values of the file referenced
  156. in the previous Get Stamp call otherwise.
  157.  
  158.      Because no buffering is required of the calling program, Get Stamp and
  159. Use Stamp can be implemented with little cost in terms of additional program
  160. code.  It is not necessary for the program to store the file's date and time
  161. stamps, or even to know whether time stamps are present for the file.
  162.  
  163.      Because the Get Stamp and Use Stamp routines of Z80DOS are called as non-
  164. standard functions, programs which use them will remain downward compatible,
  165. i.e., compatible with operating systems which do not provide Get Stamp and Use
  166. Stamp.    As far as I know, no operating system in use for the Z80 (except
  167. possibly CP/M 3) uses DOS calls 54 and 55.  Therefore, programs can call these
  168. functions and still function properly under CP/M or ZRDOS.
  169.  
  170.      Please note that functions 54 and 55 needn't remain exclusive to Z80DOS.
  171. Since these are unused function numbers under CP/M and ZRDOS, future operating
  172. systems such as ZOS might implement functionally equivalent routines using the
  173. same calls.  In this way, functions 54 and 55 may eventually become standard
  174. Get and Use Stamp calls for programs for the Z80 which recognize time and date
  175. stamping.
  176.  
  177.  
  178.  
  179.  3.2.  Z80DOS function 54 -- Get Stamp
  180.  
  181.      This function loads the 10-byte date and time stamp of a file into a
  182. buffer in BDOS following a successful file open, file search, or file create
  183. call.  The buffer holds these values until the next cold or warm boot, or
  184. until Get Stamp is called again.  If no time stamps are present on the
  185. directory, the buffer is filled with zeroes.
  186.  
  187.      As an additional service, Get Stamp returns a pointer in HL to the first
  188. byte of the ten byte dedicated buffer.    This allows programs such as directory
  189. programs to easily read a file's time stamp following a call to Search First,
  190. Search Next, or Open File (see DATEDEMO.Z80 for example).
  191.  
  192.      At present, Z80DOS only provides a valid date and time stamp for the
  193. first extent of multiple-extent files.    Therefore, if a program is searching
  194. all extents of files (e.g., to get file sizes), measures must be taken to
  195. ensure that Get Stamp is called following searches for first extents only.
  196. Otherwise, possibly invalid time stamps from susequent extents will be stored.
  197.  
  198.  
  199.  
  200. 3.3  Z80DOS function 55 -- Use Stamp
  201.  
  202.      The main purpose of Get Stamp is to load a file's date and time stamp for
  203. retrieval with Use Stamp.  When Use Stamp is called before a file is created,
  204. written to, or closed, Z80DOS retrieves the appropriate values stored by Get
  205. Stamp and substitutes them for the system time for date and time stamping.
  206. For example, if Use Stamp is called immediately before a call to Make File
  207. (function 22), the new file is stamped with the creation date value stored
  208. earlier by Get Stamp.
  209.  
  210.      Z80DOS will automatically revert to the current system time following all
  211. BDOS calls except to Use Stamp.  This allows the smallest amount of program
  212. overhead, since no "Reset Stamp" call is required following the Use Stamp call
  213. to set the BDOS back to the current time.  However, Use Stamp must therefore
  214. be called IMMEDIATELY BEFORE Create, Write, or Close calls which are to use
  215. the stored stamp values.
  216.  
  217.  
  218.  
  219. 4.  Using Get Stamp and Use Stamp
  220.  
  221.      The following pseudo code describes the general pattern for file copy
  222. programs using these Get Stamp and Use Stamp:
  223.  
  224.      Open source File
  225.      If file open successful then
  226.       Get Stamp
  227.       Use Stamp
  228.       Create destination file
  229.       Repeat
  230.            Read Sequential from source file
  231.            Use Stamp
  232.            Write Sequential to destination file
  233.       Until end of source file reached
  234.       Use Stamp
  235.       Close destination file
  236.      Close source file
  237.  
  238. Get Stamp need only be called once upon successfully opening the source file;
  239. from then on Use Stamp does all of the work.  When called before creating the
  240. destination file, Use Stamp causes Z80DOS to initialize all three time/date
  241. fields of the destination file to those of the source file.  Upon closing the
  242. destination file, Use Stamp is called again, this time causing Z80DOS to use
  243. the stored stamp of the source file in setting the destination file's last
  244. modified date and time.  Otherwise, the current system time would be used.
  245.  
  246.      Use Stamp is also called before each write to the destination file.  This
  247. is necessary only when copying files with over one extent, and is due to the
  248. way CP/M's Write Sequential function is implemented.  Write Sequential calls
  249. to files of over one extent cause CP/M to Close a file's first extent before
  250. opening a new one for writing.    If the first extent of a file is closed
  251. without first calling Use Stamp, Z80DOS will stamp the first extent with the
  252. current system time.  Therefore, to ensure that the first extent of the copied
  253. file is marked with the proper stamp, it is necessary to call Use Stamp before
  254. each call to Write Sequential.
  255.  
  256.  
  257.      Most word processors for CP/M erase the source file and rewrite it to
  258. disk each a file is modified.  The Z80DOS environment will enable these
  259. programs to preserve the original file's time and date stamps as follows:
  260.  
  261.      Reset file replaced flag
  262.      Search for file X
  263.      If file X found then
  264.       Get Stamp
  265.       Set file replaced flag
  266.      Delete file X
  267.      If replaced = true then
  268.       Use Stamp
  269.      Create File X
  270.      Repeat
  271.       If replaced = true then
  272.            Use Stamp
  273.       Write Sequential to file X
  274.      Until end of text
  275.      If replaced = true then
  276.       Use Stamp
  277.      Close file X
  278.  
  279. This procedure is nearly as simple as the file copy procedure, but does
  280. require that the calling program maintain a record of whether a file is being
  281. replaced or created anew.
  282.  
  283.  
  284.  
  285. 4.1.  Programming Example
  286.  
  287. The following assembly language example illustrates the use of functions 54
  288. and 55 to copy the date of creation from the source file to the destination
  289. file in a file copy program:
  290.  
  291.  
  292. GetStp    equ    54        ; Store file's date and time stamp
  293. UseStp    equ    55        ; Use stored stamp for write/close
  294.  
  295.     ....
  296.  
  297. ; Open source file
  298.  
  299.     call    initfcb2
  300.     ld    c,15        ; Open source file
  301.     call    bdos
  302.     inc    a        ; Check for error
  303.     jp    z,prfnf     ; Branch if file not found
  304. ;
  305.     ld    c,54        ; Save source's stamp
  306.     call    bdos
  307.     ....
  308.  
  309. ; Create destination file
  310.  
  311.     ld    c,55        ; Use stored stamp
  312.     call    bdos        ; ..for destination file
  313. ;
  314.     ld    de,fcb1     ; Point to destination FCB
  315.     ld    c,22        ; BDOS make-file function
  316.     call    bdos
  317.     inc    a        ; Test for error (no directory space)
  318.     ....
  319.  
  320.  
  321. For other programming examples, see files RCPCP.LIB, DATEDEMO.Z80, and
  322. SAVESTMP.Z80 in this library.
  323.  
  324.