amarquee.library/QSetOp           amarquee.library/QSetOp

   NAME
    QSetOp - Create or update a data item with a new buffer of data.

   SYNOPSIS
    #include 

    LONG QSetOp(struct QSession * session, char * path, void * buffer, ULONG bufferLength)

   FUNCTION
    This function allows you to upload to the server data you wish to
    be made public.  The data sent is stored as a simple buffer of bytes,
    and can thus be any data type you wish to send.

    This function may also be used in direct client-to-client
    connections (as created via QNewSession and QNewHostSession),
    in which case the data in the arguments is received directly by
    the other client.
    
   NOTE
    You may only set nodes in your own directory.

    This function is preferable to QStreamOp when the data
    you are posting is absolute, and it matters more that the other client 
    programs see the latest revision of the data as soon as possible, than to 
    have them always receive every update of the data.  Also, this function 
    is more memory-efficient that QStreamOp.
    
    This operation will immediately clear any streaming data buffers
    that were previously in use for the given node.  Thus, if you
    were previously using QStreamOp on a node and then 
    want to do a QSetOp on that same node, it is a good idea to do a
    QGo(QGOF_SYNC) and wait for the sync QMessage first, 
    before execting the QSetOp, so that none of your streamed updates 
    will be lost.

   INPUTS
    session      - The session to wish to send the set op to.
    path         - The regular path of the node you wish to create
                   or update.  Wildcards are not allowed here.
    buffer       - A pointer to the first byte of the data buffer you
                   wish to upload, or NULL if you wish to delete an
                   existing node specified by "path".
    bufferLength - The length of the data buffer, in bytes.
    
   RESULTS
    Returns the assigned ID number of the set operation on success,
    or 0 on failure.  Any server-side errors will be sent asynchronously
    as QMessages.

   EXAMPLE
    LONG transID;
    LONG data[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};    
    
    /* Upload the data array into a node named "data" in our home dir */
    if (transID = QSetOp(session, "data", data, sizeof(data)))
       printf("Set op succeeded, was given id #%li\n",transID);
    else 
       printf("Set op failed.  (no memory?)\n");

   AREXX NOTES
    In ARexx, the fourth argument is optional.  If it is not specified,
    then the length of the third argument will be computed automatically
    so that the entire ARexx string is sent.  (that is, it defaults to
    length(data)+1.  Note that if you specify the fourth argument to
    be a value of less than that, the first (n) bytes of the string
    will be stored on the server as an unterminated character array)

   AREXX EXAMPLE
    transID = QSetOp(session, 'myName', 'Fred')
    if (transID = 0) then say "Oops, operation failed"

   SEE ALSO
    QGo, QStreamOp