Strings

When transferring string values to or from the instrument, you can use %s, %t, %T, and %[] format codes with a field width modifier. Because this is a message-based communication system, string formatting is the most common routine. With string formatting, you can configure instrument settings and query instrument information.

White Space Termination—"%s"

Characters are read from an instrument into the string until a white space character is read.

Example

This example queries the trigger source. This instrument returns a string. The maximum length of the string is specified in the format string with the number (#) sign. The argument rdBufferSize contains the maximum length on input, and it contains the actual number of bytes read on output.

/* Trigger Source Query */
ViChar rdBuffer[BUFFER_SIZE];
ViInt32 rdBufferSize = sizeof(rdBuffer);
viPrintf (io, ":TRIG:SOUR?\n");
viScanf (io, "%#s", &rdBufferSize, rdBuffer);

END Termination—"%t"

Characters are read from an instrument into the string until the first END indicator is received. This will often be accompanied by the linefeed character (\n), but that is not always the case. Use %T to parse up to a linefeed instead of an END.

Example

This example queries the instrument model on a Tektronix instrument. The model number, a 32-bit integer, is the part of the string between the first two characters "," returned from the instrument. The format string %t specifies that the string reads from the device until the END indicator is received. For instance, if the instrument returns TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04\n, the model number is 210, and the module string is 0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04\n.

/* Instrument Model Information */
ViChar moduleStr[BUFFER_SIZE];
ViInt32 modelNumber;
viPrintf (io, "*IDN?\n");
viScanf (io, "TEKTRONIX,TDS %d,%t", &modelNumber, moduleStr);

Other Terminators—"%[^]", "%*[^]"

Without the asterisk, characters are read from an instrument into the string until the character specified after ^ is read. With the asterisk, characters are discarded until the character specified after ^ is read.

Examples

This is an example of how to perform a self-test. In this case, the format string %256[^\n] specifies the maximum field width of the string as 256 and terminates with a line feed (LF) character.

/* Self Test */
ViChar testMessage[256];
viPrintf (io, "TST\n");
viScanf (io, "%256[^\n]", testMessage);

This example shows how to query for an error. The instrument returns an integer (32 bits) as the error code and a message that terminates with a double-quote ("). The message is in quotes.

/* Error Query */
ViInt32 errCode;
ViChar errMessage[MAX_SIZE];
viPrintf (io, ":STAT:ERR?\n");
viScanf (io, "%d,\"%[^\"]\"", &errCode, errMessage);

This example shows how to query for the instrument manufacturer. The manufacturer name is the first part of the string, up to the character ",", returned from the instrument. For instance, if the instrument returns ROHDE&SCHWARZ,NRVD,835430/066,V1.52 V1.40\n, the manufacturer name is ROHDE&SCHWARZ. The rest of the response is discarded.

/* Instrument Manufacturer */
ViChar rdBuffer[256];
viQueryf (io, "*IDN?\n", "%256[^,]%*T", rdBuffer);

This example shows how to query for the instrument model. The model name is the part of the string between the first two characters "," returned from the instrument. For instance, if the instrument returns ROHDE&SCHWARZ,NRVD, 835430/066,V1.52 V1.40\n, the model name is NRVD. The format string %*[^,] discards the input up to character ",". The final part of the response is also discarded.

/* Instrument Model Information */
ViChar rdBuffer[256];
viQueryf (io, "*IDN?\n", "%*[^,],%256[^,]%*T", rdBuffer);

This example queries the instrument firmware revision. The firmware revision information is everything up to the carriage return (CR) character.

/* Instrument Firmware Revision */
ViChar rdBuffer[256];
viQueryf (io, "ROM?", "%256[^\r]", rdBuffer);