USE Files
A USE file is a text file containing a list of OdxSQL commands to be
processed automatically without the need for user interaction. Directives
placed throughout the USE file control the flow of the execution. OdxSQL
processes each command in the file in order until it encounters an error
or the end of the file. If an error occurs, by default, processing halts
and all subsequent commands are ignored.
To prevent OdxSQL from halting execution when an error occurs, set the
ERRORS set option to CONTINUE either before issuing the USE command or
at the beginning of the USE file.
A WHERE clause passed with the USE filename command can instruct OdxSQL
to execute only a certain block of commands in the USE file defined with
directives. Directives can be used to assign a name to a block of commands,
so when referenced in the WHERE clause, only the specified block and commands
contained within a COMMON directive, will be executed. Directives can
also be used to suspend execution on a certain block of commands, causing
all commands except the suspended block to be executed.
Commands in a USE file are executed in order as they appear in the file.
Therefore, they must occur in proper logical order. For example, a CONNECT
must occur before a SELECT and an ATTACH OST must occur before a DETACH
OST.
Using Directives
Directives are tags placed inside a USE file to control the flow of
the use file commands. They divide a USE file into sections that will
be treated differently, according to the directive. With the exception
of VERBOSE and QUIET, all directives come in pairs: one marking the beginning
of a section and one marking the end of that section.
Directives are defined in a comment line inside < > tags. Multiple
directives on a single line must be placed within the same < > tags.
For example,
;<COMMON VERBOSE> is the correct
way
;<COMMON><VERBOSE> will
not work. <VERBOSE> is
ignored.
In the second example, the first directive, COMMON, will be implemented;
everything after that will be ignored.
Comments can be placed on the same line as a directive as long as they
come after the directive. If comments are placed on the line before the
directive, the directive will be ignored.
Blocks of commands can be separated using directives to prevent them
from being executed, ensure that they are always executed, group them
together by some logic, or name them to be explicitly executed. For example,
if a block of commands was separated and named using the SECTION directive,
this particular section could be executed while the rest of the USE file
is ignored, with the exception of the COMMON sections, which are always
executed.
USE file (useme.txt)
;<COMMON>
CONNECT ORDERS.ENV
;<END_COMMON>
OPEN CURSOR
SET CURSOR 1
...
;<QUIET>
...
;<SECTION=secname>
select * from customers
;<END_SECTION>
...
;<VERBOSE>
...
;<COMMON>
DISCONNECT
;<END_COMMON>
OdxSQL
>USE useme.txt WHERE section='secname'
...
In the above example, from the beginning of the file, execution proceeds
as follows:
The first COMMON section is executed - CONNECT ORDERS.ENV
All subsequent commands are ignored until the QUIET directive is reached,
which is then executed.
Again, all subsequent commands are ignored until the SECTION named 'secname'
is reached. The commands inside this SECTION are executed (select * from
customers)
All subsequent commands are ignored until the VERBOSE directive is reached,
which is then executed.
Again, all subsequent commands are ignored until the final COMMON directive
is reached, and the commands inside this common area are executed (DISCONNECT).
Directives
<VERBOSE>
The VERBOSE directive instructs OdxSQL to echo each command in the USE
file to the OdxSQL window, as it is executed. VERBOSE can be set by itself
or with another directive within the same < > tags.
;<VERBOSE> By itself OR
;<COMMON VERBOSE> with another directive
<QUIET>
The QUIET directive prevents OdxSQL from echoing each command in the USE
file to the OdxSQL window, as it is executed. Like VERBOSE, QUIET can
be set by itself or with another directive within the same < > tags.
;<QUIET> By itself OR
;<COMMON QUIET> with another directive
<SUSPEND>
The SUSPEND directive is used with the RESUME directive to prevent OdxSQL
from executing a group of commands in a USE file. SUSPEND marks the beginning
of the section and RESUME marks the end. Everything between these two
directives will be ignored, including other directives.
CONNECT ORDERS.ENV
;<SUSPEND> Stop executing commands here
OPEN CURSOR
OPEN CURSOR
SET CURSOR 1
;<RESUME> Resume executing commands here
<RESUME>
The RESUME directive causes OdxSQL to resume executing commands in a USE
file. It is used in conjunction with the SUSPEND directive, which marks
the place to stop executing commands in a USE file. Everything between
these two directives will be ignored, including other directives.
<COMMON>
T he COMMON directive marks the beginning of a section of commands in
a USE file that will be executed every time the USE file is processed
by OdxSQL. END_COMMON marks the end of this section. A COMMON block is
terminated by an END_COMMON directive, another COMMON directive, a SECTION=name
directive, or a TEST=name directive. For clarity, an END_COMMON directive
should always be used.
;<COMMON>
CONNECT ORDERS.ENV
OPEN CURSOR
SET CURSOR 1
;<END_COMMON>
...
;<COMMON>
DISCONNECT
;<END_COMMON>
<END_COMMON>
The END_COMMON directive marks the end of a section of commands in a USE
file that will be executed every time the USE file is processed by OdxSQL.
COMMON marks the beginning of this section.
<SECTION=name>
The SECTION=name directive marks the beginning of a section or block of
commands and gives it the specified name so that it can be referenced
in the WHERE clause of a USE command. A SECTION block is terminated by
an END_SECTION directive, another SECTION=name2 directive, a COMMON directive,
or a TEST=name directive. For clarity, an END_SECTION directive should
always be used.
<END_SECTION>
The END_SECTION directive marks the end of the last named SECTION in the
USE file. SECTION=name marks the beginning of this section.
<TEST=name>
The TEST=name directive marks the beginning of a small group of commands
that are logically linked in some way. For example, a qualify and select
statement could be grouped together. A TEST block is terminated by an
END_TEST directive, another TEST=name2 directive, a COMMON directive,
or a SECTION=name directive. For clarity, an END_TEST directive should
always be used.
<END_TEST>
The END_TEST directive marks the end of the last named TEST in the USE
file. TEST=name marks the beginning of this section.
Top
|
