home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1995 May / Simtel-MSDOS-May1995-CD1.iso / starter / ludef5.doc < prev    next >
Text File  |  1986-11-08  |  17KB  |  391 lines

  1.  File:    LUDEF5.DOC        Date:    84-08-19
  2.  Replaces: LUDEF4.DOC        Dated:    84-08-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. |   This is the fifth revision of the 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. |   Many thanks to all of those who have taken the time to
  18. |make suggestions for improvements to this definition.  Purely
  19. |voluntary compliance with this standard by scores of program-
  20. |mers on many differing operating systems has allowed the .LBR
  21. |format to evolve into a successful exchange tool in many
  22. |segments of the computing community.  Additional suggestions
  23. |are encouraged.
  24. |   Please note that the current version of LU does not support
  25. |the full directory format as defined here.  This revision has
  26. |been distributed as an aid to programmers working on various
  27. |other programs on non-CP/M operating systems, to allow support
  28. |for new features in a standardized manner.
  29.  
  30.  1. Library Overview
  31. |   A library is a data file which is assumed to be logically
  32.  divided into one or more subparts called members.  The library
  33.  may have any filename and filetype, except that ".LBR" is
  34.  considered to be the default filetype.  Programs must assume
  35.  and may optionally require the .LBR extension on any file
  36.  which is to be treated as a library.
  37.  
  38.  2. Disk Access Method
  39.     Libraries are usually treated as Random Record files by
  40.  programs, but must never contain unallocated "holes" which
  41.  are normally allowed in Random Record files.  A library can
  42.  therefore be safely treated as a sequential file if desired.
  43.     This allows copy programs, compacting programs, and remote
  44.  transfer programs to process the library sequentially, and to
  45.  safely make the assumption that the first occurrence of a
  46.  no-record-found condition truly indicates the physical end of
  47.  the library.
  48.  
  49.  3. Internal Organization
  50.     A library must contain at least one member, the directory,
  51.  and may contain an arbitrary number of other members, up to
  52.  the limits of file size imposed by the operating system.  The
  53.  library may also contain unused sectors which are not assigned
  54.  to any member.  These sectors may occur as a result of the
  55.  deletion of members, or of an unsuccessful add operation.
  56.     There are no constraints on the contents of members, except
  57.  for the directory, which is always the first member in the
  58. |library, and has a specific format defined later.  The entire
  59. |library file and each of its members are conceptually
  60. |organized into "sectors", each sector being 128 bytes long.
  61.  Each sector of the file belongs to at most one library member.
  62. |Each member comprises a whole number of sectors.  The last
  63. |sector of a member may, however, be logically declared as a
  64. |"Short Sector".  Although it physically contains 128 bytes,
  65. |a Short Sector contains one or more "pad" bytes at the end
  66. |for the purpose of maintaining the structure of the library
  67.  file as a whole.  A member may have as few as 0 sectors.
  68.  
  69.     Members may be referred to by a name of up to 8 characters,
  70.  and an extension of up to 3 characters.  The naming rules
  71.  are identical to those for the naming of CP/M-80 disk files.
  72. |Members must be uniquely named; any given combination of name
  73. |and extension may identify at most one member.
  74.  
  75.     The start and end points of each member are defined by the
  76.  pointers in a "directory entry" for the member.  There are no
  77.  embedded start or end marks separating the members.  All
  78.  sectors between the start and end sectors of a member belong
  79. |to that member.  The members need not appear in the library
  80. |in the same order that their directory entries appear in the
  81. |directory.  Thus the directory may be sorted, within certain
  82. |ordering constraints defined below, without physically moving
  83. |the members themselves.
  84.  
  85.  4. Directory Format
  86.     The directory is the first member of a library, and must
  87.  begin in sector 0 of the file.  It must contain at least one
  88.  sector, and may contain an arbitrary number of sectors.  The
  89. |directory may not contain a Short Sector.
  90.     The directory is composed of entries.  Each entry is 32
  91.  bytes in length, so that the number of entries is equal to
  92.  four times the number of sectors in the directory.  The
  93. |number of entries present determines the maximum number of
  94. |members in the library.  Each directory entry contains the
  95. |name, starting point, size, and other information for one
  96. |of the members in the library.
  97.     Each entry is initialized to one of three possible states:
  98.  Active, Deleted, or Unused.  The first entry is always active,
  99.  and is the entry corresponding to the directory itself.
  100.     Unused entries always occur after all active and deleted
  101.  entries.  If the directory is scanned beginning with the
  102.  first entry, and an unused entry is found, then all remaining
  103.  entries from there through the end of the directory must also
  104.  be tagged as unused.
  105.     However, active and deleted entries may be mixed in any
  106.  order.  Finding a deleted entry does not guarantee that all
  107.  active entries have been scanned.
  108.  
  109.  5. Directory Entry Format
  110.  
  111.     The 32 bytes of each entry have the following significance:
  112.  
  113.     Byte            Meaning
  114.     ----    ------------------------------------------
  115.     0    STATUS  Possible values (in hexadecimal) are:
  116.         00    Active Entry
  117.           FE    Deleted Entry
  118.         FF    Unused Entry
  119.             Any other value should be treated as
  120.         a deleted entry.
  121.  
  122.     1-8    NAME    Rules are identical with those which
  123.             govern the naming of disk files.  Names
  124.         shorter than the maximum are padded with
  125.         spaces.
  126.  
  127.     9-11    EXTENSION  Rules are the same as for NAME.
  128.  
  129.     12-13    INDEX    Pointer to the first sector of the
  130.             member within the library.  Stored as
  131.         a two-byte binary value, least significant byte
  132. |        first.  For example, an index of value of 9
  133. |        indicates that the first sector of the member
  134. |        occurs 9 sectors, or 9 * 128 = 1152 bytes from
  135. |        the beginning of the library.
  136.  
  137.     14-15    LENGTH    The length of the member in sectors.
  138.             Stored as a two-byte binary value,
  139.         least significant byte first.  If this value is
  140.         zero, then the member is empty, and the Index
  141.         field (above) is meaningless.
  142.  
  143.     16-17    CRC    The Cyclic Redundancy Check value for
  144.             the member.  Stored as a two-byte
  145.         binary value, least significant byte first.
  146.         This value is calculated using the CCITT
  147.         algorithm as used in the widely supported
  148.          XMODEM protocol.  If each of the bytes in the
  149. |        member (including any pad bytes inserted in the
  150. |        possibly "short" last sector) are processed by
  151. |        this algorithm, followed by the two bytes of
  152.         the CRC itself (high order first) the resulting
  153.         value will be zero.
  154. |           Special-case processing is required for the
  155. |        CRC value of the directory member. See below.
  156. |
  157. |    The next four 16-bit words are reserved for library
  158. |    member time and date stamping.  They are all stored
  159. |    as two-byte binary values, least significant byte
  160. |    first.  Programs not implementing time and date
  161. |    stamping shall explicitly set any unused values to
  162. |    zero when creating a new entry.  Programs must convert
  163. |    the time and date formats, if any, defined by their own
  164. |    operating system into the given formats to insure
  165. |    transportability of the resulting library file.
  166.  
  167. |    18-19   CREATION DATE    The date of creation of the
  168. |                file.  Its value may be prior
  169. |        to the date the file was added as a member of
  170. |        the library, if the operating system can supply
  171. |        the original creation date of the file.  On
  172. |        extracting the member from the library, this
  173. |        date may be passed to the operating system for
  174. |        its use in restoring the original creation
  175. |        date.  The format for the date conforms to
  176. |        Digital Research MP/M (and CP/M+) julian date
  177. |        format.  This is a binary 16-bit integer
  178. |        value representing the number of days since
  179. |        December 31, 1977.  For example:  Jan 1, 1978
  180. |        is day 1 (0001H), and July 4, 1984 is 2377
  181. |        (0949H).  A zero value indicates this date is
  182. |        not available.
  183.  
  184. |    20-21   LAST CHANGE DATE  The date of last change to
  185. |                  the member.  Assumed to be
  186. |        no earlier than the creation date, and may
  187. |        pre-date the addition of the file as a member.
  188. |        Storage format is identical to creation date.
  189. |        If the operating system supplies only one file
  190. |        date, it should be stored in Creation Date,
  191. |        and Last Change Date left unused (set to zero.)
  192. |        A zero value is assumed to be equal to the
  193. |        creation date.  A program which makes any
  194. |        in-place changes to the member while it resides
  195. |        in the library should update the value of this
  196. |        field with the current date if known, or if
  197. |        not known, should overwrite with zeros.  For
  198. |        the purpose of this definition, the performing
  199. |        of a strictly reversable process, such as the
  200. |        encryption, compression, or translation of a
  201. |        member does not require a change of date.
  202.  
  203. |    22-23    CREATION TIME    If available, the time-of-day
  204. |                corresponding to the creation
  205. |        date as defined above.  The storage format
  206. |        conforms to MS-DOS standards, wherein the 16-
  207. |        bit word comprises three sub-fields as follows:
  208. |
  209. |        byte:    <==23==> <==22==>
  210. |        bit:    76543210 76543210
  211. |        field:    hhhhhmmm mmmsssss
  212. |
  213. |        legend:
  214. |        h = Hours.  Treated as a 5-bit binary integer
  215. |            in the range 0..23
  216. |        m = Minutes.  Treated as a 6-bit binary integer
  217. |            in the range 0..59
  218. |        s = Seconds/2.  Treated as a 5-bit binary
  219. |            integer in the range 0..29, allowing
  220. |            resolution to the nearest 2-second
  221. |            interval.  May be zeros in a system
  222. |            supporting only hour/minutes.
  223. |
  224. |    24-25    LAST CHANGE TIME   If available, the time of
  225. |                   day corresponding to the
  226. |        Last Change Date defined above.  Format is the
  227. |        same as Creation Time.
  228.  
  229. |    26      PAD COUNT    Valid range: 00H to 7FH.  This
  230. |                byte is for use with non-CP/M
  231. |        systems, such as MS-DOS and UNIX, where file
  232. |        lengths are not necessarily a multiple of 128
  233. |        bytes. It allows the exact size of the member
  234. |        to be expressed in the directory entry.  The
  235. |        value in PAD COUNT represents the number of pad
  236. |        bytes (from 0 to 127) which were inserted in
  237. |        the final sector of the member to bring its
  238. |        size up to the required 128 bytes.  The value
  239. |        of each pad byte inserted should be a hexi-
  240. |        decimal 1A (ASCII SUB character) which is
  241. |        a normal end-of-file mark under CP/M.
  242. |
  243. |        For example, a Pad Count of 10 hexidecimal (16
  244. |        decimal) implies that the last 16 bytes of the
  245. |        final sector of the member are pad characters,
  246. |        i.e. that only the first 112 bytes (128-16) are
  247. |        actually part of the member file.  The pad
  248. |        characters may be ignored when the member is
  249. |        extracted from the library.  The resulting file
  250. |        is then the same length as the original.
  251. |        Specifically, it is ((LENTH * 128) - PAD COUNT)
  252. |        bytes long.
  253. |        
  254. |        Note well, however, that the pad characters are
  255. |        in fact physically present in the library file,
  256. |        and are counted as significant characters in
  257. |        the CRC check value calculations discussed
  258. |        above.  This is necessary to provide downward
  259. |        compatibility with older libraries, and with
  260. |        programs which do not implement this feature,
  261. |        such as CP/M-only versions of LU.  Any program
  262. |        not implementing this feature shall explicitly
  263. |        set this byte to zero when creating a new
  264. |        entry.  (Libraries built by any program which
  265. |        properly adhered to prior versions of this
  266. |        standard have therefore been properly created.)
  267. |        In this case, the last sector of the member
  268. |        will be assumed to be a full 128 bytes long,
  269. |        which was always the case in the past.
  270.  
  271.     27-31    FILLER     Reserved for future use.  In unused
  272.               and deleted entries, these bytes are
  273.      garbage.  In all active entries, they are explicitly
  274.     set to binary zero.
  275.        Any future enhancements to the .LBR format which
  276.     make use of these bytes will recognize this zero
  277.     value as a non-error condition to allow a library
  278.     created with an old version of LU to be processed by
  279.     future versions.
  280.  
  281. | 6. Directory Control Entry
  282. |    The Directory Control Entry is always the first entry in
  283. | the directory, and is the entry which corresponds to the
  284. | directory member itself.  This entry is similar in form to
  285. | any other entry, but is specified more completely here for
  286. | clarification.
  287. |
  288. |     STATUS        Always 00, Active.  The directory must
  289. |            always be an active member.
  290. |
  291. |    NAME        Always 8 blanks.  This is the unique
  292. |            name of the directory member.
  293. |
  294. |    EXTENSION    Always 3 blanks.
  295. |   
  296. |    INDEX        Always 0000; the directory must be
  297. |            physically located at the beginning of
  298. |            the library file.
  299. |
  300. |    LENGTH        Never 0000.  The directory must contain
  301. |            at least one sector.  The actual length
  302. |            of the directory is found here.
  303. |
  304. | If any program finds, in the first sixteen bytes of a library
  305. | file, one or more values which conflict with the above
  306. | specifications, this fact shall be interpreted as a fatal
  307. | indication that the file is not a valid LBR-format library.
  308. | Errors in the following bytes are non-fatal:
  309. |
  310. |    CRC        Since the directory contains its own
  311. |            entry, and hence its own CRC value, a
  312. |    logical conflict would arise if the CRC value were
  313. |    calculated in the normal manner.  The act of storing
  314. |    the CRC value in the entry would render it invalid.
  315. |    For this reason, the CRC value of the directory member
  316. |    is calculated after explicitly storing a 0000 value
  317. |    in the CRC word of the first entry.  The resulting
  318. |    calculated value is then stored in this word before
  319. |    closing the library.
  320. |        When checking the CRC of an existing directory, the
  321. |    old CRC value in the first entry is saved in temporary
  322. |    storage and replaced by 0000 before calculating the
  323. |    new CRC value.  The old and new values should then be
  324. |    compared for equality.
  325.  
  326.     CREATION DATE    If used, the date of creation of the
  327.             library.  Reorganization of the library
  328.     to reclaim space may leave this date unchanged.
  329.  
  330.     LAST CHANGE DATE  If used, the date of last change to
  331.               the directory.  The directory is
  332.     changed by adding, deleting, or renaming members, and
  333.     by reorganizing the library.
  334.  
  335.     CREATION TIME    If used, the time of creation of the
  336.             library.
  337.  
  338.     LAST CHANGE TIME  If used, the time of last change to
  339.               the directory.
  340.  
  341.     PAD COUNT    Value ignored and assumed 0. Directory
  342.             sectors are always a full 128 bytes.
  343.     Set to 0 when library is created or reorganized.
  344.  
  345.     FILLER        Set to 0 as in any other entry.
  346.  
  347.  Notes:
  348.     In unused and deleted entries all bytes except the
  349.     Status byte are undefined.
  350.  
  351.        The contents of any data sectors which are not
  352.     assigned to an active member are not defined.
  353.     They remain allocated to the .LBR file, to provide
  354.     for sequential processing, as noted above, but no
  355.     assumptions should be made as to their contents.
  356.     These sectors are eliminated from the library when
  357.     it is reorganized.
  358.  
  359.     For systems which do not implement the CRC validation
  360.     functions, the CRC value of member entries should
  361. |    be set to 0000.  Libraries created by very early
  362. |    versions of LU may have garbage in the last 16 bytes
  363. |    of the first directory entry, but all other entries
  364. |    will conform to this convention.  These old library
  365. |    files may generate spurious (but non-fatal) error
  366. |    messages caused by a garbage Directory CRC.  Attempts
  367. |    to support the detection of this condition, and the
  368. |    supression of these error messages has become more and
  369. |    more complex to implement, and more difficult to
  370. |    justify.  Beginning with this definition, such attempts
  371. |    are forsaken.  Users experiencing a problem with this
  372. |    are encouraged to make a minor change to such libraries
  373. |    with a version 3.0 or higher LU.  A dummy add/delete or
  374. |    reorganization will suffice.  My appologies for any
  375. |    inconvenience this may cause.
  376.  
  377.  6. Conclusion
  378.     If there are any further questions, comments, or requests
  379.  regarding library format, or if you note any ambiguities or
  380.  contradictions in these specifications, please feel free to
  381.  contact me.
  382.  
  383.     Gary P. Novosielski
  384.  
  385.     Voice phone: (201)935-4087   Evenings and weekends
  386.     MCI Mail:    GNOVOSIELSKI
  387.     CompuServe:  [70160,120]     EMAIL or CP-MIG
  388.     Telex:         650-195-2395    6501952395 MCI
  389.  
  390.  End of file.
  391.