public class Enqueue
extends java.lang.Object
SA22-7605 z/OS MVS Programming: Assembler Services Guideand:
SA22-7607 z/OS MVS Programming: Assembler Services Reference, Volume 2 (IARR2V-XCTLX)Example: Obtain and release an Enqueue
Enqueue enq = new Enqueue("JZOSTEST", "TEST01");
enq.setContentionActFail(); // don't wait if contention
try {
enq.obtain();
} catch (RcException rce) {
if (rce.getRc() != Enqueue.ISGENQ_RSN_NOTIMMEDIATELYAVAILABLE) {
System.err.println("Resource not available");
}
throw rce;
}
...
enq.release();
Constructor and Description |
---|
Enqueue(java.lang.String qname,
java.lang.String rname)
Construct an instance.
|
Modifier and Type | Method and Description |
---|---|
void |
change()
Change a previously obtained enqueue described by this object's 'enqToken' property
from CONTROL=SHARED to CONTROL=EXCLUSIVE.
|
byte[] |
getEnqToken()
|
java.lang.String |
getQName()
Answers the QNAME
|
java.lang.String |
getRName()
Answers the RNAME
|
void |
obtain()
Obtain (ENQ on) the resource described by this object by invoking
the ISGENQ macro.
|
void |
release()
Release (DEQ) the resource described by this object's 'enqToken' property,
which was previous enqueued using a successful
obtain() call. |
void |
setContentionActFail()
Specifies that the ISGENQ call should fail with a RcException if there is a contention for the
resource.
|
void |
setContentionActWait()
Specifies that the ISGENQ call should wait if there is a contention for the
resource.
|
void |
setControl(int controlValue)
Configures the ENQ for shared or exclusive control
(See ISGENQ_CONTROL_* constants).
|
void |
setScope(int scopeValue)
Configures the ENQ scope
(See ISGENQ_SCOPE_* constants).
|
void |
setWaitTypeECB()
Specifies that the ISGENQ call should wait on an internal ECB if there is a contention for the
resource.
|
void |
setWaitTypeSuspend()
Specifies that the ISGENQ call should suspend the current thread if there is a contention for the
resource.
|
void |
test()
Obtain (ENQ on) the resource described by this object by invoking
the ISGENQ macro, using the TEST=YES option.
|
public static final int ISGENQ_QNAME_MAX_LEN
public static final int ISGENQ_RNAME_MAX_LEN
public static final int ISGENQ_SCOPE_STEP
public static final int ISGENQ_SCOPE_SYSTEM
public static final int ISGENQ_SCOPE_SYSTEMS
public static final int ISGENQ_SCOPE_SYSSPLEX
public static final int ISGENQ_CONTROL_SHARED
public static final int ISGENQ_CONTROL_EXCLUSIVE
public static final int ISGENQ_RSN_NONZERORETURNCODES
public static final int ISGENQ_RSN_REQUESTNOTPROCESSED
public static final int ISGENQ_RSN_ECBWILLBEPOSTED
public static final int ISGENQ_RSN_NOTIMMEDIATELYAVAILABLE
public static final int ISGENQ_RSN_TASKOWNSEXCLUSIVE
public static final int ISGENQ_RSN_TASKOWNSSHARED
public static final int ISGENQ_RSN_TASKWAITING
public static final int ISGENQ_RSN_OTHERSHAREDOWNERS
public static final int ISGENQ_RSN_TASKDOESNOTOWN
public static final int ISGENQ_RSN_TASKSUSPENDEDFORRESOURCE
public static final int ISGENQ_RSN_UNPROTECTEDQNAME
public static final int ISGENQ_RSN_UNPROTECTEDEXITQNAME
public static final int ISGENQ_RSN_ECBATLEASTONEREQUESTFAILED
public static final int ISGENQ_RSN_BADPLISTADDRESS
public static final int ISGENQ_RSN_BADPLISTALET
public static final int ISGENQ_RSN_BADPLISTVERSION
public static final int ISGENQ_RSN_RESERVEDFIELDNOTNULL
public static final int ISGENQ_RSN_MUTUALLYEXCLUSIVE
public static final int ISGENQ_RSN_BADREQUEST
public static final int ISGENQ_RSN_BADCONTENTIONACT
public static final int ISGENQ_RSN_BADOWNINGTTOKEN
public static final int ISGENQ_RSN_BADANSAREAADDRESS
public static final int ISGENQ_RSN_BADANSAREAALET
public static final int ISGENQ_RSN_ANSLENTOOSMALL
public static final int ISGENQ_RSN_BADRNAMEADDRESS
public static final int ISGENQ_RSN_BADRNAMEALET
public static final int ISGENQ_RSN_BADRNAMELEN
public static final int ISGENQ_RSN_BADSCOPE
public static final int ISGENQ_RSN_BADUCB
public static final int ISGENQ_RSN_BADCOND
public static final int ISGENQ_RSN_BADSYNCHRES
public static final int ISGENQ_RSN_BADENQTOKENADDRESS
public static final int ISGENQ_RSN_BADENQTOKENALET
public static final int ISGENQ_RSN_BADENQTOKEN
public static final int ISGENQ_RSN_BADNUMRES
public static final int ISGENQ_RSN_BADRESTABLEADDRESS
public static final int ISGENQ_RSN_BADRESTABLEALET
public static final int ISGENQ_RSN_BADRESTABLE
public static final int ISGENQ_RSN_BADENQTOKENTBLADDRESS
public static final int ISGENQ_RSN_BADENQTOKENTBLALET
public static final int ISGENQ_RSN_BADRETURNTABLEADDRESS
public static final int ISGENQ_RSN_BADRETURNTABLEALET
public static final int ISGENQ_RSN_NOTAUTHORIZEDFORQNAME
public static final int ISGENQ_RSN_NOTAUTHORIZEDFOREXITQNAME
public static final int ISGENQ_RSN_NOTAUTHORIZEDFORECB
public static final int ISGENQ_RSN_NOTAUTHORIZEDFOROWNINGTTOKEN
public static final int ISGENQ_RSN_DEVICENOTALLOCATED
public static final int ISGENQ_RSN_EXITDEVICENOTALLOCATED
public static final int ISGENQ_RSN_BADCONTROL
public static final int ISGENQ_RSN_BADEXITUCB
public static final int ISGENQ_RSN_REQUESTLIMITEXCEEDED
public static final int ISGENQ_RSN_ABENDINEXIT
public static final int ISGENQ_RSN_TASKENDING
public static final int ISGENQ_RSN_FRRHELD
public static final int ISGENQ_RSN_LOCKHELD
public static final int ISGENQ_RSN_SRBMODE
public static final int ISGENQ_RSN_NOTENABLED
public static final int ISGENQ_RSN_CANNOTOBTAINHOMESTORAGE
public static final int ISGENQ_RSN_CANNOTOBTAINCOMMONSTORAGE
public static final int ISGENQ_RSN_CANNOTOBTAINPRIMARYALET
public static final int ISGENQ_RSN_SYNCHRESFLUSHFAILED
public static final int ISGENQ_RSN_RESERVESTARTFAILED
public static final int ISGENQ_RSN_RESERVECOUNTOVERFLOW
public static final int ISGENQ_RSN_CANNOTOBTAINDSQE
public static final int ISGENQ_RSN_RESERVEDONEFAILED
public Enqueue(java.lang.String qname, java.lang.String rname)
This does not actually test or obtain an ENQ on the resource;
see obtain()
and test()
.
qname
- the QNAMErname
- the RNAMEjava.lang.IllegalArgumentException
- if either qname or rname is null or if qname.length() > 8 or rname.length() > 255public void setContentionActWait()
setContentionActFail()
public void setContentionActFail()
public void setWaitTypeSuspend()
setWaitTypeECB()
,
setContentionActWait()
public void setWaitTypeECB()
Use of this method requires z/OS release 1.12 or later.
Waiting using an ECB is accomplished internally by using the 'MVSPAUSE' Unix API, which has the advantage of allowing Unix interrupts to be processed while waiting. Waiting without an ECB (WAITTYPE=SUSPEND) does not allow Unix interrupt processing to occur for the thread, which can for example block normal termination of the JVM when there is a thread suspended waiting on an ENQ contention.
setWaitTypeSuspend()
,
setContentionActWait()
public void setControl(int controlValue)
controlValue
- a value from ISGENQ_CONTROL_* constants.public void setScope(int scopeValue)
scopeValue
- a value from ISGENQ_SCOPE_* constants.public byte[] getEnqToken()
public java.lang.String getQName()
public java.lang.String getRName()
public void obtain() throws RcException
The ISGENQ macro is invoked with the following options:
ISGENQ REQUEST=OBTAIN, COND=YES, QNAME=qname, RNAME=rname, SCOPE=scope, CONTROL=control, CONTENTIONACT=WAIT|FAIL, WAITTYPE=SUSPEND|ECB, (only present if CONTENTIONACT=WAIT), ECB@=ecbaddr, (only present if CONTENTIONACT=WAIT and WAITTYPE=ECB) ENQTOKEN=enqToken, RETCODE=returncode, RSNCODE=reasoncode
RcException
- if a non-zero return code is returned from ISGENQ,
with a return code that contains the return code in the high order 16 bits and
the reason code in the low order 16 bits. The ISGENQ_RSN_* constants contain
combined return code / reason code values.public void test() throws RcException
The macro is invoked with the following options:
ISGENQ REQUEST=OBTAIN, COND=YES, TEST=YES, QNAME=qname, RNAME=rname, SCOPE=scope, CONTROL=control, ENQTOKEN=enqToken, RETCODE=returncode, RSNCODE=reasoncode
RcException
- if a non-zero return code is returned from ISGENQ,
with a return code that contains the return code in the high order 16 bits and
the reason code in the low order 16 bits. The ISGENQ_RSN_* constants contain
combined return code / reason code values.public void release() throws RcException
obtain()
call.
The ISGENQ macro is invoked with the following options:
ISGENQ REQUEST=RELEASE, COND=YES, ENQTOKEN=enqToken, RETCODE=returncode, RSNCODE=reasoncode
java.lang.IllegalStateException
- if the enqToken property is not set from a previous obtain()RcException
- if a non-zero return code is returned from ISGENQ,
with a return code that contains the return code in the high order 16 bits and
the reason code in the low order 16 bits. The ISGENQ_RSN_* constants contain
combined return code / reason code values.public void change() throws RcException
The ISGENQ macro is invoked with the following options:
ISGENQ REQUEST=CHANGE, COND=YES, ENQTOKEN=enqToken, RETCODE=returncode, RSNCODE=reasoncode
java.lang.IllegalStateException
- if the enqToken property is not set from a previous obtain()RcException
- if a non-zero return code is returned from ISGENQ,
with a return code that contains the return code in the high order 16 bits and
the reason code in the low order 16 bits. The ISGENQ_RSN_* constants contain
combined return code / reason code values.