This API lets the user not only obtain data from an application - status link but also create a new application - status link and modify an existing one.
APINLNK replaces APINLINK and can be invoked with:
CALLNAT 'APINLNK' API-PARM API-LNK-PARM
| A | To add an application status link |
| D | To obtain data from an application status link |
| M | To modify an application status link |
This document covers the following topics:
A definition of API-LNK-PARM is provided in LDA USLLLNK.
| Field Name | Format | I/O |
|---|---|---|
| API-LNK-PARM | ||
| APPLICATION | A32 | in |
| STATUS | A32 | in |
| FILE-TRANS-TABLE | A32 | in/out |
| STEPLIB-CNT | N3 | in/out |
| PRD-CASE-LIB | A32 (1:8) | in/out |
| NEIGHBOUR | A32 | |
| LIBRARY | A32 | out |
| FUSER-DBID | N8 | in/out |
| FUSER-FNR | N5 | in/out |
| FDIC-DBID | N5 | in/out |
| FDIC-FNR | N5 | in/out |
| FPAA-DBID | N5 | in/out |
| FPAA-FNR | N5 | in/out |
| XREF | A1 | in/out |
| ESY-NODE | N5 | in/out |
| OP-SYSTEM | A8 | out |
| FOREIGN-PDS-CNT | N3 | in/out |
| FOREIGN-PDS | A79 (1:50) | in/out |
| ADD-DATE | T | out |
| ADD-BY | A8 | out |
| ADD-TID | A8 | out |
| MOD-DATE | T | out |
| MOD-BY | A8 | out |
| MOD-TID | A8 | out |
| LNK-USER | A64 | |
| LNK-PASSWORD | A64 | |
| LNK-CODEPAGE | A64 |
Whenever APINLNK is called:
API-LNK-PARM.APPLICATION should carry the name of the link's application.
API-LNK-PARM.STATUS should carry the name of the link's status.
If [API-PARM.API-MAIN-FUNC] = 'A' and the application status link is not found, APINLNK tries to add an application status link with the characteristics specified in the "in/out" fields.
If [API-PARM.API-MAIN-FUNC] = 'D' and the application status link is found, APINLNK returns in the remaining parameter fields the application status link data, ignoring any values put by the user in the "in/out" fields.
If [API-PARM.API-MAIN-FUNC] = 'M' and the application status link is found, APINLNK tries to modify the application status link endowing it with the characteristics specified in the "in/out" fields.
Which of the parameter fields can carry meaningful values for a link depends on the application (Predict or not) and on the type of the status. APINLNK tries to reset all irrelevant parameter fields when called with API-PARM.API-MAIN-FUNC at 'A' or 'M'.
If [API-PARM.API-MAIN-FUNC] is 'M' then [API-LNK-PARM.STEPLIB-CNT] is made 0, if negative.
The names of the step applications are returned or expected to be specified [API-LNK-PARM.STEPLIB-CNT] is the number of step applications (to be) specified in the link.
If [API-PARM.API-MAIN-FUNC] is 'A' or 'M' then [API-LNK-PARM.STEPLIB-CNT] is made 8, if greater than 8. If [API-PARM.API-MAIN-FUNC] is 'A' then a negative [API-LNK-PARM.STEPLIB-CNT] is interpreted as an instruction to make the link inherit the sequence of step applications specified in the application record. (if API-LNK-PARM.STEPLIB-CNT GT 0) in API-LNK-PARM.STEPLIB(1:[API-LNK-PARM.STEPLIB-CNT]).
A Predict Case library specification in an application status link can be retrieved but not introduced with APINLNK.
If [API-PARM.API-MAIN-FUNC] is 'A' and a relevant [API-LNK-PARM.LIBRARY] is not specified then APINLNK seeks the value among the defaults in the application record. If [API-PARM.API-MAIN-FUNC] is 'A' and a relevant ([...-DBID],[...-FNR]) = (0,0) then APINLNK seeks the values in the status record. If [API-PARM.API-MAIN-FUNC] is 'A' and a relevant [API-LNK-PARM.XREF] is not specified then APINLNK seeks the value in the status record.
The type of operating system is unique for a node and is discovered by APINLNK regardless of any value possibly put in API-LNK-PARM.OP-SYSTEM by the user. APINLNK processes the user-specified values of API-LNK-PARM.FOREIGN-PDS-CNT and API-LNK-PARM.FOREIGN-PDS only if API-LNK-PARM.ESY-NODE not equal to 0. [API-LNK-PARM.FOREIGN-PDS-CNT] is the number of foreign PDSes (to be) specified in the link.
If [API-PARM.API-MAIN-FUNC] is A or M then [API-LNK-PARM.FOREIGN-PDS-CNT] is made 0, if negative, it is made 50, if greater than 50. The foreign PDS specifications are returned or expected to be supplied (if API-LNK-PARM.ESY-NODE not equal to 0 AND API-LNK-PARM.FOREIGN-PDS-CNT greater than 0) in API-LNK-PARM.FOREIGN-PDS(1:[API-LNK-PARM.FOREIGN-PDS-CNT]).
Each element of API-LNK-PARM.FOREIGN-PDS contains or should contain:
a foreign location type code (bytes 1 - 4), a PDS name (bytes 5 - 58), and operation system specific data:
(optional) z/OS volume specification (bytes 59 - 64) or (required) BS2000 LMS element type specification (byte 59).
In byte 67 of an element of API-LNK-PARM.FOREIGN-PDS APINLNK puts a S(ource) or L(oadable) marking.
APINLNK returns the following [API-PARM.API-MSG-NO]:
| 1011 | If an [API-PARM.API-MAIN-FUNC] distinct from A, D and M has been specified. |
| 6303 | If the LMS element type specification is invalid. |
| 7102 | If an out-of-range database number is specified. |
| 7103 | If and out-of-range file number is specified. |
| 7136 | If an attempt has been made to link application Predict to status ARCHIVE or RETIRE. |
| 7250 | If the link has been found. |
| 7251 | If an application or the status or a foreign type is unknown or the link (to be retrieved) has not been found. |
| 7253 | If the link has been added. |
| 7254 | If the link has been modified. |
| 7259 | If the link (to be added) has not been added for an unspecified reason. |
| 7264 | If the link (to be modified) is held. |
| 7267 | If more than one location of a single foreign type has been specified. |
| 7428 | If an inappropriate [XREF] has been specified. |
| 7517 | If Predict or Predict Case has been specified as a step application. |
| 7577 | If an attempt has been made to link to a status application Predict Case. |
Other values of API-PARM.API-MSG-NO may be received in more unusual situations. APINLNK may pass an Entire System Server message resulting from the ESY's inactivity or an unsuccessful search for a node or a PDS.
Failure to assign to the just added or modified application status link an FTT does not get reflected in API-PARM.API-MSG-NO; it causes the resetting of API-LNK-PARM.FILE-TRANS-TABLE.