amarquee.library/QReattachSession           amarquee.library/QReattachSession

   NAME
    QReattachSession - Creates a messaging connection between the 
                       given detached QSession and calling process.

   SYNOPSIS
    #include 

    BOOL QReattachSession(struct QSession * session, ULONG flags)

   FUNCTION
    Once a QSession has been detached from its process, this
    function may be called by any process in order to create
    a messaging association between the calling process and the 
    QSession.
    
    After this function returns (successfully), the QSession
    is no longer detached, and is operable by the calling
    process, just as if the calling process had created the
    QSession itself.  In particular, the QSession's qMsgPort 
    field will no longer be NULL: rather, it will be set to point to 
    a MsgPort that the calling process can then Wait() on for QMessages.

   NOTE
    This function requires v47 of amarquee.library.
    
    When a QSession is first created, it is already attached
    to its creating process.  Thus, 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.

    See QDetachSession for the list extra rules that apply
    to detached QSession's.
    
    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 reattach.
    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
    attached to a process)

   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 (QReattachSession(s, 0L))
      {
        GiveSessionToAnotherThread(s);
      }
      else printf("Uh oh, QReattachSession 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
    QReattachSession() 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 (QReattachSession(session) == 0) then
        say "uh oh, session reattach failed!"
      end

   SEE ALSO
    QDetachSession, QFreeSession