![[Company Logo Image]](images/logo.gif){kind=logo}
![[Home]](images/bhome.gif){kind=small}
![[What's New]](images/bnews.gif){kind=small}
![[Feedback]](images/bfeed.gif){kind=small}
![[Documentation]](images/docs.gif){kind=small}
Overview
Creating a Server Port
Connecting to a Server Port
Reading and Writing Packets
Error and Event Trapping
Connection Status
Connection Control
Sample Code
TCP/IP communications in SBW consists of connections made between Server and Client processes. To start communications the Server process creates a "Server" or "Listening" port by issuing an OPEN statement.
The Client process then "connects" to the Server port by creating a "Client" port by issuing another OPEN statement. If there is no Server port active at the specified address this OPEN statement will return an error.
In both cases, the user specifies the maximum packet length to be used during communications as the RECL parameter in the OPEN statement. The apparent record length is adjusted as needed later during the communications process.
Sending and Receiving data packets is done by using the standard WRITE and READ statements. Data packets may be sent in either formatted or unformatted form by choosing to use the "USING" clause of the READ and WRITE statements.
When the need for communications ends the Server and Client ports are closed via the CLOSE statement.
Various status information may be gathered about the communications ports via Machine$ functions as described below. In addition, various control functions may also be performed by Machine$ functions.
In order to create a "Server" or "Listening" port it is necessary to provide two pieces of information: 1) the local port number, and 2) the maximum allowed packet length, and 3) the number of client connections to permit. These values are presented as keywords in an OPEN statement that is used to create the port.
LOCALPORT=PortNumber
The local port number identifies the port number on which to listen. The Client process will need to specify the same port number in order to send or receive data to the Server process on the file number being opened.
A "PortNumber" is a 16 bit integer value that identifies the TCP/IP port on which to listen. Many established servers (FTP, HTTP, etc.) use standard port assignments and this should be taken into account when selecting a port for use in your own application so that port assignments do not conflict. A large list of currently assigned ports can be found here. [Typically you will not run into much trouble if you keep your port number somewhere above 2 or 3 thousand.]
MAXPACKET=PacketLength
The valid range for "PacketLength" is currently 1 to 32224 bytes. The default value is 16384 or the RECL value if that is specified.
RECL=RecordLength
The valid range for "RecordLength" is currently 1 to 32224 bytes. The default value is 16384 or the MAXPACKET value if that is specified.
CONNECTIONS=ConnectionMax
Connections are established when a Client process opens a Client port and specifies this machine and LOCALPORT. The first connection will be handled using the file number specified in this OPEN statement. Subsequent connections will automatically open the first available file number greater than on this OPEN statement using the same maximum packet length.
In order to create a "Client" port it is necessary to provide three pieces of information: 1) the name or TCP/IP address of the remote host computer, 2) the remote port number, and 3) the maximum allowed packet length. These values are presented as keywords in an OPEN statement that is used to create the port.
REMOTEHOST=HostName
A "HostName" is a name or 32 bit TCP/IP address that identifies the remote computer to be accessed.
A host name may be of the form "SERVER" or "RALPH" or it may be a fully articulated internet name such as "microsoft.com" or "freedomdata.com". In all of the above cases, using the Microsoft "PING" command (such as "PING SERVER") will decode and show the host name into a 32 bit TCP/IP address. If PING doesn't decode the host name, neither will the OPEN statement.
A 32 bit TCP/IP address is represented as a text string of the form "a.b.c.d" where a, b, c, and d are 8 bit integer values (0 to 255 inclusive).
REMOTEPORT=PortNumber
The remote port number identifies the port number to which to connect. The Server process must have specified the same port number in order to prepare for a Client process to connect.
A "PortNumber" is a 16 bit integer value that identifies the TCP/IP port on which to listen. Many established servers (FTP, HTTP, etc.) use standard port assignments and this should be taken into account when selecting a port for use in your own application so that port assignments do not conflict. A large list of currently assigned ports can be found here. [Typically you will not run into much trouble if you keep your port number somewhere above 2 or 3 thousand.]
MAXPACKET=PacketLength
The valid range for "PacketLength" is currently 1 to 32224 bytes. The default value is 16384 or the RECL value if that is specified.
RECL=RecordLength
The valid range for "RecordLength" is currently 1 to 32224 bytes. The default value is 16384 or the MAXPACKET value if that is specified.
When sending a packet it is necessary to specify the length of the packet. The packet length is taken from the current record length associated with the file number. This record length will be reset automatically when a packet is received to match the actual length of the packet received so if the process is alternately sending and receiving packets it may be necessary to set the record length / packet length each time a packet is sent.
The record length and packet length are set using a Machine$ function:
Machine$("RLN(FileNumber)=RecordLength")
The "FileNumber" and "RecordLength" are either numbers or variables containing the active file number and desired record length. Once the packet length is set the packet is sent by issuing a write statement:
WRITE #FileNumber:Parameter1, Parameter2, etc. or
WRITE #FileNumber,USING FormSpec:Parameter1, Parameter2, etc.
The "FormSpec" is as usual the line number of a FORM statement or a string expression that evaluates to FORM control parameters.
To receive a packet issue a READ statement.
READ #FileNumber:Parameter1, Parameter2, etc. or
READ #FileNumber,USING FormSpec:Parameter1, Parameter2, etc.
If no packet is waiting the READ statement will generate an EOF trap. The file's record length will be set to the length of the packet read. It is also possible to reprocess a received packet by using a REREAD statement.
Just as with record oriented file IO the use of the unformatted READ and WRITE commands (i.e., without a USING clause) requires that the parameter types and count match between the WRITE and the corresponding READ.
A new error trap type has been defined for use with TCP/IP processing. It is activated by issuing the statement:
ON _TCPIP GOTO Destination
SBW can be configured using the Machine$ functions described in Connection Control to trap on the following events:
Connection Established from Client
Connection Closed
Packet Received
During the execution of the "Destination" error trap service routine all further _TCPIP traps are blocked. For proper operation the service routine must be terminated with a Machine$("TCPIP.EventEnd=return-info") request to unblock further _TCPIP traps and resume normal program execution at the point of interruption. See Connection Control below for further information.
Various information about the current status of TCP/IP connections can be acquired through the use of the following Machine$ functions:
Machine$("TCPIP.Event")
Return a description of the event that triggered the last "ON _TCPIP GOTO" trap. The description consists of an 8 character event type and a 4 digit file number associated with the event. The event types defined are "Connect", "Close", and "Packet".
Machine$("TCPIP.EventExit=trap-info")
Return from the event service routine to the normal program flow.
Machine$("TCPIP(FileNumber).PacketCount")
Return the number of data packets waiting on the connection associated with the file "FileNumber." This requests returns a numeric string suitable for evaluation with the VAL function.
Machine$("TCPIP(FileNumber).State")
Return the connection status of the connection associated with the file "FileNumber." The return values are: "Not Connected", "Listening", and "Connected".
Machine$("TCPIP(FileNumber).Type")
Return the connection type of the connection associated with the file "FileNumber." The return values are: "Server" to indicate a Server Port, "Client" to indicate a Client Port, and a blank string to indicate not a TCPIP related file number or file number not open.
Control of error/service routine trapping and termination is controlled by the following Machine$ functions:
Machine$("TCPIP.EventExit=trap-info")
Return from the event service routine to the normal program flow. The service routine should save the "trap-info" as its first operation capturing the return value from Machine$("error-put"). The execution of the TCPIP.EventExit request will restore the program flow to its saved position, clear the current TCPIP.Event value and then trigger the next _TCPIP trap if there are any more events waiting for servicing.
Machine$("TCPIP.EventTraps=enablebits")
Control the triggering of _TCPIP event traps. The "enablebits" parameter is computed by adding together the following bit flags:
Hex
Decimal
Meaning
0x01
1
Connection Established
0x02
2
Connection Closed
0x04 4 Packet Received Machine$("TCPIP.EventTraps")
Return the string value of the current numeric "enablebits" code.
An example of a Client / Server application is provided here.