sockets

TCP/IP Socket Commands

CobolScript has commands for several TCP/IP socket operations. Socket programming is very similar to file I/O, except socket programming reads from and writes to sockets instead of files. A socket is an endpoint of communication, created in software, and equivalent to a computer’s network interface.

We have provided two sample programs that, when combined, demonstrate the use of socket operations – the first program is a socket server, and the second is its client. The server program should first be run from one command prompt window, and then the client program run from another . After they have both started, you can type a string in the client window that will be sent via TCP/IP to the server. This example can easily be modified to communicate with clients and servers on different platforms simply by changing the IP address (host name) parameters.

The server program (the sample program SERV.CBL) requires the same set of TCP/IP data structures that we defined in the previously discussed DNS.CBL program, as well the following user-defined variables:

1 host_name PIC X(80).

1 socket_num PIC 9(2).

1 connected_socket_num PIC 9(2).

1 port_num PIC 9(5).

1 backlog_num PIC 9(2).

1 string_var PIC X(10).

1 receive_string PIC X(20).

1 send_string PIC X(20).

Here’s the main code. Note the order of the socket server commands (CREATESOCKET, BINDSOCKET, LISTENTOSOCKET), which is necessary set-up for the socket before a connection can be accepted using ACCEPTFROMSOCKET:

******************************************************

* This program requires that you have TCP/IP running

* on your machine.

******************************************************

MAIN.

GETHOSTNAME USING host_name.

DISPLAY `Starting Deskware Server on ` & host_name.

MOVE 1 TO socket_num.

MOVE 2 TO connected_socket_num.

CREATESOCKET USING socket_num.

DISPLAY `CREATESOCKET return code = <` & TCPIP-RETURN-CODE & `>`.

MOVE 2500 TO port_num.

BINDSOCKET USING socket_num port_num.

DISPLAY `BINDSOCKET return code = <` & TCPIP-RETURN-CODE & `>`.

MOVE 1 TO backlog_num.

LISTENTOSOCKET USING socket_num backlog_num.

DISPLAY `LISTENTOSOCKET return code = <` & TCPIP-RETURN-CODE & `>`.

DISPLAY `Waiting to accept socket connection on port ` & port_num

& `...`.

ACCEPTFROMSOCKET USING socket_num connected_socket_num.

DISPLAY `ACCEPTFROMSOCKET return code = <` & TCPIP-RETURN-CODE

& `>`.

MOVE SPACES TO receive_string.

PERFORM ACCEPT-TCPIP-CONNECTIONS UNTIL receive_string(1:4) = `STOP`.

DISPLAY `Shutting down Deskware Server`.

SHUTDOWNSOCKET USING connected_socket_num 1.

CLOSESOCKET USING connected_socket_num.

SHUTDOWNSOCKET USING socket_num 1.

CLOSESOCKET USING socket_num.

GOBACK.

ACCEPT-TCPIP-CONNECTIONS.

MOVE SPACES TO receive_string.

RECEIVESOCKET USING connected_socket_num receive_string.

DISPLAY `TCP/IP return code = <` & TCPIP-RETURN-CODE & `>`.

DISPLAY `TCP/IP return message = <` & TCPIP-RETURN-MESSAGE & `>`.

DISPLAY `This was received: ` & receive_string.

MOVE `GOT IT` TO send_string.

SENDSOCKET USING connected_socket_num send_string.

DISPLAY `TCP/IP return code = <` & TCPIP-RETURN-CODE & `>`.

DISPLAY `TCP/IP return message = <` & TCPIP-RETURN-MESSAGE & `>`.

DISPLAY `This was sent: ` & send_string.

The client program (the sample program CLIENT.CBL) requires the same set of TCP/IP data structures as defined in DNS.CBL, and also the following user-defined variables:

1 host_name PIC X(80).

1 socket_num PIC 9(2).

1 connected_socket_num PIC 9(2).

1 port_num PIC Z9999.

1 backlog_num PIC 9(2).

1 string PIC X(10).

1 receive_string PIC X(20).

1 send_string PIC X(20).

1 stop_var PIC 9.

The client code in this example assumes that the client and server programs are running on the same machine (hence the move of the loopback address to host_name).

Note the interaction points between the previous server program and this client program; the server uses ACCEPTFROMSOCKET to accept a connection initiated by the client’s CONNECTTOSOCKET statement. Once the connection is established, the server uses RECEIVESOCKET to receive the data transmitted from the client using SENDSOCKET. Once the transmission is complete, they reverse, and the server sends the string `GOT IT` back to the client as a way to confirm the data transmission. Here’s our client code:

