This API lets obtain a chunk of a list of entities. They are of four kinds:
PAA objects,
PAC objects,
PAC meta entities - JCL texts, migrations lists and audit reports,
common objects
PAA and PAC objects are classified into four groups:
DDMs,
error messages,
foreign objects,
Natural objects.
PAC meta entities are classified into two groups:
JCL texts,
migration events.
Common objects are classified into three groups:
DDMs,
error messages,
Natural objects.
APINENTS can be invoked with:
CALLNAT 'APINENTS' API-PARM API-ENTS-PARM
To obtain a chunk, set API-PARM.API-MAIN-FUNC at 'S'. API-PARM.API-SUB-FUNC is not used by APINENTS.
This document covers the following topics:
A definition of API-ENTS-PARM is provided in LDA UPILENTS.
| Field Name | Format | Description | |
|---|---|---|---|
| API-ENTS-PARM | |||
| KIND | A1 | in | |
| DBNR | B2 | in | |
| FNR | B2 | in | |
| TYPE | A18 | in | |
| TYPE1 | A1 | in | |
| TYPE2 | A16 | in | |
| TYPE3 | A1 | in | |
| E-BYTE | A1 | in | |
| LIBRARY | A8 | in | |
| COMPARTMENT | B2 | in/out | |
| APPLICATION | A32 | in | |
| LOC-LIBRARY | A8 | in | |
| LOC-DBNR | B2 | in | |
| LOC-FNR | B2 | in | |
| LOC-ESY-NODE | N5 | in | |
| LOC-PDS | A54 | in | |
| LOC-VOL-TYPE | A6 | in | |
| NAME | A33 | in | |
| C-VERSION-FM | N5 | in | |
| C-VERSION-TO | N5 | in | |
| A-VERSION-FM | N5 | in | |
| A-VERSION-TO | N5 | in | |
| DDM-DBNR-COND-K | A1 | in | |
| DDM-DBNR-COND-M | A5 | in | |
| DDM-DBNR-COND-L | N5 | in | |
| DDM-DBNR-COND-U | N5 | in | |
| DDM-FNR-COND-K | A1 | in | |
| DDM-FNR-COND-M | A5 | in | |
| DDM-FNR-COND-L | N5 | in | |
| DDM-FNR-COND-U | N5 | in | |
| TIME-FM | T | in | |
| TIME-TO | T | in | |
| USER | A9 | in | |
| STATUS | A32 | in | |
| EVENT | A33 | in | |
| CURRENT-ON | T | in | |
| STATUS-FM | A33 | in | |
| STATUS-TO | A33 | in | |
| UAPPLICATION | A32 | in | |
| JOB-FM | N10 | in | |
| JOB-TO | N10 | in | |
| STATE | A1 | in | |
| LINE-CNT | N3 | out | |
| LINE-TOT | N3 | in/out | |
| LINE | A250 (1:60) | out | |
| API-PAC-AREA | A160 | in/out | |
Whenever APINENTS is called, [API-ENTS-PARM.KIND] should be:
| A | for a list of PAA objects, |
| C | for a list of PAC objects, |
| E | for a list of PAC meta entities, or |
| M | for a list of common objects. |
[API-ENTS-PARM.DBNR] and [API-ENTS-PARM.FNR] must specify an FPAA, an ACF, an ACF, or an FUSER (FNAT) or FDIC respectively.
[API-ENTS-PARM.TYPE1] should be:
| D | for DDM, |
| E | for error message, |
| F | for foreign, |
| J | JCL text, |
| M | migration event, or |
| N | Natural. |
The six possible settings of API-ENTS-PARM.TYPE1 can be usefully combined with the following values of API-ENTS-PARM.TYPE3:
| TYPE1 | TYPE3 | |
|---|---|---|
| D | ' ' | for DDMs themselves, |
| B | for the USED BY lists (of DDMs in a PAC compartment). | |
| E | ' ' | for error messages themselves, |
| B | for the USED BY lists (of DDMs in a PAC compartment). | |
| F | L | for loadables, |
| S | for sources. | |
| J | ' ' | . |
| M | A | for the audit reports, |
| I | for the migration lists. | |
| N | B | for the USED BY lists (of Natural objects in a PAC compartment), |
| L | for loadables, | |
| S | for sources, | |
| U | for the USED lists (of Natural objects in a PAC compartment). |
If [API-ENTS-PARM.TYPE1] = 'F', then API-ENTS-PARM.TYPF2 should carry the PAC foreign type code of the objects to be selected with the leading '3' pared off (eg, '3JCL' would turn into 'JCL').
If [API-ENTS-PARM.TYPE1] = 'N', then API-ENTS-PARM.TYPF2 may carry a sequence of one character external codes of NATURAL types (eg, 'N' for subprogram or 'P' for program).
If [API-ENTS-PARM.TYPE1] = 'E', then API-ENTS-PARM.E-BYTE may carry a one character language code; this will restrict the selection to long error messages in the language specified.
If [API-ENTS-PARM.KIND] = 'M' and ([API-ENTS-PARM.TYPE1] = 'N' or [API-ENTS-PARM.TYPE1] = 'E'), then API-ENTS-PARM.LIBRARY should carry the name of the library whose objects are to be listed.
API-ENTS-PARM.COMPARTMENT should be reset at the first call for a list of PAC objects or events and may be left alone at the subsequent calls for the same list.
If [API-ENTS-PARM.KIND] = 'C' then API-ENTS-PARM.APPLICATION should carry the name of the PAC (ACF) compartment whose objects are to be listed. If [API-ENTS-PARM.KIND] = 'A' or ([API-ENTS-PARM.KIND] = 'E' and [API-ENTS-PARM.TYPE1] = 'M') then API-ENTS-PARM.APPLICATION may carry the name of a PAC compartment.
If [API-ENTS-PARM.KIND] = 'A', then the five LOC-... fields should carry the specification of the PAA location whose objects are to be listed.
API-ENTS-PARM.NAME should carry the specification of a range into which the names of the entities to be selected must fit.
If [API-ENTS-PARM.KIND] = 'A' or 'C', then API-ENTS-PARM.C-VERSION-FM and API-ENTS-PARM.C-VERSION-TO may carry the specification of an interval into which the PAC version numbers of the objects to be selected must fit. [API-ENTS-PARM.C-VERSION-TO] = 0 does not impose an upper bound on the PAC version numbers of the objects being selected.
If [API-ENTS-PARM.KIND] = 'A', then API-ENTS-PARM.A-VERSION-FM and API-ENTS-PARM.A-VERSION-TO may carry the specification of an interval into which the PAA version numbers of the objects to be selected must fit. [API-ENTS-PARM.A-VERSION-TO] = 0 does not impose an upper bound on the PAA version numbers of the objects being selected.
If [API-ENTS-PARM.TYPE1] = 'D', then the eight DDM-... fields may carry the specification of conditions imposed on the data base and file numbers of the files whose DDMs are to be listed. A condition is imposed on such a number if the corresponding ...COND-K field carries 'B' (between), 'G' (greater or equal), 'L' (less or equal), 'M' (mask only), 'O' (strictly outside). In any of these cases the number must fit the mask specified in the corresponding ...COND-M field, decimal digits and '.', which will match any digit in the number, being the characters acceptable in a mask. If [...COND-K] = 'M', then the mask is the only condition imposed on the number. In the other cases the number must additionally fit into or, with 'O', outside the specified interval. The lower bound should be specified in ...COND-L and the upper bound in ...COND-U. Thus [...COND-K] = 'L' makes [...COND-U] relevant, and [...COND-K] = 'G' makes [...COND-L] relevant.
If [API-ENTS-PARM.KIND] = 'E' or ([API-ENTS-PARM.KIND] = 'M' and [API-ENTS-PARM.TYPE1] = 'N') then an interval for entity latest modification times may be specified in API-ENTS-PARM.TIME-FM and API-ENTS-PARM.TIME-TO. Values achieved by resetting do not impose bounds on the times of the entities being selected.
If [API-ENTS-PARM.KIND] = 'E' or ([API-ENTS-PARM.KIND] = 'M' and [API-ENTS-PARM.TYPE1] = 'N'), then a range of user ids may be specified in API-ENTS-PARM.USER. Such specification will restrict the selection of entities to those last modified by users whose ids fit into the range.
If [API-ENTS-PARM.KIND] = 'A' or 'C', then a single status may be specified in API-ENTS-PARM.STATUS.
If [API-ENTS-PARM.KIND] = 'C', then a range of events names may be specified in API-ENTS-PARM.EVENT. This will restrict the selection of PAC objects to those immigrated ([API-ENTS-PARM.STATUS] = ' ') or emigrated ([API-ENTS-PARM.STATUS] NE ' ') with an appropriately named event.
If [API-ENTS-PARM.KIND] = 'A' or 'C', then a single time may be specified in API-ENTS-PARM.CURRENT-ON. The specification will restrict the selection of PAA or PAC objects to those known to be or have been the current (PAA) or the highest numbered non-superseded (PAC) version at the time specified.
If [API-ENTS-PARM.KIND] = 'E' and [API-ENTS-PARM.TYPE1] = 'M', then ranges of origin and destination status names may be specified in [API-ENTS-PARM.STATUS-FM] and [API-ENTS-PARM.STATUS-TO] respectively.
If [API-ENTS-PARM.KIND] = 'C' and [API-ENTS-PARM.TYPE3] = 'B' or 'U', then a single PAC compartment may be specified in API-ENTS-PARM.UAPPLICATION. The specification will restrict the selection of PAC objects to those (known to be) used by (B) or using (U) an object in the specified compartment (of the specified application).
If [API-ENTS-PARM.KIND] = 'A', then an interval of PAA job numbers may be specified in API-ENTS-PARM.JOB-FM and API-ENTS-PARM.JOB-TO The specification will restrict the selection of PAA objects to those belonging to PAA jobs of appropriate numbers. [API-ENTS-PARM.JOB-TO] = 0 does not restrict the selection.
If [API-ENTS-PARM.KIND] = 'A' or ([API-ENTS-PARM.KIND] = 'E' and [API-ENTS-PARM.TYPE1] = 'M'), then a single PAA object state or PAC event state respectively may be specified in API-ENTS-PARM.STATE. The specification will restrict the selection of PAA objects or PAC events to those in the specified state.
PAA object state codes are:
| B | backed up |
| C | current |
| H | historical |
| R | removed |
| S | scheduled |
PAC event state codes are:
| A | authorized |
| B | backed out |
| C | completed |
| P | pending |
| S | started |
| U | submitted |
| V | validated |
[API-ENTS-PARM.LINE-CNT] is made 0, if negative; it is made 60, if greater than 60. It is then interpreted as the number of lines (the size of the chunk) to be returned. In particular, no lines will be returned, if LINE-CNT EQ 0. APINENTS returns in API-ENTS-PARM.LINE-CNT the number of lines of the returned chunk. It may be less than the adjusted original value, if the end of the list has been reached.
Normally, API-ENTS-PARM.LINE-TOT should be reset when the first chunk of a list is wanted and left untouched until the processing of the list is finished. It will then after each call carry the total of list entries already returned.
API-ENTS-PARM.LINE will carry the returned chunk.
Normally, API-ENTS-PARM.API-PAC-AREA should be reset when the first chunk of a list is wanted. API-ENTS-PARM.API-PAC-AREA should be left untouched for a next call to obtain an immediately following chunk of the list.
APINENTS returns the following [API-PARM.API-MSG-NO]:
| 0000 | if a non-final chunk of a list is being returned. |
| 0070 | if no entities satisfying the selection criteria have been found. |
| 1011 | if the specified [API-PARM.API-MAIN-FUNC] is meaningless (ie, is not 'S'). |
| 9999 | if at least one entity satisfying the selection criteria has been found and a final chunk of a list is being returned. |
Other values of API-PARM.API-MSG-NO may be received in more unusual situations.