Module ibm.jzos
Package com.ibm.jzos

Class Enqueue

java.lang.Object
com.ibm.jzos.Enqueue
All Implemented Interfaces:
AutoCloseable
public class Enqueue extends Object implements 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. 


    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();
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. 

    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 Details

    • ISGENQ_QNAME_MAX_LEN

      public static final int ISGENQ_QNAME_MAX_LEN
      See Also:

    • ISGENQ_RNAME_MAX_LEN

      public static final int ISGENQ_RNAME_MAX_LEN
      See Also:

    • ISGENQ_SCOPE_STEP

      public static final int ISGENQ_SCOPE_STEP
      See Also:

    • ISGENQ_SCOPE_SYSTEM

      public static final int ISGENQ_SCOPE_SYSTEM
      See Also:

    • ISGENQ_SCOPE_SYSTEMS

      public static final int ISGENQ_SCOPE_SYSTEMS
      See Also:

    • ISGENQ_SCOPE_SYSSPLEX

      public static final int ISGENQ_SCOPE_SYSSPLEX
      See Also:

    • ISGENQ_CONTROL_SHARED

      public static final int ISGENQ_CONTROL_SHARED
      See Also:

    • ISGENQ_CONTROL_EXCLUSIVE

      public static final int ISGENQ_CONTROL_EXCLUSIVE
      See Also:

    • ISGENQ_RSN_NONZERORETURNCODES

      public static final int ISGENQ_RSN_NONZERORETURNCODES
      See Also:

    • ISGENQ_RSN_REQUESTNOTPROCESSED

      public static final int ISGENQ_RSN_REQUESTNOTPROCESSED
      See Also:

    • ISGENQ_RSN_ECBWILLBEPOSTED

      public static final int ISGENQ_RSN_ECBWILLBEPOSTED
      See Also:

    • ISGENQ_RSN_NOTIMMEDIATELYAVAILABLE

      public static final int ISGENQ_RSN_NOTIMMEDIATELYAVAILABLE
      See Also:

    • ISGENQ_RSN_TASKOWNSEXCLUSIVE

      public static final int ISGENQ_RSN_TASKOWNSEXCLUSIVE
      See Also:

    • ISGENQ_RSN_TASKOWNSSHARED

      public static final int ISGENQ_RSN_TASKOWNSSHARED
      See Also:

    • ISGENQ_RSN_TASKWAITING

      public static final int ISGENQ_RSN_TASKWAITING
      See Also:

    • ISGENQ_RSN_OTHERSHAREDOWNERS

      public static final int ISGENQ_RSN_OTHERSHAREDOWNERS
      See Also:

    • ISGENQ_RSN_TASKDOESNOTOWN

      public static final int ISGENQ_RSN_TASKDOESNOTOWN
      See Also:

    • ISGENQ_RSN_TASKSUSPENDEDFORRESOURCE

      public static final int ISGENQ_RSN_TASKSUSPENDEDFORRESOURCE
      See Also:

    • ISGENQ_RSN_UNPROTECTEDQNAME

      public static final int ISGENQ_RSN_UNPROTECTEDQNAME
      See Also:

    • ISGENQ_RSN_UNPROTECTEDEXITQNAME

      public static final int ISGENQ_RSN_UNPROTECTEDEXITQNAME
      See Also:

    • ISGENQ_RSN_ECBATLEASTONEREQUESTFAILED

      public static final int ISGENQ_RSN_ECBATLEASTONEREQUESTFAILED
      See Also:

    • ISGENQ_RSN_BADPLISTADDRESS

      public static final int ISGENQ_RSN_BADPLISTADDRESS
      See Also:

    • ISGENQ_RSN_BADPLISTALET

      public static final int ISGENQ_RSN_BADPLISTALET
      See Also:

    • ISGENQ_RSN_BADPLISTVERSION

      public static final int ISGENQ_RSN_BADPLISTVERSION
      See Also:

    • ISGENQ_RSN_RESERVEDFIELDNOTNULL

      public static final int ISGENQ_RSN_RESERVEDFIELDNOTNULL
      See Also:

    • ISGENQ_RSN_MUTUALLYEXCLUSIVE

      public static final int ISGENQ_RSN_MUTUALLYEXCLUSIVE
      See Also:

    • ISGENQ_RSN_BADREQUEST

      public static final int ISGENQ_RSN_BADREQUEST
      See Also:

    • ISGENQ_RSN_BADCONTENTIONACT

      public static final int ISGENQ_RSN_BADCONTENTIONACT
      See Also:

    • ISGENQ_RSN_BADOWNINGTTOKEN

      public static final int ISGENQ_RSN_BADOWNINGTTOKEN
      See Also:

    • ISGENQ_RSN_BADANSAREAADDRESS

      public static final int ISGENQ_RSN_BADANSAREAADDRESS
      See Also:

    • ISGENQ_RSN_BADANSAREAALET

      public static final int ISGENQ_RSN_BADANSAREAALET
      See Also:

    • ISGENQ_RSN_ANSLENTOOSMALL

      public static final int ISGENQ_RSN_ANSLENTOOSMALL
      See Also:

    • ISGENQ_RSN_BADRNAMEADDRESS

      public static final int ISGENQ_RSN_BADRNAMEADDRESS
      See Also:

    • ISGENQ_RSN_BADRNAMEALET

      public static final int ISGENQ_RSN_BADRNAMEALET
      See Also:

    • ISGENQ_RSN_BADRNAMELEN

      public static final int ISGENQ_RSN_BADRNAMELEN
      See Also:

    • ISGENQ_RSN_BADSCOPE

      public static final int ISGENQ_RSN_BADSCOPE
      See Also:

    • ISGENQ_RSN_BADUCB

      public static final int ISGENQ_RSN_BADUCB
      See Also:

    • ISGENQ_RSN_BADCOND

      public static final int ISGENQ_RSN_BADCOND
      See Also:

    • ISGENQ_RSN_BADSYNCHRES

      public static final int ISGENQ_RSN_BADSYNCHRES
      See Also:

    • ISGENQ_RSN_BADENQTOKENADDRESS

      public static final int ISGENQ_RSN_BADENQTOKENADDRESS
      See Also:

    • ISGENQ_RSN_BADENQTOKENALET

      public static final int ISGENQ_RSN_BADENQTOKENALET
      See Also:

    • ISGENQ_RSN_BADENQTOKEN

      public static final int ISGENQ_RSN_BADENQTOKEN
      See Also:

    • ISGENQ_RSN_BADNUMRES

      public static final int ISGENQ_RSN_BADNUMRES
      See Also:

    • ISGENQ_RSN_BADRESTABLEADDRESS

      public static final int ISGENQ_RSN_BADRESTABLEADDRESS
      See Also:

    • ISGENQ_RSN_BADRESTABLEALET

      public static final int ISGENQ_RSN_BADRESTABLEALET
      See Also:

    • ISGENQ_RSN_BADRESTABLE

      public static final int ISGENQ_RSN_BADRESTABLE
      See Also:

    • ISGENQ_RSN_BADENQTOKENTBLADDRESS

      public static final int ISGENQ_RSN_BADENQTOKENTBLADDRESS
      See Also:

    • ISGENQ_RSN_BADENQTOKENTBLALET

      public static final int ISGENQ_RSN_BADENQTOKENTBLALET
      See Also:

    • ISGENQ_RSN_BADRETURNTABLEADDRESS

      public static final int ISGENQ_RSN_BADRETURNTABLEADDRESS
      See Also:

    • ISGENQ_RSN_BADRETURNTABLEALET

      public static final int ISGENQ_RSN_BADRETURNTABLEALET
      See Also:

    • ISGENQ_RSN_NOTAUTHORIZEDFORQNAME

      public static final int ISGENQ_RSN_NOTAUTHORIZEDFORQNAME
      See Also:

    • ISGENQ_RSN_NOTAUTHORIZEDFOREXITQNAME

      public static final int ISGENQ_RSN_NOTAUTHORIZEDFOREXITQNAME
      See Also:

    • ISGENQ_RSN_NOTAUTHORIZEDFORECB

      public static final int ISGENQ_RSN_NOTAUTHORIZEDFORECB
      See Also:

    • ISGENQ_RSN_NOTAUTHORIZEDFOROWNINGTTOKEN

      public static final int ISGENQ_RSN_NOTAUTHORIZEDFOROWNINGTTOKEN
      See Also:

    • ISGENQ_RSN_DEVICENOTALLOCATED

      public static final int ISGENQ_RSN_DEVICENOTALLOCATED
      See Also:

    • ISGENQ_RSN_EXITDEVICENOTALLOCATED

      public static final int ISGENQ_RSN_EXITDEVICENOTALLOCATED
      See Also:

    • ISGENQ_RSN_BADCONTROL

      public static final int ISGENQ_RSN_BADCONTROL
      See Also:

    • ISGENQ_RSN_BADEXITUCB

      public static final int ISGENQ_RSN_BADEXITUCB
      See Also:

    • ISGENQ_RSN_REQUESTLIMITEXCEEDED

      public static final int ISGENQ_RSN_REQUESTLIMITEXCEEDED
      See Also:

    • ISGENQ_RSN_ABENDINEXIT

      public static final int ISGENQ_RSN_ABENDINEXIT
      See Also:

    • ISGENQ_RSN_TASKENDING

      public static final int ISGENQ_RSN_TASKENDING
      See Also:

    • ISGENQ_RSN_FRRHELD

      public static final int ISGENQ_RSN_FRRHELD
      See Also:

    • ISGENQ_RSN_LOCKHELD

      public static final int ISGENQ_RSN_LOCKHELD
      See Also:

    • ISGENQ_RSN_SRBMODE

      public static final int ISGENQ_RSN_SRBMODE
      See Also:

    • ISGENQ_RSN_NOTENABLED

      public static final int ISGENQ_RSN_NOTENABLED
      See Also:

    • ISGENQ_RSN_CANNOTOBTAINHOMESTORAGE

      public static final int ISGENQ_RSN_CANNOTOBTAINHOMESTORAGE
      See Also:

    • ISGENQ_RSN_CANNOTOBTAINCOMMONSTORAGE

      public static final int ISGENQ_RSN_CANNOTOBTAINCOMMONSTORAGE
      See Also:

    • ISGENQ_RSN_CANNOTOBTAINPRIMARYALET

      public static final int ISGENQ_RSN_CANNOTOBTAINPRIMARYALET
      See Also:

    • ISGENQ_RSN_SYNCHRESFLUSHFAILED

      public static final int ISGENQ_RSN_SYNCHRESFLUSHFAILED
      See Also:

    • ISGENQ_RSN_RESERVESTARTFAILED

      public static final int ISGENQ_RSN_RESERVESTARTFAILED
      See Also:

    • ISGENQ_RSN_RESERVECOUNTOVERFLOW

      public static final int ISGENQ_RSN_RESERVECOUNTOVERFLOW
      See Also:

    • ISGENQ_RSN_CANNOTOBTAINDSQE

      public static final int ISGENQ_RSN_CANNOTOBTAINDSQE
      See Also:

    • ISGENQ_RSN_RESERVEDONEFAILED

      public static final int ISGENQ_RSN_RESERVEDONEFAILED
      See Also:

  • Constructor Details

    • Enqueue

      public Enqueue(String qname, String rname)
      Construct an instance.

      This does not actually test or obtain an ENQ on the resource; see obtain() and test().

      Parameters:
      qname - the QNAME
      rname - the RNAME
      Throws:
      IllegalArgumentException - if either qname or rname is null or if qname.length() > 8 or rname.length() > 255

  • Method Details

    • 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

      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.
      See Also:

    • 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

      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:

    • 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()
      Gets the 32-byte ISGENQ token that resulted from a previous obtain() or test() call. May be null.

    • getQName

      public String getQName()
      Answers the QNAME

    • getRName

      public 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 successful obtain() call.

      The ISGENQ macro is invoked with the following options: 

          ISGENQ REQUEST=RELEASE,
           COND=YES,
           ENQTOKEN=enqToken,
           RETCODE=returncode,
           RSNCODE=reasoncode
      Throws:
      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:
      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 interface AutoCloseable
      Throws:
      RcException
      Since:
      2.4.8