Ivi_ReadInstrData
Usage
ViStatus Ivi_ReadInstrData(ViSession vi, ViInt32 numberBytesToRead, ViChar readBuffer[ ], ViInt32* numBytesRead);
Purpose
This function reads data directly from an instrument using VISA I/O. The function bypasses the attribute state caching mechanism. Use this function only to implement the PREFIX_ReadInstrData function that your instrument driver exports to the end-user.
The function assumes that the IVI_ATTR_IO_SESSION attribute for the IVI session you specify holds a valid VISA session for the instrument.
If data is not available at the instrument's output buffer when you call this function, the instrument might hang up. In that case, the function does not return until the VISA I/O call times out. If you have disabled the timeout, the function hangs indefinitely.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession |
The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session. |
| numberBytesToRead | ViInt32 |
Specify the maximum number of bytes to read from the instrument. The Read Buffer parameter must be a ViChar buffer that contains at least the number of bytes you specify. If the number of bytes you specify is less than the number of bytes in the instrument's output buffer, you must call this function again to empty the output buffer. If you do not empty the instrument's output buffer, the instrument might return invalid data in response to subsequent requests. If data is not available at the instrument's output buffer when you call this function, the instrument might hang up. In that case, the function does not return until the VISA I/O call times out. If you have disabled the timeout, the function hangs indefinitely. |
| readBuffer | ViChar[ ] |
A buffer in which the function places the data it receives from the instrument. The buffer must be a ViChar array that has at least as many bytes as you specify in the Number Bytes To Read parameter. This function does not write an ASCII NUL byte to terminate the data, nor does it clear the buffer beyond the bytes it actually receives from the instrument. |
| numBytesRead | ViInt32* |
This control returns the actual number of bytes the function received from the instrument. This is the value that the VISA viRead function returns. If the actual number of bytes received is less than the number of bytes you specify in the Number Bytes To Read parameter, the instrument's output buffer has probably emptied. If the number of bytes received is 0, the most probable cause is that no data was available at the instrument's output buffer. |
Return Value
Contains the status code that the function call returns. IVI engine functions can return error and warning values from several sets of status codes. Some status codes are unique to the IVI engine. Other status codes are the same codes that VISA Library functions return. Still others are error or warning values that functions in specific instrument drivers return. Each set of status codes has its own numeric range.
Regardless of the source of the status code, 0 always indicates success, a positive value indicates a warning, and a negative value indicates an error.