home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / sigm / vol119 / ludef1.doc < prev   
Encoding:
Text File  |  1984-04-29  |  6.2 KB  |  161 lines
  1. |File:    LUDEF1.DOC        Date:    82-11-04
  2. |Replaces:
  3. |    LUDEF.DOC           Dated:    82-10-31
  4.  
  5.  From:    Gary P. Novosielski
  6.  To:    All LU users
  7.  
  8.  Subj:    .LBR format definition
  9.  
  10. |    This file is a revision of and obsoletes the previous
  11. |    version.  Revised material is indicated by a vertical
  12. |    bar (|) to the left of the text.
  13.  
  14.  0. Introduction
  15.     There have been several requests for a formal definition of
  16.  the format of library (.LBR) files as used by the LU Library
  17.  Utility program and the LRUN command-file load-and-go utility.
  18.  
  19.     Well, better late than never.  I hope that this definition
  20.  will allow other programmers to make effective use of .LBR
  21.  files in their programming without the need for detective
  22.  work or guesswork about the library format.  Enjoy.
  23.  
  24.  
  25.  1. Library Overview
  26.     A library is a disk file which is assumed to be logically
  27.  divided into one or more subparts called members.  The library
  28.  have any filename and filetype, except that ".LBR" is
  29.  considered to be the default filetype.  Programs must assume
  30.  and may optionally require the .LBR extension on any file which
  31.  is to be treated as a library.
  32.  
  33.  2. Access Method
  34.     Libraries are normally treated as Random Record files by
  35.  programs, but must never contain unallocated "holes" which
  36.  are normally allowed in Random Record files.  A library can
  37.  therefore be safely treated as a sequential file if desired.
  38.     This allows copy programs, compacting programs, and remote
  39.  transfer programs to process the library sequentially, and to
  40.  safely make the assumption that the first occurrence of a
  41.  no-record-found condition truly indicates the physical end of
  42.  the library.
  43.  
  44.  3. Internal Organization
  45.     A library must contain at least one member, the directory,
  46.  and may contain an arbitrary number of other members, up to
  47. |the limits of file size imposed by the operating system.  The
  48. |library may also contain unused sectors which are not assigned
  49. |to any member.  These sectors may occur as a result of the
  50. |deletion of members, or of an unsuccessful add operation.
  51. |   There are no constraints on the contents of members, except
  52.  for the directory, which is always the first member in the
  53.  library, and has a specific format defined later.  However,
  54.  each member must comprise a whole number of 128 byte sectors;
  55. |i.e. each sector of the file belongs to at most one library
  56.  member, and no member has a fractional number of sectors.  A
  57.  member may have 0 sectors.
  58. |   Members may be referred to by a name of up to 8 characters,
  59. |and an extension of up to 3 characters.  The naming rules
  60. |are identical to those for the naming of disk files.
  61.     The start and end points of each member are defined by the
  62.  pointers in the directory entry for the member.  There are no
  63.  embedded start or end marks separating the members.  All
  64.  sectors between the start and end sectors of a member belong
  65.  to that member.
  66.  
  67.  4. Directory Format
  68.     The directory is the first member of a library, and must
  69.  begin in sector 0 of the file.  It must contain at least one
  70.  sector, and may contain an arbitrary number of sectors.
  71.     The directory is composed of entries.  Each entry is 32
  72.  bytes in length, so that the number of entries is equal to four
  73.  times the number of sectors in the directory.  The number of
  74.  entries determines the maximum number of members in the
  75.  library, one entry per member.
  76.     All entries are initialized to one of three possible states:
  77.  Active, Deleted, or Unused.  The first entry is always active,
  78.  and is the entry corresponding to the directory itself.
  79.     Unused entries always occur after all active and deleted
  80.  entries.  If the directory is scanned beginning with the
  81.  first entry, and an unused entry is found, then all remaining
  82.  entries from there through the end of the directory must also
  83.  be tagged as unused.
  84.     However, active and deleted entries may be mixed in any
  85.  order.  Finding a deleted entry does not guarantee that all
  86.  active entries have been scanned.
  87.  
  88.  5. Directory Entry Format
  89.     The 32 bytes of each entry have the following significance:
  90.          
  91.      Byte            Meaning
  92.      ----    ------------------------------------------
  93.      0    Status  Possible values (in hexadecimal) are:
  94.          00    Active Entry
  95. |         FE    Deleted Entry
  96.          FF    Unused Entry
  97.             Any other value should be treated as
  98. |            a deleted entry.
  99.  
  100.      1-8    Name    Rules are identical with those which
  101.              govern the naming of disk files.  Names
  102.              shorter than the maximum are padded
  103.              with spaces.  No two members may have
  104.              the same name.  The name of the
  105.              directory member (first entry) is all
  106.              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 signifi-
  113.              cant byte first.  To begin reading at
  114.              the start of a member, this value
  115.              is loaded into the Random Record field
  116.              of the File Control Block.
  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
  121.              value is zero, then the member is null,
  122.              and the Index field (above) is meaning-
  123.              less.
  124.  
  125.      16-31    Filler     Reserved for future use.  In unused
  126. |             and deleted entries, and in the first
  127. |            (directory) entry, these bytes are
  128. |            garbage.  In all other active entries,
  129.              they are explicitly set to binary zero.
  130.              Any future enhancements to the .LBR
  131.              format which use these bytes must
  132.              recognize this zero value as a
  133.              non-error condition to allow a library
  134.              created with an old version of LU to
  135.              be processed by future versions.
  136.  
  137. |Notes: In unused and deleted entries all bytes except the
  138. |    Status byte are undefined.
  139. |       The contents of any data sectors which are not
  140. |    assigned to an active member are not defined.
  141. |    They remain allocated to the .LBR file, to provide
  142. |    for sequential processing, as noted above, but no
  143. |    assumptions should be made as to their contents.
  144. |    These sectors are eliminated from the library when
  145. |    it is reorganized.
  146.  
  147.  6. Conclusion
  148.     If there are any further questions, comments, requests, etc.
  149.  regarding library format, or if you note any ambiguities or
  150.  contradictions in these specifications, please feel free to
  151.  contact me.
  152.  
  153.      Gary P. Novosielski
  154.  
  155.      Voice phone: (201) 935-4087  Evenings and weekends
  156.      CompuServe:  [70160,120]     EMAIL or CP-MIG
  157.  
  158.  
  159.  
  160.  End of file.
  161.