Application Programming Interfaces

#### Search Results

Search

# Application Programming Interfaces

Predict Application Audit delivers eight APIs for the PAA system. All of these are retrieval APIs.

Using APINADPS, APINALOS, APINAJOS, and APINAOBS you can select deployments, locations, jobs, and objects respectively by various combinations of criteria; all four return the numbers of the selected entities. These numbers are the job numbers in the case of jobs; they are "internal" numbers for deployments, locations, and objects.

Using APINADPD, APINALOD, APINAJOD, and APINAOBD you can retrieve information about a deployment, a location, a job, and an object respectively; the number of the entity has to be provided as the principal "in" parameter.

The eight Natural subprogram modules reside in library SYSPAA. Definitions of their parameter structures are provided in local data areas whose source and loadable parts reside in library SYSPAAUS.

Each of the eight APIs can be invoked thus:

    CALLNAT 'APINA...' API-PARM API-...-PARM

The nine local data areas are UPILPARM, UPILADPD, UPILADPS, UPILALOD, UPILALOS, UPILAJOD, UPILAJOS, UPILAOBD, and UPILAOBS.

The following list shows the structure in UPILPARM:

         1     API-PARM
         2     API-FUNC          A      2     in
    R    2     API-FUNC
         3     API-MAIN-FUNC     A      1
         3     API-SUB-FUNC      A      1
         2     API-MSG-NO        P      5        out
         2     API-MSG           A     78        out
         2     API-USER-AREA     A     50     in/out

API-USER-AREA is not used by any of the eight APIs; it may come into use in future releases or versions, if PAA should acquire user exits reachable from the APIs. The eight other structures are given in the following sections.

- APINADPD

- APINADPS

- APINAJOD

- APINAJOS

- APINALOD

- APINALOS

- APINAOBD

- APINAOBS

## APINADPD

Using this API you obtain data from a deployment.

Each PAA deployment has an "internal" number. APINADPD requires the specification of one such number; it then produces information about the deployment. The numbers of PAA deployments can be obtained from APINADPS.

APINADPD corresponds to the Display Deployment functions of the menu system.

Use the following syntax to invoke the API:

    CALLNAT 'APINADPD' API-PARM API-ADPD-PARM

To obtain data from a deployment, set [API-PARM.API-MAIN-FUNC] = 'D'.

The value of API-PARM.API-SUB-FUNC is ignored. A definition of API-ADPD-PARM is provided in LDA UPILADPD.

         1     API-ADPD-PARM
         2     NUMBER               N     10          in
         2     APPLICATION          A     32              out
         2     STATUS               A     32              out
         2     NAT-LOCATION-CNT     N     3               out
         2     NAT-LOCATION         A     38 (1:24)       out
    R    2     NAT-LOCATION
         3     NAT-NUMBER           N     10
         3     NAT-LIBRARY          A     8
         3     NAT-FUSER-DBNR       N     5
         3     NAT-FUSER-FNR        N     5
         3     NAT-FDIC-DBNR        N     5
         3     NAT-FDIC-FNR         N     5
         2     PRD-LOCATION-CNT     N     3              out
         2     PRD-LOCATION         A     20 (1:24)      out
    R    2     PRD-LOCATION
         3     PRD-NUMBER           N     10
         3     PRD-FDIC-DBNR        N     5
         3     PRD-FDIC-FNR         N     5
         2     FRG-LOCATION-CNT     N     3              out
         2     FRG-LOCATION         A     86 (1:24)      out
    R    2     FRG-LOCATION
         3     FRG-NUMBER           N     10
         3     FRG-TYPE             A     4
         3     FRG-FORMAT           A     1
         3     FRG-ESY-NODE         N     5
         3     FRG-OP-SYSTEM        A     8
         3     FRG-PDS              A     60
         2     MIGRATE-DATE         T                   out
         2     ADD-DATE             T                   out
         2     ADD-USER             A     8             out
         2     ADD-TID              A     8             out
         2     MAINT-DATE           T                   out
         2     MAINT-USER           A     8             out
         2     MAINT-TID            A     8             out
         2     HOLD-DATE            T                   out
         2     HOLD-USER            A     8             out
         2     HOLD-TID             A     8             out
         2     HOLD-RECOVERY        A     50            out

When APINADPD is called:

- API-ADPD-PARM.NUMBER
  should carry the number of the deployment whose data are to be retrieved.

  If [API-PARM.API-MAIN-FUNC] = 'D' and the deployment is found, APINADPD returns in the remaining parameter fields the deployment data.

  [API-ADPD-PARM.NAT-LOCATION-CNT] is the number of the deployment's Natural locations. Their numbers, names, and some additional data are returned in API-ADPD-PARM.NAT-LOCATION(1:[API-ADPD-PARM.NAT-LOCATION-CNT]).

  [API-ADPD-PARM.PRD-LOCATION-CNT] is the number of the deployment's Predict locations. Their numbers and names are returned in API-ADPD-PARM.PRD-LOCATION(1:[API-ADPD-PARM.PRD-LOCATION-CNT]).

  [API-ADPD-PARM.FRG-LOCATION-CNT] is the number of the deployment's foreign locations. Their numbers, names, and some additional data are returned in API-ADPD-PARM.FRG-LOCATION(1:[API-ADPD-PARM.FRG-LOCATION-CNT]).

  Each element of API-ADPD-PARM.FRG-PDS contains a fifty-four-character PDS name and, possibly, operating system specific data like a volume (z/OS).

APINADPD returns the following [API-PARM.API-MSG-NO]:

