VISA XOP Functions

The VISA XOP adds the following low-level functions to Igor. These functions provide direct access to VISA library functions. VISA library functions that are not supported by VISA XOP are also noted in this list.

note

In addition to these low-level functions, VISA XOP also adds higher-level VISA XOP Operations.

Resource Manager

Function	Details
viOpenDefaultRM	Opens a session with the VISA default resource manager.
viOpen	Opens a session with an instrument.
viFindRsrc	Find what instruments are available for use.
viFindNext	Used with viFindRsrc to find successive instruments.
viParseRsrc	viParseRsrc is not supported by VISA XOP.
viParseRsrcEx	viParseRsrcEx is not supported by VISA XOP.

Resource Template

Function	Details
viClose	Closes a session opened with viOpenDefaultRM or viOpen.
viSetAttribute	Sets a numeric attribute of a VISA interface or instrument.
viSetAttributeString	Sets a string attribute of a VISA interface or instrument.
viGetAttribute	Gets a numeric attribute of a VISA interface or instrument.
viGetAttributeString	Gets a string attribute of a VISA interface or instrument.
viStatusDesc	Returns a string description of a VISA status code.
viTerminate	Terminates an asynchronous job.
viLock	Locks a resource.
viUnlock	Unlocks resource.
viEnableEvent	Enables event notification.
viDisableEvent	Disables event notification.
viDiscardEvents	Discards event notifications.
viWaitOnEvent	Waits until an event has occurred.
viInstallHandler	viInstallHandler is not supported by VISA XOP.
viUninstallHandler	viUninstallHandler is not supported by VISA XOP.

Basic I/O

Function	Details
viRead	Reads data into a string variable.
viReadAsync	viReadAsync is not supported by VISA XOP.
viReadToFile	viReadToFile is not supported by VISA XOP.
viWrite	Writes data from a string variable.
viWriteAsync	viWriteAsync is not supported by VISA XOP.
viWriteFromFile	viWriteFromFile is not supported by VISA XOP.
viAssertTrigger	Generates a trigger signal.
viReadSTB	Reads an instrument's status byte.
viClear	Performs a "device-clear" operation.

Formatted and Buffered I/O

Function	Details
viSetBuf	viSetBuf is not supported by VISA XOP.
viFlush	viFlush is not supported by VISA XOP.
viBufWrite	viBufWrite is not supported by VISA XOP.
viBufRead	viBufRead is not supported by VISA XOP.
viPrintf	viPrintf is not supported by VISA XOP.
viVPrintf	viVPrintf is not supported by VISA XOP.
viSPrintf	viSPrintf is not supported by VISA XOP.
viVSPrintf	viVSPrintf is not supported by VISA XOP.
viScanf	viScanf is not supported by VISA XOP.
viVScanf	viVScanf is not supported by VISA XOP.
viSScanf	viSScanf is not supported by VISA XOP.
viVSScanf	viVSScanf is not supported by VISA XOP.
viQueryf	viQueryf is not supported by VISA XOP.
viVQueryf	viVQueryf is not supported by VISA XOP.

Memory I/O

Function	Details
viIn8	Reads a one-byte value from a VXI board. Not supported by TekVISA.
viOut8	Writes a one-byte value to a VXI board. Not supported by TekVISA.
viIn16	Reads a two-byte value from a VXI board. Not supported by TekVISA.
viOut16	Writes a two-byte value to a VXI board. Not supported by TekVISA.
viIn32	Reads a four-byte value from a VXI board. Not supported by TekVISA.
viOut32	Writes a four-byte value to a VXI board. Not supported by TekVISA.
viMoveIn8	Reads multiple one-byte values from a VXI board. Not supported by TekVISA.
viMoveOut8	Writes multiple one-byte values to a VXI board. Not supported by TekVISA.
viMoveIn16	Reads multiple two-byte values from a VXI board. Not supported by TekVISA.
viMoveOut16	Writes multiple two-byte values to a VXI board. Not supported by TekVISA.
viMoveIn32	Reads multiple four-byte values from a VXI board. Not supported by TekVISA.
viMoveOut32	Writes multiple four-byte values to a VXI board. Not supported by TekVISA.
viMoveAsync	viMoveAsync is not supported by VISA XOP.
viMapAddress	Maps VXI register space into memory space. Not supported by TekVISA.
viUnmapAddress	Frees up memory space previously mapped by viMapAddress. Not supported by TekVISA.
viPeek8	Reads a one-byte value using an address obtained from viMapAddress. Not supported by TekVISA.
viPoke8	Writes a one-byte value using an address obtained from viMapAddress. Not supported by TekVISA.
viPeek16	Reads a two-byte value using an address obtained from viMapAddress. Not supported by TekVISA.
viPoke16	Writes a two-byte value using an address obtained from viMapAddress. Not supported by TekVISA.
viPeek32	Reads a four-byte value using an address obtained from viMapAddress. Not supported by TekVISA.
viPoke32	Writes a four-byte value using an address obtained from viMapAddress. Not supported by TekVISA.

Shared Memory

Function	Details
viMemAlloc	Allocates memory on a VXI board. Not supported by TekVISA.
viMemFree	Frees memory on a VXI board. Not supported by TekVISA.

Interface Specific

Function	Details
viGpibControlREN	Controls the GPIB remote enable signal. Not supported by TekVISA.
viGpibControlATN	Controls the GPIB attention signal. Not supported by TekVISA.
viGpibSendIFC	Sends the GPIB interface-clear signal. Not supported by TekVISA.
viGpibCommand	Sends controller GPIB command bytes to the GPIB bus. Not supported by TekVISA.
viGpibPassControl	Passes GPIB control to another controller. Not supported by TekVISA.
viVxiCommandQuery	Sends a command or query to a VXI device. Not supported by TekVISA.
viAssertUtilSignal	Controls a utility bus signal. Not supported by TekVISA.
viAssertIntrSignal	Controls an interrupt signal. Not supported by TekVISA.
viMapTrigger	Maps a trigger source to a trigger destination. Not supported by TekVISA.
viUnmapTrigger	Unmaps a trigger signal. Not supported by TekVISA.
viUsbControlOut	Sends data to a USB device. Not supported by TekVISA.
viUsbControlIn	Reads data from a USB device. Not supported by TekVISA.

Errors and Status Codes From VISA XOP Functions

When you call a VISA function from Igor, you are calling an Igor function added by the VISA XOP. The VISA XOP in turn calls a VISA library function. Each VISA library function returns a status code which indicates if the function succeeded or failed. Status codes greater than or equal to zero indicate success. Status codes less than zero indicate failure.

Each VISA XOP function calls one VISA library function. The function result returned by the Igor VISA function is the status code returned by the VISA library function. In the event of a failure (status code less than zero) you can get a human-readable message by calling viStatusDesc. See the example under viStatusDesc. There is one special status code. -1 indicates that an error occurred in the VISA XOP function before it made any calls to the corresponding VISA library function.

In addition to the status code which is returned to your user-defined Igor function, each VISA XOP function returns an error code to Igor. Your user-defined Igor function does not see this error code. If the error code is non-zero, Igor aborts function execution and reports the error to the user. VISA XOP functions do not return errors to Igor to indicate a failure status returned by a VISA library function. They return errors to Igor only to indicate programming errors such as "out-of-memory" or passing a null (uninitialized) string variable as a parameter. You can test for Igor errors by calling GetRTError, but in general this is not necessary because they are programming errors that need to be fixed by the Igor programmer (you), not VISA library failures that need to be gracefully handled by your code.

See the example under viFindRsrc for an example of handling VISA library failure status codes.

viOpenDefaultRM (session)

Opens the VISA default resource manager and returns a session ID via session .

The function result is a VISA status code.

Parameters

session is an output. On return it contains a session ID which can be passed to viOpen to open an instrument session.

Details

You must open a default resource manager session before doing anything else with VISA.

See the VISA library documentation for further details.

See viOpen for an example.

viOpen (session , resourceName , accessMode , openTimeout , instr )

Opens a session with the instrument specified by resourceName.

The function result is a VISA status code.

Parameters

