EQUEL(1) | General Commands Manual | EQUEL(1)

# NAME

`equel` —
Embedded QUEL precompiler for C

# SYNOPSIS

`equel` | [`-d`] [`-f`] [`-r`] file.q ...

# DESCRIPTION

The `equel` utility provides a method of interfacing the general purpose programming language C with INGRES. It consists of the EQUEL precompiler and the EQUEL runtime library.

The precompiler reads source input files which must end with the .q extension. The output is written to corresponding .c files. As many files as desired may be specified. Flags may be interspersed between file names and apply to subsequent files.

The options are as follows:

`-d`
  Generate code to print source listing file name and line number when a run-time error occurs. This can be useful for debugging, but takes up process space. Defaults to off.
`-f`
  Force code to be on the same line in the output file as it is in the input file, to ease interpreting C diagnostic messages. EQUEL will usually try to keep C code lines in the output file on the same lines as they were in the input file. Sometimes it must break up queries into several lines to avoid C-preprocessor line overflows, possibly moving some C code ahead some lines. With the `-f` flag, this will never happen and, though the line buffer may overflow, C lines will be on the right line.
`-r`
  Reset flags to default values. Used to suppress other flags for some of the files in the argument list.

The output files may then be compiled using the C compiler:

`cc file1.c file2.c ... -lq`

The `-lq` flag requests the use of the EQUEL object library.

## Basic Syntax

EQUEL commands are indicated by lines which begin with a double pound sign (“##”). Other lines are simply copied as is. All normal INGRES commands may be used in EQUEL and have the same effect as if invoked through the interactive terminal monitor. Only retrieve commands with no result relation specified have a different syntax and meaning.

The format of retrieve without a result relation is:

    ## retrieve (C-variable = a_fcn {, C-variable = a_fcn})
    ## [where qual]
    ## {
    	/* C-code */
    ## }

This statement causes the C-code to be executed once for each tuple retrieved, with the C-variables set appropriately. Numeric values of any type are converted as necessary. No conversion is done between numeric and character values.

## EQUEL Commands

`## ingres` [flags database]
  Start INGRES running and direct all dynamically following queries to database. It is a run-time error to execute this command twice without an intervening `## exit`. Each flag should be enclosed in quotes:

  `## ingres "-f4f10.2" "-i212" demo`
`## exit`
  Exit from INGRES. Equivalent to the `\q` command to the terminal monitor.

## Parametrized QUEL Statements

QUEL statements with target lists may be “parametrized” by preceding the statement with the keyword `param`. The target list has the form:

`(tl_var, argv)`

Where tl_var is taken to be a string pointer at execution time and interpreted as a regular target list, except that wherever a ‘`%`’ appears, a valid INGRES type (f4, f8, i2, i4, c) is expected to follow. Each of these is replaced by the value of the corresponding entry in argv.

## Declarations

Any valid C variable declaration on a line beginning with “##” declares a C-variable that may be used in an EQUEL statement and as a normal variable. All variables must be declared before being used. Anywhere a constant may appear in an INGRES command, a C-variable may appear. The value is substituted at execution time.

Neither nested structures nor variables of type char (as opposed to pointer to char or array of char) are allowed. Variables declared to EQUEL have either global or local scope. Their scope is local if their declaration is within a free (not bound to a retrieve) block declared to EQUEL.

The C-preprocessor's `#include` feature may be used on files containing EQUEL statements and declarations if these files are named with a .q.h extension. An EQUEL-processed version of the file will be left with a .c.h extension.

## Errors and Interrupts

INGRES and run-time EQUEL errors cause the routine `IIerror`() to be called with the error number and the parameters to the error. The error message will be looked up and printed. Before printing the error message, the function pointed to by IIprint_err is called with the error number; printing will be suppressed if it returns 0. IIprint_err may be reassigned and is useful for programs which map INGRES errors into their own error messages.

Interrupts are caught by EQUEL if they are not being ignored. There is a function pointer, IIinterrupt, which points to a function to call after the interrupt is caught. It is initialized to `exit`() and is called with -1 as its argument.

All EQUEL routines and globals begin with the characters “II”; all global variables and procedure names of the form IIxxx are reserved for use by EQUEL and should be avoided.

# FILES

.../files/error7_*
  Error message files.
/lib/libq.a
  Run-time library.

# SEE ALSO

cc(1), ingres(1)

# BUGS

The C-code embedded in the tuple-by-tuple retrieve operation may not contain additional QUEL statements or recursive invocations of INGRES.

There is no way to specify an i1 format C-variable.

Includes of an EQUEL file within a parametrized target list, or within a C variable's array subscript brackets, are not handled correctly.

# HISTORY

Originally part of UC Berkeley INGRES 8.9 (1988).

March 28, 2026 | NetBSD 10.1_STABLE