TCPIP Socket (SOCKET) Resource

This topic describes the TCPIP Socket (SOCKET) Resource that encapsulates the operations and properties of the capabilities of a raw network socket connection using TCPIP.

SOCKET Resource Overview

A VISA SOCKET Resource, like any other resource, starts with the basic operations and attributes of the VISA Resource Template. For example, modifying the state of an attribute is done via the operation viSetAttribute, which is defined in the VISA Resource Template.

Although the TCPIP resource does not have viSetAttribute listed in its operations, it provides the operation because it is defined in the VISA Resource Template. From this basic set, each resource adds its specific operations and attributes that allow it to perform its dedicated task.

The SOCKET Resource exposes the capability of a raw network socket connection over TCPIP. This usually means Ethernet, but the protocol is not restricted to that physical interface. Services are provided to send and receive blocks of data. If the device is capable of communicating with IEEE-488.2-style strings, an attribute setting also allows sending software triggers, querying an IEEE-488-style status byte, and sending a device clear message.

SOCKET Resource Attributes

AP = Access Privileges

Attribute Name	Attribute Value	Access Privilege		Data Type	Range	Default
Generic SOCKET Resource Attributes
VI_ATTR_DMA_ALLOW_EN	0x3FFF001EUL	RW	Local	ViBoolean	VI_TRUE VI_FALSE	VI_FALSE
VI_ATTR_FILE_APPEND_EN	0x3FFF0192UL	RW	Local	ViBoolean	VI_TRUE VI_FALSE	VI_FALSE
VI_ATTR_INTF_INST_NAME	0xBFFF00E9UL	RO	Global	ViString	N/A	N/A
VI_ATTR_INTF_NUM	0x3FFF0176UL	RO	Global	ViUInt16	0 to FFFFh	0
VI_ATTR_INTF_TYPE	0x3FFF0171UL	RO	Global	ViUInt16	VI_INTF_TCPIP	VI_INTF_TCPIP
VI_ATTR_IO_PROT	0x3FFF001CUL	RW	Local	ViUInt16	VI_NORMAL VI_PROT_4882_STRS	VI_PROT_4882_STRS
VI_ATTR_RD_BUF_OPER_MODE	0x3FFF002AUL	RW	Local	ViUInt16	VI_FLUSH_ON_ACCESS VI_FLUSH_DISABLE	VI_FLUSH_DISABLE
VI_ATTR_SEND_END_EN	0x3FFF0016UL	RW	Local	ViBoolean	VI_TRUE VI_FALSE	VI_TRUE
VI_ATTR_TERMCHAR	0x3FFF0018UL	RW	Local	ViUInt8	0 to FFh	0Ah(linefeed)
VI_ATTR_TERMCHAR_EN	0x3FFF0038UL	RW	Local	ViBoolean	VI_TRUE VI_FALSE	VI_FALSE
VI_ATTR_TMO_VALUE	0x3FFF001AUL	RW	Local	ViUInt32	VI_TMO_IMMEDIATE 1 to FFFFFFFEh VI_TMO_INFINITE	2000 msec.
VI_ATTR_WR_BUF_OPER_MODE	0x3FFF002DUL	RW	Local	ViUInt16	VI_FLUSH_ON_ACCESS VI_FLUSH_WHEN_FULL >	VI_FLUSH_WHEN_FULL
VI_ATTR_RD_BUF_SIZE	0x3FFF002BUL	RO	Local	ViUInt32	N/A	N/A
VI_ATTR_WR_BUF_SIZE	0x3FFF002EUL	RO	Local	ViUInt32	N/A	N/A
TCPIP Specific SOCKET Resource Attributes
VI_ATTR_TCPIP_ADDR	0xBFFF0195UL	RO	Global	ViString	N/A	N/A
VI_ATTR_TCPIP_HOSTNAME	0xBFFF0196UL	RO	Global	ViString	N/A	N/A
VI_ATTR_TCPIP_PORT	0x3FFF0197UL	RO	Global	ViUInt16	0 to FFFFh	N/A
VI_ATTR_TCPIP_NODELAY	0x3FFF019AUL	RW	Local	ViBoolean	VI_TRUE VI_FALSE	VI_TRUE
VI_ATTR_TCPIP_KEEPALIVE	0x3FFF019BUL	RW	Local	ViBoolean	VI_TRUE VI_FALSE	VI_FALSE

SOCKET Resource Attribute Descriptions

