Retrieve Monitored Resource Information (QfpadRtvMonitoredResourceInfo) API


  Required Parameter Group:

1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
3 Format of receiver variable Input Char(8)
4 Manager type Input Char(10)
5 Monitored resource information Input Char(*)
6 Length of monitored resource information Input Binary(4)
7 Format of monitored resource information Input Char(8)
8 Server information Input Char(*)
9 Length of server information Input Binary(4)
10 Format of server information Input Char(8)
11 Server defined output Output Char(*)
12 Error code I/O Char(*)

  Service Program Name: QFPADAP1

  Default Public Authority: *EXCLUDE

  Threadsafe: Yes

The Retrieve Monitored Resource Information (QfpadRtvMonitoredResourceInfo) API returns information about monitored resources in a cluster administrative domain.

A monitored resource may be a system object or a set of attributes not associated with a specific system object, such as the set of system environment variables. System objects and attributes are monitored by the system to allow notifications of changes to the attributes to be passed to a supporting system function or application for system management purposes. See Cluster administrative domain for more information about monitored resources.

This API returns information about monitored resources within a cluster administrative domain. The API cannot be called from a cluster node that is not in the domain node list of the cluster administrative domain. If cluster resource services is not started on the node in the domain node list where the API was called, or the cluster administrative domain nodes are partitioned, the information returned may not reflect the most current information in the cluster administrative domain.

Authorities and Locks

User Profile Authority
*READ
Job Description Authority
*USE
Class Authority
*USE
Configuration Object Authority
*USE
NWS Configuration Authority
*USE
NWS Storage Space Authority
*X
Subsystem Description Authority
*OBJOPR, *READ
Start of changeAuthorization List Authority
*USEEnd of change
Library Authority
*EXECUTE

Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)

The receiver variable to hold the monitored resource entry information.

Length of receiver variable
INPUT; BINARY(4)

The length of the receiver variable in bytes. The minimum length is 8 bytes. If the length of the receiver variable is not large enough to hold the repeating fields of the information specified in the Monitored Resource Entry Information Format Name parameter, only the number of records specified by the Number of Records Returned field will be returned.

Format of receiver variable
INPUT; CHAR(8)

The format name of the monitored resource entry information which will be returned. The following format names are allowed:

DENR0100 Information about one or more monitored resource entries.

DENR0200 Information about the monitored attributes for a single monitored resource.

DENR0300 Information about the monitored attributes, including compound attribute entries, for a single monitored resource.

DENR0310 Information about the monitored attributes, including compound attribute entries, for a single monitored resource. The attribute value information is returned in character format.

Manager type
INPUT; CHAR(10)

The management function which is to monitor the resource. *ADMDMN must be specified.

Monitored resource information
INPUT; CHAR(*)

Information to identify the monitored resource or resources that are to be returned. See EENT0100 for a description of the monitored resource information.

Length of monitored resource information
INPUT; BINARY(4)

The length of the monitored resource information. The length must be at least as large as the monitored resource information format plus the specified length of the resource name.

Format of monitored resource input information
INPUT; CHAR(8)

The format name of the monitored resource information. The following format name is allowed:

EENT0100 The format of the monitored resource input information in a cluster administrative domain.

Server information
INPUT; CHAR(*)

Information about the server. When the manager type is *ADMDMN, the server is the cluster administrative domain.

Length of server information
INPUT; BINARY(4)

The length of the server information. The length of the server information parameter must be set to the size of the SRVI0100 structure.

Format of server information
INPUT; CHAR(8)

The format name of the server information. The following format name is allowed:

SRVI0100 The format of the server information when the server is a cluster.

Server defined output
OUTPUT; CHAR(*)

Information returned which is specific to the server type. When the manager type is *ADMDMN, the following information is returned:

Information status. One byte which indicates the consistency of the retrieved information.

0 The information is consistent for all active nodes in the cluster administrative domain.
1 The information retrieved from the node running the API may not be consistent with all active nodes in the cluster. In order to obtain consistent information, start Cluster Resource Services on the node running the API if it is not active.

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


Monitored Resource Entry Information (DENR0100 Format)

