The WRITE command writes one or more items to a specified queue.
This command has the following format:
ADDRESS PPQ 'WRITE QUEUE(qname) ITEM(item)|VAR(varname)
[DATATYPE(BINARY|TEXT)]
[ITEMNUM(LAST|FIRST|itemnum)]
[WAIT(NO|YES|waittime)]'
Specifies the 1- to 16-character name of the queue (qname). The queue name can contain alphanumeric characters and any of these special characters: ! @ # $ _
The queue name cannot contain blanks.
Specifies the item to write to the queue. The item value can be either a literal string (such as "this is an item") or a simple variable name (not enclosed in quotation marks so that REXX can evaluate it).
Note: You cannot specify the ITEM operand if you specify the VAR operand.
Specifies the name of a simple or compound variable (varname) containing an item or items to write to the queue.
A trailing dot after the varname value (as in varname.) specifies a compound variable, where varname.0 contains the number of items to write, and varname.1, varname.2, and so on, each contain an item to write. If you specify a compound variable containing more than one item, the WRITE command locks the specified queue temporarily, writes all items to the queue contiguously, and then unlocks the queue.
Note: You cannot specify the VAR operand if you specify the ITEM operand.
(Optional) Specifies which type of data translation should be used. Valid DATATYPE values are:
Automatically translates the data between EBCDIC and ASCII to match the requirements of the receiving system. This value is most useful when you want to send text strings between z/OS and Windows.
Specifies that no data translation should occur.
Note: The BINARY format is faster and should be used for all data, including text, if all systems that communicate through PPQs use the same character set.
Default: BINARY
(Optional) Specifies the starting item to write to the queue.
Assume that the specified queue contains count number of items and that you want to write n items to the queue. Valid ITEMNUM values are:
Starts the write operation from the end of the queue. The first item written to the queue is item number count+1 and succeeding items are numbered count+2, count+3, and so on through count+n. This is the default method for writing to the queue.
Starts the write operation from the beginning of the queue. The current item number 1 in the queue becomes item number 1+n after n items are written.
Starts the write operation from somewhere in the middle of the queue. The WRITE command writes n items ahead of an item (specified by itemnum) that already exists in the queue (so that the current itemnum becomes itemnum+n after n items are written).
Note: The starting item that you specify must exist or must be the count+1 item in the queue; specifying an itemnum value beyond the end of the queue generates an error.
Default: LAST
(Optional) Specifies what the command does if it cannot execute immediately. For example, the queue may be in use or locked by another REXX program. Valid WAIT values are:
Returns a nonzero return code (RC) value immediately. For information about what happens when a command does not execute successfully, see the chapter on using program-to-program queues in the Administrator Guide.
Waits indefinitely while blocking the current REXX program until the queue becomes available.
Specifies the number of seconds to wait (up to 100000) while blocking the current REXX program. Fractional values (such as 1.5) are valid.
Default: NO
Usage Note:
When writing to a remote queue, especially using the TCP/IP transport, it is possible to receive return code 4520 (queue not found), indicating errors when the queue exists on the remote machine. These errors can occur if remote host network response times are slow or inconsistent. To alleviate this condition, use the following sample to code a function around the read request to detect the problem and recover from it:
WRITERMTPPQ:
/*
********************************************************************
* THIS FUNCTION WILL WRITE A PPQ REMOTE QUEUE WITH TIMEOUT. *
********************************************************************
* EXAMPLE CALL: RC = WRITEPPQ('RMTQ', 4*60, 'DATATYPE(BINARY)') *
* RETURNS: RC FROM PPQWRITE *
* NOTES: FOR LOCAL QUEUE, USE PPQWRITE WAIT() PARAMETER IN PLACE OF*
* THIS ROUTINE. *
*********************************************************************
*/
QUEUE = ARG(1) /* QUEUE NAME */
TIMEOUT = ARG(2) /* TIME OUT IN SECONDS */
WRITE_PARMS = ARG(3) /* OTHER PPQWRITE PARMS */
/* DEFAULT 3 MINUTE TIME OUT */
IF TIMEOUT = '' THEN TIMEOUT = 3*60
/* ENSURE WAIT PARM */
IF POS('WAIT(',WRITE_PARMS) = 0
THEN WRITE_PARMS = 'WAIT(1)' WRITE_PARMS
/* ENSURE DATATYPE PARM */
IF POS('DATATYPE(',WRITE_PARMS) = 0
THEN WRITE_PARMS = 'DATATYPE(TEXT)' WRITE_PARMS
/* START TIMER */
X = TIME('R')
/* LOOP UNTIL QUEUE FOUND, TIME OUT, OR ERROR */
DO UNTIL TIME('E') > TIMEOUT
ADDRESS 'PPQ' 'WRITE QUEUE('QUEUE')' WRITE_PARMS
IF RC <> 4520 THEN LEAVE
END
RETURN RC
|
Copyright © 2012 CA Technologies.
All rights reserved.
|
|