FILENAME Statement, SOCKET Access Method | SAS 9.1 Language Reference Dictionary, Volumes 1, 2 and 3

Enables you to read from or write to a TCP/IP socket

Valid: anywhere

Category: Data Access

Syntax

 [  1]

FILENAME fileref SOCKET hostname : portno < tcpip-options >;

 [  2]

FILENAME fileref SOCKET : portno SERVER < tcpip-options >;

Arguments

fileref

is a valid fileref.
Tip: The association between a fileref and an external file lasts only for the duration of the SAS session or until you change it or discontinue it with another FILENAME statement. You can change the fileref for a file as often as you want.

SOCKET

specifies the access method that enables you to read from or write to a Transmission Control Protocol/Internet Protocol (TCP/IP) socket.

hostname : portno

is the name or IP address of the host and the TCP/IP port number to connect to.
Tip: Use this specification for client access to the socket.

: portno

is the port number to create for listening.
Tip: Use this specification for server mode.
Tip: If you specify :0 , the system will choose a number.

SERVER

sets the TCP/IP socket to be a listening socket, thereby enabling the system to act as a server that is waiting for a connection.
Tip: The system accepts all connections serially ; only one connection is active at any one time.
See Also: The RECONN= option description on page 1201 under TCPIP-Options .

TCPIP-Options

BLOCKSIZE= blocksize

where blocksize is the size of the socket data buffer in bytes.
Default: 8192

ENCODING= encoding-value

specifies the encoding to use when reading from or writing to the socket. The value for ENCODING= indicates that the socket has a different encoding from the current session encoding.
When you read data from a socket, SAS transcodes the data from the specified encoding to the session encoding. When you write data to a socket, SAS transcodes the data from the session encoding to the specified encoding.
For valid encoding values, see Encoding Values for SAS Language Elements in SAS National Language Support (NLS): User s Guide .

LRECL= lrecl

where lrecl is the logical record length.
Default: 256

RECFM= recfm

where recfm is one of three record formats:

is fixed record format. Thus, all records are of size LRECL with no line delimiters. Data are transferred in image (binary) mode.

is stream record format.

Tip: Data are transferred in image (binary) mode.

Interactions: The amount of data that is read is controlled by the current LRECL value or the value of the NBYTE= variable in the INFILE statement. The NBYTE= option specifies a variable equal to the amount of data to be read. This amount must be less than or equal to LRECL.

See Also: The NBYTE= option on page 1227 in the INFILE statement.

is variable record format (the default).

Tip: In this format, records have varying lengths, and they are transferred in text (stream) mode.

Tip: Any record larger than LRECL is truncated.

Default: V

RECONN= conn-limit

where conn-limit is the maximum number of connections that the server will accept.
Explanation: Because only one connection may be active at a time, a connection must be disconnected before the server can accept another connection. When a new connection is accepted, the EOV= variable is set to 1. The server will continue to accept connections, one at a time, until conn-limit has been reached.

TERMSTR= eol-char

where eol-char is the line delimiter to use when RECFM=V. There are three valid values:

CRLF

carriage return (CR) followed by line feed (LF).

LF

line feed only (the default).

NULL

NULL character (0x00).
Default: LF
Restriction: Use this option only when RECFM=V.

Details

The Basics A TCP/IP socket is a communication link between two applications. The server application creates the socket and waits for a connection. The client application connects to the socket. With the SOCKET access method, you can use SAS to communicate with another application over a socket in either client or server mode. The client and server applications can reside on the same machine or on different machines that are connected by a network.

As an example, you can develop an application using Microsoft Visual Basic that communicates with a SAS session that uses the TCP/IP sockets. Note that Visual Basic does not provide inherent TCP/IP support. You can obtain a custom control (VBX) from SAS Technical Support (free of charge) that allows a Visual Basic application to communicate through the sockets.

[ 1]	Using the SOCKET Access Method in Client Mode In client mode, a local SAS application can use the SOCKET access method to communicate with a remote application that acts as a server (and waits for a connection). Before you can connect to a server, you must know:

the network name or IP address of the host machine running the server.
the port number that the remote application is listening to for new connections.

The remote application can be another SAS application, but it doesn t need to be. When the local SAS application connects to the remote application through the TCP/IP socket, the two applications can communicate by reading from and writing to the socket as if it were an external file. If at any time the remote side of the socket is disconnected, the local side will also automatically terminate.

[ 2]

Using the SOCKET Access Method in Server Mode When the local SAS application is in server mode, it remains in a wait state until a remote application connects to it. To use the SOCKET access method in server mode, you need to know only the port number that you want the server to listen to for a connection. Typically, servers use well-known ports to listen for connections. These port numbers are reserved by the system for specific server applications. For more information about how well-known ports are defined on your system, refer to the documentation for your TCP/IP software or ask your system administrator.

If the server application does not use a well-known port, then the system assigns a port number when it establishes the socket from the local application. However, because any client application that waits to connect to the server must know the port number, you should try to use a well-known port.

While a local SAS server application is waiting for a connection, SAS is in a wait state. Each time a new connection is established, the EOV= variable in the DATA step is set to 1. Because the server accepts only one connection at a time, no new connections can be established until the current connection is closed. The connection closes automatically when the remote client application disconnects. The SOCKET access method continues to accept new connections until it reaches the limit set in the RECONN option.

Examples

Example 1: Communicating between Two SAS Applications Over a TCP/IP Socket

This example shows how two SAS applications can talk over a TCP/IP socket. The local application is in server mode; the remote application is the client that connects to the server. This example assumes that the server host name is hp720.unx.sas.com , that the well-known port number is 5000, and that the server allows a maximum of three connections before closing the socket.

Here is the program for the server application:

 filename local socket ':5000' server reconn=3;     /*The server is using a reserved */     /*port number of 5000.           */  data tcpip;     infile local eov=v;     input x ;     if v=1 then        do;             /* new connection when v=1 */           put 'new connection received';        end;     output;  run;

Here is the program for the remote client application:

 filename remote socket 'hp720.unx.sas.com:5000';  data _null_;     file remote;     do i=1 to 10;        put i;     end;  run;

CRLF	carriage return (CR) followed by line feed (LF).
LF	line feed only (the default).
NULL	NULL character (0x00).