viFlush
Purpose
Manually flushes the specified buffers associated with formatted I/O operations and/or serial communication.
C Syntax
ViStatus viFlush(ViSession vi, ViUInt16 mask)
Visual Basic Syntax
viFlush&(ByVal vi&, ByVal mask%)
Resource Classes
GPIB INSTR, GPIB INTFC, GPIB-VXI INSTR, Serial INSTR, TCPIP INSTR, TCPIP SOCKET, VXI INSTR, VXI SERVANT
Parameters
| Name | Direction | Description |
|---|---|---|
|
vi |
IN |
Unique logical identifier to a session. |
|
mask |
IN |
Specifies the action to be taken with flushing the buffer. Refer to the Description section for more information. |
Return Values
| Completion Codes | Description |
|---|---|
|
VI_SUCCESS |
Buffers flushed successfully. |
| Error Codes | Description |
|---|---|
|
VI_ERROR_INV_OBJECT |
The given session reference is invalid. |
|
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_IO |
Could not perform Read/Write operation because of I/O error. |
|
VI_ERROR_TMO |
The Read/Write operation was aborted because timeout expired while operation was in progress. |
|
VI_ERROR_INV_MASK |
The specified mask does not specify a valid flush operation on Read/Write resource. |
Description
The value of mask can be one of the following flags.
| Flag | Interpretation |
|---|---|
|
VI_READ_BUF (1) |
Discard the read buffer contents. If data was present in the read buffer and no END-indicator was present, read from the device until encountering an END indicator (which causes the loss of data). This action resynchronizes the next viScanf() call to read a <TERMINATED RESPONSE MESSAGE>. (Refer to the IEEE 488.2 standard.) |
|
VI_READ_BUF_DISCARD (4) |
Discard the read buffer contents (does not perform any I/O to the device). |
|
VI_WRITE_BUF (2) |
Flush the write buffer by writing all buffered data to the device. |
|
VI_WRITE_BUF_DISCARD (8) |
Discard the write buffer contents (does not perform any I/O to the device). |
|
VI_IO_IN_BUF (16) |
Discard the low-level I/O receive buffer contents (same as VI_IO_IN_BUF_DISCARD). |
|
VI_IO_IN_BUF_DISCARD (64) |
Discard the low-level I/O receive buffer contents (does not perform any I/O to the device). |
|
VI_IO_OUT_BUF (32) |
Flush the low-level I/O transmit buffer by writing all buffered data to the device. |
|
VI_IO_OUT_BUF_DISCARD (128) |
Discard the low-level I/O transmit buffer contents (does not perform any I/O to the device). |
It is possible to combine any of these read flags and write flags for different buffers by ORing the flags. However, combining two flags for the same buffer in the same call to viFlush() is illegal.
Notice that when using formatted I/O operations with a session to a Serial device or Ethernet socket, a flush of the formatted I/O buffers also causes the corresponding I/O communication buffers to be flushed. For example, calling viFlush() with VI_WRITE_BUF also flushes the VI_IO_OUT_BUF.
In previous versions of VISA, VI_IO_IN_BUF was known as VI_ASRL_IN_BUF and VI_IO_OUT_BUF was known as VI_ASRL_OUT_BUF.
Implicit versus Explicit Flushing
Although you can explicitly flush the buffers by making a call to viFlush(), the buffers are flushed implicitly under some conditions. These conditions vary for the viPrintf() and viScanf() operations.
Flushing a write buffer immediately sends any queued data to the device. The write buffer is maintained by the viPrintf() operation. To explicitly flush the write buffer, you can make a call to the viFlush() operation with a write flag set. In addition, the write buffer is flushed automatically under the following conditions:
- When an END-indicator character is sent (that is, the \n character is specified in the formatting string).
- When the buffer is full.
- In response to a call to viSetBuf() with the VI_WRITE_BUF flag set.
Flushing a read buffer discards the data in the read buffer. This guarantees that the next call to a viScanf() (or related) operation reads data directly from the device rather than from queued data residing in the read buffer. The read buffer is maintained by the viScanf() operation. To explicitly flush the read buffer, you can make a call to the viFlush() operation with a read flag set.
Also, the formatted I/O buffers of a session to a given device are reset whenever that device is cleared. Invoking the viClear() operation will flush the read buffer and discard the contents of the write buffers.
Related Topics
Automatically Flushing the Formatted I/O Buffers
Controlling the Serial I/O Buffers
Formatted I/O Read and Low-Level I/O Receive Buffers
Formatted I/O Write and Low-Level I/O Transmit Buffers
Manually Flushing the Formatted I/O Buffers