Offset Type Field
Dec Hex
0 0 BINARY(4) Bytes returned
4 4 BINARY(4) Bytes available
8 8 BINARY(4) Offset to first record
12 C BINARY(4) Length of fixed portion of record
16 10 BINARY(4) Number of records returned
Note: Record entry information. These fields are repeated for each record entry returned.
BINARY(4) Displacement to next record
CHAR(10) Monitored resource type
CHAR(10) Monitored resource library name
BINARY(4) Global resource status
BINARY(4) Local resource status
BINARY(4) Displacement to monitored resource name
BINARY(4) Length of monitored resource name
BINARY(4) Displacement to node array
BINARY(4) Length of node array entry
BINARY(4) Number of node array entries
BINARY(4) Displacement to message information
BINARY(4) Length of message information
Note: Use the displacements in the fixed portion of the record to get to the following fields.
CHAR(*) Monitored resource name
CHAR(*) Node array
CHAR(*) Message information


Attribute Information (DENR0200 Format)

Attribute List Entry Format describes the format of the attribute list.

Offset Type Field
Dec Hex
0 0 BINARY(4) Bytes returned
4 4 BINARY(4) Bytes available
8 8 BINARY(4) Offset to first record
12 C BINARY(4) Length of fixed portion of record
16 10 BINARY(4) Number of records returned
Note: Record entry information. These fields are repeated for each record entry returned.
BINARY(4) Displacement to next record
CHAR(10) Monitored resource type
CHAR(10) Monitored resource library name
BINARY(4) Global resource status
BINARY(4) Local resource status
BINARY(4) Displacement to monitored resource name
BINARY(4) Length of monitored resource name
BINARY(4) Displacement to attribute list
BINARY(4) Length of fixed portion of attribute list entry
BINARY(4) Number of attribute list entries
BINARY(4) Additional information available
Note: Use the displacements in the fixed portion of the record to get to the following fields.
CHAR(*) Monitored resource name
CHAR(*) Attribute list


Attribute Information (DENR0300 and DENR0310 Formats)

Attribute List Entry 2 Format describes the format of the attribute list.

Offset Type Field
Dec Hex
0 0 BINARY(4) Bytes returned
4 4 BINARY(4) Bytes available
8 8 BINARY(4) Offset to first record
12 C BINARY(4) Length of fixed portion of record
16 10 BINARY(4) Number of records returned
Note: Record entry information. These fields are repeated for each record entry returned.
BINARY(4) Displacement to next record
CHAR(10) Monitored resource type
CHAR(10) Monitored resource library name
BINARY(4) Global resource status
BINARY(4) Local resource status
BINARY(4) Displacement to monitored resource name
BINARY(4) Length of monitored resource name
BINARY(4) Displacement to attribute list
BINARY(4) Length of fixed portion of attribute list entry
BINARY(4) Number of attribute list entries
Note: Use the displacements in the fixed portion of the record to get to the following fields.
CHAR(*) Monitored resource name
CHAR(*) Attribute list


Attribute List Entry Format

For detailed descriptions of the fields in this table, see Field Descriptions.

Offset Type Field
Dec Hex
0 0 BINARY(4) Displacement to next attribute list entry
4 4 BINARY(4) Attribute status
8 8 BINARY(4) Data type
12 C BINARY(4) Displacement to attribute name
16 10 BINARY(4) Length of attribute name
20 14 BINARY(4) Displacement to attribute value
24 18 BINARY(4) Length of attribute value
CHAR(*) Attribute name
CHAR(*) Attribute value


Attribute List Entry 2 Format

For detailed descriptions of the fields in this table, see Field Descriptions.

Offset Type Field
Dec Hex
0 0 BINARY(4) Displacement to next attribute list entry
4 4 BINARY(4) Attribute status
8 8 BINARY(4) Attribute type
12 C BINARY(4) Data type
16 10 BINARY(4) Displacement to attribute name
20 14 BINARY(4) Length of attribute name
24 18 BINARY(4) Displacement to attribute value
28 1C BINARY(4) Length of attribute value
    CHAR(*) Attribute name
CHAR(*) Attribute value
CHAR(*) Compound attribute list


Compound Attribute List Format

