amarquee.library/QFreeSession           amarquee.library/QFreeSession

   NAME
    QFreeSession - Closes the given connection to an AMarquee server.

   SYNOPSIS
    #include 

    LONG QFreeSession(struct QSession * session)

   FUNCTION
    Closes the given AMarquee connection, terminates the
    associated TCP handling thread, and cleans up.

   NOTE
    You MUST QFreeSession every session that you created with
    any of the QNew*Session() functions, before closing 
    amarquee.library!  Otherwise, you will quickly receive a visit 
    from the Guru, as the TCP thread associated with the QSession
    tries to execute code that is no longer loaded into memory...

   INPUTS
    session - Pointer to the QSession struct you wish to free.

   RESULTS
    QFreeSession always succeeds.  However, QFreeSession returns
    a QERROR_* code describing any earlier problems--usually the
    return code is QERROR_NO_ERROR, but if there was a problem in 
    connecting this QSession, or an exceptional event (such as the 
    TCP stack shutting down) occurred, then the return value might 
    be one of the following:
         
     QERROR_NO_CLIENT_MEM - The client computer ran out of memory.
     
     QERROR_NO_TCP_STACK - Couldn't connect because the TCP stack 
                           was not running.
                           
     QERROR_HOSTNAME_LOOKUP - The name server failed to find the
                              requested host.
                              
     QERROR_ABORTED - The TCP thread received a CTRL-C signal.
                      This happens when the TCP stack is shutting
                      down (at least under AmiTCP), or if the user 
                      is monkeying around with system monitors.  ;)

     QERROR_NO_SERVER - The requested host refused the TCP connection,
                        most likely because an AMarquee server was not
                        installed properly on that machine.
                        
     QERROR_NO_TCPSERVER - The requested host refused the TCP connection,
                        most likely because there was no server installed
                        on the given port on that machine.

     QERROR_NO_INETD - QNewServerSession detected that InetD was
                       not what invoked the user program.

     QERROR_ACCESS_DENIED - The AMarquee server program refused to accept 
                            the connection.
     
    This return value is for informational purposes only; no specific
    actions are required based on the value returned.

   EXAMPLE
    struct QSession * s;
    
    if (s = QNewSession("example.server.com", 2957, "ExampleProgram"))
    {
      LONG err;
      
      /* ... do stuff with the session here ... */
      
      /* ... */
      
      err = QFreeSession(s);
      
      if (ret != QERROR_NO_ERROR)
        printf("Error connecting session: %s\n",QErrorName(err));
    }

   AREXX NOTES
    Note that it is *critical* that your script call this function 
    for each active QSession, before the script terminates!  Otherwise,
    the connection threads will hang around and probably crash the
    computer.  The best way to make sure that all QSessions are freed
    is to use ARexx's "signal on" exception handling to clean up.

   AREXX EXAMPLE
    signal on break_c
    session = QNewSession('example.server.com', 2957, 'exampleRexx')
    if (session > 0) then do
      /* ... */
    break_c:
      call QFreeSession(session)
      end

   SEE ALSO
    QNewSession, QNewSessionAsync, QNewHostSession, QNewServerSession