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

The application supplies the following parameters:
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_NODE

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. 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_VRN

If 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

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.
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_LIST_OPTION

AP_INVALID_NODE
AP_INVALID_RESOURCE_TYPES
AP_INVALID_TG

Supplied Parameters

Supplied Parameters when restore = AP_YES

The application supplies the following parameters:
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

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 parameter:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_CHECKSUM_FAILED

AP_DATA_CORRUPT
AP_INVALID_RESOURCE_TYPES

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 has not been built with 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 yet 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_SYSTEM_ERROR