4. System Access Technique Macroinstructions
4.4. CONTROLLING YOUR DISK FILE PROCESSING
After you have specified the details of the file and partition you wish to access through the declarative macroinstructions, the imperative macroinstructions described in the following subsections actually control your file accessing. The sequence of these macroinstructions for a particular type of processing is listed in 4.3.3.1 and 4.33.2, together with a brief description of their function.
4.4.1. Open a Disk File (OPEN) Eu nction:
The OPEN macroinstruction opens a file defined by the DTFPF and PCA macroinstructions so that it can be accessed by the logical IOCS.
Eormat:
filename-i
Specifies the symbolic address of the DTFPF corresponding to the file to be opened.
(1)
Indicates that register 1 has been preloaded macro instruction.
macroinstruction in the program
with the address of the DTFPF
Positional Parameter n:
f i I ename-n
Successive entries specify the symbolic addresses of the DTFPF macroinstructions in the program corresponding to the additional files to be opened.
Use this form (for example, OPEN EILE1, FILE2) when more than one lockable file is to be accessed by a single task. This opens all the files named and applies the required read or write locks at the same time.
Multiple open should be used to open more than one file when filelock is involved to prevent a lockout between two programs contending for the same file. If any one file on an OPEN macroinstruction cannot be opened because of lock, then none of the files will be opened. In such a case, if an error address had been specified in the DTF of the first file that failed, control returns to that error address. An 88 (lock failure) occurs in the DTF error code (byte 56 of the DTF file table). If no error address was specified, all files specified by the OPEN macroinstruction are deactivated pending the closing of those files by the locking program. This also produces a DM88 (writing for lock) console message.
UP-8832 4-19
LABEL L2SOPERATIONA [symbol] OPEN
OPERAND
Positional Parameter 1
jf I Iename-1[ filename-n]
k( 1)
After the file has been defined by the DTFPF and PCA macroinstructions, you must issue
C
an OPEN macroinstruction to initialize the file before any other access can be made. Use the GET macroinstruction to access the first (or next) data block.
The transient routine called by the OPEN macroinstruction allocates disk space to each of the partition control appendages from the VTOC file extents; these areas are then preformatted if necessary. If too little disk space has been allocated to a fife to satisfy all PCA requirements, partitions requiring space may be extended during processing.
4.4.2. Retrieve Next Logical Block (GET) Function:
The GET macroinstruction reads a logical block from disk into main storage and makes it accessible for processing. The address into which the data is read is specified in the associated PCA macroinstruction by the keyword parameter IOAREA1.
Format:
ffi Iename1jPCA-name
(1) (ø)
f I I ename
Specifies the symbolic address of the DTFPF corresponding to the file being read.
(1)
Indicates that register 1 has been preloaded macroinstruction.
macroinstruction in the program
with the address of the DTFPF
Positional Parameter 2:
PCA-name
Specifies the symbolic address of the PCA macroinstruction associated with the partition to be accessed.
(0)
Indicates that register 0 has been preloaded with the address of the PCA macro instruction.
UP-8832 SPERRY UNIVAC OS/3
SUPERVISOR MACROINSTRUCTIONS
4-20
LABEL L2OPERATIONL [symbol] GET
OPERAND
Positional Parameter 1
UP-8832
PCA Table Content:
SPERRY UNIVAC OS/3 SUPERVISOR MACROINSTRUCTIONS
4-21
The OPEN macroinstruction initializes the current ID field in the PCA table to the start ID of the partition. If the SEQ keyword parameter in the PCA macroinstruction is used, the current ID field will be updated after each GET macroinstruction has been waited.
If the SEQ keyword is not used, or random access is desired, it is your responsibility to preload the current ID field with the relative ID of the data block to be read. The current ID field is located at the address (label) of the PCA being referenced. This is a 4-byte field and contains a right-justified hexadecimal number representing the number of the block (relative to the first block in the partition) to be read.
When a GET macroinstruction is issued for a SAT file, the contents of registers 14, 13, and 12 are saved in three consecutive full words whose address is in register 13.
4.4.3. Output a Logical Block (PUT) Eu nction:
The PUT macroinstruction writes a logical block from main storage to disk. The main storage address from which the data is written is specified in the associated PCA macroinstruction by the keyword parameter IOAREA1.
Format:
f i I ename
Specifies the symbolic address of the DTFPF corresponding to the file being written.
(1)
Indicates that register 1 has been preloaded macroinstruction.
Positional Parameter 2:
macroinstruction in the program
with the address of the DTFPF
PCA-name
Specifies the symbolic address of the PCA macroinstruction associated with the partition to be written.
(0)
Indicates that register 0 has been preloaded with the address of the PCA macroinstruction.
UP-8832
PCA Table Content:
SPERRY UNIVAC OS/3 SUPERVISOR MACROINSTRUCTIONS
4-22
The OPEN macroinstruction initializes the current ID field in ID of the partition. If the SEQ keyword parameter macroinstruction is used, the current ID field will be macroinstruction has been waited.
the PCA table
If the SEQ keyword is not used, or random access is desired, it is your responsibility to pre load the current ID field with the relative ID of the data block to be written. The current ID field is located at the address (label) of the PCA being referenced. This is a 4-byte field and contains a right-justified hexadecimal number representing the number of the block (relative to the first block in the partition) to be written.
When a PUT macroinstruction is issued for a SAT file, the contents of registers 14, 13, and 1 2 are saved in three consecutive full words whose address is in register 13.
4.4.4. Wait for Block Transfer (WAITF) Function:
The WAITF macroinstruction ensures that a command initiated by a preceding GET, PUT, READE, or READH macroinstruction has been completed. When completed, the error status field contains the error status information pertaining to the I/O request. It is your responsibility to check these bits, which are in bytes 50 and 51 of the DTF table.
If the keyword parameter WAIT=YES was not specified in the DTFPF macroinstruction, the WAITE macroinstruction must be issued after a GET, PUT, READE, or READH macroinstruction and before another imperative macroinstruction is issued for that file.
Format:
f I I ename
Specifies the symbolic address of the DTFPF corresponding to the file being accessed.
(1)
Indicates that register 1 has been preloaded macro instruction.
macroinstruction in the program
with the address of the DTFPF
LABEL L\OPERATIONA
UP-8832 SPERRY UNIVAC OS/3 4-23
SUPERVISOR MACROINSTRUCTIONS Update A
4.4.5. Read by Key Equal/Read by Key Equal or Higher (READE/READH) Function:
The READE and READH macroinstructions initiate a search by key for a block having a key equal to the key specified (READE) or equal to or greater than the key specified (READH).
Format:
LABEL LSOPERATIONA OPERAND
[symbol] IREADEk ff11 ename, JPCA-name
IREADHI 1(1) j 1(0)
Positional Parameter 1:
f I I ename
Specifies the symbolic address of the DTFPF macroinstruction in the program corresponding to the file being processed.
(1)
Indicates that register 1 has been preloaded with the address of the DTFPF macro instruction.
Positional Parameter 2:
PCA-name
Specifies the symbolic address of the PCA macroinstruction associated with the partition to be accessed.
(0
Indicates that register 0 has been preloaded with the address of the partition to be accessed.
PCA Table Content:
After a successful search, the current ID entry in the PCA table is updated to reflect the relative number of the record retrieved. However, if SEQ’YES has been specified in the PCA macroinstruction, the current ID field in the PCA table will be the relative block number plus 1.
44.6. Access a Physical Block (SEEK) Eu nction:
The SEEK macroinstruction initiates movement of the disk read/write head to the position specified in the current ID field of the PCA. This is a 4-byte field which contains a right-justified hexadecimal number representing any block number on the track (relative to the first block in the partition) to which head movement will be initiated. It is your responsibility to store the desired relative block number in this field.
Format:
f i I ename
(1)
Specifies the symbolic address of the DTFPF macroinstruction in the program corresponding to the file being accessed.
Indicates that register 1 has been preloaded with the address of the DTFPF macroinstruction.
Positional Parameter 2:
PCA-name
(0)
Specifies the symbolic address of the PCA macroinstruction associated with the partition to be accessed.
Indicates that register 0 has been preloaded with the address of the PCA macroinstruction.
4.4.7. Close a Disk File (CLOSE) Function:
The CLOSE macroinstruction performs the required termination operations for a file.
Once the CLOSE macroinstruction has been issued for a file, only the OPEN macroinstruction may reference that file.
UP-8832 SPERRY UNIVAC OS/3 4-24
SUPERVISOR MACROINSTRUCTIONS
LABEL AOPERATIONz
[symbol] SEEK
OPERAND
Positional Parameter 1
ft I len ame JPCA-name
1(1) J 1(0)
( )
UP-8832
Format
Positional Parameter 1:
f ii ename -1
Specifies the symbolic address of the DTFPF macroinstruction in the program corresponding to the file to be closed.
(1)
Indicates that register 1 has been preloaded with the address of the DTFPF macroinstruction.
‘ALL
Specifies that all files currently open in the job step are to be closed.
Positional Parameter n:
f I I ename-n
Successive entries specify the symbolic addresses of the DTFPF macroinstructions in the program corresponding to the additional files to be closed.