SOCKET

The SOCKET procedure opens a client-side or server-side TCP/IP Internet socket as an IDL file unit. Such files can be used in the standard manner with any of IDL’s Input/Output routines.

Tip: Avoid using the EOF procedure as a way to check to see if a socket is empty. Instead, structure your communication across the socket so that using EOF is not necessary to know when the communication is complete.

Examples

Most UNIX systems maintain a daytime server on the daytime port (port 13). These servers send a 1 line response when connected to, containing the current time of day.

; To obtain the current time from the host bullwinkle:

SOCKET, 1, 'bullwinkle','daytime'

date=''

READF, 1, date

CLOSE, 1

PRINT, date

IDL prints:

Wed Sep 15 17:20:27 1999

To open a listening socket and accept a connection request from a client:

; open a listening socket, letting the OS choose the port

SOCKET, listenLun, /LISTEN, /GET_LUN, PORT=listenPort

print, listenPort

; wait for a connection request

WHILE 1 DO BEGIN

  ; check for activity on the listening socket

  res = FILE_POLL_INPUT(listenLun, TIMEOUT=0.5)

  IF (res) THEN BEGIN

    ; establish a connection with the client

    SOCKET, readLun, ACCEPT=listenLun, /GET_LUN

    ; close the listening socket

    FREE_LUN, listenLun

    ; escape infinite loop

    BREAK

  ENDIF

  ; pause to not dominate the CPU

  WAIT, 0.5

ENDWHILE

Syntax

SOCKET, Unit, ACCEPT=value [, CONNECT_TIMEOUT=value] [, ERROR=variable] [, /GET_LUN] [, /RAWIO] [, READ_TIMEOUT=value] [, /SWAP_ENDIAN] [, /SWAP_IF_BIG_ENDIAN] [, /SWAP_IF_LITTLE_ENDIAN] [, WIDTH=value] [, WRITE_TIMEOUT=value]

SOCKET, Unit, [Port,] /LISTEN [, ERROR=variable] [, /GET_LUN] [, PORT=variable]

SOCKET, Unit, Host, Port [, CONNECT_TIMEOUT=value] [, ERROR=variable] [, /GET_LUN] [, PORT=variable] [, /RAWIO] [, READ_TIMEOUT=value] [, /SWAP_ENDIAN] [, /SWAP_IF_BIG_ENDIAN] [, /SWAP_IF_LITTLE_ENDIAN] [, WIDTH=value] [, WRITE_TIMEOUT=value]

UNIX-Only Keywords: [, /STDIO]

Arguments

Unit

The unit number to associate with the opened socket.

Host

The name of the host to which the socket is connected. This can be either a standard Internet host name (e.g.info.cern.ch) or a dot-separated numeric address (e.g. 192.5.156.21).

Port

The port to which the socket is connected on the remote machine. If this is a well-known port (as contained in the /etc/services file on a UNIX host), then you can specify its name (e.g. daytime); otherwise, specify a number.

This is optional when /LISTEN is specified, at which point the OS will choose a port to listen on, and the value will be returned in the PORT keyword.

Keywords

ACCEPT

Set this keyword to a specified LUN, which was previously opened by this procedure with the /LISTEN keyword.

CONNECT_TIMEOUT

Set this keyword to the number of seconds to wait before giving up and issuing an error to shorten the connect timeout from the system-supplied default. Most experts recommend that you not specify an explicit timeout, and instead use your operating system defaults.

Note: Although you can use CONNECT_TIMEOUT to shorten the timeout, you cannot increase it past the system-supplied default.

ERROR

A named variable in which to place the error status. If an error occurs in the attempt to open the socket, IDL normally takes the error handling action defined by the ON_ERROR and/or ON_IOERROR procedures. SOCKET always returns to the caller without generating an error message when ERROR is present. A nonzero error status indicates that an error occurred. The error message can then be found in the system variable !ERROR_STATE.MSG.

GET_LUN

Set this keyword to use the GET_LUN procedure to set the value of Unit before the file is opened. Instead of using the two statements:

GET_LUN, Unit

OPENR, Unit, 'data.dat'

you can use the single statement:

OPENR, Unit, 'data.dat', /GET LUN

LISTEN

Set this keyword to tell this socket to listen on the specified port.

PORT

A named variable which returns the port of the current socket.

RAWIO

Set this keyword to disable all use of the standard operating system I/O for the file, in favor of direct calls to the operating system. This allows direct access to devices, such as tape drives, that are difficult or impossible to use effectively through the standard I/O. Using this keyword has the following implications:

No formatted or associated (ASSOC) I/O is allowed on the file. Only READU and WRITEU are allowed.
Normally, attempting to read more data than is available from a file causes the unfilled space to be set to zero and an error to be issued. This does not happen with files opened with RAWIO. When using RAWIO, the programmer must check the transfer count, either via the TRANSFER_COUNT keywords to READU and WRITEU, or the FSTAT function.
The EOF and POINT_LUN functions cannot be used with a file opened with RAWIO.
Each call to READU or WRITEU maps directly to UNIX read(2) and write(2) system calls. The programmer must read the UNIX system documentation for these calls and documentation on the target device to determine if there are any special rules for I/O to that device. For example, the size of data that can be transferred to many cartridge tape drives is often forced to be a multiple of 512 bytes.

READ_TIMEOUT

Set this keyword to the number of seconds to wait for data to arrive before giving up and issuing an error. By default, IDL blocks indefinitely until the data arrives. Typically, this option is unnecessary on a local network, but it is useful with networks that are slow or unreliable.

STDIO

This keyword is only available on UNIX platforms.

Under UNIX, forces the file to be opened via the standard C I/O library (stdio) rather than any other more native OS API that might usually be used. This is primarily of interest to those who intend to access the file from external code, and is not necessary for most uses.

Note: Under Windows, the STDIO feature is not possible. Requesting it causes IDL to throw an error.

SWAP_ENDIAN

Set this keyword to swap byte ordering for multi-byte data when performing binary I/O on the specified file. This is useful when accessing files also used by another system with byte ordering different than that of the current host.

SWAP_IF_BIG_ENDIAN

Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the current system has big endian byte ordering. This keyword does not refer to the byte ordering of the input data, but to the computer hardware.

SWAP_IF_LITTLE_ENDIAN

Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the current system has little endian byte ordering. This keyword does not refer to the byte ordering of the input data, but to the computer hardware.

WIDTH

The desired output width. When using the defaults for formatted output, IDL uses the following rules to determine where to break lines:

If the output file is a terminal, the terminal width is used.
Otherwise, a default of 80 columns is used.

The WIDTH keyword allows the user to override this default.

WRITE_TIMEOUT

Set this keyword to the number of seconds to wait to send data before giving up and issuing an error. By default, IDL blocks indefinitely until it is possible to send the data. Typically, this option is unnecessary on a local network, but it is useful with networks that are slow or unreliable.

Version History

5.3	Introduced
5.6	Added SWAP_IF_BIG_ENDIAN and SWAP_IF_LITTLE_ENDIAN keywords
8.5	Added ACCEPT, LISTEN, and PORT keywords.