1011 | If [API-PARM.API-MAIN-FUNC] other than 'D' has been specified,
7250 | If the location has been found,
7251 | If a location with the given number has been sought but has not been found.

## APINADPS

Using this API you obtain chunks of lists of deployment numbers.

Each PAA deployment has an "internal" number, which is of no interest to the users of the menu system. However, APINADPD, the API that enables you to retrieve the data of a particular deployment, requires the specification of a single deployment number. APINADPS enables users to obtain the numbers of all deployments whose names satisfy the specified selection criteria.

APINADPS corresponds to the Select Deployments functions of the menu system and to the REPORT DEPLOYMENT direct commands. Unlike them, it produces only the numbers of the deployments. These numbers can then be used as input to APINADPD, which in turn corresponds to the Display Deployment functions of the menu system.

Use the following syntax to invoke APINADPS:

    CALLNAT 'APINADPS' API-PARM API-ADPS-PARM

To obtain a chunk of a list of deployment numbers, set [API-PARM.API-MAIN-FUNC] = 'S'.

The value of API-PARM.API-SUB-FUNC is ignored.

A definition of API-ADPS-PARM is provided in LDA UPILADPS.

         1     API-ADPS-PARM
         2     APPLICATION     A     32        in
         2     STATUS          A     32        in
         2     NUMBER-CNT      N     3         in/out
         2     NUMBER          N     10 (1:60)    out
         2     API-PAC-AREA    A     145       in/out

When APINADPS is called:

- API-ADPS-PARM.APPLICATION
  should carry a range of application names or be blank.

  A blank API-ADPS-PARM.APPLICATION has the same effect on the selection as one carrying an initial asterisk.

- API-ADPS-PARM.STATUS
  should carry a range of status names or be blank, if API-ADPS-PARM.APPLICATION in fact carries an application name.

  The value of API-ADPS-PARM.STATUS is ignored, if API-ADPS-PARM.APPLICATION is blank or carries a range of application names which is not an application name.

  A blank API-ADPS-PARM.STATUS has the same effect on the selection as one carrying an initial asterisk.

- [API-ADPS-PARM.NUMBER-CNT]
  is made 0, if negative; it is made 60, if greater than 60. It is then interpreted as the maximum number of deployment numbers to be returned; no deployment numbers will be returned, if API-ADPS-PARM.NUMBER-CNT = 0.

- API-ADPS-PARM.PAC-AREA
  should be reset when the first chunk of a list of deployment numbers is wanted. API-ADPS-PARM.PAC-AREA should be left untouched for a next call to obtain an immediately following chunk of the same list.

APINADPS returns in API-ADPS-PARM.NUMBER-CNT the number of deployment numbers in the returned chunk; it may be less than the adjusted original value, if the end of the deployment number list has been reached. If no deployment satisfying the selection criteria is found or a non-positive [API-ADPS-PARM.NUMBER-CNT] has been specified then APINADPS returns 0 in API-ADPS-PARM.NUMBER-CNT.

If APINADPS returns a non-zero [API-ADPS-PARM.NUMBER-CNT] then it returns the chunk of the list of the numbers of the deployments satisfying the selection criteria in API-ADPS-PARM.NUMBER(1:[API-ADPS-PARM.NUMBER-CNT]).

APINADPS returns the following [API-PARM.API-MSG-NO]:

0000 | If at least one deployment satisfying the selection criteria has been found and a non-final chunk of a list of the numbers of the deployments satisfying the selection criteria is being returned,
0070 | If deployments satisfying the selection criteria have been sought but none has been found,
1011 | If [API-PARM.API-MAIN-FUNC] other than 'S' has been specified,
9999 | If at least one deployment satisfying the selection criteria has been found and a final chunk of a list of the numbers of the deployments satisfying the selection criteria is being returned.

## APINAJOD

This PAA API enables you to obtain data from a PAA job. The value of API-PARM.API-SUB-FUNC is ignored.

APINAJOD requires the specification of one job number; it then produces information about the job. The numbers of the PAA jobs satisfying various selection conditions can be retrieved with APINAJOS.

APINAJOD corresponds to the Display Job functions of the menu system.

APINAJOD can be invoked thus:

    CALLNAT 'APINAJOD' API-PARM API-AJOD-PARM

To obtain data from a job, set [API-PARM.API-MAIN-FUNC] = 'D'.

A definition of API-AJOD-PARM is provided in LDA APILAJOD.

         1     API-AJOD-PARM
         2     NUMBER               N     10    In
         2     DEPL-NUMBER          N     10       Out
         2     APPLICATION          A     32       Out
         2     STATUS               A     32       Out
         2     STATE                A     10       Out
         2     ORIGIN-STATUS        A     32       Out
         2     EVENT                A     32       Out
         2     PAC-JOB-NAME         A     8        Out
         2     AUTH-DATE            T              Out
         2     AUTH-USER            A     8        Out
         2     AUTH-TID             A     8        Out
         2     LOAD-USER            A     8        Out
         2     SCHED-DATE           T              Out
         2     ACTIV-DATE           T              Out
         2     ACTIV-USER           A     8        Out
         2     ACTIV-TID            A     8        Out
         2     FINAL-DATE           T              Out
         2     FINAL-USER           A     8        Out
         2     FINAL-TID            A     8        Out
         2     BACKOUT-DATE         T              Out
         2     BACKOUT-USER         A     8        Out
         2     BACKOUT-TID          A     8        Out
         2     ADD-DATE             T              Out
         2     ADD-USER             A     8        Out
         2     ADD-TID              A     8        Out
         2     MAINT-DATE           T              Out
         2     MAINT-USER           A     8        Out
         2     MAINT-TID            A     8        Out
         2     HOLD-DATE            T              Out
         2     HOLD-USER            A     8        Out
         2     HOLD-TID             A     8        Out
         2     HOLD-RECOVERY        A     50       Out

