Register APPN Topology Information (QNMRGTI) API
Required Parameter Group:
| 1 | Queue handle | Output | Binary(4) |
| 2 | Options | Input | Array of Char(10) |
| 3 | Number of options | Input | Binary(4) |
| 4 | Format | Input | Char(8) |
| 5 | Qualified user space name | Input | Char(20) |
| 6 | Qualified queue name | Input | Char(20) |
| 7 | Queue type | Input | Char(10) |
| 8 | Replace registration | Input | Char(10) |
| 9 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Register APPN Topology Information (QNMRGTI) API causes the requested APPN topology information to be reported. The application calling this API may request the current copy of the entire database (to be reported to the specified user space), or may register for information about particular types of ongoing updates to the topology (to be reported to the registered queue), or both.
A queue handle is returned by this program when a queue is successfully registered for topology updates. The queue handle identifies a registered queue, and must be used when the Deregister APPN Topology Information (QNMDRGTI) API is called. The queue handle is unique to a specific job.
When a queue is registered for ongoing topology updates, the specified types of updates for which the queue is registered will be asynchronously enqueued on an ongoing basis. If current topology is also requested on the application calling this API, the current topology is reported to the user space before topology updates are reported to the registered queue.
The QNMRGTI API may be called to request the current topology only (without updates), updates only (without current topology), or both current topology and updates. This is determined by the options specified in the options parameter.
If an application program calling the API requests current topology, and the complete topology data cannot be returned in the user space, an error is returned. In this situation, the user space header contains a P in the information status field indicating partial but accurate data. Even if a user space error such as this occurs, any queue registered on the API call will remain registered.
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- Queue Authority
- *CHANGE
- Queue Library Authority
- *USE
- User Space Lock
- *EXCLRD
Required Parameter Group
- Queue handle
- OUTPUT; BINARY(4)
A variable that uniquely identifies the registered queue within the job. This value is returned when a queue is registered. When the *CURRENT value is the only option specified in the options parameter, 0 is returned.
- Options
- INPUT; Array OF CHAR(10)
An array structure containing options specifying the topology information to be reported. These options only apply to topology updates. All deletions are reported regardless of the type of updating information you want.
One or more of the following values must be specified:
*CURRENT Report the current copy of the entire topology database. *LOCALEN Register for local topology updates pertaining to adjacent end nodes. Local topology consists of the local node, adjacent nodes, and links to adjacent nodes. See Local and Network Topology Updates for more details. *LOCALNN Register for local topology updates pertaining to adjacent network nodes. This option must be used if updates pertaining to adjacent network nodes in a disconnected subnetwork, such as network nodes having a different network ID, are required. *LOCALVN Register for local topology updates pertaining to adjacent virtual nodes. An APPN virtual node represents a connection network (for example, an attached token-ring network). For more information, see the Distributed database programming topic collection. *NETNN Register for network topology updates pertaining to network nodes. *NETVN Register for network topology updates pertaining to virtual nodes.
- Number of options
- INPUT; BINARY(4)
The number of options specified in the options parameter. Valid values are 1 through 6.
- Format
- INPUT; CHAR(8)
The content and format of the topology information reported. The valid values are:
APPN0100 The basic APPN topology information format. See APPN0100 Format for a description of this format. APPN0200 The basic APPN topology information format. See APPN0200 Format for a description of this format.
- Qualified user space name
- INPUT; CHAR(20)
The user space that is to receive current topology information. This parameter is ignored when the *CURRENT value is not specified on the options parameter. The first 10 characters specify the user space name, and the last 10 characters specify the library name.
The following special values are supported for the library name:
*LIBL The library list. *CURLIB The job's current library.
- Qualified queue name
- INPUT; CHAR(20)
The queue that is to receive requested topology information. This parameter is ignored when the *CURRENT value is the only option specified on the options parameter. The first 10 characters specify the queue object name, and the last 10 characters specify the library name.
The following special values are supported for the library name:
*LIBL The library list. *CURLIB he job's current library. When special values are used for the library name, the actual name will be substituted when the API is called. The actual name will be used in future references to the object when topology updates are enqueued.
The following considerations apply to the queue specified on the API call:
- The queue object must exist when this API is called.
- There is no restriction that prevents applications in separate jobs from
registering the same queue object. Therefore, each application should ensure it
registers a unique queue to prevent duplicate topology updates from being
reported to the same queue. For example, specifying a queue in library QTEMP
ensures the queue is not being used by other jobs on the system.
- The maximum entry length of the queue must be at least 128 bytes.
- The sequence of the queue must be *FIFO.
- A data queue defined with FORCE(*YES) is allowed, but is discouraged due to
degraded performance.
- A data queue defined with SENDERID is allowed, but the application is responsible for ensuring sufficient record length to handle the additional data on queue elements.
- The queue object must exist when this API is called.
- Queue type
- INPUT; CHAR(10)
The type of queue object. This parameter is ignored when *CURRENT is the only value specified on the options parameter.
Otherwise, one of the following values must be specified:
*DTAQ Data queue *USRQ User queue Replace registration
- Replacement Registration
- INPUT; CHAR(10)
Whether this registration should replace a previous registration that has the same qualified queue name and type. This parameter is ignored when *CURRENT is the only value specified on the options parameter.
*YES This registration replaces any previous registration with the same qualified queue name and type. The options specified on this registration replace options from any previous registration. *NO This registration does not replace any existing registration with the same qualified queue name and type. The existing registration is not changed.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of the Generated List
The user space is used to report current topology information and consists of:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section
For details about the user area and generic header, see User spaces. For details about the other items, see the following sections. For a detailed description of each field in the information returned, see Field Descriptions.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | CHAR(8) | Format name specified |
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name used |
| 10 | A | CHAR(10) | User space library name used |
| 20 | 14 | BINARY(4) | Number of nodes reported |
| 24 | 18 | CHAR(8) | Timestamp of list data |
| 32 | 20 | CHAR(8) | Timestamp when local node initialized |
| 40 | 28 | BINARY(4) | Number of end nodes reported |
| 44 | 2C | BINARY(4) | Number of transmission groups reported for all end nodes |
| 48 | 30 | BINARY(4) | Number of transmission groups reported for all network and virtual nodes |
| 52 | 34 | CHAR(8) | Local node network ID |
| 60 | 3C | CHAR(8) | Local node control point name |
| 68 | 44 | BINARY(4) | Local topology database flow reduction sequence number |
| 72 | 48 | CHAR(3) | Local node type |
| 75 | 4B | CHAR(1) | Reserved |
| 76 | 4C | BINARY(4) | Local node type enumeration |
| 80 | 50 | BINARY(2) | Length of local node network-qualified control point name |
| 82 | 52 | CHAR(17) | Local node network-qualified control point name |
| 99 | 63 | CHAR(1) | Reserved |
| 100 | 64 | BINARY(4) | Number of nodes deleted since local node initialized |
| 104 | 68 | BINARY(4) | Number of transmission groups deleted since local node initialized |
APPN0100 Format
The format of topology entry data is the same for queue entries reported on the registered queue for topology updates and deletions as for list entries reported to the user space for the current topology.
For topology entries reported to the user space, the entry ID field contains the value that indicates a current topology entry.
For topology entries reported to the registered queue, the entry ID field contains a value that identifies the type of notification reported:
- Topology entry updated
- Topology entry deleted
- Topology database deleted
The format of the topology entry is described below. See Field Descriptions for descriptions of the fields in this format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Entry type |
| 10 | A | CHAR(2) | Entry ID |
| 12 | C | CHAR(8) | Timestamp |
| 20 | 14 | CHAR(8) | Node network ID |
| 28 | 1C | CHAR(8) | Node control point name |
| 36 | 24 | BINARY(4) | Number of associated transmission group entries |
| 40 | 28 | CHAR(1) | Node data valid indicator |
| 41 | 29 | CHAR(3) | Node type |
| 44 | 2C | CHAR(8) | Node attributes |
| 52 | 34 | CHAR(8) | Transmission group destination network ID |
| 60 | 3C | CHAR(8) | Transmission group destination control point name |
| 68 | 44 | BINARY(4) | Transmission group number |
| 72 | 48 | CHAR(20) | Transmission group characteristics |
| 92 | 5C | BINARY(4) | Length of DLC signaling information |
| 96 | 60 | CHAR(16) | DLC signaling information |
| 112 | 70 | CHAR(10) | Controller description object name |
| 122 | 7A | CHAR(1) | Transmission group flags |
| 123 | 7B | CHAR(5) | Reserved |
APPN0200 Format
See Field Descriptions for descriptions of the fields in this format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Entry type |
| 10 | A | CHAR(2) | Entry ID |
| 12 | C | BINARY(4) | Node entry time left |
| 16 | 10 | BINARY(4) | Node flow reduction sequence number |
| 20 | 14 | BINARY(2) | Length of node network-qualified name |
| 22 | 16 | CHAR(17) | Node network-qualified control point name |
| 39 | 27 | CHAR(1) | Reserved |
| 40 | 28 | BINARY(4) | Node type enumeration |
| 44 | 2C | CHAR(8) | Node attributes |
| 52 | 34 | BINARY(4) | Number of associated transmission group entries |
| 56 | 38 | CHAR(4) | Transmission group number |
| 60 | 3C | BINARY(2) | Length of transmission group destination network-qualified name |
| 62 | 3E | CHAR(17) | Transmission group destination network-qualified control point name |
| 79 | 4F | CHAR(1) | Transmission group flags |
| 80 | 50 | CHAR(20) | Transmission group characteristics |
| 100 | 64 | BINARY(4) | Transmission group entry time left |
| 104 | 68 | BINARY(4) | Transmission group flow reduction sequence number |
| 108 | 6C | BINARY(2) | Length of DLC signaling information |
| 110 | 6E | CHAR(8) | DLC signaling information |
| 118 | 76 | CHAR(10) | Controller description object name |
Field Descriptions
Controller description object name. The name of the controller description object for the transmission group. This field is valid only when the number of associated transmission group entries field is not zero. The object name is only available for transmission group entries associated with the local node, and only when the object currently exists on the local system. When the object name is not available, this field contains blanks.
DLC signaling information. The data link control (DLC) signaling information related to the link connection network. For token ring, the first 6 bytes is the MAC address, and the seventh byte is the link layer service access point address. This field is valid only when the number of associated transmission group entries field is not zero.
Entry ID. The type of topology information. The possible values are listed below. Value 00 is always used in topology entries reported to only the user space.
The other three values are used for topology entries reported to the registered queue.
| 00 | The entry reported is present in the current APPN topology database. |
| 01 | The entry reported was updated in the APPN topology database. |
| 02 | The entry reported was deleted from the APPN topology database. APPN performs cleanup of the APPN topology database once every 24 hours. This cleanup may cause multiple entries to be removed from the APPN topology database. |
| 03 | The current APPN topology database was deleted and reinitialized with the node entry for the local system. The node entry for the local system is reported on the entry. Any additions to the newly initialized topology database will follow in subsequent queue entries. This indication may be reported, for example, when the node type parameter changes as a result of the Change Network Attributes (CHGNETA) command, causing the APPN topology database to be deleted. |
Entry type. The type of queue entry.
This field can contain the following special value:
| *APPNTOP | The entry contains APPN topology information. |
Format name specified. The format name specified to the API.
Length of DLC signaling information. The length of the data link control (DLC) signaling information. This field is valid only when the number of associated transmission group entries field is not zero. The value is 7 for token ring (only DLC currently allowed), or 0 when there is no DLC signaling information available.
Length of local node network-qualified control point name. The length of the node network-qualified control point name. Valid range is 3-17.
Length of node network-qualified name. The length of the node network-qualified name.
Length of transmission group destination network-qualified name. The length of the transmission group destination network-qualified control point name. When the number of associated transmission group entries is zero, this value is zero. When the number of associated transmission group entries is not zero, valid values range from 3 through 17.
Local node control point name. The control point name for the local node.
Local node network ID. The network ID for the local node.
Local node network-qualified control point name. The network-qualified control point name for the local node, in the format NETID.CPNAME.
Local node type. The APPN node type of the local node. The valid values are:
| *EN | APPN end node |
| *NN | APPN network node |
| *VN | APPN virtual node |
Local node type enumeration. A number representing the APPN node type of the node. The valid values are:
| 0 | Node data not valid (this may occur when an entry only contains transmission groups owned by this node). |
| 1 | APPN network node |
| 2 | APPN end node |
| 3 | APPN virtual node |
Local topology database flow reduction sequence number. The flow reduction sequence number (FRSN) incremented each time the local network node sends a topology database update. This field is valid only when the local node type is a network node.
Node attributes. The attributes of the node. See Format of Node Attributes Field for the structure. For format APPN0100, the data in this field is valid only when the node data valid indicator field is Y. For format APPN0200, the data in this field is valid only when the node type enumeration is not 0.
Node control point name. The control point name for the node.
Node data valid indicator. Whether values contained in the format APPN0100 node type and attributes fields are valid. The valid values are:
| Y | The values contained in the node type and the node attributes fields are valid. |
| N | The values contained in the node type and the node attributes fields are not valid. This may occur when an entry only contains associated transmission groups owned by this node. |
Node entry time left. The number of days left before the node entry is deleted from the topology database. This field in the APPN0200 format is valid only when the node type enumeration is not 0.
Node flow reduction sequence number. The flow reduction sequence number (FRSN) for the node. This field in the APPN0200 format is valid only when the local node is a network node and the node type enumeration is 1 or 3 (the node is a network node or virtual node).
Node and transmission group FRSN numbers are not broadcast on topology data updates (TDUs) and not duplicated on every network node in the network. Each network node keeps its own node and transmission group FRSN for each node and transmission group in the topology database. FRSNs are used to minimize TDU exchanges with adjacent network nodes.
Node network ID. The network ID for the node.
Node network-qualified control point name. The network-qualified control point name for the node, in the format NETID.CPNAME.
Node type. The APPN node type of the node. This field in the APPN0100 format contains blanks when the node data valid indicator field is N. The valid values are:
| *EN | APPN end node |
| *NN | APPN network node |
| *VN | APPN virtual node |
There is no distinction made between APPN end nodes and low-entry networking (LEN) nodes. Any node defined as a LEN node is reported as *EN.
Node type enumeration. A number representing the APPN node type of the node. This field is used only for format APPN0200. The valid values are:
| 0 | Node Data not valid (this may occur when an entry only contains transmission groups owned by this node). |
| 1 | APPN network node |
| 2 | APPN end node |
| 3 | APPN virtual node |
Number of associated transmission group entries. The number of transmission group (TG) entries reported for a node. When this value is not zero, the specified number of associated transmission groups are reported for the node. The first associated transmission group entry is reported on the same entry as the initial node entry, and any additional transmission groups are reported on subsequent entries.
Number of end nodes reported. The total number of end nodes returned in the list (end node entries containing valid node data).
Number of nodes deleted since local node initialized. The number of node entries deleted from the topology database since the local node was initialized.
Number of nodes reported. The total number of node entries returned in the list (entries containing valid node data).
Number of transmission groups deleted since local node initialized. The number of transmission group entries deleted from the topology database since the local node was initialized.
Number of transmission groups reported for all end nodes. The total number of associated transmission groups returned in the list owned by end nodes.
Number of transmission groups reported for all network and virtual nodes. The total number of associated transmission groups returned in the list owned by network nodes and virtual nodes.
Reserved. An ignored field.
Transmission group characteristics. The transmission group (TG) characteristics. See Format of Transmission Group Characteristics for the structure. This field is valid only when the number of associated transmission group entries field is not zero.
Transmission group destination control point name. The control point name for the transmission group (TG) destination node. This field is blank when the number of associated transmission group entries field is zero.
Transmission group destination network ID. The network ID for transmission group (TG) destination node. This field is blank when the number of associated transmission group entries field is zero.
Transmission group destination network-qualified control point name. The network-qualified control point name for the transmission group destination node, in the format NETID.CPNAME. This field is blank when the number of associated transmission group entries field is zero.
Transmission group entry time left. The number of days left before the transmission group entry is deleted from the topology database. This field in the APPN0200 format is valid only when the number of associated transmission group entries field is not zero.
Transmission group flags. The format of the transmission group flags data is described in Format of Transmission Group Flags Field. This field is valid only when the number of associated transmission group entries field is not zero.
Transmission group flow reduction sequence number. The flow reduction sequence number (FRSN) for the transmission group. This field in the APPN0200 format is valid only when the number of associated transmission group entries field is not zero, the local node is a network node, and the transmission group reported is owned by a network node or virtual node.
Node and transmission group FRSN numbers are not broadcast on topology data updates (TDUs) and not duplicated on every network node in the network. Each network node keeps its own node and transmission group FRSN for each node and transmission group in the topology database. FRSNs are used to minimize TDU exchanges with adjacent network nodes.
Transmission group number. The transmission group (TG) number. This field is valid only when the number of associated transmission group entries field is not zero.
Timestamp. The machine timestamp (time of day) when reported.
Timestamp of list data. The machine timestamp of the list data.
Timestamp when local node initialized. The machine timestamp when the local node was initialized. The local node is initialized at initial program load (IPL) time and when the APPN node type changes.
User space library name specified. The user space library name specified to the API.
User space library name used. The actual user space library name used to report data.
User space name specified. The user space name specified to the API.
User space name used. The actual user space name used to report data.
Format of Node Attributes Field
The format of the node attributes field is described below.
| Offset | Bit | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Dec | Hex | |||||||||||
| 0 | 0 | CHAR(4) | Resource sequence number | |||||||||
| 4 | 4 | CHAR(1) | Route addition resistance | |||||||||
| 5 | 5 | CHAR(1) | Node status | |||||||||
| 5 | 5 | 0 | BIT(1) | Node congested | ||||||||
| 5 | 5 | 1 | BIT(1) | Intermediate routing resources depleted | ||||||||
| 5 | 5 | 2 | BIT(1) | End point routing resources depleted | ||||||||
| 5 | 5 | 3 | BIT(2) | Reserved | ||||||||
| 5 | 5 | 5 | BIT(1) | Quiescing | ||||||||
| 5 | 5 | 6 | BIT(2) | Reserved | ||||||||
| 6 | 6 | CHAR(1) | Node type and support | |||||||||
| 6 | 6 | 0 | CHAR(1) | Gateway services support | ||||||||
| 6 | 6 | 1 | BIT(1) | Central directory services support | ||||||||
| 6 | 6 | 2 | BIT(1) | Intermediate routing services support | ||||||||
| 6 | 6 | 3 | BIT(1) | Retired (always set to 1) | ||||||||
| 6 | 6 | 4 | BIT(2) | Reserved | ||||||||
| 6 | 6 | 6 | BIT(2) | Retired (always set to 1) | ||||||||
| 7 | 7 | CHAR(1) | Additional node support | |||||||||
| 7 | 7 | 0 | BIT(1) | Peripheral border node support:
|
||||||||
| 7 | 7 | 1 | BIT(1) | Interchange node support:
|
||||||||
| 7 | 7 | 2 | BIT(1) | Extended border node support:
|
||||||||
| 7 | 7 | 3 | BIT(2) | High performance routing support
level:
|
||||||||
| 7 | 7 | 5 | BIT(2) | Reserved | ||||||||
Format of Transmission Group Flags Field
The format of the transmission group flags data is described below.
| Offset | Bit | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Dec | Hex | |||||||||||
| 0 | 0 | CHAR(1) | Transmission group flags | |||||||||
| 0 | 0 | 0 | BIT(1) | Link connection network
indicator:
|
||||||||
| 0 | 0 | 1 | BIT(1) | Reserved | ||||||||
| 0 | 0 | 2 | BIT(1) | This transmission group supports high
performance routing:
|
||||||||
| 0 | 0 | 3 | BIT(2) | Transmission group type:
|
||||||||
| 0 | 0 | 5 | BIT(1) | Intersubnetwork link indicator:
|
||||||||
| 0 | 0 | 6 | BIT(1) | Reserved | ||||||||
| 0 | 0 | 7 | BIT(1) | This transmission group goes to a
node that supports the high performance routing transport tower:
|
||||||||
Format of Transmission Group Characteristics
The format of the transmission group (TG) characteristics data is described below.
| Offset | Bit | Type | Description | |||||
|---|---|---|---|---|---|---|---|---|
| Dec | Hex | |||||||
| 0 | 0 | CHAR(4) | Resource sequence number (reserved except in topology database updates (TDUs)): a 32-bit binary value that uniquely identifies a topology update. | |||||
| 4 | 4 | CHAR(1) | Status | |||||
| 4 | 4 | 0 | BIT(1) | Operational status:
|
||||
| 4 | 4 | 1 | BIT(1) | Reserved | ||||
| 4 | 4 | 2 | BIT(1) | Quiescing:
|
||||
| 4 | 4 | 3 | BIT(1) | CP-CP session support status:
|
||||
| 4 | 4 | 4 | BIT(4) | Reserved | ||||
| 5 | 5 | CHAR(1) | Effective capacity | |||||
| 6 | 6 | CHAR(5) | Reserved | |||||
| 11 | B | CHAR(1) | Cost per connect time | |||||
| 12 | C | CHAR(1) | Cost per byte transmitted | |||||
| 13 | D | CHAR(1) | Reserved | |||||
| 14 | E | CHAR(1) | Security | |||||
| 15 | F | CHAR(1) | Propagation delay of the transmission group | |||||
| 16 | 10 | CHAR(1) | Modem class | |||||
| 17 | 11 | CHAR(1) | User-defined parameter 1 | |||||
| 18 | 12 | CHAR(1) | User-defined parameter 2 | |||||
| 19 | 13 | CHAR(1) | User-defined parameter 3 | |||||
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3CAA E | List is too large for user space &1. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF91C2 E | Queue type must be *DTAQ or *USRQ. |
| CPF91C3 E | Internal processing error. |
| CPF91C4 E | Queue &5/&4 with type &6 already registered. |
| CPF91C5 E | Queue &2/&1 not valid. |
| CPF91C7 E | Options list not valid. |
| CPF91C8 E | Replace registration must be *YES or *NO. |
| CPF9800 E | All CPF98xx messages could be signaled. xx is from 01 to FF. |
API introduced: V2R3
[ Back to top | Network Management APIs | APIs by category ]