home *** CD-ROM | disk | FTP | other *** search
/ RBBS in a Box Volume 1 #3.1 / RBBSIABOX31.cdr / magn / ludef4.doc < prev    next >
Text File  |  1985-03-05  |  11KB  |  232 lines
  1. r ludef4.doc (pcs131 xa4)
  2.  
  3.  File:  LUDEF4.DOC              Date:   84-08-04
  4.  Replaces: LUDEF3.DOC           Dated:  83-08-16
  5.  
  6.  From:  Gary P. Novosielski / Paul Homchick
  7.  To:    All LU users
  8.  
  9.  Subj:  .LBR format definition
  10.  
  11.         This file is a revision of and obsoletes the previous
  12.         version.  Revised material is indicated by a vertical
  13.         bar (|) to the left of the text.
  14.  
  15.  0. Introduction
  16.     There have been several requests for a formal definition of
  17.  the format of library (.LBR) files as used by the LU Library
  18.  Utility program and the LRUN command-file load-and-go utility.
  19.  
  20.     I hope that this definition will allow other programmers to
  21.  make effective use of .LBR files in their programming without
  22.  the need for detective work or guesswork about the library
  23.  format.  Enjoy.
  24.  
  25.  
  26.  1. Library Overview
  27.     A library is a disk file which is assumed to be logically
  28.  divided into one or more subparts called members.  The library
  29.  may have any filename and filetype, except that ".LBR" is
  30.  considered to be the default filetype.  Programs must assume
  31.  and may optionally require the .LBR extension on any file
  32.  which is to be treated as a library.
  33.  
  34.  2. Access Method
  35.     Libraries are usually treated as Random Record files by
  36.  programs, but must never contain unallocated "holes" which
  37.  are normally allowed in Random Record files.  A library can
  38.  therefore be safely treated as a sequential file if desired.
  39.     This allows copy programs, compacting programs, and remote
  40.  transfer programs to process the library sequentially, and to
  41.  safely make the assumption that the first occurrence of a
  42.  no-record-found condition truly indicates the physical end of
  43.  the library.
  44.  
  45.  3. Internal Organization
  46.     A library must contain at least one member, the directory,
  47.  and may contain an arbitrary number of other members, up to
  48.  the limits of file size imposed by the operating system.  The
  49.  library may also contain unused sectors which are not assigned
  50.  to any member.  These sectors may occur as a result of the
  51.  deletion of members, or of an unsuccessful add operation.
  52.     There are no constraints on the contents of members, except
  53.  for the directory, which is always the first member in the
  54.  library, and has a specific format defined later.  However,
  55.  each member must comprise a whole number of 128 byte sectors;
  56.  i.e. each sector of the file belongs to at most one library
  57.  member, and no member has a fractional number of sectors.  A
  58.  member may have 0 sectors.
  59.     Members may be referred to by a name of up to 8 characters,
  60.  and an extension of up to 3 characters.  The naming rules
  61.  are identical to those for the naming of disk files.
  62.     The start and end points of each member are defined by the
  63.  pointers in the directory entry for the member.  There are no
  64.  embedded start or end marks separating the members.  All
  65.  sectors between the start and end sectors of a member belong
  66.  to that member.
  67.  
  68.  4. Directory Format
  69.     The directory is the first member of a library, and must
  70.  begin in sector 0 of the file.  It must contain at least one
  71.  sector, and may contain an arbitrary number of sectors.
  72.     The directory is composed of entries.  Each entry is 32
  73.  bytes in length, so that the number of entries is equal to
  74.  four times the number of sectors in the directory.  The
  75.  number of entries determines the maximum number of members in
  76.  the library, one entry per member.
  77.     Each entry is initialized to one of three possible states:
  78.  Active, Deleted, or Unused.  The first entry is always active,
  79.  and is the entry corresponding to the directory itself.
  80.     Unused entries always occur after all active and deleted
  81.  entries.  If the directory is scanned beginning with the
  82.  first entry, and an unused entry is found, then all remaining
  83.  entries from there through the end of the directory must also
  84.  be tagged as unused.
  85.     However, active and deleted entries may be mixed in any
  86.  order.  Finding a deleted entry does not guarantee that all
  87.  active entries have been scanned.
  88.  
  89.  5. Directory Entry Format
  90.     The 32 bytes of each entry have the following significance:
  91.                 
  92.         Byte                    Meaning
  93.         ----    ------------------------------------------
  94.         0       STATUS  Possible values (in hexadecimal) are:
  95.                 00      Active Entry
  96.                 FE      Deleted Entry
  97.                 FF      Unused Entry
  98.                         Any other value should be treated as
  99.                         a deleted entry.
  100.  
  101.         1-8     NAME    Rules are identical with those which
  102.                         govern the naming of disk files.  Names
  103.                 shorter than the maximum are padded with
  104.                 spaces.  No two members may have the same name.
  105.                 The name of the directory member (first entry)
  106.                 is all spaces.
  107.  
  108.         9-11    EXTENSION       (same rules as Name)
  109.  
  110.         12-13   INDEX   Pointer to the first sector of this
  111.                         member within the library.  Stored as
  112.                 a two-byte binary value, least significant byte
  113.                 first.  To begin reading at the start of a
  114.                 member, this value is loaded into the Random
  115.                 Record field of the File Control Block.  The
  116.                 index of the directory itself is zero.
  117.  
  118.         14-15   LENGTH  The length of the member in sectors.
  119.                         Stored as a two-byte binary value,
  120.                 least significant byte first.  If this value is
  121.                 zero, then the member is null, and the Index
  122.                 field (above) is meaningless.
  123.  
  124.         16-17   CRC     The Cyclic Redundancy Check value for
  125.                         the member.  Stored as a two-byte
  126.                 binary value, least significant byte first.
  127.                 This value is calculated using the same
  128.                 algorithm as the widely distributed XMODEM
  129.                 program using CRC protocol.  If each byte of
  130.                 the member file is processed by this algorithm,
  131.                 followed by the two bytes of the CRC itself
  132.                 (high order first), the resulting value will be
  133.                 zero.
  134.                    The directory member is a special case. Its
  135.                 own CRC value is embedded within it, which
  136.                 would affect the outcome of the next CRC check.
  137.                 For this reason, The CRC value for the
  138.                 directory's own entry is calculated as if the
  139.                 two bytes of its own CRC word were 00.  The
  140.                 actual value is plugged in just before writing 
  141.                 to disk.  When checking the directory CRC, the 
  142.                 value is moved  to a hold area, and these two
  143.                 bytes are zeroed before the calculation.
  144.  
  145. |               The next four 16-bit words are reserved for library
  146. |               member time and date stamping.  These words are defined
  147. |               below, and must be stored INTEL HEX format with the
  148. |               least significant byte stored first.
  149. |
  150. |       18-19   FILE CREATION DATE.  Stored in Digital Research
  151. |               MP/M - CP/M+ julian date format, as a binary
  152. |               number representing the number of days since
  153. |               December 31, 1977.  For example:  Jan 1, 1978 is
  154. |               1 (0001H), and July 4, 1984 is 2377 (0949H).  If
  155. |               this feature is not used, it should be zero filled
  156. |               to retain compatibility.  For use in MS-DOS
  157. |               environments, convert the MS-DOS yy/mm/dd date
  158. |               to the DRI format, and store in this word.
  159. |
  160. |       20-21   FILE UPDATE/CHANGE DATE.  Stored in Digital Research
  161. |               MP/M - CP/M+ julian date format.  If this feature is
  162. |               not used, it should be zero filled to retain
  163. |               compatibility.
  164. |
  165. |       22-23   FILE CREATION TIME.  Stored in MS-DOS format:
  166. |
  167. |       ------------  23  ------------  ------------  22  ------------
  168. |       15  14  13  12  11  10  09  08  07  06  05  04  03  02  01  00
  169. |        h   h   h   h   h   m   m   m   m   m   m   s   s   s   s   s
  170. |
  171. |               h = binary number of hours (0-23).
  172. |               m = binary number of minutes (0-59).
  173. |               s = binary number of two-second increments.
  174. |
  175. |               Use this field for time-stamping in MS-DOS
  176. |               environments.  If this feature is not used
  177. |               it should be zero-filled.
  178. |
  179. |       24-25   FILE UPDATE/CHANGE TIME.  Stored in MS-DOS
  180. |               format.  In an MS-DOS environment, or if this
  181. |               feature is not implemented, this field
  182. |               should be zero filled.
  183. |
  184. |       26-31   FILLER  Reserved for future use.  In unused
  185.                         and deleted entries, these bytes are
  186.         garbage.  In all active entries, including the first
  187.         (directory) entry, they are explicitly set to binary
  188.         zero.  This is a difference from previously published
  189.         definitions, which did not define the contents of these
  190.         bytes in the directory control entry.
  191.            Any future enhancements to the .LBR format which
  192.         make use of these bytes will recognize this zero
  193.         value as a non-error condition to allow a library
  194.         created with an old version of LU to be processed by
  195.         future versions.
  196.  
  197.  Notes:
  198.         In unused and deleted entries all bytes except the
  199.         Status byte are undefined.
  200.  
  201.            The contents of any data sectors which are not
  202.         assigned to an active member are not defined.
  203.         They remain allocated to the .LBR file, to provide
  204.         for sequential processing, as noted above, but no
  205.         assumptions should be made as to their contents.
  206.         These sectors are eliminated from the library when
  207.         it is reorganized.
  208.  
  209.         For systems which do not implement the CRC validation
  210.         functions, the crc value of member entries should
  211.         be set to 0000.  The last 16 bytes of the directory
  212.         control (first) entry should all be set to a non-zero
  213.         value.  This will prevent CRC-capable versions of
  214.         the program from issuing CRC error messages when
  215.         opening or extracting from an old-style library
  216.  
  217.  6. Conclusion
  218.     If there are any further questions, comments, or requests
  219.  regarding library format, or if you note any ambiguities or
  220.  contradictions in these specifications, please feel free to
  221.  contact me.
  222.  
  223.         Gary P. Novosielski
  224.  
  225.         Voice phone: (201) 935-4087  Evenings and weekends
  226.         CompuServe:  [70160,120]     EMAIL or CP-MIG
  227.  
  228.  
  229.  
  230.  End of file.
  231.  
  232.