Macro type: type O
By means of the EXLST macro, the user defines a list of symbolic addresses which point to program routines for evaluating and handling events which cause normal processing to be interrupted.
There is a separate operand in the EXLST macro for each event. If a symbolic address is specified in the macro for the related operand, DMS can branch to the appropriate program routine if a given event occurs. If the operand is omitted or contains only a null string, the occurrence of the event will result in abortion of the program unless a common error handling routine is addressed via the operand COMMON.
However, this routine is not called for the operands with which the FCB can be modified during OPEN processing or with which the user writes his own tape labels during OPEN or CLOSE processing. If these operands are specified in the EXLST macro, DMS branches to the program routines which they address.
Format
Operation | Operands |
|
[,DUPEKY = NO / relexp]
|
Operand descriptions
relexp
Symbolic address in the Assembler program.
PARMOD
Specifies the generation mode for the macro.
Default value: | the value preset for the generation mode by means of the GPARMOD macro or by the assembler. |
= 24
The macro is expanded in accordance with the format for the 24-bit interface. The object code is thus executable only in 24-bit addressing mode, i.e. in the 16-Mb address space.
= 31
The macro is generated as addressing mode-independent; the object code can run in the 2-Gb address space.
CLOSER
An error has occurred during CLOSE processing. An error code describing the condition in more detail is stored in FCB field ID1ECB.
CLOSPOS
For tape input files with nonstandard labels:
The user can use BTAM macros to position a tape for which a CLOSE macro with either REPOS or LEAVE was called. CLOSE processing continues after execution of the CLOSPOS routine. If this exit is not defined, the system handles tape positioning.
COMMON
Control is passed to this address if there is no special exit for the type of error encountered.
Exceptions:
CLOSPOS | LABEOV | OPENC | OPENZ |
EOVCTRL | LABERR | OPENV | WLRERR |
LABEND | LABGN | OPENX |
If processing is interrupted by an event for which no EXLST operand is specified, control is passed to the routine addressed via COMMON, except for the operands listed above, which “expect” an intervention in the processing.
For further details see the tables at the end of the EXLST description.
DLOCK
For UPAM processing of disk files only:
Deadlock: further locks, which are not available, have been requested for a job which already has locks active.
Control is passed to the deadlock exit after the waiting time specified in the PAMTOUT operand. The DLOCK routine must first release the “old” locks before new locks can be requested; otherwise, the program will be aborted.
DUPEKY
For ISAM only:
An attempt has been made to write a record into an ISAM file, although the key of this record already exists in the file. This attempt was made:
using the INSRT macro, which must not be used for writing records with duplicate keys, even if DUPEKY=YES is specified in the FILE or FCB macro, or
using the PUT macro, but without DUPEKY=YES specified in the FILE or FCB macro.
EOFADDR
For input files only:
The end of the file was encountered when trying to read a record.
After checking all the labels, DMS activates the EOFADDR routine, in which the user can close the file.
EOVCTRL
This exit must be specified in order to transfer control from the system to the user after a new tape volume has been mounted.
For input files:
This exit is activated only for multivolume files. It is called for every continuation tape only after the system has checked the standard header labels on the continuation tape and the user has (if necessary) checked his own labels in the LABGN exit.
For output files:
This exit is activated only in the case of multivolume files, and only for the continuation tapes, after the system has finished checking and writing the standard header labels (VOL, HDR).
This exit is left by specifying the EXRTN macro.
ERRADDR
During file processing, a hardware error or abnormal I/O termination has occurred. The status byte, the standard device bytes, the Executive flag byte (EFB) and the three sense bytes are stored in the FCB. For ISAM processing, this exit may indicate that ISAM blocks are inconsistent (SAM uses the exits EOFADDR, ERROPT, USERERR).
ERROPT
For SAM input files:
A parity error occured while reading a block: DMS makes several attempts to read the block again before flagging it as errored and attempting to branch to the ERROPT routine. If no ERROPT error exit is provided, the program is terminated. In the EXLST macro, the user can choose to ignore the error, to skip the block or to handle the error in an ERROPT routine.
For SAM output files:
ERROPT is relevant only if no WLRERR exit has been defined and records of incorrect length occur.
= SKIP
The faulty block is skipped, i.e. no records from this block are made available to the program for processing. The next block is read and processing continues with the first record of this block.
= IGNORE
The error condition is ignored and the records from the block are made available to the user program for further processing.
= relexp
Symbolic address of a user routine. This routine must not contain any GET macros for the file containing the faulty block. The routine may evaluate register 0, which contains the address of the errored block, and set a flag for further processing (also in register 0). Normal processing is resumed by means of the EXRTN macro.
If general-purpose register 0 contains the value X'00000001', the current block is skipped and processing continues with the next block. Any other code signifies that the current block is to be processed as if no error had occurred.
ISPERR
For ISAM files with index and data sections on different private disks:
Not enough space is available for extending the index section (for this type of ISAM file, the space can be extended separately for the index and data sections (see the FILE macro)).
LABEND
For tape files:
For checking/writing user file trailer labels; if this exit is not used, the system ignores all user labels.
For input files:
After encountering the end of the file, the system activates the LABEND exit before activating the EOFADDR exit. In the LABEND routine, the user can check his end-of-file labels (UTL). The system provides him/her with the address of a UTL in register 0.
In the case of input files with nonstandard labels, the LABEND exit provides the user with a means of reading and checking his/her labels, if present, when the EOF condition is encountered.
For output files:
The LABEND exit is activated for the purpose of writing user labels after the file has been closed by the user and the end-of-file labels (EOF) have been written. The system supplies the user, in register 0, with an address at which the user trailer labels (UTL) must be made available.
In the case of output files with nonstandard labels, the user, after issuing the CLOSE macro, receives control at this exit for the purpose of writing the nonstandard labels.
Once control has been returned to the system (via the LBRET macro), CLOSE processing is completed.
LABEOV
For tape files:
For checking/writing user trailer labels.
For input files:
This exit is activated after EOF has been encountered and the trailer labels have been written. The user can check the user labels (UTL) here. The system provides the user with the address of a UTL in register 0.
In the case of input files with nonstandard labels, this exit enables the user to read and check the user labels following his/her file, if there are any such labels.
For output files:
This exit is activated when EOV is encountered (or is explicitly requested by the user via the FEOV macro) and after the EOV labels have been written. The system provides an address in register 0 at which the user must make his/her trailer labels (UTL) available.In the case of output files with nonstandard labels, the user receives control from the system via this exit either after EOV is encountered or when a FEOV macro is issued, in order to write his/her labels.
Users working with the BTAM access method must issue an FEOV macro after encountering the end of the tape in the ERRBYTE field. SAM initiates EOV processing automatically.
After control has been returned to the system (by means of the LBRET macro), a tape swap can be executed.
LABERR
For tape files:
For files with standard labels, the system branches to this exit if an error occurs during end-of-tape processing.
One of the following error codes is placed in the ID1ECB field of the FCB:
X'0DE9' | A tape mark was read instead of the expected EOV/EOF labels. |
X'0DEA' | A record other than the expected EOV/EOF label was read. |
X'0DEB' | End-of-tape (double tape mark) was encountered without the expected EOV/EOF labels being read. |
X'0DEC' | The check of the block count was negative. |
The user must return control to the system by means of the EXRTN macro.
Register 0 must contain one of the following values in order to notify the system of how it is to proceed:
X'00' | Perform a tape swap as if the correct EOV/EOF labels had been read. |
X'01' | Terminate the task with an error. |
X'02' | Perform EOF processing. |
If the LABERR exit is not used and one of the conditions described above occurs, the system sends the user an error message. (S)he can then either continue the program or activate a CLOSE routine.
If this exit is not specified, the system ignores user labels for input files, and no user labels can be created for output files.
LABGN
For tape files:
For input files:
The LABGN exit is activated after the standard header labels (VOL, HDR) have been checked; the user header labels (UHL) can be checked in the LABGN routine. The address of the label in the buffer is passed to the user program in register 0. If the file contains nonstandard labels, the user can read and check his/her labels in the LABGN routine.
For output files after OPEN processing and after checking and writing the standard header label:
The system provides the user, in register 0, with the address at which he must make his labels (UHL) available. If the file is to have nonstandard labels, these can be written in the LABGN routine.
When control is returned to the system (by means of the LBRET macro), the tape must be positioned either before the first data block (for OPEN=REVERSE) or after the last data block (for OPEN=EXTEND). If TPMARK=YES was specified, the tape is rewound by one tape mark for OPEN INPUT or wound forward by one tape mark for OPEN REVERSE. If TPMARK=NO was specified, the system assumes that the tape is positioned before the first data block.
LOCK
The file is locked: it cannot be opened because it has already been opened by another job and the OPEN modes are incompatible, i.e. at least one of the jobs has requested an OPEN mode other than INPUT.
NODEV
Either no device on which the private volume could be mounted is free, or the private volume is already being used by another user (it is advisable to reserve devices beforehand).
NOFIND
For ISAM:
The action macro GETKY, ELIM (with KEY specified) or GETFL could not be executed successfully:
GETKY / ELIM: there is no record with the specified key in the file
GETFL: the specified file range contains no records which match the flag conditions.
NOSPACE
For disk files:
The required storage space cannot be provided.
OPENC
The file was opened earlier as an output file but was not closed properly. The VERIF macro can be used in the OPENC routine to close the file and restore its consistency. Field ID1ECB in the FCB contains DMS error code X'0DD1'. If no OPENC exit is specified, the system continues with OPEN processing.
OPENER
An error occurred when opening a file (e.g. inconsistent FCB). An error code describing this condition more precisely is stored in the FCB.
OPENV
For tape files:
For files with standard labels:
This exit is used to check (for input files) or write (for output files) the UVL labels.
DMS provides, in register 0, the address where the label can be found for input files or where the label must be made available by the user for output files. For output files, OPENV can be used for positioning or for writing up to 9 user labels (UVL). The user can issue any BTAM macros which may be required.
For input files with nonstandard labels:
The OPENV exit enables the user to read and check his/her volume header labels (VOL), if any.
Before returning control to the system (via the EXRTN macro), the user must position the tape before the file header labels (HDR), if any. Positioning can also be carried out with the FSEQ operand (see the FILE or FCB macro).
The user is responsible for correct positioning. The user program cannot perform tape swaps during positioning.
OPENX
The FCB has already been updated, during OPEN processing, on the basis of values in the TFT or the catalog. The program can now check that all parameters are set such that OPEN processing can be completed without errors. If OPEN=OUTPUT/OUTIN, the FCB is updated on the basis of the TFT, but the catalog entry is not updated.
Processing can be continued after calling the EXRTN macro.
OPENZ
For files being opened in OUTPUT or OUTIN mode, catalog processing has already been completed when this exit is activated, but the remaining OPEN processing must still be performed. In the OPENZ routine, the program can modify the FCB so that processing is possible: the user can, for example, process the file with an access method other than that specified in the catalog.
Processing is continued after the EXRTN macro has been called.
PASSER
An invalid password has been specified for a protected file.
PGLOCK
Only together with SHARUPD=YES for UPAM or ISAM:
Locks requested by the calling job cannot be set, because they are already set by another job. However, there is no danger of a deadlock situation.
UPAM:
The waiting time specified in the PAMTOUT operand of the FCB has elapsed when control is passed to this exit.
ISAM:
If a PGLOCK routine exists, ISAM does not wait for a record lock. If PGLOCK=NO applies, the job is entered in a queue; the user is not informed, in this case, that the record is already locked by another job.
If a file was opened with SHARUPD=YES, control can be passed to this exit during processing of any ISAM macro (except OSTAT). If the PGLOCK exit is taken, the “internal pointer” will be wrong unless the condition is due to a PUTX or ELIM macro (without KEY).
It is therefore imperative that this internal pointer is repositioned before any macro is issued which requires it to be set correctly (e.g. GET, GETR and GETFL). The pointer can be repositioned using the RETRY macro or with one of the ISAM action macros GETKY, SETL, PUT, STORE, INSRT or ELIM (with KEY). If GET, GETR or GETFL is called before the pointer is repositioned, control is passed to the USERERR exit.
If the condition which caused the PGLOCK exit to be taken was due to a PUTX or ELIM macro (without KEY), the data block remains locked and repositioning is not necessary.
SEQCHK
For ISAM:
A record to be added to an ISAM file by means of the PUT macro has a key less than the highest key already present in the ISAM file.
USERERR
The program attempted to execute an illegal or invalid action, such as trying to write to a file opened in INPUT mode, calling a PUTX or ELIM macro (without KEY) for a file opened with SHARUPD=YES, or an invalid PAM operation code.
WLRERR
A record of invalid length was read. In the case of blocked records of fixed length, the record length is regarded as invalid if the block size is not a multiple of the record length defined in the FCB entry RECSIZE (up to the maximum block size defined in the FCB entry BLKSIZE). This permits short blocks of logical records to be read without “invalid record length” being flagged. In the case of variable-length records, the record length is invalid if it no longer matches the record length specified in the block count control field.
For files with record format U, no WLRERR exit needs to be provided, because the record length is not checked in this case.
If a program is given control at this exit, general-purpose register 0 contains the address of the errored block. An EXRTN macro is required if processing is to continue. If register 0 contains X'00000001', the current block is skipped and processing continues with the next block. Any other code signifies that the current block is to be processed as if no error had occurred.
If no special form of error handling is defined for WLRERR and an “invalid record length” event occurs, DMS checks the value of the ERROPT operand:
ERROPT ≠ NO: the “invalid length” record is treated as an errored block and control is passed to the address specified in ERROPT.
ERROPT = NO: the job is aborted.
Programming notes
Registers 14, 15, 0 and 1 are DMS parameter registers. Therefore, unless explicitly stated otherwise, it cannot be assumed that these registers have a defined value when the user receives control at the EXLST exit.
The following tables show which EXLST exits are used, and when:
Error exit | STD | NSTD | ISAM | PAM | BTAM | Spec. | Spec. | Spec. |
CLOSER | A | A | A | A | A | N | N | N |
CLOSPOS | N | A | N | A | A | N | A | A |
DLOCK | N | N | N | A | N | A | N | A |
DUPEKY | N | N | A | N | N | A | N | A |
EOFADDR | A | A | A | A(1) | A(2) | A | N | A |
EOVCTRL | A | A | N | N | A | A | A | N |
ERRADDR | A | A | A | A | A | A | N | A |
ERROPT | A | A | N | N | N | A | A | N |
ISPERR | N | N | A | N | N | A | N | A |
LABEND | A | A | N | A | A | X | A | A(3) |
LABEOV | A | A | N | A | A | X | A | A(3) |
LABERR | A | X | N | A | A | X | A | A(3) |
LABGN | A | A | N | A | A | X | A | A(3) |
LOCK | A | A | A | A | N | N | N | A |
NODEV | A | A | A | A | A | N | N | N |
NOFIND | N | N | A | N | N | A | N | A |
NOSPACE | A | N | A | N | N | A | N | A/N(SAM) |
OPENC | A | N | A | A | N | N | N | Try VERIF |
OPENER | A | A | A | A | A | N | N | N |
OPENV | A | A | N | A | A | X | A | A(3) |
OPENX | A | A | A | A | A | A | A | N |
OPENZ | A | A | A | A | A | A | A | N |
PASSER | A | A | A | A | A | N | N | N |
PGLOCK | N | N | A | A | N | A | N | A |
SEQCHK | N | N | A | N | N | A | N | A |
USERERR | A | A | A | A | A | A | N | A |
WLRERR | A | A | N | N | N | A | A | N |
Meanings of the entries
EXLST | COMMON | FCB code | 1) | Meaning |
CLOSER | Z | 2C | A | File regarded as closed |
CLOSPOS | N | 70 | N | Only for files with standard labels |
DLOCK | Z | 3C | A | No further locks until all existing locks are cleared |
DUPEKY | Z | 54 | A | |
EOFADDR | Z | 40 | A | |
EOVCTRL | N | 34 | N | |
ERRADDR | Z | 44 | A | Error code and/or end byte (PAM and BTAM) |
ERROPT | N | 48 | A | End byte stored in FCB |
ISPERR | Z | 50 | A | |
LABEND | N | 30 | N | File regarded as closed |
LABEOV | N | 28 | N | - |
LABERR | N | 6C | N | Only for files with standard labels |
LABGN | N | 24 | N | - |
LOCK | Z | 10 | A | |
NODEV | Z | 14 | A | |
NOFIND | Z | 58 | A | |
NOSPACE | Z | 4C | A | |
OPENC | N | 68 | N | |
OPENER | Z | 08 | A | Error code stored in FCB |
OPENV | N | 1C | N | |
OPENX | N | 04 | N | |
OPENZ | N | 18 | N | |
PASSER | Z | 0C | A | |
PGLOCK | Z | 38 | A | |
SEQCHK | Z | 60 | A | |
USERERR | Z | 5C | A | Error code stored in FCB |
WLRERR | N | 64 | N | End byte stored in FCB |
where: | |
A | Allowed |
X | Not allowed |
Z | Applicable |
N | Not applicable |
(1) | Only for *DUMMY files |
(2) | Only used with FEOV |
(3) | Only if LABEL=NSTD is specified. |
1) | The program is terminated if the exit is not defined and the event occurs. |