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