When APINAJOD is called:

- API-AJOD-PARM.NUMBER
  should carry the number of the job whose data are to be retrieved. If [API-PARM.API-MAIN-FUNC] = 'D' and the deployment is found, APINAJOD returns in the remaining parameter fields the job data.

- API-AJOD-PARM.STATE
  contains a designation of the job's state.

The following are possible designations:

- Pending

- Scheduled

- Activated

- Finalized

- Backed out

APINAJOD returns the following [API-PARM.API-MSG-NO]:

1011 | If [API-PARM.API-MAIN-FUNC] other than 'D' has been specified.
7250 | If the job has been found.
7251 | If a job with the given number has been sought but has not been found.

## APINAJOS

This PAA API enables users to obtain chunks of lists of job numbers.

APINAJOD, the API that enables users to retrieve the data of a particular job, requires the specification of a single job number. APINAJOS enables users to obtain the numbers of all jobs, which satisfy the specified selection criteria.

APINAJOS corresponds to the Select Jobs functions of the menu system and to the REPORT JOB direct commands. Unlike them, it produces only the numbers of the jobs. These numbers can then be used as input to APINAJOD, which in turn corresponds to the Display Job functions of the menu system.

APINAJOS can be invoked thus:

    CALLNAT 'APINAJOS' API-PARM API-AJOS-PARM

To obtain a chunk of a list of job numbers, set [API-PARM.API-MAIN-FUNC] = 'S'.

The value of API-PARM.API-SUB-FUNC is ignored.

A definition of API-AJOS-PARM is provided in LDA UPILAJOS.

         1     API-AJOS-PARM
         2     APPLICATION     A     32         in
         2     STATUS          A     32         in
         2     STATE           A     1          in
         2     FROM-DATE       T                in
         2     TO-DATE         T                in
         2     NUMBER-CNT      N     3          in/out
         2     NUMBER          N     10 (1:60)     out
         2     API-PAC-AREA    A     145        in/out

When APINAJOS is called:

- API-AJOS-PARM.APPLICATION
  should carry an application name or be blank.

- API-AJOS-PARM.STATUS
  should carry a status name or be blank. If API-AJOS-PARM.APPLICATION or API-AJOS-PARM.STATUS is not blank then the concatenation of their values is interpreted as the name of the only deployment whose jobs may be selected.

  If both API-AJOS-PARM.APPLICATION and API-AJOS-PARM.STATUS are blank then a job of any deployment may be selected.

- API-AJOS-PARM.STATE
  should carry a character designating the state(s) of the jobs to be selected. The following characters designate job states.

  B | backed out
  F | finalized
  A | activated
  P | purged
  S | scheduled
  space | any

- API-AJOS-PARM.FROM-DATE
  should carry a lower bound of the load times of the jobs to be selected.

- API-AJOS-PARM.TO-DATE
  should carry an upper bound of the load times of the jobs to be selected or 0. If API-AJOS-PARM.TO-DATE = 0 then the selection of jobs are not restricted on the account of this parameter.

- [API-AJOS-PARM.NUMBER-CNT]
  is made 0, if negative; it is made 60, if greater than 60. It is then interpreted as the maximum number of job numbers to be returned; no job numbers will be returned, if API-AJOS-PARM.NUMBER-CNT = 0.

- API-AJOS-PARM.PAC-AREA should be reset when the first chunk of a list of job numbers is wanted.

  API-AJOS-PARM.PAC-AREA should be left untouched for a next call to obtain an immediately following chunk of the same list.

APINAJOS returns in API-AJOS-PARM.NUMBER-CNT the number of job numbers in the returned chunk; it may be less than the adjusted original value, if the end of the job number list has been reached. If no job satisfying the selection criteria is found or a non-positive [API-AJOS-PARM.NUMBER-CNT] has been specified then APINAJOS returns 0 in API-ALOS-PARM.NUMBER-CNT.

If APINAJOS returns a non-zero [API-AJOS-PARM.NUMBER-CNT] then it returns the chunk of the list of the numbers of the jobs satisfying the selection criteria in API-AJOS-PARM.NUMBER(1:[API-AJOS-PARM.NUMBER-CNT]).

APINAJOS returns the following [API-PARM.API-MSG-NO]:

0000 | If at least one job satisfying the selection criteria has been found and a non-final chunk of a list of the numbers of the jobs satisfying the selection criteria is being returned.
0057 | If jobs satisfying the selection criteria have been sought but none has been found.
0070 | If the specified deployment has not been found.
1011 | If [API-PARM.API-MAIN-FUNC] other than 'S' has been specified.
9999 | If at least one job satisfying the selection criteria has been found and a final chunk of a list of the numbers of the jobs satisfying the selection criteria is being returned.

## APINALOD

This PAA API enables users to obtain data from a location.

Each PAA location has an "internal" number. APINALOD requires the specification of one such number; it then produces information about the location. The numbers of PAA locations can be learnt from APINALOS.

APINALOD corresponds to the Display Location functions of the menu system.

APINALOD can be invoked thus:

    CALLNAT 'APINALOD' API-PARM API-ALOD-PARM

To obtain data from a location, set [API-PARM.API-MAIN-FUNC] = 'D'.

The value of API-PARM.API-SUB-FUNC is ignored.

