RULE 3.2.11 Every VISA system SHALL implement the following operations: viClose(), viGetAttribute(), viSetAttribute(), viStatusDesc(), viTerminate(), viLock(), viUnlock(), viEnableEvent(), viDisableEvent(), viDiscardEvents(), viWaitOnEvent(), viInstallHandler(), and viUninstallHandler().
Description The viGetAttribute() operation is used to retrieve the state of an attribute for the specified session, event, or find list. Related Items See viSetAttribute(). Implementation Requirements RULE 3.4.1 IF attribute is a string attribute, THEN viGetAttribute SHALL write no more than 256 characters into attrState, including the null character. OBSERVATION 3.4.1 RULE 3.4.1 states the maximum length of a VISA string attribute to be 255 characters. 3.4.1.2 viSetAttribute(vi, attribute, attrState) Purpose Set the state of an attribute. Parameters Name Direction Type Description vi IN ViSession ViEvent ViFindList Unique logical identifier to a session, event, or find list. attribute IN ViAttr Session, event, or find list attribute for which the state is modified. attrState IN ViAttrState The state of the attribute to be set for the specified resource. The interpretation of the individual attribute value is defined by the resource. Return Values Type ViStatus This is the operational return status. It returns either a completion code or an error code as follows. Completion Codes Description VI_SUCCESS Attribute value set successfully. VI_WARN_NSUP_ATTR_STATE Although the specified attribute state is valid, it is not supported by this implementation. Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value).
Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). VI_ERROR_INV_JOB_ID Specified job identifier is invalid. VI_ERROR_INV_DEGREE Specified degree is invalid. Description This operation requests a session to terminate normal execution of an operation, as specified by the jobId parameter. The jobId parameter is a unique value generated from each call to an asynchronous operation. If a user passes VI_NULL as the jobId value to viTerminate(), a VISA implementation should abort any calls in the current process executing on the specified vi. Any call that is terminated this way should return VI_ERROR_ABORT. Due to the nature of multi-threaded systems, for example where operations in other threads may complete normally before the operation viTerminate() has any effect, the specified return value is not guaranteed. Related Items viReadAsync(), viWriteAsync(), viMoveAsync(). Implementation Requirements There are no additional implementation requirements other than those specified above.
mechanism IN ViUInt16 Specifies event handling mechanisms to be enabled. The queuing mechanism is enabled by specifying VI_QUEUE, and the callback mechanism is enabled by specifying VI_HNDLR or VI_SUSPEND_HNDLR. It is possible to enable both mechanisms simultaneously by specifying "bit-wise OR" of VI_QUEUE and one of the two mode values for the callback mechanism. context IN ViEventFilter VI_NULL Return Values Type ViStatus This is the operational return status. It returns either a completion code or an error code as follows. Completion Codes Description VI_SUCCESS Event enabled successfully. VI_SUCCESS_EVENT_EN Specified event is already enabled for at least one of the specified mechanisms. Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). VI_ERROR_INV_EVENT Specified event type is not supported by the resource. VI_ERROR_INV_MECH Invalid mechanism specified. VI_ERROR_INV_CONTEXT Specified event context is invalid. VI_ERROR_HNDLR_NINSTALLED A handler is not currently installed for the specified event. The session cannot be enabled for the VI_HNDLR mode of the callback mechanism. VI_ERROR_NSUP_MECH The specified mechanism is not supported for the given event type. Description This operation enables notification of an event identified by the eventType parameter for mechanisms specified in the mechanism parameter. The specified session can be enabled to queue events by specifying VI_QUEUE. Applications can enable the session to invoke a callback function to execute the handler by specifying VI_HNDLR. The applications are required to install at least one handler to be enabled for this mode. Specifying VI_SUSPEND_HNDLR enables the session to receive callbacks, but the invocation of the handler is deferred to a later time. Successive calls to this operation replace the old callback mechanism with the new callback mechanism. Specifying VI_ALL_ENABLED_EVENTS for the eventType parameter refers to all events that have previously been enabled on this session, making it easier to switch between the two callback mechanisms for multiple events. Table 3.7.3 Special Values for eventType Parameter Value Action Description
accessMode IN ViAccessMode Specifies the modes by which the resource is to be accessed. The value VI_EXCLUSIVE_LOCK is used to acquire an exclusive lock immediately upon opening a session; if a lock cannot be acquired, the session is closed and an error is returned. The value VI_LOAD_CONFIG is used to configure attributes to values specified by some external configuration utility; if this value is not used, the session uses the default values provided by this specification. Multiple access modes can be used simultaneously by specifying a "bit-wise OR" of the above values. timeout IN ViUInt32 If the accessMode parameter requests a lock, then this parameter specifies the absolute time period (in milliseconds) that the resource waits to get unlocked before this operation returns an error. vi OUT ViSession Unique logical identifier reference to a session. Return Values Type ViStatus This is the operational return status. It returns either a completion code or an error code as follows. Completion Codes Description VI_SUCCESS Session opened successfully. VI_SUCCESS_DEV_NPRESENT Session opened successfully, but the device at the specified address is not responding. VI_WARN_CONFIG_NLOADED The specified configuration either does not exist or could not be loaded; using VISA-specified defaults. Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). VI_ERROR_NSUP_OPER The given sesn does not support this operation. For VISA, this operation is supported only by the Default Resource Manager session. VI_ERROR_INV_RSRC_NAME Invalid resource reference specified. Parsing error. VI_ERROR_INV_ACC_MODE Invalid access mode. VI_ERROR_RSRC_NFOUND Insufficient location information or resource not present in the system. VI_ERROR_ALLOC Insufficient system resources to open a session. VI_ERROR_RSRC_BUSY The resource is valid, but VISA cannot currently access it.
implementation allows multiple aliases for a single resource, then the implementation must pick one alias (in an implementation-defined manner) and return it in this parameter. Table 4.3.3 Special Values for rsrcClass Parameter Value Action Description VI_NULL Do not return the resource class. Table 4.3.4 Special Values for unaliasedExpandedRsrcName Parameter Value Action Description VI_NULL Do not return the full resource name. Table 4.3.5 Special Values for aliasIfExists Parameter Value Action Description VI_NULL Do not return the alias. Related Items See also viFindRsrc(), viOpen(), and viParseRsrc(). Implementation Requirements RULE 4.3.21 IF a VISA implementation recognizes aliases in viOpen(), THEN it SHALL recognize those same aliases in viParseRsrcEx(). RECOMMENDATION 4.3.5 A VISA implementation should not perform any I/O to the specified resource during this operation. The recommended implementation of viParseRsrcEx() will return information determined solely from the resource string and any static configuration information (e.g., .INI files or the Registry). RULE 4.3.22 A VISA implementation of viParseRsrcEx() SHALL use a case-insensitive compare function when matching resource names against the name specified in rsrcName. OBSERVATION 4.3.10 Calling viParseRsrcEx() with "VXI::1::INSTR" will produce the same results as invoking it with "vxi::1::instr". OBSERVATION 4.3.11 Calling viParseRsrc() with "VXI::BACKPLANE" may result in unaliasedExpandedRsrcName containing either "VXI0::BACKPLANE" or "VXI0::0::BACKPLANE". This is because the driver may not know the mainframe number until the resource is actually opened. RULE 4.3.23 IF a VISA implementation of viParseRsrcEx() does not support aliases, AND the aliasIfExists parameter is not NULL, THEN the output value of aliasIfExists SHALL be an empty string. RULE 4.3.24
IF a user calls viGetAttribute() with the attribute VI_ATTR_PXI_MEM_BASE_BARn_32 and the value would not fit in a 32-bit integer (meaning the value is greater than 0xFFFFFFFF), THEN the implementation SHALL return VI_ERROR_NSUP_OFFSET. OBSERVATION 5.1.10 When the PXI memory base fits in a 32-bit integer, calling viGetAttribute() with the attributes VI_ATTR_PXI_MEM_BASE_BARn_32 and VI_ATTR_PXI_MEM_BASE_BARn_64 return the same status and value.
of the data to the user’s buffer. The user’s buffer must be sufficiently large enough to hold all of the data. VI_ATTR_STATUS Specifies the status of the read operation from the USB interrupt-IN pipe. If the device sent more data than the user specified in VI_ATTR_USB_MAX_INTR_SIZE, then this attribute value will contain the status code VI_WARN_QUEUE_OVERFLOW. VI_EVENT_PXI_INTR Description Notification that a PCI Interrupt was received from the device. Event Attribute Symbolic Name Access Privilege Data Type Range VI_ATTR_EVENT_TYPE RO ViEventType VI_EVENT_PXI_INTR VI_ATTR_PXI_RECV_INTR_SEQ RO ViInt16 N/A VI_ATTR_PXI_RECV_INTR_DATA RO ViUInt32 N/A Event Attribute Descriptions VI_ATTR_EVENT_TYPE Unique logical identifier of the event. VI_ATTR_PXI_RECV_INTR_SEQ Specifies the index of the interrupt sequence that detected the interrupt condition. VI_ATTR_PXI_RECV_INTR_DATA Specifies the first PXI/PCI register that was read in the successful interrupt detection sequence. RULE 5.1.53 All INSTR resource implementations SHALL support the generation of the events VI_EVENT_IO_COMPLETION and VI_EVENT_EXCEPTION. RULE 5.1.54 An INSTR resource implementation for a GPIB, GPIB-VXI, VXI, TCPIP, or USB system SHALL support the generation of the event VI_EVENT_SERVICE_REQ. RULE 5.1.55 An INSTR resource implementation for a VXI system SHALL support the generation of the events VI_EVENT_VXI_SIGP, VI_EVENT_TRIG, and VI_EVENT_VXI_VME_INTR. RULE 5.1.56 An INSTR resource implementation for a PXI system SHALL support the generation of the event VI_EVENT_PXI_INTR.
5.6.3 SOCKET Resource Events VI_EVENT_IO_COMPLETION Description Notification that an asynchronous operation has completed. Event Attributes Symbolic Name Access Privilege Data Type Range VI_ATTR_EVENT_TYPE RO ViEventType VI_EVENT_IO_COMPLETION VI_ATTR_STATUS RO ViStatus N/A VI_ATTR_JOB_ID RO ViJobId N/A VI_ATTR_BUFFER RO ViBuf N/A VI_ATTR_RET_COUNT RO ViBusSize * VI_ATTR_OPER_NAME RO ViString N/A VI_ATTR_RET_COUNT_32 RO ViUInt32 0 to FFFFFFFFh VI_ATTR_RET_COUNT_64** RO ViUInt64 0 to FFFFFFFFFFFFFFFFh * The data type is defined in the appropriate VPP 4.3.x framework specification. ** Defined only for frameworks that are 64-bit native. Event Attribute Descriptions VI_ATTR_EVENT_TYPE Unique logical identifier of the event. VI_ATTR_STATUS This field contains the return code of the asynchronous I/O operation that has completed. VI_ATTR_JOB_ID This field contains the job ID of the asynchronous operation that has completed. VI_ATTR_BUFFER This field contains the address of a buffer that was used in an asynchronous operation. VI_ATTR_RET_COUNT This field contains the actual number of elements that were VI_ATTR_RET_COUNT_32 asynchronously transferred. VI_ATTR_RET_COUNT_64 VI_ATTR_OPER_NAME The name of the operation generating the event. For more information on VI_ATTR_OPER_NAME, see its definition in Section 3.7.2.3, VI_EVENT_EXCEPTION. RULE 5.6.4 All SOCKET resource implementations SHALL support the event VI_EVENT_IO_COMPLETION.
VI_ERROR_BERR Bus error occurred during transfer. VI_ERROR_INV_SETUP Unable to start write operation because setup is invalid (due to attributes being set to an inconsistent state). VI_ERROR_NCIC The interface associated with the given vi is not currently the controller in charge. (continues) Error Codes Description VI_ERROR_NLISTENERS No Listeners condition is detected (both NRFD and NDAC are deasserted). VI_ERROR_IO An unknown I/O error occurred during transfer. VI_ERROR_CONN_LOST The I/O connection for the given session has been lost. Description The write operation synchronously transfers data. The data to be written is in the buffer represented by buf. This operation returns only when the transfer terminates. Only one synchronous write operation can occur at any one time. Table 6.1.4 Special Values for retCount Parameter Value Action Description VI_NULL Do not return the number of bytes transferred. Related Items See the INSTR resource description. Also see viRead(). Implementation Requirements OBSERVATION 6.1.13 If you pass VI_NULL as the retCount parameter to the viWrite() operation, the number of bytes transferred will not be returned. This may be useful if it is important to know only whether the operation succeeded or failed. 6.1.5 viWriteAsync(vi, buf, count, jobId) Purpose Write data to device asynchronously. Parameters Name Direction Type Description vi IN ViSession Unique logical identifier to a session. buf IN ViBuf Represents the location of a data block to be sent to device. count IN ViUInt32 Specifies number of bytes to be written.
writeFmt IN ViString The format string to apply to parameters in ViVAList. params IN ViVAList A list containing the variable number of parameters on which the format string is applied. The formatted data is written to the specified device. Return Values Type ViStatus This is the operational return status. It returns either a completion code or an error code as follows. Completion Code Description VI_SUCCESS Parameters were successfully formatted. Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). VI_ERROR_RSRC_LOCKED Specified operation could not be performed because the resource identified by vi has been locked for this kind of access. VI_ERROR_INV_FMT A format specifier in the writeFmt string is invalid. VI_ERROR_NSUP_FMT A format specifier in the writeFmt string is not supported. VI_ERROR_ALLOC The system could not allocate a formatted I/O buffer because of insufficient system resources. Description This operation is similar to viVPrintf(), except that the output is not written to the device; it is written to the user-specified buffer. This output buffer will be NULL terminated. Related Items See the INSTR resource description. Also see viSPrintf() and viVPrintf(). Implementation Requirements RULE 6.2.9 IF the viVSPrintf() operations outputs an END indicator before all the arguments are satisfied, THEN the rest of the writeFmt string SHALL be ignored and the buffer string will still be terminated by a NULL. 6.2.7 viBufWrite(vi, buf, count, retCount) Purpose Similar to viWrite(), except the data is written to the formatted I/O write buffer rather than directly to the device. Parameters Name Direction Type Description
vi IN ViSession Unique logical identifier to a session. buf IN ViBuf Represents the location of a data block to be sent to device. count IN ViUInt32 Specifies number of bytes to be written. retCount OUT ViUInt32 Represents the location of an integer that will be set to the number of bytes actually transferred. Return Values Type ViStatus This is the operational return status. It returns either a completion code or an error code as follows. Completion Code Description VI_SUCCESS Operation completed successfully. Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). VI_ERROR_NSUP_OPER The given vi does not support this operation. VI_ERROR_RSRC_LOCKED Specified operation could not be performed because the resource identified by vi has been locked for this kind of access. VI_ERROR_TMO Timeout expired before operation completed. VI_ERROR_INV_SETUP Unable to start write operation because setup is invalid (due to attributes being set to an inconsistent state). VI_ERROR_IO An unknown I/O error occurred during transfer. Description This operation is similar to viWrite() and does not perform any kind of data formatting. It differs from viWrite() in that the data is written to the formatted I/O write buffer (the same buffer as used by viPrintf() and related operations) rather than directly to the device. This operation can intermix with the viPrintf() operation, but mixing it with the viWrite() operation is discouraged. Table 6.2.1 Special Values for retCount Parameter Value Action Description VI_NULL Do not return the number of bytes transferred. Related Items See the INSTR resource description. Also see viWrite() and viBufRead(). Implementation Requirements RULE 6.2.10 IF the viBufWrite() operation returns VI_ERROR_TMO, THEN the write buffer for the specified session SHALL be cleared.
VI_ERROR_NSUP_FMT A format specifier in the readFmt string is not supported. VI_ERROR_ALLOC The system could not allocate a formatted I/O buffer because of insufficient system resources. Description This operation is similar to viScanf(), except that the data is read from a user-specified buffer rather than a device. Related Items See the INSTR resource description. Also see viScanf(). Implementation Requirements There are no additional implementation requirements other than those specified above. 6.2.11 viVSScanf(vi, buf, readFmt, params) Purpose Same as viVScanf(), except that the data is read from a user-specified buffer instead of a device. Parameters Name Direction Type Description vi IN ViSession Unique logical identifier to a session. buf IN ViBuf Buffer from which data is read and formatted. readFmt IN ViString The format string to apply to parameters in ViVAList. params OUT ViVAList A list with the variable number of parameters into which the data is read and the format string is applied. Return Values Type ViStatus This is the operational return status. It returns either a completion code or an error code as follows. Completion Code Description VI_SUCCESS Data was successfully read and formatted into arg parameter(s). Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). VI_ERROR_RSRC_LOCKED Specified operation could not be performed because the resource identified by vi has been locked for this kind of access. VI_ERROR_INV_FMT A format specifier in the readFmt string is invalid.
Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). VI_ERROR_NSUP_OPER The given vi does not support this operation. VI_ERROR_RSRC_LOCKED Specified operation could not be performed because the resource identified by vi has been locked for this kind of access. VI_ERROR_INV_SPACE Invalid address space specified. VI_ERROR_INV_OFFSET Invalid offset specified. (continues) Error Codes Description VI_ERROR_NSUP_OFFSET Specified region is not accessible from this hardware. VI_ERROR_INV_SIZE Invalid size of window specified. VI_ERROR_INV_ACC_MODE Invalid access mode. VI_ERROR_TMO viMapAddress() could not acquire resource or perform mapping before the timer expired. VI_ERROR_ALLOC Unable to allocate window of at least the requested size. VI_ERROR_WINDOW_MAPPED The specified session already contains a mapped window. VI_ERROR_INV_SETUP Unable to start operation because setup is invalid (due to attributes being set to an inconsistent state). Description This operation maps in a specified memory space. The memory space that is mapped is dependent on the type of interface specified by the vi parameter and the mapSpace (refer to the following table) parameter. The address parameter returns the address in your process space where memory is mapped. The following table lists the valid entries for the mapSpace parameter. Value Description VI_A16_SPACE Map the A16 address space of VXI/MXI bus. VI_A24_SPACE Map the A24 address space of VXI/MXI bus. VI_A32_SPACE Map the A32 address space of VXI/MXI bus. VI_A64_SPACE Map the A64 address space of VXI/MXI bus. Address the PCI configuration space. – Address the specified PCI memory or I/O space.
Notice that offset returned from the viMemAlloc() and viMemAllocEx() operations is the offset address relative to the device’s allocated address base for whichever address space into which the given device exports memory. OBSERVATION 6.4.2 No device is required to have memory that can be shared or managed by the local controller. In this case, a VISA implementation may always return VI_ERROR_NSUP_OPER. RULE 6.4.1 The offset parameter in the viMemAlloc(), viMemAllocEx(), viMemFree(), and viMemFreeEx() operations on a PXI MEMACC resource SHALL be an absolute physical PCI address. 6.4.3 viMemFree(vi, offset) 6.4.4 viMemFreeEx(vi, offset64) Purpose Free memory previously allocated using viMemAlloc() or viMemAllocEx(). Parameters Name Direction Type Description Vi IN ViSession Unique logical identifier to a session. offset or offset64 IN ViBusAddress or ViBusAddress64 Specifies the memory previously allocated with viMemAlloc() or viMemAllocEx(). Return Values Type ViStatus This is the operational return status. It returns either a completion code or an error code as follows. Completion Code Description VI_SUCCESS Operation completed successfully. Error Codes Description VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). VI_ERROR_NSUP_OPER The given vi does not support this operation. VI_ERROR_INV_OFFSET Invalid offset specified. VI_ERROR_WINDOW_MAPPED The specified offset is currently in use by viMapAddress(). Description This operation frees the memory previously allocated using viMemAlloc() or viMemAllocEx(). Related Items See the INSTR resource description. Also see viMemAlloc(), and viMemAllocEx(). Implementation Requirements RULE 6.4.2