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:
1
Start exclusive
2
Start shared
3
End shared
4
End exclusive
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.
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
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.
CPFB8E5 E
Vary Configuration or Reclaim Storage detected a problem.