session is a value returned by viOpenDefaultRM.

instr is an output. On return it contains an instrument session ID which can be passed to viRead, viWrite, viClose and so on.

Details

See the VISA library documentation for further details.

Examples

Variable defaultRM, instr
String resourceName = "GPIB0::1::INSTR"

viOpenDefaultRM(defaultRM)
viOpen(defaultRM, resourceName, 0, 0, instr)

// Do something with instr
viClose(instr)
viClose(defaultRM)

viFindRsrc (session , expr , findList , retcnt , instrDesc )

Finds the first resource matching expr and sets up for subsequent calls to viFindNext.

The function result is a VISA status code.

Parameters

session is a value returned by viOpenDefaultRM.

expr is is a regular expression indicating what type of resources you want to find. See National Instruments' documentation for viFindRsrc for the regular expression rules. They are different from Igor's regular expression rules.

findList is an output. It is used with subsequent calls to viFindNext.

retcnt is the number of resources that match expr and is used to control the number of subsequent calls to viFindNext.

instrDesc is an output. It is the description of the first resource found and can be passed to viOpen.

Details

Unlike calling viFindRsrc from C, when calling from Igor, you can not pass NULL for the findList parameter. Thus you must call viClose on the VISA object whose reference is returned in findList .

The value returned in findList is a VISA object and must be passed to viClose when you are finished with it.

See the VISA library documentation for further details.

Examples

Function Example()
    Variable defaultRM=0, findList=0, retcnt
    String expr, instrDesc
    Variable i, status=0

    do		// Just a structure to break out of in case of error
        expr = "ASRL?*INSTR"			// Match all serial instruments.
        status = viOpenDefaultRM(defaultRM)
        if (status < 0)
            break
        endif

        status = viFindRsrc(defaultRM, expr, findList, retcnt, instrDesc)
        if (status < 0)
            break
        endif

        if (retcnt <= 0)
            break
        endif

        i = 1
        do
            Printf "Instrument %d: %s\r", i, instrDesc
            i += 1

            if (i > retcnt)
                break
            endif

            status = viFindNext(findList, instrDesc)
            if (status < 0)
                break
            endif

        while(1)
    while(0)

    if (status < 0)
        String errorDesc
        Variable viObject

        viObject = findList

        if (viObject == 0)
            viObject = defaultRM
        endif

        viStatusDesc(viObject, status, errorDesc)
        Printf "VISA Error: %s\r", errorDesc
    endif

    if (findList != 0)
        viClose(findList)
    endif

    if (defaultRM != 0)
        viClose(defaultRM)
    endif

    return status
End

viFindNext (findList , instrDesc )

Finds the next resource. viFindNext is called after viFindRsrc.

The function result is a VISA status code.

Parameters

findList is an object reference returned by viFindRsrc.

instrDesc is an output. It is the description of the next resource found and can be passed to viOpen.

Details

See the VISA library documentation for further details.

Examples

See the example under viFindRsrc.

viClose (session )

Closes a session.

The function result is a VISA status code.

Parameters

session is a value returned by viOpenDefaultRM or viOpen.

Details

See the VISA library documentation for further details.

See viOpen for an example.

viSetAttribute (vi , attribute , attrState )

Sets the value of a numeric attribute of a VISA interface or instrument .

The function result is a VISA status code.

Parameters

vi is a VISA object reference obtained from viOpen.

attribute is an attribute constant as defined in the VISA.ipf Igor procedure file.

attrState is the new value to which the attribute is to be set.

Details

viSetAttribute works with numeric attributes only. It does not work with string attributes. For string attributes, use viSetAttributeString.

viSetAttribute does not support attributes of type ViAddr, ViBuf or ViAUInt8, or with any attributes not defined in VISA.h from VISA 3.0, or with any non-standard attributes such as VI_ATTR_PXI_* and VI_ATTR_USB_*.

See the VISA library documentation for viSetAttribute further details.

Example

Function VISASetAttrBaud(instr, baud)
    Variable instr			// An instrument referenced obtained from viOpen
    Variable baud
    Variable status

    status = viSetAttribute(instr, VI_ATTR_ASRL_BAUD, baud)
    return status
End

viSetAttributeString (vi , attribute , attrStateStr )

Sets the value of a string attribute of a VISA interface or instrument .

The function result is a VISA status code.

Parameters

vi is a VISA object reference obtained from viOpen.

attribute is an attribute constant as defined in the VISA.ipf Igor procedure file.

attrStateStr is the new value to which the attribute is to be set.

Details

viSetAttributeString does not correspond to a VISA library function of the same name. It corresponds viSetStringAttribute for ViString and ViRsrc-type attributes.

As of this writing, VISA defines no read/write attributes of these types.

viSetAttributeString works with ViString and ViRsrc-type attributes only. It does not work with numeric attributes. For numeric attributes, use viSetAttribute.

viSetAttributeString does not support attributes of type ViAddr, ViBuf or ViAUInt8, or with any attributes not defined in VISA.h from VISA 3.0, or with any non-standard attributes such as VI_ATTR_PXI_* and VI_ATTR_USB_*.

See the VISA library documentation for viSetAttribute further details.

viGetAttribute (vi , attribute , attrState )

Gets the value of a numeric attribute of a VISA interface or instrument which is returned via attrState .

The function result is a VISA status code.

Parameters

vi is a VISA object reference obtained from viOpen.

attribute is an attribute constant as defined in the VISA.ipf Igor procedure file.

attrState is an output. On return it contains the value of the attribute.

Details

viGetAttribute works with numeric attributes only. It does not work with string attributes. For string attributes, use viGetAttributeString.

viGetAttribute does not support attributes of type ViAddr, ViBuf or ViAUInt8, or with any attributes not defined in VISA.h from VISA 3.0, or with any non-standard attributes such as VI_ATTR_PXI_* and VI_ATTR_USB_*.

See the VISA library documentation for viGetAttribute further details.

Example

Function VISAGetAttrBaud(instr, baud)
    Variable instr			// An instrument referenced obtained from viOpen
    Variable &baud			// Output

    Variable status
    status = viGetAttribute(instr, VI_ATTR_ASRL_BAUD, baud)
    return status
End

viGetAttributeString (vi , attribute , attrStateStr )

Gets the value of a string attribute of a VISA interface or instrument which is returned via attrStateStr .

The function result is a VISA status code.

Parameters

vi is a VISA object reference obtained from viOpen.

attribute is an attribute constant as defined in the VISA.ipf Igor procedure file.

attrStateStr is an output. On return it contains the value of the attribute.

Details

viGetAttributeString does not correspond to a VISA library function of the same name. It corresponds viGetStringAttribute for ViString and ViRsrc-type attributes.

viGetAttributeString works with ViString and ViRsrc-type attributes only. It does not work with numeric attributes. For numeric attributes, use viGetAttribute.

viGetAttributeString does not support attributes of type ViAddr, ViBuf or ViAUInt8, or with any attributes not defined in VISA.h from VISA 3.0, or with any non-standard attributes such as VI_ATTR_PXI_* and VI_ATTR_USB_*.

Example

Function VISAGetAttrRsrcClass(instr, name)
    Variable instr			// An instrument referenced obtained from viOpen
    String &name			// Output

    Variable status
    status = viGetAttributeString(instr, VI_ATTR_RSRC_NAME, name)
    return status
End

viStatusDesc (vi , status , desc )

Returns via desc a string description of a VISA status code.

The function result is a VISA status code.

Parameters

vi is a value returned by viOpenDefaultRM or viOpen.

status is a result returned by any VISA library call.

desc is a string variable. On return it contains a description of the status code.

Details

See the VISA library documentation for further details.

Example

// ReportVISAError is defined in the VISA.ipf procedure file.

Function ReportVISAError(name, session, status)
    String name                 // VISA function name, e.g., viRead or other identifier
    Variable session            // Session ID obtained from viOpen
    Variable status             // Status code from VISA library

    String desc
    viStatusDesc(session, status, desc)
    Printf "%s error (%x): %s\r", name, status, desc
    Beep
End

