home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / vxtech04.zip / VXTECH04.TXT
Text File  |  1994-05-03  |  9KB  |  230 lines
  1. ============================================================================
  2.  VX-REXX Tech Note #4:
  3.                                    Introduction to REXX Queues
  4.  
  5.                                                             March 09, 1994
  6.  
  7.                      Applies to all versions of VX-REXX
  8.                      
  9. ----------------------------------------------------------------------------
  10.  
  11.                                                        Paul Prescod
  12.                                                        WATCOM International
  13.  
  14. ============================================================================
  15.  
  16. Abstract
  17. --------
  18.  
  19. REXX queues are the standard interprocess communication mechanism between
  20. REXX programs.  REXX queues can also be used to pipe the output of 
  21. external programs into a REXX program. This technical note explains when
  22. to use queues, as well as how to create and destroy them.  There is 
  23. more advanced information on the queue interface in the "REXX Information"
  24. reference in the VX-REXX folder.  This document is intended to be used as
  25. an introduction and companion to that reference.
  26.  
  27. When To Use A REXX Queue
  28. ------------------------
  29.  
  30. Use a REXX queue any time you want to communicate between processes.  
  31. Examples of this would be communication between REXX programs running at
  32. the same time, passing the output of the OS/2 "set" command to a REXX 
  33. program, or sending information from a C program to a REXX program.  Queues 
  34. are system-wide so any REXX application, whether it is Presentation 
  35. Manager based or text mode, foreground, background or detached, can 
  36. access them.
  37.  
  38. Creating a Queue
  39. ----------------
  40.  
  41. Queue maintanence is done using the RXQueue function.  Queues have names,
  42. just like VX-REXX objects or OS/2 files.  Usually, you will let
  43. REXX choose the queue name:
  44.  
  45. Qname = RXQueue( "Create" )
  46.  
  47. Now the variable Qname contains the string that represents the queue, the
  48. queue's name.  This name is usually something along the lines of
  49. "S20Q0363406248." There is nothing special about this string.  It is just
  50. a quasi-random string of letters chosen by REXX used to identify this
  51. queue.  REXX is will always choose a name that is unique system-wide, so you
  52. can be sure that no one else is using that queue.  You can pass that
  53. queue name to any other REXX program, and the two programs can  use the
  54. queue for communications.  You might pass it via a command line
  55. argument, an already existing queue, or a file on disk.
  56.  
  57. On the other hand, it might be difficult to communicate the queue name
  58. to another program (e.g. one which is already running).  In this case, you 
  59. would want to choose the name of the queue yourself, so you can hard code it 
  60. into both programs when you write them.
  61.  
  62.     Creating Named Queues
  63.     ------------------
  64. To create a new queue named "Fred", you would say:
  65.  
  66. Qname = RXQueue( "Create", "Fred" )
  67.  
  68. If "Fred" did not already exist, REXX will create it, and return the word 
  69. "Fred" (so the variable Qname now contains the word "Fred").
  70.  
  71.  
  72. What if Fred Already Exists?
  73. ----------------------------
  74.  
  75. If "Fred" did already exist, REXX will create a new queue, choose its
  76. name, and return it.  Since you have already made the decision to use the
  77. Fred queue, you should immediately delete the new queue.
  78.  
  79. Be careful, though,  since Fred was already created, there may be another
  80. program using that queue.  Since it is unlikely that two different
  81. developers would choose the same queue name (unless you actually use a
  82. queue named "Fred", which is now world famous!), it is likely that the
  83. queue was created by another copy of your program. Either an earlier 
  84. instance of your program did not destroy the queue, or two instances of 
  85. your program are running concurrently.  Be careful!  It is very easy to 
  86. cross messages.
  87.  
  88.  
  89. Using REXX Queues
  90. -----------------
  91.  
  92. A system can have as many queues as it has memory for, and any particular
  93. REXX program can access as many of them as it wants.  All it has to know
  94. are the names of the queues that it is going to access.  At any one time,
  95. however, there is only one queue that is considered "current". The current
  96. queue is the only one that you can work with.  To use multiple queues, you
  97. change the current queue to each of them in turn.  You can change 
  98. the current queue to any queue whose name you know using the following 
  99. command:
  100.  
  101. oq = RXQueue( "Set", "Fred" )
  102.  
  103. Now the current queue is set to the queue "Fred."  The queue name could also
  104. be stored in a variable:
  105.  
  106. qname = "Fred"
  107. oq = RXQueue( "Set", qname )
  108.  
  109. Often, instead of setting the variable to a constant, you will use the
  110. variable returned by the "Create" command (above).
  111.  
  112. qname = RXQueue( "Create" )
  113. oq = RXQueue( "Set", qname )
  114.  
  115.  
  116. Sending Data To Queues
  117. ----------------------
  118. From REXX
  119. ---------
  120. REXX programs use the "Push" and "Queue" commands to put data on the
  121. current queue.  See the "REXX Information" reference for more information
  122. on these functions.
  123.  
  124.    From the Command Line
  125.    ---------------------
  126.    There is a program in the \OS2 directory called RXQUEUE that allows you to
  127.    send the output of a program to a REXX queue.  Though this command has the
  128.    same name as the RXQueue function, they are in fact different.  RXQUEUE
  129.    is a filter, so you must send data through an OS/2 pipe.  For more 
  130.    information on pipes, see the section called "pipe, using a" in the 
  131.    Master Help Index.  RXQUEUE has the following syntax:
  132.    
  133.    RXQUEUE [Queuename] [/FIFO|/LIFO|/CLEAR],
  134.    
  135.    Queuename is the name of a REXX queue that exists.  
  136.  
  137.    The /CLEAR parameter removes all text from the queue.
  138.    The /LIFO flag stacks items Last In First Out (like push() ) 
  139.    the /FIFO flag queue items First In First Out (like queue() )
  140.    
  141.    If the queue name is omitted, RXQUEUE uses the contents of the 
  142.    environment variable "RXQUEUE". When the queue name is omitted and 
  143.    the "RXQUEUE" environment variable does not have a value, the RXQUEUE 
  144.    program uses the "SESSION" queue.  For more information on the "SESSION" 
  145.    queue, read the "REXX Information" reference.
  146.  
  147.    Since commands that can be executed from the command line can also be
  148.    executed from REXX, you can use this technique to pipe the output of an
  149.    external program into your REXX program. For instance, here is a small 
  150.    function which collects the data from the "set" command and sends it to 
  151.    a ListBox.
  152.  
  153.     /* Set2LB_1: Collects output of set and then puts it in a ListBox
  154.       called LB_1  (if LB_1 does not exist you will get an error message)
  155.     */
  156.     Set2LB_1:
  157.        'set | rxqueue'
  158.        do while queued()>0
  159.        call VRMethod "LB_1", "AddString", linein("QUEUE:")
  160.        end
  161.     return
  162.    
  163.    This example does not specify a queue because it uses the default queue,
  164.    the "SESSION" queue.  For more information on the queued() function used
  165.    above, see the "REXX Information Reference."  For more information on
  166.    the RXQueue function, see the "Procedures Language 2/REXX Reference" in
  167.    the OS/2 2.0 Technical Library.
  168.  
  169.    From C
  170.    ------
  171.    There is an undocumented API for accessing a REXX queue from a C program.
  172.    These functions are prototyped in the REXXSAA.H header file. This API is
  173.    not likely to change, but just in case it does, there is also  a
  174.    documented way to write to a REXX queue.  All you have to do is write a
  175.    small REXX program that uses the PUSH command to a buffer in memory, and
  176.    use the RexxStart function to execute it.  There is more information on
  177.    the RexxStart function in the RexxApi.inf reference.
  178.  
  179.  
  180. Getting Data From a Queue
  181. ---------------------------
  182. Data is retrieved from the queue using the Pull and Linein("QUEUE:")
  183. functions.  These are well documented in the "REXX Information" reference
  184. in the VX-REXX folder.
  185.  
  186. Destroying REXX Queues
  187. ----------------------
  188. You should destroy any REXX Queue you create.  Once the name of the queue is
  189. lost, there is no way to destroy it. To destroy a queue named "Fred", you 
  190. would say:
  191.  
  192. rc = RXQueue( "Delete", "Fred" )
  193.  
  194. To destroy a queue whose name is in a variable, qname, you would say:
  195.  
  196. rc = RXQueue( "Delete", qname )
  197.  
  198. There is more information about destroying queues and analysing the return
  199. codes in the "REXX Information" reference.
  200.  
  201. Example Program
  202. ----------------
  203.  
  204. /* Parent.cmd : Simple program showing how to use a REXX Queue */
  205. /* ----------
  206.                 Calls a VX-REXX program with a queue name as a parameter
  207.         and then "executes" any commands the VX-REXX program queues.
  208.         Good for modifying the environment of the parent session of
  209.         a VX-REXX program.
  210. */
  211.  
  212. qname = rxqueue("Create")
  213.  
  214. oldqname = rxqueue("Set",qname)
  215.  
  216. /* Call a VX-REXX program with the queue name as the first parameter
  217. */
  218. 'project.exe' qname
  219.  
  220. do while queued()>0
  221.  
  222.     /* Get data out of the queue and execute it as a command
  223.     */
  224.     data = linein("QUEUE:")
  225.     data
  226.  
  227. end
  228.  
  229.  
  230.