APINLNK

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:


Local Data Area USLLLNK

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.

API Return Codes

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.