For detailed descriptions of the fields in this table, see Field Descriptions.

Offset Type Field
Dec Hex
0 0 BINARY(4) Displacement to first compound attribute entry
4 4 BINARY(4) Number of compound attribute entries
This field repeats for each number of compound attribute entries. CHAR(*) Compound attribute entry


Compound Attribute Entry Format

For detailed descriptions of the fields in this table, see Field Descriptions.

Offset Type Field
Dec Hex
0 0 BINARY(4) Displacement to next compound attribute entry
4 4 BINARY(4) Global entry status
8 8 BINARY(4) Local entry status
12 C BINARY(4) Data type
16 10 BINARY(4) Displacement to attribute value
20 14 BINARY(4) Length of attribute value
CHAR(*) Attribute value



Message Information Format

For detailed descriptions of the fields in this table, see Field Descriptions.

Offset Type Field
Dec Hex
0 0 CHAR(7) Message ID
7 7 CHAR(10) Message file
17 11 CHAR(10) Message library
27 1B CHAR(1) Reserved
28 1C BINARY(4) Displacement to message replacement data
32 20 BINARY(4) Length of message replacement data
36 24 BINARY(4) Message replacement data CCSID
40 28 CHAR(*) Message replacement data

Message information is available when the global status is INCONSISTENT.


Field Descriptions

Additional information available. Specifies whether or not addition information about the resource is available though the use of another format. Possible values are:

0 NO All information about the resource was returned.
1 YES More information concerning compound attributes is available. Use the DENR0300 or DENR0310 format to retrieve the additional information.

Attribute list. A list of attributes for the monitored resource described in the current record. This structure consists of a list of repeating entries. The DENR0200 format uses the Attribute List Entry Format for the format of a single entry. The DENR0300 format uses the Attribute List Entry 2 Format for the format of a single entry.

Attribute name. The name of the attribute.

Attribute type. The type of the attribute. Possible values are:

0 SIMPLE The attribute is represented by a single value.
1 COMPOUND The attribute is represented by a variable number of compound attribute entries, each having a value.

Attribute status. The status of a single attribute value across the active cluster administrative domain. If all of the compound attribute entries for a compound attribute are consistent, the attribute status will be consistent. Possible values are:

0 CONSISTENT The value for this attribute is the same on all active nodes in the cluster administrative domain.
1 INCONSISTENT The value for this attribute is not the same on all active nodes in the cluster administrative domain.

Attribute value. The value of the attribute or the attribute entry, if it is a value for a compound attribute. If the global status for the resource is CONSISTENT, this is the value of the attribute across the active cluster administrative domain. If the global status is INCONSISTENT or PENDING, this value represents the last attempted change to the attribute value within the active cluster administrative domain.

Bytes available. The number of bytes of data available to be returned to the user. If all data is returned, this is the same as the number of bytes returned. If the receiver variable was not big enough to contain all of the data, this is the number of bytes that can be returned.

Bytes returned. The number of bytes of data returned to the user. This is the lesser of the number of bytes available to be returned or the length of the receiver variable. If the requested monitored resource is not monitored by the system, this value will be set to 20.

Compound attribute list. A list of compound attribute entries for a compound attribute. This structure consists of a list of repeating entries. See Compound Attribute Entry Format for the format of a single entry.

Data Type. The data type of the attribute value. See Monitored Resource Entry Data Types for more information about data types. Valid data types are:

0 Character data
1 Binary data
2 Library qualified object name
3 Special authority data
4 User profile options data
5 Supplemental groups data
6 IFS path name
7 Message log data
9 Environment variable data
10 Communication recovery limit structure
11 Local interface structure
12 Network server information
13 SSAP list
14 Group address list
15 Functional address list
18 Storage path list
19 Event log list
20 Port configuration list
21 Name server list
22 Virtual ethernet path list
23 Restricted device resource list
24 Network server configuration data
25 ASP group list
26 Autostart job entry
27 Workstation name entry
28 Workstation type entry
29 Job queue entry
30 Routing entry
31 Communication entry
32 Remote location name entry
33 Prestart job entry
34 IXSVR NWS storage data
35 ISCSI NWS storage data
36 Remote system ID
37 Bood device ID
38 Dynamic boot options
39 Remote interfaces
40 Enclosure ID
41 Certificate ID
42 Multipath group list
43 Service processor name
44 Serviceability options data
Start of change45 Font identifierEnd of change
Start of change46 Character identifierEnd of change
Start of change47 User defined objectEnd of change
Start of change48 Advanced function printingEnd of change
Start of change49 TransformEnd of change
Start of change50 System driver programEnd of change
Start of change51 User defined optionsEnd of change
Start of change52 Switched line listEnd of change
Start of change53 Publish informationEnd of change
Start of change54 Authorization list entryEnd of change
Start of change55 Initial library listEnd of change
Start of change56 Excluded temporary addressEnd of change