DISPLAY `Starting Deskware Client (type STOP to exit).`.

MOVE 1 TO socket_num .

CREATESOCKET USING socket_num.

DISPLAY `CREATESOCKET return code = <` & TCPIP-RETURN-CODE & `>`.

MOVE 2500 TO port_num.

* We are using the loop back IP in this example;

* uncomment the line below and comment out the move

* to actually get the host name

* GETHOSTNAME USING host_name

MOVE `127.0.0.1` TO host_name.

DISPLAY `Your hostname is: ` & host_name.

CONNECTTOSOCKET USING socket_num host_name port_num.

DISPLAY `CONNECTTOSOCKET return code = <` & TCPIP-RETURN-CODE & `>`.

DISPLAY TCPIP-RETURN-MESSAGE.

PERFORM SEND-DATA-TO-SERVER UNTIL stop_var.

SHUTDOWNSOCKET USING socket_num 1.

CLOSESOCKET USING socket_num.

GOBACK.

SEND-DATA-TO-SERVER.

ACCEPT send_string FROM KEYBOARD

PROMPT `Data to send to port 2500: `.

SENDSOCKET USING socket_num send_string.

DISPLAY `SENDSOCKET return code = <` & TCPIP-RETURN-CODE & `>`.

DISPLAY TCPIP-RETURN-MESSAGE.

MOVE SPACES TO receive_string.

RECEIVESOCKET USING socket_num receive_string.

DISPLAY `RECEIVESOCKET return code = <` & TCPIP-RETURN-CODE & `>`.

DISPLAY `This was received: <` & receive_string & `>`.

DISPLAY `RECEIVESOCKET return code = <` & TCPIP-RETURN-CODE & `>`.

DISPLAY TCPIP-RETURN-MESSAGE.

IF send_string(1:4) = `STOP` THEN

MOVE 1 to stop_var

END-IF.

Command:

ACCEPTFROMSOCKET

Syntax:

ACCEPTFROMSOCKET USING <socket-number> <accept-socket-number>.

Description:

ACCEPTFROMSOCKET creates a new TCP/IP socket connection on accept-socket-number when a remote machine attempts to connect using a particular socket socket-number. Socket-number refers to the socket that has already been created in order to listen for a connection; when a remote computer attempts to connect on that socket, the ACCEPTFROMSOCKET command will accept the connection and create a newly connected socket on accept-socket-number.

The ACCEPTFROMSOCKET command will cause CobolScript to suspend program flow until a socket connection is successfully established with a remote computer.

After the new socket connection has been established, socket-number is freed and is ready to listen for another connection.

This command is conventionally used only on the machine that is considered to be the server in two-way socket connections.

The TCP/IP return code and return message variables are populated with standard TCP/IP return codes and messages after execution of this command. They can be examined after command execution for error-trapping purposes.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

ACCEPTFROMSOCKET USING socket_num_var

connctd_socket_num_var.

The ACCEPTFROMSOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

BINDSOCKET

CLOSESOCKET

CONNECTTOSOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

BINDSOCKET

Syntax:

BINDSOCKET USING <socket-number> <port-number>.

Description:

The BINDSOCKET command binds a socket socket-number to a specific TCP/IP port port-number on the local machine. After this command is executed , the operating system will associate port-number with socket-number.

This command is conventionally used only on the machine that is considered to be the server in two-way socket connections.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

BINDSOCKET USING socket_num_var port_num_var.

The BINDSOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

CLOSESOCKET

CONNECTTOSOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

CLOSESOCKET

Syntax:

CLOSESOCKET USING <socket-number>

Description:

The CLOSESOCKET command closes the specified TCP/IP socket connection socket-number. It should only be called after the SHUTDOWNSOCKET command has been issued, to ensure a graceful socket termination.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

CLOSESOCKET USING socket_num_var.

The CLOSESOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

BINDSOCKET

CONNECTTOSOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

CONNECTTOSOCKET

Syntax:

CONNECTTOSOCKET USING <socket-number> <ip-address> <port-number>.

Description:

The CONNECTTOSOCKET command attempts to establish a remote TCP/IP connection with the machine at ip-address using a socket socket-number and a port port-number. Ip-address can be a raw IP address or any valid host name on the network or internet that will accept the communication.

This command is conventionally used only on the machine that is considered to be the client in two-way socket connections. It requires that the remote machine accept the connection with ACCEPTFROMSOCKET or an equivalent command.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

CONNECTTOSOCKET USING socket_num_var

host_name_var

port_num_var.

The CONNECTTOSOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

BINDSOCKET

CLOSESOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

