SFS_NN_TOPOLOGY_NODE

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

Each network node maintains a network topology database that holds information about all network nodes, VRNs, and network node to network node TGs in the network. The SFS_NN_TOPOLOGY_NODE verb is used to safely store the topology database node entries 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).

To obtain information about a specific network node or to obtain the list information in several chunks, the node_name and node_type fields 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 by node_name, and node_name_type, and frsn. 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). Ordering for the node_type is AP_NETWORK_NODE, then AP_VRN. The frsn is ordered numerically.
  • If AP_LIST_INCLUSIVE is selected, the returned list starts from the first valid record of that name.
  • If AP_LIST_FROM_NEXT is selected, the list will begin from the first valid record with a name following the one specified.
Note that if the frsn field is set to a nonzero value, only database entries with Flow Reduction Sequence Number (FRSNs) higher than this are returned. This allows a consistent topology database to be returned in a number of chunks by first getting the node's current FRSN. This works as follows:
  1. Issue QUERY_NODE that returns the node's current FRSN.
  2. Issue as many SFS_NN_TOPOLOGY_NODE (with FRSN set to zero) as necessary to get all the database entries in chunks.
  3. Issue QUERY_NODE again and compare the new FRSN with the one returned in stage one.
  4. If the two FRSNs are different then what has changed in the database, issue a SFS_NN_TOPOLOGY_NODE with the FRSN set to one greater than the FRSN supplied in stage one.

VCB Structure

typedef struct sfs_nn_topology_node
{
        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    */
        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   node_name[17];      /* network qualified             */
                                            /* node name                     */
        unsigned char   node_type;          /* node type                     */
        unsigned long   frsn;               /* flow-reduction sequence       */
                                            /* number                        */
} SFS_NN_TOPOLOGY_NODE;

typedef struct nn_topology_node_detail
{
        unsigned short  overlay_size;       /* size of this entry            */
        unsigned char   node_name[17];      /* network qualified             */
        unsigned char   node_type;          /* node type                     */
        unsigned short  days_left           /* days left in database         */
        unsigned long   frsn;               /* flow reduction sequence number*/
        unsigned long   rsn;                /* resource sequence number      */
        unsigned char   rar;                /* route additional resistence   */
        unsigned char   status;             /* node status                   */
        unsigned char   function_support;   /* function support              */
        unsigned char   reserv2;            /* reserved                      */
        unsigned char   reserva[20];        /* reserved                      */
} NN_TOPOLOGY_NODE_DETAIL;

Supplied Parameters

Supplied Parameters when restore = AP_NO

The application supplies the following parameters:
opcode
AP_SFS_NN_TOPOLOGY_NODE
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 node_name, node_types and frsn specified (see the following parameters, node_name, node_types and frsn) 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.
node_name
Network qualified node name from the Network Topology Database. This name is a 17-byte adjacent control point name, which is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This field is only relevant for links to APPN nodes and is otherwise ignored. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
node_type
Type of the node. This node is set to one of the following:

AP_NETWORK_NODE
AP_VRN

If the node_type is unknown, AP_LEARN_NODE must be specified. This field is ignored if list_options is set to AP_FIRST_IN_LIST.

frsn
Flow Reduction Sequence Number. If this is nonzero, then only topology resources with a FRSN greater than or equal to this value is returned.

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.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
num_entries
The number of entries actually returned.
nn_topology_node_detail.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
nn_topology_node_detail.node_name
Network qualified node name from the Network Topology Database. This name is a 17-byte adjacent control point name, which is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
nn_topology_node_detail.node_type
Type of the node. It is one of the following:

AP_NETWORK_NODE
AP_VRN