Displacement to attribute list. The displacement in bytes from the start of the current monitored resource entry to the attribute list.

Displacement to attribute name. Displacement from the beginning of the current attribute list entry to the attribute name.

Displacement to attribute value. The displacement from the beginning of the current attribute list entry to the attribute value.

Displacement to first compound attribute entry. The displacement from the beginning of the current compound attribute list to the first entry. If there are no entries in the list, the value will be 0.

Displacement to next compound attribute entry. The displacement from the beginning of the current compound attribute entry to the next entry.

Displacement to next attribute list entry. Displacement from the beginning of the current attribute list entry to the next attribute list entry. The value will be zero if there are no more entries in the list.

Displacement to message information. The displacement in bytes from the start of the current entry to the message information. Start of change The value will be 0 if there is no message information. End of change

Displacement to message replacement data. The displacement in bytes from the beginning of the message information to the message replacement data. If there is no message information data, this field is set to zero.

Displacement to monitored resource name. The displacement in bytes from the start of the current monitored resource entry to the monitored resource name field.

Displacement to next record. The displacement in bytes from the start of the current monitored resource entry to the next entry.

Displacement to node array. The displacement in bytes from the start of the current monitored resource entry to the node array. This will be set to 0 if the global status for the monitored resource is not set to 1 (INCONSISTENT).

Global entry status. The status of a single compound attribute entry across the active cluster administrative domain. Possible values are:

0 CONSISTENT The value for this compound attribute entry is the same on all active nodes in the cluster administrative domain.
1 INCONSISTENT The value for this compound attribute entry is not the same on all active nodes in the cluster administrative domain.

Global resource status. The status of the resource across the active cluster administrative domain. Possible values are:

0 CONSISTENT The monitored resource has the same attribute values on all active nodes in an active cluster administrative domain.
1 INCONSISTENT The resource has incorrect attribute values on one or more active nodes a cluster administrative domain.
2 PENDING The monitored resource is in the process of being synchronized across the cluster administrative domain.
3 ADDED The monitored resource has been added to the cluster administrative domain but has not yet been synchronized because the domain has not been started.
4 ENDED The monitored resource is in an unknown state because the cluster administrative domain has been ended and changes to the resource are no longer being processed.
5 FAILED The resource is no longer being monitored by the cluster administrative domain and the monitored resource entry should be removed.

Length of fixed portion of attribute list entry. The length in bytes of the fixed fields in an attribute list entry.

Length of fixed portion of compound attribute list entry. The length in bytes of the fixed fields in a compound attribute entry list entry.

Length of fixed portion of record. The length of the fixed fields in the format description. If no records are returned, this field will be set to 0.

Length of message information. The length in bytes of the message information.

Length of message replacement data. The length in bytes of the message replacement data.

Length of monitored resource name. The length in bytes of the monitored resource entry name.

Length of node array entry. The length in bytes of the node array entry.

Local entry status. The status of a single compound attribute entry on the local node. Possible values are:

0 CURRENT There are no pending updates for the compound attribute entry on this node.
1 ADDPND The compound attribute entry is in the process of being added on this node.
2 CHGPND The compound attribute entry is in the process of being changed on this node.
3 RMVPND The compound attribute entry is in the process of being removed on this node.
4 ADDFAIL The compound attribute entry was not successfully added on this node.
5 CHGFAIL The compound attribute entry was not successfully changed on this node.
6 RMVFAIL The compound attribute entry was not successfully removed on this node.

