Record Collections

General Points

A record collection contains a number of RECORD's. Each record has a NAME, by which it is known, a STRING of bytes, and perhaps a KEY. {Translation: we say "key" where others say "capability", and we say "name" where others say "key".}

Each RC has a limit on the size of the records it can accept. The size of a record is defined as the sum of the lengths of the name and the string. The largest limit available is 4057 bytes. {The reason for the limit: the B-tree is based on a unit of a page, and there is some space in the page used for control information.}

There is an ordering defined on names. It is the lexicographical order on the binary bytes of the names. If two names of unequal length match in their common number of initial characters, the shorter one will precede the longer one.

There are two types of record collections, Name Sequenced and Entry Sequenced. The type is declared when the record collection is created. The calling sequences have been kept as similar as possible to promote interchangeability of programs and data.

Name Sequenced {NS} record collections

There are no restrictions on the contents of the name field. In some record collections names will be variable length upper case EBCDIC alphabetics, while in others, the names will be fixed length binary values. Records may be added, modified, and deleted in any time sequence within NS record collections.

A "user data" area, which may contain information about the records in the record collection, is also maintained within the record collection.

Record Collection Factory

rclim

p3,wrcc

Unspecified order codes give return code X'04'

RCF may currently be found as USER.SYS.RCC .

Record Collection protocol description. A return code summary may be found in (rcrcode). If RC is a record collection, NM is a name of length LNM, ST is a string of length LST, and K is a KEY then:

The order code OC specifies the search criteria as follows:

C will be 4 if there is no record meeting the specified criterion.

For ES record collections: If LNM = 0 then the name used for the search is 4 bytes of zero. Otherwise, c will be 7 if LNM \= 4.

The order code OC specifies under what conditions the record collection will be changed as follows:

If a record with name NM already existed, the name and string of the replaced record will be returned in BS in the format (1,LNM),(LNM,NM),(LST',ST').

If the record did not have a key, c will be 2 and K' will be DK(0).

If NM = 0, the record will be appended to the record collection. C will be 0 and BS will contain (1,4)(4,NM') where NM' is the assigned name for the record. The value of NM' will be equal to the number of records in the record collection after the write operation completes. Thus, the first record will be assigned NM = 1. C will be 5 and BS will be null if there is no room for the record.

If NM \= 0, a replace operation is indicated. If a record with name NM already existed in the record collection, c will be 1 and the new record will replace the old one. C will be 6 and the record collection will be unchanged if the length of the specified record does not match the length of the record to be replaced. In either case, BS will contain the record which was in the record collection at the time of the write operation. BS will be in the format (1,4),(4,NM),(LST,ST).

C will be 7 (invalid request) and BS will be null if any of the following occur: OC is 3 and NM not equal to 0. OC is 4 and NM equal to 0. First Byte of parameter string {length of name} not equal to 4.

Even a delete operation may fail due to insufficient space in the bank.

The Restrictions field contains 32 bit switches defined as follows:]
BIT - MEANING IF ON]
25 - Read user data operation is forbidden] 26 - Write user data operation is forbidden] 27 - Read record operation is forbidden]
28 - Write new record operation is forbidden] 29 - Update existing record operation is forbidden] 30 - Delete record operation is forbidden] 31 - Empty, truncate and delete collection (kt+4) are forbidden

x1 - Time of day clock value in standard epoch. {microseconds since midnight, January 1, 1900}

x2 - will contain 0 if one record collection record corresponds to one OS access method record. Several OS access methods {such as VBS writes from Fortran I/O} produce multiple record collection records for 1 Fortran logical record. In such cases, x2 will contain an {as yet undefined} value indicating the internal structure of the records. This value is communicated to the record collection by the write user data operation (p2,rcwriteud).

{nonref}See (p2,registry) for the current directory facility. See (formative,directory) for some other ideas about directories.

{arcane}{nonref}Design Notes

A second optimization is possible for entry sequenced record collections if the record keeper keeps track of whether all the records are the same length. If this is true, records may be located by addressing arithmetic. If a record is written with a different length, an index must be created which contains, for each record, the address of the text for that record. This table may be addressed directly, since the record number is specified in each call for ES record collections.

{arcane}{nonref}Notes on Implementation, Costs and Limits

The space used by the record collection is never more than about twice the space occupied by the records. In other words there is a small space penalty to achieve fast operation.

If a modest record size limit is specified then an empty record collection uses just one page and a few nodes.

The implementation is the same for ES and NS record collections. No advantage is taken of the special form of ES names.