Syntax of Param Statements
These statements are called param statements because of the param function in place of its target list. The param function has the following syntax:
param (target_string, var_address_array)
Thus, for example, a param retrieve statement might look like this:
## retrieve (param (targetstr, varaddr))
## where qual_string
The target_string is a formatted target list string that can be either a C string variable or a C string constant. Normally it is a variable, since the purpose of this feature is to allow statements to be built at runtime. The var_address_array is an array of pointers to which values are assigned at runtime. The elements in this array then hold the addresses of variables of appropriate types to receive or supply data for the table columns or form fields with which the param statement interacts.
The target_string looks like a regular target list expression, except where a C variable intended to receive or supply data in an assignment would normally appear. In place of these names, the target_string contains symbolic type indicators representing the variables. For each of these type indicators appearing in the target list, there must be an address recorded in the corresponding element of the var_address_array, beginning with var_address_array[0].
At runtime, EQUEL processes the statement by associating the variable addresses with the type indicators embedded in the target_string. Addresses must previously have been placed in the cells of the array in a sequence corresponding to the sequence of type indicators in the target_string, such that the statement will find a list of the correct number of C variables of the correct type.
The variable-type indicators can be any of the following:
In the list above, the length specifier N is optional. For further storage class information, see
The Varying Length String Type.
In this context, the format indicator must always agree with the C variable that supplies or receives the data. This format does not need to be the same as that of the column where the data is stored in the database. Store data to be retrieved from, or inserted into, table columns of type date in character arrays of a length of at least 26 in your program. Items of type money should be retrieved into program variables of type float or double.
When you reference ordinary character-string data in a param target list, you can use the "c" type indicator with or without specifying the number of characters to be assigned. The optional length specification has the following effect, depending on the kind of statement in which the target list appears:
• In an input statement, such as append or putform, the length specification, N, attached to a "c" type indicator, limits to N the number of bytes actually assigned from the C character string variable to the database or form object. The length specification should not include the null string-termination byte. If N is specified, the string need not be null-terminated.
• In an output statement, such as retrieve or getform, the length specification limits to N the number of bytes of actual data assigned from the database or form object to the C character string variable (this is the number of bytes assigned before the null string-terminator is appended). In this context, the length specifier can be useful for preventing the EQUEL runtime system from writing more bytes into a C program variable than the variable has room to hold. In the absence of the length specifier, EQUEL would write into the variable the full length of data located in the column or field and then append the null byte as string terminator.
You must use another type indicator, "v", when referencing data stored in a buffer of the EQUEL-defined
varchar storage class. (For information about this special storage class, see
The Varying Length String Type.) The
varchar class receives and sends data that may contain the ASCII null character as valid data. This applies to both the
char and
varchar data types in QUEL. Since the C language ordinarily uses the null character as a string terminator, ordinary string-handling routines are not appropriate for this type of data.
A length specifier, N, can also be used in conjunction with the "v" type indicator. If used, it has the following effect:
• In an input statement, such as append or putform, it is ignored. The count of valid characters, contained in the varchar C structure itself, overrides in this case.
• In an output statement, such as retrieve or getform, it limits the number of bytes actually transferred into the data buffer of the varchar C structure.
The following example contains a param append statement:
main ()
## {
/*
** Declare variables to be used for supplying data
** to the database
*/
## char ch_var[27];
## int int_var;
## double doub_var;
/* Declare variables for the PARAM target list, the
** array of variable addresses, and the database
** table to be used
*/
## char targlist[100];
## char *varaddr[10];
## char tablename[25];
/* Now assign values to variables in order to set up
** the PARAM statements. In a real application, this
** would be done during the process of interacting
** with the user, as well as by obtaining
** information from system catalogs, or from the
** FRS, about the number and data type of table
** columns. In this example, the assignments are
** hard-coded.
*/
strcpy (tablename, "employee");
/* The following target list is for use with
** the APPEND statement. Note that the type
** indicators appear on the right-hand side of
** the assignments. Column names appear on the
** left-hand side.
*/
strcpy (targlist,
"empname=%c, empnum=%i4, salary=%f8");
/* The next three statements assign, to an array of
** character pointers, the addresses of variables
** which will supply data for the APPEND statement.
** Because the values being assigned are addresses
** of several different types of variables, they
** need to be cast to character-pointer type.
*/
varaddr[0] = (char *) ch_var;
varaddr[1] = (char *) &int_var;
varaddr[2] = (char *) &doub_var;
/* Next, values are assigned to the data variables
** themselves. Again, in an actual application this
** would likely be done by interacting with the
** user.
*/
strcpy (ch_var, "Swygart, Jane");
int_var = 332;
doub_var = 37500.00;
## ingres "personnel"
## append to tablename (param (targlist, varaddr))
## exit
exit (0);
## }