// This function illustrates the use of ReportVISAError which calls viStatusDesc.

Function Test()
    Variable status
    Variable defaultRM
    String resourceName = "GPIB0::1::INSTR"

    Variable instr = 0
    status = viOpenDefaultRM(defaultRM)

    if (status < 0)
    ReportVISAError("viOpenDefaultRM", instr, status)
    return status               // Failure
    endif

    status = viOpen(defaultRM, resourceName, 0, 0, instr)
    if (status < 0)
    viClose(defaultRM)
    ReportVISAError("viOpen", instr, status)
    return status               // Failure
    endif

    // Do something with instr

    viClose(instr)
    viClose(defaultRM)
    return 0                    // Success
End

viTerminate (vi , degree , jobId )

Requests termination of an operation.

The function result is a VISA status code.

Parameters

vi is a value returned by viOpenDefaultRM or viOpen.

degree must always be zero.

jobId specifies the operation to terminate.

Details

See the VISA library documentation for further details.

This function is untested.

viLock (vi , lockType , timeout , requestedKeyStr , accessKeyStr )

Sets access mode for a resource.

The function result is a VISA status code.

Parameters

vi is a value returned by viOpen.

lockType is VI_EXCLUSIVE_LOCK or VI_SHARED_LOCK.

timeout specifies the time in milliseconds to wait for resource to be free.

requestedKeyStr is the key to use for a shared lock. It is ignored if lockType is VI_EXCLUSIVE_LOCK.

accessKeyStr is an output. It is set to "" if lockType is VI_EXCLUSIVE_LOCK.

Details

See the VISA library documentation for further details.

This function is untested.

viUnlock (vi)

Releases a lock.

The function result is a VISA status code.

Parameters

vi is a value returned by viOpen.

Details

See the VISA library documentation for further details.

This function is untested.

viEnableEvent (vi , eventType , mechanism, context )

Tells the VISA library that you are interested in the specified event.

Later you would use viWaitOnEvent to see if the event occurred.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

eventType is one of the VI_EVENT constants defined in VISA.h (for C) and VISA.ipf (for Igor).

mechanism specifies how the event is to be handled. With VISA XOP, the only legal value is VI_QUEUE.

context must always be zero.

Details

See the VISA library documentation for further details.

viDisableEvent (vi , eventType , mechanism, context )

Tells the VISA library that you are not interested in the specified event.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

eventType is one of the VI_EVENT constants defined in VISA.h (for C) and VISA.ipf (for Igor).

mechanism specifies how the event is to be handled. With VISA XOP, the only legal value is VI_QUEUE.

context must always be zero.

Details

See the VISA library documentation for further details.

viDiscardEvents (vi , eventType , mechanism, context )

Discards specified events in the event queue.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

eventType is one of the VI_EVENT constants defined in VISA.h (for C) and VISA.ipf (for Igor).

mechanism specifies how the event is to be handled. With VISA XOP, the only legal value is VI_QUEUE.

context must always be zero.

Details

See the VISA library documentation for further details.

viWaitOnEvent (vi , inEventType , timeout , outEventType , outContext)

Waits till the specified event occurs or until a timeout occurs.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

inEventType is one of the VI_EVENT constants defined in VISA.h (for C) and VISA.ipf (for Igor).

timeout is the maximum time in milliseconds to wait for the event to occur.

outEventType is an output and returns the type of event that occurred. It is one of the VI_EVENT constants defined in VISA.h (for C) and VISA.ipf (for Igor).

outContext is an output and identifies a unique occurrence of an event. If viWaitOnEvent succeeds then you must call viClose on outContext when you are finished with the event.

Details

See the VISA library documentation for further details.

viRead (vi , buf , cnt , retCnt)

Reads data from an instrument into an Igor string variable.

For reading into a numeric wave, use VISAReadWave or VISAReadBinary.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

buf is the string variable to receive the data read from the instrument.

cnt is the number of bytes to read.

retCnt is an output and returns the number of bytes actually read.

Details

When reading binary data into a string, the VISA library may terminate the read prematurely unless you set the appropriate attributes. See VISA Library Terminator Character Issues for details.

See the VISA library documentation for further details.

viWrite (vi , buf , cnt , retCnt)

Writes data from an Igor string variable to an instrument.

For reading into a numeric wave, use VISAWriteWave or VISAWriteBinary.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

buf is the string to write to the instrument.

cnt is the number of bytes to write. It must not be larger than the number of bytes in the string variable.

retCnt is an output and returns the number of bytes actually written.

Details

See the VISA library documentation for further details.

viAssertTrigger (vi , protocol )

Asserts a hardware or software trigger.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

protocol is one of the VI_TRIG constants defined in VISA.ipf.

Details

See the VISA library documentation for further details.

viReadSTB (vi , status)

Reads an instrument's status byte.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

status is an output and returns the instrument's status byte.

Details

See the VISA library documentation for further details.

viClear (vi )

Performs a "device-clear" operation on the instrument. What this means depends on the instrument.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

Details

See the VISA library documentation for further details.

viIn8 (vi , space , offset , val)

Reads a one-byte value from a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

val is a variable to receive the value read from the board.

Details

See the VISA library documentation for further details.

This function is untested.

viOut8 (vi , space , offset , val)

Writes a one-byte value to a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

val is a value to write to the board.

Details

See the VISA library documentation for further details.

This function is untested.

viIn16 (vi , space , offset , val)

Reads a two-byte value from a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

val is a variable to receive the value read from the board.

Details

See the VISA library documentation for further details.

This function is untested.

viOut16 (vi , space , offset , val)

Writes a two-byte value to a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

val is a value to write to the board.

Details

See the VISA library documentation for further details.

This function is untested.

viIn32 (vi , space , offset , val)

Reads a four-byte value from a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

val is a variable to receive the value read from the board.

Details

See the VISA library documentation for further details.

This function is untested.

viOut32 (vi , space , offset , val )

Writes a four-byte value to a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

val is a value to write to the board.

Details

See the VISA library documentation for further details.

This function is untested.

viMoveIn8 (vi , space , offset , length , buf )

Reads multiple one-byte values from a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

length is the number of one-byte values to read.

buf is a wave to receive the values read from the board. The wave must be a signed or unsigned byte (8-bit integer) wave and must be at least as long as length.

Details

See the VISA library documentation for further details.

This function is untested.

viMoveOut8 (vi , space , offset , length , buf )

Writes multiple one-byte values to a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

length is the number of one-byte values to write.

buf is a wave containing the values write to the board. The wave must be a signed or unsigned byte (8-bit integer) wave and must be at least as long as length.

Details

See the VISA library documentation for further details.

This function is untested.

viMoveIn16 (vi , space , offset , length , buf )

Reads multiple two-byte values from a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

length is the number of two-byte values to read.

buf is a wave to receive the values read from the board. The wave must be a signed or unsigned short (16-bit integer) wave and must be at least as long as length.

Details

See the VISA library documentation for further details.

This function is untested.

viMoveOut16 (vi , space , offset , length , buf )

Writes multiple two-byte values to a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

length is the number of two-byte values to write.

buf is a wave containing the values write to the board. The wave must be a signed or unsigned short (16-bit integer) wave and must be at least as long as length.

Details

See the VISA library documentation for further details.

This function is untested.

viMoveIn32 (vi, space, offset, length, buf)

Reads multiple four-byte values from a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

length is the number of four-byte values to read.

buf is a wave to receive the values read from the board. The wave must be a signed or unsigned long (32-bit integer) and must be at least as long as length.

Details

See the VISA library documentation for further details.

This function is untested.

viMoveOut32 (vi, space, offset, length, buf )

Writes multiple four-byte values to a VXI board. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

space is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE.

offset is the offset of the register to read.

length is the number of four-byte values to write.

buf is a wave containing the values write to the board. The wave must be a signed or unsigned long (32-bit integer) wave and must be at least as long as length.

Details

See the VISA library documentation for further details.

This function is untested.

viMapAddress (vi, mapSpace, mapOffset, mapSize , access, suggested, address )

Maps VXI register space into memory space. Not supported by TekVISA.

This function is for expert VXI bus users.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