Local resource status. The resource status of the monitored resource on the local node. The following values are valid:

0 CURRENT There are no pending updates for the monitored resource on this node.
2 DLTPND The monitored resource has been deleted on this node. The other nodes in the cluster administrative domain have not been notified.
3 UPDPND One or more attributes which are being monitored for a resource have changed on this node. The other nodes in the cluster administrative domain have not been notified.
4 RSTPND The monitored resource has been restored on this node. The other nodes in the cluster administrative domain have not been notified.
5 RNMPND The monitored resource has been renamed on this node. The other nodes in the cluster administrative domain have not been notified.
6 MOVPND The monitored resource has been moved on this node. The other nodes in the cluster administrative domain have not been notified.
8 DLTFAIL The monitored resource on has been deleted on one of the nodes in the cluster administrative domain. The other active nodes in the domain have been notified and the global resource status has been set to FAILED. Future changes to this resource will not be synchronized.
9 UPDFAIL An update to the monitored resource on this node has failed. The other nodes in the cluster administrative domain have been notified and the global resource status has been set to INCONSISTENT.
10 RSTFAIL The monitored resource has been restored on a node in the cluster administrative domain to a state that is not recognized by the domain. The global resource status has been set to FAILED.
11 RNMFAIL The monitored resource has been renamed on one of the nodes in the cluster administrative domain. The other active nodes in the domain have been notified and the global resource status has been set to FAILED. Future changes to this resource will not be synchronized.
12 MOVFAIL The monitored resource has been moved on one of the nodes in the cluster administrative domain. The other active nodes in the domain have been notified and the global resource status has been set to FAILED. Future changes to this resource will not be synchronized.

Message file. The message file.

Message ID. The message identifier.

Message information. The message information associated with the monitored resource or attribute. See Message Information Format for the format of this data.

Message library. The message library.

Message replacement data. The message replacement data.

Message replacement data CCSID. The coded character set identifier (CCSID) of the convertible character (CCHAR) portion of the exception data.

Monitored resource name. The name of the monitored resource entry for which information is returned.

Monitored resource library name. The name of the library of the monitored resource. Blanks will be returned for the monitored resource types *SYSVAL, *NETA, *ENVVAR, *TCPA, and *NWSSTG.

Monitored resource type. The type of monitored resource. Possible values are:

*ASPDEV Independent auxiliary storage pool (ASP) device description
Start of change*AUTL Authorization listEnd of change
*CLS Class
*ETHLIN Ethernet line description
*ENVVAR System environment variable
*JOBD Job description
*NETA Network attribute
*NWSCFG NWS Configuration
*NWSD Network server description
*NWSHDEV NWSH device description
*NWSSTG NWS Storage Space
*OPTDEV Optical device description
Start of change*PRTDEV Printer device descriptionEnd of change
*SBSD Subsystem description
*SYSVAL System value
*TAPDEV Tape device description
*TCPA TCP/IP attribute
*TRNLIN Token-ring line description
*USRPRF User profile

Node array. The array of cluster node names that represents the list of nodes where a problem caused the global status of the monitored resource to be set to INCONSISTENT.

Number of attribute list entries. The number of entries in the attribute list. If the receiver variable is not large enough to hold all of the information, this number contains only the number of attribute list entries actually returned.

Number of compound attribute entries. The number of entries in the compound attribute list.

Number of node array entries. The number of entries in the node array.

Number of records returned. The number of resource entries returned. If the receiver variable is not large enough to hold all of the information, this number contains only the number of record entries actually returned. If no records are returned, this field is set to 0.

Offset to first record. The offset, in bytes, from the beginning of the receiver variable to the first record. If no entries are returned, the offset is set to zero.

Reserved. This field will be set to hexadecimal zeroes.


Monitored Resource Input Information (EENT0100 Format)

Offset Type Field
Dec Hex
0 0 CHAR(10) Monitored resource input type
10 A CHAR(10) Monitored resource input library name
20 14 BINARY(4) Length of monitored resource input name
24 18 CHAR(*) Monitored resource input name


Field Descriptions

Length of monitored resource input name. The length, in bytes, of the monitored resource name.

