Add Monitored Resource Entry (QfpadAddMonitoredResourceEntry) API

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 the manager type is *ADMDMN:

• 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 created attributes will be set to the values of the attributes from the monitored 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 monitored 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 administative domain is active, the global status will be either PENDING, CONSISTENT or INCONSISTENT.

This API requires the following when the manager type is *ADMDMN:

• When adding a monitored resource entry (MRE) to a cluster administrative domain, 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.
• To add a monitored resource entry (MRE), 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.
• This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.

Authorities and Locks

General Authority

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

The caller of the API will need authority to retrieve the value of the monitored resource entry's attributes on the source system and authority to create or change the monitored resource entry.

• Security Administrator (*SECADM) special authority is required to add a monitored resource entry (MRE) for user profile.
• Job Control (*JOBCTL) special authority is required to add a monitored resource entry (MRE) for system environment variable.
• *USE authority to the CHGSYSVAL command, plus the authority required to change the system value specified, are required to add a monitored resource entry (MRE) for system value.

User queue

The following authorities and locks are required for the user queue specified in the results information parameter.

User Queue Authority

     *OBJOPR and *ADD

User Queue Library Authority

     *EXECUTE

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 monitored resource information provided as input.

Length of monitored resource information

INPUT; BINARY(4)

The length of the monitored resource information.

Format of monitored resource 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 information.

Attribute information

INPUT; CHAR(*)

The attribute information for the resource being monitored.

Length of attribute information

INPUT; BINARY(4)

The length of attribute information.

Format of attribute information

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 where the monitored resource entry will be monitored by the system. When the manager type is *ADMDMN the server is the cluster resource group associated with 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(*)

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)

Field Descriptions

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

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

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:

Attribute Information (ATRI0100 Format)

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 this entry to the beginning of the next attribute entry.

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. Tbe allowed values are:

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.

Server Information (SRVI0100 Format)

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 basics for more information about using this API to add monitored resource entries in a cluster administrative domain.

Unless otherwise noted, all character strings are assumed to be in the CCSID of the program that calls the API.

Monitored resources must exist in the system base auxiliary storage pool (ASP).

Error Messages

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