OS/2 Procedures Language 2/REXX


Inf-HTML [About][Toc][Index] 0.9b (c) 1995 Peter Childs


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            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