- java.lang.Object
-
- com.ibm.jzos.Enqueue
-
- All Implemented Interfaces:
java.lang.AutoCloseable
public class Enqueue extends java.lang.Object implements java.lang.AutoCloseable
A class that provides a Java interface to the z/OS ISGENQ service. Can be used to control and serialize z/OS system QNAME/RNAME resources.For detailed information on using ISGENQ, see:
SA22-7605 z/OS MVS Programming: Assembler Services Guide
and:SA22-7607 z/OS MVS Programming: Assembler Services Reference, Volume 2 (IARR2V-XCTLX)
The class implements AutoCloseable. It can be used with the AutoCloseable with a try-with-resources block or without, as shown in the two examples below: Example 1: Obtain and release an Enqueue when a try-with-resources block is not used. The method release() is needed to release an obtained queue.
Example 2: Obtain and release an Enqueue when a try-with-resources block is used. The method release() is not needed. Upon exiting a try-with-resources block, the AutoCloseable will automatically call the close() method which will release the queue.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();
try (Enqueue enq = new Enqueue("JZOSTEST", "TEST01")) { enq.setContentionActFail(); // don't wait if contention enq.obtain(); } catch (RcException rce) { if (rce.getRc() != Enqueue.ISGENQ_RSN_NOTIMMEDIATELYAVAILABLE) { System.err.println("Resource not available"); } throw rce; } ...
- Since:
- 2.3.0, 2.4.0 changed to actually throw EnqueueException (a subclass of RcException) rather than RcException; the interface type is unchanged.
-
-
Field Summary
-
Constructor Summary
Constructors Constructor Description Enqueue(java.lang.String qname, java.lang.String rname)
Construct an instance.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
change()
Change a previously obtained enqueue described by this object's 'enqToken' property from CONTROL=SHARED to CONTROL=EXCLUSIVE.void
close()
The close method is automatically called by AutoCloseable to release an enqueue.byte[]
getEnqToken()
java.lang.String
getQName()
Answers the QNAMEjava.lang.String
getRName()
Answers the RNAMEboolean
getRNL()
Answer whether RNL=YES (true) or RNL=NO (false) will be used on ISGENQ REQUEST=OBTAIN calls.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 successfulobtain()
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
setRNL(boolean rnl)
Specify whether RNL=YES (true) or RNL=NO (false) will be used on ISGENQ REQUEST=OBTAIN calls.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.
-
-
-
Field Detail
-
ISGENQ_QNAME_MAX_LEN
public static final int ISGENQ_QNAME_MAX_LEN
- See Also:
- Constant Field Values
-
ISGENQ_RNAME_MAX_LEN
public static final int ISGENQ_RNAME_MAX_LEN
- See Also:
- Constant Field Values
-
ISGENQ_SCOPE_STEP
public static final int ISGENQ_SCOPE_STEP
- See Also:
- Constant Field Values
-
ISGENQ_SCOPE_SYSTEM
public static final int ISGENQ_SCOPE_SYSTEM
- See Also:
- Constant Field Values
-
ISGENQ_SCOPE_SYSTEMS
public static final int ISGENQ_SCOPE_SYSTEMS
- See Also:
- Constant Field Values
-
ISGENQ_SCOPE_SYSSPLEX
public static final int ISGENQ_SCOPE_SYSSPLEX
- See Also:
- Constant Field Values
-
ISGENQ_CONTROL_SHARED
public static final int ISGENQ_CONTROL_SHARED
- See Also:
- Constant Field Values
-
ISGENQ_CONTROL_EXCLUSIVE
public static final int ISGENQ_CONTROL_EXCLUSIVE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_NONZERORETURNCODES
public static final int ISGENQ_RSN_NONZERORETURNCODES
- See Also:
- Constant Field Values
-
ISGENQ_RSN_REQUESTNOTPROCESSED
public static final int ISGENQ_RSN_REQUESTNOTPROCESSED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_ECBWILLBEPOSTED
public static final int ISGENQ_RSN_ECBWILLBEPOSTED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_NOTIMMEDIATELYAVAILABLE
public static final int ISGENQ_RSN_NOTIMMEDIATELYAVAILABLE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_TASKOWNSEXCLUSIVE
public static final int ISGENQ_RSN_TASKOWNSEXCLUSIVE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_TASKOWNSSHARED
public static final int ISGENQ_RSN_TASKOWNSSHARED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_TASKWAITING
public static final int ISGENQ_RSN_TASKWAITING
- See Also:
- Constant Field Values
-
ISGENQ_RSN_OTHERSHAREDOWNERS
public static final int ISGENQ_RSN_OTHERSHAREDOWNERS
- See Also:
- Constant Field Values
-
ISGENQ_RSN_TASKDOESNOTOWN
public static final int ISGENQ_RSN_TASKDOESNOTOWN
- See Also:
- Constant Field Values
-
ISGENQ_RSN_TASKSUSPENDEDFORRESOURCE
public static final int ISGENQ_RSN_TASKSUSPENDEDFORRESOURCE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_UNPROTECTEDQNAME
public static final int ISGENQ_RSN_UNPROTECTEDQNAME
- See Also:
- Constant Field Values
-
ISGENQ_RSN_UNPROTECTEDEXITQNAME
public static final int ISGENQ_RSN_UNPROTECTEDEXITQNAME
- See Also:
- Constant Field Values
-
ISGENQ_RSN_ECBATLEASTONEREQUESTFAILED
public static final int ISGENQ_RSN_ECBATLEASTONEREQUESTFAILED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADPLISTADDRESS
public static final int ISGENQ_RSN_BADPLISTADDRESS
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADPLISTALET
public static final int ISGENQ_RSN_BADPLISTALET
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADPLISTVERSION
public static final int ISGENQ_RSN_BADPLISTVERSION
- See Also:
- Constant Field Values
-
ISGENQ_RSN_RESERVEDFIELDNOTNULL
public static final int ISGENQ_RSN_RESERVEDFIELDNOTNULL
- See Also:
- Constant Field Values
-
ISGENQ_RSN_MUTUALLYEXCLUSIVE
public static final int ISGENQ_RSN_MUTUALLYEXCLUSIVE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADREQUEST
public static final int ISGENQ_RSN_BADREQUEST
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADCONTENTIONACT
public static final int ISGENQ_RSN_BADCONTENTIONACT
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADOWNINGTTOKEN
public static final int ISGENQ_RSN_BADOWNINGTTOKEN
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADANSAREAADDRESS
public static final int ISGENQ_RSN_BADANSAREAADDRESS
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADANSAREAALET
public static final int ISGENQ_RSN_BADANSAREAALET
- See Also:
- Constant Field Values
-
ISGENQ_RSN_ANSLENTOOSMALL
public static final int ISGENQ_RSN_ANSLENTOOSMALL
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADRNAMEADDRESS
public static final int ISGENQ_RSN_BADRNAMEADDRESS
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADRNAMEALET
public static final int ISGENQ_RSN_BADRNAMEALET
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADRNAMELEN
public static final int ISGENQ_RSN_BADRNAMELEN
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADSCOPE
public static final int ISGENQ_RSN_BADSCOPE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADUCB
public static final int ISGENQ_RSN_BADUCB
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADCOND
public static final int ISGENQ_RSN_BADCOND
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADSYNCHRES
public static final int ISGENQ_RSN_BADSYNCHRES
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADENQTOKENADDRESS
public static final int ISGENQ_RSN_BADENQTOKENADDRESS
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADENQTOKENALET
public static final int ISGENQ_RSN_BADENQTOKENALET
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADENQTOKEN
public static final int ISGENQ_RSN_BADENQTOKEN
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADNUMRES
public static final int ISGENQ_RSN_BADNUMRES
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADRESTABLEADDRESS
public static final int ISGENQ_RSN_BADRESTABLEADDRESS
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADRESTABLEALET
public static final int ISGENQ_RSN_BADRESTABLEALET
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADRESTABLE
public static final int ISGENQ_RSN_BADRESTABLE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADENQTOKENTBLADDRESS
public static final int ISGENQ_RSN_BADENQTOKENTBLADDRESS
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADENQTOKENTBLALET
public static final int ISGENQ_RSN_BADENQTOKENTBLALET
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADRETURNTABLEADDRESS
public static final int ISGENQ_RSN_BADRETURNTABLEADDRESS
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADRETURNTABLEALET
public static final int ISGENQ_RSN_BADRETURNTABLEALET
- See Also:
- Constant Field Values
-
ISGENQ_RSN_NOTAUTHORIZEDFORQNAME
public static final int ISGENQ_RSN_NOTAUTHORIZEDFORQNAME
- See Also:
- Constant Field Values
-
ISGENQ_RSN_NOTAUTHORIZEDFOREXITQNAME
public static final int ISGENQ_RSN_NOTAUTHORIZEDFOREXITQNAME
- See Also:
- Constant Field Values
-
ISGENQ_RSN_NOTAUTHORIZEDFORECB
public static final int ISGENQ_RSN_NOTAUTHORIZEDFORECB
- See Also:
- Constant Field Values
-
ISGENQ_RSN_NOTAUTHORIZEDFOROWNINGTTOKEN
public static final int ISGENQ_RSN_NOTAUTHORIZEDFOROWNINGTTOKEN
- See Also:
- Constant Field Values
-
ISGENQ_RSN_DEVICENOTALLOCATED
public static final int ISGENQ_RSN_DEVICENOTALLOCATED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_EXITDEVICENOTALLOCATED
public static final int ISGENQ_RSN_EXITDEVICENOTALLOCATED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADCONTROL
public static final int ISGENQ_RSN_BADCONTROL
- See Also:
- Constant Field Values
-
ISGENQ_RSN_BADEXITUCB
public static final int ISGENQ_RSN_BADEXITUCB
- See Also:
- Constant Field Values
-
ISGENQ_RSN_REQUESTLIMITEXCEEDED
public static final int ISGENQ_RSN_REQUESTLIMITEXCEEDED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_ABENDINEXIT
public static final int ISGENQ_RSN_ABENDINEXIT
- See Also:
- Constant Field Values
-
ISGENQ_RSN_TASKENDING
public static final int ISGENQ_RSN_TASKENDING
- See Also:
- Constant Field Values
-
ISGENQ_RSN_FRRHELD
public static final int ISGENQ_RSN_FRRHELD
- See Also:
- Constant Field Values
-
ISGENQ_RSN_LOCKHELD
public static final int ISGENQ_RSN_LOCKHELD
- See Also:
- Constant Field Values
-
ISGENQ_RSN_SRBMODE
public static final int ISGENQ_RSN_SRBMODE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_NOTENABLED
public static final int ISGENQ_RSN_NOTENABLED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_CANNOTOBTAINHOMESTORAGE
public static final int ISGENQ_RSN_CANNOTOBTAINHOMESTORAGE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_CANNOTOBTAINCOMMONSTORAGE
public static final int ISGENQ_RSN_CANNOTOBTAINCOMMONSTORAGE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_CANNOTOBTAINPRIMARYALET
public static final int ISGENQ_RSN_CANNOTOBTAINPRIMARYALET
- See Also:
- Constant Field Values
-
ISGENQ_RSN_SYNCHRESFLUSHFAILED
public static final int ISGENQ_RSN_SYNCHRESFLUSHFAILED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_RESERVESTARTFAILED
public static final int ISGENQ_RSN_RESERVESTARTFAILED
- See Also:
- Constant Field Values
-
ISGENQ_RSN_RESERVECOUNTOVERFLOW
public static final int ISGENQ_RSN_RESERVECOUNTOVERFLOW
- See Also:
- Constant Field Values
-
ISGENQ_RSN_CANNOTOBTAINDSQE
public static final int ISGENQ_RSN_CANNOTOBTAINDSQE
- See Also:
- Constant Field Values
-
ISGENQ_RSN_RESERVEDONEFAILED
public static final int ISGENQ_RSN_RESERVEDONEFAILED
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Enqueue
public Enqueue(java.lang.String qname, java.lang.String rname)
Construct an instance.This does not actually test or obtain an ENQ on the resource; see
obtain()
andtest()
.- Parameters:
qname
- the QNAMErname
- the RNAME- Throws:
java.lang.IllegalArgumentException
- if either qname or rname is null or if qname.length() > 8 or rname.length() > 255
-
-
Method Detail
-
setContentionActWait
public void setContentionActWait()
Specifies that the ISGENQ call should wait if there is a contention for the resource. Corresponds to the macro option: CONTENTIONACT=WAIT. This is the default setting.- See Also:
setContentionActFail()
-
setContentionActFail
public void setContentionActFail()
Specifies that the ISGENQ call should fail with a RcException if there is a contention for the resource. Corresponds to the macro option: CONTENTIONACT=FAIL. The default, if this method is not called, is to wait.
-
setRNL
public void setRNL(boolean rnl)
Specify whether RNL=YES (true) or RNL=NO (false) will be used on ISGENQ REQUEST=OBTAIN calls. The default is true (RNL=YES).- Since:
- 2.4.8
-
getRNL
public boolean getRNL()
Answer whether RNL=YES (true) or RNL=NO (false) will be used on ISGENQ REQUEST=OBTAIN calls. The default is true (RNL=YES).- Since:
- 2.4.8
-
setWaitTypeSuspend
public void setWaitTypeSuspend()
Specifies that the ISGENQ call should suspend the current thread if there is a contention for the resource. Corresponds to the macro option: WAITTYPE=SUSPEND. This setting is ignored if CONTENTIONACT=WAIT is not also in effect (the default). This is the default WAITTYPE.- See Also:
setWaitTypeECB()
,setContentionActWait()
-
setWaitTypeECB
public void setWaitTypeECB()
Specifies that the ISGENQ call should wait on an internal ECB if there is a contention for the resource. Corresponds to the macro option: WAITTYPE=ECB. This setting is ignored if CONTENTIONACT=WAIT is not also in effect (the default).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.
- See Also:
setWaitTypeSuspend()
,setContentionActWait()
-
setControl
public void setControl(int controlValue)
Configures the ENQ for shared or exclusive control (See ISGENQ_CONTROL_* constants). If not set, defaults to ISGENQ_CONTROL_EXCLUSIVE.- Parameters:
controlValue
- a value from ISGENQ_CONTROL_* constants.
-
setScope
public void setScope(int scopeValue)
Configures the ENQ scope (See ISGENQ_SCOPE_* constants). If not set, defaults to ISGENQ_SCOPE_SYSTEM.- Parameters:
scopeValue
- a value from ISGENQ_SCOPE_* constants.
-
getEnqToken
public byte[] getEnqToken()
-
getQName
public java.lang.String getQName()
Answers the QNAME
-
getRName
public java.lang.String getRName()
Answers the RNAME
-
obtain
public void obtain() throws RcException
Obtain (ENQ on) the resource described by this object by invoking the ISGENQ macro.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
- Throws:
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.- Since:
- 2.4.0 actually throws EnqueueException (a subclass of RcException); signature is unchanged
-
test
public void test() throws RcException
Obtain (ENQ on) the resource described by this object by invoking the ISGENQ macro, using the TEST=YES option.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
- Throws:
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.- Since:
- 2.4.0 actually throws EnqueueException (a subclass of RcException); signature is unchanged
-
release
public void release() throws RcException
Release (DEQ) the resource described by this object's 'enqToken' property, which was previous enqueued using a successfulobtain()
call.The ISGENQ macro is invoked with the following options:
ISGENQ REQUEST=RELEASE, COND=YES, ENQTOKEN=enqToken, RETCODE=returncode, RSNCODE=reasoncode
- Throws:
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.- Since:
- 2.4.0 actually throws EnqueueException (a subclass of RcException); signature is unchanged
-
change
public void change() throws RcException
Change a previously obtained enqueue described by this object's 'enqToken' property from CONTROL=SHARED to CONTROL=EXCLUSIVE.The ISGENQ macro is invoked with the following options:
ISGENQ REQUEST=CHANGE, COND=YES, ENQTOKEN=enqToken, RETCODE=returncode, RSNCODE=reasoncode
- Throws:
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.- Since:
- 2.4.0 actually throws EnqueueException (a subclass of RcException); signature is unchanged
-
close
public void close() throws RcException
The close method is automatically called by AutoCloseable to release an enqueue. It is not intended to be used from customer code.The method is created to satisfy the AutoCloseable implementation. The AutoCloseable will automatically call this method when exiting a try-with-resources block. The method is equivalent to the release() method when a try-with-resources block is not used. Refer to the examples demonstrated in the class javadoc.
- Specified by:
close
in interfacejava.lang.AutoCloseable
- Throws:
RcException
- Since:
- 2.4.8
-
-