gtps2m3kACF/SNA Data Communications Reference

Queue Manager Interface

The Queue Manager parameter list, IQPRM (Table 21), is used for both input and output when interfacing with the Queue Manager. The user must provide this parameter list, load its address in register one (R1), and enter (ENTRC) segment CMX0 when issuing a queueing request. After completing the user-requested service, the Queue Manager returns the parameter list and sets indicators to identify successful or unsuccessful queue management results.

Note:
The Queue Manager package is subsystem independent. It is the user's responsibility to ensure the subsystem environment is initialized when entering the Queue Manager package.

Table 21. Queue Manager Parameter List

Field Label Displacement Byte Value Comments
IQPRFUNC 0 1 X'00'
X'01'
X'02'
X'03'
X'04'
X'05'
ENQUEUE
GET Message
GET N Bytes
DEQUEUE Message
WASH
PURGE All
IQPRINDC 1 1 X'80'
Release File
IQPRGENR 2 1 X'00'
X'01'
X'02'
Successful Completion
Unsuccessful Completion
Parameter List Error
IQPRDETL 3 1 X'01'
X'02'
X'03'
X'04'
X'05'
X'06'
X'07'
X'08'
X'09'
X'0A'
X'0B'
X'0C'
X'0D'
X'0E'
End of Message
Queue Empty
I/O Error
No Message Available for Wash
GET Message Function Not Valid or
Not Performed
Consecutive GETs Issued
DEQUEUE Function Not Valid
Function Not Supported
GET N Byte Function Not Valid
Invalid Target Offset for GET
Invalid Record ID
No Block Attached On D0
Invalid QCE Address
Invalid Block Attached On D0 or
Can't Queue the Message
IQPRQCE 4 4
QCE core address
IQPRRET 8 2
Number of bytes for GET N Bytes
IQPROFF 10 2
Target offset for GET N Bytes
IQPRID 12 2
2-character record ID
IQPRPARM 14 16
User parameter area

Input Interface

The Queue Manager Input Interface is detailed in Table 22.

Table 22. Queue Manager Input Interface

Registers ECB Workarea ECB Data Levels
R1 : Parameter List Addr - IQPRM EBW - Irrelevant
EBX - Irrelevant
Protect Key of
Working Storage
  • ENQUEUE Message D0: Prime block of the message
    DD-DF: Available
    D1-DC: Reserved
  • GET Message
    D0, DD-DF: Available
    D1-DC: Reserved
  • GET N Bytes
    D0: Prime block of the message
    DD-DF: Available
    D1-DC: reserved
  • DEQUEUE Message
    D0, DD-DF: Available
    D1-DC: Reserved
  • WASH/PURGE All
    DD-DF: Available
    D0-DC: Reserved

For all queueing services, the QCE core address must be present in the parameter list. The user is responsible for initializing the QCE only before the first queueing request.

Enqueue
When the Queue Manager is started with the Enqueue function, the prime block of the message must be on data level zero (D0) of the ECB. Additional blocks should be file chained using standard AMSG format.

The user must include within the parameter list the record ID that the Queue Manager should use. Prime record attributes are used by the Queue Manager on the specified record ID. The user may also include within the parameter list a 16-byte parameter area. This area is saved by the Queue Manager and returned to the user in the QCE when the message is dequeued.

The prime block on level D0, provided by the user, is released by the Queue Manager.

Get Message
When the Queue Manager is started with the Get Message function, the message at the top of the QCE queue is returned to the user as originally enqueued. The prime block, returned by the Queue Manager, resides on data level zero (D0) of the ECB and any additional blocks are file chained using standard AMSG format. The 16-byte user parameter area is returned in the QCE.

Upon issuing the Get Message request, the user must include within the parameter list the record ID that the Queue Manager should use.

Get N Bytes
When the Queue Manager is started with the Get N Bytes function, the user must provide sufficient space within a single target core block on data level zero (D0) of the ECB. It is at this ECB location where the Queue Manager returns up to N bytes from the current message, source block, in the QCE.

The user may also specify a target offset (M bytes), within the parameter list. M indicates that the Queue Manager should start filling the target block on level zero (D0) M bytes after the 18th byte of the block. If M is equal to zero, the Queue Manager fills the target block starting at location 18.

Note:
The text is extracted from the source block starting at location 18 within the prime block and location 23 within the overflow blocks.

The Queue Manager does not impose any values within the first 18 bytes of the returned block.

Upon return, the Queue Manager places the actual number of bytes returned in the IQPRRET field of the input parameter list.

The user must include within the input parameter list the record ID that the Queue Manager should use.

If the Get N Bytes function has been used to retrieve a message, the Get Message function cannot be used for retrieving any remaining bytes of the same message. The "End of Message" return code indicates that the message has been fully dequeued.

Dequeue
When the Queue Manager is started with the Dequeue function, the previously returned message is removed from the queue. The user may also specify the Release File option with the Dequeue function. In that case, all file addresses of the previously returned message are released.

The Dequeue function must be specified between two consecutive "Get" operations.

Wash
When the Queue Manager is started with the Wash function, the QCE structure is rearranged where the previously retrieved message is positioned at the top of the QCE queue.

Purge All
When the Queue Manager is started with the Purge All function, the QCE queue becomes empty. All file addresses are released.

Output Interface

The Queue Manager Output Interface is detailed in Table 23.

Table 23. Queue Manager Output Interface

Registers ECB Workarea ECB Data Levels
  • R1 : Parm List addr - IQPRM
  • R0, R2-R7: Unchanged

EBW - Unchanged
EBX - Unchanged
Protect Key of
Working Storage
  • ENQUEUE Message D0-DC: Unchanged
    DD-DF: Unpredictable
  • GET Message
    D0: Prime block of the message
    D1-DC: Unchanged
    DD-DF: Unpredictable
  • GET N Byte
    D0: Prime block of the message
    D1-DC: Unchanged
    DD-DF: Unpredictable
  • DEQUEUE Message
    D0: Prime block of the message
    D1-DC: Unchanged
    DD-DF: Unpredictable
  • WASH/PURGE All
    D0-DF: Unchanged
    DD-DF: Unpredictable

The input/output parameter list is returned to the user upon completion of every queue service request. The Queue Manager also sets two types of indicators (general and detailed) to communicate the actions taken (or attempted) by the Queue Manager to the user as detailed in General Return Codes and Detailed Return Codes.

General Return Codes

The general indicator returns one of these results:

Detailed Return Codes