A definition of API-ALOD-PARM is provided in LDA UPILALOD.

          1      API-ALOD-PARM
          2      NUMBER                 N       10          in
          2      KIND-OF-LOC            A       1              out
          2      LOCATION               A       73             out
    R            LOCATION
          3      NAT-LIBRARY            A       8
          3      NAT-FUSER-DBNR         N       5
          3      NAT-FUSER-FNR          N       5
          3      NAT-FDIC-DBNR          N       5
          3      NAT-FDIC-FNR           N       5
    R     2      LOCATION
          3      PRD-FDIC-DBNR          N       5
          3      PRD-FDIC-FNR           N       5
    R     2      LOCATION
          3      FRG-ESY-NODE           N       5
          3      FRG-OP-SYSTEM          A       8
          3      FRG-PDS                A       60
          2      DEPLOYMENT-CNT         N       3              out
          2      DEPLOYMENT             A       74 (1:24)      out
    R     2      DEPLOYMENT
          3      DEPL-NUMBER            N       10
          3      DEPL-APPLICATION       A       32
          3      DEPL-STATUS            A       32
          2      ADD-DATE               T                      out
          2      ADD-USER               A       8              out
          2      ADD-TID                A       8              out
          2      MAINT-DATE             T                      out
          2      MAINT-USER             A       8              out
          2      MAINT-TID              A       8              out
          2      HOLD-DATE              T                      out
          2      HOLD-USER              A       8              out
          2      HOLD-TID               A       8              out
          2      HOLD-RECOVERY          A       50             out

When APINALOD is called:

- API-ALOD-PARM.NUMBER
  should carry the number of the location whose data are to be retrieved.

If [API-PARM.API-MAIN-FUNC] = 'D' and the location is found, APINALOD returns in the remaining parameter fields the location data.

[API-ALOD-PARM.DEPLOYMENT-CNT] is the number of the deployments in which the location participates. Their numbers and names are returned in API-ALOD-PARM.DEPLOYMENT(1:[API-ALOD-PARM.DEPLOYMENT-CNT]).

API-ALOD-PARM.FRG-PDS contains a fifty-four-character PDS name and, possibly, operating system specific data like a volume (z/OS).

APINALOD returns the following [API-PARM.API-MSG-NO]:

1011 | If [API-PARM.API-MAIN-FUNC] other than 'D' has been specified,
7250 | If the location has been found,
7251 | If a location with the given number has been sought but has not been found.

## APINALOS

This PAA API enables users to obtain chunks of lists of location numbers.

Each PAA location has an "internal" number, which is of no interest to the users of the menu system. However, APINALOD, the API that enables users to retrieve the data of a particular location, requires the specification of a single location number. APINALOS enables users to obtain the numbers of all locations, which satisfy the specified selection criteria.

APINALOS corresponds to the Select Locations functions of the menu system and to the various locations orientated REPORT direct commands. Unlike them, it produces only the numbers of the locations. These numbers can then be used as input to APINALOD, which in turn corresponds to the Display Location functions of the menu system.

APINALOS can be invoked thus:

    CALLNAT 'APINALOS' API-PARM API-ALOS-PARM

To obtain a chunk of a list of location numbers, set [API-PARM.API-MAIN-FUNC] = 'S'.

The value of API-PARM.API-SUB-FUNC is ignored.

A definition of API-ALOS-PARM is provided in LDA UPILALOS.

    1 API-ALOS-PARM
    2 KIND-OF-LOCATION                 A          1
    2 NAT-LIBRARY                      A          8
    2 NAT-FUSER-DBNR                   N          5
    2 NAT-FUSER-FNR                    N          5
    2 PRD-FDIC-DBNR                    N          5
    2 PRD-FDIC-FNR                     N          5
    2 FRG-ESY-NODE                     N          5
    2 FRG-PDS                          A         54
    2 FRG-VOL-TYPE                     A          6
    2 NUMBER-CNT                       N          3

    2 NUMBER                           N         10 (1:60)
    2 API-PAC-AREA                     A        145

When APINALOS is called:

- API-ALOS-PARM.KIND-OF-LOCATION
  should carry a character designating the kind(s) of locations to be selected. The following characters designate kinds of locations.

  N | Natural
  P | Predict
  F | foreign
  * | any
  space | any

- API-ALOS-PARM.NAT-LIBRARY
  should carry a range of Natural library names or be blank, if API-ALOS-PARM.KIND-OF-LOCATION = 'N' OR = '*' OR = ' '. The value of API-ALOS-PARM.NAT-LIBRARY is ignored, if [API-ALOS-PARM.KIND-OF-LOCATION] is not one of the three enumerated.

  A blank API-ALOS-PARM.NAT-LIBRARY has the same effect on the selection as one carrying an initial asterisk.

- API-ALOS-PARM.NAT-FUSER-DBNR
  should carry the database number of a Natural system file or 0, if API-ALOS-PARM.KIND-OF-LOCATION = 'N' OR = '*' OR = ' '. The value of API-ALOS-PARM.NAT-FUSER-DBNR is ignored, if [API-ALOS-PARM.KIND-OF-LOCATION] is not one of the three enumerated.

  If API-ALOS-PARM.NAT-FUSER-DBNR = 0 then the selection of locations are not restricted on the account of this parameter.

