Control ASP Access (QYASPCTLAA) API

The Control ASP Access (QYASPCTLAA) API performs one of a set of operations on an independent ASP (IASP). The operation can be any of the following:

• Start exclusive.
• Start shared.
• End shared.
• End exclusive.

Authorities and Locks

To use this API you must have *JOBCTL special authority. *USE authority is required to each of the ASP device descriptions in the ASP group identified by parameter one. An *EXCLRD lock is obtained on each of the ASP device descriptions in the ASP group.

Required Parameter Group

ASP name

INPUT; CHAR(10)

The name of a UDFS or primary ASP. If a primary ASP is specified, the operation is performed on all ASPs in its ASP group.

Operation key

INPUT; BINARY(4)

An integer value indicating which operation is to be performed. Valid operation key values are:

The following is a description of each operation:

Start exclusive

If there is an existing start exclusive for the ASP, the request is denied. Otherwise the API ends jobs that have threads using the ASP and returns a return handle that identifies this start exclusive request. Once the start exclusive is in effect, other jobs can do start shared and present the same handle. These requests will be accepted but requests with a different handle but the same ASP will be rejected.

The request handle must be blanks for this operation.

Start

If the request handle does not have the same value as the return handle of the current start exclusive, the request is denied. Only jobs that have done start exclusive or start shared will be able to do Set ASP Group (SETASPGRP) command requests and use IFS objects in the ASP.

End shared

Ends the job's shared use of the ASP.

End exclusive

Varies the IASP to the AVAILABLE state and allows SETASPGRP requests and requests to use IFS objects to be accepted without presentation of a current valid handle. This operation must be performed in the same job as the one that did the start exclusive.

Request handle

INPUT; CHAR(8)

A valid handle whose value is that of the return handle from the current start exclusive for the ASP.

Return handle

OUTPUT; CHAR(8)

A handle that must be used as the request handle on all QYASPCTLAA operations except start exclusive.

Error code

I/O; CHAR(*)

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

Use of Start and End Exclusive

The following are ways in which Start Exclusive can be paired with End Exclusive.

• Start exclusive is eventually followed by end exclusive in the same job.
• Start exclusive is done in a job but the job ends without doing an end exclusive. If another job has access to the handle, it may do a start shared followed by end exclusive. If no job has access to the handle, the only way to end the exclusive use is to vary the ASP off and back on again or to IPL.
• Start exclusive is done in a job and start shared is done in several others. The job that did the start exclusive can do either an end exclusive or an end shared. Any job that has done a start shared can do end exclusive, provided that this has not yet been done by any other job. Once end exclusive has been processed, the ASP goes back to an available state and jobs that did not do a start shared can begin using the ASP.

Sample Uses

The value of this API is that it can be used to achieve a "restricted" state for an IASP without ending all subsystems. This allows functions such as TCP and clustering to remain active during operations where one might otherwise have gone into restricted state. It also allows applications that are not using the ASP to continue to function.

Some possible uses of this API are:

• Precede an IASP Reclaim Storage with a start exclusive and follow it with an end exclusive. This effectively establishes a "restricted" state for the ASP.
• Do a start exclusive in a control job. Follow it with a start shared in a different job that is going to do save-while-active. Once the save has reached its synchronization point, do end exclusive in the control job. This will bring the ASP back to an AVAILABLE state and other jobs will be able to use the ASP. The save-while-active job can do its end shared anytime, as long as it is after the save-while-active synchronization point has been reached.
• In order to have a more complete copy of changes when doing ESS flashcopy or detach of a geographic mirroring mirror copy, precede the detach or flashcopy operation with start exclusive. Then use the QYASSDMO API to write changes to disk. This should reduce the time the ASP cannot be used when compared with doing vary off prior to detach or flashcopy.

Error Messages