Open List Network Servers (QFPADOLS) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | List information | Output | Char(80) |
| 4 | Number of records to return | Input | Binary(4) |
| 5 | Format name | Input | Char(8) |
| 6 | Server name qualifier | Input | Char(*) |
| 7 | Length of server name qualifier | Input | Binary(4) |
| 8 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Open List Network Servers (QFPADOLS) API retrieves a list of servers. The functions provided by this API are similar to the Work with Network Server Status (WRKNWSSTS) command.
Authorities and Locks
- Network Server Description Authority
- *USE
- Network Server Description Lock
- *EXCLRD
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of the receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of the receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 0 bytes.
- List information
- OUTPUT; CHAR(80)
Information about the list created by this program. For a description of the layout of this parameter, see Format of List Information.
- Number of records to return
- INPUT; BINARY(4)
The number of records in the list to put into the receiver variable. The value must be 0 or greater.
- Format name
- INPUT; CHAR(8)
The format of the information returned. You must use one of the the following format names:
DOLS0100 The output server list structure for Windows® servers only. For more information, see DOLS0100 Format. DOLS0200 The output server list structure for all server types in the hosting partition. For more information, see DOLS0200 Format.
- Server name qualifier
- INPUT; CHAR(*)
A restriction on the information to be retrieved. This parameter allows the caller to request a subset of the entries that normally would be returned on a given format. If this parameter is *ALL, no information qualification is performed. Allowable values are:
*ALL Information about all servers. Server name Information about the specified server name entry only. Generic server name* Information about servers matching the generic server name string.
- Length of server name qualifier
- INPUT; BINARY(4)
The length of the server name qualifier.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
DOLS0100 Format
Format DOLS0100 returns Windows server information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next server entry |
| 4 | 4 | BINARY(4) | Length of server entry |
| 8 | 8 | CHAR(8) | Network server description (NWSD) name |
| 16 | 10 | CHAR(1) | Server status |
| 17 | 11 | CHAR(3) | Reserved |
| 20 | 14 | BINARY(4) | Displacement to server name |
| 24 | 18 | BINARY(4) | Length of server name |
| 28 | 1C | BINARY(4) | Displacement to domain name |
| 32 | 20 | BINARY(4) | Length of domain name |
| 36 | 24 | BINARY(4) | Displacement to server description |
| 40 | 28 | BINARY(4) | Length of server description |
| 44 | 2C | BINARY(4) | Displacement to DNS domain name |
| 48 | 30 | BINARY(4) | Length of DNS domain name |
| 52 | 34 | CHAR(10) | Hardware resource name |
| 62 | 3E | CHAR(4) | Hardware resource type |
| 66 | 42 | CHAR(3) | Hardware resource model |
| 69 | 45 | CHAR(6) | Integrated Server Support version |
| 75 | 4B | CHAR(7) | Integrated Server Support service pack |
| 82 | 52 | CHAR(2) | Reserved |
| 84 | 54 | BINARY(4) | Displacement to list of Integrated Server Support hot fix entries |
| 88 | 58 | BINARY(4) | Length of an Integrated Server Support hot fix entry |
| 92 | 5C | BINARY(4) | Number of Integrated Server Support hot fix entries |
| 96 | 60 | CHAR(10) | Windows version |
| 106 | 6A | CHAR(10) | Windows build number |
| 116 | 74 | CHAR(128) | Windows service pack level |
| 244 | F4 | BINARY(4) | NWSD server status |
| 248 | F8 | BINARY(4) | System pool identifier |
| See note | See note | CHAR(*) | Server name |
| See note | See note | CHAR(*) | Domain name |
| See note | See note | CHAR(*) | Server description |
| See note | See note | CHAR(*) | DNS domain name |
| These fields repeat for each Integrated Server Support hot fix. | CHAR(7) | Integrated Server Support hot fix | |
| CHAR(1) | Reserved | ||
| Note: The displacement to the server name, domain name, server description, and DNS domain name and hot fix are specified in the respective displacement variables. | |||
DOLS0200 Format
Format DOLS0200 returns Windows, VMware ESX, Linux, AIX® and IBM® i Network Server Information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next server entry |
| 4 | 4 | BINARY(4) | Length of server entry |
| 8 | 8 | CHAR(8) | Network server description (NWSD) name |
| 16 | 10 | CHAR(1) | Server status |
| 17 | 11 | CHAR(3) | Reserved |
| 20 | 14 | BINARY(4) | Displacement to server name |
| 24 | 18 | BINARY(4) | Length of server name |
| 28 | 1C | BINARY(4) | Displacement to domain name |
| 32 | 20 | BINARY(4) | Length of domain name |
| 36 | 24 | BINARY(4) | Displacement to server description |
| 40 | 28 | BINARY(4) | Length of server description |
| 44 | 2C | BINARY(4) | Displacement to DNS domain name |
| 48 | 30 | BINARY(4) | Length of DNS domain name |
| 52 | 34 | BINARY(4) | Displacement to server operating system description |
| 56 | 38 | BINARY(4) | Length of server operating system description |
| 60 | 3C | CHAR(10) | Hardware name |
| 70 | 46 | CHAR(24) | Hardware type and model |
| 94 | 5E | CHAR(12) | Hardware serial number |
| 106 | 6A | CHAR(10) | Server operating system type |
| 116 | 74 | CHAR(10) | NWSD connection type |
| 126 | 7E | CHAR(10) | NWSD operating system |
| 136 | 88 | CHAR(6) | Operating system integration version |
| 142 | 8E | CHAR(7) | Operating system integration service level |
| 149 | 95 | CHAR(10) | Server operating system version |
| 159 | 9F | CHAR(10) | Server operating system build ID |
| 169 | A9 | CHAR(128) | Server operating system service level |
| 297 | 129 | CHAR(1) | Server enrollment enabled |
| 298 | 12A | CHAR(1) | Domain enrollment enabled |
| 299 | 12B | CHAR(1) | SBMNWSCMD enabled |
| 300 | 12C | CHAR(1) | Server statistics enabled |
| 301 | 12D | CHAR(1) | Dynamic unlinking enabled |
| 302 | 12E | CHAR(1) | Synchronize integration software enabled |
| 303 | 12F | CHAR(24) | Hardware type and model at install |
| 327 | 147 | CHAR(1) | Reserved. |
| 328 | 148 | BINARY(4) | NWSD server status |
| 332 | 14C | BINARY(4) | System pool identifier |
| See note | See note | CHAR(*) | Server name |
| See note | See note | CHAR(*) | Domain name |
| See note | See note | CHAR(*) | Server description |
| See note | See note | CHAR(*) | DNS domain name |
| See note | See note | CHAR(*) | Server operating system description |
| Note: The displacement to the server name, domain name, server description, DNS domain name, and server operating system description are specified in the respective displacement variables. | |||
Field Descriptions
Displacement to DNS domain name. The displacement in bytes from the beginning of the record to the domain name of the Domain Name System (DNS).
Displacement to domain name. The displacement in bytes from the beginning of the record to the domain name.
Displacement to list of Integrated Server Support hot fix entries. The displacement to the first entry in the Integrated Server Support hot fix list.
Displacement to next server entry. The displacement in bytes from the beginning of the record to the next server entry. If this is the last entry, this value will be zero.
Displacement to server description. The displacement in bytes from the beginning of the record to the server description.
Displacement to server name. The displacement in bytes from the beginning of the record to the server name.
Displacement to server operating system description. The displacement in bytes from the beginning of the record to the server operating system description.
DNS domain name. The domain name system (DNS) domain name of this server.
Domain enrollment enabled. Indicates if user profiles may be enrolled to the Domain name.
| '0' | No, enrollment is not supported to this servers domain name. |
| '1' | Yes, enrollment is supported to this servers domain name. |
Domain name. The domain name of this server.
Dynamic unlinking enabled. Indicates if NWS Storage Space dynamic unlinking operations are supported for this server.
| '0' | No, dynamic unlinking is not supported on this server. |
| '1' | Yes, dynamic unlinking is support on this server. |
Hardware name. The hardware resource name of the input/output adapter (IOA), or the remote system NWSCFG name for iSCSI connected servers.
Hardware resource model. The hardware resource model of the input/output adapter (IOA) for the server.
Hardware resource name. The hardware resource name of the input/output adapter (IOA) for the server.
Hardware resource type. The hardware resource type of the input/output adapter (IOA) for the server.
Hardware serial number. The serial number of the remote server hardware. When not available the value will be *N.
Hardware type and model. The remote server hardware type and model, or the hardware resource type input/output adapter (IOA) for the server. Hardware type and model at install. The remote server hardware type and model, or the hardware resource type input/output adapter (IOA) used when the server was originally installed. When not available the value will be *N.
Integrated Server Support hot fix. The identifier for an Integrated Server Support hot fix that is installed on the server.
Integrated Server Support service pack. The identifier for an Integrated Server Support service pack that is installed on the server. When not available the value will be *N.
Integrated Server Support version. The version number of the Integrated Server Support product that is installed on the server. The value has the format VxRyMz, where x is the version, y is the release, and z is the modification. When not available the value will be *N.
Length of an Integrated Server Support hot fix entry. The length of one Integrated Server Support hot fix entry.
Length of DNS domain name. The length of this DNS domain name.
Length of domain name. The length of this domain name.
Length of server description. The length of this server description.
Length of server entry. The length of this server entry.
Length of server name. The length of this server name.
Length of server operating system description. The length of this server operating system description.
Network server description (NWSD) name. The name of the network server description.
Number of Integrated Server Support hot fix entries. The number of times the Integrated Server Support hot fix entries are repeated. Hot fix entries are never used, so this field value will always be zero.
NWSD connection type. The NWSD Server connection value. The possible values are:
| *IXSVR | The NWSD uses an integrated network server connection. |
| *ISCSI | The NWSD uses an iSCSI connection. |
| *GUEST | The NWSD uses an operating system running in a logical partition. |
NWSD operating system. The NWSD Server operating system value. The possible values are:
| *WIN32 | The network server description is for a 32bit Windows operating system. |
| *LINUX32 | The network server description is for a 32bit Linux operating system. |
| *WIN64 | The network server description is for a 64bit Windows operating system. |
| *LINUX64 | The network server description is for a 64bit Linux operating system. |
| *ESX | The network server description is for a VMware ESX ®system. |
| *ESXE | The network server description is for a VMware ESX ® embedded system. |
| *LINUXPPC | The network server description is for a Linux PowerPC® operating system. |
| *AIXPPC | The network server description is for an AIX PowerPC operating system. |
| *OPSYS | The network server description is for IBM i . |
 |
