amarquee.library/QSubscribeOp           amarquee.library/QSubscribeOp

   NAME
    QSubscribeOp - Start watching the given data items for updates.

   SYNOPSIS
    #include 

    LONG QSubscribeOp(struct QSession * session, char * wildpath, LONG maxBytes)

   FUNCTION
    This function tells the AMarquee server that your client has
    a continuing interest in the given data item(s) specified in
    "wildpath".  When any items meeting the pattern specified in
    "wildpath" are created, changed, or deleted, you will be sent
    QMessages reflecting their new contents.
    (Nodes being deleted will result in you receiving a QMessage
    with qm_Data being NULL.)
    
   NOTE
    This function will not cause any data to be sent to you until
    a change in the data's state occurs.  If you are just starting 
    up your session and wish to get the full current state of the
    data, you should probably send a QGetAndSubscribeOp
    instead.
    
    If a client whose data you are watching disconnects, you will
    get messages indicating that each node you are watching has
    been deleted.  (If you want to know for sure that a disconnection
    is taking place and not just a bunch of manual deletions, watch
    the client's root node (e.g. "/progName/clientName")--this node
    will only ever be deleted when the client disconnects.
    
   INPUTS
    session  - The session to send the subscribe op to.
    wildpath - The regular path name indicating which items you are
               interested in.  Regular expressions are allowed.
    maxBytes - Works similarly to the maxBytes argument in QGetOp.
               If the data portion of entries sent to you is longer
               than "maxBytes", it will be truncated to maxBytes
               bytes.  Set this to -1 to allow any size data to be
               sent.
  
   RESULTS
    Returns the assigned ID number of the subscribe operation on
    success, or 0 on failure.  Any server-side errors will be sent
    asynchronously as QMessages.  Data QMessages resulting from this
    command may continue to be sent indefinitely, or until you cancel
    your subscription with QClearSubscriptionOp.

   EXAMPLE
    LONG transID;
    
    /* Tells AMarqueed to send us a message whenever a program
       named ExampleProgram changes a node named data in its home dir */
    if (transID = QSubscribeOp(session, "/#?/ExampleProgram/data", -1))
       printf("Subscribe op succeeded, was given id #%li\n",transID);
    else 
       printf("Subscribe op failed.  (no memory?)\n");

   AREXX NOTES
    In ARexx, the third argument is optional.  If it is not specified,
    it defaults to -1 (e.g. no size limit).

   AREXX EXAMPLE
    transID = QSubscribeOp(session, '/#?/ExampleProgram/data')
    if (transID = 0) then say "Oops, operation failed"

   SEE ALSO
    QGo, QGetAndSubscribeOp, QClearSubscriptionOp