mapSpace is VI_A16_SPACE, VI_A24_SPACE or VI_A32_SPACE (defined in VISA.ipf).

mapSize specifies the number of bytes to map.

access must always be zero.

suggested is a suggested memory address or VI_NULL.

address is an output and specifies the mapped address. This is passed to one of the viPeek or viPoke routines.

Details

See the VISA library documentation for further details.

This function is untested.

viUnmapAddress (vi)

Frees up memory space previously mapped by viMapAddress. Not supported by TekVISA.

This function is for expert VXI bus users.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

Details

See the VISA library documentation for further details.

This function is untested.

viPeek8 (vi, address, val)

Reads a one-byte value using an address obtained from viMapAddress. Not supported by TekVISA.

This function is for expert VXI bus users.

The function result is always VI_SUCCESS (0).

Parameters

vi is a session identifier returned by viOpen.

address is an address obtained from viMapAddress.

val is an output and is the value read.

Details

See the VISA library documentation for further details.

This function is untested.

viPoke8 (vi , address, val)

Writes a one-byte value using an address obtained from viMapAddress. Not supported by TekVISA.

This function is for expert VXI bus users.

The function result is always VI_SUCCESS (0).

Parameters

vi is a session identifier returned by viOpen.

address is an address obtained from viMapAddress.

val is the value to be written.

Details

See the VISA library documentation for further details.

This function is untested.

viPeek16 (vi, address, val)

Reads a two-byte value using an address obtained from viMapAddress. Not supported by TekVISA.

This function is for expert VXI bus users.

The function result is always VI_SUCCESS (0).

Parameters

vi is a session identifier returned by viOpen.

val is an output and is the value read.

address is an address obtained from viMapAddress.

Details

See the VISA library documentation for further details.

This function is untested.

viPoke16 (vi, address, val)

Writes a two-byte value using an address obtained from viMapAddress. Not supported by TekVISA.

This function is for expert VXI bus users.

The function result is always VI_SUCCESS (0).

Parameters

vi is a session identifier returned by viOpen.

address is an address obtained from viMapAddress.

val is the value to be written.

Details

See the VISA library documentation for further details.

This function is untested.

viPeek32 (vi, address, val)

Reads a four-byte value using an address obtained from viMapAddress. Not supported by TekVISA.

This function is for expert VXI bus users.

The function result is always VI_SUCCESS (0).

Parameters

vi is a session identifier returned by viOpen.

val is an output and is the value read.

address is an address obtained from viMapAddress.

Details

See the VISA library documentation for further details.

This function is untested.

viPoke32 (vi, address, val)

Writes a four-byte value using an address obtained from viMapAddress. Not supported by TekVISA.

This function is for expert VXI bus users.

The function result is always VI_SUCCESS (0).

Parameters

vi is a session identifier returned by viOpen.

address is an address obtained from viMapAddress.

val is the value to be written.

Details

See the VISA library documentation for further details.

This function is untested.

viMemAlloc (vi, size, offset)

Allocates memory on a VXI board. The memory can be accessed using viMove functions. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

size is the number of bytes to allocate.

offset is an output and is used with viMove functions to access the memory.

Details

Call viMemFree to free the memory.

See the VISA library documentation for further details.

This function is untested.

viMemFree (vi, offset)

Frees memory allocated with viMemAlloc. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

offset is the value returned by viMemAlloc.

Details

See the VISA library documentation for further details.

This function is untested.

viGpibControlREN (vi, mode)

Controls the GPIB remote-enable line. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

mode specifies the state of the REN line.

Details

See the VISA library documentation for further details.

This function is untested.

viGpibControlATN (vi, mode)

Controls the GPIB attention line. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

mode specifies the state of the ATN line.

Details

See the VISA library documentation for further details.

This function is untested.

viGpibSendIFC (vi)

Sends the GPIB interface-clear signal. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

Details

See the VISA library documentation for further details.

This function is untested.

viGpibCommand (vi, cmd, cnt, retCnt)

Controls the GPIB attention line. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

cmd is a signed or unsigned byte (8-bit integer) wave containing the data to sent. It must be at least as long as cnt .

cnt is the number of bytes to write.

retCnt is an output and returns the number of bytes actually written.

Details

See the VISA library documentation for further details.

This function is untested.

viGpibPassControl (vi, primAddr, secAddr)

Passes GPIB control to another controller. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

primAddr is the primary address of the new controller.

secAddr is the secondary address of the new controller or VI_NO_SEC_ADDR (a constant defined in VISA.ipf).

Details

See the VISA library documentation for further details.

This function is untested.

viVxiCommandQuery (vi, mode, cmd, response)

Sends a command or query to a VXI device. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

mode determines whether to send a command and/or get a response.

cmd is the command to send.

response is an output and returns the response from the device.

Details

See the VISA library documentation for further details.

This function is untested.

viAssertUtilSignal (vi, line)

Controls a utility bus signal. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

line is VI_UTIL_ASSERT_SYSRESET, VI_UTIL_ASSERT_SYSFAIL or VI_UTIL_DEASSERT_SYSFAIL.

Details

See the VISA library documentation for further details.

This function is untested.

viAssertIntrSignal (vi, mode, statusID)

Controls a utility bus signal. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

mode specifies how to assert interrupt.

statusID is the value used during interrupt acknowledgment.

Details

See the VISA library documentation for further details.

This function is untested.

viMapTrigger (vi, trigSrc, trigDest, mode)

Maps a trigger source to a trigger destination. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

trigSrc specifies the trigger source.

trigSrc specifies the trigger destination.

mode must always be zero.

Details

See the VISA library documentation for further details.

This function is untested.

viUnmapTrigger (vi, trigSrc, trigDest)

Unmaps a trigger signal. Not supported by TekVISA.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

trigSrc specifies the trigger source.

trigSrc specifies the trigger destination.

Details

See the VISA library documentation for further details.

This function is untested.

viUsbControlOut (vi, bmRequestType, bRequest, wValue, wIndex, wLength, buf )

Sends data to a USB device. Not supported by TekVISA.

Use of this function requires a detailed knowledge of the low-level operation of the USB.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

bmRequestType, bRequest, wValue, wIndex, wLength are explained in the NI-VISA Programmers Manual.

buf is a signed or unsigned byte (8-bit integer) wave containing the data to sent. It must be at least as long as wLength.

Details

See the VISA library documentation for further details.

This function is untested.

viUsbControlIn (vi, bmRequestType, bRequest, wValue, wIndex, wLength, buf, retCnt)

Reads data from a USB device. Not supported by TekVISA.

Use of this function requires a detailed knowledge of the low-level operation of the USB.

The function result is a VISA status code.

Parameters

vi is a session identifier returned by viOpen.

bmRequestType, bRequest, wValue, wIndex, wLength are explained in the NI-VISA Programmers Manual.

buf is a signed or unsigned byte (8-bit integer) wave into which data is read. It must be at least as long as wLength.

Details

See the VISA library documentation for further details.

This function is untested.

VISA XOP Operations

The VISA XOP adds the following command line operations to Igor. These operations provide higher level capabilities than the VISA XOP functions.

Operation	Details
VISAControl	Controls various aspects of the VISA XOP
VISARead	For reading ASCII data into Igor variables or strings
VISAWrite	For writing ASCII data strings
VISAReadWave	For reading ASCII data into Igor waves
VISAWriteWave	For writing ASCII data from Igor waves
VISAReadBinary	For reading binary data into Igor variables or strings
VISAWriteBinary	For writing binary data from Igor variables or strings
VISAReadBinaryWave	For reading binary data into Igor waves
VISAWriteBinaryWave	For writing binary data from Igor waves

The VISARead, VISAWrite, VISAReadWave, VISAWriteWave, VISAReadBinary, VISAWriteBinary, VISAReadBinaryWave and VISAWriteBinaryWave, operations are collectively called "read/write" operations. These work at a level higher than the VISA XOP functions. For most data transfer operations, you can use these high level calls.

(In addition to these higher-level operations, VISA XOP also adds low-level VISA XOP Functions.)