Attribute Name	Description
Generic SOCKET Resource Attributes
VI_ATTR_DMA_ALLOW_EN	This attribute specifies whether I/O accesses should use DMA ( VI_TRUE) or Programmed I/O ( VI_FALSE). In some implementations, this attribute may have global effects even though it is documented to be a local attribute. Since this affects performance and not functionality, that behavior is acceptable.
VI_ATTR_FILE_APPEND_EN	This attribute specifies whether viReadToFile will overwrite (truncate) or append when opening a file.
VI_ATTR_INTF_INST_NAME	Human-readable text describing the given interface.
VI_ATTR_INTF_NUM	Board number for the given interface.
VI_ATTR_INTF_TYPE	Interface type of the given session.
VI_ATTR_IO_PROT	Specifies which protocol to use.
VI_ATTR_RD_BUF_OPER_MODE	Determines the operational mode of the read buffer. When the operational mode is set to VI_FLUSH_DISABLE (default), the buffer is flushed only on explicit calls to viFlush.
VI_ATTR_SEND_END_EN	Whether to assert END during the transfer of the last byte of the buffer.
VI_ATTR_TERMCHAR	Termination character. When the termination character is read and VI_ATTR_TERMCHAR_EN is enabled during a read operation, the read operation terminates. Note: the termination character must be enabled in the program when reading from a SOCKET device that does not support EOI; otherwise the SOCKET read will timeout.
VI_ATTR_TERMCHAR_EN	Flag that determines whether the read operation should terminate when a termination character is received.
VI_ATTR_TMO_VALUE	Minimum timeout value to use, in milliseconds. A timeout value of VI_TMO_IMMEDIATE means that operations should never wait for the device to respond. A timeout value of VI_TMO_INFINITE disables the timeout mechanism.
VI_ATTR_WR_BUF_OPER_MODE	Determines the operational mode of the write buffer. When the operational mode is set to VI_FLUSH_WHEN_FULL (default), the buffer is flushed when an END indicator is written to the buffer or when the buffer fills up. If the operational mode is set to VI_FLUSH_ON_ACCESS, the write buffer is flushed under the same conditions, and also every time a viPrintf operation completes.
VI_ATTR_RD_BUF_SIZE	This attribute specifies the size of the formatted I/O read buffer. The user can modify this value by calling viSetBuf().
VI_ATTR_WR_BUF_SIZE	This attribute specifies the size of the formatted I/O write buffer. The user can modify this value by calling viSetBuf().
TCPIP Specific SOCKET Resource Attributes
VI_ATTR_TCPIP_ADDR	This is the TCPIP address of the device to which the session is connected. This string is formatted in dot notation.
VI_ATTR_TCPIP_HOSTNAME	Specifies the host name of the device. If no host name is available, this attribute returns an empty string.
VI_ATTR_TCPIP_PORT	Specifies the port number for a given TCPIP address. For a TCPIP SOCKET resource, this is a required part of the address string.
VI_ATTR_TCPIP_NODELAY	The Nagle algorithm is disabled when this attribute is enabled (and vice versa). The Nagle algorithm improves network performance by buffering "send" data until a full-size packet can be sent. This attribute is enabled by default in VISA to verify that synchronous writes get flushed immediately.
VI_ATTR_TCPIP_KEEPALIVE	An application can request that a TCPIP provider enable the use of "keep-alive" packets on TCP connections by turning on this attribute. If a connection is dropped as a result of "keep-alives," the error code VI_ERROR_CONN_LOST is returned to current and subsequent I/O calls on the session.

SOCKET Resource Event

This resource defines the following events for communication with applications, where AP = Access Privilege.

VI_EVENT_IO_COMPLETION - Notification that an asynchronous operation has completed.

Event Attribute	Attribute Value	Description	AP	Data Type	Range
VI_ATTR_BUFFER	0x3FFF4027UL	Address of a buffer that was used in an asynchronous operation.	RO	ViBuf	N/A
VI_ATTR_EVENT_TYPE	0x3FFF4010UL	Unique logical identifier of the event.	RO	ViEventType	VI_EVENT_IO_COMPLETION
VI_ATTR_JOB_ID	0x3FFF4006UL	Job ID of the asynchronous operation that has completed.	RO	ViJobId	N/A
VI_ATTR_OPER_NAME	0xBFFF4042UL	Name of the operation generating the event.	RO	ViString	N/A
VI_ATTR_STATUS	0x3FFF4025UL	Return code of the asynchronous I/O operation that has completed.	RO	ViStatus	N/A
VI_ATTR_RET_COUNT	32-bit: 0x3FFF4026UL 64-bit: 0x3FFF4028UL	Actual number of elements that were asynchronously transferred.	RO	ViBus Size	*
VI_ATTR_RET_COUNT_32	0x3FFF4026UL	Actual number of elements that were asynchronously transferred.	RO	ViUInt32	0 to FFFFFFFFh
VI_ATTR_RET_COUNT_64**	0x3FFF4028UL	Actual number of elements that were asynchronously transferred.	RO	ViUInt64	0 to FFFFFFFF FFFFFFFFh

*The data type is defined in the appropriate VPP 4.3.x framework specification.

**Defined only for operating systems that are 64-bit native.

SOCKET Resource Operations

viAssertTrigger (vi, protocol)

viBufRead (vi, buf, count, retCount)

viBufWrite (vi, buf, count, retCount)

viClear (vi)

viFlush (vi, mask)

viPrintf (vi, writeFmt, arg1, arg2, ...)

viRead (vi, buf, count, retCount)

viReadAsync (vi, buf, count, jobId)

viReadSTB (vi, status)

viReadToFile (vi, filename, count, retCount)

viScanf (vi, readFmt, arg1, arg2, ...)

viSetBuf (vi, mask, size)

viSPrintf (vi, buf, writeFmt, arg1, arg2, ...)

viSScanf (vi, buf, readFmt, arg1, arg2, ...)

viVPrintf (vi, writeFmt, params)

viVScanf (vi, readFmt, params)

viVSPrintf (vi, buf, writeFmt, params)

viVSScanf (vi, buf, readFmt, params)

viWrite (vi, buf, count, retCount)

viWriteAsync (vi, buf, count, jobId)

viWriteFromFile (vi, filename, count, retCount)