Macro type: | R for PARMOD=24 |
The GETFL macro can be used only for files which were created with flags. It evaluates the flags in the ISAM index and returns to the user program the next record in a specified range (see the LIMIT operand, "GETFL - Read record by flag") which fulfills the specified conditions.
GETFL can evaluate both the value flag and the logical flag and can search the file either forwards or backwards.
Note that NK-ISAM does not include flags in the index entries and that a search for records with specific characteristics is thus executed as a sequential read operation.
For K-ISAM files, the flags are evaluated as specified in the VALPROP operand of the FILE/FCB macro and placed in the index entry. A search using GETFL is thus not executed sequentially, but via the index tree. The only difference in flag processing between NK-ISAM files and K-ISAM files which is visible to the user is the drop in performance in the case of NK-ISAM. For this reason, flag processing is not recommended for NK-ISAM files.
If VALTEST and LOGTEST are specified, both conditions must be fulfilled by the record.
If neither VALTEST nor LOGTEST is specified, the GETFL macro acts (within the limits set with LIMIT) like a GET or GETR macro. If the specified limit defined with LIMIT is reached, control passes to the EXLST exit EOFADDR (for LIMIT=END) or the EXLST exit NOFIND (for LIMIT=KEY).
If the GETFL macro is used for a file which was created without flags, control is passed to the EXLST exit USERERR.
The field to which the FCB operand KEYARG points must be large enough to accommodate the complete index (key + value flag + logical flag). The value for the value flag or the mask for the logical flag must comply formally with the corresponding flags in the records (e.g. with respect to their position and length).
Value flags
During a search for a record with a specific value flag (operand VALTEST), the appropriate flag area of each record or in the index entry is compared with the value specified in the GETFL macro. In each case, the first record within the specified limits which complies with the specified conditions is read.
Logical flags
To search for a record on the basis of the logical flag, a bit mask must be defined in the GETFL macro. This mask is then compared bit-by-bit with the logical flag in each record. Depending on the specification for the operand LOGTEST, the first record within the specified limits which complies with either one or all of the specified conditions is read.
Formats
The format of the GETFL macro varies, depending on whether the MF operand is specified and what is specified for this operand:
No MF operand | The macro generates parameters and SVC, PARMOD=24/31, |
MF=L | List form: the macro generates the operand list, PARMOD=24. |
MF=E | Execute form: the macro generates the SVC for MF=L. |
As the operands in the format without the MF operand and in the format with MF=L are (apart from the FCB address, PARMOD and MF) identical, these two formats are not shown separately.
Operation | Operands |
|
|
|
Operand descriptions
fcbaddr
Address of the FCB associated with the file to be processed.
(1)
The FCB address is stored in register 1.
(r2)
Only in conjunction with PARMOD=24: on execution of GETFL with MF=(E,...), the FCB address is stored in the register designated by “r2” (where r2 ≠ 1).
area
Address of the area to which the record is to be transferred.
(0)
The address of the area to which the record is to be transferred is stored in register 0.
LOCK
The lock is to remain active once the macro has been executed (explicit lock).
NOLOCK
The lock is not to remain active after execution of the macro.
LIMIT
Defines the end of the area to be searched. The start position is the current position in the file, depending on the preceding macro. The “search direction” depends on whether or not REVERSE=YES is specified. The search begins:
at the first record of the file after the macro SETL B
at the last record of the file after the macro SETL E (this is meaningful only together with REVERSE=YES)
at the current pointer position after the macro SETL KEY
at the record before or after the current pointer position (dependent on REVERSE=YES) for all other macros
= END
The search continues until the end (or beginning) of the file is reached. If the file contains no records whose flags fulfill the specified conditions, the EXLST exit EOFADDR is activated.
= KEY
The limit is defined by a key to which the FCB operand KEYARG points. The search is aborted when it encounters a record with the same key as that referenced by KEYARG.
without REVERSE=YES: only records with keys less than the key addressed via KEYARG are scanned.
with REVERSE=YES: only records with keys greater than the key addressed via KEYARG are scanned.
If the range defined via a key contains no records whose flags fulfill the conditions in the GETFL macro, control is passed to the EXLST exit NOFIND. This is true even if the file is already positioned to the record which contains the LIMIT key; in this case, the file position remains unchanged.
If the key addressed via KEYARG is less than the key at the current pointer position (or greater than this if REVERSE=YES is specified), control passes to the EXLST exit USERERR.
LOGTEST
Specifies, for a search with logical flags, whether the records to be retrieved must fulfill all of the specified conditions or whether compliance with only one condition is sufficient. The bit mask must be specified in the field to which the FCB operand KEYARG points. At least one bit in the mask must be set; otherwise control is passed to the EXLST exit USERERR.
= ANY
The search retrieves the next record whose logical flag matches at least one of the bits of the mask.
= ALL
The search retrieves the next record in whose logical flag all of the bits set in the bit mask are also set.
MF = (E,...)
Generates the SVC: the operand list generated with MF=L is used for execution of the macro.
= E,addr
Address of the operand list generated with MF=L. If the addresses of the FCB and “area” are to be passed in registers, these registers must be loaded with valid addresses before the macro is called.
= E,r
The address of the operand list generated with MF=L is stored in register “r”.
MF = L
Only for PARMOD=24:
an 8-byte operand list is generated; the macro is not executed. The operand list is aligned on a word boundary and contains:
operand byte 1 (see table "Operand byte 1")
the FCB address or the number of the register which contains the FCB address (=1)
operand byte 2 (see table "Operand byte 1")
the address of the area to which the record is to be transferred or the number of the register which will contain this address for a macro call with MF=E.
The operand list must be symbolically addressable (= symbolic address of the macro).
PARMOD
Specifies the generation mode for the macro.
Depending on PARMOD and MF=L, different “operand lists” are generated.
Default value: | the value predefined for the generation mode by means of the GPARMOD macro or preset by the assembler. |
= 24
The object code generated can run only in the 16-Mb address space. If MF=L is specified, an 8-byte operand list is generated; if MF=L is not specified, the operands are transferred to registers 0 and 1.
= 31
The object code generated can run in the 2-GByte address space. The information required for macro processing is contained in the FCB.
REVERSE = YES
Processing is performed “in reverse” (towards the beginning of the file).
Default value: | processing is performed forwards (towards the end of the file). |
VALTEST
Specifies the desired relationship between the value flag of the record to be retrieved and the value to which the FCB operand KEYARG points.
= GT
The value in the record must be greater than the value in the KEYARG field.
= GE
The value in the record must be greater than or equal to the value in the KEYARG field.
= EQ
The value in the record must be equal to the value in the KEYARG field.
= NE
The value in the record must not be equal to the value in the KEYARG field.
= LE
The value in the record must be less than or equal to the value in the KEYARG field.
= LT
The value in the record must be less than the value in the KEYARG field.
Operand list for MF=L
Word 1 | ... | Word 2 | ... |
Operand byte 1 | FCB address or register number | Operand byte 2 | Area address or register number |
Operand byte 1:
Encoded GETFL operand and LOGTEST (see the table "Operand byte 1" ).
FCB address/register:
Must specify either the address of the FCB or a register (right-justified) containing the FCB address.
Operand byte 2:
Encoded information relating to the GETFL operands LOCK/NOLOCK, fcbaddr, area (see the table "Operand byte 2").
Area address/register:
Must specify either the address of the area or a register (right-justified) containing the address of the area to which the record is to be transferred.
Operand byte 1
Bit position/bit pattern | ||||||||
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | Meaning |
0 | 0 | 1 | 0 | VALTEST=GT | ||||
0 | 1 | 0 | 0 | VALTEST=LT | ||||
1 | 0 | 0 | 0 | VALTEST=EQ | ||||
0 | 1 | 1 | 1 | VALTEST=NE | ||||
1 | 0 | 1 | 0 | VALTEST=GE | ||||
1 | 1 | 0 | 0 | VALTEST=LE | ||||
0 | 0 | 0 | 0 | VALTEST=0 or invalid | ||||
1 | LOGTEST operand specified | |||||||
1 | LOGTEST=ALL | |||||||
1 | LIMIT=KEY | |||||||
1 | REVERSE=YES | |||||||
Operand byte 2
Bit pattern/bit position | |||||
7 | 6 | 5 | 4 | Meaning PARMOD=24 | Meaning PARMOD=31 |
1 0 | LOCK specified or default setting NOLOCK specified | LOCK specified or default setting NOLOCK specified | |||
1 0 | FCB address contained in register FCB address specified | - not used - | |||
1 0 | 'area' address not specified 'area' address specified | - not used - | |||
1 0 | 'area' address contained in register 0 'area' address | - not used - | |||
Programming note
The GETFL macro overwrites the contents of registers 0, 1, 14 and 15.
Overview of the EXLST exits
EXLST exit | Related GETFL operand | Meaning |
EOFADDR | LIMIT = END | No matching record found |
NOFIND | LIMIT = KEY |
|
USERERR | --- | File was created without flags or other user error (such as an invalid OPEN mode) |
LIMIT = KEY | Limit has already been exceeded | |
LOGTEST | Bit mask for logical flag contains only zeros (no bits set) |