391 lines
16 KiB
Plaintext
391 lines
16 KiB
Plaintext
File: LUDEF5.DOC Date: 84-08-19
|
|
Replaces: LUDEF4.DOC Dated: 84-08-04
|
|
|
|
From: Gary P. Novosielski
|
|
To: All LU users
|
|
|
|
Subj: .LBR format definition
|
|
|
|
This file is a revision of and obsoletes the previous
|
|
version. Revised material is indicated by a vertical
|
|
bar (|) to the left of the text.
|
|
|
|
0. Introduction
|
|
| This is the fifth revision of the formal definition of
|
|
the format of library (.LBR) files as used by the LU Library
|
|
Utility program and the LRUN command-file load-and-go utility.
|
|
| Many thanks to all of those who have taken the time to
|
|
|make suggestions for improvements to this definition. Purely
|
|
|voluntary compliance with this standard by scores of program-
|
|
|mers on many differing operating systems has allowed the .LBR
|
|
|format to evolve into a successful exchange tool in many
|
|
|segments of the computing community. Additional suggestions
|
|
|are encouraged.
|
|
| Please note that the current version of LU does not support
|
|
|the full directory format as defined here. This revision has
|
|
|been distributed as an aid to programmers working on various
|
|
|other programs on non-CP/M operating systems, to allow support
|
|
|for new features in a standardized manner.
|
|
|
|
1. Library Overview
|
|
| A library is a data file which is assumed to be logically
|
|
divided into one or more subparts called members. The library
|
|
may have any filename and filetype, except that ".LBR" is
|
|
considered to be the default filetype. Programs must assume
|
|
and may optionally require the .LBR extension on any file
|
|
which is to be treated as a library.
|
|
|
|
2. Disk Access Method
|
|
Libraries are usually treated as Random Record files by
|
|
programs, but must never contain unallocated "holes" which
|
|
are normally allowed in Random Record files. A library can
|
|
therefore be safely treated as a sequential file if desired.
|
|
This allows copy programs, compacting programs, and remote
|
|
transfer programs to process the library sequentially, and to
|
|
safely make the assumption that the first occurrence of a
|
|
no-record-found condition truly indicates the physical end of
|
|
the library.
|
|
|
|
3. Internal Organization
|
|
A library must contain at least one member, the directory,
|
|
and may contain an arbitrary number of other members, up to
|
|
the limits of file size imposed by the operating system. The
|
|
library may also contain unused sectors which are not assigned
|
|
to any member. These sectors may occur as a result of the
|
|
deletion of members, or of an unsuccessful add operation.
|
|
There are no constraints on the contents of members, except
|
|
for the directory, which is always the first member in the
|
|
|library, and has a specific format defined later. The entire
|
|
|library file and each of its members are conceptually
|
|
|organized into "sectors", each sector being 128 bytes long.
|
|
Each sector of the file belongs to at most one library member.
|
|
|Each member comprises a whole number of sectors. The last
|
|
|sector of a member may, however, be logically declared as a
|
|
|"Short Sector". Although it physically contains 128 bytes,
|
|
|a Short Sector contains one or more "pad" bytes at the end
|
|
|for the purpose of maintaining the structure of the library
|
|
file as a whole. A member may have as few as 0 sectors.
|
|
|
|
Members may be referred to by a name of up to 8 characters,
|
|
and an extension of up to 3 characters. The naming rules
|
|
are identical to those for the naming of CP/M-80 disk files.
|
|
|Members must be uniquely named; any given combination of name
|
|
|and extension may identify at most one member.
|
|
|
|
The start and end points of each member are defined by the
|
|
pointers in a "directory entry" for the member. There are no
|
|
embedded start or end marks separating the members. All
|
|
sectors between the start and end sectors of a member belong
|
|
|to that member. The members need not appear in the library
|
|
|in the same order that their directory entries appear in the
|
|
|directory. Thus the directory may be sorted, within certain
|
|
|ordering constraints defined below, without physically moving
|
|
|the members themselves.
|
|
|
|
4. Directory Format
|
|
The directory is the first member of a library, and must
|
|
begin in sector 0 of the file. It must contain at least one
|
|
sector, and may contain an arbitrary number of sectors. The
|
|
|directory may not contain a Short Sector.
|
|
The directory is composed of entries. Each entry is 32
|
|
bytes in length, so that the number of entries is equal to
|
|
four times the number of sectors in the directory. The
|
|
|number of entries present determines the maximum number of
|
|
|members in the library. Each directory entry contains the
|
|
|name, starting point, size, and other information for one
|
|
|of the members in the library.
|
|
Each entry is initialized to one of three possible states:
|
|
Active, Deleted, or Unused. The first entry is always active,
|
|
and is the entry corresponding to the directory itself.
|
|
Unused entries always occur after all active and deleted
|
|
entries. If the directory is scanned beginning with the
|
|
first entry, and an unused entry is found, then all remaining
|
|
entries from there through the end of the directory must also
|
|
be tagged as unused.
|
|
However, active and deleted entries may be mixed in any
|
|
order. Finding a deleted entry does not guarantee that all
|
|
active entries have been scanned.
|
|
|
|
5. Directory Entry Format
|
|
|
|
The 32 bytes of each entry have the following significance:
|
|
|
|
Byte Meaning
|
|
---- ------------------------------------------
|
|
0 STATUS Possible values (in hexadecimal) are:
|
|
00 Active Entry
|
|
FE Deleted Entry
|
|
FF Unused Entry
|
|
Any other value should be treated as
|
|
a deleted entry.
|
|
|
|
1-8 NAME Rules are identical with those which
|
|
govern the naming of disk files. Names
|
|
shorter than the maximum are padded with
|
|
spaces.
|
|
|
|
9-11 EXTENSION Rules are the same as for NAME.
|
|
|
|
12-13 INDEX Pointer to the first sector of the
|
|
member within the library. Stored as
|
|
a two-byte binary value, least significant byte
|
|
| first. For example, an index of value of 9
|
|
| indicates that the first sector of the member
|
|
| occurs 9 sectors, or 9 * 128 = 1152 bytes from
|
|
| the beginning of the library.
|
|
|
|
14-15 LENGTH The length of the member in sectors.
|
|
Stored as a two-byte binary value,
|
|
least significant byte first. If this value is
|
|
zero, then the member is empty, and the Index
|
|
field (above) is meaningless.
|
|
|
|
16-17 CRC The Cyclic Redundancy Check value for
|
|
the member. Stored as a two-byte
|
|
binary value, least significant byte first.
|
|
This value is calculated using the CCITT
|
|
algorithm as used in the widely supported
|
|
XMODEM protocol. If each of the bytes in the
|
|
| member (including any pad bytes inserted in the
|
|
| possibly "short" last sector) are processed by
|
|
| this algorithm, followed by the two bytes of
|
|
the CRC itself (high order first) the resulting
|
|
value will be zero.
|
|
| Special-case processing is required for the
|
|
| CRC value of the directory member. See below.
|
|
|
|
|
| The next four 16-bit words are reserved for library
|
|
| member time and date stamping. They are all stored
|
|
| as two-byte binary values, least significant byte
|
|
| first. Programs not implementing time and date
|
|
| stamping shall explicitly set any unused values to
|
|
| zero when creating a new entry. Programs must convert
|
|
| the time and date formats, if any, defined by their own
|
|
| operating system into the given formats to insure
|
|
| transportability of the resulting library file.
|
|
|
|
| 18-19 CREATION DATE The date of creation of the
|
|
| file. Its value may be prior
|
|
| to the date the file was added as a member of
|
|
| the library, if the operating system can supply
|
|
| the original creation date of the file. On
|
|
| extracting the member from the library, this
|
|
| date may be passed to the operating system for
|
|
| its use in restoring the original creation
|
|
| date. The format for the date conforms to
|
|
| Digital Research MP/M (and CP/M+) julian date
|
|
| format. This is a binary 16-bit integer
|
|
| value representing the number of days since
|
|
| December 31, 1977. For example: Jan 1, 1978
|
|
| is day 1 (0001H), and July 4, 1984 is 2377
|
|
| (0949H). A zero value indicates this date is
|
|
| not available.
|
|
|
|
| 20-21 LAST CHANGE DATE The date of last change to
|
|
| the member. Assumed to be
|
|
| no earlier than the creation date, and may
|
|
| pre-date the addition of the file as a member.
|
|
| Storage format is identical to creation date.
|
|
| If the operating system supplies only one file
|
|
| date, it should be stored in Creation Date,
|
|
| and Last Change Date left unused (set to zero.)
|
|
| A zero value is assumed to be equal to the
|
|
| creation date. A program which makes any
|
|
| in-place changes to the member while it resides
|
|
| in the library should update the value of this
|
|
| field with the current date if known, or if
|
|
| not known, should overwrite with zeros. For
|
|
| the purpose of this definition, the performing
|
|
| of a strictly reversable process, such as the
|
|
| encryption, compression, or translation of a
|
|
| member does not require a change of date.
|
|
|
|
| 22-23 CREATION TIME If available, the time-of-day
|
|
| corresponding to the creation
|
|
| date as defined above. The storage format
|
|
| conforms to MS-DOS standards, wherein the 16-
|
|
| bit word comprises three sub-fields as follows:
|
|
|
|
|
| byte: <==23==> <==22==>
|
|
| bit: 76543210 76543210
|
|
| field: hhhhhmmm mmmsssss
|
|
|
|
|
| legend:
|
|
| h = Hours. Treated as a 5-bit binary integer
|
|
| in the range 0..23
|
|
| m = Minutes. Treated as a 6-bit binary integer
|
|
| in the range 0..59
|
|
| s = Seconds/2. Treated as a 5-bit binary
|
|
| integer in the range 0..29, allowing
|
|
| resolution to the nearest 2-second
|
|
| interval. May be zeros in a system
|
|
| supporting only hour/minutes.
|
|
|
|
|
| 24-25 LAST CHANGE TIME If available, the time of
|
|
| day corresponding to the
|
|
| Last Change Date defined above. Format is the
|
|
| same as Creation Time.
|
|
|
|
| 26 PAD COUNT Valid range: 00H to 7FH. This
|
|
| byte is for use with non-CP/M
|
|
| systems, such as MS-DOS and UNIX, where file
|
|
| lengths are not necessarily a multiple of 128
|
|
| bytes. It allows the exact size of the member
|
|
| to be expressed in the directory entry. The
|
|
| value in PAD COUNT represents the number of pad
|
|
| bytes (from 0 to 127) which were inserted in
|
|
| the final sector of the member to bring its
|
|
| size up to the required 128 bytes. The value
|
|
| of each pad byte inserted should be a hexi-
|
|
| decimal 1A (ASCII SUB character) which is
|
|
| a normal end-of-file mark under CP/M.
|
|
|
|
|
| For example, a Pad Count of 10 hexidecimal (16
|
|
| decimal) implies that the last 16 bytes of the
|
|
| final sector of the member are pad characters,
|
|
| i.e. that only the first 112 bytes (128-16) are
|
|
| actually part of the member file. The pad
|
|
| characters may be ignored when the member is
|
|
| extracted from the library. The resulting file
|
|
| is then the same length as the original.
|
|
| Specifically, it is ((LENTH * 128) - PAD COUNT)
|
|
| bytes long.
|
|
|
|
|
| Note well, however, that the pad characters are
|
|
| in fact physically present in the library file,
|
|
| and are counted as significant characters in
|
|
| the CRC check value calculations discussed
|
|
| above. This is necessary to provide downward
|
|
| compatibility with older libraries, and with
|
|
| programs which do not implement this feature,
|
|
| such as CP/M-only versions of LU. Any program
|
|
| not implementing this feature shall explicitly
|
|
| set this byte to zero when creating a new
|
|
| entry. (Libraries built by any program which
|
|
| properly adhered to prior versions of this
|
|
| standard have therefore been properly created.)
|
|
| In this case, the last sector of the member
|
|
| will be assumed to be a full 128 bytes long,
|
|
| which was always the case in the past.
|
|
|
|
27-31 FILLER Reserved for future use. In unused
|
|
and deleted entries, these bytes are
|
|
garbage. In all active entries, they are explicitly
|
|
set to binary zero.
|
|
Any future enhancements to the .LBR format which
|
|
make use of these bytes will recognize this zero
|
|
value as a non-error condition to allow a library
|
|
created with an old version of LU to be processed by
|
|
future versions.
|
|
|
|
| 6. Directory Control Entry
|
|
| The Directory Control Entry is always the first entry in
|
|
| the directory, and is the entry which corresponds to the
|
|
| directory member itself. This entry is similar in form to
|
|
| any other entry, but is specified more completely here for
|
|
| clarification.
|
|
|
|
|
| STATUS Always 00, Active. The directory must
|
|
| always be an active member.
|
|
|
|
|
| NAME Always 8 blanks. This is the unique
|
|
| name of the directory member.
|
|
|
|
|
| EXTENSION Always 3 blanks.
|
|
|
|
|
| INDEX Always 0000; the directory must be
|
|
| physically located at the beginning of
|
|
| the library file.
|
|
|
|
|
| LENGTH Never 0000. The directory must contain
|
|
| at least one sector. The actual length
|
|
| of the directory is found here.
|
|
|
|
|
| If any program finds, in the first sixteen bytes of a library
|
|
| file, one or more values which conflict with the above
|
|
| specifications, this fact shall be interpreted as a fatal
|
|
| indication that the file is not a valid LBR-format library.
|
|
| Errors in the following bytes are non-fatal:
|
|
|
|
|
| CRC Since the directory contains its own
|
|
| entry, and hence its own CRC value, a
|
|
| logical conflict would arise if the CRC value were
|
|
| calculated in the normal manner. The act of storing
|
|
| the CRC value in the entry would render it invalid.
|
|
| For this reason, the CRC value of the directory member
|
|
| is calculated after explicitly storing a 0000 value
|
|
| in the CRC word of the first entry. The resulting
|
|
| calculated value is then stored in this word before
|
|
| closing the library.
|
|
| When checking the CRC of an existing directory, the
|
|
| old CRC value in the first entry is saved in temporary
|
|
| storage and replaced by 0000 before calculating the
|
|
| new CRC value. The old and new values should then be
|
|
| compared for equality.
|
|
|
|
CREATION DATE If used, the date of creation of the
|
|
library. Reorganization of the library
|
|
to reclaim space may leave this date unchanged.
|
|
|
|
LAST CHANGE DATE If used, the date of last change to
|
|
the directory. The directory is
|
|
changed by adding, deleting, or renaming members, and
|
|
by reorganizing the library.
|
|
|
|
CREATION TIME If used, the time of creation of the
|
|
library.
|
|
|
|
LAST CHANGE TIME If used, the time of last change to
|
|
the directory.
|
|
|
|
PAD COUNT Value ignored and assumed 0. Directory
|
|
sectors are always a full 128 bytes.
|
|
Set to 0 when library is created or reorganized.
|
|
|
|
FILLER Set to 0 as in any other entry.
|
|
|
|
Notes:
|
|
In unused and deleted entries all bytes except the
|
|
Status byte are undefined.
|
|
|
|
The contents of any data sectors which are not
|
|
assigned to an active member are not defined.
|
|
They remain allocated to the .LBR file, to provide
|
|
for sequential processing, as noted above, but no
|
|
assumptions should be made as to their contents.
|
|
These sectors are eliminated from the library when
|
|
it is reorganized.
|
|
|
|
For systems which do not implement the CRC validation
|
|
functions, the CRC value of member entries should
|
|
| be set to 0000. Libraries created by very early
|
|
| versions of LU may have garbage in the last 16 bytes
|
|
| of the first directory entry, but all other entries
|
|
| will conform to this convention. These old library
|
|
| files may generate spurious (but non-fatal) error
|
|
| messages caused by a garbage Directory CRC. Attempts
|
|
| to support the detection of this condition, and the
|
|
| supression of these error messages has become more and
|
|
| more complex to implement, and more difficult to
|
|
| justify. Beginning with this definition, such attempts
|
|
| are forsaken. Users experiencing a problem with this
|
|
| are encouraged to make a minor change to such libraries
|
|
| with a version 3.0 or higher LU. A dummy add/delete or
|
|
| reorganization will suffice. My appologies for any
|
|
| inconvenience this may cause.
|
|
|
|
6. Conclusion
|
|
If there are any further questions, comments, or requests
|
|
regarding library format, or if you note any ambiguities or
|
|
contradictions in these specifications, please feel free to
|
|
contact me.
|
|
|
|
Gary P. Novosielski
|
|
|
|
Voice phone: (201)935-4087 Evenings and weekends
|
|
MCI Mail: GNOVOSIELSKI
|
|
CompuServe: [70160,120] EMAIL or CP-MIG
|
|
Telex: 650-195-2395 6501952395 MCI
|
|
|
|
End of file.
|
|
|