CEVENT(1)                Network Queuing Env. 3.3     Last changed: 4-13-98


NNAAMMEE
     cceevveenntt - Specifies interdependency of events in scripts or NQE
     requests

SSYYNNOOPPSSIISS
     cceevveenntt --pp [--gg _g_r_o_u_p_n_a_m_e] _n_a_m_e[==_v_a_l_u_e] [_n_a_m_e[==_v_a_l_u_e]...]]

     cceevveenntt --rr [--gg _g_r_o_u_p_n_a_m_e] [--dd _d_e_l_i_m_i_t_e_r] [--ww _s_e_c_o_n_d_s] [--zz _s_e_c_o_n_d_s]
     _n_a_m_e[==_v_a_l_u_e] [_n_a_m_e[==_v_a_l_u_e]...]]

     cceevveenntt --cc [--gg _g_r_o_u_p_n_a_m_e] [--aa] _n_a_m_e[==_v_a_l_u_e] [_n_a_m_e[==_v_a_l_u_e]...]]

     cceevveenntt --ll [--gg _g_r_o_u_p_n_a_m_e] [--aa] [--dd _d_e_l_i_m_i_t_e_r] [--ff] _n_a_m_e[==_v_a_l_u_e]
     [_n_a_m_e[==_v_a_l_u_e...]]

IIMMPPLLEEMMEENNTTAATTIIOONN
     IRIX systems

     UNICOS/mk systems

     UNICOS systems

     AIX systems

     Digital UNIX systems

     HP-UX systems

     Solaris systems

DDEESSCCRRIIPPTTIIOONN
     The cceevveenntt command lets a client script or Network Queuing System
     (NQS) request post, read, and wait for events.  Events are associated
     with the following information:

     * Group.  A group of requests or shell scripts communicates by using
       events.  The group is identified by a name that must be globally
       unique.  Group names are limited to 1023 characters.  They must
       begin with a letter and contain accepted C identifier characters.
       To specify group names, set the NNQQEE__GGRROOUUPP environment variable or
       use the --gg option.

     * Name.  Each event has a name that must be unique within its group.

     * Value.  Optionally, events may have values.  The value is an
       arbitrary string of characters.  Client commands can set this value
       when posting an event and obtain the value when reading the event.
       Values are limited to 4095 characters.

     * Other information such as the NQS originating user name, the NQS
       server, the time of the event, and so on.

     _E_x_i_t _e_v_e_n_t_s are unique events for tracking an NQS request.  If a
     request is submitted and the NNQQEE__GGRROOUUPP environment variable is set,
     NQS notifies the Network Load Balancer (NLB) when the request
     completes.  The event group name is obtained from NNQQEE__GGRROOUUPP.  The
     event name has the form EEXXIITT__$${{QQSSUUBB__RREEQQNNAAMMEE}}.  The name is derived
     from the request's name as specified by the --rr option of ccqqssuubb(1),
     which lets the event be tested without knowing the request ID.  The
     originator of the request owns the event.

     The following criteria determine access to events:

     * The user name that posts an event owns the event.

     * Anyone who knows the group name can read an event.

     * Only rroooott can read or delete all events.

     The cceevveenntt _c_o_m_m_a_n_d_s let you specify whether you want to post, read,
     clear, or list events.  The cceevveenntt _o_p_t_i_o_n_s let you specify groups,
     names, and values.

     The cceevveenntt commands are as follows:

     --pp          Posts one or more events.

     --rr          Reads a set of events.  Event values are returned as a set
                 of strings to ssttddoouutt separated by a delimiter character
                 specified by using --dd.  Events posted without an explicit
                 value are returned as <<NNOONNEE>>.

     --cc          Clears (deletes) the events in a group.  cceevveenntt clears
                 events that match only the specified names and values.
                 You can specify a set of explicit events or a set of
                 events and values.  This command is usually the last
                 command performed.

     --ll          Lists the events in a group to ssttddoouutt.

     The cceevveenntt options are as follows:

     --aa          Specifies all groups.  This option overrides any
                 environment variables or the value of --gg.  The --aa option
                 requires rroooott privileges.  You can use it only in
                 conjunction with the --cc and --ll options.

     --dd _d_e_l_i_m_i_t_e_r
                 Specifies the character used as a delimiter for event
                 strings written to ssttddoouutt.  By default, when events are
                 read, the delimiter is a colon (::); when events are
                 listed, the delimiter is a space.

     --ff          Displays full information concerning a set of events.
                 Used with --ll.

     --gg _g_r_o_u_p_n_a_m_e
                 Specifies the name of the event's group.  You are
                 validated for access to the group you specify.  If you
                 omit this option, cceevveenntt uses the value of the NNQQEE__GGRROOUUPP
                 environment variable.  The _g_r_o_u_p_n_a_m_e variable cannot
                 contain a pipe (||) symbol or be longer than 1023
                 characters.  NQS automatically passes the group name to
                 NQS requests.

     --ww _s_e_c_o_n_d_s  Specifies the interval (in seconds) to wait for an event
                 to occur.  You use this option only when you are reading
                 an event by using the --rr option.  The --ww option checks the
                 NLB database at regular intervals (see the description of
                 --zz).

     --zz _s_e_c_o_n_d_s  Specifies the interval (in seconds) between queries to the
                 NLB database.  The default is 30 seconds.  The minimum
                 interval is 15 seconds.

     _n_a_m_e[==_v_a_l_u_e]
                 Specifies a set of events.  The _n_a_m_e is limited to 1023
                 characters.  The optional _v_a_l_u_e is limited to 4095
                 characters.  This is a required operand.  You can specify
                 more than one name and associated value.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
     To specify the name of your event's group, set the NNQQEE__GGRROOUUPP
     environment variable.  If you do, you do not have to specify it on
     each command line.  If events are associated with a group, you can
     list and clear them as a group.  NQS automatically exports the value
     of the NNQQEE__GGRROOUUPP environment variable if you have set it, so you do
     not have to use the ccqqssuubb --xx option went you submit the request.

