Add Monitored Resource Entry (QfpadAddMonitoredResourceEntry) API

Required Parameter Group:

1	Manager type	Input	Char(10)
2	Monitored resource information	Input	Char(*)
3	Length of monitored resource information	Input	Binary(4)
4	Monitored resource information format name	Input	Char(8)
5	Attribute information	Input	Char(*)
6	Length of attribute information	Input	Binary(4)
7	Attribute information format name	Input	Char(8)
8	Server information	Input	Char(*)
9	Length of server information	Input	Binary(4)
10	Server information format name	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 Add Monitored Resource Entry (QfpadAddMonitoredResourceEntry) API adds a monitored resource entry for a system resource and its attributes. A 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.

When adding a monitored resource entry (MRE) for a system object, the monitored resource name is the name of the system object. It is possible to specify one or more of the system object's attributes for monitoring. Otherwise, a special value of -1 may be specified as the number of attribute entries, which will cause all of the system object's allowed attributes to be monitored by the system.

When adding a monitored resource entry (MRE) for a resource that is not a system object, such as a system value, network attribute, TCP/IP attribute or system environment variable, the monitored resource name is the name of the specific system value, network attribute, TCP/IP attribute, or system environment variable which is to be monitored by the system.

This API will do the following when adding a monitored resource entry to a cluster administrative domain:

Create a monitored resource entry on all nodes in the cluster administrative domain.
The resource being monitored by the cluster administrative domain will be created on all nodes in the cluster administrative domain where it does not already exist. The attributes of the created resource will be set to the values of the attributes from the resource on the node from which the API was called.
If the cluster administrative domain has been started, the values of the attributes for the monitored resource will be synchronized to the same attribute values from the resource on the node where the API was called.
If the cluster administrative domain has not been started, the attribute values for the resource being monitored by the cluster administrative domain will not be synchronized until the cluster administrative domain is started.
Once the API has completed, if the cluster administrative domain is not active, the global status will be ADDED. If the cluster administrative domain is active, the global status will be either PENDING, CONSISTENT or INCONSISTENT.

Restrictions:

The cluster administrative domain must exist and all nodes in the domain must be active.
Resources cannot be added to a cluster administrative domain when it is partitioned.
The monitored resource must exist on the system from which this API is called.
The program that calls this API must be running under a user profile that exists on all nodes in the cluster administrative domain.
The system value QRETSVRSEC must be set to 1 to monitor any secure attribute such as the PASSWORD attribute for user profile resources.
This API can only be called from a cluster node in the domain node list of the cluster administrative domain.
A monitored resource entry for a *SBSD, *NWSD, *NWSCFG, *NWSSTG, *NWSHDEV, *ETHLIN, *TRNLIN, *OPTDEV or *TAPDEV resource type can only be added for a cluster at cluster version 6 or greater.
All monitored resources must exist in the system base auxiliary storage pool (ASP) except network server storage spaces (*NWSSTG) which must exist in an independent ASP.
The IBM-supplied classes QARBCLS, QMONCLS, and QLPINSTALL cannot be monitored.
This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.
A monitored resource entry for a *AUTL or *PRTDEV resource type can only be added when the IBM® PowerHA™ for i licensed program product is installed. The cluster version must be 7 or greater and the PowerHA version must be 2.0 or greater.
A monitored resource entry for a *NWSD with a server operating system value of *ESX or *ESXE can only be added at cluster version 7 or greater.
An *ETHLIN resource with a resource name of *AGG is not allowed to be added to a cluster administrative domain as a monitored resource.
The IP6TMPAXP *TCPA resource can only be added to a cluster administrative domain at cluster version 7 or greater.
The maximum number of monitored resources that can be added to a cluster administrative domain is 25,000.

Authorities and Locks

The following authorities are explicitly checked for by this API. Additional authority checking may be performed by APIs or CL commands invoked as a result of this API.

The program that calls this API must be running under a user profile with system configuration (*IOSYSCFG) special authority.

*AUDIT authority is required to add a monitored resource entry for for the QAUDCTL, QAUDENDACN, QAUDFRCLVL, QAUDLVL, QAUDLVL2 and QCRTOBJAUD system values.

*JOBCTL authority is required to add a monitored resource entry for the QPASTHRSVR and QLOGOUTPUT system values.

