Retrieve Network Server Configuration (QFPRRNWS) API
Required Parameter Group:
| 1 | Receiver variable | OUTPUT | CHAR(*) |
| 2 | Length of receiver variable | INPUT | BINARY(4) |
| 3 | Format name | INPUT | CHAR(8) |
| 4 | Network server configuration name | INPUT | CHAR(10) |
| 5 | Error Code | I/O | CHAR(*) |
Default Public Authority: *USE
Threadsafe: NO
The Retrieve Network Server Configuration (QFPRRNWS) API retrieves information about a network server configuration.
Authorities and Locks
- Network Server Configuration
- *USE
- NWS Configuration Authority Attributes
- Security administrator (*SECADM) special authorities are needed to retrieve password, CHAP secret or pre-shared key values.
Required Parameter Group
- Receiver variable
-
OUTPUT; CHAR(*)
The variable that is to receive the network server configuration information.
- Length of receiver variable
-
INPUT; BINARY(4)
The length of the area that is referred to by the receiver variable parameter. If the amount of information to be returned is greater than this value, the information will be truncated to this length. The minimum length is 8 bytes.
- Format name
-
INPUT; CHAR(8)
The format of the returned network server configuration information. You must use this format:
FPRC0100 Basic network server configuration information FPRC0200 Detailed information for configuration type *CNNSEC FPRC0300 Detailed information for configuration type *RMTSYS FPRC0400 Detailed information for configuration type *SRVPRC See Format of Network Server Configuration for a description of these formats.
- Network server configuration name
-
INPUT; CHAR(10)
The name of the network server configuration to be retrieved.
- 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 Network Server Configuration
When the network server configuration type is unknown, specify FPRC0100 and the basic information (including network server configuration type) will be returned. When the network server configuration type is known, specify one of the other category-specific formats.
For detailed descriptions of the fields returned in these formats, see Field Descriptions.
FPRC0100 Format
Use this format to find out the network server configuration type, plus some basic information about the network server configuration. Then you may use the returned network server configuration type to select one of the other (category-specific) formats to call the API again for detailed information about the network server configuration.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to higher-level format |
| 12 | C | CHAR(7) | Date information retrieved |
| 19 | 13 | CHAR(6) | Time information retrieved |
| 25 | 19 | CHAR(10) | Network server configuration name |
| 35 | 23 | CHAR(10) | Network server configuration library |
| 45 | 2D | CHAR(10) | Validation list name |
| 55 | 37 | CHAR(10) | Validation list library |
| 65 | 41 | CHAR(50) | Text description |
| 115 | 73 | CHAR(1) | Reserved |
| 116 | 74 | BINARY(4) | Configuration type |
FPRC0200 Format
This format returns detailed information about a network server configuration of type *CNNSEC.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| * | * | Returns everything from format FPRC0100 | |
| 0 | 0 | BINARY(4) | Offset to list of IP security rules |
| 4 | 4 | BINARY(4) | Number of IP security rules |
| 8 | 8 | BINARY(4) | Entry length of IP security rules |
| These fields repeat for each security rule | BINARY(4) | IP security rule length | |
| CHAR(64) | IP security rule | ||
FPRC0300 Format
This format returns detailed information about a network server configuration of type *RMTSYS.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| * | * | Returns everything from format FPRC0100 | |
| 0 | 0 | CHAR(10) | Service processor configuration name |
| 10 | A | CHAR(10) | Service processor configuration library |
| 20 | 14 | CHAR(12) | Remote system serial number |
| 32 | 20 | CHAR(24) | Remote system type and model |
| 56 | 38 | BINARY(4) | Delivery method |
| 60 | 3C | CHAR(16) | Target CHAP name |
| 76 | 4C | CHAR(24) | Target CHAP secret |
| 100 | 64 | BINARY(4) | Boot device ID - bus |
| 104 | 68 | BINARY(4) | Boot device ID - device |
| 108 | 6C | BINARY(4) | Boot device ID - function |
| 112 | 70 | CHAR(8) | Dynamic boot vendor ID |
| 120 | 78 | CHAR(8) | Dynamic boot alternate client ID |
| 128 | 80 | BINARY(4) | Offset to list of remote interfaces |
| 132 | 84 | BINARY(4) | Number of remote interfaces |
| 136 | 88 | BINARY(4) | Entry length of remote interfaces |
| 140 | 8C | CHAR(16) | Initiator CHAP name |
| 156 | 9C | CHAR(24) | Initiator CHAP secret |
| These fields repeat for each remote interface | CHAR(12) | SCSI adapter address | |
| BINARY(4) | SCSI internet address version | ||
| CHAR(15) | SCSI internet address | ||
| CHAR(1) | Reserved | ||
| CHAR(15) | SCSI subnet mask | ||
| CHAR(1) | Reserved | ||
| CHAR(15) | SCSI gateway address | ||
| CHAR(1) | Reserved | ||
| BINARY(4) | iSCSI qualified name length | ||
| CHAR(255) | iSCSI qualified name | ||
| CHAR(1) | Reserved | ||
| CHAR(12) | LAN adapter address | ||
| BINARY(4) | LAN internet address version | ||
| CHAR(15) | LAN internet address | ||
| CHAR(1) | Reserved | ||
| CHAR(15) | LAN subnet mask | ||
| CHAR(1) | Reserved | ||
| CHAR(15) | LAN gateway address | ||
| CHAR(20) | Reserved | ||
FPRC0400 Format
This format returns detailed information about a network server configuration of type *SRVPRC.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| * | * | Returns everything from format FPRC0100 | |
| 0 | 0 | BINARY(4) | Initialize service processor |
| 4 | 4 | BINARY(4) | Enable unicast |
| 8 | 8 | BINARY(4) | Service processor name length |
| 12 | C | CHAR(255) | Service processor name |
| 267 | 10B | CHAR(1) | Reserved |
| 268 | 10C | BINARY(4) | Service processor address version |
| 272 | 110 | CHAR(15) | Service processor internet address |
| 287 | 11F | CHAR(15) | Service processor user name |
| 302 | 12E | CHAR(15) | Service processor password |
| 317 | 13D | CHAR(3) | Reserved |
| 320 | 140 | BINARY(4) | SP certificate identifier component |
| 324 | 144 | BINARY(4) | SP certificate identifier compare length |
| 328 | 148 | CHAR(255) | SP certificate identifier compare value |
| 583 | 247 | CHAR(1) | Reserved |
| 584 | 248 | CHAR(12) | Enclosure serial number |
| 596 | 254 | CHAR(24) | Enclosure type and model |
Field Descriptions
The field descriptions are always in alphabetical order.Some of the fields in the various formats returned by this API are described in greater detail in the CRTNWSCFG command that was used to create the network server configuration object. They also are described in the online help for the CRTNWSCFG command. For these fields, the CL parameter keyword is specified in parentheses following the field name. The CL command name is specified in the field description.
In certain cases, numeric values are assigned by this API to represent character values for some of the returned fields. Where a numeric value is assigned, the numeric value and the equivalent character value are listed as an Exception in the following field descriptions.
Boot device ID - bus. The PCI device ID - bus number for the remote system's iSCSI adapter that has been configured to boot.
Exception:
| -1 | The single PCI device ID is used. |
Boot device ID - device. The PCI device ID - device number for the remote system's iSCSI adapter that has been configured to boot.
Exception:
| -1 | The single PCI device ID is used. |
Boot device ID - function. The PCI device ID - function number for the remote system's iSCSI adapter that has been configured to boot.
Exception:
| -1 | The single PCI device ID is used. |
Bytes available. The number of bytes of data available to be returned to the user.
Bytes returned. The number of bytes that were returned to the user. This is the lesser of the number of bytes available to be returned or the length of the receiver variable.
Configuration type (TYPE). The type of the network server configuration.
| 1 | Connection security |
| 2 | Remote system |
| 3 | Service processor |
Date information retrieved. The date that the information was provided by the API. It is returned as 7 characters in the form CYYMMDD, as follows:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
Delivery method (DELIVERY). The delivery method used to deploy security parameters.
| 1 | Dynamic |
| 2 | Manual |
Dynamic boot alternate client ID. Alternate client ID of the remote system's iSCSI adapter.
Exception:
| *ADPT | The remote system's iSCSI adapter address is used the for the alternate client ID. |
Dynamic boot vendor ID. Vendor ID of the remote system's iSCSI adapter.
Exception:
| *DFT | The default vendor ID will be used. |
Enable unicast (ENBUCAST). Enable unicast to discover the remote system.
| 0 | No |
| 1 | Yes |
Enclosure serial number. The enclosure's machine serial number.
Exception:
| *AUTO | The enclosure's machine serial number will be automatically determined once the system has been successfully contacted. |
Enclosure type and model. The enclosure's manufacturer type and model number.
Exception:
| *AUTO | The enclosure's machine serial number will be automatically determined once the system has been successfully contacted. |
Entry length of IP security rule. The entry length in bytes of each element in the list of security rules that are returned with this format. A value of zero is returned if the list is empty.
Entry length of remote interfaces. The entry length in bytes of each element in the list of remote interfaces that are returned with this format. A value of zero is returned if the list is empty.
Initialize service processor (INZSP). The method used to secure the remote system's service processor.
| 0 | None |
| 1 | Auto |
| 2 | Manual |
Initiator CHAP name. Specifies the Challenge Handshake Authentication Protocol (CHAP) name for the remote system's iSCSI initiator to authenticate the System i® iSCSI target.
Exception:
| *NONE | CHAP authentication is not enabled. |
Initiator CHAP secret. Specifies the Challenge Handshake Authentication Protocol (CHAP) secret for the remote system's iSCSI initiator to authenticate the System i iSCSI target.
Exception:
| *NOTAVL | The CHAP secret is unavailable to the caller of the API. The caller of the API must have *SECADM special authorities to retrieve this value. |
| *NONE | CHAP authentication is not enabled. |
IP security rule. The shared secret key used as the Internet Key Exchange (IKE) authentication protocol for the connection.
Exception:
| *NOTAVL | The IP security rule is unavailable to the caller of the API. The caller of the API must have *SECADM special authorities to retrieve this value. |
| *NONE | IP Security (IPSec) protocol security settings are not configured. |
| *REGEN | A random pre-shared key is automatically generated every time the system is varied on. |
IP security rule length. Length in bytes of IP security rule.
iSCSI qualified name. The iSCSI qualified name associated with the remote system's SCSI interface.
Exception:
| *GEN | The iSCSI qualified name associated with the remote system's SCSI interface will be generated once the remote systems serial number has been determined. |
iSCSI qualified name length. The length in bytes of the iSCSI qualified name.
LAN adapter address. The address used by the remote system's LAN interface. This field will be blank if a value has not been specified.
LAN gateway address. The IPv4 gateway address of the remote system's LAN interface. This field will be blank if a value has not been specified.
LAN internet address. The IPv4 address of the remote system's LAN interface. This field will be blank if a value has not been specified. An IPv4 address is expressed in standard dotted-decimal form www.xxx.yyy.zzz (for example, 130.99.128.1).
LAN internet address version. The version of the Internet Protocol (IP) that is currently in use with the remote system's LAN interface.
| 0 | Not specified |
| 2 | Internet Protocol version 4 (IPv4) |
LAN subnet mask. The IPv4 subnet mask of the remote system's LAN interface. This field will be blank if a value has not been specified.
Network server configuration library. The library of the network server configuration.
Network server configuration name. The name of the network server configuration.
Number of IP security rules. The number of entries in the list of security rules returned with this format. A value of zero is returned if the list is empty.
Number of remote interfaces. The number of entries in the list of remote interfaces returned with this format. A value of zero is returned if the list is empty.
Offset to higher-level format. The offset in bytes to the network server configuration information.
Offset to list of IP security rules. The offset in bytes to the first element in the list of security rules that are returned with this format. A value of zero is returned if the list is empty.
Offset to list of remote interfaces. The offset in bytes to the first element in the list of remote interfaces that are returned with this format. A value of zero is returned if the list is empty.
Remote system serial number. The remote system's machine serial number.
Exception:
| *SPNWSCFG | The remote system's machine serial number will use the service processor's managing system machine serial number. |
Remote system type and model. The remote system's manufacturer type and model number.
Exception:
| *SPNWSCFG | The remote system's machine serial number will use the service processor's managing system manufacturer type and model number. |
Reserved. This is an ignored field.
SCSI adapter address. The address used by the remote system's SCSI interface. This field will be blank if a value has not been specified.
SCSI gateway address. The IPv4 gateway address of the remote system's SCSI interface. This field will be blank if a value has not been specified.
SCSI internet address. The IPv4 address of the remote system's SCSI interface. An IPv4 address is expressed in standard dotted-decimal form www.xxx.yyy.zzz (for example, 130.99.128.1). This field will be blank if a value has not been specified.
SCSI internet address version. The version of the Internet Protocol (IP) that is currently in use with the remote system's SCSI interface.
| 0 | Not specified |
| 2 | Internet Protocol version 4 (IPv4) |
SCSI subnet mask. The IPv4 subnet mask of the remote system's SCSI interface. This field will be blank if a value has not been specified.
Service processor address version. The version of the Internet Protocol (IP) that is currently in use with the Remote SP Internet address.
| 0 | Not specified |
| 2 | Internet Protocol version 4 (IPv4) |
Service processor configuration library. The library of the service processor network server configuration.
Service processor configuration name. The name of the service processor network server configuration.
Service processor internet address. The IPv4 address of the remote service processor. This field will be blank if a value has not been specified. An IPv4 address is expressed in standard dotted-decimal form www.xxx.yyy.zzz (for example, 130.99.128.1).
Service processor name (SPNAME). Specifies the remote system's service processor host name. The following special value also may be returned:
Exception:
| *SPINETADR | The remote system is identified by the value specified for Service processor address. |
Service processor name length. Length in bytes of the remote system's service processor host name.
Service processor password. Specifies the remote system's service processor password.
Exception:
| *NOTAVL | The service processor password is unavailable to the caller of the API. The caller of the API must have *SECADM special authorities to retrieve this value. |
Service processor user name. Specifies the remote system's service processor user name.
SP certificate identifier compare length. Specifies the length of the SP certificate compare value.
SP certificate identifier compare value. Specifies the certificates component compare value.
SP certificate identifier component. Specifies the component of the service processor's certificate that will be used to correlate the certificate to this Network Server Configuration for a manually initialized service processor as follows:
| 0 | Service processor certificate is not configured |
| 1 | Common name |
| 2 | E-mail address |
| 3 | Organizational unit |
Target CHAP name. Specifies the Challenge Handshake Authentication Protocol (CHAP) name for the System i iSCSI target to authenticate the remote system's iSCSI initiator.
Exception:
| *NONE | CHAP authentication is not enabled. |
Target CHAP secret. Specifies the Challenge Handshake Authentication Protocol (CHAP) secret for the System i iSCSI target to authenticate the remote system's initiator.
Exception:
| *NOTAVL | The CHAP secret is unavailable to the caller of the API. The caller of the API must have *SECADM special authorities to retrieve this value. |
| *NONE | CHAP authentication is not enabled. |
Text description (TEXT). A brief description of the network server configuration.
Time information retrieved. The time that the information was provided by the API. It is returned as 6 characters in the form HHMMSS where:
| HH | Hour |
| MM | Minute |
| SS | Second |
Validation list library. Specifies the library of the validation list that is used to store authentication information.
Validation list name. Specifies the name of the validation list that is used to store authentication information. Authentication information associated with the network server configuration is used to securely interact with the remote system.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF2189 E | Not authorized to object &1 in &2 type *&3. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF96CB E | Network server configuration &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPFA31E E | Required parameter &1 omitted. |
| CPFB752 E | Internal error in &2 API. |
API introduced: V5R4