Introduction
This document describes how to connect to the Zetaly Messaging address space (DXQUEUE) in order to consume the records stored by the Zetaly SMF Exit (DXSMF address space).
The Zetaly Messaging is a 64-bit address space responsible to buffer messages (or records) in memory in a FIFO basis (first in first out) where the messages are kept on the memory above the BAR i.e. storage above the address 0x100000000H.
The communication with the DXQUEUE is done through the execution off program calls (PC), so any address space have to connect the DXQUEUE linkage table in order to execute the program calls.
The process of connecting and disconnecting is done through the DRSPC module functions:
@PCINIT - Initialize DRSPC
@PCCCON - Client connection to server
@PCCDIS - Client disconnect from server
@PCTERM - Terminate DRSPC
DXQUEUE Connection
In order to interact with the DXQUEUE address space, the first thing to do is to connect to it. The following code describes the process:
Note: You should be authorized and running in KEY=0 to call the DRSPC. After this, you can return to problem state.
The CTSNAME is the server name and its currently value is 'DXPL.DXQUEUE.CB' and should be padded with blanks to complete 16 characters:
You also need to define the DRSPC parmlist through the DNSPC macro:
DXQUEUE Disconnection
You can gracefully disconnect from the DXQUEUE through the following functions:
Note: You have to be authorized and running in KEY=0 to call the DRSPC functions.
Getting DXQUEUE messages
To get messages from the DXQUEUE, you need to open a session (QOPEN macro) and them get the messages with the QDEQ or QMDEQ macros.
QDEQ returns a single message if there is one available and QMDEQ, get a bulk of messages.
Once you have done with the records, you execute the macro QCONF to confirm that you do not need the messages anymore and their memory slots can be reused.
If you issue the QCANC macro (cancel), all unconfirmed messages returns to the message list.
Zetaly Messaging functions
On this chapter we describe the Zetaly Messaging functions to communicate with the DXQUEUE address space.
Macro | Description |
QOPEN | Open a session connection to the DXQUEUE |
QDEQ | Get one message from the DXQUEUE if there is one available |
QMDEQ | Get multiple messages from the DXQUEUE |
QCONF | Acknowledge all previous messages on the same session |
QCANC | All unconfirmed messages on this session will return to the message queue |
QCLOS | Close a session. All non acknowledged messages will be canceled. i.e. return to the message queue |
Environment
Minimum authorization: problem state and PSW key 8-15
Dispatchable unit mode: Task
Cross memory mode:Any PASN, any HASN, any SASN
AMODE:24- or 31-or 64-bit
ASC mode: Primary or AR
Output Register Information
When control returns to the caller, the general purpose registers (GPRs) contain:
Register Contents
0-1Used as work registers by the system
2-13 Unchanged
14-15Used as work registers by the system
QOPEN - Open a session
Description
A DXQUEUE session allows the acknowledgment of message receival and rollback functionality when canceling messages.
Once you open a session, you get a connection ID (CID) that you should provide in all sucessive functions calls.
You can open as many sessions as you want.
Syntax
name QOPEN CID=cid-addr
cid-addr RX-type address, or register (R0) - (R15)
Parameters
CID=Specifies the address of a fullword to receive the connection ID (CID). The CID value has to be used on all subsequent functions.
Example
QOPEN CID=DYCID * OPEN A QUEUE
.
.
.
DYCID DS F * CID - CONNECTION ID
Return Codes
Return Code | Description |
00 | Success. The connection session is opened and the session ID is returned on the CID provided address |
08 | Session limit reached. Currently the maximum number of sessions is 1100. |
QDEQ - Get a Message
Description
Get the oldest message on the DXQUEUE address space. If there is no message available, the function returns immediately.
Syntax
name QDEQ CID=cid-addr,MSG=msg,LEN=len,MAXLEN=
cid-addrRX-type address, or register (R0) - (R15)
msg RX-type address, or register (R0) - (R15)
Default: (R1)
lenr RX-type address, or register (R0) - (R15)
Default: (R0)
MAXLEN200 - 32768
Default: 32768
Parameters
CID=Specifies the address of a fullword containing a connection ID (CID) returned on the QOPEN function.
MSG= Buffer address to receive the message.
LEN= Fullword address to receive the size of the message returned.
MAXLEN= Maximum size of the message.
Example
Return Codes
Return Code | Description |
00 | Success. The message is copied to the provided buffer and its size returned on the LEN supplied address. |
04 | No messages on the DXQUEUE. |
08 | Invalid connection ID (CID). Or Message bigger than MAXLEN. |
QMDEQ - Get Multiple Messages
Description
Get multiple messages from the DXQUEUE address space. If there is less messages available than requested, the function will return immediately with the available messages.
Syntax
name QMDEQ CID=cid-addr,BUF=buf,NMSG=nmsg,MAX=
cid-addrRX-type address, or register (R0) - (R15)
buf RX-type address, or register (R0) - (R15)
Default: (R1)
nmsg RX-type address, or register (R0) - (R15)
Default: (R0)
MAX1 - 32768
Default: 100
Parameters
CID=Specifies the address of a fullword containing a connection ID (CID) returned on the QOPEN function.
BUF= Buffer address to receive the messages.
Each message is preceded by 2 bytes containing the size of the message.
After the last message, there is 2 bytes with zeros indicating the end of messages.
NMSG= Fullword address to receive the number of messages on the output buffer informed on BUF address.
MAX= Number of desired returned messages. The buffer supplied has to have enough space to hold all the messages requested.
Example
Return Codes
Return Code | Description |
00 | Success. The messages are copied to the provided buffer and its quantity is returned on the NMSG supplied address. |
04 | No messages on the DXQUEUE. |
08 | Invalid connection ID (CID). |
QCONF - Acknowledge MEssages Received
Description
Confirm all non-acknowledge messages on the supplied session ID. The slots used to save these messages are freed to be reused.
Syntax
name QCONF CID=cid-addr
cid-addrRX-type address, or register (R0) - (R15)
Default: (R1)
Parameters
CID=Specifies the address of a fullword containing a connection ID (CID) returned on the QOPEN function.
Example
Return Codes
Return Code | Description |
00 | Success. The messages were free. |
08 | Invalid connection ID (CID). |
QCANC - Cancel Messages
Description
This function is used to return all non-acknowledge messages on the provided session to the message list.
You can call this function on an error situation.
Syntax
name QCANC CID=cid-addr
cid-addrRX-type address, or register (R0) - (R15)
Default: (R1)
Parameters
CID=Specifies the address of a fullword containing a connection ID (CID) returned on the QOPEN function.
Return Codes
Return Code | Description |
00 | Success. The messages returns to the message queue. |
08 | Invalid connection ID (CID). |
QCLOS - Close Session
Description
Close a session with the DXQUEUE. All non-acknowledge messages on the session will be canceled i.e. return to the message queue.
A closed session can be reused by another QOPEN session.
Syntax
name QCLOS CID=cid-addr
cid-addrRX-type address, or register (R0) - (R15)
Default: (R1)
Parameters
CID=Specifies the address of a fullword containing a connection ID (CID) returned on the QOPEN function.
Example
Return Codes
Return Code | Description |
00 | Success. Any non-acknowledge message will return to the message queue and the session is terminated. |
08 | Invalid connection ID (CID). |