NAME

INST_QUERY − Compiled SCPI Commands
 

SYNOPSIS

 
INST_QUERY (id, cmd_string, readfmt, [c_expr], c_addr[,c_addr]
 

DESCRIPTION

 
This is an HP Compiled SCPI macro command. The instrument query command arranges to have SCPI commands in the cmd_string parameter sent to the instrument defined by the id parameter.  This command also stores the result(s) from the query command in the address(es) specified by the c_addr parameter(s).
 

PARAMETERS

id

The user variable name for the instrument.  This is the variable name that you assign to the instrument in the INST_DECL or INST_EXTERN command.  For example,
 
INST_DECL (vm, "E1411B", REGISTER);
 
assigns vm as an instrument data pointer to the E1411B.  Now when you use vm as the id in INST_QUERY, an instrument query command will be sent to the HP E1411B.
 

cmd_string

The string constant containing the SCPI commands.  See the instrument’s VXI user’s manual for information on the SCPI commands. 
 
Any SCPI parameter in the string can be expressed with a format specifier.  If a format specifier is used, each [c_expr] parameter that follows contains the corresponding expression.
 
NOTE: The format specifier must be the same type that the instrument expects.  If, for example, the instrument expects a float number, you must use the %f format specifier.  See the instrument’s user manual for information on what the SCPI command expects.
 
NOTE: For MESSAGE configurations, C-SCPI uses the HP SICL iprintf function.  See the HP SICL documentation  for addition information.
 
The following are the available format specifiers for register-based cards.
 
%d :  The %d format indicates that an int is used as the numeric expression for the [c_expr] parameter.  For example,
 
int numb1;
 
INST_QUERY (vm, "MEAS:RES? %d", "%f", numb1, &result);
 
If a comma is present in the format specifier (comma operator only valid with HP-UX 9.0 or later), the [c_expr] is a pointer to an array of integers instead of a numeric expression.  The comma operator is immediately followed by a number indicating the size of the array.  The comma operator can be useful when you have a list of channels to query.  For example,
 
int list [5]= {101,102,103,104,105};
 
INST_QUERY (sw, "CLOSE? (@%,5d)", "%,5d", list, &result);
 
NOTE: C-SCPI requires that the comma operator’s corresponding array contain the complete channel list.  In the C-SCPI command above, for example, you cannot add another comma operator to specify more channels to query.
 
 
%f :  The %f format indicates that a float is used as the numeric expression  for the [c_expr] parameter.  For example,
 
 
float numb1;
 
 
INST_QUERY (vm, "MEAS:RES? %f", "%f", numb1, &result);
 
If a comma is present in the format specifier (comma operator only valid with HP-UX 9.0 or later), the [c_expr] is a pointer to an array of floats instead of a numeric expression.  The comma operator is immediately followed by a number indicating the size of the array.  The comma can be useful when you have a list of channels to query.  For example,
 
float list[5]={101,102,103,104,105};
 
INST_QUERY(sw, "CLOSE? (@%,5f)", "%,5d", list, &result);
 
NOTE: C-SCPI requires that the comma operator’s corresponding array contain the complete channel list.  In the C-SCPI command above, for example, you cannot add another comma operator to specify more channels to query.
 
%s :  The %s format indicates that a string expression without quotations will be used in [c_expr]. For example,
 
char count[5]="MAX";
 
 
INST_QUERY(vm, "SAMP:COUNT? %s","%d",count, &result);
 
 
%S :  The %S format indicates a string expression with quotations will be used for [c_expr]. See INST_SEND for example.
 
 
%r :  The %r format indicates an expression will be used for [c_expr] .
 
%<size>b : The %b format indicates that a char array will be used for [c_expr]. <size> is either a number or an asterisk. The number indicates the size of the array, or the * indicates that the size is taken from the next parameter. (for example, %1024b or %*b).
 
%<size>a :  The %a format indicates that a binary FILE* will be used for  [c_expr].<size> is either a number or an asterisk (*).  The number indicates the size of the array, or the * indicates that the size will be taken from the next parameter (for example,%1024a or  %*a).
 

readfmt

The format of the query result when using a MESSAGE configuration. A format  specifier will be used in this location.  For example,
 
INST_QUERY (vm, "*IDN?", "%s", addrloc);
 
indicates that the result of the *IDN? command will be a string (because of the %s).
 
This command is ignored for register-based cards; however, it is good practice to include it.
 

[c_expr]

The expression that will be used if a format specifier is used in the cmd_string  parameter.  Any valid C expression can be used.  The preprocessor does not check to make sure it is the same type as the format specifier. 
 

c_addr

The address location where the results of the instrument query will be stored.  Any valid  C expression which evaluates to an address can be used.  The preprocessor does not check it.  The address location must be of the same type as the response.  If a string is returned, only non-quoted strings are returned.  See the instrument’s  HP-UX manual page for details on query command response types.  For example, type:
 
 man E1411B
 
to display the manual page for the HP E1411B Multimeter.
 

[c_addr]

The address location if more than one result is returned from the query.  For example, if you have "SYS:ERROR?" as the SCPI command, two items will be returned, the error number and the error message. 
 

COMMENTS

 
Multiple SCPI commands can be combined in the cmd_string parameter.  As with SCPI, these commands are separated by semicolons (;).  For example, *RST;MEAS:VOLT:AC? is a common command linked with a SCPI command separated by semicolons.
 
The cmd_string parameter must be a quoted string, and the SCPI command can not be a variable.  If you want to use a string variable, use the cscpi_exe function call.
 
Register configurations ignore the contents of readfmt. This parameter is used by MESSAGE configurations to specify the format of the query result.
 
When you send a SCPI command to a MESSAGE configuration,  you may have to include a terminator if the instrument expects one.
 
On-Line documentation in the form of C-SCPI manual pages are provided. The manual pages contain a SCPI quick reference, list of commands not supported, commands changed, the SCPI command query response types, a list of overlapping commands, and ONSRQ restrictions.
 
For MESSAGE configurations, C-SCPI uses the HP SICL ipromptf() function.  See the HP SICL documentation for additional information.
 
See also INST_SEND.
 

EXAMPLE

 
This example queries for a card description and stores the result.
 

INST_DECL (vm, "E1411B", REGISTER);
main()
{
int cardnum=1;
char result[255];
.
.
INST_STARTUP();
INST_OPEN (vm, "VXI,24");
.
.
INST_QUERY (vm, "SYSTEM:CDES? %d", "%s" ,cardnum, &result);
.
.
.
printf ("The vm card description: %s 0, result);
}

  —  December 08, 1992