Example of Message-Based Communication

Serial, GPIB, Ethernet, and VXI systems all have a definition of message-based communication. In GPIB, serial, and Ethernet, the messages are inherent in the design of the bus itself. For VXI, the messages actually are sent via a protocol known as word serial, which is based on register communication. In either case, the end result is sending or receiving strings.

Message-Based Communication Example (C)

The following example shows the basic steps in any VISA program.

Note The following example uses bold text to distinguish lines of code that are different from the other introductory programming examples.
#include "visa.h"
#define MAX_CNT 200
int main(void)
{
    ViStatus     status;            /* For checking errors */
    ViSession    defaultRM, instr;  /* Communication channels */
    ViUInt32     retCount;          /* Return count from string I/O */
    ViChar       buffer[MAX_CNT];   /* Buffer for string I/O */
    /* Begin by initializing the system */
    status = viOpenDefaultRM(&defaultRM);
    if (status < VI_SUCCESS) {
        /* Error Initializing VISA...exiting */
        return -1;
    }
    /* Open communication with GPIB Device at Primary Addr 1 */
    /* NOTE: For simplicity, we will not show error checking */
    status = viOpen(defaultRM, "GPIB0::1::INSTR", VI_NULL, VI_NULL, &instr);
    
    /* Set the timeout for message-based communication */
    status = viSetAttribute(instr, VI_ATTR_TMO_VALUE, 5000);

    /* Ask the device for identification */
    status = viWrite(instr, "*IDN?\n", 6, &retCount);
    status = viRead(instr, buffer, MAX_CNT, &retCount);

    /* Your code should process the data */
    
    /* Close down the system */
    status = viClose(instr);
    status = viClose(defaultRM);
    return 0;
}

Message-Based Communication Example (VB)

Note The Visual Basic examples in this manual use the VISA data types where applicable. This feature is available only on Windows. To use this feature, select the VISA library (visa32.dll) as a reference from Visual Basic. This makes use of the type library embedded into the DLL.
Private Sub vbMain()
   Const MAX_CNT = 200
    Dim stat        As ViStatus
    Dim dfltRM      As ViSession
    Dim sesn        As ViSession
    Dim retCount    As Long
    Dim buffer      As String * MAX_CNT 
   Rem Begin by initializing the system
   stat = viOpenDefaultRM(dfltRM)
   If (stat < VI_SUCCESS) Then
    Rem Error initializing VISA...exiting
    Exit Sub
   End If

   Rem Open communication with GPIB Device at Primary Addr 1
   Rem NOTE: For simplicity, we will not show error checking
   stat = viOpen(dfltRM, "GPIB0::1::INSTR", VI_NULL, VI_NULL, sesn)

   Rem Set the timeout for message-based communication
   stat = viSetAttribute(sesn, VI_ATTR_TMO_VALUE, 5000)

   Rem Ask the device for identification
   stat = viWrite(sesn, "*IDN?", 5, retCount)
   stat = viRead(sesn, buffer, MAX_CNT, retCount)

   Rem Your code should process the data

   Rem Close down the system
   stat = viClose (sesn)
   stat = viClose (dfltRM)
End Sub

Message-Based Communication Example Discussion

We can break down the message-based communication example into the following steps.

  1. Begin by initializing the VISA system. For this task you use viOpenDefaultRM(), which opens a communication channel with VISA itself. This channel has a purpose similar to a telephone line. The function call is analogous to picking up the phone and dialing the operator. From this point on, the phone line, or the value output from viOpenDefaultRM(), is what connects you to the VISA driver. Any communication on the line is between you and the VISA driver only. viOpenDefaultRM() initializes VISA and must be the first VISA function called in your program.
  2. Now you must open a communication channel to the device itself using viOpen(). Notice that this function uses the handle returned by viOpenDefaultRM(), which is the variable defaultRM in the example, to identify the VISA driver. You then specify the address of the device you want to talk to. Continuing with the phone analogy, this is like asking the operator to dial a number for you. In this case, you want to address a GPIB device at primary address 1 on the GPIB0 bus. The value for x in the GPIBx token (GPIB0 in this example) indicates the GPIB board to which your device is attached. This means that you can have multiple GPIB boards installed in the computer, each controlling independent buses.

    The two VI_NULL values following the address string are not important at this time. They specify that the session should be initialized using VISA defaults. Finally, viOpen() returns the communication channel to the device in the parameter instr. From now on, whenever you want to talk to this device, you use the instr variable to identify it. Notice that you do not use the defaultRM handle again. The main use of defaultRM is to tell the VISA driver to open communication channels to devices. You do not use this handle again until you are ready to end the program.

  3. At this point, set a timeout value for message-based communication. A timeout value is important in message-based communication to determine what should happen when the device stops communicating for a certain period of time. VISA has a common function to set values such as these: viSetAttribute(). This function sets values such as timeout and the termination character for the communication channel. In this example, notice that the function call to viSetAttribute() sets the timeout to be 5 s (5000 ms) for both reading and writing strings.
  4. Now that you have the communication channel set up, you can perform string I/O using the viWrite() and viRead() functions. Notice that this is the section of the programming code that is unique for message-based communication. Opening communication channels, as described in steps 1 and 2, and closing the channels, as described in step 5, are the same for all VISA programs. The parameters that these calls use are relatively straightforward.
    1. First you identify which device you are talking to with instr.
    2. Next you give the string to send, or what buffer to put the response in.
    3. Finally, specify the number of characters you are interested in transferring.
  5. When you are finished with your device I/O, you can close the communication channel to the device with the viClose() function.

    Notice that the program shows a second call to viClose(). When you are ready to shut down the program, or at least close down the VISA driver, you use viClose() to close the communication channel that was opened using viOpenDefaultRM().