ISAM: | Macro type: | R for PARMOD=24 |
SAM: | Macro type: | R for PARMOD=24 |
Area of application
The GET function can be used when processing files with SAM or ISAM (record-oriented access methods). The file must have been opened with one of the following OPEN modes:
INPUT (SAM or ISAM)
INOUT (ISAM)
OUTIN (ISAM)
UPDATE (SAM)
Function
The GET function makes a record from a file available to the user. The record returned is always the record referenced by the current record counter. After an OPEN INPUT, this counter is 1. A series of GET macros will thus read the file records sequentially (cf. GETKY, GETFL, GETR for ISAM).
The GET macro does not always issue an SVC. An SVC will only be issued if the next record to be read is no longer in the current buffer area.
If a record located outside the file is requested, DMS detects the “end-of-file” condition. It branches to the EOFADDR address (see the EXLST macro, "EXLST - Define exit address list") and passes control to the user.
Return modes
The user can process a file in two modes which are important for the use of GET:
In LOCATE mode, the system transfers the record to a buffer area in the system (IOREG operand). The address of the record is received in a register specified by the user. The record is not transferred to the program area (cf. MOVE mode).
In MOVE mode, the user includes in his/her program an area to which the system can copy the record. The address of this record area is passed to the system via register 1 when the macro is issued.
Changing the record pointer
The record pointer can be changed by means of positioning. In this case sequential processing is interrupted and continued elsewhere: cf. SETL, SETLKY.
Special features
For SAM files only
OPEN UPDATEIn the OPEN mode UPDATE, GET reads records which are to be updated. PUTX changes the record but does not result in a write job; it just places a code in the FCB indicating that this record needs to be written. The actual write job is only executed upon a subsequent GET, RELSE, SETL; PUTX does not issue an SVC.
Tape files and blocking
With tape files in PAMKEY format with high blocking (STD,n), I/O is extended. In this case conversion to NON-KEY format or BLKSIZE=length is advisable.
Access time can be reduced by using large buffer areas. In this case SAM chains together consecutive PAM pages (chained I/O). However, significant time savings can be expected only if the files occupy largely contiguous storage space (see the SPACE operand of the FILE macro, "FILE - Define file attributes / control file processing").
A GET macro results in an SVC only when a buffer transfer is initiated. Consequently, the user cannot expect to receive control in a STXIT process each time a GET macro is issued (when using the STXIT macro with SVC= or SVCLIST=. For more details see the “Executive Macros” manual [2]).
The fact that a record has been updated in the current buffer is “noted” in the TU FCB by PUTX. It is only if this bit is set at the time of the next GET (RELSE, SETL) that the entire logical block is written to disk. PUTX never issues an SVC.
For ISAM files only
Reading via primary keys
With ISAM files, the logical sequence of records is defined via primary keys. With a series of GET macros, the records are read sequentially in ascending order of primary keys. A SETLKEY can be used to position the file to a given primary key. A subsequent GET will then return this record.
Reading via secondary keysWhen processing an NK-ISAM file, it is also possible to read records by specifying a secondary key. If a primary key covers several records with identical secondary keys (DUPEKEY), these records are returned by GET macros in the order in which they were created.
If the file contains records with duplicate primary keys, they will be retrieved on a “first in, first out” (FIFO) basis.
If a file is read sequentially via a secondary key, records with the same secondary key values are returned in the order in which the secondary key values were created.
Where SETL KEY is used to position the file to an existing record, a subsequent GET macro makes this record available for processing.
Format
Operation | Operands |
|
[,AIX = NO /
|
Operand descriptions
fcbaddr
Address of the FCB associated with the file to be processed.
For ISAM files only:
If the file is to be located with the aid of a secondary key, the 31-bit interface of this FCB must be available.
(1)
The FCB address is located in register 1.
area
Address of the field to which the record is to be transferred when the file is processed in MOVE mode. In LOCATE mode, “area” is ignored.
(0)
The address of the field to which the record is to be transferred is stored in register 0.
LOCK
For ISAM files only:
The record or block lock is to remain active after the macro has been executed (explicit lock).
NOLOCK
No explicit lock is set.
AIX
For ISAM files only:
Specifies whether the record is to be located via its primary or secondary key.
= NO
The record is provided via its primary key.
= YES
This may only be specified if
the 31-bit interface of the macro is generated (via the operand PARMOD=31 or the macro GPARMOD 31) and
the macro refers to a 31-bit FCB.
The record is located via the secondary key specified in the operand KEYNAME or KEYNMAD.
KEYNAME = name
For ISAM files only:
Specifies the name of the secondary key via which the record is to be read.
“name” must be the name of a secondary key declared for the current file. The names of all secondary keys defined for a file can be determined with the SHOWAIX macro or the SHOW-INDEX-ATTRIBUTES command.
KEYNMAD = addr
For ISAM files only:
Specifies the symbolic address (the name) of a field in which the user has stored the name of the secondary key via which the record is to be read.
The field containing the symbolic address addr must contain the name of a secondary key declared for the current file at the time the macro is executed.
PARMOD
Specifies the generation mode for the macro.
Default value: | the value set in the program by the assembler or by means of the GPARMOD macro. |
= 24
The object code generated can run only in the 16-Mb address space (24-bit addressing only).
= 31
The object code generated can run in the 2-Gb address space (24-bit or 31-bit addressing).
Programming note
The GET macro overwrites the contents of registers 0, 1, 14 and 15.