 |
» |
|
|
|
Regardless of the mode you use, the following files must be
available when you invoke the COBOL preprocessor, as shown in
Figure 2-2. Source file: a file containing the COBOL
ALLBASE/SQL program or subprogram with embedded SQL commands for
one or more DBEnvironments. An alternative name can be specified by using the -i option as
explained later in this chapter. ALLBASE/SQL message catalog: a file containing
preprocessor messages and ALLBASE/SQL error and warning
messages. The fully qualified name for the default message
catalog is:
/usr/lib/nls/n-computer/hpsqlcat
|
Note, the COBOL preprocessor does not currently support native
language modes. As Figure 2-2 points out, the COBOL preprocessor creates the
following output files: ALLBASE/SQL message file: a file containing the
preprocessor banner, error and warning messages, and other
messages. The file is named:
Installable module file: a file containing a
copy of the module created by the preprocessor. The default
file name for this file is:
An alternative name can be specified by using the -m option as
explained later in this chapter. When you run the preprocessor in full preprocessing mode,
the preprocessor also stores a module in the DBEnvironment
accessed by your program. The module is used at run time to
execute DBEnvironment operations.
Modified source file: a file containing a
modified version of the source code in the source file. The
default file name for this file is:
An alternative name can be specified by using the -p option as
described later in this chapter.
Copy files: After you use the preprocessor in
full preprocessing mode, you use the modified source file and
the following three copy files as input to the COBOL compiler,
as shown in Figure 2-3. These copy files are generated by the preprocessor and contain
definitions of variables and constants used by COBOL statements
which the preprocessor has inserted into the modified source
code file. Constant copy file: This file, which contains
constant definitions, is:
Variable copy file: This file, which contains
variable definitions, is:
The following copy file is not generated by the preprocessor,
however, it is needed as input to the compiler. - System copy file: This file defines the
ALLBASE/SQL subprogram call number. Its fully qualified name
is:
When you run the preprocessor in full preprocessing mode,
also ensure that the DBEnvironment accessed by the program or
subprogram is available. Source File | |
The source file must be an ASCII file (numbered or unnumbered)
that contains at a minimum the following statements:
IDENTIFICATION DIVISION.
PROGRAM-ID. ProgramName.
AnyStatement.
|
When parsing the source file, the COBOL preprocessor ignores
COBOL statements and COBOL compiler directives except $INCLUDE.
Only the following information is parsed by the COBOL
preprocessor: The Program Name. Unless you specify a module name in the
preprocessor invocation line, the preprocessor uses the
PROGRAM-ID to name the module it stores. A module name can
contain as many as 20 characters and must follow the rules
governing ALLBASE/SQL basic names (given in the ).
Statements found between the prefix EXEC SQL and the suffix
END-EXEC. These statements follow the rules given in the chapter,
"Embedding SQL Commands."
for how and where to embed SQL statements.
Statements found between the BEGIN DECLARE SECTION and END
DECLARE SECTION commands. These commands delimit a declare
section which contains COBOL data description entries for the
host variables used in the program. Host variables are
described in the chapter, "Host Variables."
Figure 2-5 illustrates a source file containing a sample program
using the following SQL commands:
INCLUDE SQLCA
BEGIN DECLARE SECTION
END DECLARE SECTION
WHENEVER
CONNECT
BEGIN WORK
COMMIT WORK
RELEASE
SELECT
SQLEXPLAIN
|
As the sample dialog in Figure 2-4 illustrates, the program
begins a DBE session for PartsDBE, the sample DBEnvironment. It
prompts the user for a part number, then displays information
about the part from the table PURCHDB.PARTS. Warning and error
conditions are handled with WHENEVER and SQLEXPLAIN commands
with the exception of explicit error checking after the SELECT
command. The program continues to prompt for a part number
until a serious error is encountered or until the user enters a
slash (/). Output File Attributes | |
When the source file illustrated in Figure 2-5 is preprocessed,
the attributes of the output files created are as follows:
$ ll cobex2*
-rw-rw-r-- 1 joann dbusers 25814 Jul 2 10:26 cobex2.cbl
-rw-rw-r-- 1 joann dbusers 1539 Jul 2 10:26 cobex2.sqlc
-rw-rw-rw- 1 joann dbusers 1500 Jul 2 10:26 cobex2.sqlm
-rw-rw-rw- 1 joann dbusers 1148 Jul 2 10:26 cobex2.sqlv
$ ll sqlmsg
-rw-rw-rw- 1 joann dbusers 451 Oct 30 10:26 sqlmsg
|
Modified Source File | |
As the COBOL preprocessor parses the source file, it copies
lines from the source file and any copy file(s) into the
modified source file, comments out embedded SQL commands, and
inserts information around each embedded SQL command. The
shaded portions of Figure 2-6 illustrate the
boundaries of the original code commented out and the
modified portions
in the preprocessed file generated from the source file pictured
in Figure 2-5. In both preprocessing modes, the COBOL preprocessor: Inserts an * in column 7 on each line containing an
embedded SQL command to comment out the SQL command for the
COBOL compiler.
Places any punctuation you place after an embedded command on
the line following the last line generated for the embedded
command. Note that the period following the INCLUDE SQLCA
command in the source file is in the same column but on a
different line in the modified source file. In the modified
source file, the period is on the line following the last line
generated by the preprocessor for the INCLUDE SQLCA command.
Inserts three COBOL compiler directives after the
WORKING-STORAGE SECTION label. During compilation, these three
COPY commands reference the copy files of the following syntax:
SourceFileName.sqlc, SourceFileName.sqlv, and
/usr/include/sqlcall.cbl.
Inserts a "Start SQL Preprocessor" comment before and an End SQL
Preprocessor comment after code it modifies.
In full preprocessing mode, the preprocessor also: Generates a COBOL declaration of the SQLCA following the INCLUDE
SQLCA command.
Generates COBOL conditional instructions for the following SQL
commands: WHENEVER SQLERROR, WHENEVER SQLWARNING, and WHENEVER
NOT FOUND.
Generates COBOL sentences that call ALLBASE/SQL external
procedures at run time. These calls reference the module stored
by the preprocessor in the DBEnvironment. Parameters used by
these external calls are defined in the copy files with the syntax
SourceFileName.sqlc and SourceFileName.sqlv, and the system copy file
/usr/include/sqlcall.cbl.
Inserts a "Start Inserted Statements" comment before generated
information.
| | | |  | CAUTION:
Although you can access the preprocessor output files with an
editor, you should never change the information generated by
the COBOL preprocessor. Your DBEnvironment could be damaged at
run time if preprocessor-generated statements are altered.
| | | | |
If you need to change statements not generated by the
preprocessor in preprocessor output files, make the changes to
the source file(s), preprocess the source file(s), and compile
the output files before putting the application program into
production. Preprocessor-Generated Copy Files | |
The preprocessor generates two copy files which contain
declarations for constants and variables referenced in
preprocessor-generated statements in the modified source file.
Figure 2-7 and Figure 2-8 illustrate generated files that
correspond to the modified source file in Figure 2-6. Note that
the preprocessor inserts the following two COBOL compiler
directives to reference copy files of the following syntax:
COPY "SourceFileName.sqlc".
COPY "SourceFileName.sqlv".
|
In addition, a COPY directive, allowing the system copy file to
be compiled with the modified source file, is inserted by the
preprocessor. This file is illustrated in Figure 2-9.
COPY "/usr/include/sqlcall.cbl".
|
These three COPY directives are always inserted in the
WORKING-STORAGE SECTION of a modified source file. COPY Statement Support | |
ALLBASE/SQL supports the COBOL COPY statement. The preprocessor
scans your source code and inserts the indicated
copy files into the preprocessed code.
The REPLACING clause, if specified, is expanded during
compilation (not during preprocessing). Two compiler directives are used in your source code to set and unset
the COPY statement
feature. These are shown in the table below. Table 2-1 Compiler Directives for Implementing the COBOL COPY Statement | Directive | How Used |
|---|
| $SQL COPY | Turns on ALLBASE/SQL COPY statement processing. | | $SQL NOCOPY | Turns off ALLBASE/SQL COPY statement processing.
|
$SQL NOCOPY is the default. To be recognized by the preprocessor,
the $ must appear in column 7 of your source code. A directive
that begins with $SQL is not recognized by the compiler. You can use the directives at any point in your source code.
Perhaps your application has many COPY statements,
some of which reference
files
containing ALLBASE/SQL commands.
If you want only ALLBASE/SQL copy code expanded in your preprocessor
listing,
delimit the appropriate COPY statements with the $SQL COPY and $SQL NOCOPY
directives.
If you want all copy code expanded at preprocessing time, put the $SQL COPY
statement at the beginning of your file.
When you do not use these compiler directives, COPY statements are
processed at compile time. This is appropriate when your copy code
files
do not contain ALLBASE/SQL commands. The following sections are presented in this section: Using the COPY Statement with ALLBASE/SQL. COPY Statement Code Example.
Using the COPY Statement with ALLBASE/SQLCOPY statement syntax and a complete explanation of its use in COBOL
are found in chapter 8 of the
and chapter 6 of the . The following syntax requirements reflect the expanded functionality provided
by the ALLBASE/SQL preprocessor. Italicized names refer to
syntax elements. text-name must be the full file name and path name (if the file is not
in the current directory or the library-name or library-name-literal
is not specified) of the file to be
copied. Compiler defaults for path name and file extensions are not
supported by ALLBASE/SQL. external-file-name-literal
is the name of a file delimited by quotation marks.
This file name may have an extension and may include a path name if no
library-name or library-name-literal is specified. library-name must be the name of a directory or a path.
text-name or
external-file-name-literal is searched for in this location if it is
specified. library-name-literal must be the name of a directory or a path name
within quotation marks.
text-name or external-file-name-literal is searched for in this
location if it is specified. The reserved word SUPPRESS can be used to suppress printing the contents
of the copy file in the compiler listing. Any ALLBASE/SQL commands within a copy file will be preprocessed, but
the REPLACING phrase will have no effect on them. The COPY statement cannot be used within an ALLBASE/SQL command.
COPY Statement Code ExampleSuppose you want to copy a generic error checking routine into your
application. The routine is located in a copy file named ERRORCOPY.
You embed the following COBOL COPY statement in your source code:
$SQL COPY
COPY ERRORCOPY
$SQL NOCOPY
|
The preprocessed output file will be as follows. (Note that ALLBASE/SQL
commands within the copy file have been expanded just as they would
have been if the code had been a part of the main source file.)
|
**** Start SQL Preprocessor ****
*SQL COPY
**** End SQL Preprocessor ****
**** Start SQL Preprocessor ****
*COPY ERRORCOPY.
**** Start insertion of text from: ERRORCOPY
S100-STATUS-CHECK.
IF SQLCODE < DEADLOCK
MOVE 'Y' TO ABORT-FLAG.
PERFORM S200-SQL-EXPLAIN THRU S200-EXIT
UNTIL SQLCODE = 0.
S100-EXIT.
EXIT.
S200-SQL-EXPLAIN.
**** Start SQL Preprocessor ****
* EXEC SQL
* SQLEXPLAIN :SQLMESSAGE
* END-EXEC
**** Start Inserted Statements ****
MOVE SPACES TO SQLREC2
MOVE 2 TO SQLINLEN
CALL SQLXCBL USING SQLXPLN, SQLCA, SQLTEMPV, SQLINLEN,
SQLFALSE
MOVE SQLREC2-FIELD1
TO SQLMESSAGE
**** End SQL Preprocessor ****
DISPLAY SQLMESSAGE.
S200-EXIT.
EXIT.
**** End insertion of text from: ERRORCOPY
**** End SQL Preprocessor ****
**** Start SQL Preprocessor ****
*SQL NOCOPY
**** End SQL Preprocessor ****
|
ALLBASE/SQL Message File | |
Messages placed in the SQL message file, named sqlmsg, come from
the ALLBASE/SQL message catalog, named /usr/lib/hpsqlcat by
default. Ensure that the message catalog is available when you
invoke the COBOL preprocessor. Each SQL message contains four parts: A banner:
MON, MAY 21, 1990, 12:48 PM
HP36217-02A.E1.00 COBOL Preprocessor/9000 ALLBASE/SQL
(C)COPYRIGHT HEWLETT-PACKARD CO. 1982,1983,1984,1985,1986,1987,1988,
1989,1990,1991. ALL RIGHTS RESERVED.
|
A summary of the preprocessor invocation conditions:
DBEnvironment = ../sampledb/PartsDBE
Module Name = COBEX2
|
Warnings and errors encountered during preprocessing:
34 01 PARTNUMBER PIC X(16) COMP.
****** Syntax error in host variable declaration. (DBERR 10932)
.
.
.
There are errors. No sections stored.
|
A summary of the results of preprocessing:
2 ERRORS 0 WARNINGS
END OF PREPROCESSING.
|
Both the banner and the preprocessing summary results are echoed
to the terminal. Note that sqlmsg is recreated each time the
preprocessor is invoked. As illustrated in Figure 2-10, a line number is often provided
in sqlmsg. This line number references the line in the source
file containing the command in question. A message accompanied
by a number may also appear. You can refer to the for
additional information on the exception condition when these
numbered messages appear. As Figure 2-11 illustrates, the preprocessor can terminate with
the warning message ****** ALLBASE/SQL warnings (DBWARN 10602) when the name of an object in the source file does not match the
name of any object in the system catalog. Although a section is
stored for the semantically incorrect command, the section is
marked as invalid and will not execute at run time if it cannot
be validated. Installable Module File | |
When the COBOL preprocessor stores a module in the system
catalog of a DBEnvironment at preprocessing time, it places a
copy of the module in an installable module file. The name of
this file is of the syntax SourceFileName.sqlm. This file can be
installed into a DBEnvironment different from the DBEnvironment
accessed at preprocessing time by using the INSTALL command in
ISQL.
:isql
In order to install the module, you need CONNECT
or DBA authority in the target DBEnvironment:
isql=> CONNECT TO ../sampledb/PartsDBE
isql=> INSTALL;
File name> COBEX2.sqlm
Name of module in this file: login.COBEX2
Number of sections installed: 1
COMMIT WORK to save to DBEnvironment.
isql=> COMMIT WORK;
isql=>
|
Stored Sections | |
In full preprocessing mode, the preprocessor stores a section
for each embedded command except:
BEGIN DECLARE SECTION INCLUDE
BEGIN WORK OPEN
CLOSE PREPARE
COMMIT WORK RELEASE
CONNECT ROLLBACK WORK
DECLARE CURSOR SAVEPOINT
DELETE WHERE CURRENT START DBE
DESCRIBE STOP DBE
END DECLARE SECTION SQLEXPLAIN
EXECUTE TERMINATE USER
EXECUTE IMMEDIATE UPDATE WHERE CURRENT
WHENEVER
|
The commands listed above either require no authorization to
execute or are executed based on information contained in the
compilable preprocessor output files.
Note that if the DELETE WHERE CURRENT or UPDATE WHERE CURRENT command
is dynamically preprocessed, a section does exist in the module. When the preprocessor stores a section, it actually stores what
is known as an input tree and a run tree. The input tree
consists of an uncompiled command. The run tree is the
compiled, executable form of the command. If a section is valid at run time, ALLBASE/SQL executes the
appropriate run tree when the SQL command is encountered in the
application program. If a section is invalid, ALLBASE/SQL
determines whether the objects referenced in the sections exist
and whether current authorization criteria are satisfied. When
an invalid section can be validated, ALLBASE/SQL dynamically
recompiles the input tree to create an executable run tree and
executes the command. When a section cannot be validated, the
command is not executed, and an error condition is returned to
the program. There are three types of sections: Sections for executing the SELECT command associated with a DECLARE CURSOR command.
Sections for executing the SELECT command associated with a CREATE VIEW command.
Sections for all other commands for which the preprocessor stores a section.
Figure 2-12 illustrates the kinds of information in the system
catalog that describe each type of stored section. The query
result illustrated was extracted from the system view named
SYSTEM.SECTION by using ISQL. The columns in Figure 2-12 have
the following meanings: NAME: This column contains the name of the module to which a
section belongs. You specify a module name when you invoke the
preprocessor; the module name is by default the PROGRAM-ID.
OWNER: This column identifies the owner of the module. You
specify an owner name when you invoke the preprocessor; the
owner name is by default the userid associated with the
preprocessing session. DBEFILESET: This column indicates the DBEFileSet with which
DBEFiles housing the section are associated.
SECTION: This column gives the section number. Each section
associated with a module is assigned a number by the
preprocessor as it parses the related SQL command at
preprocessing time.
TYPE: This column identifies the type of section:
1 = SELECT associated with a cursor
2 = SELECT defining a view
0 = All other sections
|
VALID: This column identifies whether a section is valid or
invalid:
The first eighteen rows in this query result describe the sections
stored for the system views. The next two rows describe the two
views in the sample database: PURCHDB.PARTINFO and
PURCHDB.VENDORSTATISTICS. Views are always stored as invalid
sections, because the run tree is always generated at run time. The remaining rows describe sections associated with two
preprocessed programs. COBEX2 contains only one section, for
executing the SELECT command in the program illustrated in
Figure 2-5. COBEX8 contains two sections, one for executing the
SELECT command associated with a DECLARE CURSOR command and one
for executing a FETCH command. Stored sections remain in the system catalog until they are
deleted with the DROP MODULE command or by invoking the
preprocessor with the -d option:
isql=> DROP MODULE COBEX2;
or
$ psqlcbl ../sampledb/PartsDBE -i cobex2 -d
|
Stored sections are marked invalid when: The UPDATE STATISTICS command is executed.
Tables accessed in the program are dropped, altered, or assigned new owners.
Indexes or DBEFileSets related to tables accessed in the program are changed.
Module owner authorization changes occur that affect the execution of embedded commands.
When an invalid section is validated at run time, the validated
section is committed when the program issues a COMMIT WORK
command. If a COMMIT WORK command is not executed, ALLBASE/SQL
must revalidate the section again the next time the program is
executed. For this reason, you should embed COMMIT WORK
commands even following SELECT commands, since the COMMIT WORK
command may be needed even when data is not changed by a
program. |
Printable version
