The user program must have three storage areas for data transfer when the MARENADM program interface MAREN1PS is called:
Statement area (maximum of 1014 bytes)
Here the user program must provide a MARENADM 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).
Parameter set area (672 bytes)
In this area, the user program receives the complete parameter set output by the SHOW-MAREN-PARAMETERS statement. The individual fields may be addressed symbolically via the Dsect MARENP or the copy element MARENPL. This area must also be provided for every other statement, since MAREN1PS requires it as an internal work area.
When calling the program interface, the contents of the catalog entry and of the parameter set area are of no significance.
The MARENA macro generates a DSECT for symbolic address of the individual catalog entry fields. The MARENP macro generates a DSECT for symbolic addressing of the individual fields of the MAREN parameter set. The two macros (MARENAC and MARENPL) are 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 or the parameter set 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 statement can be used to copy the source element MARENPC into a COBOL source program. MARENPC defines the MAREN parameter set. The two copy elements (MARENAC and MARENPL) are also contained in the library SYSLIB.MAREN.<ver>.
Once a statement has been executed, MAREN1PS 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 VSN obtained and incrementing FSEQ. Please note the following when incrementing FSEQ: if only one catalog entry per VSN is to be processed, FSEQ must be set at 9999. If, however, all available FSEQ entries are to be processed for each VSN, FSEQ must be incremented by 1 except if FSEQ=*001 (see example on "Examples").
Return codes
After each return from the MARENADM program interface MAREN1PS, the user program must inspect the return information in the catalog entry field RETFLAG. Only when RETFLAG=A applies the statement has 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 MARENADM 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 VSN 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 an 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 three words: First word: Address of the statement area Second word: Address of the archive record area Third word: Address of the parameter set area |
| 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 MARENADM 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 MAREN1PS. |