*SECADM and *ALLOBJ authority is required to add a monitored resource entry (MRE) for the QACGLVL, QDEVNAMING, QDSPSGNINF, QKBDBUF, QLMTSECOFR, QMAXJOB, QMAXSGNACN, QMAXSIGN, QPWDEXPITV, QPWDLMTAJC, QPWDLMTCHR, QPWDLMTREP, QPWDLVL, QPWDMAXLEN, QPWDMINLEN, QPWDPOSDIF, QPWDRQDDGT, QPWDRQDDIF, QRETSVRSEC, QSECURITY, QSPLFACN, QALWOBJRST, QALWUSRDMN, QATNPGM, QAUTORMT, QAUTOVRT, QCRTAUT, QFRCCVNRST, QINACTITV, QINACTMSGQ, QIPLTYPE, QLIBLCKLVL, QLMTDEVSSN, QMLTTHDACN, QPRTDEV, QPWDVLDPGM, QRMTSIGN, QRMTSRVATR, QSCANFS, QSANFSCTL, QSHRMEMCTL, QSPCENV, QSYSLIBL, QUSEADPAUT, QVFYOBJRST, QALWJOBITP, QPWDRULES, QPWDCHGBLK, QPWDEXPWRN, QSSLCSL, QSSLPCL and QSSLCSLCTL system values.

*ALLOBJ authority is required to add a monitored resource entry (MRE) for the DDMACC or PSCACC network attribute.

User Profile Authority (applies to the user profile for which the MRE is added): *USE, *OBJMGT, and *SECADM
Configuration Object Authority (applies to a configuration object for which the MRE is added): *CHANGE, *ADD, *READ and *OBJMGT
Library Authority: *EXECUTE
System Environment Variable Authority (applies to a system environment variable for which the MRE is added): *JOBCTL
System Value Authority (applies to the system value for which the MRE is added): *SECADM and *ALLOBJ required for the following system values:
QACGLVL, QDEVNAMING, QDSPSGNINF, QKBDBUF, QLMTSECOFR, QMAXJOB, QMAXSGNACN, QMAXSIGN, QPWDEXPITV, QPWDLMTAJC, QPWDLMTCHR, QPWDLMTREP, QPWDLVL, QPWDMAXLEN, QPWDMINLEN, QPWDPOSDIF, QPWDRQDDGT, QPWDRQDDIF, QRETSVRSEC, QSECURITY, QSPLFACN, QALWOBJRST, QALWUSRDMN, QATNPGM, QAUTORMT, QAUTOVRT, QCRTAUT, QFRCCVNRST, QINACTITV, QINACTMSGQ, QIPLTYPE, QLIBLCKLVL, QLMTDEVSSN, QMLTTHDACN, QPRTDEV, QPWDVLDPGM, QRMTSIGN, QRMTSRVATR, QSCANFS, QSANFSCTL, QSHRMEMCTL, QSPCENV, QSYSLIBL, QUSEADPAUT, QVFYOBJRST, QALWJOBITP, QPWDRULES, QPWDCHGBLK, QPWDEXPWRN, QSSLCSL, QSSLPCL and QSSLCSLCTL; *AUDIT required for the following system values:
QAUDCTL, QAUDENDACN, QAUDFRCLVL, QAUDLVL, QAUDLVL2 and QCRTOBJAUD; *JOBCTL required for the following system values:
QPASTHRSVR and QLOGOUTPUT
Job Description Authority (applies to a job description for which the MRE is added): *OBJMGT and *OBJOPR
Class Authority (applies to a class object for which the MRE is added): *OBJMGT and *OBJOPR
Network Attribute Authority (applies to a network attribute for which the MRE is added): *ALLOBJ required for the following network attributes:
DDMACC and PSCACC
Subsystem Description Authority (applies to a subsystem description for which the MRE is added): *READ, *OBJMGT and *OBJOPR
Network Server Configuration Authority (applies to a network server configuration for which the MRE is added): *SECADM
Network Server Storage Space Authority (applies to a network server storage space for which the MRE is added): *WX
Authorization List Authority (applies to an authorization list for which the MRE is added): *ALLOBJ or ownership
Request Information User Queue Authority: *OBJOPR, *ADD
Request Information User Queue Library Authority: *EXECUTE
Request Information User Queue Lock: *EXCLRD

