I/O Format Specifiers for Writing Strings

String Data -- %s

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

%[{enum} | VARIANT_BOOL] [flags] [width] [.precision] [delimiter [array size] ] [$S] [$B | $C] [q | Q] s

Modifier	Interpretation
Default Functionality	The argument is interpreted as a null-terminated C-style string. The string is sent to the device without change.
enum	The argument is interpreted as an integer representing an allowed value for the specified enum. The integer value is converted to a string based upon the enum-to-string mappings specified int 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. The value is converted to a string based upon the enum-to-string mappings specified int the Instrument Command Editor.
flags -, 0	Controls justification and padding of the output, as follows: - - left aligns the result with the given field width. 0 - pads with zeros until the width is reached. If 0 and - appear together, the 0 is ignored.
width	Minimum field width of the output string. An asterisk (*) may be present in lieu of an integer width modifier, in which case an extra int argument supplies the value.
precision	Maximum number of characters to send. An asterisk (*) may be present in lieu of an integer precision modifier, in which case an extra int argument supplies the value.
delimiter [array size]	The argument is interpreted as an array of BSTR elements. Note that the $S modifier must be present. If the array size is not specified, then number of elements sent is determined from the size of the SAFEARRAY itself. array size specifies the number of array elements to send. An asterisk (*) 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 interpreted as a BSTR or a SAFEARRAY of BSTR elements if paired with the $S modifier.
$C	The argument is interpreted as a CString. Note that the $C modifier cannot be combined with the $S modifier.
$S	The argument is interpreted as 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 formatted with enclosing single quotes ('). If combined with the $S and $B modifiers to format a delimited list of strings, each element is enclosed in single quotes.
Q	The string is formatted with enclosing double quotes ("). If combined with the $S and $B modifiers to format a delimited list of strings, each element is enclosed in double quotes.

Example -- String literal output

C++

Copy

HRESULT hr = S_OK;

hr = io.Printf(_T("Hello World"));           // Sends "Hello World"

// Special formatting character -- linefeed
hr = io.Printf(_T("Hello World\\n"));        // Sends "Hello World" followed by a linefeed and END indicator

// Character specified using an octal value
hr = io.Printf(_T("\123"));                  // Sends "S"

Example -- String width and precision

C++

Copy

HRESULT hr = S_OK;

LPCSTR psz = "Hello World";

// Sends all characters up to the null terminator
hr = io.Printf(_T("%s"), psz);               // Sends "Hello World"

// Field width sets minimum width at 15, pad to the left
hr = io.Printf(_T("%15s"), psz);             // Sends "    Hello World"

// Field width set using a variable, left-justify and pad to the right
int nWidth = 15;
hr = io.Printf(_T("%-*s"), nWidth, psz);     // Sends "Hello World    "

// Precision specifies maximum width
hr = io.Printf(_T("%.5s"), psz);             // Sends "Hello"

Example -- Quoted strings

C++

Copy

HRESULT hr = S_OK;

LPCSTR psz = "Hello World";

// Enclose in single quotes
hr = io.Printf(_T("%qs"), psz);                 // Sends "'Hello World'"

// Padding is applied outside of the quotes
hr = io.Printf(_T("%15qs"), psz);               // Sends "  'Hello World'"

// Enclose in double quotes
hr = io.Printf(_T("%15Qs"), psz);               // Sends "  "Hello World""

Example -- BSTR and CString

C++

Copy

HRESULT hr = S_OK;

CComBSTR bstrName = OLESTR("Hello World");

hr = io.Printf(_T("%$Bs"), bstrName);      // Sends "Hello World"

CString strName = COLE2T(bstrName);

hr = io.Printf(_T("%$Cs"), strName);       // Sends "Hello World"

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;

CComBSTR bstr1 = OLESTR("one");
CComBSTR bstr2 = OLESTR("two");
CComBSTR bstr3 = OLESTR("three");

CComSafeArray<BSTR> saNames;
saNames.Add(bstr1);
saNames.Add(bstr2);
saNames.Add(bstr3); 

hr = io.Printf(_T("%,$S$Bs"), saNames.m_psa);       // Sends "one,two,three"

// Enclose in single quotes
hr = io.Printf(_T("%,$S$Bqs"), saNames.m_psa);      // Sends "'one','two','three'"

Example -- Enum and boolean command strings

C++

Copy

HRESULT hr = S_OK;

// Convert eSource variable to a command string
// Note the enum format specifier excludes the "Acme4321" prefix and the "Enum" suffix
Acme4321TriggerSourceEnum eSource = Acme4321TriggerSourceExternal;
hr = io.Printf(_T("TRIG:SOUR %{TriggerSource}s"), eSource);

// Convert bEnabled variable to a command string
VARIANT_BOOL bEnabled = VARIANT_TRUE;
hr = io.Printf(_T("TRIG:SOUR:ENAB %{VARIANT_BOOL}s"), bEnabled);

Other Resources

Printf