Incorporating Ingres into the Micro Focus RTS--UNIX
Before you can run any EQUEL/COBOL program, you must create a new Micro Focus Runtime System (RTS), linked with the Ingres libraries. This will enable your EQUEL/COBOL programs to access the necessary Ingres routines at runtime.
If you are not sure your COBOL RTS is linked to the Ingres libraries, you can perform a simple test. Preprocess, compile, and run a simple EQUEL/COBOL program that connects and disconnects from Ingres. For example, the simple test file "test.qcb" could include the lines:
## INGRES dbname
## EXIT dbname
If your COBOL RTS is not linked to the Ingres libraries, you will receive the COBOL runtime error number 173 when you run the program:
$ eqcbl test.qcb
$ cob test.cbl
$ cobrun test
Load error: file 'IIingopen'
error code: 173, pc=1A, call=1, seg=0
173 Called program file not found in drive/directory
Note: Check the Readme file for any operating system specific information on compiling and linking ESQL/COBOL programs.
The COBOL Runtime System
To compile the code produced by the preprocessor, use the Micro Focus cob command.
The following example preprocesses and compiles the file "test1."
$ eqcbl test1.qbc
$ cob test1.cbl
When you use the cob command to compile the generated COBOL code using the cob command, the compiler issues the following informational message:
01 III4-1 PIC S9(9) USAGE COMP-5 SYNC VALUE 0.
**209-I**********************************************
** COMP-5 is machine specific format.
COMP-5 is an Ingres-compatible numeric data type (see
COBOL Variables and Data Types), and a data item of that type is included in the Ingres system COPY file. You can ignore this warning or you can suppress it using the
cob compiler directive or command line flag:
cob -C warning=1
Also, because the program will be run through the COBOL interpreter that is linked to the Ingres runtime system, do not modify the default values of the COBOL compiler align and ibmcomp directives. To run your EQUEL/COBOL test program, use the ingrts command (an alias to your Ingres-linked RTS):
ingrts test1
For more information on building and linking the Interpreter (or RTS), see
Incorporating Ingres into the Micro Focus RTS--UNIX.
Building an Ingres RTS Without the Ingres FRS
If you are using the COBOL screen utilities and do not need the Ingres forms runtime system (FRS) incorporated into your COBOL runtime support module, then you can link the RTS exclusively for database activity.
This section describes how to provide the COBOL RTS with all Ingres runtime routines.
Create a directory in which you want to store the Ingres-linked RTS. For example, if the COBOL root directory is "/usr/lib/cobol", you may want to add a new directory "/usr/lib/cobol/ingres" to store the Ingres/COBOL RTS. From that new directory, issue the commands that extract the Ingres Micro Focus support modules, link the Ingres COBOL RTS, and supply an alias to run the new program. The shell script shown below performs all of these steps. Note that "$II_SYSTEM" refers to the path-name of the Ingres root directory on your system:
#
# These 2 steps position you in the directory in which
# you want to build the RTS
#
mkdir /usr/lib/cobol/ingres
cd /usr/lib/cobol/ingres
#
# Extract 2 Ingres Micro Focus COBOL support modules
#
ar xv $II_SYSTEM/ingres/lib/libingres.a iimfdata.o
ar xv $II_SYSTEM/ingres/lib/libingres.a iimflibq.o
#
# Now link the new Ingres COBOL RTS (this example c
# calls it "ingrts")
#
cob -x -e "" -o ingrts \
iimfdata.o iimflibq.o \
$II_SYSTEM/ingres/lib/libingres.a \
-lc -lm
#
# Provide an alias to run the new program (distribute to
# RTS users)
#
alias ingrts /usr/lib/cobol/ingrts
Ingres shared libraries are available on some Unix platforms. To link with these shared libraries replace "libingres.a" in the cob command with:
-L $II_SYSTEM/ingres/lib -linterp.1 -lframe.1 -lq.1 \
-lcompat.1
To verify if your release supports shared libraries check for the existence of any of these four shared libraries in the $II_SYSTEM/ingres/lib directory. For example:
ls -l $II_SYSTEM/ingres/lib/libq.1.*
Since the resulting RTS is quite large, the temporary holding directory required by COBOL may need to be reset. By default, this directory is set to "/usr/tmp". If you are issued "out of disk space" errors during the linking of the Ingres/COBOL RTS, you should consult your COBOL Programmer's Reference Manual to see how to modify the TMPDIR environment variable.
Note that you may need to specify other system libraries in addition to the "-lm" library on the cob command. The libraries required are the same as those needed to link an EQUEL/C program. The library names may be added to the last line of the cob command shown above. For example, if the "inet" and the "inetd" system libraries are required, the last line of the cob command would be:
-lc -lm -linet -linetd
At this point you are ready to run your EQUEL/COBOL program.
Building an RTS with the Ingres FRS
If you are using the Ingres forms system in your EQUEL/COBOL programs, then you must include the Ingres FRS in the RTS. The link script shown below builds an RTS that includes the Ingres FRS:
#
# Optional: Assume you are in an appropriate directory
# as described in the previous section.
#
cd /usr/lib/cobol/ingres
#
# Extract 3 Ingres Micro Focus support modules
#
ar xv $II_SYSTEM/ingres/lib/libingres.a iimfdata.o
ar xv $II_SYSTEM/ingres/lib/libingres.a iimflibq.o
ar xv $II_SYSTEM/ingres/lib/libingres.a iimffrs.o
#
# Now link the new Ingres COBOL RTS (example calls
# it "ingfrs")
#
cob -x -e "" -o ingfrs \
iimfdata.o iimflibq.o iimffrs.o \
$II_SYSTEM/ingres/lib/libingres.a \
-lc -lm
# Provide an alias to run the new program (distribute
# to RTS users)
#
alias ingfrs /usr/lib/cobol/ingfrs
Here, too, you may be required to specify other system libraries on the
cob command line. For information about how to specify other system libraries on the
cob command line, see
Building an Ingres RTS Without the Ingres FRS.
Including External Compiled Forms in the RTS
The description of how to build an Ingres RTS that can access the Ingres forms system does not include a method with which to include compiled forms into the RTS. (Compiled forms are pre-compiled form objects that do not need to be retrieved from the database. Refer to your language reference manual for a description of precompiled forms.) Since the compiled forms are external objects (in object code), you must link them into your RTS.
Because some UNIX platforms allow you to use the Micro Focus EXTERNAL clause to reference objects linked into your RTS and some do not, two procedures are given here. The first procedure describes how to include external compiled forms in the RTS on a platform that does permit the use of the EXTERNAL clause. The second procedure describes how to perform this task on a platform that does not allow EXTERNAL data items to reference objects linked to the RTS.
Procedure 1
Use this procedure if your platform accepts the EXTERNAL clause to reference objects linked into your RTS.Build and compile the form(s) in VIFRED.
When you compile a form in VIFRED, you are prompted for the name of the file, and VIFRED then creates the file in your directory describing the form in C.
1. Compile the C file into object code:
$ cc -c formfile.c
2. Link the compiled forms into your RTS by modifying the cob command line to include the object code files for the forms. List the files before listing the system libraries that will be linked.
For example:
cob -x -e "" -o ingfrs \
iimfdata.o iimflibq.o iimffrs.o \
form1.o form2.o \
...
Procedure 2
Use this procedure if your platform does not allow you to use the Micro Focus EXTERNAL clause to reference objects linked into your RTS. The extra step forces the external object to be loaded into your RTS and allows access to it through your EQUEL/COBOL program.Build and compile the form or forms in VIFRED.
When you compile a form in VIFRED, you are prompted for the name of the file, and VIFRED then creates the file in your directory describing the form in C.
1. Compile the C file into object code:
$ cc -c formfile.cWrite a small EQUEL/C procedure that just references and initializes the form(s) to the Ingres FRS using the addform statement.
Make sure that the name of the procedure follows conventions allowed for externally called names. For example, external names may be restricted to 14 characters on some versions of COBOL.
For example:
add_form1()
{
## extern int *form1;
## ADDFORM form1
}
add_form2()
{
## extern int *form2;
## ADDFORM form2
}Build the object code for the initialization of the compiled form(s):
$ eqc filename.qc
$ cc -c filename.c
where filename.qc is the name of the file containing the procedure written in Step 3.Link the compiled form(s) and the initialization references to the form(s) into your RTS by modifying the cob command line to include the object files for the forms and the procedure. Specify the object files before the list of system libraries.
For example:
cob -x -e "" -o ingfrs \
iimfdata.o iimflibq.o iimffrs.o \
filename.o form1.o form2.o \
...
where filename.o is the name of object code file resulting from Step 4, containing the initialization references to the forms "form1" and "form2."
2. Replace the addform statement in your source program with a COBOL CALL statement to the appropriate C initialization procedure. For example, what would have been:
## ADDFORM form1
becomes:
CALL "add_form1".
To illustrate this procedure, assume you have compiled two forms in VIFRED, "empform" and "deptform," and need to be able to access them from your EQUEL/COBOL program without incurring the overhead (or database locks) of the forminit statement. After compiling them into C from VIFRED, turn them into object code:
$ cc -c empform.c deptform.c
Now create an EQUEL/C file, "addforms.qc", that includes a procedure (or two) that initializes each one using the addform statement:
add_empform()
{
## extern int *empform;
## ADDFORM empform
}
add_deptform()
{
## extern int *deptform;
## ADDFORM deptform
}
Now build the object code for the initialization of these 2 compiled forms:
$ eqc addforms.qc
$ cc -c addforms.c
Then link the compiled forms and the initialization references to those forms into your RTS:
cob -x -e "" -o ingfrs \
iimfdata.o iimflibq.o iimffrs.o \
addforms.o empform.o deptform.o \
...
Finally, be sure to replace the appropriate addform statements in your source code with COBOL CALL statements.
Note, of course, that you may store all your compiled forms in an archive library that will not require the constant modification of a link script. The sample applications (see
Sample Applications) were built using such a method that included a single file, "addforms.qc", and an archive library, "compforms.a", that included all the compiled forms referenced in the sample applications.
If, at a later time you are able to reference EXTERNAL data items directly from your COBOL source code, then the intermediate step of creating an EQUEL/C addform procedure can be skipped, and your compiled form is declared as an EXTERNAL PIC S9(9) COMP-5 data-item in your EQUEL/COBOL source code:
## 01 empform IS EXTERNAL PIC S9(9) USAGE COMP-5.
...
## ADDFORM empform
The external object code for each form must still be linked into the RTS but there is no need to write an EQUEL/C intermediate file, or call an external C procedure to initialize the compiled form for you.