GPIB Bus Interface (INTFC) Resource

Agilent VISA.NET

GPIB Bus Interface (INTFC) Resource

This topic describes the GPIB Bus Interface (INTFC) Resource that is provided to encapsulate the operations and properties of a raw GPIB interface (reading, writing, triggering, etc.).

INTFC Resource Overview

A VISA GPIB Bus Interface (INTFC) Resource, like any other resource, defines the basic operations and attributes of the VISA Resource Template.

For example, modifying the state of an attribute is done via the operation viSetAttribute. Although the INTFC 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 INTFC Resource lets a controller interact with any devices connected to the board associated with this resource. Services are provided to send blocks of data onto the bus, request blocks of data from the bus, trigger devices on the bus, and send miscellaneous commands to any or all devices. In addition, the controller can directly query and manipulate specific lines on the bus and also pass control to other devices with controller capability.

INTFC Resource Attributes

Attribute Name

Access Privileges

Data Type

Range

Default

Generic INTFC Resource Attributes

VI_ATTR_DEV_STATUS_BYTE

RW

Global

ViUInt8

0 to FFh

N/A

VI_ATTR_DMA_ALLOW_EN

RW

Local

ViBoolean

VI_TRUE
VI_FALSE

VI_TRUE

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_GPIB

VI_INTF_GPIB

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 FFFFFFFE
h

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

 

GPIB-Specific INTFC Resource Attributes

VI_ATTR_GPIB_ADDR_STATE

RO

Global

ViInt16

VI_GPIB_UNADDRESSED
VI_GPIB_TALKER
VI_GPIB_LISTENER

N/A

VI_ATTR_GPIB_HS488_CBL_LEN

RW

Global

ViInt16

1 to 15
VI_GPIB_HS488_DISABLED
VI_GPIB_HS488_NIMPL

N/A

VI_ATTR_GPIB_SECONDARY_ADDR

RW

Global

ViUInt16

0 to 30
VI_NO_SEC_ADDR

VI_NO_SEC_ADDR

VI_ATTR_GPIB_ATN_STATE

RO

Global

ViInt16

VI_STATE_ASSERTED
VI_STATE_UNASSERTED
VI_STATE_UNKNOWN

N/A

VI_ATTR_GPIB_CIC_
STATE

RO

Global

ViBoolean

VI_TRUE
VI_FALSE

N/A

VI_ATTR_GPIB_NDAC_
STATE

RO

Global

ViInt16

VI_STATE_ASSERTED
VI_STATE_UNASSERTED
VI_STATE_UNKNOWN

N/A

VI_ATTR_GPIB_PRIMARY_ADDR

RW

Global

ViUInt16

0 to 30

N/A

VI_ATTR_GPIB_REN_STATE

RO

Global

ViInt16

VI_STATE_ASSERTED
VI_STATE_UNASSERTED
VI_STATE_UNKNOWN

N/A

VI_ATTR_GPIB_SRQ_STATE

RO

Global

ViInt16

VI_STATE_ASSERTED
VI_STATE_UNASSERTED
VI_STATE_UNKNOWN

N/A

VI_ATTR_GPIB_SYS_CNTRL_STATE

RW

Global

ViBoolean

VI_TRUE
VI_FALSE

N/A

INTFC Resource Attribute Descriptions

Attribute Name

Description

Generic INTFC Resource Attributes

VI_ATTR_INTF_NUM

Board number for the given interface.

VI_ATTR_INTF_TYPE

Interface type of the given session.

VI_ATTR_INTF_INST_NAME

Human-readable text describing the given interface.

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.

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_DEV_STATUS_BYTE

This attribute specifies the 488-style status byte of the local controller associated with this session. If this attribute is written and bit 6 (0x40) is set, this device or controller will assert a service request (SRQ) if it is defined for this interface.

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_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_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. If the operational mode is set to VI_FLUSH_ON_ACCESS, the buffer is flushed every time a viScanf operation completes.

VI_ATTR_FILE_APPEND_EN

This attribute specifies whether viReadToFile will overwrite (truncate) or append when opening a file.

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().

GPIB-Specific INTFC Resource Attributes

VI_ATTR_GPIB_PRIMARY_ADDR

Primary address of the local GPIB controller used by the given session.

VI_ATTR_GPIB_SECONDARY_ADDR

Secondary address of the local GPIB controller used by the given session.

VI_ATTR_GPIB_REN_STATE