- API-ALOS-PARM.NAT-FUSER-FNR
  should carry the file number of a Natural system file or 0, if API-ALOS-PARM.KIND-OF-LOCATION = 'N' OR = '*' OR = ' '. The value of API-ALOS-PARM.NAT-FUSER-FNR is ignored, if [API-ALOS-PARM.KIND-OF-LOCATION] is not one of the three enumerated.

  If API-ALOS-PARM.NAT-FUSER-FNR = 0 then the selection of locations are not restricted on the account of this parameter.

- API-ALOS-PARM.PRD-FDIC-DBNR
  should carry the database number of a Predict system file or 0, if API-ALOS-PARM.KIND-OF-LOCATION = 'P' OR = '*' OR = ' '. The value of API-ALOS-PARM.PRD-FDIC-DBNR is ignored, if [API-ALOS-PARM.KIND-OF-LOCATION] is not one of the three enumerated.

  If API-ALOS-PARM.PRD-FDIC-DBNR = 0 then the selection of locations are not restricted on the account of this parameter.

- API-ALOS-PARM.PRD-FDIC-FNR
  should carry the file number of a Predict system file or 0, if API-ALOS-PARM.KIND-OF-LOCATION = 'P' OR = '*' OR = ' '. The value of API-ALOS-PARM.PRD-FDIC-FNR is ignored, if [API-ALOS-PARM.KIND-OF-LOCATION] is not one of the three enumerated.

  If API-ALOS-PARM.NAT-FDIC-FNR = 0 then the selection of locations are not restricted on the account of this parameter.

- API-ALOS-PARM.FRG-ESY-NODE
  should carry the number of an ENTIRE SYSTEM SERVER node or 0, if API-ALOS-PARM.KIND-OF-LOCATION = 'F' OR = '*' OR = ' '. The value of API-ALOS-PARM.FRG-ESY-NODE is ignored, if [API-ALOS-PARM.KIND-OF-LOCATION] is not one of the three enumerated.

  If API-ALOS-PARM.FRG-ESY-NODE = 0 then the selection of locations are not restricted on the account of this parameter.

- API-ALOS-PARM.FRG-PDS
  should carry a range of PDS names or be blank, if API-ALOS-PARM.KIND-OF-LOCATION = 'F' OR = '*' OR = ' '. The value of API-ALOS-PARM.FRG-PDS is ignored, if [API-ALOS-PARM.KIND-OF-LOCATION] is not one of the three enumerated.

  A blank API-ALOS-PARM.FRG-PDS has the same effect on the selection as one carrying an initial asterisk.

- API-ALOS-PARM.FRG-VOL-TYPE
  should carry the name of a volume (z/OS) or '*' or ' ', if API-ALOS-PARM.KIND-OF-LOCATION = 'F' OR = '*' OR = ' '. The value of API-ALOS-PARM.FRG-VOL-TYPE is ignored, if [API-ALOS-PARM.KIND-OF-LOCATION] is not one of the three enumerated.

  If API-ALOS-PARM.FRG-VOL-TYPE = '*' OR = ' ' then the selection of locations is not restricted on the account of this parameter.

- [API-ALOS-PARM.NUMBER-CNT]
  is made 0, if negative; it is made 60, if greater than 60. It is then interpreted as the maximum number of location numbers to be returned; no location numbers will be returned, if API-ALOS-PARM.NUMBER-CNT = 0.

- API-ALOS-PARM.PAC-AREA
  should be reset when the first chunk of a list of location numbers is wanted. API-ALOS-PARM.PAC-AREA should be left untouched for a next call to obtain an immediately following chunk of the same list.

APINALOS returns in API-ALOS-PARM.NUMBER-CNT the number of location numbers in the returned chunk; it may be less than the adjusted original value, if the end of the location number list has been reached. If no location satisfying the selection criteria is found or a non-positive [API-ALOS-PARM.NUMBER-CNT] has been specified then APINALOS returns 0 in API-ALOS-PARM.NUMBER-CNT.

If APINALOS returns a non-zero [API-ALOS-PARM.NUMBER-CNT] then it returns the chunk of the list of the numbers of the locations satisfying the selection criteria in API-ALOS-PARM.NUMBER(1:[API-ALOS-PARM.NUMBER-CNT]).

APINALOS returns the following [API-PARM.API-MSG-NO]:

0000 | If at least one location satisfying the selection criteria has been found and a non-final chunk of a list of the numbers of the locations satisfying the selection criteria is being returned,
0044 | If [API-ALOS-PARM.KIND-OF-LOCATION] other than 'N', 'P', 'F', '*', ' ' has been specified,
0070 | If locations satisfying the selection criteria have been sought but none has been found,
1011 | If [API-PARM.API-MAIN-FUNC] other than 'S' has been specified,
9999 | If at least one location satisfying the selection criteria has been found and a final chunk of a list of the numbers of the locations satisfying the selection criteria is being returned.

## APINAOBD

This PAA API enables users to obtain data from a PAA object.

Each PAA object has an "internal" number. APINAOBD requires the specification of one such number; it then produces information about the object. The numbers of PAA objects can be learnt from APINAOBS.

APINAOBD corresponds to the Display Object functions of the menu system.

APINAOBD can be invoked thus:

    CALLNAT 'APINAOBD' API-PARM API-AOBD-PARM

To obtain data from an object, set [API-PARM.API-MAIN-FUNC] = 'D'.

The value of API-PARM.API-SUB-FUNC is ignored.

