amarquee.library/QDetachSession           amarquee.library/QDetachSession

   NAME
    QDetachSession - Removes the messaging connection between the given
                     QSession and the user process that created it.

   SYNOPSIS
    #include 

    BOOL QDetachSession(struct QSession * session, ULONG flags)

   FUNCTION
    When a QSession is created, it is implicitely coupled with
    (a.k.a. "attached to") the process that created it.  That is to 
    say, only the process that created the QSession will be able to 
    successfully receive QMessages from that QSession.  However, 
    there are some cases where it would be convenient to "hand off" 
    a QSession from one process to another.  In order to do this, 
    you must first call QDetachSession on the session in the process
    that created it, then call QReattachSession on the session 
    in the process you wish to hand the QSession to.

   NOTE
    This function requires v47 of amarquee.library.

    This function is only useful if you want to pass QSessions
    from one process to another.  Most AMarquee programs won't
    need to use it.
    
    Once you have detached a QSession, there are special rules
    you must follow.  These rules are:
    
      - Only the process that is attached to a QSession may
        call QDetachSession() on it.
        
      - The qMsgPort field of a detached QSession is NULL.
        As such, you may not Wait() or GetMsg() or otherwise
        access the QSession's qMsgPort field in any way (until
        you reattach the QSession, anyway).  When the QSession
        is reattached, the qMsgPort field will have a new value
        (so don't store the old value, as it becomes invalid
        when QDetachSession() is called)
      
      - An unattached QSession may be freed by any process.
        Attached QSessions may only be freed by the process they
        are attached to.  Attempting to free a QSession that
        is attached to another process will most likely hang
        or crash your process.
        
      - All AMarquee functions (except GetNextQMessage in ARexx)
        may be called on a detached QSession, but you won't be 
        able to get results (i.e. QMessages) back from it until 
        the QSession has been reattached.
      
      - All QMessages that the detached QSession generates will
        be stored in an internal queue, and will be made available
        when the QSession is reattached.  That is to say, events
        will not be "dropped" just because a QSession is detached.
        (which means if you leave a QSession detached for a long time,
        it may build up quite a large queue of stored QMessages
        and eat up lots of memory)
      
      - It's (still) not safe to let multiple processes accessing a 
        QSession simultaneously.  That is, the Q*Op() methods should
        be serialized, and the Wait()'ing and GetMsg()'ing should
        only be done by the one thread that the QSession is attached
        to.

    Finally, detaching or reattaching a QSession to a process
    is a synchronous operation, so if the TCP thread is busy
    shovelling lots of data around, it may take a while for
    this function to return.
     
   INPUTS
    session - Pointer to the QSession struct you wish to detach.
    flags   - Reserved for future use.  Always set to 0L for now.
    
   RESULTS
    Returns TRUE on success, FALSE on failure.  (Failure occurs
    if there is not enough memory, or if the QSession was already
    detached)

   EXAMPLE
    See the included program AMarqueeDebugMultiThread.c for
    a full working example of how to use this function.
   
    struct QSession * s;
    
    /* ... In thread one ... */
    if (s = QNewSession("example.server.com", 2957, "ExampleProgram"))
    { 
      /* ... do stuff with the session here ... */
      
      if (QDetachSession(s, 0L))
      {
        GiveSessionToAnotherThread(s);
      }
      else printf("Uh oh, QDetachSession failed!\n");      
    }
    
    ------------------
    
    /* ... In thread two ... */
    s = GetSessionFromFirstThread();   /* using message passing or whatever */
    if (QReattachSession(s, 0L))
    {
       /* ... Do stuff with the QSession ... */
       QFreeSession(s);
    }
    else printf("Oh dear, QReattachSession failed!\n");

   AREXX NOTES
    QDetachSession() is implemented for ARexx, although I have
    yet to see a multithreaded ARexx script.  Perhaps it might
    come in handy for passing a QSession from one ARexx script
    to another, though.
    
    The ARexx function returns 1 on success, 0 on failure.
    
      if (QDetachSession(session) == 0) then
        say "uh oh, session detach failed!"
      end

   SEE ALSO
    QReattachSession, QFreeSession