com.ibm.jzos

Class Enqueue

  • 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. 

    
    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 Detail

      • 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_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_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_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_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_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_REQUESTLIMITEXCEEDED

        public static final int ISGENQ_RSN_REQUESTLIMITEXCEEDED
        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() and test().

        Parameters:
        qname - the QNAME
        rname - 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.
        See Also:
        setContentionActWait(), setWaitTypeECB(), setWaitTypeSuspend()

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

      • 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 successful obtain() 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 interface java.lang.AutoCloseable
        Throws:
        RcException
        Since:
        2.4.8
Skip navigation links
� Copyright IBM Corporation 2005, 2022.