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 book Distributed Data Management.
*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.

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 Space Format for List APIs. 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	Type	Field
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	Type	Field
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	Type	Field
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	Type	Field
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

CHAR(4)

Resource sequence number

CHAR(1)

Route addition resistance

CHAR(1)

Node status

BIT(1)

Node congested

BIT(1)

Intermediate routing resources depleted

BIT(1)

End point routing resources depleted

BIT(2)

Reserved

BIT(1)

Quiescing

BIT(2)

Reserved

CHAR(1)

Node type and support

CHAR(1)

Gateway services support

BIT(1)

Central directory services support

BIT(1)

Intermediate routing services support

BIT(1)

Retired (always set to 1)

BIT(2)

Reserved

BIT(2)

Retired (always set to 1)

CHAR(1)

Additional node support

BIT(1)

Peripheral border node support:

0	The node lacks such support
1	The node has such support

BIT(1)

Interchange node support:

0	The node lacks such support
1	The node has such support

BIT(1)

Extended border node support:

0	The node lacks such support
1	The node has such support

BIT(2)

High performance routing support level:

00	Lacks high performance routing support
01	Supports high performance routing but not the high performance routing transport tower
10	Supports high performance routing and the high performance routing transport tower
11	Reserved

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

CHAR(1)

Transmission group flags

BIT(1)

Link connection network indicator:

0	The transmission group-Partner Node's Network-Qualified CP/PU Name field does not identify a link connection network (such as a local area network)
1	The transmission group-Partner Node's Network-Qualified CP/PU Name field identifies a link connection network

BIT(1)

Reserved

BIT(1)

This transmission group supports high performance routing:

0	No
1	Yes

BIT(2)

Transmission group type:

00	Boundary function based transmission group or APPN transmission group
01	Interchange transmission group
10	Virtual route based transmission group
11	Reserved

BIT(1)

Intersubnetwork link indicator:

0	This link is not an intersubnetwork link.
1	This link is an intersubnetwork link. It defines a border between subnetworks.

BIT(1)

Reserved

BIT(1)

This transmission group goes to a node that supports the high performance routing transport tower:

0	No
1	Yes

Format of Transmission Group Characteristics

The format of the transmission group (TG) characteristics data is described below.

Offset

Bit

Type

Description

Dec

Hex

CHAR(4)

Resource sequence number (reserved except in topology database updates (TDUs)): a 32-bit binary value that uniquely identifies a topology update.

CHAR(1)

Status

BIT(1)

Operational status:

0	The transmission group is not operational
1	The transmission group is operational

BIT(1)

Reserved

BIT(1)

Quiescing:

0	The transmission group is not quiescing
1	The transmission group is quiescing

BIT(1)

CP-CP session support status:

0	CP-CP sessions are supported on this transmission group.
1	CP-CP sessions are not supported on this transmission group.

BIT(4)

Reserved

CHAR(1)

Effective capacity

CHAR(5)

Reserved

CHAR(1)

Cost per connect time

CHAR(1)

Cost per byte transmitted

CHAR(1)

Reserved

CHAR(1)

Security

CHAR(1)

Propagation delay of the transmission group

CHAR(1)

Modem class

CHAR(1)

User-defined parameter 1

CHAR(1)

User-defined parameter 2

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

Top | Network Management APIs | APIs by category