Click or drag to resize

EnumConverter Class

Nimbus provides special features for message-based devices that greatly simplify sending commands to and from instruments. The topic on Working With Instrument Commands discusses many of these features. One of the key components of the automatic command formatting features offerred by Nimbus is the ability to convert enum parameters to and from instrument command strings.

The Nimbus Runtime Library provides the EnumConverter class for converting between driver-defined enums and instrument command strings. The driver developer uses the Enum Member Editor to associate instrument command strings with specific enum members. For each enum with command mappings configured via this editor, Nimbus creates an entry in the enum macro map maintained in the driver project's Enums.h file. Each entry in that map produces a class definition that derives from EnumConverter and that exposes a ToCommand function for converting enum member values to instrument command strings and a FromResponse function for converting instrument command strings to enum member values.

Using an EnumConverter

In the following example, the TRIGGER_SOURCE attribute is defined to have enum members mapped as follows:

  • TRIGGER_SOURCE_VAL_INTERNAL -> INT

  • TRIGGER_SOURCE_VAL_EXTERNAL -> EXT

  • TRIGGER_SOURCE_VAL_SOFTWARE -> SW

Note that the name of the EnumConverter-derived class is always the name of the enum chosen by the driver developer followed by the string Enum. In the below, the enum converter class is TriggerSourceEnum.

C++
ViStatus _VI_FUNC acme4321_set_TRIGGER_SOURCE(ViSession Vi, ViConstString RepCapIdentifier, ViInt32 AttributeValue)
{      
    // ...

    // The ToCommand function will convert the AttributeValue to one of the defned strings -- "INT", "EXT" or "SW".
    // If the AttributeValue is not one of the defined enum member values, then an the IVI-defined error code
    // IVIC_ERROR_CANNOT_RECOVER will be returned, along with a descriptive error message.
    // 
    std::string strAttributeValue;
    status = TriggerSourceEnum::ToCommand(Vi, AttributeValue, strAttributeValue);
    ReturnOnError(status);

    // At this point, the strAttributeValue variable has the value "INT", "EXT", or "SW", so we use it
    // directly in formatting the overall instrument command for the operation.
    // 
    status = viPrintf(GetVisaSession(Vi), "CONFIG:SOUR %s\n", strAttributeValue.c_str());
    ReturnOnError(status);

    // ...    
}

The EnumConverter classes are also used when reading instrument responses and returning them as attribute values. The getter implementation of the same TRIGGER_SOURCE enum might look something like the code below.

C++
ViStatus _VI_FUNC acme4321_set_TRIGGER_SOURCE(ViSession Vi, ViConstString RepCapIdentifier, ViInt32 AttributeValue)
{      
    // ...

    // The viQueryf function will read the instrument response into the szAttributeValue variable.
    // 
    char szAttributeValue[MAX_ENUM_RESPONSE];
    int cbAttributeValue = _countof(szAttributeValue);
    status = viQueryf(GetVisaSession(Vi), "CONFIG:SOUR?\n", "%#s%*t", &cbAttributeValue, szAttributeValue);
    ReturnOnError(status);

    // At this point, the szAttributeValue variable should have the value "INT", "EXT", or "SW".
    // The FromResponse function will map that string back to one of the three attribute values:
    // TRIGGER_SOURCE_VAL_INTERNAL, TRIGGER_SOURCE_VAL_EXTERNAL, or TRIGGER_SOURCE_VAL_SOFTWARE.
    // If the szAttributeValue does not have one of the expected string values, then the FromResponse
    // function will return the error code IVIC_ERROR_UNEXPECTED_RESPONSE along with a descriptive message.
    // 
    status = TriggerSourceEnum::FromResponse(Vi, szAttributeValue, AttributeValue);
    ReturnOnError(status);

    // ...    
}

Download a complete CHM version of this documentation here.