amarquee.library/QSysMessageOp           amarquee.library/QSysMessageOp

   NAME
    QSysMessageOp - Send a system message to one or more other clients.

   SYNOPSIS
    #include 

    LONG QSysMessageOp(struct QSession * session, char * hosts, char * message)

   FUNCTION
    This function allows you to send a text message to all clients
    who have requested QPRIV_GETSYSMESSAGE access.  Note that
    in order to use this function, your client must have QPRIV_SENDSYSMESSAGE
    access.
     
    Your message will be sent to every host that matches the regular 
    expression specified in the "hosts" argument, as long as the
    client hav QPRIV_GETSYSMESSAGE access.
    
    The regular expression in "hosts" should be of the form "/foo/bar".
    
    If no other clients received your message (either because no clients 
    matching your specification existed, or because they do not have
    QPRIV_GETSYSMESSAGE access), you will be receive a QERROR_UNPRIVILEGED 
    QMessage notifying you of this.  You will also receive a 
    QERROR_UNPRIVILEGED QMessage if you did not have QPRIV_SENDSYSMESSAGE
    access when you called this function.
    
    When another client sends your client a QSysMessageOp, the QMessage you
    receive will have a qm_ID of zero, and the qm_Path field will contain 
    the path of the home node of the message's sender (e.g. "/host/prog").
    The qm_Status field will be set to QERROR_SYS_MESSAGE.
    The qm_Data field will contain the ASCII text of the message body.
    
   NOTE
    By default, all clients have system messaging access turned off.  So
    in order to send a system message to a client, that client must have
    first allowed it with QRequestPrivilegesOp.
    
    Data passed with this function will be streamed, so you do not
    have to worry about synchronization.
    
   INPUTS
    session      - The session to wish to send the message op to.
    hosts        - A regular expression indicating which set of clients
                   you wish to send the message to.  It must be of the
                   form "/foo/bar".  For example:  to send your message
                   to all clients named "Bob", do "/#?/Bob".
    message      - A pointer to the text string you wish to transmit.  
                   If NULL is specified, a one-byte empty string
                   ("") will be sent.
    
   RESULTS
    Returns the assigned ID number of the message operation on success,
    or 0 on failure.  Any server-side errors will be sent asynchronously
    as QMessages.

   EXAMPLE    
    /* Send a system message to all clients who are listening for it. */
    if (transID = QSysMessageOp(session, "/#?/#?", "System shutting down!  Log off now.");
       printf("SysMessage op succeeded, was given id #%li\n",transID);
    else 
       printf("SysMessage op failed.  (no memory?)\n");

   AREXX EXAMPLE
    transID = QSysMessageOp(session, '/#?/#?', 'System shutting down!')
    if (transID = 0) then say "Oops, operation failed"

   SEE ALSO
    QGo, QRequestPrivilegesOp, QMessageOp