Complete Linux

home *** CD-ROM | disk | FTP | other *** search

/ Complete Linux / Complete Linux.iso / docs / apps / database / ingres04.lzh / doc / quel / macros.doc < prev next >

Wrap

Text File | 1992-11-19 | 13.4 KB | 327 lines

MACROS(QUEL) 2/19/79 MACROS(QUEL) NAME macros - terminal monitor macro facility DESCRIPTION The terminal monitor macro facility provides the ability to tailor the QUEL language to the user's tastes. The macro facility allows strings of text to be removed from the query stream and replaced with other text. Also, some built in macros change the environment upon execution. _B_a_s_i_c _C_o_n_c_e_p_t_s All macros are composed of two parts, the _t_e_m_p_l_a_t_e part and the _r_e_p_l_a_c_e_m_e_n_t part. The template part defines when the macro should be invoked. For example, the template ``ret'' causes the corresponding macro to be invoked upon encounter- ing the word ``ret'' in the input stream. When a macro is encountered, the template part is removed and replaced with the replacement part. For example, if the replacement part of the ``ret'' macro was ``retrieve'', then all instances of the word ``ret'' in the input text would be replaced with the word ``retrieve'', as in the statement ret (p.all) Macros may have parameters, indicated by a dollar sign. For example, the template ``get $1'' causes the macro to be triggered by the word ``get'' followed by any other word. The word following ``get'' is remembered for later use. For example, if the replacement part of the ``get'' macro where retrieve (p.all) where p.pnum = $1 then typing ``get 35'' would retrieve all information about part number 35. _D_e_f_i_n_i_n_g _M_a_c_r_o_s Macros can be defined using the special macro called ``de- fine''. The template for the define macro is (roughly) {define; $t; $r} where $t and $r are the template and replacement parts of the macro, respectively. Let's look at a few examples. To define the ``ret'' macro discussed above, we would type: {define; ret; retrieve} When this is read, the macro processor removes everything between the curly braces and updates some tables so that ``ret'' will be recognized and replaced with the word ``re- trieve''. The define macro has the null string as replace- ment text, so that this macro seems to disappear. A useful macro is one which shortens range statements. It can be defined with {define; rg $v $r; range of $v is $r} This macro causes the word ``rg'' followed by the next two words to be removed and replaced by the words ``range of'', followed by the first word which followed ``rg'', followed by the word ``is'', followed by the second word which fol- lowed ``rg''. For example, the input rg p parts becomes the same as range of p is parts _E_v_a_l_u_a_t_i_o_n _T_i_m_e_s When you type in a define statement, it is not processed im- mediately, just as queries are saved rather than executed. No macro processing is done until the query buffer is evaluated. The commands \go, \list, and \eval evaluate the query buffer. \go sends the results to INGRES, \list prints them on your terminal, and \eval puts the result back into the query buffer. It is important to evaluate any define statements, or it will be exactly like you did not type them in at all. A common way to define macros is to type {define . . . } \eval \reset If the \eval was left out, there is no effect at all. _Q_u_o_t_i_n_g Sometimes strings must be passed through the macro processor without being processed. In such cases the grave and acute accent marks (` and ') can be used to surround the literal text. For example, to pass the word ``ret'' through without converting it to ``retrieve'' we could type `ret' Another use for quoting is during parameter collection. If we want to enter more than one word where only one was ex- pected, we can surround the parameter with accents. The backslash character quotes only the next character (like surrounding the character with accents). In particular, a grave accent can be used literally by preceeding it with a backslash. Since macros can normally only be on one line, it is fre- quently useful to use a backslash at the end of the line to hide the newline. For example, to enter the long ``get'' macro, you might type: {define; get $n; retrieve (e.all) \ where e.name = "$n"} The backslash always quotes the next character even when it is a backslash. So, to get a real backslash, use two backslashes. _M_o_r_e _P_a_r_a_m_e_t_e_r_s Parameters need not be limited to the word following. For example, in the template descriptor for define: {define; $t; $r} the $t parameter ends at the first semicolon and the $r parameters ends at the first right curly brace. The rule is that the character which follows the parameter specifier terminates the parameter; if this character is a space, tab, newline, or the end of the template then one word is col- lected. As with all good rules, this one has an exception. Since system macros are always surrounded by curly braces, the macro processor knows that they must be properly nested. Thus, in the statement {define; x; {sysfn}} The first right curly brace will close the ``sysfn'' rather than the ``define''. Otherwise this would have to be typed {define; x; `{sysfn}'} Words are defined in the usual way, as strings of letters and digits plus the underscore character. _O_t_h_e_r _B_u_i_l_t_i_n _M_a_c_r_o_s There are several other macros built in to the macro proces- sor. In the following description, some of the parameter specifiers are marked with two dollar signs rather than one; this will be discussed in the section on prescanning below. {define; $$t; $$r} defines a macro as discussed above. Spe- cial processing occurs on the template part which will be discussed in a later section. {rawdefine; $$t; $$r} is another form of define, where the special processing does not take place. {remove; $$n} removes the macro with name $n. It can remove more than one macro, since it actually removes all macros which might conflict with $n under some circumstance. For example, typing {define; get part $n; . . . } {define; get emp $x; . . . } {remove; get} would cause both the get macros to be removed. A call to {remove; get part} would have only removed the first macro. {type $$s} types $s onto the terminal. {read $$s} types $s and then reads a line from the terminal. The line which was typed replaces the macro. A macro called ``{readcount}'' is defined containing the number of charac- ters read. A control-D (end of file) becomes -1, a single newline becomes zero, and so forth. {readdefine; $$n; $$s} also types $s and reads a line, but puts the line into a macro named $n. The replacement text is the count of the number of characters in the line. {readcount} is still defined. {ifsame; $$a; $$b; $t; $f} compares the strings $a and $b. If they match exactly then the replacement text becomes $t, otherwise it becomes $f. {ifeq; $$a; $$b; $t; $f} is similar, but the comparison is numeric. {ifgt; $$a; $$b; $t; $f} is like ifeq, but the test is for $a strictly greater than $b. {substr; $$f; $$t; $$s} returns the part of $s between char- acter positions $f and $t, numbered from one. If $f or $t are out of range, they are moved in range as much as possi- ble. {dump; $$n} returns the value of the macro (or macros) which match $n (using the same algorithm as remove). The output is a rawdefine statement so that it can be read back in. {dump} without arguments dumps all macros. _M_e_t_a_c_h_a_r_a_c_t_e_r_s Certain characters are used internally. Normally you will not even see them, but they can appear in the output of a dump command, and can sometimes be used to create very fancy macros. \| matches any number of spaces, tabs, or newlines. It will even match zero, but only between words, as can occur with punctuation. For example, \| will match the spot between the last character of a word and a comma following it. \^ matches exactly one space, tab, or newline. \& matches exactly zero spaces, tabs, or newlines, but only between words. _T_h_e _D_e_f_i_n_e _P_r_o_c_e_s_s When you define a macro using define, a lot of special pro- cessing happens. This processing is such that define is not functionally complete, but still adequate for most require- ments. If more power is needed, rawdefine can be used; how- ever, rawdefine is particularly difficult to use correctly, and should only be used by gurus. In define, all sequences of spaces, tabs, and newlines in the template, as well as all ``non-spaces'' between words, are turned into a single \| character. If the template ends with a parameter, the \& character is added at the end. If you want to match a real tab or newline, you can use \t or \n respectively. For example, a macro which reads an en- tire line and uses it as the name of an employee would be defined with {define; get $n\n; \ ret (e.all) where e.name = "$n"} This macro might be used by typing get *Stan* to get all information about everyone with a name which in- cluded ``Stan''. By the way, notice that it is ok to nest the ``ret'' macro inside the ``get'' macro. _P_a_r_a_m_e_t_e_r _P_r_e_s_c_a_n Sometimes it is useful to macro process a parameter before using it in the replacement part. This is particularly im- portant when using certain builtin macros. For prescan to occur, two things must be true: first, the parameter must be specified in the template with two dollar signs instead of one, and second, the actual parameter must begin with an ``at'' sign (``@'') (which is stripped off). For an example of the use of prescan, see ``Special Macros'' below. _S_p_e_c_i_a_l _M_a_c_r_o_s Some special macros are used by the terminal monitor to con- trol the environment and return results to the user. {begintrap} is executed at the beginning of a query. {endtrap} is executed after the body of a query is passed to INGRES. {continuetrap} is executed after the query completes. The difference between this and endtrap is that endtrap occurs after the query is submitted, but before the query executes, whereas continuetrap is executed after the query executes. {editor} can be defined to be the pathname of an editor to use in the \edit command. {shell} can be defined to be the pathname of a shell to use in the \shell command. {tuplecount} is set after every query (but before con- tinuetrap is sprung) to be the count of the number of tuples which satisfied the qualification of the query in a re- trieve, or the number of tuples changed in an update. It is not set for DBU functions. If multiple queries are run at once, it is set to the number of tuples which satisfied the last query run. For example, to print out the number of tuples touched au- tomatically after each query, you could enter: {define; {begintrap}; {remove; {tuplecount}}} {define; {continuetrap}; \ {ifsame; @{tuplecount}; {tuplecount};; \ {type @{tuplecount} tuples touched}}} SEE ALSO monitor(quel)