Required Parameter Group

Manager type

INPUT; CHAR(10)

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

Monitored resource information

INPUT; CHAR(*)

The resource information for the MRE that is to be added.

Length of monitored resource information

INPUT; BINARY(4)

The length, in bytes, of the monitored resource information. The length must be at least as large as the length of the fixed portion of the monitored resource information format plus the length of the resource name.

Monitored resource information format name

INPUT; CHAR(8)

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

EENT0100 The format for a monitored resource entry.

Attribute information

INPUT; CHAR(*)

The list of attribute names that are to be monitored.

Length of attribute information

INPUT; BINARY(4)

The length, in bytes, of the attribute information. The specified length must be at least the length of the fixed portion of the attribute information format plus the combined length of all of the specified attribute name entries.

Attribute information format name

INPUT; CHAR(8)

The format name for the attribute information. The following format name is allowed:

ATRI0100 The format of the attribute information for an entry.

Server information

INPUT; CHAR(*)

The information about the server which will monitor the resource. 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.

Server information format name.

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 administrative domain.

Server defined output

OUTPUT; CHAR(*)

When the manager type is *ADMDMN, the server defined output contains the 16 character request handle. The request handle is a unique string or handle that identifies this API call. It is used to associate this call to any responses placed on the user queue specified in the results information parameter. The API will generate the request handle and return the handle to the caller of the API.

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 (EENT0100 Format)

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

Field Descriptions

Length of monitored resource name. The length in, bytes, of the monitored resource name. The length of the monitored resource name must be at least 1 byte long. The maximum length allowed is 256 bytes.

Monitored resource library name. The name of the monitored resource library. The allowed values are:

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

Monitored resource name. The name of the monitored resource which is being monitored by the system.

Monitored resource type. The type of monitored resource entry which is being monitored by the system. The allowed values are:

*ASPDEV	Independent auxiliary storage pool (ASP) device description.
*AUTL	Authorization list.
*CLS	Class.
*ENVVAR	System environment variable.
*ETHLIN	Ethernet line description.
*JOBD	Job description.
*NETA	Network attribute.
*NWSCFG	Network server configuration.
*NWSD	Network server description.
*NWSH	NWSH device description.
*NWSSTG	Network server storage.
*OPTDEV	Optical device description.
*PRTDEV	Printer device description.
*SBSD	Subsystem description.
*SYSVAL	System value.
*TAPDEV	Tape device description.
*TCPA	TCP/IP attribute.
*TRNLIN	Token ring line description.
*USRPRF	User profile.

Attribute Information (ATRI0100 Format)

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Number of attribute entries
4	4	BINARY(4)	Offset to attribute array
Note: The following fields repeat for each attribute monitored by the system.
		BINARY(4)	Displacement to next attribute entry
		BINARY(4)	Length of attribute name
		CHAR(*)	Attribute name

Field Descriptions

Attribute name. The name of the attribute to be monitored by the system. For monitored resource types of *ENVVAR, *SYSVAL, *NETA and *TCPA, the attribute name is the same as the resource name.

Displacement to next attribute entry. The displacement in bytes from the beginning of the current entry to the beginning of the next attribute entry. This field must be set to 0 for the last entry. For all entries except the last entry, the displacement must be at least as big as the fixed portion of the current entry plus the length of the current attribute name.

Length of attribute name. The length, in bytes, of the attribute name.

Number of attribute entries. The number of attribute entries in the ATRI0100 format. The allowed values are:

-1	Specify -1 to monitor all allowed attributes for a system object monitored resource.
>0	Specify a value greater than 0 to monitor one or more attributes for a system object monitored resource. The number specified cannot be greater than the total number of attributes supported for the monitored resource.

Offset to attribute array. The offset in bytes from the beginning of this structure to the first attribute entry. A value of 0 must be specified when the number of attribute entries value is equal to -1. If the number of attribute entries is greater than 0, this field must be set to a value greater than 0.

Server Information (SRVI0100 Format)

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Length of server defined output
4	4	CHAR(10)	Cluster name
14	E	CHAR(10)	Cluster administrative domain name
28	1C	CHAR(30)	Results information

Field Descriptions

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

