![[About]](r:\html\rexxabout.gif)
![[Toc]](r:\html\rexxtoc.gif)
0.9b (c) 1995 Peter Childs
Use the RxQueue function in a REXX program to create and delete queues and to set and query their names. The first parameter determines the function, the entire function name must be specified but the case of the function parameter is ignored.
Syntax:
>>--RXQUEUE(-+--"Create"--+-------------+-+-)-----><
| +-,queuename -+ |
+---"Delete"-- queuename ----+
+---"Get"----- newqueuename -+
+---"Set"----- newqueuename -+
Parameters:
Create Creates a queue with the name, queuename (if
specified); if no name is specified, then REXX will
provide a name. Returns the name of the queue in either
case.
Delete Deletes the named queue; returns 0 if successful, a
nonzero number if an error occurs; the possible return
values are:
0 Queue has been deleted.
5 Not a valid queue name.
9 Queue named does not exist.
10 Queue is busy; wait is active.
12 A memory failure has occurred.
1000 Initialization error; check file OS/2.INI
Get Returns the name of the queue currently in use.
Set Sets the name of the current queue to newqueuename and
returns the previous name of the queue.
Example: Sample Queue in a REXX Procedure
/* */
/* push/pull WITHOUT multiprogramming support */
/* */
push date() time() /* push date and time */
do 1000 /* lets pass some time */
nop /* doing nothing */
end /* end of loop */
pull a b . /* pull them */
say 'Pushed at ' a b ', Pulled at ' date()
time() /* say now and then */
/* */
/* push/pull WITH multiprogramming support */
/* (no error recovery, or unsupported env tests */
/* */
newq = RXQUEUE('Create') /* create a unique queue */
oq = RXQUEUE('Set',newq) /* establish new queue */
push date() time() /* push date and time */
do 1000 /* lets spend some time */
nop /* doing nothing */
end /* end of loop */
pull a b . /* get pushed info */
say 'Pushed at ' a b ', Pulled at ' date() time() /* tell user */
call RXQUEUE 'Delete',newq /* destroy unique queue created */
call RXQUEUE 'Set',oq /* reset to default queue (not required)*/
Special Considerations
1. External programs that must communicate with a REXX procedure by
means of defined data queues can use the default queue or the
session queue, or they can receive the data queue name by some
interprocess communication technique. This could include parameter
passing, placement on a prearranged logical queue, or use of normal
OS/2 Inter-Process Communication mechanisms (for example, pipes,
shared memory or IPC queues).
2. Named queues are available across the entire system; therefore, the
names of queues must be unique within the system. If a queue named
os2que exists and this function is issued:
newqueue = RXQUEUE('Create', 'os2que')
a new queue is created and the name is chosen by REXX. This new
name is returned by the function.
3. Any external program started inherits as its default queue the queue
in use by the parent process.
Detached Processes
1. Detached processes will access a detached session queue that is
unique for each detached process. Note, however, that this detached
session queue is not the same as the session queue of the starting
session.
2. REXX programs that are to be run as detached processes cannot
perform any SAY instructions or any PULL or PARSE PULL instructions
that involve terminal I/O. However, PULL and PARSE PULL instructions
that act on a queue are permitted in detached processes.
Multi-Programming Considerations
This data queue mechanism differs from OS/2 standard API queueing in the following ways:
1. The queue is NOT owned by a specific process, and as such any
process is entitled to modify the queue at any time. The operations
that effect the queue are atomic, in that the resource will be
serialized by the subsystem such that no data integrity problems can
be encountered.
However, synchronization of requests such that two processes,
accessing the same queue, get the data in the order it was placed on
the queue is a user responsibility and will not be provided by the
subsystem support code. This selector is owned by the calling
application code and must be freed by the caller using DosFreeSeg.
2. A regular OS/2 IPC queue is owned (created) by a specific process.
When that process terminates, the queue is destroyed. Conversely,
the queues created by the RxQueue('Create', queuename) call will
exist until EXPLICITLY deleted. Termination of a program or
procedure that created a private queue does not force the deletion
of the private queue. Any data on the queue when the process
creating it terminates will remain on the queue until either the
queue is deleted (by way of the REXX function call RxQueue('Create',
queuename) or until the data is read.
Data queues must be explicitly deleted by some procedure or program (not necessarily the creator). Deletion of a queue with remaining items, destroys those items. If a queue is not deleted, it will be lost and cannot be recovered except by randomly attempting to access each queue in the defined series.
Inf-HTML End Run - Successful