Monitored resource input library name. The name of the library for the specified monitored resource. Allowed values are:

Blank Specify a blank monitored resource library name for the monitored resource types *SYSVAL, *ENVVAR, *NETA, *TCPA, *NWSSTG, or *ALL.
Monitored resource library name Specify the library name for the monitored resource types which are system objects. The library name must be QSYS for Start of change user profiles, configuration objects, or authorization lists. End of change The library name must be QUSRSYS for *NWSCFG resources. Library special values, e.g. *CURLIB or *LIBL, are not allowed.

Monitored resource input name. The name of the monitored resource or list of resources for which information is returned. The allowed values are:

Monitored resource name The name of a monitored resource.
*ALL Returns information for all monitored resources.

Monitored resource input type. The type of monitored resource for which information is to be returned. Possible values are:

*ALL Return information for all monitored resource types
*ASPDEV Independent auxiliary storage pool (ASP) device description
Start of change*AUTL Authorization listEnd of change
*CLS Class
*ETHLIN Ethernet line description
*ENVVAR System environment variable
*JOBD Job description
*NETA Network attribute
*NWSCFG NWS Configuration
*NWSD Network server description
*NWSHDEV NWSH device description
*NWSSTG NWS Storage Space
*OPTDEV Optical device description
Start of change*PRTDEV Printer device descriptionEnd of change
*SBSD Subsystem description
*SYSVAL System value
*TAPDEV Tape device description
*TCPA TCP/IP attribute
*TRNLIN Token-ring line description
*USRPRF User profile


Server Information (SRVI0100 Format)

Offset Type Field
Dec Hex
0 0 BINARY(4) Length of server defined output
4 4 CHAR(10) Cluster name
14 D CHAR(10) Cluster administrative domain name
24 18 CHAR(30) Reserved


Field Descriptions

Cluster administrative domain name. The name of the cluster administrative domain.

Cluster name. The name of the cluster associated with the cluster administrative domain.

Length of server defined output. The length, in bytes, of the server defined output parameter. For a *ADMDMN manager type, this value must be 1.

Reserved. This field must be set to hexadecimal zeroes.


Usage Notes

Retrieving Monitored Resource Information in a Cluster Administrative Domain

See Cluster administrative domain for more information about using this API to retrieve monitored resource information in a cluster administrative domain.

Use of Teraspace

This API is teraspace enabled. Teraspace can be used for the receiver variable if more than 16 MB of information could be returned.


Error Messages

Message ID Error Message Text
CPF1098 E No authority to class &1 in library &2.
CPF2634 E Not authorized to object &1.
CPF2697 E The request did not complete in the time allotted.
CPF3C19 E Error occurred with receiver variable specified.
CPF3C24 E Length of the receiver variable is not valid.
CPF3C29 E Object name &1 is not valid.
CPF3C1E E Required parameter &1 omitted.
CPF3C21 E Format name &1 is not valid.
CPF3C3C E Value for parameter &1 not valid.
CPF3CF1 E Error code parameter not valid.
CPF3CF2 E Error(s) occurred during running of &1 API.
CPF9801 E Object &2 in library &3 not found.
CPF9802 E Not authorized to object &2 in &3.
CPF9803 E Cannot allocate object &2 in library &3.
CPF9804 E Object &2 in library &3 damaged.
CPF9810 E Library &1 not found.
CPF9820 E Not authorized to use library &1.
CPFA0AA E Error occurred while attempting to obtain space.
CPFAA03 E Monitored resource entry not found.
CPFAA05 E Value specified for Manager Type not valid.
CPFAA06 E Length specified in parameter &1 not valid.
CPFAA07 E Field value within structure is not valid.
CPFAA09 E Length of monitored resource name not valid.
CPFAA0A E Length of server information not valid.
CPFAA0B E Internal error in procedure &2. Reason code is &1.
CPFAA0E E Library name &1 not valid.
CPFB0CE E &1 special authority is required.
CPFBBB6 E Library &1 not allowed for resource &2.
CPFBBBD E Resource type &1 not valid.
CPFBBC4 E Request not valid for cluster node &1.



API introduced: V5R4

[ Back to top | Cluster APIs | APIs by category ]