Introduction | Language Structure | IB Statements | File System | Index |
Winsock
Gateway
Overview
The Winsock gateway provides a way for Internet Basic applications to communicate over the Internet or an intranet using industry-standard application-layer protocols such as HTTP, SMTP, and FTP.
This gateway is built on the foundation of Windows Sockets, which is a simple Application Program Interface (API) to the network-programming interface of Microsoft Windows. It is based on the “socket” paradigm first popularized in the Berkeley Software Distribution (BSD) of UNIX. The Comet Winsock gateway uses the Winsock Version 1.1 functions, on behalf of the Internet Basic application, to implement network communications between the client and server.
Basic Concepts
The
Socket
The basic building block for communication is the socket. A socket is an endpoint of communication between two communicating processes, such as the client-server model. The Winsock gateway manages the socket data structures internally, on behalf of the Internet Basic application, and presents each socket/connection as the logical unit number (lun) on which the Winsock gateway was opened.
The Client
The client process is the network application establishing the connection. It does so by requesting a connection with a network computer on a given port number. Each network computer has 64K ports, numbered from 0 to 65,535, and there may be a limitation on the number of simultaneous connections a given network computer may have active at any given time.
The Server
The server process is a network application that listens for one or more connections at the local computer (localhost) on a given port. Once the server process accepts a given connection request, bi-directional full-duplex communication is established between the two network applications.
The Connection
A connection is established when the client process successfully connects with a server process. This is done from the Internet Basic application by issuing one or more commands to the Winsock gateway using the CONTROL statement. Once the connection is established, reads and writes are performed on the connection using PRINT and INPUT statements.
The Protocol
The Winsock gateway uses the TCP transport protocol. Connections using other transport protocols, such as UDP and IPX are not available to users of the Winsock gateway. TCP provides a connection-oriented transport that guarantees delivery of each transmission packet, and is the most widely used transport protocol in use on the Internet. Through it, a vast number of network protocols are implemented, such as FTP, SMTP, POP3, TELNET, and HTTP, to name a few. Any of these may likewise be implemented from an Internet Basic application using the Winsock gateway.
Configuring the Winsock Gateway
In order to use the Winsock gateway, you must configure it. For
example, here is the entry you would need to add to your INI configuration
file:
[GATEWAYS]
Gateway = 3,0;
This entry defines one Winsock gateway, which is identified as a Type 3
gateway with a sub type of 0. Since this is the first gateway listed, it
assumes the name "G00."
It's possible, and sometimes necessary, to configure more than one
Winsock gateway. For example:
[GATEWAYS]
Gateway = 3,0;
Gateway = 3,0;
In this example, there are two gateways, "G00" and
"G01" resectively.
For more information about configuring gateways, see the SYSGEN.
The Winsock gateway is opened using the OPEN statement. The DSTAT function may be used on Comet systems with multiple gateways in determining when the correct gateway has been located.
Where the name of the gateway is known, the gateway is simply opened. For example:
OPEN (1) "G03" EXCP =
ErrorHandler
Where the name of the gateway is not known, the DSTAT function is used to query each possible gateway to identify who’s type is 3. See the Winsock gateway subroutine for some sample code.
Controlling
the Winsock Gateway
Once the gateway is opened, commands are issued to control the nature of the connection through the Winsock gateway lun using the CONTROL statement. Responses to these commands are read on the same lun using INPUT statements immediately following the CONTROL statement. The STS function may be used to determine the status of the connection and other aspects of the Winsock gateway.
The following controls are available:
The Internet Basic program initiates communication as a client process by requesting a connection with a given server process using the “CONNECT” control. The Internet Basic application then waits (execution is blocked) at an INPUT statement following the CONTROL statement for the connection to complete. Once the connection is established, the “+OK” string is returned, and the application may then use the connection for sending and receiving data. If an error occurs attempting to establish the connection, the “–ERR” string is returned. If the connection is not completed after 60 seconds (default), an exception occurs.
An Internet Basic application may also “listen” for connections as a server process, and connect with client processes, by issuing the “LISTEN” control. Once listening, the application may then wait for connection notification using one of two methods. It may either block at an INPUT statement waiting for an incoming connection, or poll the status of the connection by using the STS function. The blocked INPUT call has a timeout of 300 seconds (default) after which the “–ERR” string is returned. The application continues to wait for a connection by entering another blocked INPUT call, looping after each timeout until either a connection is established (indicated when the “+OK” string is returned), or the application chooses to abort the operation with a “CLOSE” control. Alternatively, the STS function may be called from a processing loop waiting for Connection Status to show “Connected.” The default timeouts for the client and server connections may be changed using the “TIMEOUT” control. The connection is closed using the “DISCONNECT” control.
Once the connection is established, sending data is accomplished using the PRINT statement. Likewise, receiving data uses the INPUT statement. The target lun is the same as that opened on the Winsock gateway. As with other Internet Basic applications running in Comet, a maximum sending and receiving limitation of 1024 bytes is applicable.