Cluster name. The name of the cluster.

Length of server defined output. The length, in bytes, of the server defined output parameter for this API. If the manager type is *ADMDMN, this value must be 16.

Results information. This field identifies a qualified user queue field and is followed by a reserved field.

Qualified user queue

Completion information is returned to this user queue, which exists on the node from which the API was called, after the function has completed. See the Usage Notes section of this API for a description of the data that is placed on this queue. This is a 20-character field. The first 10 characters contain the user queue name, and the second 10 characters contain the user queue library name. No special values are supported. QTEMP, *LIBL, *CURLIB are not valid library names. The attributes of this user queue must be keyed.

Reserved

The last 10 characters of the results information are reserved and must be set to hexadecimal zero.

Usage Notes

Adding a Monitored Resource Entry (MRE) in a Cluster Administrative Domain

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

Results Information User Queue

Asynchronous results are returned to a user queue specified by the Results Information parameter of the API. See Cluster APIs Use of User Queues and Using Results Information for details on how to create the results information user queue, the format of the entries, and how to use the data placed on the queue. The data is sent to the user queue in the form of a message identifier and the substitution data for the message (if any exists). The following identifies the data sent to the user queue (excluding the message text).

Message ID	Message Text
CPCBB01 C	Cluster Resource Services API &1 completed.
CPF1999 D	Errors occurred on command.
CPF2204 D	User profile &1 not found.
CPF3C21 E	Format name &1 is not valid.
CPF3CF2 D	Error(s) occurred during running of &1 API.
CPFAA04 E	Resource &1 of type &3 is not valid. Reason code is &5.
CPFBB17 D	&1 API cannot be processed in cluster &2.
CPFBB2D D	Timeout detected while waiting for a response.
CPFBB35 D	The user profile name &1 is not valid for this request.
CPFBB39 E	Current user does not have IOSYSCFG special authority.
CPFBB47 D	Cluster Resource Services detected an error and may have ended abnormally.
CPFBB48 D	Cluster Resource Services error detected.
CPFBBA1 D	All cluster command user queues busy.
CPFBBB9 D	Cluster administrative domain &1 internal error.

Error Messages

Messages that are delivered through the error code parameter are listed here.

Message ID	Error Message Text
CPDAC07 E	System value QRETSVRSEC not set correctly.
CPF1097 E	No authority to change certain network attributes.
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.
CPF3C1E E	Required parameter &1 omitted.
CPF3C21 E	Format name &1 is not valid.
CPF3C24 E	Length of the receiver variable is not valid.
CPF3C29 E	Object name &1 is not valid.
CPF3C39 E	Value for reserved field 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.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFA0AA E	Error occurred while attempting to obtain space.
CPFA98E E	*JOBCTL special authority required to update system-level environment variables.
CPFAA01 E	Attribute &1 for resource &2 not allowed to be monitored.
CPFAA02 E	Resource &1 cannot be added for &2.
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.
CPFAA08 E	Attribute &1 specified more than once.
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.
CPFAA0C E	Resource &2 not found or not supported.
CPFAA0D E	Number of attribute names not valid.
CPFAA0E E	Library name &1 not valid.
CPFAA0F E	Request &1 not supported with specified cluster version and modification level.
CPFAD10 E	An error was detected in the exit program &1 in library &2.
CPFB0CE E	&1 special authority is required.
CPFBB02 E	Cluster &1 does not exist.
CPFBB09 E	Cluster node &1 does not exist in cluster &2.
CPFBB0A E	Cluster node &1 in cluster &2 is not active.
CPFBB0F E	Cluster resource group &1 does not exist in cluster &2.
CPFBB20 E	Cluster partition detected for cluster &1 by cluster node &2.
CPFBB26 E	Cluster Resource Services is not active or not responding.
CPFBB32 E	Attributes of user queue &1 in library &1 are not valid.
CPFBB39 E	Current user does not have IOSYSCFG special authority.
CPFBB46 E	Cluster Resource Services internal error.
CPFBB70 E	API request &1 not compatible with current cluster version.
CPFBBB5 E	Resource &1 cannot be added for &2.
CPFBBB6 E	Library &1 not allowed for resource &2.
CPFBBBD E	Resource type &1 not valid.

API introduced: V5R4

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