Errors and Status Codes From VISA XOP Operations

VISA XOP operations return an error to Igor in the event of an error, whether this is an Igor error (e.g., "attempt to use a null wave") or a VISA library error (e.g., VI_ERROR_TMO). This is in contrast to low-level VISA XOP functions which do not return VISA library errors as errors to Igor.

In addition, the operations set the variables V_flag and V_status which you can use to determine what occurred. V_flag gives information about the overall success of the operation. V_status is the status code returned from the last VISA library function call made by the operation or -1 if the error occurred before any calls the the library.

When the operation returns an error to Igor, by default Igor will stop running procedures and display an error dialog. For most purposes this is sufficient. However if you are trying to write a bulletproof set of routines for use by a wide audience you may want to implement more sophisticated error handling. In that case, you must check for runtime errors after calling the operation.

Here is an example. The function result is an Igor error code, 0 for success or a non-zero value indicating an error occurred. In addition, the function returns the VISA library status code via the output parameter status.

Function Test(instr, status)
    Variable instr      // An instrument referenced obtained from viOpen.
    Variable &status    // Output: Status code from VISA library or -1.

    Variable err = 0
    Variable v1
    VISARead instr, v1  // Sets V_flag and V_status.

    // Check for VISA library error
    err = GetRTError(1) // Clear runtime error so Igor will not abort

    if (err != 0)       // VISARead failed?
        status = V_status
        return err      // Let calling routine deal with error if any.
    endif

    status = VI_SUCCESS
    return 0	// 0 indicates success.
End

For an example of printing an error message based on a VISA status code, see the example under viStatusDesc.

VISA XOP Operations Versus NIGPIB2 and VDT2 Operations

The VISA XOP operations are very similar to operations provided by Igor's NIGPIB2 and VDT2 XOPs. If you have used NIGPIB2 or VDT2, the VISA XOP operations work nearly the same.

The only major difference is that the VISA XOP operations take a session parameter which identifies the instrument you want to work with. You obtain a value for the session parameter using the viOpen function. This is in contrast to NIGPIB2 operations which work on a device specified using the "GPIB device" command and VDT2 operations which work on a serial port specified using the VDTOperationsPort operation.

VISAControl [/Q] testMode=mode, dumpTestBuffer, clearTestBuffer, killIO

The VISAControl operation provides control over miscellaneous VISA XOP features.

VISAControl sets V_Flag to zero if no error occurred or to non-zero if an error did occur.

Flags


/Q	Do not report errors to Igor.
	Without /Q, if an error occurs during execution of VISAControl, VISAControl returns an error to Igor which causes function execution to abort.

Keywords


testMode = mode	mode=1 puts VISA XOP in a test mode. This is used only by WaveMetrics for self-testing of VISA XOP.
dumpTestBuffer	Dumps the test data buffer. This is used only by WaveMetrics for self-testing of VISA XOP.
clearTestBuffer	Clears the test data buffer. This is used only by WaveMetrics for self-testing of VISA XOP.
killIO	Closes all open default resource manager sessions which in turn closes all open sessions of all kinds.
	Use this during development to return the VISA library to an initialized state. After you execute VISAControl killIO, any sessions that you obtained from viOpen are no longer valid.
	VISA XOP also closes all open VISA sessions when Igor quits.

VISARead [/T=termStr /N=n /Q] session, variableName [, variableName]

Reads from the device specified by session into one or more string or numeric variables.

Parameters

session is a session to an instrument obtained by calling viOpen.

When used from the command line or in a macro, variableName must be the name of a local or global variable in the current data folder. When used from a user function, variableName can be the name of a local variable or the name of an NVAR or SVAR referencing a global variable in any data folder.

Flags


/T = termStr	termStr is a string or string expression specifying characters which terminate a read of a single variable. The default is /T=",\r\t".
	If termStr is not "", VISARead reads bytes one-at-a-time and is not affected by the VISA `VI_ATTR_TERMCHAR` or `VI_ATTR_ASRL_END_IN` attributes. It terminates the read only when a terminator specified by /T is received or (with GPIB devices) the END signal is received.
	If termStr is "", VISARead reads the number of bytes specified by /N=n in one VISA library call. This runs quickly but the VISA library may terminate the read prematurely unless you set the appropriate attributes. See VISA Library Terminator Character Issues for details.
/N = n	n is maximum number of characters to read for each variable.
/Q	Specifies no error message on timeout.

Details

VISARead sets the variable V_Flag to the number of items read.

VISARead internally calls the VISA library viRead function and sets the variable V_status to the status code returned from the last call to viRead or -1 if the error occurred before any calls the the library. This can be used to determine what went wrong in the event of an error.

Here is a discussion of how VISARead goes about trying to read into its argument list.

If the /T=termStr flag is present, it specifies a terminator character or characters. The terminator is the character that ends input into a string or numeric variable. The default is /T=",\r\t" so that a comma, carriage return or tab ends a read. When dealing with a GPIB device, the read is also ended if the talker asserts the GPIB END signal.

note

VISARead is not affected by the VISA VI_ATTR_TERMCHAR attribute. It terminates the read only when a terminator specified by /T is received or (with GPIB devices) the END signal is received.

/N=n is an optional maximum number of characters to be read into a string or numeric variable. The default is /N=255.

If /Q is present and a timeout occurs, VISARead aborts after setting the variable V_Flag to the number of items read but does not put up an error message and does not halt procedure execution. This allows a procedure to handle a timeout in its own way.

When reading a string, VISARead reads until the next terminator is encountered. The terminator is not put into the string. The next read starts after the terminator.

Do not use VISARead to read binary data or anything that contains a null character (ASCII 0). Use VISAReadBinary instead.

When reading a numeric variable, VISARead first skips any non-numeric characters and then reads a number. If the variableName refers to a complex variable, VISARead reads two numbers from the device and stores both the real and imaginary parts of the variable.

Example

Function Test(instr)
    Variable instr	// An instrument referenced obtained from viOpen

    Variable v1, v2
    String s1
    VISARead instr, v1, s1, v2
End

This reads from the device referenced by instr into variable v1, string variable s1 and variable v2.

Terminators

There are three common cases to consider:

Instruments that send CR as terminator
Instruments that send CR and LF as terminator
Instruments that send neither CR nor LF but use the END line only.

You must determine what terminator your instrument sends from its documentation.

The following examples show how you would read a response in the three cases into a string variable. str1 is an Igor string variable.

// CR terminator
String str1
VISARead str1	// Read the string till CR

// CRLF terminator
String str1, lf
VISARead/T="\r\n" str1, lf	// Read the string till CR, then read LF.

// END terminator
String str1
VISARead str1	// Read the string till END

The following examples show how you would read a response in the three cases into a numeric variable.

// CR terminator
Variable v0
VISARead v0	// Read the number till CR

// CRLF terminator
Variable v0
String lf
VISARead/T="\r\n" v0, lf	// Read the number till CR, then read LF.

// END terminator
VISARead v0	// Read the string till END

If you expected <number><comma><number><comma><number><crlf>, here is what you would do:

Variable v0, v1, v2
String lf
VISARead/T=",\r\n" v0, v1, v2, lf

When dealing with a GPIB device, you may want to read every character into a string until END is asserted. To do this you can specify an empty terminator:

VISARead/T="" str1

VISAReadWave [ /R=[start, end] /T=termStr /N=n /Q ] session, waveName [, waveName]

Reads data from device into waves.

Parameters

session is a session to an instrument obtained by calling viOpen.

The waves must be 1-dimensional and can be numeric or text waves. For numeric waves only, complex waves are supported and VISAReadWave reads two values for each wave point.

Assuming the the /R flag is omitted, data is stored into point 0 of each wave, then point 1 of each wave, and so on.

Flags


