CQS client requests
CQS clients communicate with the CQS address space using a general-use interface consisting of a number of assembler macros, called CQS requests. CQS clients use these requests to communicate with the CQS and manipulate client data on shared coupling facility structures. You can use these requests to write or maintain a CQS client.
You do not need to use these requests if you are using an IBM®-supplied client, such as an IMS control region.
Some CQS requests support wildcard parameters. Wildcard parameters allow you to specify multiple resources whose names match the wildcard parameter mask. The size of a wildcard parameter can be from one character to the maximum number of characters supported for the resource. The alphanumeric name can include one or more specialized characters and an asterisk or percent sign. An asterisk can be replaced by zero, one, or more characters to create a valid resource name. A percent sign can be replaced by exactly one character to create a valid resource name. The wildcard parameter asterisk (*) represents 'ALL'. However, depending on the installation, other wildcard parameters can mean all. For example, the wildcard parameter %%%% means ALL to an installation whose resource names are all 4 characters long.
This topic contains General-use Programming Interface information.
Example of using a CQS request: CQSREAD
The following example shows how you can use a CQSREAD request for a client subsystem.
***********************************************************************
* FUNCTION: USE CQSREAD REQUEST TO RETRIEVE A MESSAGE FROM SHARED *
* QUEUES. *
* *
* THE CALLER OF THIS MODULE PASSES THE ADDRESS AND SIZE OF *
* A BUFFER. IF THIS MODULE ENDS WITH RC=0, THAT BUFFER *
* HOLDS THE DATA OBJECT OR PARTIAL DATA. IF THIS MODULE *
* ENDS WITH A NON-ZERO RC, THE BUFFER'S CONTENTS ARE *
* UNPREDICTABLE. *
* *
* REGISTERS ON ENTRY: *
* *
* R2 - READ OBJECT BUFFER ADDRESS (BUFFER TO READ OBJECT INTO) *
* R3 - SIZE OF READ OBJECT BUFFER *
* R4 - CQS REGISTRATION TOKEN ADDRESS *
* R5 - CQS CONNECT TOKEN ADDRESS *
* R9 - ECB ADDRESS *
* R13 - SAVE AREA ADDRESS *
* R14 - RETURN ADDRESS *
* R15 - GETDOBJ ENTRY POINT ADDRESS *
* *
* REGISTERS DURING EXECUTION: *
* *
* R0 - WORK REGISTER *
* R1 - WORK REGISTER *
* R2 - CQSREAD PARMLIST AREA ADDRESS *
* R3 - WORK REGISTER *
* R4 - WORK REGISTER *
* R5 - WORK REGISTER *
* R6 - WORK REGISTER *
* R7 - WORK REGISTER *
* R8 - WORK REGISTER *
* R9 - ECB ADDRESS *
* R10 - WORK REGISTER *
* R11 - WORK REGISTER *
* R12 - BASE REGISTER *
* R13 - SAVE AREA ADDRESS *
* R14 - WORK REGISTER *
* R15 - WORK REGISTER *
* *
* MACROS REFERENCED: *
* WAIT *
* CQSREAD *
* *
* RETURN CODES: *
* R15 - RETURN CODE *
* X'00' CQSREAD SUCCESSFUL/PARTIAL DATA RETURNED *
* X'08' INTERFACE PROBLEM *
* X'0C' NO MESSAGE FOR QNAME *
* X'10' REQUEST IS UNSUCCESSFUL, UNEXPECTED RETURN OR REASON *
* CODE *
* *
***********************************************************************
STM R14,R12,12(R13) SAVE THE REGS
LR R12,R15 R12 = PROGRAM BASE REGISTER
USING GETDOBJ,R12 GETDOBJ CSECT
LA R14,SAVEAREA CHAIN SAVE AREAS
ST R13,4(,R14) THIS SAVEAREA BACKWARD PTR
ST R14,8(,R13) LAST SAVEAREA FORWARD PTR
LA R13,SAVEAREA THIS ROUTINE'S SAVEAREA
ST R2,RDRBUFA SAVE A(BUFFER TO READ INTO)
ST R3,RDRBUFSZ SAVE READ BUFFER SIZE
MVC RDRRQTK,0(R4) SAVE CQS REGISTRATION TOKEN
MVC RDRCONTK,0(R5) SAVE CQS CONNECT TOKEN
ST R9,RDRECBA SAVE A(ECB)
LA R2,RDRPARM LOAD A(PARAMETER AREA) INTO R2
XC RDRLCKTK,RDRLCKTK LOCKTOKEN=0 FOR FIRST CQSREAD
XC 0(4,R9),0(R9) CLEAR CALLER'S ECB
****
* RETRIEVE RECORD FROM IMS SHARED QUEUES
****
CQSREAD FUNC=READ, X
CQSTOKEN=@(RDRRQTK), A(REGISTRATION TOKEN) X
PARM=(R2), A(CQSREAD PARMLIST AREA) X
CONTOKEN=@(RDRCONTK), A(CONNECT TOKEN) X
ECB=RDRECBA, A(ECB) X
LCKTOKEN=@(RDRLCKTK), A(LOCK TOKEN) - RETURNED X
UOW=@(RDRUOW), A(UOW) - RETURNED X
LOCAL=NO, READ OBJECT FROM SHARED QUEUE X
QNAME=@(RDRQNAME), A(QUEUE NAME) X
QPOS=FIRST, READ FIRST OBJECT ON QUEUE X
OBJSIZE=@(RDROBJSZ), A(DATA OBJECT SIZE) - RETURNED X
RSNCODE=@(RDRRSN), A(REASON CODE) - RETURNED X
RETCODE=@(RDRRC), A(RETURN CODE) - RETURNED X
BUFFER=RDRBUFA, A(CLIENT'S READ BUFFER) X
BUFSIZE=@(RDRBUFSZ) CLIENT'S READ BUFFER SIZE
LTR R15,R15 TEST RETURN CODE FROM CQS INTERFACE
BZ CHECKRC ZERO - CQSREAD OK
* OTHER - RETURN R0, R15 IN PARM LIST
LA R15,RC08 CQS INTERFACE PROBLEM
B GOEXIT RETURN TO CALLER
****
* CHECK CQSREAD RETURN CODE
****
CHECKRC DS 0H
WAIT ECB=(R9) WAIT FOR CQSREAD TO COMPLETE
L R15,RDRRC RETURN CODE
LTR R15,R15 CQSREAD REQUEST SUCCESSFUL?
BZ GOEXIT YES - RETURN TO CALLER****
* CHECK FOR CQS WARNING RETURN CODE
****
CLC RDRRC,=AL4(RQRCWARN) CQSREAD WARNING?
BNE UNEXPECT NO - SET RC AND RETURN TO CALLER
****
* CQSREAD: WARNING RETURN CODE - CHECK WARNING REASON CODE
* CHECK FOR DATA OBJECT
****
CLC RDRRSN,=AL4(RRDNOOBJ) NO DATA OBJECT?
BNE PARTIAL NO, CHECK NEXT REASON CODE
LA R15,RC0C SET NO DATA OBJECT RETURN CODE
B GOEXIT RETURN TO CALLER
****
* CHECK PARTIAL DATA RETURNED
* PARTIAL DATA RETURNED - RETURN DATA OBJECT - RETURN CODE 0
****
PARTIAL DS 0H
CLC RDRRSN,=AL4(RRDPARTL) PARTIAL DATA RETURNED?
BNE UNEXPECT NO - SET RC AND RETURN TO CALLER
LA R15,RC00 SET RETURN CODE
B GOEXIT RETURN TO CALLER
****
* UNEXPECTED RETURN OR REASON CODE
****
UNEXPECT DS 0H
LA R15,RC10 UNEXPECTED RETURN OR REASON CODE
B GOEXIT RETURN TO CALLER
***********************************************************************
* STANDARD EXIT *
***********************************************************************
GOEXIT DS 0H
L 13,4(,13) GET PREVIOUS SAVE LEVEL
L 14,12(13) A(RETURN-TO-CALLER)
LM 0,12,20(13) RESTORE REGS
OI 15(13),X'01' SET RETURN FLAG IN CALLER SAVE AREA
BR 14 RETURN TO CALLER
***********************************************************************
* CONSTANTS *
***********************************************************************
*
* GETDOBJ RETURN CODES
*
RC00 EQU 0 CQSREAD SUCCESSFUL -
RC08 EQU 8 INTERFACE PROBLEM
RC0C EQU 12 NO MESSAGE FOR QNAME
RC10 EQU 16 UNEXPECTED RETURN CODE*
* REGISTER EQUATES
*
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
***********************************************************************
* VARIABLES *
***********************************************************************
DS 0F
SAVEAREA DS 18F
DS 0D
RDRRQTK DS XL16 CQS REGISTRATION TOKEN
RDRCONTK DS XL16 CQS CONNECT TOKEN
RDRLCKTK DS XL16 LOCKTOKEN (RETURNED)
RDRUOW DS XL32 UOW (RETURNED)
RDRQNAME DS 0XL16 QUEUE NAME
DC X'05' CLIENT QUEUE TYPE 5
DC CL15'FFSTR01CF02CQ04'
RDROBJSZ DS F OBJECT SIZE (RETURNED)
RDRRSN DS F CQSREAD REASON CODE (RETURNED)
RDRRC DS F CQSREAD RETURN CODE (RETURNED)
RDRBUFA DS A A(READ OBJECT BUFFER)
RDRBUFSZ DS F SIZE OF READ OBJECT BUFFER
RDRECBA DS A A(ECB)
RDRPARM DS XL(CQSREAD_PARM_LEN) CQSREAD PARMLIST
***********************************************************************
* LITERALS *
***********************************************************************
LTORG
CQSREAD FUNC=DSECT CQSREAD DSECTS & EQUATES
END GETDOBJ