![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to equel.nr CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 42BSD / ingres / doc / unix|
Return to equel.nr CVS log | Up to [CSRG BSD Unix] / 42BSD / ingres / doc / unix |
1.1 root 1: .th EQUEL UNIX 3/14/79
2: .if n .ds EE EQUEL
3: .if t .ds EE \s-2EQUEL\s0
4: .sh NAME
5: equel \- Embedded QUEL interface to C
6: .sh SYNOPSIS
7: .bd equel
8: [
9: .bd \-d
10: ] [
11: .bd \-f
12: ] [
13: .bd \-r
14: ] file.q ...
15: .sh DESCRIPTION
16: .it Equel
17: provides the user with a method of interfacing
18: the general purpose programming language ``C'' with
19: \*(II.
20: It consists of the
21: \*(EE
22: pre-compiler and the
23: \*(EE
24: runtime library.
25: .s1
26: .bd Compilation
27: .s2
28: The precompiler is invoked with the statement:
29: .s3
30: .ti +5
31: .bd equel
32: [<flags>] file1.q [<flags>] file2.q ...
33: .s3
34: where file\c
35: .it n\c
36: \&.q
37: are the source input file names,
38: which must end with
39: .bd \&.q.
40: The output is written to the file
41: ``file\c
42: .it n\c
43: \&.c''.
44: As many files as wished may be specified.
45: .br
46: The flags that may be used are:
47: .de xp
48: .s3
49: .lp +5 5
50: .if n \\$1\t\c
51: .if t \fB\\$1\fP\t\c
52: ..
53: .xp \-d
54: Generate code to print source listing file name
55: and line number when a run-time error occurs. This
56: can be useful for debugging, but takes up process space.
57: Defaults to off.
58: .xp \-f
59: Forces code to be on the same line in the output file
60: as it is in the input file to ease interpreting C diagnostic
61: messages.
62: \*(EE
63: will usually try to get all C code lines in the
64: output file on the same lines as they were in the
65: input file.
66: Sometimes it
67: must break up queries into several lines to avoid C-preprocessor line
68: overflows, possibly moving
69: some C code ahead some lines.
70: With the
71: .bd \-f
72: flag specified this will never happen and, though the line buffer
73: may overflow, C lines will be on the right line.
74: This is useful
75: for finding the line in the
76: source
77: file that C error diagnostics on the
78: output
79: file refer to.
80: .xp \-r
81: Resets flags to default values.
82: Used to supress other flags for
83: some of the files in the argument list.
84: .i0
85: .dt
86: .s3
87: The output files may than be compiled using the C compiler:
88: .s3
89: .ti +5
90: .bd cc
91: file1.c file2.c ...
92: .bd \-lq
93: .s3
94: The
95: .bd \-lq
96: requests the use of the
97: \*(EE
98: object library.
99: .s3
100: All
101: \*(EE
102: routines and globals begin with the characters "II",
103: and so all globals variables and procedure names of the form
104: II\c
105: .it xxx
106: are reserved for use by
107: \*(EE
108: and should be avoided by
109: \*(EE
110: users.
111: .s1
112: .bd "Basic Syntax"
113: .s2
114: \*(EE
115: commands are indicated by lines which begin with a double
116: pound sign (``##'').
117: Other lines are simply copied as is.
118: All normal
119: \*(II
120: commands may be used in
121: \*(EE
122: and have the same effect as if invoked through the interactive
123: terminal monitor.
124: Only retrieve commands with no result relation
125: specified have a different syntax and meaning.
126: .s3
127: The format of retrieve without a result relation is modified to:
128: .s3
129: .in +5
130: ## retrieve (C-variable = a_fcn { , C-variable = a_fcn } )
131: .s3
132: .ti -5
133: optionally followed (immediately) by:
134: .s3
135: ## [
136: .bd where
137: .it qual
138: ]
139: .br
140: ## {
141: .br
142: /\*(** C-code \*(**/
143: .br
144: ## }
145: .i0
146: .s3
147: This statement causes the ``C-code'' to be executed once for
148: each tuple retrieved,
149: with the ``C-variable''s set appropriately.
150: Numeric values of any type are converted as necessary.
151: No conversion is done between numeric and character values.
152: (The normal \*(II
153: .it ascii
154: function may be used for this purpose.)
155: .s3
156: Also, the following
157: \*(EE
158: commands are permitted.
159: .in +5
160: .sp
161: .ti -5
162: .bd "## ingres"
163: [ingres flags] data_base_name
164: .br
165: This command starts
166: \*(II
167: running, and directs all dynamically following queries to
168: the database
169: .it data_base_name.
170: It is a run-time error to execute this command twice
171: without an intervening ``## exit'',
172: as well as to issue queries while an ``## ingres'' statement is
173: not in effect.
174: Each flag should be enclosed in quotes to avoid confusion in the
175: \*(EE
176: parser:
177: .s3
178: ## ingres "\-f4f10.2" "\-i212" demo
179: .s3
180: .ti -5
181: .bd "## exit"
182: .br
183: Exit simply exits from
184: \*(II.
185: It is equivalent to the
186: .bd \eq
187: command to the teletype monitor.
188: .i0
189: .s1
190: .bd "Parametrized Quel Statements"
191: .s2
192: Quel statements with target lists may be ``parametrized''.
193: This is indicated by
194: preceding the statement with the keyword ``param''.
195: The target list of a parametrized statement has the form:
196: .s3
197: (
198: .it "tl_var, argv"
199: )
200: .s3
201: where
202: .it tl_var
203: is taken to be a string pointer at execution time (it may
204: be a string constant) and interpreted as follows.
205: For any parametrized
206: \*(EE
207: statement except a retrieve without a
208: result relation (no ``into rel'') (i.e. append, copy, create, replace,
209: retrieve into) the string
210: .it tl_var
211: is taken to be a regular target list
212: except that wherever a `%' appears a valid
213: \*(II
214: type (f4, f8, i2, i4, c)
215: is expected to follow.
216: Each of these is replaced by the value of the
217: corresponding entry into
218: .it argv
219: (starting at 0)
220: which is interpreted to be a pointer to a variable of the type indicated
221: by the `%' sequence.
222: Neither
223: .it argv
224: nor the variables which it points to
225: need be declared to
226: \*(EE.
227: For example:
228: .ne 12
229: .nf
230: .s3
231: .in +5
232: char \*(**argv[10];
233:
234: argv[0] = &double_var;
235: argv[1] = &int_var;
236: ## param append to rel
237: ## ("dom1 = %f8, dom2 = %i2", argv)
238: ## /\*(** to escape the "%<ingres_type>" mechanism use "%%" \*(**/
239: ## /\*(** This places a single `%' in the string. \*(**/
240: .i0
241: .fi
242: .s3
243: On a retrieve to C-variables, within
244: .it tl_var,
245: instead of
246: the C-variable to retrieve
247: into, the same `%' escape sequences are used to denote the type of the
248: corresponding argv entry
249: into which the value will be retrieved.
250: .s3
251: The qualification of any query may be replaced by a string valued variable,
252: whose contents is interpreted at run time
253: as the text of the qualification.
254: .s3
255: The
256: .it copy
257: statement may also be parametrized.
258: The form of the parametrized
259: .it copy
260: is analogous to the other parametrized statements: the target list
261: may be parametrized
262: in the same manner as the
263: .it append
264: statements, and furthermore, the
265: .bd from/into
266: keyword may be replaced by a string valued variable
267: whose content at run time should be
268: .bd into
269: or
270: .bd from.
271: .s1
272: .bd "Declarations"
273: .s2
274: Any valid C variable declaration on a line
275: beginning with a ``\c
276: .bd ##\c
277: \&''
278: declares a C-variable that may be used
279: in an
280: \*(EE
281: statement and as a normal
282: variable.
283: All variables must be declared before being used.
284: Anywhere a constant may appear in an
285: \*(II
286: command,
287: a C-variable may appear.
288: The value of the C-variable is substituted at execution time.
289: .s3
290: Neither nested structures nor variables of type
291: .it char
292: (as opposed to pointer to char or array of char)
293: are allowed.
294: Furthermore, there are two restrictions in the way variables are
295: referenced within
296: \*(EE
297: statements.
298: All variable usages must be dereferenced
299: and/or subscripted (for arrays and pointers),
300: or selected (for structure variables) to yield lvalues (scalar values).
301: .it Char
302: variables are used by
303: \*(EE
304: as a means to use
305: .it strings.
306: Therefore when using a
307: .it char
308: array or pointer it must be dereferenced only to a ``\c
309: .it "char \*(**\*|\c"
310: \&''.
311: Also, variables may not have parentheses in their references.
312: For example:
313: .ne 12
314: .nf
315: .in +5
316: .s3
317: ## struct xxx
318: ## {
319: int i;
320: ## int \*(**ip;
321: ## } \*(**\*(**struct_var;
322:
323: /\*(** not allowed \*(**/
324: ## delete p where p.ifield = \*(**(\*(**struct_var)->ip
325:
326: /\*(** allowed \*(**/
327: ## delete p where p.ifield = \*(**struct_var[0]->ip
328: .i0
329: .fi
330: .s3
331: C variables declared to
332: \*(EE
333: have either global or local scope.
334: Their scope is local if their declaration is within a free
335: (not bound to a retrieve)
336: block declared to \*(EE.
337: For example:
338: .s3
339: .ne 10
340: .in +5
341: .nf
342: /\*(** globals scope variable \*(**/
343: ## int Gint;
344:
345: func(i)
346: int i;
347: ## {
348: /\*(** local scope variable \*(**/
349: ## int \*(**gintp;
350: ...
351: ## }
352: .fi
353: .in -5
354: .s3
355: If a variable of one of the char types is used almost anywhere
356: in an
357: \*(EE
358: statement
359: the content of that variable is used at run time.
360: For example:
361: .nf
362: .in +5
363: .s3
364: ## char \*(**dbname[MAXDATABASES + 1];
365: int current_db;
366:
367: dbname[current_db] = "demo";
368: ## ingres dbname[current_db]
369: .in -5
370: .fi
371: .s3
372: will cause
373: \*(II
374: to be invoked with data base ``demo''.
375: However, if a variable's name is to be used as a
376: constant, then the non-referencing operator `#' should be used.
377: For example:
378: .nf
379: .ne 13
380: .in +5
381: .s3
382: ## char \*(**demo;
383:
384: demo = "my_database";
385:
386: /\*(** ingres \-d my_database \*(**/
387: ## ingres "\-d" demo
388:
389: /\*(** ingres \-d demo \*(**/
390: ## ingres "\-d" #demo
391: .in -5
392: .fi
393: .s3
394: The C-preprocessor's #include feature may be used
395: on files containing
396: equel statements and declarations if these files
397: are named
398: .it anything\c
399: .bd \&.q.h.
400: An
401: \*(EE
402: processed version of the file, which will
403: be #included by the C-preprocessor, is left in
404: .it anything\c
405: .bd \&.c.h.
406: .s1
407: .bd "Errors and Interrupts"
408: .s2
409: \*(II
410: and run-time
411: \*(EE
412: errors cause the routine
413: .bd IIerror
414: to be called,
415: with the error number and the parameters to the error in an
416: array of string pointers as in a C language main routine.
417: The error message will be looked up
418: and printed. before printing the error message, the routine
419: (\*(**IIprint_err)() is called with the error number that ocurred as
420: its single argument.
421: The error message corresponding to the error number returned
422: by (\*(**IIprint_err)() will be printed.
423: Printing will be supressed if (\*(**IIprint_err)() returns 0.
424: IIprint_err may be reassigned to, and
425: is useful for programs which map
426: \*(II
427: errors into their own
428: error messages.
429: In addition, if the ``\c
430: .bd \-d\c
431: \&''
432: flag was set the file name and line number of the error will be printed.
433: The user may write an IIerror routine to do other tasks
434: as long as the setting of IIerrflag is not modified
435: as this is used to exit retrieves correctly.
436: .s3
437: Interrupts are caught by equel if they are not being ignored.
438: This insures that the rest of \*(II is in sync with the
439: \*(EE
440: process.
441: There is a function pointer, IIinterrupt, which points to a function to
442: call after the interrupt is caught. The user may use this to service the
443: interrupt.
444: It is initialized to "exit()" and is called with \*-1 as its argument.
445: For example:
446: .nf
447: .s3
448: extern int (\*(**IIinterrupt)();
449: extern reset();
450:
451: setexit();
452: IIinterrupt = reset;
453: mainloop();
454: .s3
455: .fi
456: To ignore interrupts, signal() should be called before the
457: ## ingres satatement is executed.
458: .sh FILES
459: .in +5
460: .ti -5
461: \&.../files/error7_\*(**
462: .br
463: Can be used by
464: the user to decipher \*(II error numbers.
465: .ti -5
466: /lib/libq.a
467: .br
468: Run time library.
469: .sh "SEE ALSO"
470: \&.../doc/other/equeltut.q,
471: C reference manual,
472: ingres(UNIX),
473: quel(QUEL)
474: .sh BUGS
475: The C-code embedded in the tuple-by-tuple retrieve operation
476: may not contain additional
477: QUEL statements or recursive invocations of
478: \*(II.
479: .s3
480: There is no way to specify an
481: .bd i1
482: format C-variable.
483: .s3
484: Includes of an equel file within a parameterized target list,
485: or within a C variable's array subscription brackets, isn't
486: done correctly.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.