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.
Start of change
DOLS0200 The output server list structure for *WINDOWS, *LINUX, and *AIX NWS server types (*NETWARE servers are excluded) in the hosting partition. For more information, see DOLS0200 Format.
End of change

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) iSeries Integration version
75 4B CHAR(7) iSeries Integration service pack
82 52 CHAR(2) Reserved
84 54 BINARY(4) Displacement to list of iSeries Integration hot fix entries
88 58 BINARY(4) Length of an iSeries Integration hot fix entry
92 5C BINARY(4) Number of iSeries Integration hot fix entries
96 60 CHAR(10) Windows version
106 6A CHAR(10) Windows build number
116 74 CHAR(128) Windows service pack level
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 iSeries Integration hot fix. CHAR(7) iSeries Integration 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.


Start of change

DOLS0200 Format

Format DOLS0200 returns *WINDOWS, *LINUX, and *AIX 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
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.
End of change

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 iSeries Integration hot fix entries. The displacement to the first entry in the iSeries Integration 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.

Start of change Displacement to server operating system description. The displacement in bytes from the beginning of the record to the server operating system description. End of change

DNS domain name. The domain name system (DNS) domain name of this server.

Start of change 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.
End of change

Domain name. The domain name of this server.

Start of change 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.
End of change

Start of change Hardware name. The hardware resource name of the input/output adapter (IOA), or the remote system NWSCFG name for iSCSI connected servers. End of change

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.

Start of change Hardware serial number. The serial number of the remote server hardware. When not available the value will be *N. End of change

Start of change 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. End of change

iSeries Integration hot fix. The identifier for an iSeries Integration hot fix that is installed on the server.

iSeries Integration service pack. The identifier for an iSeries Integration service pack that is installed on the server. Start of change When not available the value will be *N. End of change

iSeries Integration version. The version number of the iSeries 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. Start of change When not available the value will be *N. End of change

Length of an iSeries Integration hot fix entry. The length of one iSeries Integration 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.

Start of change Length of server operating system description. The length of this server operating system description. End of change

Network server description (NWSD) name. The name of the network server description.

Number of iSeries Integration hot fix entries. The number of times the iSeries Integration hot fix entries are repeated. Start of change Hot fix entries are never used, so this field value will always be zero. End of change

Start of change 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.
End of change

Start of change 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.
*LINUXPPC The network server description is for a Linux Power PC operating system.
*AIXPPC The network server description is for an AIX Power PC operating system.
End of change

Start of change 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. End of change

Start of change 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. End of change

Reserved. Reserved space.

Start of change 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.
End of change

Server description. The server description.

Start of change 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.
End of change

Server name. The name of this server. Start of change The operating systems server name is retrieved for *IXSVR and *ISCSI connection types. The NWSD name is returned for *GUEST connection types.End of change

Start of change

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 retreived 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.
*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.
End of change

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
Start of change
8 Degraded
End of change

Start of change 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.
End of change

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 signalled 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:

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.

Note: CPF2634 and CPF2625 messages are returned in the error code parameter, and are not signaled.


API introduced: V4R5
Top | Server Support APIs | APIs by category