Disc Handling (Data Records)

Copy Sectors

JSBR    3000-   Overlay Module 005
P1=Address of Parameter Block

Copies the specified sectors from the Master Disc to the Copy Disc.

The Master and Copy Discs may be the same disc.

The transfer is carried out in blocks of 8 sectors (the last transfer being a short block if necessary). The program must provide a core buffer area large enough to contain the block (i.e. 1K in the case of 8 or more sectors).

Each block written to the Copy Disc is read back and a hash sum calculated and compared with the Master hash sum. The message HASHFAIL is flashed if the sums are not equal, and the transfer is retried.

Control returns to the step following P1 upon completion of the Copy.

Parameter Block

P1
Master Disc Number.
P2
Start Sector Number, Master Disc.
P3
Copy Disc Number.
P4
Start Sector, Copy Disc.
P5
Address of Transfer Buffer.
P6
Number of Sectors to be copied.

The module occupies one sector and is loaded at 3000-

Extract from File Control Block or File Status Block

JSBR IZ 1700
P1=Control Word

The subroutine returns to the step following P1 with the A-Register holding the contents of the specified word and with the B-Register pointing to the absolute core location of the word.

Control Word

B17
0
B16:B13
Either Word Number in File Status Block,
Or
Zero to extract from File Control Block.
B12:B9
Word Number in File Control Block
B8:B1
File Identifier

Direct Access File Control Block

Word
 
0
201421 if Binary
201422 if Ordinary
1
B16:B9 No of Sectors per transfer
B8:B1 Disc Number
2
Either Address of Buffer Control Block,
Or
Zero (buffer is Task Master Buffer).
3
Minimum Record Number.
4
Maximum Record Number.
5
Logical Record Length (Words)
6
Ordinary files: Number of records per transfer.
Binary files: Log2 of Number of records per transfer.
7
Absolute Sector containing Record Number 1.
8
Address of File Status Block.
Notes
  1. A File Control Block connects the symbolic File Identifier with a physical data-set held on disc. A program that extracts its file information from the FCB will not require to be modified should the file itself be modified.
  2. If B16:B13 are non-zero then B12:B9 must hold the Word Number within the FCB of the FSB pointer (=Word 8 if the file is a Direct Access File).
  3. FCB words are numbered from 0, whereas FSB words are numbered from 1.
  4. File Control Blocks exist somewhere in the OS core space. Word 0 is a mask defining the file type. A binary direct access file is one where the number of records per transfer is expressed (in Word 6) as a power of two (allowing the OS to calculate the absolute sector number more efficiently). Other file types currently recognised are:
    201420
    Undefined File.
    201423
    Directory File (containing program names).
    201424
    Overlay Library (containing overlay modules).
    201425
    Program File.

Buffers

Disc/Core transfers always involve one or more consecutive sectors of 128 words each. Thus a core buffer area is required, equal in size to the number of sectors specified in the top byte of FCB Word 1. If FCB Word 2 is zero, then the buffer area used will be the Master Buffer of the Task requesting the transfer (in this case the number of sectors per transfer will be one, or possibly two if the spool buffer area is being used as an extension); otherwise FCB Word 2 points to a two-word Shared Buffer Control Block:

Shared Buffer Control Block

Word
 
0
Absolute Sector Number currently in Buffer.
1
Address of Buffer.
Notes
  1. The buffer is shared by all tasks.
  2. To prevent another task overlaying the buffer prematurely, the OS automatically locks all transfers to/from a shared buffer (the lock will be broken by a SUSPEND or I/O routine call).
  3. On FETCH, FSB Word 1 is checked against the required sector(s). If they are the same, a disc Read does not take place and the issuing task retains control (i.e. it jumps the disc queue).
  4. More than one file may share the same shared buffer, provided each FCB Word 2 points to the same Shared Buffer Control Block (if the files are on different discs, their Absolute Sector Numbers must not overlap).
  5. The Buffer exists somewhere in the OS core space. Word 1 of the Shared Buffer Control Block must be zero initially.

