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