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:


- Generated at the generation of an accounting record.


- Generated for unsolicited attention interrupts from the virtual console.


- Generated when data is available from the virtual console.


- Generated at a CPI Communications interrupt.


- Generated when a program check or abend occurs.


- Generated when a child process abends.


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


- Generated in response to POSIX signals.


- Generated at normal program termination.


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


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


- Generated when time zone change occurs.


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


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


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


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


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



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


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



- Numeric return code indicated by the event or subfunction.


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


- 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)",,
                      ) with rc code text 1 d
   when code = 'SHORTIME' then do                /* d = 0 SHORTIME */
      d = d date() time()
   when code = 'LONGTIME' then do                /* d = 0 LONGTIME */
      d = d date() time()
   when code = 'VMCONINPUT' then do            /* d = 0 VMCONINPUT */
      parse upper pull input 1 cmd .
      d = d input
   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
   say d
   if cmd = 'STOP' then leave

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
      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)
         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
      when flih = 'MSG' then call OperatorCommand subword(iqe, 7)
         say 'Error:' rc flih iqe

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

Example 3 demonstrates the following important points:

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.