/N = n	n is maximum number of characters to read for each value. The default is 255.
/Q	Specifies no error message on timeout.
/R = [ start, end ]	Specifies the starting and ending point numbers for a range of the waves that you want to read data into.
/T = termStr	termStr is a string or string expression specifying characters which terminate a read of a single number. The default is /T=",\r\t".
	If termStr is not "", VISAReadWave reads bytes one-at-a-time and is not affected by the VISA `VI_ATTR_TERMCHAR` or `VI_ATTR_ASRL_END_IN` attributes. It terminates the read only when a terminator specified by /T is received or (with GPIB devices) the END signal is received.
	If termStr is "", VISAReadWave reads the number of bytes specified by /N=n in one VISA library call. This runs quickly but the VISA library may terminate the read prematurely unless you set the appropriate attributes. See VISA Library Terminator Character Issues for details.

Details

If the /R flag is omitted, VISAReadWave stores values in point 0 through point n-1 where n is the number of points in the first wave.

VISAReadWave sets the variable V_flag to the number of individual numbers read.

VISAReadWave internally calls the VISA library viRead function and sets the variable V_status to the status code returned from the last call to viRead or -1 if the error occurred before any calls the the library. This can be used to determine what went wrong in the event of an error.

VISAReadWave works with 64-bit integer data but is limited to 53 bits of precision. See VISA XOP 64-bit Integer Limitations for details.

Example

Function Test(instr)
    Variable instr              // An instrument referenced obtained from viOpen

    WAVE wave1, wave2, wave3    // Reference to waves in current data folder.
    VISAReadWave instr, wave1, wave2, wave3
End

This reads from the device into wave1, wave2 and wave3. It reads until it has put a value in each point of each wave.

Terminators

See the discussion of terminators for the VISARead operation.

VISAReadBinary [ /B /Q /S=strLen /T=termStr /TYPE=type /Y={offset , multiplier }] session, variableName [,variableName]

Reads binary data into Igor strings and variables. The binary data can be read as integers of one, two or four bytes, 32-bit IEEE floating point or 64-bit IEEE floating point.

Parameters

session is a session to an instrument obtained by calling viOpen.

If /S=strLen is used, the arguments are expected to be string variables and bytes are read up to strLen bytes or until a byte is read from GPIB with END asserted or until a byte specified by /T=termStr is read.

If /S=strLen is NOT used, the arguments are expected to be numeric variables into which data is to be read.

Reading binary data into strings is used mostly to skip a number of bytes or until a certain byte is received. To read actual ASCII data into strings, use VISARead instead of VISAReadBinary.

Flags


/B	Indicates that multi-byte data is to be received low-byte-first. Without /B, multi-byte data is received high-byte-first. This flag affects receiving of numeric data only, not string data.
/Q	Specifies no error message on timeout.
/S = strLen	If present, the variables are expected to be string variables. Bytes are read up to strLen bytes or until a byte is read with END asserted or until a byte specified by /T=termStr is read.
/T = termStr	Specifies a terminator character when reading bytes into strings. The default value is "" (no terminators). The read will be faster if no terminators are specified. This has no effect when reading into numeric variables.
	If termStr is not "", VISAReadBinary reads bytes one-at-a-time and is not affected by the VISA `VI_ATTR_TERMCHAR` or `VI_ATTR_ASRL_END_IN` attributes. It terminates the read only when a terminator specified by /T is received or (with GPIB devices) the END signal is received.
	If termStr is "", VISAReadBinary reads the number of bytes specified by /N=n in one VISA library call. This runs quickly but the VISA library may terminate the read prematurely unless you set the appropriate attributes. See VISA Library Terminator Character Issues for details.
/TYPE = type	Specifies the format of the incoming binary data. See WaveType for the definition of type . The default value is 8 (signed byte).
/Y = {o, m}	o is offset, m is multiplier. /Y is used to scale integer data into real numbers. output data = (input data + offset) * multiplier.

Details

If a numeric variable is complex, VISAReadBinary reads two values for that variable.

VISAReadBinary sets the variable V_flag, after creating it if necessary, to the number of items read.

VISAReadBinary internally calls the VISA library viRead function and sets the variable V_status to the status code returned from the last call to viRead or -1 if the error occurred before any calls the the library. This can be used to determine what went wrong in the event of an error.

VISAReadBinary works with 64-bit integer data but is limited to 53 bits of precision. See VISA XOP 64-bit Integer Limitations for details.

Examples

Function Test(instr)
    Variable instr  // An instrument referenced obtained from viOpen

    // Read 10 bytes or until END is received into string variable str1.
    String str1
    VISAReadBinary/S=10 instr, str1

    // Read two-byte signed integer binary numbers into the numeric variables v0 and v1.
    Variable v0, v1
    VISAReadBinary/TYPE=(0x10) instr, v0, v1        // Read big-endian data.
    VISAReadBinary/TYPE=(0x10)/B instr, v0, v1      // Read little-endian data.

    // Read four-byte IEEE single-precision floating point binary numbers into v0 and v1.
    VISAReadBinary/TYPE=2 instr, v0, v1             // Read big-endian data.
    VISAReadBinary/TYPE=2/B instr, v0, v1           // Read little-endian data.
End

VISAReadBinaryWave [ /B /Q /TYPE=type /Y={offset, multiplier} ] session, waveName [,waveName]

Reads binary data into the numeric waves named in wavelist. The waves can be of any numeric data type, real or complex.

Parameters

session is a session to an instrument obtained by calling viOpen.

Flags


/B	Indicates that multi-byte data is to be received low-byte-first. Without /B, multi-byte data is received high-byte-first.
/Q	Specifies no error message on timeout.
/TYPE = type	Specifies the format of the incoming binary data. See WaveType for the definition of type. The default value is 8 (signed byte).
/Y = {o, m}	o is offset, m is multiplier. /Y is used to scale integer data into real numbers.
	`output data = (input data + offset) * multiplier`

Details

When reading binary data into a string, the VISA library may terminate the read prematurely unless you set the appropriate attributes. See VISA Library Terminator Character Issues for details.

If multiple waves are specified, all of the values for the first wave are read, followed by all of the values for the second wave, and so on.

If a wave is complex, VISAReadBinaryWave reads two values for each point in that wave. This is true regardless of the /TYPE=type flag.

VISAReadBinaryWave sets the variable V_flag, after creating it if necessary, to the number of waves (not points) read.

VISAReadBinaryWave internally calls the VISA library viRead function and sets the variable V_status to the status code returned from the last call to viRead or -1 if the error occurred before any calls the the library. This can be used to determine what went wrong in the event of an error.

Examples

Function Test(instr)
    Variable instr	// An instrument referenced obtained from viOpen

    // Reads two-byte signed integer binary numbers into each point of wave.
    VISAReadBinaryWave/TYPE=(0x10) instr, wave0                     // Big-endian data.
    VISAReadBinaryWave/TYPE=(0x10)/B instr, wave0                   // Little-endian data.

    // Reads a four byte signed integer binary number into each point of wave0,
    // wave1 and wave2. All of wave0 is read first, then all of wave1, then all of wave2.
    VISAReadBinaryWave/TYPE=(0x20) instr, wave0, wave1, wave2       // Big-endian data.
    VISAReadBinaryWave/TYPE=(0x20)/B instr, wave0, wave1, wave2     // Little-endian data.

    // Reads two-byte signed integer binary numbers into each point of wave.
    // Then it adds 0 to each point and multiplies by .25. This would be used
    // to scale integer data where 1 count represents .25 volts, for example.
    VISAReadBinaryWave/TYPE=(0x10)/Y={0,0.25} instr, wave0          // Big-endian data.
    VISAReadBinaryWave/TYPE=(0x10)/Y={0,0.25}/B instr, wave0        // Little-endian data.
End

VISAWrite [/Q] session, str

Transmits contents of the string argument.

Parameters

session is a session to an instrument obtained by calling viOpen.

str is a string expression.

Flags


/Q	Specifies no error message on timeout.

Details

VISAWrite sets the variable V_flag to 1 if the write succeeded or to zero otherwise.

VISAWrite internally calls the VISA library viWrite function and sets the variable V_status to the status code returned from the last call to viWrite or -1 if the error occurred before any calls the the library. This can be used to determine what went wrong in the event of an error.

Examples

