File RXQUE.TXT                                   Ch. d'H. Nov 28, 1993
Copyright (C) 1992 Inventec Informatik AG
All rights reserved.



RXQUE  -  Queue Interface for REXX
==================================

The dynamic link library RXQUE.DLL provides FIFO queue functions
to an OS/2 REXX program. Queues with RPC (remote procedure call)
access can be used for inter-process communication between REXX
programs running on different computers in a network.

The queues supported by this module are not the same as the
external data queues of REXX or as the IPC queues of the OS/2
operating systems.



Registering the DLL with REXX
-----------------------------

Before the DLL can be used, it must be registered with the REXX
interpreter. The following REXX statements can be used to register
the DLL:

   if rxfuncquery("RXQUE")<>0 then do
      rc = rxfuncadd("RXQUE","RXQUE","RXQUE")
      if rc <> 0 then call abend "rxfuncadd of RXQUE failed, RC="rc
      end

If the file RXQUE.DLL is not in the current directory or in the
LIBPATH, the complete path name must be included.

Refer to RXDLLOS2.TXT for additional information about using this
DLL with REXX.



The <rxque> function
--------------------

The DLL is called through the external REXX routine with the same
name, <rxque>.

The <rxque> routine can be called as a function or as a routine.
Example to call <rxque> as a function:
   result = rxque(statement)
Example to call <rxque> as a routine:
   call rxque statement

The <rxque> routine has a single argument <statement> and returns
the value <result>. <result> contains either an empty string (if no
error has occured) or an error code character followed by an error
message.

<result> must be tested after each call to <rxque>. If <result> is
not empty and no error processing is done by the REXX program, an
error exit routine (i.e. <abend>) should be called.
Example:
   call rxque statement
   if result <> "" then call abend "rxque failed," result

The first character of <result> can be used to identify certain
error conditions.
Example:
   call rxque "read queue_handle=queue1 data_var=s"
   select
      when result="" then nop /* no error */
      when left(result,1)="E" then
         call abend "no data in queue"
      otherwise call abend "rxque failed," result
      end



Statements that can be passed to <rxque>
----------------------------------------

The following statements can be passed as parameters to <rxque>:

   open         open a queue
   close        close a queue
   read         read a block from a queue
   write        write a block to a queue
   clear        clear a queue

Before a queue can be used, it must be opened though <open>.
<Open> returns a queue handle that is used to identify the queue
with further statements.

When access to a queue queue is no longer needed, <close> should
be executed to release the internal buffer space allocated to the
queue. After <close> has been executed, the queue handle is no
longer valid.



Notes to the statement syntax and parameters
--------------------------------------------

- The statements have parameters in the form "keyword=value".
  These keyword parameters can appear in any order.
- Most parameters have default values that will be assumed when
  the parameter is not specified.
- A parameter value must be enclosed in single or double quotes if
  it contains blanks or special characters or if it is an empty
  string.
- Keywords names are case-independent. They can be written in
  uppercase, lowercase or mixed-case characters.
- Boolean output values are returned according to REXX conventions
  as 1 for <true> or 0 for <false>.
  Boolean input parameters can be 1, "TRUE" or "YES" for <true>,
  or 0, "FALSE" or "NO" for <false> (case-independent).

The following sections describe each statement in detail.



Statement:  open  -  open a queue
---------------------------------

<open> opens a queue. It provides a queue handle that can be used
to further identify the queue. When the queue is no longer needed,
<close> should be called.

Syntax:
   open type=id rpc_port_name=id rpc_comp_name=id rpc_method=id
        high_prio=boolean queue_handle_var=rexxx_var_name
        sem_handle_var=rexx_var_name

