Change ASP Activity (QYASPCHGAA) API
Required Parameter Group:
1 | ASP name | Input | Char(10) |
2 | Action key | Input | Binary(4) |
3 | Action time-out | Input | Binary(4) |
4 | Re-instruct time-out | Input | Binary(4) |
5 | Action time to complete | Output | Binary(4) |
6 | Error Code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: Yes
The Change ASP Activity (QYASPCHGAA) API provides a set of actions that are used to quiesce the use of objects in the system ASP and the basic user ASPs (*SYSBAS), an ASP group or a UDFS ASP. The object uses that are quiesced are the start of new commitment control transactions, new database change operations and new Integrated File System (IFS) change operations. In addition, the API can be used to write the changes from main storage to auxiliary storage.
The set of actions provided by the API follow.
- Start session.
- End session.
- Suspend initiation of new transactions.
- Resume initiation of new transactions.
- Suspend initiation of new operations.
- Resume initiation of new operations.
- Write changed data to auxiliary storage.
Authorities and Locks
*JOBCTL special authority is required. In addition, *USE authority is required to the ASP device descriptions identified by parameter one.
An *EXCLRD lock is obtained on each of the ASP device descriptions identified by parameter one.
Required Parameter Group
- ASP name
- INPUT; CHAR(10)
The name of a UDFS or primary ASP. If a primary ASP is specified, the action is performed on all ASPs in its ASP group. If the action is to be performed on the system ASP and the basic user ASPs, the name "*SYSBAS" must be specified.
- Action key
- INPUT; BINARY(4)
An integer value indicating which action is to be performed. Valid action key values are:
1 | Start session |
2 | End session |
3 | Suspend initiation of new transactions |
4 | Resume initiation of new transactions |
5 | Suspend initiation of new operations |
6 | Resume initiation of new operations |
7 | Write changes to auxiliary storage |
The following is a description of each action:
- Start session
- Starts a quiesce ASP session. If an independent ASP is specified, its state must be ACTIVE or AVAILABLE. Once a start session action completes, *SYSBAS, the ASP group or UDFS ASP is quiescing. That is, it is in a period where the rate at which objects in the ASP change continues to diminish.
- End session
- Ends a quiesce ASP session. Once an end session action successfully completes, *SYSBAS, the ASP group or UDFS ASP is no longer quiescing. That is, changes to objects in the ASP no longer are held off.
- Suspend initiation of new transactions
- Used to reach a state where there are no incomplete commitment control transactions using an object in *SYSBAS, the ASP group or the UDFS ASP. The action time-out field specifies the maximum time to wait for transactions to complete before returning.
- Resume initiation of new transactions
- Used to allow new commitment control transactions to start.
- Suspend initiation of new operations
- Used to reach a state where there are no incomplete database or byte stream file operations using an object in *SYSBAS, the ASP group or UDFS ASP. The action time-out field specifies the maximum time to wait for operations to complete before returning.
- Resume initiation of new operations
- Used to allow new database and IFS operations to start.
- Write changes to auxiliary storage
- Used to to get changes to auxiliary storage. The action time-out field specifies the maximum time to wait for changes to be written to auxiliary storage before returning.
- Action time-out
- INPUT; Binary(4)
The number of seconds the API has to complete the requested action before it must return. This field is ignored for start session, end session, resume initiation of new transactions and resume initiation of new operations.
- Re-instruct time-out
- INPUT; Binary(4)
Re-instruct time-out has meaning if either transactions or operations are in a suspended state. It specifies the number of seconds within which the Change ASP Activity API is to be called again for the same ASPs. The re-instruct time interval begins when the current invocation of the API completes. If it is not called again within the time-out interval, both suspended operations and suspended transactions are automatically resumed.
- Time to complete action
- OUTPUT; Binary(4)
The number of seconds the API actually took to complete the specified action. If the action failed to complete within the number of seconds specified in the action time-out parameter, this parameter is set to minus 1.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Sample Uses
The following is an example of what is expected to be the most common use of the the Change ASP Activity actions.
- Start session. This action is always necessary to start a new session.
- Write changes to auxiliary storage. The value of performing this action at this point is that it gets as many changes as possible out of main storage and on auxiliary storage before any new transactions or operations are held off.
- Suspend initiation of new transactions. Since transactions are a wrapper for operations, transactions should be suspended before suspending operations.
- Suspend initiation of new operations.
- Write changes to auxiliary storage. This action writes to auxiliary storage those changes that were made while the API was in the process of suspending transactions and operations.
- Reach a quiesce point. The previous actions brought the session to a quiesce point. That is, at this point no new transactions are being started, no new operations are being started and an attempt has been made to write the IASP's changed pages to disk.
- Perform user's function. The user performs the function for which he performed the quiesce.
- End session. Operations and transactions are resumed. The session ends.
Error Messages
Message ID | Error Message Text |
---|---|
CPF1002 E | Cannot allocate object &1. |
CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
CPF3C3C E | Value for parameter &1 not valid. |
CPF3C90 E | Literal value cannot be changed. |
CPF3CF1 E | Error code parameter not valid. |
CPF9802 E | Not authorized to object &2 in library &3. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
CPFBA44 E | Operation or action key not valid. |
API introduced: V6R1