A definition of API-AOBD-PARM is provided in LDA UPILAOBD.

          1      API-AOBD-PARM
          2      NUMBER              N      10     in
          2      APPLICATION         A      32        out
          2      STATUS              A      32        out
          2      LOCATION            A      73        out
    R     2      LOCATION
          3      NAT-LIBRARY         A      8
          3      NAT-FUSER-DBNR      N      5
          3      NAT-FUSER-FNR       N      5
          3      NAT-FDIC-DBNR       N      5
          3      NAT-FDIC-FNR        N      5
    R     2      LOCATION
          3      PRD-FDIC-DBNR       N      5
          3      PRD-FDIC-FNR        N      5
    R     2      LOCATION
          3      FRG-ESY-NODE        N      5
          3      FRG-OP-SYSTEM       A      8
          3      FRG-PDS             A      60
          2      JOB-NUMBER          N      10        out
          2      OBJECT-NAME         A      64        out
          2      SUBTYPE-1           A      1         out
          2      SUBTYPE-2           A      4         out
          2      SUBTYPE-3           A      1         out
          2      STATE               A      10        out
          2      PAA-VERNO           N      5         out
          2      PAC-VERNO           N      5         out
          2      PREDECESSOR-NUMBER  N      10        out
          2      SUCCESSOR-NUMBER    N      10        out
          2      HISTORICAL-NUMBER   N      10        out
          2      SCHED-DATE          T                out
          2      ACTIV-DATE          T                out
          2      ACTIV-USER          A      8         out
          2      ACTIV-TID           A      8         out
          2      BACKUP-DATE         T                out
          2      BACKUP-USER         A      8         out
          2      BACKUP-TID          A      8         out
          2      PURGE-DATE          T                out
          2      PURGE-USER          A      8         out
          2      PURGE-TID           A      8         out
          2      ADD-DATE            T                out
          2      ADD-USER            A      8         out
          2      ADD-TID             A      8         out
          2      MAINT-DATE          T                out
          2      MAINT-USER          A      8         out
          2      MAINT-TID           A      8         out
          2      HOLD-DATE           T                out
          2      HOLD-USER           A      8         out
          2      HOLD-TID            A      8         out
          2      HOLD-RECOVERY       A      50        out

When APINAOBD is called:

- API-AOBD-PARM.NUMBER
  should carry the number of the object whose data are to be retrieved.

If [API-PARM.API-MAIN-FUNC] = 'D' and the object is found, APINAOBD returns in the remaining parameter fields the object data.

API-AOBD-PARM.STATE contains a designation of the object's state. The following are the possible designations:

- Scheduled

- Current

- Backed up

- Removed

- Historical

[API-AOBD-PARM.PREDECESSOR-NUMBER], if distinct from 0, is the number of the object preceding in an object version succession chain the object whose data are being returned. This "predecessor" will take the place of the object whose data are being returned if the latter is removed.

If API-AOBD-PARM.SUCCESSOR-NUMBER = 0 then the object has no successor.

[API-AOBD-PARM.SUCCESSOR-NUMBER], if distinct from 0, is the number of the object succeeding in an object version succession chain the object whose data are being returned. The object whose data are being returned will take the place of this "successor" if the latter is removed.

If API-AOBD-PARM.PREDECESSOR-NUMBER = 0 then the object has no predecessor.

[API-AOBD-PARM.HISTORICAL-NUMBER], if distinct from 0, is the number of the historical object (record) which contains information about the object's penultimate current spell. (Historical objects arise when backed up objects become current.)

If API-AOBD-PARM.HISTORICAL-NUMBER = 0 then the object has not been current more than once.

APINAOBD returns the following [API-PARM.API-MSG-NO]:

1011 | If [API-PARM.API-MAIN-FUNC] other than 'D' has been specified,
7250 | If the location has been found,
7251 | If a location with the given number has been sought but has not been found.

## APINAOBS

This PAA API enables users to obtain chunks of lists of object numbers.

Each PAA object has an "internal" number, which is of no interest to the users of the menu system. However, APINAOBD, the API that enables users to retrieve the data of a particular object, requires the specification of a single object number. APINAOBS enables users to obtain the numbers of all objects, which satisfy the specified selection criteria.

APINAOBS corresponds to the Select Objects functions of the menu system and to the REPORT OBJECT direct commands. Unlike them, it produces only the numbers of the objects. These numbers can then be used as input to APINAOBD, which in turn corresponds to the Display Object functions of the menu system.

APINAOBS can be invoked thus:

    CALLNAT 'APINAOBS' API-PARM API-AOBS-PARM

To obtain a chunk of a list of object numbers, set [API-PARM.API-MAIN-FUNC] = 'S'.

The value of API-PARM.API-SUB-FUNC is ignored.

A definition of API-AOBS-PARM is provided in LDA UPILAOBS.

          1      API-AOBS-PARM
          2      APPLICATION          A      32         in
          2      STATUS               A      32         in
          2      KIND-OF-LOCATION     A      1          in
          2      NAT-LIBRARY          A      8          in
          2      NAT-FUSER-DBNR       N      5          in
          2      NAT-FUSER-FNR        N      5          in
          2      PRD-FDIC-DBNR        N      5          in
          2      PRD-FDIC-FNR         N      5          in
          2      FRG-ESY-NODE         N      5          in
          2      FRG-PDS              A      54         in
          2      FRG-VOL-TYPE         A      6          in
          2      JOB                  N      10         in
          2      OBJECT-NAME          A      32         in
          2      SUBTYPE-1            A      1          in
          2      SUBTYPE-2            A      4          in
          2      SUBTYPE-3            A      1          in
          2      STATE                A      1          in
          2      PAA-VERNO            N      5          in
          2      PAC-VERNO            N      5          in
          2      CURRENT-FROM         T                 in
          2      CURRENT-TO           T                 in
          2      NUMBER-CNT           N      3          in/out
          2      NUMBER               N      10(1:60)      out
          2      API-PAC-AREA         A      145        in/out
          2      API-PAC-AREA-1       A      145        in/out
          2      API-PAC-AREA-2       A      145        in/out