nn_topology_node_detail.days_left
Number of days before deletion of this node entry from the topology database. This will be set to zero for the local node entry (this entry is never deleted). This must be set to zero when the record is restored (for example, restore is set to AP_YES).
nn_topology_node_detail.frsn
The Flow Reduction Sequence Number. This indicates the last time that the resource was updated at the local node.
nn_topology_node_detail.rsn
The Resource Sequence Number. This is assigned by the network node that owns this resource.
nn_topology_node_detail.rar
The network node's route additional resistance.
nn_topology_node_detail.status
This field specifies the status of the node and can be AP_UNCONGESTED or one or more of the following ORed together:
AP_CONGESTED
The number of ISR sessions is greater than the isr_sessions_upper_threshold specified on the START_NODE verb.
AP_IRR_DEPLETED
The number of ISR sessions has reached the maximum specified on the max_isr_sessions parameter of the START_NODE verb.
AP_ERR_DEPLETED
The number of endpoint sessions has reached the maximum specified.
AP_QUIESCING
A STOP_NODE of type AP_QUIENCE or AP_QUIENCE_ISR was issued.
nn_topology_node_detail.function_support
This field specifies which functions are supported. This can be one or more of the following:
AP_BORDER_NODE
Border Node Function is supported.
AP_CDS
The Central Directory Server is supported.
AP_GATEWAY
The node is a Gateway Node (the function is not yet architecturally defined).
AP_ISR
This node supports the Intermediate Session Routing.
AP_HPR
This node supports the Intermediate Session Routing.
AP_RTP_TOWER
This node supports the RTP Tower of HPR.
AP_CONTROL_OVER_RTP_TOWER
This node supports the Control Flows Over the RTP Tower.
Note: The AP_CONTROL_OVER_RTP_TOWER node corresponds to the setting of both AP_HPR and AP_RTP_TOWER.
If the verb does not execute successfully, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_INVALID_LIST_OPTION

AP_INVALID_NODE
AP_INVALID_LIST_OPTIONS

Supplied Parameters

Supplied Parameters when restore = AP_YES

The application supplies the following parameters:
opcode
AP_SFS_NN_TOPOLOGY_NODE
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
Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.
restore
Flag indicating whether the information should be restored (AP_YES) or stored (AP_NO). In this case, it is set to AP_NO.
nn_topology_node_detail.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
nn_topology_node_detail.node_name
Network qualified node name from the Network Topology Database. This name is a 17-byte adjacent control point name, which is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This field is only relevant for links to APPN nodes and is otherwise ignored. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
nn_topology_node_detail.node_type
Type of the node. It is one of the following:

AP_NETWORK_NODE
AP_VRN

nn_topology_node_detail.days_left
Number of days before deletion of this node entry from the topology database. If the node is not the local node, this field must be set to a value greater than zero.
nn_topology_node_detail.frsn
The Flow Reduction Sequence Number. This indicates the last time that the resource was updated at the local node.
nn_topology_node_detail.rsn
The Resource Sequence Number. This is assigned by the network node that owns this resource.
nn_topology_node_detail.rar
The network node's route additional resistance.
nn_topology_node_detail.status
This field specifies the status of the node and can be AP_UNCONGESTED or one or more of the following ORed together:
AP_CONGESTED
The number of ISR sessions is greater than the isr_sessions_upper_threshold specified on the START_NODE verb.
AP_IRR_DEPLETED
The number of ISR sessions has reached the maximum specified on the max_isr_sessions parameter of the START_NODE verb.
AP_ERR_DEPLETED
The number of endpoint sessions has reached the maximum specified.
AP_QUIESCING
A STOP_NODE of type AP_QUIENCE or AP_QUIENCE_ISR was issued.
nn_topology_node_detail.function_support
This field specifies which functions are supported. This can be one or more of the following:
AP_BORDER_NODE
Border Node Function is supported.
AP_CDS
The Central Directory Server is supported.
AP_GATEWAY
The node is a Gateway Node (the function is not yet architecturally defined).
AP_ISR
This node supports the Intermediate Session Routing.
AP_HPR
This node supports the Intermediate Session Routing.
AP_RTP_TOWER
This node supports the RTP Tower of HPR.
AP_CONTROL_OVER_RTP_TOWER
This node supports the Control Flows Over the RTP Tower.
Note: The AP_CONTROL_OVER_RTP_TOWER node corresponds to the setting of both AP_HPR and AP_RTP_TOWER.
node_type
Type of the node. This node is set to one of the following:

AP_NETWORK_NODE
AP_VRN

If the node_type is unknown, AP_LEARN_NODE must be specified. This field is ignored if list_options is set to AP_FIRST_IN_LIST.

frsn
Flow Reduction Sequence Number. If this is nonzero, then only topology resources with a FRSN greater than or equal to this value is returned.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:
primary_rc
AP_OK
secondary_rc
AP_INVALID_DAYS_LEFT
If the verb does not execute because of a parameter error, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_INVALID_DAYS_LEFT
If the verb does not execute because of a parameter error, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_INVALID_DAYS_LEFT
If the verb does not execute because one or more of the relevant START_NODE parameters were not set, the Program returns the following parameters:
primary_rc
AP_FUNCTION_NOT_SUPPORTED
secondary_rc
AP_INVALID_DAYS_LEFT
If the verb does not execute because the system was not build with network node support, the Program returns the following parameters:
primary_rc
AP_INVALID_VERB
If the verb does not execute because of a system error, the Program returns the following parameters:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR
Parent topic: Safe-Store Verbs