TCPIP Socket (SOCKET) Resource

Agilent VISA.NET

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

Note: AP = Access Privileges

Attribute Name

AP

Data Type

Range

Default

 Generic SOCKET Resource Attributes

       

VI_ATTR_DMA_ALLOW_EN

RW

Local

ViBoolean

VI_TRUE
VI_FALSE

VI_FALSE

VI_ATTR_FILE_APPEND_EN

RW

Local

ViBoolean

VI_TRUE
VI_FALSE

VI_FALSE

VI_ATTR_INTF_INST_NAME

RO

Global

ViString

N/A

N/A

VI_ATTR_INTF_NUM

RO

Global

ViUInt16

0 to FFFFh

0

VI_ATTR_INTF_TYPE

RO

Global

ViUInt16

VI_INTF_TCPIP

VI_INTF_TCPIP

VI_ATTR_IO_PROT

RW

Local

ViUInt16

VI_NORMAL
VI_PROT_4882_STRS

VI_NORMAL

VI_ATTR_RD_BUF_OPER_MODE

RW

Local

ViUInt16

VI_FLUSH_ON_ACCESS
VI_FLUSH_DISABLE

VI_FLUSH_DISABLE

VI_ATTR_SEND_END_EN

RW

Local

ViBoolean

VI_TRUE
VI_FALSE

VI_TRUE

VI_ATTR_TERMCHAR

RW

Local

ViUInt8

0 to FFh

0Ah(linefeed)

VI_ATTR_TERMCHAR_EN

RW

Local

ViBoolean

VI_TRUE
VI_FALSE

VI_FALSE

VI_ATTR_TMO_VALUE

RW

Local

ViUInt32

VI_TMO_IMMEDIATE
1 to FFFFFFFEh
VI_TMO_INFINITE

2000 msec.

VI_ATTR_WR_BUF_OPER_MODE

RW

Local

ViUInt16

VI_FLUSH_ON_ACCESS
VI_FLUSH_WHEN_FULL >

VI_FLUSH_WHEN_FULL

VI_ATTR_RD_BUF_SIZE

RO

Local

ViUInt32

N/A

N/A

VI_ATTR_WR_BUF_SIZE

RO

Local

ViUInt32

N/A

N/A

 TCPIP Specific SOCKET Resource Attributes

       

VI_ATTR_TCPIP_ADDR

RO

Global

ViString

N/A

N/A

VI_ATTR_TCPIP_HOSTNAME

RO

Global

ViString

N/A

N/A

VI_ATTR_TCPIP_PORT

RO

Global

ViUInt16

0 to FFFFh

N/A

VI_ATTR_TCPIP_NODELAY

RW

Local

ViBoolean

VI_TRUE
VI_FALSE

VI_TRUE

VI_ATTR_TCPIP_KEEPALIVE

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

 Description

 AP

 Data Type

 Range

VI_ATTR_BUFFER

Address of a buffer that was used in an asynchronous operation.

RO

ViBuf

N/A

VI_ATTR_EVENT_TYPE

Unique logical identifier of the event.

RO

ViEventType

VI_EVENT_IO_COMPLETION

VI_ATTR_JOB_ID

Job ID of the asynchronous operation that has completed.

RO

ViJobId

N/A

VI_ATTR_OPER_NAME

Name of the operation generating the event.

RO

ViString

N/A

VI_ATTR_STATUS

Return code of the asynchronous I/O operation that has completed.

RO

ViStatus

N/A

VI_ATTR_RET_COUNT

Actual number of elements that were asynchronously transferred.

RO

ViBus Size

*

VI_ATTR_RET_COUNT_32

Actual number of elements that were asynchronously transferred.

RO

ViUInt32

0 to FFFFFFFFh

VI_ATTR_RET_COUNT_64**

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)