SAFE_STORE_TOPOLOGY
SAFE_STORE_TOPOLOGY is only used at a network node and safely stores 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).
The store node 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 index 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 index_node_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). Next, the list is ordered on index_node_type by numeric value. If TGs are being stored or restored, ordering is on index.tg_dest_node_name (MIB ordering), then index.tg_dest_node_type (by numeric value), and thirdly on index.tg_number (by numeric value).
SAFE_STORE_TOPOLOGY verb supercedes the SFS_ADJACENT_NN, SFS_NN_TOPOLOGY_NODE and SFS_NN_TOPOLOGY_TG verbs. It stores topology information using control vectors as they appear in the topology, instead of translating to and from query overlays. Unknown control vectors are stored and restored, and a checksum is provided to prevent corrupt data from being introduced into the topology.
VCB Structure
typedef struct safe_store_topology
{
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 resource_types; /* resource types (nodes, TGs...)*/
RESOURCE_INDEX index; /* resource index */
unsigned long frsn; /* flow-reduction sequence */
/* number */
unsigned char reserv3[16]; /* reserved */
} SAFE_STORE_TOPOLOGY;typedef struct resource_index
{
unsigned char node_name[17]; /* FQ node name */
unsigned char node_type; /* node type */
unsigned char tg_dest_node_name[17];
/* FQ name of TG destination node*/
unsigned char tg_dest_node_type; /* TG destination node type */
unsigned char tg_number; /* TG number */
unsigned char reserv1[3]; /* reserved */
} RESOURCE_INDEX;typedef struct safe_store_data
{
unsigned short overlay_size; /* overalllength of safe */
/* store data */
unsigned short sub_overlay_size; /* offset to first appended */
/* resource */
RESOURCE_INDEX index; /* index of appended resource */
unsigned char checksum[16]; /* reserved */
} SAFE_STORE_DATA;typedef struct safe_store_node_data
{
unsigned short overlay_size; /* overalllength of safe */
/* store data */
unsigned short sub_overlay_size; /* offset to first appended */
unsigned char adjacent; /* is this NNCP and adjacent */
/* NNCP? */
unsigned char reserv1; /* reserved */
unsigned long last_frsn_sent; /* last flow reduction sequence */
/* num sent (if node is adjacent)*/
/* resource */
unsigned long last_frsn_rcvd; /* last flow reduction sequence */
/* num rcvd (if node is adjacent)*/
unsigned long frsn; /* flow reduction sequence number*/
unsigned short days_left /* days left in database */
unsigned short; vector_len /* length of appended vector */
} SAFE_STORE_NODE_DATA;typedef struct safe_store_tg_data
{
unsigned short overlay_size; /* overalllength of safe */
/* store data */
unsigned short sub_overlay_size; /* offset to first appended */
/* resource */
unsigned long frsn; /* flow reduction sequence number*/
unsigned short days_left /* days left in database */
unsigned short vector_len; /* length of appended vector(s) */
} SAFE_STORE_TG_DATA;Supplied Parameters
Supplied Parameters when restore = AP_NO
- opcode
- AP_SAFE_STORE_TOPOLOGY
- 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 resource_types and index specified
(see the following parameters, resource_types and index) 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.
- resource_types
- This bit field controls the topology data to be stored. Any combination
of the following values may be bit-wise ORed together in this field:
- AP_SFS_NODES
- Store topology nodes
- AP_SFS_ADJ_NODES
- Store adjacent nodes
- AP_SFS_TGS
- Store TGs
Note:At least one of these three flags must be set. Adjacent nodes and topology nodes are separate entities within APPN®, so the first two flags can be set in any combination. - index.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. This field is also ignored if neither AP_SFS_NODES nor AP_SFS_ADJ_NODES is set in resource_types.
- index.node_type
- Type of the node. This node is set to one of the following:
AP_NETWORK_NODE
AP_VRN
AP_LEARN_NODEIf 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. This field is also ignored if neither AP_SFS_NODES nor AP_SFS_ADJ is set in resource_types.
- index.tg_dest_node_name
- 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. This field is also ignored if neither AP_SFS_NODES nor AP_SFS_ADJ_NODES is set in resource_types.
- index.tg_dest_node_type
- Type of the the destiation node for this TG. This node is set to one
of the following:
AP_NETWORK_NODE
AP_VRNIf the tg_dest_node_type is unknown, AP_LEARN_NODE must be specified. This field is ignored if list_options is set to AP_FIRST_IN_LIST. This field is also ignored if neither AP_SFS_TGS is not set in resource_types.
- index.tg_number
- The number associated with the TG. This field is ignored if list_options is set to AP_FIRST_IN_LIST. This field is also ignored if neither AP_SFS_TGS is not set in resource_types.
- frsn
- Flow Reduction Sequence Number (FRSN). If this is nonzero, then only topology resources with a FRSN greater than or equal to this value is returned.
- safe_store_data.overlay_size
- The length of this entry, including any padding. This is the offset to the next SAFE_STORE_DATA overlay, if any.
- safe_store_data.sub_overlay_size
- The length of this entry, including any padding. This is the offset to the appended SAFE_STORE_DATA or SAFE_STORE_TG_DATA. This field should always be used when accessing the appended data.
- safe_store_data.index
- The index for this entry. This structure can be supplied on subsequent SAFE_STORE_TOPOLOGY verbs to list subsequent entries. If dest_tg_name is set to all binary zeros, a SAFE_STORE_NODE_DATA overlay follows. Otherwise, a SAFE_STORE_TG_DATA overlay follows.
- safe_store_data.checksum
- The 128–bit checksum for the appended overlay and vectors. If this checksum and the following data becomes corrupted, it is highly probable that the corruption is detected and the verb is rejected.
- safe_store_node_data.overlay_size
- The length of this entry, including any padding. This is the offset to the appended SAFE_STORE_DATA or SAFE_STORE_TG_DATA.
- safe_store_node_data.sub_overlay_size
- The length of this entry, including any padding. This is the offset to the appended SAFE_STORE_DATA or SAFE_STORE_TG_DATA. This field should always be used to access the appended vectors.
- safe_store_node_data.adjacent
- AP_YES or AP_NO. If AP_YES, this entry corresponds to an adjacent Network Node.
- safe_store_node_data.last_frsn_sent
- If adjacent is set to AP_YES, this field holds the last FRSN sent to the adjacent Network Node. Otherwise, this field is set to zero.
- safe_store_node_data.last_frsn_rcvd
- If adjacent is set to AP_YES, this field holds the last FRSN sent to the adjacent Network Node. Otherwise, this field is set to zero.
- safe_store_node_data.frsn
- The Flow Reduction Sequence Number for this topology resource, if this node appears in the topology. Otherwise, this field is set to zero.
- safe_store_node_data.days_left
- The number of days this node remains in the topology database before being removed, unless its existence is can be confirmed. Zero signifies no limit.
- safe_store_node_data.vector_len
- The length of appended vectors. Zero signifies no vectors are appended.
- safe_store_tg_data.overlay_size
- The length of this entry, including any padding. This is the offset to the appended SAFE_STORE_DATA or SAFE_STORE_TG_DATA.
- safe_store_tg_data.sub_overlay_size
- The length of this entry, including any padding. This is the offset to the appended vectors, if there are any. This field should always be used to accessed appended vectors.
- safe_store_tg_data.frsn
- The Flow Reduction Sequence Number for this TG.
- safe_store_tg_data.days_left
- The number of days this TG remains in the topology database before being removed, unless its existence is can be confirmed. Zero signifies no limit.
- safe_store_tg_data.vector_len
- The length of appended vectors. Zero signifies no vectors are appended.
Returned 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.
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_INVALID_LIST_OPTION
AP_INVALID_NODE
AP_INVALID_RESOURCE_TYPES
AP_INVALID_TG
Supplied Parameters
Supplied Parameters when restore = AP_YES
- opcode
- AP_SAFE_STORE_TOPOLOGY
- 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.
- restore
- Flag indicating whether the information should be restored (AP_YES) or stored (AP_NO). In this case, it is set to AP_NO.
- resource_types
- This bit field controls the topology data to be stored. Any combination
of the following values may be bit-wise ORed together in this field:
- AP_SFS_NODES
- Restore topology nodes
- AP_SFS_ADJ_NODES
- Restore adjacent nodes
- AP_SFS_TGS
- Restore TGs
Note:At least one of these three flags must be set. Adjacent nodes and topology nodes are separate entities within APPN®, so the first two flags can be set in any combination.
Returned Parameters
- primary_rc
- AP_OK
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_CHECKSUM_FAILED
AP_DATA_CORRUPT
AP_INVALID_RESOURCE_TYPES
- primary_rc
- AP_FUNCTION_NOT_SUPPORTED
- primary_rc
- AP_INVALID_VERB
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR