HP 3000 Manuals HP 3000 Manuals
Preprocessor Input and Output (cont.)
Preprocessor Generated Include Files
SQLCONST and SQLVAR are preprocessor generated include files which
contain declarations for variables and constants referenced in
preprocessor generated sentences in SQLOUT. Figure 2-7 and Figure 2-8
illustrate, respectively, the SQLCONST and SQLVAR files that correspond
to the SQLOUT file in Figure 2-6. Note that the preprocessor inserts the
following two COBOL compiler directives to reference SQLCONST and SQLVAR:
$INCLUDE SQLCONST
$INCLUDE SQLVAR
These two directives are always inserted into the WORKING-STORAGE
SECTION.
Even if you use file equations to redirect the include files, the
preprocessor still inserts the same $INCLUDE directives. Therefore when
you compile preprocessor output, ensure that the preprocess-time file
equations are in effect so the correct include files are compiled:
:FILE SQLCONST=MYCONST
:FILE SQLVAR=MYVAR
:FILE SQLIN=MYPROG
:FILE SQLOUT=MYSQLPRG
. Then the COBOL preprocessor is invoked in full preprocessing mode.
. Later, when then COBOL compiler is invoked, the following
. file equations must be in effect:
:FILE SQLCONST=MYCONST
:FILE SQLVAR=MYVAR
:COB85XL MYSQLPRG, $NEWPASS, $NULL
_______________________________________________________________________
| |
| 01 SQLCONST PIC X. |
| 01 SQLCONST1. |
| 05 SQL0 PIC X(36) VALUE "(4)5061727473444245202020202020". |
| 05 SQL1 PIC X(36) VALUE "202020202020202020202020202020202020".|
| 05 SQL2 PIC X(36) VALUE "202020202020202020202020202020202020".|
| 05 SQL3 PIC X(36) VALUE "202020202020202020202020202020202020".|
| 05 SQL4 PIC X(36) VALUE "202020202020202020202020202020202020".|
| 05 SQL5 PIC X(36) VALUE "202020202020202020202020202020202020".|
| 05 SQL6 PIC X(36) VALUE "202020202020202020202020202020202020".|
| 05 SQL7 PIC X(12) VALUE "202020202020". |
| 01 SQLCONST2. |
| 05 SQL0 PIC X(16) VALUE "00A6007F00110061". |
| e SQLCONST3. |
| 05 SQL0 PIC X(8) VALUE "00A10000". |
| 01 SQLCONST4. |
| 05 SQL0 PIC X(36) VALUE 00AF00002020202020202020202020202020". |
| 05 SQL1 PIC X(12) VALUE "202020202020". |
| 01 SQLTEMPV PIC X(132) VALUE " ". |
_______________________________________________________________________
Figure 2-7. Sample Constant Include File
________________________________________________________________
| |
| 01 SQLREC1 REDEFINES SQLTEMPV. |
| 05 SQLREC1-FIELD1 PIC X(16). |
| 01 SQLREC2 REDEFINES SQLTEMPV. |
| 05 SQLREC2-FIELD1 PIC X(16). |
| 05 SQLREC2-FIELD2 PIC X(30). |
| 05 SQLREC2-FIELD3 PIC S9(8)V9(2) COMP-3.|
| 05 SQLREC2-FIELD3-IND PIC S9(4) COMP. |
| 01 SQLREC3 REDEFINES SQLTEMPV. |
| 05 FILLER PIC X(108). |
| 01 SQLREC4 REDEFINES SQLTEMPV. |
| 05 SQLREC4-FIELD1 PIC X(132). |
| |
________________________________________________________________
Figure 2-8. Sample Variable Include File
COBOL COPY Statement Support
ALLBASE/SQL now supports the COBOL COPY statement. The preprocessor
scans your source code and inserts the indicated copylib modules into the
preprocessed code.
The REPLACING clause, if specified, is expanded during compilation (not
during preprocessing).
Two new 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. |
| | |
---------------------------------------------------------------------------------------------
You can use the directives at any point in your source code. Perhaps
your application has many COPY statements, some of which reference
modules 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 modules do not contain ALLBASE/SQL
commands.
NOTE Insertion of copy text into the preprocessor output file may cause
the current file limit for SQLOUT to be exceeded.
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/SQL.
COPY statement syntax and a complete explanation of its use in COBOL is
found in chapter 13 of the HP COBOL II/XL Reference Manual.
No syntactical differences exist between COBOL and ALLBASE/SQL
implementation of the COPY statement. However, you should be aware of
the following specifics:
* The reserved word NOLIST can be used to suppress printing the
contents of the copylib module 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 Example.
Suppose you want to copy a generic error checking routine into your
application. The routine is located in a module named ERRORCPY in the
errorlib library. You embed the following COBOL COPY statement in your
source code:
$SQL COPY
COPY ERRORCPY OF ERRORLIB
$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 ERRORCPY.
**** Start insertion of text from: ERRORCPY
S100-STATUS-CHECK. ERRORCPY
ERRORCPY
IF SQLCODE < DEADLOCK ERRORCPY
MOVE 'Y' TO ABORT-FLAG. ERRORCPY
ERRORCPY
PERFORM S200-SQL-EXPLAIN THRU S200-EXIT ERRORCPY
UNTIL SQLCODE = 0. ERRORCPY
ERRORCPY
S100-EXIT. ERRORCPY
EXIT. ERRORCPY
ERRORCPY
S200-SQL-EXPLAIN. ERRORCPY
ERRORCPY
ERRORCPY
**** 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 ****
. ERRORCPY
ERRORCPY
DISPLAY SQLMESSAGE. ERRORCPY
ERRORCPY
S200-EXIT. ERRORCPY
EXIT. ERRORCPY
**** End insertion of text from: ERRORCPY
**** End SQL Preprocessor ****
**** Start SQL Preprocessor ****
*SQL NOCOPY
**** End SQL Preprocessor ****
$SET and $IF Statement Support
ALLBASE/SQL supports the COBOL SET and IF compiler directives. If you
want to preprocess only certain parts of your source code to send to the
COBOL compiler, you can set up to ten switches to either ON or OFF. You
can then test a flag for ON by testing whether it evaluates to a boolean
value of true. If the switch evaluates to true, source records are sent
to the compiler, beginning with the first one following the IF statement,
and continuing until another IF statement evaluates to false.
The SET statement is used to turn a switch off and on. Up to ten named
software switches of the form Xn are available, where n is an integer in
the range of 0 through 9. The SET statement has the following syntax:
$SET [Xn={ON } [,Xr={ON }]...]
[ {OFF} [ {OFF}] ]
$IF [Xn={ON }]
[ {OFF}]
Initially, all compilation switches are set to OFF.
A SET statement can appear anywhere in the source text. IF the SET
statement is used without parameters in the form of SET, all switches are
set to OFF.
The IF statement interrogates any of the ten compilations switches. If
the condition specified in the IF statement evaluates to true, source
records are sent to the compiler. An appearance of an IF statement
always terminates the influence of any previous IF statement.
An IF statement that appears without parameters has the same effect as an
IF satement that evaluates to true.
When an IF statement evaluates to false, no source records are sent to
the compiler until an IF statement evaluates to true is encountered.
Code Example.
Suppose you want to conditionally preprocess some parts of your source
code and send it to the compiler, and not preprocess other parts of your
source code, you could use SET and IF statements in your source code, as
follows:
$SET X1=ON,X3=ON
.
.
.
$IF X1=ON
$COMMENT Since X1 is ON, continue sending records to the compiler.
.
.
.
$IF X3=OFF
$COMMENT This $IF statement cancels the preceding one. Since X3 is &
$ set to ON, do not send the following records to the compiler.
$SET X2=ON
$CONTROL NOLIST.
$COMMENT Note that the SET and $CONTROL statements are ignored, &
$ since the previous IF statement was false.
.
.
.
$IF
$COMMENT Previous IF statement conditions are terminated, and &
$ preprocessing and compilation resume.
Considerations When Using $SET and $IF.
SET and IF statement syntax and a complete explanation of their use in
COBOL is found in chapter 13 of the HP COBOL II/XL Reference Manual.
No syntactical differences exist between COBOL and ALLBASE/SQL
implementation of the SET and IF statements. However, you should be
aware of the following specifics:
* If any other SET or CONTROL statements are encountered in the
source records that are being passed over as a result of the IF,
they are ignored by the preprocessor and are not sent to the
compiler.
* EDIT, PAGE, and TITLE statements within a range of source
statements being ignored by the preprocessor are executed.
* The operations of merging of a text and master source file, and
copying of a merged file to a new file are unaffected by IF
statements.
* Use the CONTROL preprocessor statement specifying the NOMIXED
parameter when you do not want to list source records not sent to
the compiler.
ALLBASE/SQL Message File
Messages placed in the ALLBASE/SQL message file (SQLMSG) come from the
ALLBASE/SQL message catalog. The formal file designator for the message
catalog is:
SQLCTxxx.PUB.SYS
where xxx is the numerical value for the current language. If this
catalog cannot be opened, ALLBASE/SQL looks for the default NATIVE-3000
message catalog:
SQLCT000.PUB.SYS
If the default catalog cannot be opened, ALLBASE/SQL returns an error
message saying that the catalog file is not available. If the
NATIVE-3000 catalog is available, the user sees a warning message
indicating that the default catalog is being used. SQLMSG messages
contain four parts:
1. A banner:
WED, OCT 25, 1991, 1:38 PM
HP36216-E1.02 COBOL Preprocessor/3000 ALLBASE/SQL
(C) COPYRIGHT HEWLETT-PACKARD CO. 1982,1983,1984,1985,1986,1987,1988,
1989,1990,1991. ALL RIGHTS RESERVED.
2. A summary of the preprocessor invocation conditions:
SQLIN = COBEX2.SOMEGRP.SOMEACCT
DBEnvironment = partsdbe
Module Name = COBEX2
3. Warnings and errors encountered during preprocessing:
39 01 PARTNUMBER PIC X(16) COMP.
|
****** Syntax error in host variable declaration. (DBERR 10932)
.
.
.
There are errors. No sections stored.
4. A summary of the results of preprocessing:
2 ERRORS 0 WARNINGS
END OF PREPROCESSING.
When you equate SQLMSG to $STDLIST, all these messages appear at the
terminal during your session or in the job stream listing. When SQLMSG
is not equated to $STDLIST, parts 1 and 4 are still sent to $STDLIST, and
all parts appear in the file equated to SQLMSG:
:FILE SQLMSG=MyMsg;Rec=-80,16,f,Ascii
:FILE SQLIN=COBEX2
:RUN PSQLCOB.PUB.SYS;INFO="PartsDBE (DROP)"
WED, OCT 25, 1991, 1:38 PM
HP36216-02A.E1.02 COBOL Preprocessor/3000 ALLBASE/SQL
(C) COPYRIGHT HEWLETT-PACKARD CO. 1982,1983,1984,1985,1986,1987,1988,
1989,1990,1991. ALL RIGHTS RESERVED.
1 ERRORS 0 WARNINGS
END OF PREPROCESSING.
PROGRAM TERMINATED IN AN ERROR STATE. (CIERR 976)
If you want to keep the message file, you should save the file you equate
to SQLMSG. It is created as a temporary file.
As illustrated in Figure 2-9, a line number is often provided in SQLMSG.
This line number references the line in SQLIN containing the command in
question. A message accompanied by a number may also appear. You can
refer to the ALLBASE/SQL Message Manual for additional information on the
exception condition when these numbered messages appear.
_________________________________________________________________________________
| |
| :EDITOR |
| HP32501A.07.20 EDIT/3000 FRI, OCT 27, 1991, 10:20 AM |
| (C) HEWLETT-PACKARD CO. 1990 |
| /T SQLMSG;L ALL UNN |
| FILE UNNUMBERED |
| . |
| . |
| |
| SQLIN = COBEX2.SOMEGRP.SOMEACCT |
| DBEnvironment = partsdbe |
| Module Name = COBEX2 |
| |
| SELCT PARTNUMBER, PARTNAME, SALESPRICE INTO :PARTNUMBER, :PARTNAME,|
| :SALESPRICE :SALESPRICEIND FROM PURCHDB.PARTS WHERE PARTNUMBER = |
| :PARTNUMBER ; |
| |
| ****** ALLBASE/SQL errors (DBERR 10977) |
| ****** in SQL statement ending in line 176 |
| *** <1001> Syntax error. (DBERR 1001) |
| |
| There are errors. No sections stored. |
| |
| 1 ERRORS 0 WARNINGS |
| END OF PREPROCESSING. |
_________________________________________________________________________________
Figure 2-9. Sample SQLMSG Showing Error
As Figure 2-11 illustrates, the preprocessor can terminate with a warning
message. 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.
_________________________________________________________________________________
| |
| :EDITOR |
| HP32501A.07.20 EDIT/3000 FRI, OCT 27 1991, 10:20 AM |
| (C) HEWLETT-PACKARD CO. 1990 |
| /T SQLMSG;L ALL UNN |
| FILE UNNUMBERED |
| . |
| . |
| . |
| SQLIN = COBEX2.SOMEGRP.SOMEACCT |
| DBEnvironment = partsdbe |
| Module Name = COBEX2 |
| |
| SELECT PARNUMBER, PARTNAME, SALESPRICE INTO :PARTNUMBER, :PARTNAME,|
| :SALESPRICE :SALESPRICEIND FROM PURCHDB.PARTS WHERE PARTNUMBER = |
| :PARTNUMBER ; |
| |
| ****** ALLBASE/SQL warnings (DBWARN 10602) |
| ****** in SQL statement ending in line 176 |
| *** Column PARNUMBER not found. (DBERR 2211) |
| |
| 1 Sections stored in DBEnvironment. |
| |
| 0 ERRORS 1 WARNINGS |
| END OF PREPROCESSING |
_________________________________________________________________________________
Figure 2-10. Sample SQLMSG Showing Warning
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. By default the installable module file is named
SQLMOD. The module in this file can be installed into a DBEnvironment
different from the DBEnvironment accessed at preprocessing time by using
the INSTALL command in ISQL. For example:
:RUN PSQLCBL.PUB.SYS;INFO="DBEnvironmentName&
(MODULE(InstalledModuleName)DROP)"
If you want to preserve SQLMOD after preprocessing,
you must keep it as a permanent file. Rename SQLMOD
after making it permanent:
:SAVE SQLMOD
:RENAME SQLMOD,MYMOD
Before invoking ISQL to install this module file,
you may have to transport it and its related
program file to the machine containing the target
DBEnvironment. After all the files are restored on the
target machine, you invoke ISQL on the machine containing
the target DBEnvironment:
:ISQL
In order to install the module, you need CONNECT
or DBA authority in the target DBEnvironment:
isql=> CONNECT TO 'PARTSDBE.SomeGrp.SomeAcct';
isql=> INSTALL;
File name> MYMOD.SOMEGRP.SOMEACCT;
Name of module in this file: JOANN@SOMEACCT.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
FETCH WHENEVER
The commands listed above either require no authorization to execute or
are executed based on information contained in the compilable
preprocessor output files.
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-11 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-11 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 log-on UserName@AccountName 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:
0 = invalid
1 = valid
_________________________________________________________________________________
| |
| isql=>SELECT NAME,OWNER,DBEFILESET,SECTION,TYPE,VALID FROM SYSTEM.SECTION;|
| |
| SELECT NAME,OWNER,DBEFILESET,SECTION,TYPE,VALID FROM SYSTEM.SECTION; |
| ---------------------------------------------------------------------- |
| NAME |OWNER |DBEFILESET |SECTION |TYPE |VALID |
| ---------------------------------------------------------------------- |
| TABLE |SYSTEM |SYSTEM | 0| 2| 0 |
| COLUMN |SYSTEM |SYSTEM | 0| 2| 0 |
| INDEX |SYSTEM |SYSTEM | 0| 2| 0 |
| SECTION |SYSTEM |SYSTEM | 0| 2| 0 |
| DBEFILESET |SYSTEM |SYSTEM | 0| 2| 0 |
| DBEFILE |SYSTEM |SYSTEM | 0| 2| 0 |
| SPECAUTH |SYSTEM |SYSTEM | 0| 2| 0 |
| TABAUTH |SYSTEM |SYSTEM | 0| 2| 0 |
| COLAUTH |SYSTEM |SYSTEM | 0| 2| 0 |
| MODAUTH |SYSTEM |SYSTEM | 0| 2| 0 |
| GROUP |SYSTEM |SYSTEM | 0| 2| 0 |
| VIEWDEF |SYSTEM |SYSTEM | 0| 2| 0 |
| HASH |SYSTEM |SYSTEM | 0| 2| 0 |
| CONSTRAINT |SYSTEM |SYSTEM | 0| 2| 0 |
| CONSTRAINTCOL |SYSTEM |SYSTEM | 0| 2| 0 |
| CONSTRAINTINDEX |SYSTEM |SYSTEM | 0| 2| 0 |
| COLDEFAULT |SYSTEM |SYSTEM | 0| 2| 0 |
| TEMPSPACE |SYSTEM |SYSTEM | 0| 2| 0 |
| PARTINFO |PURCHDB |SYSTEM | 0| 2| 0 |
| VENDORSTATISTICS |PURCHDB |SYSTEM | 0| 2| 0 |
| COBEX2 |KAREN@THOMAS |SYSTEM | 1| 0| 1 |
| EXP11 |KAREN@THOMAS |SYSTEM | 1| 1| 1 |
| EXP11 |KAREN@THOMAS |SYSTEM | 2| 0| 1 |
| ---------------------------------------------------------------------- |
| Number of rows selected is 16. |
| U[p], d[own], l[eft], r[ight], t[op], b[ottom], pr[int] <n>,or e[nd]> |
_________________________________________________________________________________
Figure 2-11. Information in SYSTEM.SECTION on Stored Sections
The first eleven 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-6. EXP11 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 DROP
option:
isql=> DROP MODULE COBEX2;
or
:RUN PSQLCOB.PUB.SYS;INFO="PartsDBE (MODULE(COBEX2) DROP)"
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.