Return to equel.nr CVS log

Up to [CSRG BSD Unix] / 43BSD / ingres / doc / unix

Annotation of 43BSD/ingres/doc/unix/equel.nr, revision 1.1

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.