Parameters:
   type  -  queue type
      <type> can have the following values:
         "local":
            A local queue is created that cannot be accessed by
            threads outside the current processes.
         "rpc_server":
            A queue is created that can be accessed by other
            processes through RPC (remote procedure calls).
         "rpc_client":
            An existing remote queue is accessed through RPC
            calls. The remote queue can reside in the current
            process, in another process on the current computer,
            or in a process on another computer in the network.
      Default value for <type> is "local".
   rpc_port_name  -  RPC port name
      <rpc_port_name> specifies the RPC port name associated with
      the queue. This parameter is only used if <type> is
      "rpc_server" or "rpc_client".
   rpc_comp_name  -  RPC computer name
      <rpc_comp_name> is used if <type> is "rpc_client" to
      specify the name of the computer where the remote queue
      resides. An empty string for <rpc_comp_name> can be used to
      designate the current computer.
      The default value for <rpc_comp_name> is the empty string.
      Refer to RXRPCINF.TXT for additional information.
   rpc_method  -  RPC method
      <rpc_method> specifies the RPC method to be used. This
      parameter is only used if <type> is "rpc_server" or
      "rpc_client". The default value for this parameter is
      operating system dependent.
      If <type> is "rpc_server", <rpc_method> can contain a list
      of RPC methods, separated by blanks.
      Refer to RXRPCINF.TXT for additional information.
   high_prio  -  1 for high priority thread
      <high_prio> can be used if <type> is "rpc_server".
      If <high_prio> is 1, the internal thread that processes the
      RPC requests is given a high priority.
      Default value for <high_prio> is 0,
   queue_handle_var  -  name of REXX variable for queue handle
      <queue_handle_var> specifies the name of a REXX variable
      where the queue handle will be stored. The queue handle
      is an integer number that is used to uniquely identify the
      queue. It can be used by all threads within the current
      process.
   sem_handle_var  -  name of REXX variable for semaphore handle
      <sem_handle_var> specifies the name of a REXX variable
      where the semaphore handle associated with the queue will
      be stored. The semaphore is "reset" when the queue is empty
      and "posted" when there is data within the queue. The RXSEM
      DLL can be used to wait on the semaphore.
      This parameter can only be used with queue types "local"
      and "rpc_server". For queue type "rpc_client" the
      semaphore is not supported.
      The default value for <sem_handle_var> is the empty string,
      which means that the semaphore is not needed.

Example:
   call rxque "open type=rpc_server rpc_port_name=test_queue",
         "queue_handle_var=queue1 sem_handle_var=queue1_sem"
   if result <> "" then call abend result
   say "the queue handle is" queue1



Statement:  close  -  close a queue
-----------------------------------

<close> closes a queue. This releases internal memory blocks
that are allocated with the queue. After <close> has been
executed, the queue handle is no longer valid and must not be
used any more.

Syntax:
   close queue_handle=nr

Parameters:
   queue_handle  -  queue handle
      <queue_handle> is the queue handle associated with the
      queue to be closed.

Example:
   call rxque "close queue_handle="queue1
   if result <> "" then call abend result



Statement:  read  -  read a block from a queue
----------------------------------------------

<read> is used to read a data block from the queue. If the queue is
empty, <result> returns the error code "E" followed by an error
message, and the REXX variable designated by <data_var> is set to
the empty string.

Syntax:
   read queue_handle=nr data_var=rexx_var_name

Parameters:
   queue_handle  -  queue handle
      <queue_handle> is the handle associated with the queue.
   data_var  -  name of REXX variable for block data
      <data_var> specifies the name of a REXX variable where
      the block data is to be stored.

Error codes:
   The following error conditions can be intercepted by testing
   <left(result,1)>:
      "E"  -  end of data
         No more data blocks can be read from the queue because
         the queue is empty.

Example:
   call rxque "read queue_handle="queue1 "data_var=data"
   select
      when result = "" then
         say "the block data is:" data
      when left(result,1) = "E" then
         say "the queue is empty"
      otherwise call abend result
      end



Statement:  write  -  write a block to a queue
----------------------------------------------

<write> is used to write a data block to the queue. The block
is written in FIFO (first-in-first-out) mode.

Syntax:
   write queue_handle=nr data_var=rexx_var_name

Parameters:
   queue_handle  -  queue handle
      <queue_handle> is the handle associated with the queue.
   data_var  -  name of REXX variable containing the block data
      <data_var> specifies the name of a REXX variable that
      contains the data value of the block to be written.

Example:
   data = "Hello"
   call rxque "write queue_handle="queue1 "data_var=data"
   if result <> "" then call abend result



Statement:  clear  -  clear a queue
-----------------------------------

<clear> clears the queue contents.

Syntax:
   clear queue_handle=nr

Parameters:
   queue_handle  -  queue handle
      <queue_handle> is the handle associated with the queue.

Example:
   call rxque "clear queue_handle="queue1
   if result <> "" then call abend result
