RXWAIT.html

RXWAIT USER GUIDE

Use the WAIT function to wait for one or more CMS Event Signals.

CMS Event Signals are generated by various components of the CMS operating system in response to interrupts taken by the Virtual Machine. The following CMS Event Signals, which may be managed by WAIT, are native to the CMS operating system:

VMACCOUNT

- Generated at the generation of an accounting record.

VMCONINPUT

- Generated for unsolicited attention interrupts from the virtual console.

VMCON1ECB

- Generated when data is available from the virtual console.

VMCPIC

- Generated at a CPI Communications interrupt.

VMERROR

- Generated when a program check or abend occurs.

VMERRORCHILD

- Generated when a child process abends.

VMIPC

- Generated at the arrival of an Inter Process Communication (IPC) message on a queue.

VMPOSGNL

- Generated in response to POSIX signals.

VMPROCESSEND

- Generated at normal program termination.

VMSFSASYNC

- Generated when an asynchronous Shared File System (SFS) request completes.

VMTIMER

- Generated at the expiration or cancellation of a timer (see the REXX function package TIMER below).

VMTIMECHANGE

- Generated when time zone change occurs.

VMTRACE

- Generated at the production of a trace record.

For more information about these events and signals, please refer to CMS Application Multitasking (SC24-5766).

In addition to the events generated by CMS components, the following REXX function packages also generate Event Signals that may be managed by WAIT:

MSG

- Used to manage messages received by a Virtual Machine, generates the VMMSG Event Signal on message arrival. For more information, refer to the REXX function package documentation.

RDR

- Used to manage RDR signals, generates the VMRDR CMS Event Signal each time a file arrives in the virtual reader. For more information, refer to the REXX function package documentation.

SOCKET

- Used to manage TCP/IP sockets, generates the VMSOCKET Event Signal. For more information, refer to REXX/VM Reference (SC24-5770) and CMS Application Development Reference (SC24-5762).

TIMER

- Used to manage timer events, generates the VMTIMER CMS Event Signal to indicate the completion or cancellation of a timer. For more information, refer to the REXX function package documentation.

Each of these function packages provide facilities to control the resources they manage, including the ability to wait for the signals they generate. However, if you wish to wait on any of the CMS Event Signals and one or more function package Signals concurrently, then the wait functions of any of the above packages will not suffice. Instead, the function packages must be invoked to generate the necessary signals, and then low level operating system calls to CMS Event Management must be made to intercept and process the signals.

Alternatively, the WAIT function may be invoked to make these low level operating system calls (via the Callable Service Library or CSL) on your behalf.

The format of the WAIT function call is:

 __________________________________________________________________
|                                                                  |
|                                                                  |
|                                                                  |
|  >>-- call WAIT -- arguments --------------------------------->  |
|                                                                  |
|  Arguments:                                                      |
|                                                                  |
|  >------+--------------------------------------------+-------<<  |
|         |                                            |           |
|         |  +--------------------------------------+  |           |
|         |  |                                      |  |           |
|         |  V                                      |  |           |
|         +-----+--------------------------------+--+--+           |
|         |     |                                |     |           |
|         |     +-- eventname -------------------+     |           |
|         |     |                                |     |           |
|         |     +-- subfunction( parameters ) ---+     |           |
|         |                                            |           |
|         +-- PURGE -----------------------------------+           |
|                                                                  |
|__________________________________________________________________|

Where:

eventname

- Is one of the CMS Event names.

subfunction ( parameters )

- Is any function package invocation that include a SIGnal parameter. The WAIT function package ALWAYS requires the SIGnal parameter to be specified. For the specific syntax of a function, refer to the appropriate function package documentation.

PURGE

- Is a reserved word (not case sensitive) that indicates that all outstanding events are to be purged from the signal queue.

The format of the WAIT result is:

 ________________________
|                        |
|     rc event data      |
|________________________|

Where:

rc

- Numeric return code indicated by the event or subfunction.

event

- Is the reporting event, subfunction, or signal name.

data

- Is an optional character string returned by the reporting event or subfunction.

Example 1 (cut/paste and try this example):

/* RXWAIT Demo 1. */
   address command
 
   do forever
      parse value wait("msg(sel,all,sig)",,
                       "timer(int def,0:5,sig shortime)",,
                       "timer(int def,0:20,sig longtime)",,
                       "vmconinput",
                      ) with rc code text 1 d
 
   select
   when code = 'SHORTIME' then do                /* d = 0 SHORTIME */
      d = d date() time()
      end
   when code = 'LONGTIME' then do                /* d = 0 LONGTIME */
      d = d date() time()
      end
   when code = 'VMCONINPUT' then do            /* d = 0 VMCONINPUT */
      parse upper pull input 1 cmd .
      d = d input
      end
   otherwise /* d = 0 MSG Mon 26 Jan 1998-01-26 11:24:16 SMSG BROWN HELLO */
      parse upper var d rc code day dd mon date time tz type orig cmd
      end
 
   say d
   if cmd = 'STOP' then leave
   end