File Status Block

This is an optional one or four word block containing the file’s dynamic data. The FSB will normally exist within the System Control Record, which should be STOWED whenever the block is updated.

Word
 
1
Count of Live Records.
2
Count of Chained Records.
3
First Free Chained Record Number.
4
Chain Update Flag (non-zero if update is in progress).

Notes

  1. All words of the status block must be zero when the data set is first allocated.
  2. Chain files do not require pre-formatting into an empty chain.
  3. Non-chain files: FSB Words 2:4 are not required. File Maintenance applications routines are responsible for maintaining the Count of Live Records. If this count is not required, then neither is the File Status Block.

Fetch (Direct Access File)

JSBR IZ 1670
P1=Control Word
P2=Address of Record Number
P3=Address of Extract Area

The record identified by the File Identifier (specified in P1) and relative record number within the file (a single word binary field pointed to by P2) is read into the issuing task’s Master Buffer.

If (and only if) the TEST option is specified in P1, the first word of the record is compared with the relative record number (pointed to by P2). If not equal, the subroutine returns to the step following P3 (record not loaded). If equal, the subroutine skips this step on return (record loaded).

When the TEST option is not specified, the subroutine always returns to the step following P3.

The record may be automatically de-buffered by specifying in P3 the address to which it is to be copied (this process is referred to as extraction). If extraction is not required, P3 must be zero. Extraction does not take place if the record is found to be not loaded by the TEST option.

If the issuing task is fetching the record in order to perform an update, the LOCK option must be specified in P1.

On return from FETCH, 0/0151 points to the first word of the record within the Master Buffer, and 0/0152 contains the logical record length.

Control Word

B17
1 if LOCK. Lock instructs the system not to initiate any disc transfers on behalf of any task once the record arrives in core, until the issuing task releases the LOCK (which occurs implicitly upon first entry to the task scheduler following return from FETCH).
B16
1 if TEST.
B15:B7
000 000 000
B6:B1
File Identifier.

Notes

  1. Task HALTS at 0/1374 if the File Identifier is undefined (A-Register contains FETCH back address).
  2. Task HALTS at 0/1377 if the Record Number is outside the file limits (A-Register contains FETCH back address).
  3. If the disc containing the required record is not on-line, a message to this effect is flashed and the task will be held waiting until the disc comes on-line.
  4. If hardware status is reported from the disc controller during FETCH, the system will retry the transfer anticipating that the fault will clear. A message will be flashed at suitable intervals whilst the fault persists or until the disc is taken off-line. It may be possible to clear the fault by placing the disc onto another drive.
  5. Notes 3 & 4 above apply to all disc transfers by all subroutines within LOS.

Fetch (Overlay Module)

JSBR IZ 1670
P1=Control Word
P2=Address of Module Number

The overlay module identified by the File Identifier (specified in P1) and Module Number (a single word binary field pointed to by P2) is read into core.

Control returns to the step following P2 upon completion of the transfer, unless the LINK option is specified in P1 in which case control is passed to the first word of the overlay module.

The absolute address of the first word of the module will be found in core location 0/0144 upon completion of the transfer.

Control Word

B17:B12
00 000 0
B11
1 if LINK
B10:B7
0 000
B6:B1
File Identifier (= 02).

Notes

  1. Automatic Offset Address Resolution does not occur.
  2. Task HALTS at 0/1377 if the Module Number is invalid (A-Register contains FETCH back address).
  3. Task HALTS at 0/1373 if a software hash fail is detected (A-Register contains FETCH back address).

Fetch (Program)

JSBR IZ 1670
P1=Control Word
P2=Address of four-character ASCII name

The overlay module identified by the File Identifier (specified in P1) and name (a double word pointed to by P2) is read into core.

Automatic Offset Address Resolution will be carried out if (and only if) this option is set in the program’s Overlay Module Index entry.

If the LINK option is specified in P1 control is passed to the logical entry point within the Overlay Module associated with the four-character program name.