Function Test(instr)
    Variable instr	// An instrument referenced obtained from viOpen

    // Transmits a greeting followed by a carriage return.
    VISAWrite instr, "Hello" + "\r"

    // Transmits the contents of variable v1, the sine of .5 radians and the contents of
    // point 0 of wave1, separated by tabs with a carriage return and linefeed at the end.

    Variable v1 = 1234
    Wave wave1
    String str
    sprintf str, "%g\t%g\t%g\r\n", v1, sin(.5), wave1[0]
    VISAWrite instr, str
End

VISAWriteWave [ /R=[start, end] /F={numericFormatStr, leaderStr, separatorStr, terminatorStr} /Q ] session, waveName [,waveName]

Transmits contents of wave or waves as text.

The waves must be 1-dimensional and can be numeric or text waves. For numeric waves only, complex waves are supported and VISAWriteWave writes two values for each wave point.

Parameters

session is a session to an instrument obtained by calling viOpen.


/F = {numericFormatStr, leaderStr, separatorStr, terminatorStr }
	numericFormatStr is the numeric format string used to generate the output text for each numeric wave point. VISAWriteWave passes this string to the C sprintf function. The default value is "%g".
	Only numeric formats are allowed. numericFormatStr must end with a numeric conversion character. See Printf for details on formats.
	leaderStr is text that is inserted at the start of each line of data. The default is "".
	separatorStr is text that is inserted between each pair of points. The default is "\t" (tab).
	terminatorStr is text that is written at the end of each line of data. The default is "\r" (carriage-return).
/R = [start,end]	Specifies the starting and ending point numbers for a range of the waves that you want to write data from.
/Q	Specifies no error message on timeout.

Details

If the /R flag is omitted, VISAWriteWave writes values for point 0 through point n-1 where n is the number of points in the first wave.

VISAWriteWave sets the variable V_flag, after creating it if necessary, to the number of individual numbers written.

VISAWriteWave internally calls the VISA library viWrite function and sets the variable V_status to the status code returned from the last call to viWrite or -1 if the error occurred before any calls the the library. This can be used to determine what went wrong in the event of an error.

VISAWriteWave works with 64-bit integer data but is limited to 53 bits of precision. See VISA XOP 64-bit Integer Limitations for details.

Examples

Function Test(instr)
    Variable instr	// An instrument referenced obtained from viOpen

    // Transmits contents of the waves as text, using 15 digits of precision
    // with a comma between numbers and CRLF at the end of each line.
    VISAWriteWave/F={"%.15g", "", ",", "\r\n"} instr, wave1, wave2, wave3
End

VISAWriteBinary [ /B /Q /TYPE=type ] session, argument [,argument]

Transmits contents of the argument or arguments as binary data. The binary data can be sent as integers of one-, two- or four-bytes, 32-bit IEEE floating point or 64-bit IEEE floating point.

Parameters

session is a session to an instrument obtained by calling viOpen.

argument is a numeric expression.

Flags


/B	Indicates that multi-byte data is to be sent low-byte-first. Without /B, multi-byte data is sent high-byte-first.
/Q	Specifies no error message on timeout.
/TYPE = type	Specifies the format in which the binary data is transmitted. See WaveType for the definition of type. The default value is 8 (signed byte).

Details

VISAWriteBinary sets the variable V_flag, after creating it if necessary, to the number of items written.

VISAWriteBinary internally calls the VISA library viWrite function and sets the variable V_status to the status code returned from the last call to viWrite or -1 if the error occurred before any calls the the library. This can be used to determine what went wrong in the event of an error.

VISAWriteBinary can not transmit strings. Use VISAWrite for that. VISAWriteBinary can also not transmit complex values.

VISAWriteBinary works with 64-bit integer data but is limited to 53 bits of precision. See VISA XOP 64-bit Integer Limitations for details.

Examples

Function Test(instr)
    Variable instr	// An instrument referenced obtained from viOpen

    // Writes 123 and -456 as two byte signed integer binary numbers.
    VISAWriteBinary/TYPE=(0x10) instr, 123, -456        // Big-endian
    VISAWriteBinary/TYPE=(0x10)/B instr, 123, -456      // Little-endian

    // Writes 2*PI and -PI/2 as 32-bit IEEE floating point binary numbers
    VISAWriteBinary/TYPE=2 instr, 2*PI, -PI/2           // Big-endian
    VISAWriteBinary/TYPE=2/B instr, 2*PI, -PI/2         // Little-endian
End

VISAWriteBinaryWave [ /B /Q /TYPE=type ] session, waveName [,waveName]

Writes binary data from the listed waves. The waves can be of any numeric data type.

Parameters

session is a session to an instrument obtained by calling viOpen.

Flags


/B	Indicates that multi-byte data is to be sent low-byte-first. Without /B, multi-byte data is sent high-byte-first.
/Q	Specifies no error message on timeout.
/TYPE = type	Specifies the format in which the binary data is transmitted. See WaveType for the definition of type. The default value is 8 (signed byte).

Details

The waves can be of any numeric data type, real or complex.

If multiple waves are specified, all of the values for the first wave are written, followed by all of the values for the second wave, and so on.

If a wave is complex, VISAWriteBinaryWave writes two values for each point in that wave. This is true regardless of the /TYPE=type flag.

VISAWriteBinaryWave sets the variable V_flag, after creating it if necessary, to the number of waves (not points) written.

VISAWriteBinaryWave internally calls the VISA library viWrite function and sets the variable V_status to the status code returned from the last call to viWrite or -1 if the error occurred before any calls the the library. This can be used to determine what went wrong in the event of an error.

Examples

Function Test(instr)
    Variable instr	// An instrument referenced obtained from viOpen

    // Writes each point of wave0 as a two-byte signed integer binary number.
    VISAWriteBinaryWave/TYPE=(0x10) instr, wave0                    // Big-endian
    VISAWriteBinaryWave/TYPE=(0x10)/B instr, wave0                  // Little-endian

    // Writes all of wave0 as a four-byte signed integer binary number,
    // followed by all of wave1 and then all of wave2.
    VISAWriteBinaryWave/TYPE=(0x20) instr, wave0, wave1, wave2      // Big-endian
    VISAWriteBinaryWave/TYPE=(0x20)/B instr, wave0, wave1, wave2    // Little-endian

    // Writes each point of wave0 as a 32-bit IEEE floating point binary number.
    VISAWriteBinaryWave/TYPE=2 instr, wave0                         // Big-endian
    VISAWriteBinaryWave/TYPE=2/B instr, wave0                       // Little-endian
End

