Considerations for coding CQS requests

Authorization for CQS

CQS provides two interfaces for its clients: the authorized interface and the non-authorized interface. CQS automatically selects and initializes the correct interface environment based on the client's state when the client issues a CQSREG request. If the client is authorized (in supervisor state with PSW key 0 to 7), CQS initializes the authorized interface environment. If the client is not authorized (in problem state with key 8 or greater), CQS initializes the non-authorized interface environment.

Which interface CQS assigns to the client determines the allowed environments for all subsequent CQS requests and all client exit routines driven by CQS. In general, when a client makes a CQS request, its PSW state and key must be the same as they were when it issued the CQSREG request.

How CQS requests use registers

All CQS requests use registers R0, R1, R14, and R15 as work registers. When a CQS request returns control to the caller, the contents of these registers are not the same as they were before the macro call. R15 contains a return code, and R0 contains a reason code from the CQS interface. The contents of registers R2 through R13 remain unchanged after a CQS request, except for registers specified as output parameters for the particular request.

All CQS requests require register R13 to point to a standard 72-byte save area. No other registers are required to contain any particular value when a CQS request is issued, except for registers specified as input parameters for the particular request.

Coding parameters for CQS requests

For all of the parameters (shown in the syntax diagrams as, for example, parameter) that are not literals, CQS expects either an address or a value. For example, for the cqstoken on a CQSREAD request, CQS expects the address of the 16-byte CQS token, but for the buffersize, CQS expects a 4-byte buffer size.

To pass an address or a parameter value to CQS, you can code the parameter for the CQS request in one of three ways:

1. Use a register

   To use a register, you must load the address or the parameter value into one of the general purpose registers, then use that register (enclosed in parentheses) for the parameter in the CQS request.

   Figure 1. Passing an address for register

            LA    5,TOKEN
            CQSREAD FUNC=READ,CQSTOKEN=(5),…
            ⋮
   TOKEN    DS    XL16

   Figure 2. Passing a value for register

            L     4,MYBUFLEN
            CQSREAD FUNC=READ,BUFSIZE=(4),…
            ⋮
   MYBUFLEN DC    F'00000024'

2. Use a symbol

   To use a symbol name, you must define a symbol that contains the address or the parameter value, then use that symbol for the parameter in the CQS request.

   Figure 3. Passing an address for symbol

            CQSREAD FUNC=READ,CQSTOKEN=TOKENADR,…
            ⋮ TOKENADR DC    A(TOKEN) TOKEN    DS    XL16 

   Figure 4. Passing a value for symbol

            CQSREAD FUNC=READ,BUFSIZE=MYBUFLEN,…
            ⋮ MYBUFLEN DC    F'00000024'

3. Use a symbol value

   To use a symbol value, you must define a symbol or an equate that contains the parameter value, then use that symbol (preceded by the at-sign, @, and enclosed in parentheses) for the parameter in the CQS request.

   Figure 5. Passing a value for symbol value

            CQSREAD FUNC=READ,CQSTOKEN=@(TOKEN),…
            ⋮ TOKEN    DC    XL16'0000A765B55CFF00'

   Figure 6. Passing an equate for symbol value

             CQSREAD FUNC=READ,BUFSIZE=@(MYBUFLEN),…
            ⋮ MYBUFLEN EQU   24

Literals for CQS requests

A number of CQS request macros have parameters that use a literal (for example, the LOCAL parameter on the CQSREAD request macro). A macro invocation can use either combinations of literal parameters or the OPTWORD1 parameter to pass 4 bytes containing flags that represent the literals. When you use the OPTWORD1 parameter, you obtain the literal equates by using the DSECT function of each request macro. The equates that represent the literal values are added together in a regular storage location.

To code a CQSREAD request using a series of literal parameters, use CQSREAD FUNC=READ,…,QPOS=FIRST,LOCAL=YES….

Event Control Blocks with CQS requests

Some requests allow you to use a z/OS® event control block (ECB). If you specify an ECB (ECB=ecbaddress), the client immediately receives control after issuing the request, but must at some time be sure to wait for the request to post the ECB. If you do not specify an ECB, CQS does not return control to the client until CQS completes its processing for the request.

Lists in the CQS requests

Some of the CQS requests have a LIST keyword, which specifies the address of a parameter list entry. This keyword specifies the address of the first list entry. If you want to pass multiple list entries, you must ensure that they all reside in contiguous storage, that is, the next entry must begin at the first byte following the current entry. All lists must be contiguous, even if they are not aligned on word or fullword boundaries.

Assembling a program with CQS requests

The CQS request macros are shipped with IMS and are included in the IMS.ADFSMAC data set. When you assemble a program that includes CQS request macros, you must tell the assembler to look for the macros in this data set. You can also copy the members from the IMS data set to another data set, as necessary.

There are no special requirements for link editing a program that includes CQS requests, but you do have to ensure that the IMS.SDFSRESL data set is concatenated with your JOB or STEPLIB DD statement for the client job.