Add Device Domain Entry (QcstAddDeviceDomainEntry) API


  Required Parameter Group:


  Service Program: QCSTDD

  Default Public Authority: *EXCLUDE

  Threadsafe: Yes

The Add Device Domain Entry (QcstAddDeviceDomainEntry) API is used to add a cluster node to the membership list of a device domain. There is no API to create a device domain, the device domain will be created when the first cluster node is added to it.

The following conditions apply to this API:

This API requires that IBM® i option 41, HA Switchable Resources, is installed and a valid license key exists on all cluster nodes that will be in the device domain.

For more information, see these information center topics:

This API operates in an asynchronous mode. See Behavior of Cluster Resource Services APIs for more information.

Restriction: This API cannot be called from a cluster resource group exit program.


Authorities and Locks

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

User Queue Authority
*OBJOPR and *ADD
User Queue Library Authority
*EXECUTE
User Queue Lock
*EXCLRD

Required Parameter Group

Request handle
OUTPUT; CHAR(16)

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.

Cluster name
INPUT; CHAR(10)

The name of the cluster that contains the node.

Device domain name
INPUT; CHAR(10)

The name of the device domain to which the node is being added. It must be a valid simple name. If the device domain does not currently exist, it will be created.

Device domain entry information
INPUT; CHAR(*)

Detailed information about device domain entry to be added to the device domain.

Format name
INPUT; CHAR(8)

The content and format of the device domain entry information. The possible format names are:


Results information
INPUT; CHAR(30)

A library qualified user queue name followed by a reserved field.

Library qualified user queue: A user queue, which exists on the node from which the API was called, that receives results information after the function has completed on all active nodes in the cluster. 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, and *CURLIB are not valid for the library name. The attributes of this user queue must be keyed.

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

Error code
I/O; CHAR(*)

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


Device Domain Entry Information

ADDD0100 Format



Field Descriptions

Length of data provided. This is the total length of data provided (including this field) for the device domain entry information.

Node id. A unique string of characters that identifies a cluster node to be added to the device domain.


Usage Notes

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).


Error Messages

Messages that are delivered through the error code parameter are listed here. The data (messages) sent to the results information user queue are listed in the Usage Notes above.



API introduced: V5R1

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