The user program must have two storage areas for data transfer when the MAREN program interface MARENPS is called:
Statement area (maximum of 1014 bytes);
Here the user program must provide a MAREN statement in the form of a variable-length record (record length field of 4 bytes) using the usual BS2000 format. The statement can be written with or without the two slashes. The statement area must be aligned on a halfword boundary.
Catalog entry area (1014 bytes).
In this area, MAREN transfers either a complete catalog entry or merely the catalog entry fields RETFLAG and ERRORKEY to the user program, depending on the statement. The individual catalog entry fields can be symbolically addressed via the Dsect MARENA or the copy element MARENAC.
The catalog entry is returned either in V8 format (1014 bytes). The secondary index area of a catalog in V8.1 format is not supported at the program interface.
When calling the program interface, the contents of the catalog entry area are of no significance.
The MARENA macro generates a DSECT for symbolic address of the individual catalog entry fields. The MARENA macro is also contained in the SYSLIB.MAREN.<ver> library. If the operand MF=L is specified in the macro call, a data area is created with the same length as the catalog entry with field designations identical to the names in the relevant DSECT.
The COPY statement can be used to copy the source element MARENAC into a COBOL source program. MARENAC defines the MAREN catalog entry. The copy element MARENAC is also contained in the library SYSLIB.MAREN.<ver>.
Once a statement has been executed, MARENPS automatically reverts to the user program. The RETURN-TO-PROGRAM statement is therefore superfluous in this case. The END statement closes the MAREN files if they were opened in direct access mode.
Specification of a number range, which is possible for some statements using the operand VOLUME=*INTERVAL(FROM=..., TO=...,FSEQ=...), is also supported by the program interface. However, only the first applicable catalog entry is processed, after which control is immediately passed back to the caller. If necessary, the user program must repeat the statement in a loop, each time setting the start of the number range (FROM operand and FROM-FSEQ operand) to the last archive number obtained and incrementing FSEQ.Please note the following when incrementing FSEQ: if only one catalog entry per archive number is to be processed, FSEQ must be set at 9999. If, however, all available FSEQ entries are to be processed for each archive number, FSEQ must be incremented by 1 except if FSEQ=*001 (temporarily locked tape).
Return codes
After each return from the MAREN program interface, the user program must inspect the return information in the catalog entry field RETFLAG. Only when RETFLAG=A applies has the statement been executed normally. RETFLAG=E means that no hits were made in the specified number range. For all other RETFLAGs, additional return information in the catalog entry field ERRORKEY must be evaluated. This field contains the seven-digit message code of the message otherwise output to SYSOUT by the MAREN program.
RETFLAG may be set to the following values:
| RETFLAG | Meaning |
| A | The statement was executed without errors. |
| D | A DMS error occurred while accessing a file. The name of the specified file is contained in the catalog entry field FILENAME. The DMS error code is contained in the catalog entry field ERRORKEY. |
| E | No hit was found within the specified number range |
| I | Invalid entry. |
| L | Logical error, e.g. an attempt was made to export a tape which has already been exported. |
| M | Internal error in MAREN; the exact cause of the error is shown in the catalog entry field ERRORKEY. |
| N | The specified archive number does not exist in the MAREN catalog. |
| O | The MAREN administrator has activated offline logging; as a result, access to the MAREN catalog is not possible. |
| P | The catalog entry was simultaneously modified by another task; the statement must therefore be repeated. |
| S | Access to another system via MSCF was not successful. |
| T | The tape is still reserved by another task in the same system. |
| V | The tape has not yet been released by another task in another system, i.e. the internal MAREN access lock on this tape still exists. |
| X | The request was rejected by the MAREN administrator via a exit routine. |
| 0 | The console message MAR0085 was acknowledged by the operator with tsn.0. |
| 2 | The console message MAR0085 or MAR0086 was acknowledged by the operator with tsn.2. |
The following registers must be loaded to enter the subroutine:
Register 1: | This register contains the address of an operand list with a length of two words: |
Register 13: | This register contains the address of a save area which consists of 18 words and which must be made available by the calling user program. This area is used by MAREN to save the registers of the calling program. |
Register 14: | This register contains the address of the re-entry point to the calling program. |
Register 15: | This register contains the entry point address of MARENPS. |