If the program is not found the subroutine returns to the step following P2. If the program is found but LINK is not requested, the subroutine skips this step on return.

On completion of the transfer, 0/0153 contains the Overlay Module Number, 0/0144 points to the first word of the Overlay Module and 0/0154 points to the logical entry point.

Control Word

B17:B12
00 000 0
B11
1 if LINK
B10:B7
0 000
B6:B1
File Identifier (= 05 for I/O Station programs, = 06 for Printer programs).

Note

Byte Addressing of the program name is not supported. All four characters addressed by P2 comprise the name (a NUL byte does not act as terminator).

Rewrite

JSBR IZ 1671

The record just FETCHED from a Direct Access File is written back to disc. The subroutine returns to the step following JSBR upon completion of the transfer.

There are no parameters. All relevant information is defined in the preceding FETCH parameters. The FETCH must specify the LOCK option.

If, and only if, the record was extracted by FETCH, it will be automatically replaced (i.e. re-buffered) by REWRITE.

Note

Task HALTS at 0/1376 if REWRITE called out-of-context (A-Register contains FETCH back address). Out-of-context occurs if there is no LOCK in force on the record, if there was no preceding FETCH & LOCK, or if the File Type is not Direct Access.

Overwrite

JSBR IZ 1672
P1=Address of new record

The record just FETCHED from a Direct Access File is overwritten in its core buffer by the new record pointed to by P1, and the buffer is written back to disc. The subroutine returns to the step following P1 upon completion of the transfer.

Notes

  1. Task HALTS at 001376 if OVERWRITE called out-of-context (A-Register contains FETCH back address).
  2. Consideration should be given to TEST the record fetched for a not loaded condition before going ahead with an OVERWRITE.

Stow System Control Record

JSBR IZ 1667

Writes the System Control Record to disc and returns to the step following JSBR upon completion of the transfer.

There are no parameters.

The System Control Record is permanently core resident at 0/0400 and occupies 1, 2 or 3 sectors as required by the application. The record is the only record (number 1) in the System Control File, File Identifier 10.

The System Control Record is never read from disc, except once when the system is started via control panel switches, but it is necessary to write the record to disc whenever updates are carried out within it, as a security precaution.

The first 64 words (0/0400 to 0/0477) are reserved for systems use, the remainder for applications use.

0/0477 contains the System Date in packed format.

Extension of File Identifier to eight bits

LOS Bulletin No 23 (May 1978)

The FETCH, GET (Fetch Mode) and EXTRACT from FILE CONTROL BLOCK routines have been modified to handle file identifiers 000 to 377 octal.

This increases the number of files accessible from a single file table from 64 to 256. However, the reason for making this increase is to allow related files to be grouped together. System designers are requested to adhere to the following standards when allocating file identifiers to Indexed Files:

File Id
Record Access Method
0xx
Via the slot number. FETCH reads the record into core by direct access (the slot number having been obtained by a previous FETCH via the record key).
1xx
Via the record “key”. FETCH searches the index to obtain the slot number, then reads the record into core. The slot number to be available in 0/0153 on return.
2xx
Access Index Record via record “key” (used only by File Maintenance programs with responsibility to update the Index).
3xx
Available to File Maintenance routines, e.g. if more than one Index is required.

Implementation.

The file table remains 64 words long. Existing entries are unchanged. Step xx contains the address of a five-word “Hybrid” File Control Block, format as follows:

Word
Contents
0
201426 (HYBRID FILE MASK)
1
Address of FCB of 0xx (set to 001377 if not in use)
2
Address of FCB of 1xx (set to 001377 if not in use)
3
Address of FCB of 2xx (set to 001377 if not in use)
4
Address of FCB of 3xx (set to 001377 if not in use)

Indexed Sequential Files

LOS Bulletin No 25 (July 1978)

The "FETCH" and "GET (FETCH MODE)" routines now support Indexed Sequential files.

