SFS_NN_TOPOLOGY_TG

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_TG 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). The verb uses topology_tg_detail overlay.

To obtain information about a specific network node or to obtain the list information in several chunks, the owner, owner_type, dest, dest_type, and tg_num 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 owner, owner_type, dest, dest_type, tg_num, and frsn. The owner_type and dest name are ordered 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). The ordering for owner_type and dest are: AP_ NETWORK_NODE, then AP_VRN. The tg_num and 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:

Issue QUERY_NODE that returns the node's current FRSN.
Issue as many SFS_NN_TOPOLOGY_NODE (with FRSN set to zero) as necessary to get all the database entries in chunks.
Issue QUERY_NODE again and compare the new FRSN with the one returned in stage one.
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_tg
{
        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   owner[17];          /* network qualified             */
                                            /* node name                     */
        unsigned char   owner_type;         /* node type                     */
        unsigned char   dest[17];           /* TG destination node           */
        unsigned char   dest_type;          /* TG destination node type      */
        unsigned char   tg_num;             /* TG number                     */
        unsigned char   reserv1;            /* reserved                      */
        unsigned long   frsn;               /* flow-reduction sequence       */
                                            /* number                        */
} SFS_NN_TOPOLOGY_TG;

typedef struct nn_topology_tg_detail
{
        unsigned short  overlay_size;       /* size of this entry            */
        unsigned char   owner[17];          /* network qualified             */
        unsigned char   owner_type;         /* node type                     */
        unsigned char   dest[17];           /* TG destination node           */
        unsigned char   dest_type           /* TG destination node type      */
        unsigned char   tg_num;             /* TG number                     */
        unsigned char   reserv3[1];         /* reserved                      */
        unsigned long   frsn;               /* flow reduction sequence number*/
        unsigned short  days_left           /* days left in database         */
        LINK_ADDRESS    dlc_data;           /* DLC signalling data           */
        unsigned long   rsn;                /* resource sequence number      */
        unsigned char   status;             /* node status                   */
        TG_DEFINED_CHAR tg_chars;           /* TG characteristics            */
        unsigned char   reserva[20];        /* reserved                     */
}TOPOLOGY_TG_DETAIL;

typedef struct link_address
{
        unsigned short  length              /* length                        */
        unsigned short  reserve1;           /* reserved                      */
        unsigned char   address[MAX_LINK_ADDR_LEN];
                                            /* address                       */
}LINK_ADDRESS;

Supplied Parameters

Supplied Parameters when restore = AP_NO

The application supplies the following parameters:

opcode

AP_SFS_NN_TOPOLOGY_TG

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 owner, owner_type, dest, dest_type, tg_num, and frsn specified (see the following parameters, owner, owner_type, dest, dest_type, tg_num, 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.

owner

Name of the TG's originating node (always set to the local node name). 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.

owner_type

Type of the node. This node is set to one of the following:

AP_NETWORK_NODE
AP_VRN

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

dest

Fully qualified destination node name for the TG. 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.

dest_type

Type of the node. This node is set to one of the following:

AP_NETWORK_NODE
AP_VRN

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

tg_num

Number associated with the TG. 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.
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.
nn_topology_tg_detail.overlay_size: The number of bytes in this entry, and hence the offset to the next entry returned (if any).
nn_topology_detail.owner: Name of the TG's originating node. 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_tg_detail.owner_type: Type of the node. It is one of the following:
AP_NETWORK_NODE
AP_VRN
nn_topology_tg_detail.dest: Fully qualified destination node name for the TG. 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_tg_detail.dest_type: Type of the node. It is one of the following:
AP_NETWORK_NODE
AP_VRN
nn_topology_tg_detail.tg_num: The number associated with the TG.
nn_topology_tg_detail.frsn: The Flow Reduction Sequence Number. This indicates the last time that the resource was updated at the local node.
nn_topology_tg_detail.days_left: The number of days this node remains in the topology database before being removed, unless its existence is can be confirmed. If the node specified by the owner field is not the local node, this field must be set to a value greater than zero.
nn_topology_tg_detail.dlc_data.length: The address length.
nn_topology_tg_detail.dlc_data.address: The address.
nn_topology_tg_detail.rsn: The Resource Sequence Number. This is assigned by the network node that owns this resource.
nn_topology_tg_detail.status: This field specifies the status of the TG. This can be one or more of the following ORed together:
AP_TG_OPERATIVE
AP_TG_CP_CP_SESSIONS
AP_TG_QUIESCING
AP_TG_HPR
AP_TG_RTP
AP_NONE
nn_topology_tg_detail.tg_chars: The TG characteristics. See DEFINE_CN for additional information.

Returned Parameters

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

primary_rc: AP_PARAMETER_CHECK
secondary_rc: AP_INVALID_TG
AP_INVALID_ORIGIN_NODE
AP_INVALID_LIST_OPTION

If the verb does not execute successfully, the Program returns the following parameters:

primary_rc: AP_OK

Supplied Parameters

Supplied Parameters when restore = AP_YES

This application supplies the following parameters:

opcode: AP_SFS_NN_TOPOLOGY_TG
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.
buf_size: Length of the information returned in the buffer.
restore: Flag indicating whether the information should be restored (AP_YES) or stored (AP_NO). In this case, it is set to AP_NO.
total_num_entries: Total number of entries that could have been returned. This can be higher than num_entries.
nn_topology_tg_detail.overlay_size: The number of bytes in this entry, and hence the offset to the next entry returned (if any). This must be the same as the overlay_size value returned when restore = AP_NO.
nn_topology_detail.owner: Name of the TG's originating node. 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_tg_detail.owner_type: Type of the node that owns the TG. It is one of the following:
AP_NETWORK_NODE
AP_VRN
nn_topology_tg_detail.dest: Fully qualified destination node name for the TG. 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_tg_detail.dest_type: Type of the node. It is one of the following:
AP_NETWORK_NODE
AP_VRN
nn_topology_tg_detail.tg_num: The number associated with the TG.
nn_topology_tg_detail.frsn: The Flow Reduction Sequence Number. This indicates the last time that the resource was updated at the local node.
nn_topology_tg_detail.days_left: The number of days this node remains in the topology database before being removed, unless its existence is can be confirmed. If the node specified by the owner field is not the local node, this field must be set to a value greater than zero.
nn_topology_tg_detail.dlc_data.length: The address length.
nn_topology_tg_detail.dlc_data.address: The address.
nn_topology_tg_detail.rsn: The Resource Sequence Number. This is assigned by the network node that owns this resource.
nn_topology_tg_detail.status: This field specifies the status of the TG. This can be one or more of the following ORed together:
AP_TG_OPERATIVE
AP_TG_CP_CP_SESSIONS
AP_TG_QUIESCING
AP_TG_HPR
AP_TG_RTP
AP_NONE
nn_topology_tg_detail.tg_chars: The TG characteristics. See DEFINE_CN for additional information.

Returned Parameters

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

primary_rc: AP_OK

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 parameter:

primary_rc: AP_FUNCTION_NOT_SUPPORTED

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

primary_rc: AP_INVALID_VERB

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 of a system error, the Program returns the following parameter:

primary_rc: AP_UNEXPECTED_SYSYEM_ERROR