Winsock Gateway

 

Control:          LISTEN

 

Syntax:           result-string = CONTROL(lun,"LISTEN [port]")

 

Description:    The LISTEN control waits for and automatically establishes a connection with a foreign association.

 

The port is an optional parameter that specifies the port at the local machine (localhost) on which LISTEN waits for connections. The port may be specified as either the name of the service by which the connection will be used, or as an actual decimal port number. Service names are automatically translated to the port number used by the service in accordance with RFC 1060. Windows Sockets uses the SERVICES text file found in the Windows directory when translating service names to port values. When the port parameter is omitted, port numbers are dynamically assigned by Windows Sockets. In either case, the port number assigned the LISTEN control is learned using the STS function for the open Winsock gateway.

                       

                        Connection notification is provided using one of two methods:

 

·         Method one waits at an INPUT following the LISTEN control. If no connection is requested by a client process before the TIMEOUT elapses, an exception on the INPUT redirects program execution back to the INPUT, repeating until a connection is established, or the application chooses to abort the operation.

 

·         Method two submits the listen request, followed by STS queries, waiting for the Connect Status to indicate a positive connection.

 

                        Unless the TIMEOUT value is changed by the programmer, the default TIMEOUT on an INPUT waiting for the connection request is 300 seconds (5 minutes).

 

                        LISTEN mode remains in effect until either a connection is established, or a QUIT control is issued.

 

Return values:

 

                        If no errors occur preparing the LISTEN request, once a connection is established, LISTEN returns +OK followed by the network address and port number of the peer to which it has connected.  Otherwise, it returns
–ERR followed by detailed information on the nature of the error. These values are returned in the result-string.

 

Exceptions:     EXCP 10   Comet timed out waiting for a connection request.  The default timeout is 300 seconds, unless changed using the TIMEOUT command.

                        EXCP 29   Winsock returned a network error when attempting to establish the connection.  The error is formatted and placed in the DOS PATH field of QENDITOR and QERRLOG.  It may also be queried from the WS Gateway using the GETERROR command.

                        EXCP 34   CONNECT was called while a connection was already active on the WS Gateway LUN.

                        EXCP 45   A syntax error was detected parsing the LISTEN command string passed in the FILE()CTL.

 

Example 1:     ! ** NOTIFY METHOD ONE **

            OPEN (1) "G03"          ! the Winsock Gateway

            Result$ = CONTROL(1,"LISTEN 12345")

            IF SUB(Result$,1,1) NE "+" GOTO ErrorHandler

            Repeat:

                INPUT(1) A$, EXCP = Repeat

 

Example 2:     ! ** NOTIFY METHOD TWO **

            OPEN (1) "G03"          ! the Winsock Gateway

            Result$ = CONTROL(1,"LISTEN 12345")

            IF SUB(Result$,1,1) NE "+" GOTO ErrorHandler

            Status$ = STS(1)

            DO WHILE SUB(Status$,1,1) ne "1"

                Status$ = STS(1)  ! may get paused

            LOOP

 

Example 3:     LENGTH 21 & LOCAL MyAddr$

            LENGTH 63 & LOCAL Status$

 

            ! ** DYNAMIC LISTEN PORT **

            OPEN (1) "G03"

            Result$ = CONTROL(1,"LISTEN")

            IF SUB(Result$,1,1) NE "+" GOTO ErrorHandler

            Status$ = STS(1)

            MyAddr$ = SUB(Status$,31,21)

            PRINT(0) "Waiting for connection on ";MyAddr$

            DO WHILE SUB(Status$,1,1) NE "1"

                Status$ = STS(1)  ! may get paused

            LOOP