Resource Manager
Resource Template
Basic I/O
Formatted and Buffered I/O
Memory I/O
Shared Memory
Interface Specific
Errors and Status Codes From VISA XOP Functions
viOpenDefaultRM (session)
- Parameters
- Details
- See Also
viOpen (session , resourceName , accessMode , openTimeout , instr )
- Parameters
- Details
- Examples
- See Also
viFindRsrc (session , expr , findList , retcnt , instrDesc )
- Parameters
- Details
- Examples
- See Also
viFindNext (findList , instrDesc )
- Parameters
- Details
- Examples
- See Also
viClose (session )
- Parameters
- Details
- See Also
viSetAttribute (vi , attribute , attrState )
- Parameters
- Details
- Example
- See Also
viSetAttributeString (vi , attribute , attrStateStr )
- Parameters
- Details
- See Also
viGetAttribute (vi , attribute , attrState )
- Parameters
- Details
- Example
- See Also
viGetAttributeString (vi , attribute , attrStateStr )
- Parameters
- Details
- Example
- See Also
viStatusDesc (vi , status , desc )
- Parameters
- Details
- Example
- See Also
viTerminate (vi , degree , jobId )
- Parameters
- Details
viLock (vi , lockType , timeout , requestedKeyStr , accessKeyStr )
- Parameters
- Details
- See Also
viUnlock (vi)
- Parameters
- Details
- See Also
viEnableEvent (vi , eventType , mechanism, context )
- Parameters
- Details
- See Also
viDisableEvent (vi , eventType , mechanism, context )
- Parameters
- Details
- See Also
viDiscardEvents (vi , eventType , mechanism, context )
- Parameters
- Details
- See Also
viWaitOnEvent (vi , inEventType , timeout , outEventType , outContext)
- Parameters
- Details
- See Also
viRead (vi , buf , cnt , retCnt)
- Parameters
- Details
- See Also
viWrite (vi , buf , cnt , retCnt)
- Parameters
- Details
- See Also
viAssertTrigger (vi , protocol )
- Parameters
- Details
- See Also
viReadSTB (vi , status)
- Parameters
- Details
- See Also
viClear (vi )
- Parameters
- Details
- See Also
viIn8 (vi , space , offset , val)
- Parameters
- Details
- See Also
viOut8 (vi , space , offset , val)
- Parameters
- Details
- See Also
viIn16 (vi , space , offset , val)
- Parameters
- Details
- See Also
viOut16 (vi , space , offset , val)
- Parameters
- Details
- See Also
viIn32 (vi , space , offset , val)
- Parameters
- Details
- See Also
viOut32 (vi , space , offset , val )
- Parameters
- Details
- See Also
viMoveIn8 (vi , space , offset , length , buf )
- Parameters
- Details
- See Also
viMoveOut8 (vi , space , offset , length , buf )
- Parameters
- Details
- See Also
viMoveIn16 (vi , space , offset , length , buf )
- Parameters
- Details
- See Also
viMoveOut16 (vi , space , offset , length , buf )
- Parameters
- Details
- See Also
viMoveIn32 (vi, space, offset, length, buf)
- Parameters
- Details
- See Also
viMoveOut32 (vi, space, offset, length, buf )
- Parameters
- Details
- See Also
viMapAddress (vi, mapSpace, mapOffset, mapSize , access, suggested, address )
- Parameters
- Details
- See Also
viUnmapAddress (vi)
- Parameters
- Details
- See Also
viPeek8 (vi, address, val)
- Parameters
- Details
- See Also
viPoke8 (vi , address, val)
- Parameters
- Details
- See Also
viPeek16 (vi, address, val)
- Parameters
- Details
- See Also
viPoke16 (vi, address, val)
- Parameters
- Details
- See Also
viPeek32 (vi, address, val)
- Parameters
- Details
- See Also
viPoke32 (vi, address, val)
- Parameters
- Details
- See Also
viMemAlloc (vi, size, offset)
- Parameters
- Details
- See Also
viMemFree (vi, offset)
- Parameters
- Details
- See Also
viGpibControlREN (vi, mode)
- Parameters
- Details
- See Also
viGpibControlATN (vi, mode)
- Parameters
- Details
- See Also
viGpibSendIFC (vi)
- Parameters
- Details
- See Also
viGpibCommand (vi, cmd, cnt, retCnt)
- Parameters
- Details
- See Also
viGpibPassControl (vi, primAddr, secAddr)
- Parameters
- Details
- See Also
viVxiCommandQuery (vi, mode, cmd, response)
- Parameters
- Details
- See Also
viAssertUtilSignal (vi, line)
- Parameters
- Details
- See Also
viAssertIntrSignal (vi, mode, statusID)
- Parameters
- Details
- See Also
viMapTrigger (vi, trigSrc, trigDest, mode)
- Parameters
- Details
- See Also
viUnmapTrigger (vi, trigSrc, trigDest)
- Parameters
- Details
- See Also
viUsbControlOut (vi, bmRequestType, bRequest, wValue, wIndex, wLength, buf )
- Parameters
- Details
- See Also
viUsbControlIn (vi, bmRequestType, bRequest, wValue, wIndex, wLength, buf, retCnt)
- Parameters
- Details
- See Also
VISA XOP Operations
- Errors and Status Codes From VISA XOP Operations
- VISA XOP Operations Versus NIGPIB2 and VDT2 Operations
- VISAControl [/Q] testMode=mode, dumpTestBuffer, clearTestBuffer, killIO
  - Flags
  - Keywords
- VISARead [/T=termStr /N=n /Q] session, variableName [, variableName]
- VISAReadWave [ /R=[start, end] /T=termStr /N=n /Q ] session, waveName [, waveName]
- VISAReadBinary [ /B /Q /S=strLen /T=termStr /TYPE=type /Y={offset , multiplier }] session, variableName [,variableName]
- VISAReadBinaryWave [ /B /Q /TYPE=type /Y={offset, multiplier} ] session, waveName [,waveName]
- VISAWrite [/Q] session, str
- VISAWriteWave [ /R=[start, end] /F={numericFormatStr, leaderStr, separatorStr, terminatorStr} /Q ] session, waveName [,waveName]
- VISAWriteBinary [ /B /Q /TYPE=type ] session, argument [,argument]
- VISAWriteBinaryWave [ /B /Q /TYPE=type ] session, waveName [,waveName]

Resource Manager​

Resource Template​

Basic I/O​

Formatted and Buffered I/O​

Memory I/O​

Shared Memory​

Interface Specific​

Errors and Status Codes From VISA XOP Functions​

viOpenDefaultRM (session)​

Parameters​

Details​

See Also​

viOpen (session , resourceName , accessMode , openTimeout , instr )​

Parameters​

Details​

Examples​

See Also​

viFindRsrc (session , expr , findList , retcnt , instrDesc )​

Parameters​

Details​

Examples​

See Also​

viFindNext (findList , instrDesc )​

Parameters​

Details​

Examples​

See Also​

viClose (session )​

Parameters​

Details​

See Also​

viSetAttribute (vi , attribute , attrState )​

Parameters​

Details​

Example​

See Also​

viSetAttributeString (vi , attribute , attrStateStr )​

Parameters​

Details​

See Also​

viGetAttribute (vi , attribute , attrState )​

Parameters​

Details​

Example​

See Also​

viGetAttributeString (vi , attribute , attrStateStr )​

Parameters​

Details​

Example​

See Also​

viStatusDesc (vi , status , desc )​

Parameters​

Details​

Example​

See Also​

viTerminate (vi , degree , jobId )​

Parameters​

Details​

viLock (vi , lockType , timeout , requestedKeyStr , accessKeyStr )​

Parameters​

Details​

See Also​

viUnlock (vi)​

Parameters​

Details​

See Also​

viEnableEvent (vi , eventType , mechanism, context )​

Parameters​

Details​

See Also​

viDisableEvent (vi , eventType , mechanism, context )​

Parameters​

Details​

See Also​

viDiscardEvents (vi , eventType , mechanism, context )​

Parameters​

Details​

See Also​

viWaitOnEvent (vi , inEventType , timeout , outEventType , outContext)​

Parameters​

Resource Manager

Resource Template

Basic I/O

Formatted and Buffered I/O

Memory I/O

Shared Memory

Interface Specific

Errors and Status Codes From VISA XOP Functions

viOpenDefaultRM (session)

Parameters

Details

See Also

viOpen (session , resourceName , accessMode , openTimeout , instr )

Parameters

Details

Examples

See Also

viFindRsrc (session , expr , findList , retcnt , instrDesc )

Parameters

Details

Examples

See Also

viFindNext (findList , instrDesc )

Parameters

Details

Examples

See Also

viClose (session )

Parameters

Details

See Also

viSetAttribute (vi , attribute , attrState )

Parameters

Details

Example

See Also

viSetAttributeString (vi , attribute , attrStateStr )

Parameters

Details

See Also

viGetAttribute (vi , attribute , attrState )

Parameters

Details

Example

See Also

viGetAttributeString (vi , attribute , attrStateStr )

Parameters

Details

Example

See Also

viStatusDesc (vi , status , desc )

Parameters

Details

Example

See Also

viTerminate (vi , degree , jobId )

Parameters

Details

viLock (vi , lockType , timeout , requestedKeyStr , accessKeyStr )

Parameters

Details

See Also

viUnlock (vi)

Parameters

Details

See Also

viEnableEvent (vi , eventType , mechanism, context )

Parameters

Details

See Also

viDisableEvent (vi , eventType , mechanism, context )

Parameters

Details

See Also

viDiscardEvents (vi , eventType , mechanism, context )

Parameters

Details

See Also

viWaitOnEvent (vi , inEventType , timeout , outEventType , outContext)

Parameters