GetSpecificDriverStatusDesc

IVI Library

Ivi_GetSpecificDriverStatusDesc

Usage

ViStatus Ivi_GetSpecificDriverStatusDesc(ViSession vi, ViStatus statusCode, IviStringValueTable additionalTableToSearch, ViChar statusMessage[ ]);

Purpose

This function converts a status code that an instrument driver function returns into a meaningful message string. It interprets IVI and VISA status codes just as Ivi_GetErrorMessage does, but it also allows you to pass a table of error codes and messages that are specific to the instrument driver.

Use this function to implement the PREFIX_error_message function in the instrument driver.

If the function cannot find a description for the status code, it reports the "Unknown status value" message and returns the VI_WARN_UNKNOWN_STATUS warning code.

Parameters

Name Type Description
vi ViSession

The ViSession handle that you obtain from Ivi_SpecificDriverNew.

You can pass VI_NULL for this parameter. This is useful when Ivi_SpecificDriverNew fails.

statusCode ViStatus

A status code that an instrument driver function returns.

additionalTableToSearch IviStringValueTable

Specify a string/value table that contains status codes specific to the instrument driver. Specify a message string for each status code in the table. Terminate the table with an entry that has VI_NULL in the string field.

The ivi.h include file defines the structure of a string/value table entry as follows:

typedef struct

{

ViInt32  value;ViString  string;
} IviStringValueEntry;

If you pass VI_NULL for this parameter, the function behaves the same as Ivi_GetErrorMessage.

statusMessage ViChar[ ]

Returns a meaningful message string for an IVI, VISA, or instrument driver status code. If the status code is unknown, it returns "Unknown status value".

You must pass a ViChar array that contains at least IVI_MAX_MESSAGE_BUF_SIZE (256) bytes.

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.

Related Topic

IVI Status Codes