Retrieve Network Attributes (QWCRNETA) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Number of network attributes to retrieve | Input | Binary(4) |
| 4 | Network attribute names | Input | Array(*) of Char(10) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Network Attributes (QWCRNETA) API lets you retrieve network attributes.
Authorities and Locks
None.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the information requested. For the format, see Format of Data Returned.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable described in Format of Data Returned. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 28 bytes.
- Number of network attributes to retrieve
- INPUT; BINARY(4)
The total number of network attributes to be retrieved.
- Network attribute names
- INPUT: ARRAY(*) of CHAR(10)
The names of the network attributes to be retrieved. This can be a list of network attribute names where each name is 10 characters.
- 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 Data Returned
The receiver variable holds the information returned about each network attribute.
The receiver variable has three logical parts:
- The first field specifies the number of network attributes returned.
- The next fields give the offsets to the network attributes returned. There is one offset field for each network attribute returned.
- Next are the network attribute information tables for the network attributes returned. There is one network attribute information table for each network attribute.
The format of the receiver variable is:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of network attributes returned |
| 4 | 4 | ARRAY(*) of BINARY(4) | Offset to network attribute information table |
| * | * | CHAR(*) | Network attribute information table |
| Note: Each network attribute in the table is represented by the standard network attribute information table described in Network Attribute Information Table. | |||
To determine the length of the receiver variable, the following calculation should be done. For each network attribute to be returned, get the length of the data returned for the network attribute and add 24. After adding the values for each network attribute, add 4. This calculation takes into account the data alignment that needs to be done; therefore, this value is a worst-case estimate.
Network Attribute Information Table
The following table shows the format of the network attribute information table.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Network attribute |
| 10 | A | CHAR(1) | Type of data |
| 11 | B | CHAR(1) | Information status |
| 12 | C | BINARY(4) | Length of data |
| 16 | 10 | CHAR(*) | Data |
Field Descriptions
Data. The data returned for the network attribute.
Information status. Whether the information was available for the network attribute.
| blank | The information was available. |
| L | The information was not available because the network attribute was locked. |
Length of data. The length of the data returned for the network attribute. If this value is 0, the network attribute was not available.
Network attribute. The network attribute to be retrieved. See Valid Network Attributes for the list of valid network attributes.
Number of network attributes returned. The number of network attributes returned to the application.
Offset to network attribute information table. The offset from the beginning of the structure to the start of the network attribute information.
Type of data. The type of data returned.
| blank | The data was not available. |
| C | The data is returned in character format. |
| B | The data is returned in binary format. |
Valid Network Attributes
For a detailed description of each field, see Network Attribute Field Descriptions.
| Network attribute | Type | Description |
|---|---|---|
| ALRBCKFP | CHAR(16) | Alert backup focal point |
| ALRCTLD | CHAR(10) | Alert controller |
| ALRDFTFP | CHAR(10) | Alert focal point |
| ALRFTR | CHAR(20) | Alert filter |
| ALRHLDCNT | BINARY(4) | Alert hold count |
| ALRLOGSTS | CHAR(7) | Alert logging status |
| ALRPRIFP | CHAR(10) | Alert primary focal point |
| ALRRQSFP | CHAR(16) | Alert focal point to request |
| ALRSTS | CHAR(10) | Alert status |
| ALWADDCLU | CHAR(10) | Allow add to cluster |
| ALWANYNET | CHAR(10) | Allow AnyNet® support |
| ALWHPRTWR | CHAR(10) | Allow HPR tower support |
| ALWVRTAPPN | CHAR(10) | Allow virtual APPN support |
| VRTAUTODEV | BINARY(4) | Autocreate APPC device limit |
| DDMACC | CHAR(20) | DDM request access |
| DFTCNNLST | CHAR(10) | Default ISDN connection list |
| DFTMODE | CHAR(8) | Default mode |
| DFTNETTYPE | CHAR(10) | ISDN network type |
| DTACPR | BINARY(4) | Data compression |
| DTACPRINM | BINARY(4) | Intermediate data compression |
| HPRPTHTMR | CHAR(40) | HPR path switch timers |
| JOBACN | CHAR(10) | Job action |
| LCLCPNAME | CHAR(8) | Local control point |
| LCLLOCNAME | CHAR(8) | Local location |
| LCLNETID | CHAR(8) | Local network ID |
| MAXINTSSN | BINARY(4) | Maximum sessions |
| MAXHOP | BINARY(4) | Maximum hop count |
| MDMCNTRYID | CHAR(2) | Modem country or region ID |
| MSGQ | CHAR(20) | Message queue |
| NETSERVER | CHAR(85) | Server network ID |
| NODETYPE | CHAR(8) | APPN node type |
| NWSDOMAIN | CHAR(8) | Network server domain |
| OUTQ | CHAR(20) | Output queue |
| PNDSYSNAME | CHAR(8) | Pending system name |
| PCSACC | CHAR(20) | Client Access |
| RAR | BINARY(4) | Addition resistance |
| SYSNAME | CHAR(8) | Current system name |
Network Attribute Field Descriptions
Addition resistance. The Advanced Peer-to-Peer Networking® (APPN) function routes addition resistance for an APPN node type of *NETNODE or *BEXNODE.
Alert backup focal point. Identifies the system that provides alert focal point services if the local system is unavailable and ALRPRIFP is *YES. The backup focal point is only used by systems in the primary sphere of control. The first eight characters are the control point name and the last eight characters are the network ID. *NONE means no backup focal point is defined.
Alert controller. The name of the controller to be used for alerts in a system service control point - physical unit (SSCP-PU) session. This controller is ignored if the system has a focal point (in which case the node is in another system's sphere of control). *NONE means no alert controller is defined.
Alert filter. The name of the filter object that is used by the alert manager when processing alerts. *NONE means no alert filter is being used. The first ten characters are the filter name and the last ten characters are the library name.
Alert focal point. Whether or not the system is an alert default focal point.
| *NO | The system is not an alert default focal point. |
| *YES | The system is defined to be an alert default focal point and provides focal point services to all nodes in the network that are not being serviced by another focal point. |
Alert focal point to request. Specifies the name of the system that is requested to provide focal point services. If a focal point is already defined for the entry point, it is taken away when the new focal point is requested. *NONE means no focal point is requested.
Alert hold count. The maximum number of alerts to be created before the alerts are sent over the System Service Control Point - Physical Unit (SSCP-PU) session. Alerts are held by the system until this number of alerts have been created. If the Alert Controller (ALRCTLD) network attribute is being used to send alerts (SSCP-PU session), alerts will be sent automatically regardless of the ALRHLDCNT network attribute when a switched connection is made for other reasons.
Alert logging status. Specifies which alerts are to be logged:
| *LOCAL | Only locally created alerts are logged. |
| *RCV | Only Alerts received from other nodes are logged. |
| *ALL | Both locally created alerts and incoming alerts are logged. |
| *NONE | No alerts are logged. |
Alert primary focal point. Whether or not the system is an alert primary focal point.
| *NO | The system is not an alert primary focal point. |
| *YES | The system is defined to be an alert primary focal point and provides focal point services to all nodes in the network that are explicitly defined in the sphere of control. |
Alert status. Alert status controls the creation of local alerts. The following is a list of values and their meanings:
| *ON | Alerts are created by a system for all changeable conditions except unattended conditions. |
| *UNATTEND | Alerts are created by the system for all alert conditions including those which have the alert indicator in the message description set to *UNATTEND. |
| *OFF | Alerts are not created by the system. |
Allow add to cluster. Whether this system will allow another system to add it as a node in a cluster. The following is a list of values and their meanings:
| *NONE | No other system can add this system as a node in a cluster. |
| *ANY | Any other system can add this system as a node in a cluster. |
| *RQSAUT | Any other system can add this system as a node in a cluster only after the cluster add request has been authenticated. |
Allow AnyNet® support. The AnyNet support value is used for the UNIX®-type APIs that use the AF_INET address family. The following is a list of values and their meanings:
| *NO | The system does not allow AF_INET support to be used over an SNA connection. |
| *YES | The system allows AF_INET (AnyNet) support to be used over an SNA connection. |
Allow HPR tower support. The HPR transport tower support value is used for APPN session traffic. The following is a list of values and their meanings:
| *NO | The system does not allow HPR transport tower support to be used with APPN session traffic. |
| *YES | The system allows HPR transport tower support to be used with APPN session traffic. |
Allow virtual APPN support. The virtual APPN support value is used to specify whether or not APPC sessions and devices are allowed to use virtual APPN controllers.
| *NO | The system does not allow APPC sessions or devices to use virtual APPN controllers. If sessions are using HPR transport tower support, they will use virtual APPN controllers regardless of this setting. |
| *YES | The system does allow APPC sessions or devices to use virtual APPN controllers. |
Autocreate APPC device limit. The specification for the APPC device limit used for autocreation of devices on virtual APPN controllers.
APPN node type. The Advanced Peer-to-Peer Networking (APPN) node type can have the following values:
| *ENDNODE | The node does not provide network services to other nodes, but may participate in the APPN network by using the services of an attached network server, or may operate in a peer environment similar to migration end nodes. |
| *NETNODE | The node provides intermediate routing, route selection services, and distributed directory services for local users and to end nodes and migration end nodes that it is serving. |
| *BEXNODE | The node performs as a branch extender node. The node performs as an end node in the backbone APPN network, and performs as a network node server to end nodes within its local domain. |
Client Access. The way in which the system processes Client Access requests from other systems.
| *REJECT | The system rejects every request from Client Access. |
| *OBJAUT | Normal object authorizations are checked for the Client Access request. For example, authorization to retrieve data from a database file for a transfer function request is checked. |
| *REGFAC | The system uses the system's registration facility to determine which exit program (if any) to run. If no exit program is defined for an exit point and this value is specified, *OBJAUT is used. |
| program library | The name of a user-written validation program that is called each time a Client Access application request comes from a personal computer. The program is passed two parameters: the first describes the PC request (the name of the application and type request); the second is used by the program to indicate to the Client Access application whether or not this PC request should be handled. The first 10 characters are the program name, and the last 10 characters are the library name. |
Current system name. The current system name that appears on displays.
Data compression. Whether data compression is used when the system is an SNA end node (the node containing either a primary or secondary LU). This field is used by mode descriptions that specify *NETATR for data compression. The following values are valid:
| 0 | Data compression is not allowed on the session. |
| -1 | Data compression is requested on the session by the local system. However, the request can be refused or changed to a lower compression level by the remote system. Data compression is allowed on the session if requested by the remote system. |
| -2 | Data compression is allowed on the session by the local system if requested by a remote system. The local system does not request that compression be used. |
| -3 | Data compression is required on the session. If the remote system does not change the levels of compression to the local system's exact requested levels, the session is not established. The data compression levels that the local system requires are the specified levels. |
| line speed | If either the receiving or sending link has a line speed equal to or less than this specified line speed, this value indicates the need for compression by requesting that the remote systems compress the session data. Otherwise, this value does not indicate to the remote systems that there is a need to compress the data. Possible values range from 1 through 2 147 483 647 bits per second. |
If data compression is requested by the remote system, the data compression levels used by the session are the lower of the requested levels and the configured levels (INDTACPR and OUTDTACPR).
DDM request access. The system processes distributed data management (DDM) and Distributed Relational Database Architecture™ (DRDA®) requests from other systems as follows:
| *REJECT | The system does not allow DDM or DRDA requests from remote systems. This system can still use DDM or DRDA, however, to access files or SQL tables on remote systems. |
| *OBJAUT | All requests are allowed and controlled by the object authorization on the system. |
| program library | The name of a user-written validation program that is called each time a DDM request is made from a remote system. This program indicates to DDM whether the request should proceed or be ended. System security still applies. The first ten characters are the program name and the last ten characters are the library name. |
Default ISDN connection list. The name of the default integrated services digital network (ISDN) connection list object. The operating system no longer uses this network attribute. Changes made to this network attribute have no effect.
Default mode. The default mode name for the system.
HPR path switch timers. The settings for the amount of time, in minutes, to allow for a path switch attempt of a Rapid Transport Protocol (RTP) connection. Four positional values exist to specify the time allowed based on the type of session traffic. Each positional timer will consist of 10 characters within the 40-character field. A description of each element within the field is given below:
- Network priority timer (characters 1-10)
- The first element is the network priority timer, which specifies the amount
of time in minutes to allow for a path switch attempt of an RTP connection that
has network transmission priority or *NONE.
- High priority timer (characters 11-20)
- The second element is the high priority timer, which specifies the amount
of time in minutes to allow for a path switch attempt of an RTP connection that
has high transmission priority or *NONE.
- Medium priority timer (characters 21-30)
- The third element is the medium priority timer, which specifies the amount
of time in minutes to allow for a path switch attempt of an RTP connection that
has medium transmission priority or *NONE.
- Low priority timer (characters 31-40)
- The fourth element is the low priority timer, which specifies the amount of time in minutes to allow for a path switch attempt of an RTP connection that has low transmission priority or *NONE.
Intermediate data compression. The level of data compression to request when the system is an SNA intermediate node. The following are valid values:
| 0 | Does not indicate to the remote systems that there is a need to compress the data. |
| -1 | Indicates the need for compression by requesting that the remote systems compress the session data. |
| line speed | If either the receiving or sending link has a line speed equal to or less than this specified line speed, this value indicates the need for compression by requesting that the remote systems compress the session data. Otherwise, this value does not indicate to the remote systems that there is a need to compress the data. Possible values range from 1 through 2 147 483 647 bits per second. |
ISDN network type. The type of integrated services digital network (ISDN) to which the system is attached. The operating system no longer uses this network attribute. Changes made to this network attribute have no effect.
Job action. The action that is taken for any input stream received through the SNA distribution services (SNADS) network by the system.
| *REJECT | The input stream is rejected by the system. This action allows users to secure their system from input streams received through the network. |
| *FILE | The input stream is filed in the queue of network files received for the user to whom it was sent. That user may then look at the input stream, end it, receive it, or submit it to a job queue. |
| *SEARCH | The table of network job entries is searched to determine the action to be taken for the input stream. |
Local control point. The local control point name for the system.
Local location. The default local location name for the system.
Local network ID. The local network ID assigned to the system.
Maximum hop count. The maximum number of times in an SNA distribution services (SNADS) network that a distribution queue entry originating at this node may be received and routed on the path to its final destination. If this number is exceeded, the distribution queue entry is ended. When the distribution queue entry is ended, a feedback status is sent back to the sender if it was requested.
Maximum sessions. The maximum number of advanced program-to-program communications (APPC) intermediate sessions for an Advanced Peer-to-Peer Networking (APPN) node type of *NETNODE or *BEXNODE.
Message queue. The name of the message queue to which messages received through the SNA distribution services (SNADS) network are sent for:
- Users who have no message queue specified in their user profile
- Users whose message queue is not available
The first 10 characters are the message queue name, and the last 10 characters are the library name.
Modem country or region ID. The country or region identifier associated with a modem.
This defines the country or region-specific default characteristics for modems that are internal to IBM® i I/O adapters. This value must be configured correctly to ensure proper operation and, in some countries or regions, meet legal requirements. The adapter will fail the vary on of the line if the modem country or region ID is not set.
Network server domain. The LAN server domain to which all Integrated xSeries® Servers (also known as file server I/O processor and FSIOP) on the system belong.
Output queue. The name of the output queue to which spooled files received through the SNA distribution services (SNADS) network are sent for users whose output queue is not available. The first 10 characters are the output queue name, and the last 10 characters are the library name.
Pending system name. The pending system name (if a change is pending). This will contain blanks if no change is pending.
Server network ID. The network node server of an Advanced Peer-to-Peer Networking (APPN) network (up to a maximum of five) for an APPN node type of *ENDNODE. The list is not used for an APPN node type of *NETNODE or *BEXNODE.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1860 E | Value &1 in list not valid. |
| CPF1861 E | Length of the receiver variable not valid. |
| CPF1862 E | Number of values to retrieve not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3