Example 2 is a sample of how SOCKET events should be handled:

/* RXWAIT Demo 2. */
   address command
 
   .
   .
   .
 
   do forever
      parse value wait(,
         "msg(select, smsg, signal)",,
         "socket(select, read * write" g.0EnabledForWrite", signal)",,
         ) with rc flih iqe
 
      select
 
      when rc  = 0 & flih = 'SOCKET'  then do
         parse var iqe . 1 'READ' readsocs 'WRITE' .,
                       . 1 'WRITE' writesocs 'EXCEPTION' .,
                       . 1 'EXCEPTION' exceptionsocs
 
         do i = 1 to words(writesocs)
            call SocWriteSub word(writesocs,i)
            end
 
         do i = 1 to words(readsocs)
            CurSoc = word(readsocs,i)
            if CurSoc = g.0PrimeSoc then call SocNew
            else if wordpos(CurSoc, g.0EnabledForIdent) > 0 then call SocIdent CurSoc
            else call SocRead CurSoc
            end
         end
 
      when flih = 'MSG' then call OperatorCommand subword(iqe, 7)
 
      otherwise
         say 'Error:' rc flih iqe
         end
      end
 
   .
   .
   .

Example 3 demonstrates a client that SMSGs a request to a server then waits for either an SMSG response or a timeout:

/* RXWAIT Demo 3. */
   address command
 
   call msg "count"
   call wait "purge"
 
   'CP SMSG SERVER ECHO HELLO'
 
   parse value wait("msg(select,smsg,signal)",,
                    "timer(int def,0:5,signal)",
                   ) with rc code text 1 d
 
   if code = "TIMER" then return -1
   else do
      call timer "cancel"
      call wait
      return 0 text
      end

Example 3 demonstrates the following important points:

The statement 'call msg "count"' is required for the first invocation of this exec, and causes message trapping to be enabled. If this statement was omitted, any response arriving before the first 'msg("select"...)' function call would be missed.
The statement 'call wait "purge"' purges any signals that may have been created in response to previous invocations of this exec. If a message signal and a timer signal arrive simultaneously, it is possible for one of these to remain on the queue for the next invocation.
The statements 'call timer "cancel"' cancels any outstanding timer requests, and ensures ill that no timer signal will be queued following the completion of this exec.

Return codes and messages:

0     Normal completion.
1     Logic error, qualifying-text.
2     Function parameter omitted.
3     Function parameter "%s" is invalid.
4     Stack overflow at location hexaddr.
5     CSL(routinename) error r/c=returncode, reason=reasoncode.
2001  Wait for what?
2002  Subfunction "%s" is invalid.
2003  Subfunction "%s" syntax error.
2004  Subfunction "%s" is not callable.
2005  %s - function response does not contain the function name.
2006  Too many subfunctions.
2007  Too many subfunction arguments.
2008  "SIGNAL" parameter omitted on "%s" subfunction call.

VMACCOUNT	- Generated at the generation of an accounting record.
VMCONINPUT	- Generated for unsolicited attention interrupts from the virtual console.
VMCON1ECB	- Generated when data is available from the virtual console.
VMCPIC	- Generated at a CPI Communications interrupt.
VMERROR	- Generated when a program check or abend occurs.
VMERRORCHILD	- Generated when a child process abends.
VMIPC	- Generated at the arrival of an Inter Process Communication (IPC) message on a queue.
VMPOSGNL	- Generated in response to POSIX signals.
VMPROCESSEND	- Generated at normal program termination.
VMSFSASYNC	- Generated when an asynchronous Shared File System (SFS) request completes.
VMTIMER	- Generated at the expiration or cancellation of a timer (see the REXX function package TIMER below).
VMTIMECHANGE	- Generated when time zone change occurs.
VMTRACE	- Generated at the production of a trace record.

MSG	- Used to manage messages received by a Virtual Machine, generates the VMMSG Event Signal on message arrival. For more information, refer to the REXX function package documentation.
RDR	- Used to manage RDR signals, generates the VMRDR CMS Event Signal each time a file arrives in the virtual reader. For more information, refer to the REXX function package documentation.
SOCKET	- Used to manage TCP/IP sockets, generates the VMSOCKET Event Signal. For more information, refer to REXX/VM Reference (SC24-5770) and CMS Application Development Reference (SC24-5762).
TIMER	- Used to manage timer events, generates the VMTIMER CMS Event Signal to indicate the completion or cancellation of a timer. For more information, refer to the REXX function package documentation.

eventname	- Is one of the CMS Event names.
subfunction ( parameters )	- Is any function package invocation that include a SIGnal parameter. The WAIT function package ALWAYS requires the SIGnal parameter to be specified. For the specific syntax of a function, refer to the appropriate function package documentation.
PURGE	- Is a reserved word (not case sensitive) that indicates that all outstanding events are to be purged from the signal queue.

rc	- Numeric return code indicated by the event or subfunction.
event	- Is the reporting event, subfunction, or signal name.
data	- Is an optional character string returned by the reporting event or subfunction.