RXQUEUE Function

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

queuename

Delete

Queue has been deleted.
Not a valid queue name.
Queue named does not exist.
10
12
1000
Get
Set
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
- 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).
- 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.
- Any external program started inherits as its default queue the queue in use by the parent process.
Detached Processes
- 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.
- 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:
- 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.
- 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.
[Back: Queue Interface]
[Next: ]