When APINAOBS is called:

- API-AOBS-PARM.APPLICATION
  should carry a range of application names or be blank.

- API-AOBS-PARM.STATUS
  should carry a range of status names or be blank, if API-AOBS-PARM.APPLICATION in fact carries an application name. The value of API-AOBS-PARM.STATUS is ignored, if API-AOBS-PARM.APPLICATION carries a range of application names which is not an application name.

  If API-AOBS-PARM.APPLICATION or API-AOBS-PARM.STATUS but not both are blank then the blank parameter field has the same effect on the selection as it would have if it carried an initial asterisk.

  If both API-AOBS-PARM.APPLICATION and API-AOBS-PARM.STATUS are blank then objects are selected regardless of their deployments.

  If both API-AOBS-PARM.APPLICATION and API-AOBS-PARM.STATUS carry initial asterisks then the selection of objects is not restricted on the account of these parameters, but the objects are selected first in the ascending order of their deployment names.

- API-AOBS-PARM.KIND-OF-LOCATION
  should carry a character designating the kind(s) of locations whose objects are to be selected. The following characters designate kinds of locations.

  N | Natural
  P | Predict
  F | foreign
  * | any
  space | any

  If API-AOBS-PARM.KIND-OF-LOCATION = ' ' then objects are selected regardless of their locations.

  If API-AOBS-PARM.KIND-OF-LOCATION = '*' then objects in any location which satisfies the selection criteria relevant to its kind are considered for selection. In this case objects are selected first or second in the ascending order of their location names. '*' should be used with caution in this context; incautious use can result in a very time consuming scan of large portions of the PAA system file.

- API-AOBS-PARM.NAT-LIBRARY
  should carry a range of Natural library names or be blank, if API-AOBS-PARM.KIND-OF-LOCATION = 'N' OR = '*'. The value of API-AOBS-PARM.NAT-LIBRARY is ignored, if [API-AOBS-PARM.KIND-OF-LOCATION] is not one of the two enumerated.

  A blank API-AOBS-PARM.NAT-LIBRARY has the same effect on the selection as one carrying an initial asterisk.

- API-AOBS-PARM.NAT-FUSER-DBNR
  should carry the database number of a Natural system file or 0, if API-AOBS-PARM.KIND-OF-LOCATION = 'N' OR = '*'. The value of API-AOBS-PARM.NAT-FUSER-DBNR is ignored, if [API-AOBS-PARM.KIND-OF-LOCATION] is not one of the two enumerated.

  If API-AOBS-PARM.NAT-FUSER-DBNR = 0 then the selection is not restricted on the account of this parameter.

- · API-AOBS-PARM.NAT-FUSER-FNR should carry the file number of a Natural system file or 0, if API-AOBS-PARM.KIND-OF-LOCATION = 'N' OR = '*'. The value of API-AOBS-PARM.NAT-FUSER-FNR is ignored, if [API-AOBS-PARM.KIND-OF-LOCATION] is not one of the two enumerated.

  If API-AOBS-PARM.NAT-FUSER-FNR = 0 then the selection is not restricted on the account of this parameter.

- API-AOBS-PARM.PRD-FDIC-DBNR
  should carry the database number of a Predict system file or 0, if API-AOBS-PARM.KIND-OF-LOCATION = 'P' OR = '*'. The value of API-AOBS-PARM.PRD-FDIC-DBNR is ignored, if [API-AOBS-PARM.KIND-OF-LOCATION] is not one of the two enumerated.

  If API-AOBS-PARM.PRD-FDIC-DBNR = 0 then the selection is not restricted on the account of this parameter.

- API-AOBS-PARM.PRD-FDIC-FNR
  should carry the file number of a Predict system file or 0, if API-AOBS-PARM.KIND-OF-LOCATION = 'P' OR = '*'. The value of API-AOBS-PARM.PRD-FDIC-FNR is ignored, if [API-AOBS-PARM.KIND-OF-LOCATION] is not one of the two enumerated.

  If API-AOBS-PARM.NAT-FDIC-FNR = 0 then the selection is not restricted on the account of this parameter.

- API-AOBS-PARM.FRG-ESY-NODE
  should carry the number of an ENTIRE SYSTEM SERVER node or 0, if API-AOBS-PARM.KIND-OF-LOCATION = 'F' OR = '*'. The value of API-AOBS-PARM.FRG-ESY-NODE is ignored, if [API-AOBS-PARM.KIND-OF-LOCATION] is not one of the two enumerated.

  If API-AOBS-PARM.FRG-ESY-NODE = 0 then the selection is not restricted on the account of this parameter.

- API-AOBS-PARM.FRG-PDS
  should carry a range of PDS names or be blank, if API-AOBS-PARM.KIND-OF-LOCATION = 'F' OR = '*'. The value of API-AOBS-PARM.FRG-PDS is ignored, if [API-AOBS-PARM.KIND-OF-LOCATION] is not one of the two enumerated.

  A blank API-AOBS-PARM.FRG-PDS has the same effect on the selection as one carrying an initial asterisk.

- API-AOBS-PARM.FRG-VOL-TYPE
  should carry the name of a volume (z/OS) or '*' or ' ', if API-AOBS-PARM.KIND-OF-LOCATION = 'F' OR = '*'. The value of API-AOBS-PARM.FRG-VOL-TYPE is ignored, if [API-AOBS-PARM.KIND-OF-LOCATION] is not one of the two enumerated. I

  f API-AOBS-PARM.FRG-VOL-TYPE = '*' OR = ' ' then the selection of locations is not restricted on the account of this parameter.

