I/O Format Specifiers for Readings Strings

String Data -- %s, %t, %T, and %[]

A string argument has a format specifier of the following form:

%[{enum} | VARIANT_BOOL] [*] [width] [delimiter [array size] ] [$S] [$B | $C] [q | Q] type

The type code indicates how the read operation is terminated and how whitespace is handled, as explained in the following table:

String Format Code	Whitespace Handling	Read Operation Termination
%s	Leading whitespace is ignored.	Characters are read until a whitespace character is received.
%t	Whitespace is preserved.	Characters are read until the first END indicator is received. The character on which the END indicator was received is included in the user buffer.
%T	Whitespace is preserved.	Characters are read until a linefeed character (\n) is received. The linefeed character is included in the user buffer.
%[]	Whitespace is preserved (unless explicitly excluded by the format code itself).	If the first character enclosed in brackets ([]) is not a caret (^), then characters are read up to the first character that does not appear in the bracketed character set. If the first character in the set is a caret (^), the effect is reversed: characters are read up to the first character that does appear in the rest of the character set. In either case, the character on which the read terminated is not included in the user buffer.

All four string format codes (%s, %t, %T, and %[]) have the same behavior with regard to the format modifiers, as given in the table below.

Modifier	Interpretation
enum	The argument is interpreted as an int pointer representing an allowed value for the specified enum. The string read from the device is converted to its associated integer value and stored in the int pointer argument supplied by the user. The string-to-integer conversion is performed according to the enum-to-string mappings specified in the Instrument Command Editor. A simplified version of the enum name can be used for the enum field. Specifically, the project name prefix and Enum suffix can be excluded.
VARIANT_BOOL	The argument is interpreted as a VARIANT_BOOL pointer. The string read from the device is converted to a value of VARIANT_TRUE or VARIANT_FALSE performed according to the bool-to-string mappings specified in the Instrument Command Editor.
* (asterisk)	An asterisk acts as the assignment suppression character. The input is scanned but not assigned to any parameters and is discarded.
width	Maximum string size. A # may be present in lieu of an integer width modifier, in which case an extra int pointer argument supplies the value. Upon completion of the read operation, this width pointer argument is updated with the actual number of characters copied into the user array, not including the NULL terminator.
delimiter [array size]	The argument is assumed to be a SAFEARRAY of BSTR elements. Note that the $S modifier must be present. array size specifies the maximum number of array elements to store in the user array argument. A # may be present in lieu of an integer array size modifier, in which case an extra int argument supplies the value.
$B	The argument is assumed to be a BSTR or a SAFEARRAY of BSTR elements if paired with the $S modifier.
$C	The argument is assumed to be a CString. Note that the $C modifier cannot be combined with the $S modifier.
$S	The argument is assumed to be a SAFEARRAY of BSTR elements. This modifier can only appear if $B is also used, as SAFEARRAYs of CString or C-style strings are not supported.
q	The string is expected to be read with surrounding single-quotes (') or double-quotes ("). Whitespace and delimiter characters enclosed in quotes are preserved and copied to the user argument.
Q	Same as q modifier except that the surrounding quotes are stripped before copying to the user argument.

Example -- String basics

C++

Copy

HRESULT hr = S_OK;

LPSTR sz[100];

// Instrument sends the following:
//    "Hello World"
hr = io.Scanf(_T("%100s"), sz);       // sz contains "Hello"
                                      // read stops at first whitespace

char szManufacturer[100];
char szModel[100];
char szSerial[100];
char szRevision[100];

// Send *IDN? query
// Instrument response is:
//   "Acme,Model4321,A53QWE,Rev1.2"
hr = io.Queryf(_T("*IDN?"), _T("%100[^,],%100[^,],%100[^,],%100[^,]"), szManufacturer, szModel, szSerial, szRevision);           

// szManufacturer contains "Acme"
// szModel contains "Model4321"
// szSerial contains "A53QWE"
// szRevision contains "Rev1.2"

// Store only the model and serial number
// WARNING: Access violation occurs if instrument sends more than 99 characters for either model or serial number fields
hr = io.Queryf(_T("*IDN?"), _T("%*[^,],%[^,],%[^,],%*[^,]"), szModel, szSerial); 

// Read until something OTHER than an "A", "B", or "C" is encountered
// Instrument sends the following:
//    "AB AC, aC"
hr = io.Scanf(_T("%100[ABC]"), sz);       // sz contains "AB AC, "
                                          // character set is case-sensitive, so read stops at "a"

// Read until a "D", "E", or "F" is encountered
// Instrument sends the following:
//    "AB EA"
hr = io.Scanf(_T("%100[^DEF]"), sz);      // sz contains "AB "

Example -- Quoted strings

C++

Copy

HRESULT hr = S_OK;

char szArg1[100];
char szArg2[100];
char szArg3[100];

// Response is expected in quotes
// Instruments sends the following:
//    'abc','def','hij'
hr = io.Scanf(_T("%100qs,%100qs,%100qs"), szArg1, szArg2, szArg3);      // szArg1 contains 'abc'
                                                                        // szArg2 contains 'def'
                                                                        // szArg3 contains 'hij'

// Response is expected in quotes, results stripped of quotes
// Instruments sends the following:
//    "abc","def","hij"
hr = io.Scanf(_T("%100Qs,%100Qs,%100Qs"), szArg1, szArg2, szArg3);      // szArg1 contains abc
                                                                        // szArg2 contains def
                                                                        // szArg3 contains hij

// Delimiters and whitespace enclosed in quotes are preserved
// Instruments sends the following:
//    "ab,c"," def ","h,i j"
hr = io.Scanf(_T("%100qs,%100qs,%100qs"), szArg1, szArg2, szArg3);      // szArg1 contains "ab,c"
                                                                        // szArg2 contains " def "
                                                                        // szArg3 contains "h,i j"

Example -- BSTR and CString

C++

Copy

HRESULT hr = S_OK;

// Queryf function will allocate memory within the CString objects
CString strManufacturer, strModel, strSerial, strRevision;

// Instrument response is:
//   "Acme,Model4321,A53QWE,Rev1.2"
hr = io.Queryf(_T("*IDN?"), _T("%$C[^,],%$C[^,],%$C[^,],%$C[^,]"), &strManufacturer, &strModel, &strSerial, &strRevision);           

// strManufacturer contains "Acme"
// strModel contains "Model4321"
// strSerial contains "A53QWE"
// strRevision contains "Rev1.2"


// Queryf function will allocate memory within the CComBSTR objects
CComBSTR bstrManufacturer, bstrModel, bstrSerial, bstrRevision;

hr = io.Queryf(_T("*IDN?"), _T("%$B[^,],%$B[^,],%$B[^,],%$B[^,]"), &bstrManufacturer, &bstrModel, &bstrSerial, &bstrRevision);           

// Memory allocated for CComBSTR and CString objects released upon existing the containing scope

Example -- String arrays

Important
The only type of string arrays supported are SAFEARRAYs of BSTR elements. Thus, $S$B will always appear in the format specifier for a string array. SAFEARRAY arguments that have CString or C-style strings as elements are not supported.

C++

Copy

HRESULT hr = S_OK;

// Queryf will allocate memory for the SAFEARRAY AND for the BSTR elements within it
// Instrument response is:
//   "Acme,Model4321,A53QWE,Rev1.2"
SAFEARRAY* psaArg1 = NULL;
hr = io.Queryf(_T("*IDN?"), _T("%,$S$Bs"), &psaArg1);        // psaArg1[0] contains "Acme"
                                                             // psaArg1[1] contains "Model4321"
                                                             // psaArg1[2] contains "A53QWE"
                                                             // psaArg1[3] contains "Rev1.2"

// NOTE: Caller is responsible for freeing memory associated with SAFEARRAY
// AND the memory associated with each BSTR element.

// Scan using more than one possible delimiter -- colon, semicolon, and comma
// Instrument sends:
//   "abc;def,hij:klm"
SAFEARRAY* psaArg2 = NULL;
hr = io.Scanf(_T("%(:;,)$S$Bs"), &psaArg2);    // psaArg2[0] contains "abc"
                                               // psaArg2[1] contains "def"
                                               // psaArg2[2] contains "hij"
                                               // psaArg2[3] contains "klm"

Example -- Enum and boolean command strings

C++

Copy

HRESULT hr = S_OK;

// Convert string response of device into a valid enum value
// Note the enum format specifier excludes the "Acme4321" prefix and the "Enum" suffix
// Instrument response is:
//   "External"
Acme4321TriggerSourceEnum eSource;
hr = io.Queryf(_T("TRIG:SOUR?"), _T("%{TriggerSource}s"), &eSource);

// Acme4321TriggerSourceExternal is mapped to "External"
ATLASSERT(eSource == Acme4321TriggerSourceExternal);

// Convert string response of device into a VARIANT_BOOL
// Instrument response is "TRUE"
VARIANT_BOOL bEnabled;
hr = io.Queryf(_T("TRIG:ENAB?"), _T("%{VARIANT_BOOL}s"), &bEnabled);

// "TRUE" is mapped to VARIANT_TRUE
ATLASSERT(bEnabled == VARIANT_TRUE);

Other Resources

Scanf