This attribute returns the current state of the GPIB REN (Remote ENable) interface line.

VI_ATTR_GPIB_ATN_STATE

This attribute shows the current state of the GPIB ATN (ATtentioN) interface line.

VI_ATTR_GPIB_NDAC_STATE

This attribute shows the current state of the GPIB NDAC
(Not Data ACcepted) interface line.

VI_ATTR_GPIB_SRQ_STATE

This attribute shows the current state of the GPIB SRQ (Service ReQuest) interface line.

VI_ATTR_GPIB_CIC_STATE

This attribute shows whether the specified GPIB interface is currently CIC (controller in charge).

VI_ATTR_GPIB_SYS_CNTRL_STATE

This attribute shows whether the specified GPIB interface is currently the system controller. In some implementations, this attribute may be modified only through a configuration utility. On these systems, this attribute is read only (RO).

VI_ATTR_GPIB_HS488_CBL_LEN

This attribute specifies the total number of meters of GPIB cable used in the specified GPIB interface. If HS488 is not implemented, querying this attribute should return the value VI_GPIB_HS488_NIMPL. On these systems, trying to set this attribute value will return error VI_ERROR_NSUP_ATTR_STATE.

VI_ATTR_GPIB_ADDR_STATE

This attribute shows whether the specified GPIB interface is currently addressed to talk or listen, or is not addressed.

INTFC Resource Events

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

VI_EVENT_GPIB_CIC - Notification that the GPIB controller has gained or lost CIC (controller in charge) status.

Event Attribute

Description

AP

Data Type

Range

VI_ATTR_EVENT_TYPE

Unique logical identifier of the event.

RO

ViEventType

VI_EVENT_GPIB_CIC

VI_ATTR_GPIB_RECV_CIC_STATE

Controller has become controller in charge.

RO

ViBoolean

VI_TRUE
VI_FALSE

VI_EVENT_GPIB_TALK - Notification that the GPIB controller has been addressed to talk.

Event Attribute

Description

AP

Data Type

Range

VI_ATTR_EVENT_TYPE

Unique logical identifier of the event.

RO

ViEventType

VI_EVENT_GPIB_TALK

VI_EVENT_GPIB_LISTEN - Notification that the GPIB controller has been addressed to listen.

Event Attribute

Description

AP

Data Type

Range

VI_ATTR_EVENT_TYPE

Unique logical identifier of the event.

RO

ViEventType

VI_EVENT_GPIB_LISTEN

VI_EVENT_CLEAR - Notification that the GPIB controller has been sent a device clear message.

Event Attribute

Description

AP

Data Type

Range

VI_ATTR_EVENT_TYPE

Unique logical identifier of the event.

RO

ViEventType

VI_EVENT_CLEAR

VI_EVENT_TRIGGER - Notification that a trigger interrupt was received from the interface.

Event Attribute

Description

AP

Data Type

Range

VI_ATTR_EVENT_TYPE

Unique logical identifier of the event.

RO

ViEventType

VI_EVENT_TRIG

VI_ATTR_RECV_TRIG_ID

The identifier of the triggering mechanism on which the specified trigger event was received.

RO

ViInt16

VI_TRIG_SW

VI_EVENT_IO_COMPLETION - Notification that an asynchronous operation has completed.

Event Attribute

Description

AP

Data Type

Range

VI_ATTR_EVENT_TYPE

Unique logical identifier of the event.

RO

ViEventType

VI_EVENT_IO_COMPLETION

VI_ATTR_STATUS

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

RO

ViStatus

N/A

VI_ATTR_JOB_ID

Job ID of the asynchronous operation that has completed.

RO

ViJobId

N/A

VI_ATTR_BUFFER

Address of buffer used in an asynchronous operation.

RO

ViBuf

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

VI_ATTR_OPER_NAME

The name of the operation generating the event.

RO

ViString

N/A

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

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

INTFC Resource Operations

viAssertTrigger (vi, protocol)

viBufRead (vi, buf, count, retCount)

viBufWrite (vi, buf, count, retCount)

viFlush (vi, mask)

viGpibCommand (vi, buf, count, retCount)

viGpibControlATN  (vi, mode)

viGpibControlREN (vi, mode)

viGpibPassControl (vi, primAddr, secAddr)

viGpibSendIFC (vi)

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

viRead (vi, buf, count, retCount)

viReadAsync (vi, buf, count, jobId)

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)