amarquee.library/QNewSession           amarquee.library/QNewSession

   NAME
    QNewSession - Creates a new connection to an AMarqueed server. (V50)

   SYNOPSIS
    #include 

    struct QSession * QNewSession(char * hostname, LONG port, char * progname, struct TagItem *taglist)
    struct QSession * QNewSessionTags(char * hostname, LONG port, char * progname, ULONG tag1, ...)

   FUNCTION
    Creates a new TCP-handling thread and attempts to connect it
    to the specified AMarqueed server.

   NOTE
    This function is synchronous--it will not return until either
    a TCP connection has been made to the remote host, or the attempt 
    has failed.  If the connection fails, this function will return
    NULL with no side effects.

    If a non-NULL QSession is returned, it must be QFreeSession'd 
    before you close the amarquee.library. 

   INPUTS
    hostname - The IP name of the computer to connect to.  (e.g.
               foo.bar.com)
    port     - The port to connect on.  Port 2957 is the "official"
               AMarqueed port.
    progname - A null-terminated string indicating the name
               the client program wishes to use.  If another
               client from your host has already registered 
               progname, the server for that client will close 
               its connection and quit so that your client program 
               will still be uniquely addressable.
    taglist  - A pointer to a tag list. For usable tags see .
               You must set this to NULL if you don't want to use any tags.

   TAGS
   QSESSION_ERRORCODEPTR - Can optionally be used to find out why a connection failed.
   The argument is a pointer to an int that will hold the error code. (V50)

   QSESSION_SHAREDMSGPORT - Can optionally be used to specify a shared message port to
   bind the session to. This must have been created with QCreateSharedMessagePort(). (V52)

   RESULTS
    On success, returns a pointer to a QSession struct that should be
    passed to the other functions in this API.  The QSession struct
    also contains a pointer to an exec.library MsgPort that your program
    should Wait() on and GetMsg() from to receive QMessages from the
    TCP thread.  Returns NULL if a connection could not be established.

   EXAMPLE
    struct QSession * s;
    
    if (s = QNewSession("example.server.com", 2957, "ExampleProgram"))
       printf("Connection to example.server.com:2957 was successful\n");
    else
       printf("Connection failed.\n");

   AREXX NOTES
    For ARexx, the return value of this method is a string representation 
    of the pointer to the session struct.  If the returned value is equal 
    to zero, then the call failed.  Otherwise, use the return value as a 
    handle to pass to other amarquee.library functions.
    
    Note that instead of calling Wait() and GetMsg(), you will want
    to use amarquee.library's GetNextQMessage function to receive
    incoming QMessages.

    Tags cannot be used.
     
   AREXX EXAMPLE
    session = QNewSession('example.server.com', 2957, 'ExampleScript')
    if (session > 0) then say "Connection was successful!"
                     else say "Connection failed!"
       
   NOTE
   This function was modified in amarquee.library v.50. The v.49 version had the
   same functionality but without the last argument, struct TagItem *taglist. I.e tags
   could not be used. Use the AMarquee49 pragmas and protos if your program have
   to work with amarquee.library v.49, though it's not recommended.
 
   SEE ALSO
    QNewSessionAsync, QNewHostSession, QNewServerSession, QFreeSession