EEXXIITT SSTTAATTUUSS
     An exit status of 0 indicates success; that is, all events were read.
     An exit status of 1 indicates failure; that is, not all events were
     read.  An exit status of 2 indicates a general failure, and messages
     are sent to ssttddeerrrr.  An exit status of 3 indicates that cceevveenntt timed
     out waiting for an event to occur.

EEXXAAMMPPLLEESS
     Example 1:  To post the event TTAAPPEE__HHEERREE, use the following command:

          cevent -g mygroup TAPE_HERE

     Example 2:  The following lines in a script file submit JJOOBBBB after
     JJOOBBAA successfully completes.  It uses kksshh shell syntax.

     To name the group for the event AA__tthheenn__BB, set the NNQQEE__GGRROOUUPP
     environment variable by including the following line in the script
     file:

          export NQE_GROUP="A_then_B"

     To submit the request file jjoobbaa and name the request JJOOBBAA, include the
     following line in the script file:

          cqsub -r JOBA joba

     To read the event EEXXIITT__JJOOBBAA and to report the exit status of the
     request JJOOBBAA, include the following lines in the file:

          done_A=`cevent -g mygroup -r EXIT_JOBA`
          if (( $? != 0 )); then
          echo "No exit event posted for JOBA"
          exit 1
          fi
          echo "JOBA completed with exit status $done_A"

     To submit the next NQS request, include the following line in the
     file:

          cqsub -r JOBB jobb

SSEEEE AALLSSOO
     ccqqddeell(1), ccqqssttaattll(1), ccqqssuubb(1), nnqqee(1) for information about batch
     requests submitted from an NQE client

     nnqqeeiinnffoo(5) for information on the nnqqeeiinnffoo file

     _N_Q_E _U_s_e_r'_s _G_u_i_d_e, publication SG-2148, for more information on using
     cceevveenntt and general use of NQE

     This man page is available only online.