A new subroutine, JSBR IZ 1661 is available to programs requiring to LOAD or DELETE records in an Indexed Sequential File.

A new system utility is available for the re-organisation of Indexed Sequential Indexes.

Notes

  1. The Operating System ISAM coding is permanently resident at 7/0200 to 7/0677. If IS files are to be added at existing installations the Configuration Table will (in most cases) require modification to avoid using this area.
  2. The LOAD/DELETE subroutine calls System Overlays into the last two sectors of the calling task's Overlay area, i.e. into 2600-

Setting up an Indexed Sequential File

An Indexed Sequential File structure comprises three Direct Access files. Conventionally these will be allocated file identifiers within a single Hybrid FCB (File Control Block) as follows:

File Id
Used to access records within:
0xx
Data File directly via Direct Access method
1xx
Data File sequentially via ISAM
2xx
Secondary Index File via Direct Access method
3xx
Primary Index File via Direct Access method

Data File Control Block

This is a Direct Access file defined as is appropriate for the individual application. The record's ISAM key need not be included within the actual data record. A four-word File Status Block must be provided within the System Control Record and initially cleared to zeros; this will be automatically maintained in the "Free Chain" format.

Indexed Sequential File Control Block

Word
Contents
0
201427 (ISAM FILE MASK)
1
Data File Identifier
2
Secondary Index File Identifier
3
Primary Index File Identifier
4
Key Length (in words)
5
Address of File Status Block

A one-word File Status Block must be provided within the System Control Record and initially cleared to zero.

Secondary Index File Control Block

This is a Direct Access file with a minimum record length equal to Key Length (in words) + 2 but preferably extended, if necessary, to be a Binary file for efficient access. A one-word File Status Block must be provided within the System Control Record. A Shared Buffer must be used. The number of records must be at least equal to the number of data records allowed for.

Primary Index File Control Block

This again is a Direct Access file. A Shared Buffer must be used and the record length is the same as that of the Secondary Index file. For efficient use, the Shared Buffer of the Secondary Index must be different to that of the Primary Index. A File Status Block is not required. The file size is chosen to produce an efficient access time. A rough guide is to allow approximately 100 secondary index entries per primary index entry as a minimum.

Indexed Sequential Re-Organisation Utility

It is essential to re-organise the indexed to an Indexed Sequential File from time to time because:

  • New Secondary Index records, although logically linked into the correct position in the collating sequence, are physically loaded into the next free record. This tends to increase the number of disc transfers required to search for a key.
  • Deleted Secondary Index records are not released for re-use (although the deleted key may be reloaded).
  • Primary Index records tend to become unevenly spaced along the logical sequence.

A re-organisation program must therefore be provided for each Indexed Sequential file at an installation. It is five steps long (+ ASCII file name for display purposes) and should be placed in System Overlay Module 11:

JSBR IZ 1670 FETCH & LINK Module 21
P1=002002
P2=0/0221 -> Module Number 021
P3=Indexed Sequential File Identifier
P4=Byte Address of File Name (ASCII terminated by NUL)

Notes

  1. The program is requested at an I/O Station. A suitable name should be placed in the "Input" Directory.
  2. The operator will be prompted for Password 1.
  3. The request is posted to a plain paper print queue, renamed as program "ISAM".
  4. The I/O Station returns (or escapes) to the "PROGRAM?" prompt.
  5. Re-organisation is carried out by program ISAM in a printer partition. If the File Identifier (P3) is not that of an IS file, ISAM halts. Disc workspace (at least equal to the size of the index files) is required from the spool file; if insufficient space is available ISAM aborts.
  6. Only the indexes are re-organised; the Data File is not re-organised (Data Record slot numbers remain unaltered).
  7. Other tasks should not access an IS file whilst it is being re-organised.

System Catalogue

LOS Bulletin No 27 (July 1978)

File Identifier 007 is reserved for the System Catalogue. Each new installation will have a System Catalogue, and it is recommended that a System Catalogue be added at existing installations. Each Dataset (= File on disc) is allocated one 16-word Catalogue record containing (among other fields) its File Control Block.

