SFS_ADJACENT_NN

Note: This verb has been superceded by SAFE_STORE_TOPOLOGY and is only retained for compatibility with previous versions of the Program.

SFS_ADJACENT_NN is used to safely store topology information that can be later accessed if the node is restarted. The restore flag is used to indicate whether information is being stored (AP_NO) or accessed (AP_YES).

When the restore flag is set to AP_NO, SFS_ADJACENT_NN returns information about adjacent network nodes (that is, those network nodes which CP-CP sessions are active, have been active, or have been active at some time).

The SFS information is returned as a formatted list. To obtain information about a specific network node or to obtain the list information in several chunks, the adj_nncp_name field should be set.

Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. See Querying the Node for background on how the list formats are used.

This list is ordered on the adj_nncp_name. Ordering is by name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with IBM's 6611 APPN MIB ordering). If AP_LIST_FROM_NEXT is selected, the list starts from the next entry according to the defined ordering (whether the specified entry exists or not).

VCB Structure

typedef struct sfs_adjacent_nn
{
        unsigned short  opcode;             /* verb operation code           */
        unsigned char   reserv2;            /* reserved                      */
        unsigned char   format;             /* format                        */
        unsigned short  primary_rc;         /* primary return code           */
        unsigned long   secondary_rc;       /* secondary return code         */
        unsigned char   *buf_ptr;           /* pointer to buffer             */
        unsigned long   buf_size;           /* buffer size                   */
        unsigned long   total_buf_size;     /* total buffer size required    */
                                            /* to hold all information       */
        unsigned short  num_entries;        /* number of entries             */
        unsigned short  total_num_entries;  /* total number of entries       */
        unsigned char   list_options;       /* listing options               */
        unsigned char   restore;            /* store or restore;             */
        unsigned char   adj_nncp_name[17];  /* CP name of adj Network Node   */
} SFS_ADJACENT_NN;

typedef struct adj_nncp_data
{
        unsigned short  overlay_size;       /* size of this entry            */
        unsigned char   adj_nncp_name[17];  /* CP name of adj Network Node   */
        unsigned char   cp_cp_sess_status;  /* CP-CP session status          */
        unsigned COUNTER
                        out_of_seq_tdus;    /* out of sequence TDUs          */
        unsigned long   last_frsn_sent;     /* last FSRN sent                */
        unsigned long   last_frsn_rcvd;     /* last FRSN received            */
        unsigned char   reserva[20];        /* reserved                      */
} ADJ_NNCP_DATA;

Supplied Parameters

Supplied Parameters when restore = AP_NO

The application supplies the following parameters:

opcode

AP_SFS_ADJACENT_NN

format

Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.

buf_ptr

Pointer to a buffer where list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.

buf_size

Size of buffer supplied. The data returned will not exceed this size.

num_entries

Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.

list_options

This indicates what should be returned in the list information. The adj_nncp_name specified (see the following parameter, adj_nncp_name) represents an index value that is used to specify the starting point of the actual information to be returned.

AP_FIRST_IN_LIST: The index value is ignored, and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT: The returned list starts from the next entry in the list after the one specified by the supplied index value.
AP_LIST_INCLUSIVE: The returned list starts from the entry specified by the index value.

restore

Flag indicating whether the information should be restored (AP_YES) or stored (AP_NO). In this case, it is set to AP_NO.

adj_nncp_name

Fully-qualified, 17 byte, CP name of the adjacent network node composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, which is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This field is ignored if list_options is set to AP_FIRST_IN_LIST.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:

primary_rc: AP_OK
buf_size: Length of the information returned in the buffer.
total_buf_size: Returned value indicating the size of buffer that would have been required to return all the list information requested. This can be higher than buf_size.
num_entries: The number of entries actually returned.
total_num_entries: Total number of entries that could have been returned. This can be higher than num_entries.
adj_nncp_data.overlay_size: The number of bytes in this entry, and hence the offset to the next entry returned (if any).
adj_nncp_data.adj_nncp_name: This is a 17-byte fully-qualified CP name of adjacent network node which is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
adj_nncp_data.cp_cp_sess_status: Status of the CP-CP session (AP_ACTIVE or AP_INACTIVE).
adj_nncp_data.out_of_seq_tdus: Number of out of sequence TDUs received from this node.
adj_nncp_data.last_frsn_sent: The last flow reduction sequence number sent to this node.
adj_nncp_data.last_frsn_rcvd: The last flow reduction sequence number received from this node.

If the verb does not execute because of a parameter error, the Program returns the following parameters:

primary_rc: AP_OK
secondary_rc: AP_INVALID_ADJ_NNCP_NAME
AP_INVALID_LIST_OPTION

Supplied Parameters

Supplied Parameters when restore = AP_YES

The application supplies the following parameters:

opcode: AP_SFS_ADJACENT_NN
format: Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
buf_ptr: Pointer to a buffer where list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.
num_entries: The number of entries actually returned.
restore: Flag indicating whether the information should be restored (AP_YES) or stored (AP_NO). In this case, it is set to AP_NO.
adj_nncp_data.overlay_size: The number of bytes in this entry, and hence the offset to the next entry returned (if any).
adj_nncp_data.adj_nncp_name: This is a 17-byte fully-qualified CP name of adjacent network node which is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
adj_nncp_data.cp_cp_sess_status: This field is ignored when restore is set to AP_YES.
adj_nncp_data.out_of_seq_tdus: This field is ignored when restore is set to AP_YES.
adj_nncp_data.last_frsn_sent: The last flow reduction sequence number sent to this node.
adj_nncp_data.last_frsn_rcvd: The last flow reduction sequence number received from this node.

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:

primary_rc: AP_OK

If the verb does not execute because the node has not been started, the Program returns the following parameter:

primary_rc: AP_NODE_NOT_STARTED

If the verb does not execute because one or more of the relevant START_NODE parameters were not sent, the Program returns the following parameter:

primary_rc: AP_FUNCTION_NOT_SUPPORTED

If the verb does not execute because the system is not built with network node support, the Program returns the following parameter:

primary_rc: AP_INVALID_VERB

If the verb does not execute because of a system error, the Program returns the following parameter:

primary_rc: AP_UNEXPECTED_SYSTEM_ERROR