|
| *AUX | The network server description is for an auxiliary server operating system. |
|
NWSD server status. The NWSD Server Status value. The possible values are:
| 0 | Varied Off - network server is varied off. |
| 10 | Vary Off Pending - network server is in the process of being varied off. |
| 20 | Vary On Pending - network server is in the process of being varied on. |
| 30 | Vary On - network server is varied on. |
| 60 | Active - network server is active. |
| 80 | Recovery Pending - error recovery operation is pending. |
| 100 | Failed - device not usable. |
| 107 | Shutdown - shutdown pending for network server. |
| 110 | Diagnostic Mode - the network server has been put in diagnostic mode. |
| 111 | Damage - the network server has incurred hard damage and cannot be used again. |
| 113 | Unknown - the network server status cannot be determined. This is an exception condition. |
| 114 | Degraded - storage path temporarily or permanently disabled. |
Operating system integration service level. The identifier for the operating system integration service level that is installed on the server. When not available the value will be *N.
Operating system integration version. The version number of the operating system integration product that is installed on the server. The value has the format VxRyMz, where x is the version, y is the release, and z is the modification. When not available the value will be *N.
Reserved. Reserved space.
SBMNWSCMD enabled. Indicates if the SBMNWSCMD CL command is supported to this server.
| '0' | No, SBMNWSCMD is not supported to this server. |
| '1' | Yes, SBMNWSCMD is supported to this server. |
Server description. The server description.
Server enrollment enabled. Indicates whether user profiles may be enrolled to this server name.
| '0' | No, enrollment to the server name is not available. |
| '1' | Yes, enrollment to the server name is available. |
Server name. The name of this server. The operating systems server name is retrieved for *IXSVR and *ISCSI connection types. The NWSD name is returned for *GUEST connection types.
Server operating system build ID. The current build identifier of the server operating system. When not available the value will be *N.
Server operating system description. A description of the operating system on the server. The values is retrieved from the remote server. When not available, the value will be *N.
Server operating system service level. The current service level of the operating system on the server. When not available the value will be *N.
Server operating system type. The remote server operating system type. The possible values are:
| *WINDOWS | Windows operating system types. |
| *LINUX | Linux operating system types. |
| *ESX | VMware ESX system types. |
| *AIX | AIX operating system types. |
Server operating system version. The current version of the operating system on the server. When not available the value will be *N.
Server statistics enabled. Indicates if server statistics are supported for this server.
| '0' | No, server statistics are not supported. |
| '1' | Yes, server statistics are supported. |
Server status. The status of the server. The possible values follow:
| 0 | Active |
| 1 | Inactive |
| 2 | Restricted |
| 3 | Pending |
| 4 | Unknown |
| 5 | Ending |
| 6 | Failed |
| 7 | Partially shut down |
| 8 | Degraded |
| 9 | Connection Pending |
Synchronize integration software enabled. Indicates if operating system operations are supported to directly update integration software on this server.
| '0' | No, integration software synchronization is not supported. |
| '1' | Yes, integration software synchronization is supported. |
System pool identifier. System-related pool identifier specified to be used for both guest servers and iSCSI virtual I/O operations.
Windows build number. The current build number of the Windows operating system on the server.
Windows service pack level. The current service pack level of the Windows operating system on the server.
Windows version. The current version of the Windows operating system on the server.
Format of List Information
The following table shows the format of the list information parameter. For detailed descriptions of the field in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Total records |
| 4 | 4 | BINARY(4) | Records returned |
| 8 | 8 | CHAR(4) | Request handle |
| 12 | C | BINARY(4) | Record length |
| 16 | 10 | CHAR(1) | Information complete indicator |
| 17 | 11 | CHAR(13) | Date and time created |
| 30 | 1E | CHAR(1) | List status indicator |
| 31 | 1F | CHAR(1) | Reserved |
| 32 | 20 | BINARY(4) | Length of information returned |
| 36 | 24 | BINARY(4) | First record in buffer |
| 40 | 28 | CHAR(40) | Reserved |
Field Descriptions
Date and time created. The date and time the list was created. The 13 characters are:
| 1 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | The date, in YYMMDD (year, month, day) format. |
| 8-13 | The time of day, in HHMMSS (hours, minutes, seconds) format. |
First record in buffer. The number of the first record in the receiver variable.
Information complete indicator. Whether all information requested has been supplied.
| I | Incomplete information. An interruption caused the list to contain incomplete information about a buffer or buffers. |
| P | Partial and accurate information. Partial information is returned when the maximum space was used and not all of the buffers requested were read. |
| C | Complete and accurate information. All the buffers requested were read and returned. |
Length of information returned. The size, in bytes, of the information returned in the receiver variable.
List status indicator. The status of the list building. The indicators are:
| 0 | The list building is pending. |
| 1 | The list is in the process of being built. |
| 2 | The list has been built completely. |
| 3 | An error occurred while building the list. The next call to QGYGTLE will cause the error to be signaled to the caller of QGYGTLE. |
Record length. The length of each record of information returned. For variable length records, this value is set to 0. For variable length records, you can obtain the length of individual records from the records themselves.
Records returned. The number of records returned in the receiver variable. This is the smallest of the following values:
- The number of records that fit into the receiver variable.
- The number of records in the list.
- The number of records requested.
Request handle. The handle of the request that can be used for subsequent requests of information from the list. The handle is valid until the Close List (QGYCLST) API is called to close the list or until the job ends.
Note: This field should be treated as a hexadecimal field. It should not be converted from one CCSID to another (for example, EBCDIC to ASCII) because doing so could result in an unusable value.
Reserved. Reserved field. Must be set to hexadecimal or binary zero.
Total records. The total number of records available in the list.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2625 E | Not able to allocate object &1. |
| CPF2634 E | Not authorized to object &1. |
| CPF3C17 E | Error occurred with input data parameter. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C1F E | Pointer is not on a 16 byte boundary. |
| 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. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF9806 E | Cannot perform function for object &2 in library &3. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V4R5