CREATESOCKET

Syntax:

CREATESOCKET USING <socket-number>.

Description:

The CREATESOCKET command creates a socket descriptor, or virtual circuit, on a TCP/IP socket socket-number. Once created, this socket descriptor can then be used with other CobolScript socket commands.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

CREATESOCKET USING socket_num_var.

The CREATESOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

BINDSOCKET

CLOSESOCKET

CONNECTTOSOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

CLOSESOCKET

Syntax:

CLOSESOCKET USING <socket-number>

Description:

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

CLOSESOCKET USING socket_num_var.

The CLOSESOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

BINDSOCKET

CONNECTTOSOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

CONNECTTOSOCKET

Syntax:

CONNECTTOSOCKET USING <socket-number> <ip-address> <port-number>.

Description:

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

CONNECTTOSOCKET USING socket_num_var

host_name_var

port_num_var.

The CONNECTTOSOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

BINDSOCKET

CLOSESOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

LISTENTOSOCKET

Syntax:

LISTENTOSOCKET USING <socket-number> <backlog-queue-length>.

Description:

The LISTENTOSOCKET command prepares a socket socket-number to accept an incoming connection. The backlog-queue-length is the number of incoming connection requests permitted to queue while accepted connections are processed.

LISTENTOSOCKET should be called prior to using ACCEPTFROMSOCKET.

This command is conventionally used only on the machine that is considered to be the server in two-way socket connections.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Command:

BINDSOCKET

Syntax:

BINDSOCKET USING <socket-number> <port-number>.

Description:

This command is conventionally used only on the machine that is considered to be the server in two-way socket connections.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

BINDSOCKET USING socket_num_var port_num_var.

The BINDSOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

CLOSESOCKET

CONNECTTOSOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

RECEIVESOCKET

Syntax:

RECEIVESOCKET USING <socket-number> <receiving-variable>.

Description:

The RECEIVESOCKET command receives the data in receiving-variable from a remotely transmitting machine, over an open socket connection using socket socket-number.

For RECEIVESOCKET to work properly, the transmitting (remote) machine must transmit the data using SENDSOCKET or an equivalent command.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

RECEIVESOCKET USING socket_num_var receive_string.

The RECEIVESOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

BINDSOCKET

CLOSESOCKET

CONNECTTOSOCKET

CREATESOCKET

LISTENTOSOCKET

SENDSOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

SENDSOCKET

Syntax:

SENDSOCKET USING <socket-number> <send-string>.

Description:

The SENDSOCKET command transmits the data in send-string over an open TCP/IP socket connection using socket socket-number.

For SENDSOCKET to work properly, the receiving (remote) machine must receive the data using RECEIVESOCKET or an equivalent command.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

SENDSOCKET USING connected_socket_num send_string.

The SENDSOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

BINDSOCKET

CLOSESOCKET

CONNECTTOSOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SHUTDOWNSOCKET

Sample Program:

SERV.CBL

Command:

SHUTDOWNSOCKET

Syntax:

SHUTDOWNSOCKET USING <socket-number> <shutdown-method>.

Description:

The SHUTDOWNSOCKET command prepares an open socket connection socket-number to be closed. SHUTDOWNSOCKET should be used prior to calling CLOSESOCKET, to ensure a graceful termination. The shutdown-method is a numeric variable or literal flag that describes how the socket will be shut down. The allowed values for shutdown-method are:

0: Receives are no longer allowed

1: Sends are no longer allowed

2: Sends and receives are no longer allowed

Normally, a shutdown-method of 1 is preferred; by using 1, the local machine will alert the remote machine that the local machine is no longer transmitting data packets, which initiates a graceful termination of the socket connection.

See the Using TCP/IP Commands section of Chapter 6, Network and Internet Programming Using CobolScript, for more information on using socket commands.

Example Usage:

SHUTDOWNSOCKET USING socket_num 1.

SHUTDOWNSOCKET USING socket_num shutdown_method.

The SHUTDOWNSOCKET command requires that the following TCP/IP variable declarations be included in your program:

1 TCPIP-RETURN-CODES.

5 TCPIP-RETURN-CODE PIC 9(07).

5 TCPIP-RETURN-MESSAGE PIC X(255).

Alternatively, include the sample file TCPIP.CPY in your program with a COPY or INCLUDE statement. This copybook includes these variable definitions.

See Also:

ACCEPTFROMSOCKET

BINDSOCKET

CLOSESOCKET

CONNECTTOSOCKET

CREATESOCKET

LISTENTOSOCKET

RECEIVESOCKET

SENDSOCKET

Sample Program:

SERV.CBL