If the Catalogue Record Number (+ Bit 17 set) is inserted into the File Table (in the Configuration Table) instead of the FCB core address, the Initiator (on bootstrapping) obtains the FCB from the catalogue and establishes it in a free core area.

Note: All FCBs other than that of the Catalogue itself may be obtained in this manner.

The Catalogue is maintained as an Indexed Sequential File (with File Identifier 107) with six-character keys (the Dataset Name) via the new utility program "CATM". Program "CATP" is available to print the catalogue either in alphabetic order or in physical order. The CATM utility does not allow datasets to physically overlap.

In addition, program ACT has been modified to enable catalogue numbers to be inserted into the file table.

"System Disc" recommended layout

The recommended layout of the installation's "System Disc" (usually Unit 70 Fixed Cartridge and always on-line when the system is running) follows:

Start Sector (octal)Number of Sectors (decimal)Number of Records (decimal)File IdentifierDescription
0000001  BOOTSTRAP
00000131  Not used
0000401  DISC LABEL
0000411  MASTER BOOTSTRAP (backup copy of Sector 000000
0000423  CONFIGURATION TABLE
00004531010SYSTEM CONTROL FILE
00005095  OPERATING SYSTEM (12K)
000207116307System Catalogue (Primary Index
0002108128207System Catalogue (Secondary Index)
000220816305File of File Tables
00023016128007System Catalogue
0002508256001Overlay Index
0002608256003Input/Output Station Directory
0002708256004Printer Directory
0003001  Not used
0003011103 002Overlay Module Library
002420  Start of User Datasets
014537   D818 cartridge max (6,496 sectors)
031277   D1600 cartridge max (12,992 sectors)

File Handling Schema

The File Table (pointed to by 00/0073) provides the active task with access to all the storage files required at an installation. Software designers assign a unique 8-bit File Identifier to each logical file (the capacity of the original 64-word File Table is extended to 256 files as described in LOS Bulletin No 23).

Because all the programs at an installation use the same File Identifier for each specific logical file (Spool File, Customer File, Product File etc.) the File Control Blocks (defining the attributes and storage location of the physical dataset) are established by the Initiator from information within the Configuration Table on bootstrapping. Individual programs do not, therefore, need to open (or close) files as they are already "pre-opened" by the system and remain so in the absence of any close/open facility.

The association between File Id and physical Dataset becomes much more flexible when there is a System Catalogue; in particular the catalogue maintenance and print utilities greatly simplify the reallocation of an installation's available disc storage in the light of operational experience.

Whilst the File Table's 256 file capacity amply satisfies the programming requirements at a user installation, program development at BCL's branch offices often involves staff working on different client test and/or demonstration systems on a single machine at the same time. The Table of File Tables (pointed to by 00/0025) enables an I/O Station to select from up to four pre-loaded File Tables via the Fn command, whilst the "LOAD" utility (new in October 1978) designates which File Table should be over-loaded into the Station's current resident File Table from the File of File Tables on the System Disc. Printer tasks automatically select the resident File Table of the task which posted their current job.

Note that a dataset is not required online unless and until a program attempts to access the data within it. In response to any disc transfer request LOS constructs a 16-word "Transfer Vector" at 00/0140 holding all the information required to execute the request and resume the calling task on its successful completion. If the request is to read data which is already "cached" in a Shared Buffer the calling task is resumed immediately. Otherwise the transfer vector is added to the end of the queue for the disc controller through which the relevant disc is mounted, or to the "unallocated" queue if the disc is not online.

The disc controllers give notice (by hardware interrupt) whenever a drive comes online or goes offline. LOS responds to an online notification by rescheduling any "unallocated" transfers that can now proceed, and to an offline notification by moving the relevant controller's transfer queue to the unallocated queue. LOS alerts users to any matters arising during transfer attempts and queued tasks remain blocked until their transfer is reported successfully completed (so there is no need for the calling program to check for itself).