SETL - Position file pointer

ISAM:	Macro type:	R for PARMOD=24 0 for PARMOD=31
SAM:	Macro type:	R for PARMOD=24 0 for PARMOD=31

ISAM:

The SETL macro positions the pointer to the beginning or end of a file or, by specifying the record key, to any record within the file.

If SETL KEY is used to position within a file via the primary key and if the file contains records with duplicate primary key values (DUPEKY=YES), the file is positioned to the first of these records.

If SETL KEY is used to position within a file via a secondary key and if the file contains records with duplicate values for this secondary key, the file is positioned to the record whose primary key is indicated by the first pointer in the associated secondary index block.

SAM:

SETL sets the block and record pointer to the position (retrieval address) specified by the user.

The SETL macro sets the position of the internal record pointer, thus enabling the user to define the starting point for subsequent processing of the file.

The retrieval address in the 31-bit TU FCB is updated such that it will be correct after a subsequent GET or PUT macro; in the 24-bit TU FCB, the retrieval address is not changed.

Since the positioning information in the 24-bit TU FCB is 1 byte long, a buffer must not contain more than 255 records.

An invalid SETL operand causes control to be passed to the address USERERR of the EXLST macro.

Format

Operation	Operands
SETL	fcbadr / (1) ,B / E / R / KEY / (0) [,AIX = NO /         YES,KEYNAME = name /         YES,KEYNMAD = adr] [,PARMOD = 24 / 31]

Operand descriptions

fcbaddr

Address of the FCB associated with the file to be processed.
For ISAM only:
If the file is to be positioned with the aid of a secondary key, the 31-bit interface of this FCB must be available.

(1)
The FCB address is stored in register 1.

B

The pointer is to be moved to the beginning of the file.
For ISAM only:
Using SETL B for a null file will cause control to be passed to the EOFADDR error exit of the EXLST macro.
For SAM only:
For multivolume files, the pointer is positioned to the first record on the current tape.

E

The pointer is to be moved to the end of the file.
For SAM only:
For multivolume files, the pointer is positioned to the last record of the current tape, which means that the next GET macro will initiate a tape swap.
With OPEN OUTPUT/EXTEND, specifying “E” will cause control to be passed to the USERERR exit of the EXLST macro.

R

For SAM only:
The positioning information is to be taken from the retrieval address (not permitted for tape files with nonstandard blocks processed with PARMOD=24). For multivolume files, the retrieval address applies to the current volume, not to the file.

KEY

For ISAM only:
The pointer is to be positioned to the primary or secondary key value stored in the field specified in the KEYARG operand of the FCB macro.

If a SETL ...,KEY points to an existing key, a subsequent GET or GETR will read this record.
If SETL ...,KEY points to a non-existent record, a subsequent GET will read the record with the next higher key and a GETR will read the record with the next lower key.

(0)
Register 0 contains a “positioning code”. Before the SETL macro is executed, the positioning code must be loaded into register 0 as follows:

SETL operand	Contents of register 0	Effect
B	0	Position to beginning-of-file
E	1	Position to end-of-file
R	2	For SAM only: position according to retrieval address
KEY	Address of KEYARG	Position to specific record

If register 0 contains a value other than 0 or 1, this value is always interpreted as the KEYARG address.

AIX

For ISAM only:
Specifies whether the pointer is to be positioned to a record via its primary key or via a secondary key.

= NO
The pointer is positioned to the record via its primary key (default value).

= 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 pointer is positioned to the record via the secondary key specified in the KEYNAME or KEYNMAD operand.

KEYNAME = name

For ISAM only:
Specifies the name of the secondary key via which the pointer is to be positioned to the record.
“name” must be the name of a secondary key defined for the current file. The names of all secondary keys defined for a file can be determined by means of the SHOWAIX macro or the SHOW-INDEX-ATTRIBUTES command.

AIX=YES must be specified.

KEYNMAD = addr

For ISAM 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 pointer is to be positioned to the record.
When the macro is executed, the field with the symbolic address “addr” must contain the name of a secondary key defined for the current file.

AIX=YES must be specified.

PARMOD

Specifies the generation mode for the macro.

Default value:

the value predefined for the generation mode by means of the GPARMOD macro or preset by the assembler.

= 24
The macro is generated with the expansion for the 24-bit interface. The object code generated can run only in the 16-Mb address space (24-bit addressing).

= 31
The macro is generated such that it is independent of the addressing mode (24-bit or 31-bit addressing). The object code generated can run in the 2-Gb address space. 

Programming notes

1. The SETL macro overwrites the contents of registers 0, 1, 14 and 15.

2. A SETL macro always results in an SVC.