- API-AOBS-PARM.JOB
  should carry the number of the PAA job to which the objects to be selected must belong or 0.

  If API-AOBS-PARM.JOB = 0 then the selection is not restricted on the account of this parameter.

- API-AOBS-PARM.OBJECT-NAME
  should carry a range of object names or be blank. A blank API-AOBS-PARM.OBJECT-NAME has the same effect on the selection of objects as it would have if it carried an initial asterisk.

- API-AOBS-PARM.SUBTYPE-1
  should carry the first, one character, part of the designation of the type(s) of the objects to be selected.

  The following characters can be meaningful values of this parameter:

  N | Natural objects
  E | error messages
  V | DDMs
  F | foreign objects
  space | any objects

- API-AOBS-PARM.SUBTYPE-2
  should carry the second, two character, part of the designation of the type(s) of the objects to be selected. The following strings can be meaningful values of this parameter:

  If API-AOBS-PARM.SUBTYPE-1 = 'N':

  A | parameter data areas
  C | copycodes
  G | global data areas
  H | helproutines
  L | local data areas
  M | maps
  N | subprograms
  P | programs
  S | subroutines
  T | texts
  all spaces | any objects

  If API-AOBS-PARM.SUBTYPE-1 = 'E' OR = 'V' then API-AOBS-PARM.SUBTYPE-2 should be blank.

  If API-AOBS-PARM.SUBTYPE-1 = 'F' then API-AOBS-PARM.SUBTYPE-2 should contain a "foreign type" designation (to be seen in the third column of a Deployment Foreign Part Display screen) or be blank.

  If API-AOBS-PARM.SUBTYPE-2 is blank then the selection of objects is not restricted on the account of this parameter.

- API-AOBS-PARM.SUBTYPE-3
  should carry the third, one character, part of the designation of the type(s) of the objects to be selected. The following characters can be meaningful values of this parameter.

  S | sources
  L | loadables
  X | Xrefs
  space | any objects

  If API-AOBS-PARM.SUBTYPE-1 = 'E' OR = 'V' then API-AOBS-PARM.SUBTYPE-3 should be blank.

  If API-AOBS-PARM.SUBTYPE-1 = 'F' then [API-AOBS-PARM.SUBTYPE-3] should not be 'X'.

- API-AOBS-PARM.STATE
  should carry a character designating the state(s) of the objects to be selected. The following characters designate object states.

  B | backed up
  C | current
  H | historical
  R | removed
  S | scheduled
  space | any

- API-AOBS-PARM.PAA-VERNO
  should carry the PAA version number of the objects to be selected or 0. If API-AOBS-PARM.PAA-VERNO = 0 then the selection of objects are not restricted on the account of this parameter.

- API-AOBS-PARM.PAC-VERNO
  should carry the PAC version number of the objects to be selected or 0.

  If API-AOBS-PARM.PAC-VERNO = 0 then the selection of objects are not restricted on the account of this parameter.

- API-AOBS-PARM.CURRENT-FROM
  should carry the starting time of the period at some point of which any object to be selected must have been or be current.

  0 must be specified, if scheduled objects are not to be excluded.

- API-AOBS-PARM.CURRENT-TO
  should carry the ending time of the period at some point of which any object to be selected must have been or be current.

  If API-AOBS-PARM.CURRENT-TO = 0 then the selection of objects are not restricted on the account of this parameter.

  0 must be specified, if scheduled objects are not to be excluded.

- [API-AOBS-PARM.NUMBER-CNT]
  is made 0, if negative; it is made 60, if greater than 60. It is then interpreted as the maximum number of object numbers to be returned; no object numbers will be returned, if API-AOBS-PARM.NUMBER-CNT = 0.

- API-AOBS-PARM.PAC-AREA, API-AOBS-PARM.PAC-AREA-1, and API-AOBS-PARM.PAC-AREA-2
  should be reset when the first chunk of a list of object numbers is wanted. They should be left untouched for a next call to obtain an immediately following chunk of the same list.

APINAOBS returns in API-AOBS-PARM.NUMBER-CNT the number of object numbers in the returned chunk; it may be less than the adjusted original value, if the end of the object number list has been reached. If no object satisfying the selection criteria is found or a non-positive [API-AOBS-PARM.NUMBER-CNT] has been specified then APINAOBS returns 0 in API-AOBS-PARM.NUMBER-CNT.

If APINAOBS returns a non-zero [API-AOBS-PARM.NUMBER-CNT] then it returns the chunk of the list of the numbers of the objects satisfying the selection criteria in API-AOBS-PARM.NUMBER(1:[API-AOBS-PARM.NUMBER-CNT]).

APINAOBS returns the following [API-PARM.API-MSG-NO]:

0000 | if at least one object satisfying the selection criteria has been found and a non-final chunk of a list of the numbers of the objects satisfying the selection criteria is being returned,
0044 | If [API-AOBS-PARM.KIND-OF-LOCATION] other than 'N', 'P', 'F', '*', ' ' has been specified,
0070 | If objects satisfying the selection criteria have been sought but none has been found,
1011 | If [API-PARM.API-MAIN-FUNC] other than 'S' has been specified,
9999 | If at least one object satisfying the selection criteria has been found and a final chunk of a list of the numbers of the objects satisfying the selection criteria is being returned.