Adjust Cluster Version (QcstAdjustClusterVersion) API
Required Parameter Group:
1 | Request handle | Output | Char(16) |
2 | Cluster name | Input | Char(10) |
3 | Cluster version information | Input | Char(*) |
4 | Format name | Input | Char(8) |
5 | Results information | Input | Char(30) |
6 | Error code | I/O | Char(*) |
Service Program: QCSTCTL2
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Adjust Cluster Version (QcstAdjustClusterVersion) API is used to adjust the current version of the cluster. The current cluster version is the version at which the nodes in the cluster are actively communicating with each other. In addition, this value determines what nodes can join into the cluster and the cluster's ability to use new functions supported by the nodes potential node version. It is set when the cluster is created. The version is adjusted to be one level greater than the existing value. To view the current cluster version, use the List Cluster Information or the Retrieve Cluster Information API.
This command will not cause the Cluster Resource Group Exit Program to be called.
The following conditions apply to this API:
- This API must be called from a program running on a cluster node with a status of Active. The node must have a version of the operating system that is equal to or greater than node version of 2.
- This API cannot be used if the cluster is in a partitioned state.
- This API can only be used to adjust to a higher version. The only way to change the cluster to a lower version is to delete and recreate the cluster at the lower version.
- The cluster version cannot be set higher than the lowest potential node version in the cluster. To view the potential node versions, use the List Cluster Information or the Retrieve Cluster Information API.
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 being adjusted.
- Cluster version information
- INPUT; CHAR(*)
Additional details for adjusting the cluster version. When the format name is *NONE, the cluster version information field must be CHAR(10) and filled with blanks or omitted. When the default is taken by filling in blanks or omitting this field, Cluster Resource Services adjusts the version up by 1.
- Format name
- INPUT; CHAR(8)
The format of the cluster version information. This field must be set to *NONE and must be left-justified.
- 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.
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).
Message ID | Message Text |
---|---|
CPCBB01 C | Cluster Resource Services API &1 completed. |
CPF3C4B D | Value not valid for field &1. |
CPF3CF2 D | Error(s) occurred during running of &1 API. |
CPFBB17 D | &1 API cannot be processed in cluster &2. |
CPFBB24 D | Node &1 not participating in &2 protocol. |
CPFBB2D D | Timeout detected while waiting for a response. |
CPFBB2F D | Cluster version &1 cannot be adjusted. |
CPFBB46 D | Cluster Resource Services internal error. |
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.
Message ID | Error Message Text |
---|---|
CPF2113 E | Cannot allocate library &1. |
CPF3C1E E | Required parameter &1 omitted. |
CPF3C21 E | Format name &1 is not valid. |
CPF3C39 E | Value for reserved field not valid. |
CPF3C4B E | Value not valid for field &1. |
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. |
CPF9804 E | Object &2 in library &3 damaged. |
CPF980C E | Object &1 in library &2 cannot be in an independent auxiliary storage pool. |
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. |
CPFBB02 E | Cluster &1 does not exist. |
CPFBB17 E | &1 API cannot be processed in cluster &2. |
CPFBB26 E | Cluster Resource Services not active or not responding. |
CPFBB2F E | Cluster version &1 cannot be adjusted. |
CPFBB32 E | Attributes of user queue &1 in library &2 are not valid. |
CPFBB39 E | Current user does not have IOSYSCFG special authority. |
CPFBB44 E | &1 API cannot be called from a cluster resource group exit program. |
CPFBB46 E | Cluster Resource Services internal error. |
API introduced: V5R1
[ Back to top | Cluster APIs | APIs by category ]