Embedded SQL Companion Guide > Embedded SQL Companion Guide > Embedded SQL for COBOL > Preprocessor Operation > How to Incorporate Ingres into the Micro Focus RTS--Linux
Was this helpful?
How to Incorporate Ingres into the Micro Focus RTS--Linux
Before you can run any embedded SQL/COBOL program, you must create a new Micro Focus Runtime System (or RTS), linked with the Ingres libraries. This will enable your embedded SQL/COBOL programs to access the necessary Ingres routines at runtime.
If you are unsure whether your COBOL RTS is linked to the Ingres libraries, you can perform a simple test. Preprocess, compile, and run a simple ESQL/COBOL program that connects and disconnects from Ingres. For example, the simple test file test.scb could include the lines:
EXEC SQL CONNECT dbname END-EXEC.
EXEC SQL DISCONNECT END-EXEC.
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:
esqlcbl test.scb
cob test.cbl
cobrun test
    Load error: file 'IIsqConnect'
    error code: 173, pc=1A, call=1, seg=0
    173 Called program file not found in
         drive/directory
How to Build an Ingres RTS without the Ingres FRS
If you are using the COBOL screen utilities and do not need to incorporate the Ingres forms runtime system (FRS) 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 to where 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
# 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 Linux 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.*
Any user-defined handlers must also be incorporated into the Ingres/COBOL RTS, and should be added to the cob command line. For a detailed description, see Include User-Defined Handlers in the Micro Focus RTS--Linux in this chapter.
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.
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 need to link an embedded SQL/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 embedded SQL/COBOL program.
How to Build an RTS with the Ingres FRS
If you are using the Ingres forms system in your embedded SQL/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 (this 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
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 How to Build an Ingres RTS without the Ingres FRS in this chapter.
How to Include 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. Recall that compiled forms are precompiled form objects that do not need to be retrieved from the database. Since the compiled forms are externals objects (in object code) you must link them into your RTS.
Because some Linux 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 for Platforms that Accept the EXTERNAL Clause
Use this procedure if your platform accepts the EXTERNAL clause to reference objects linked into your RTS.
To include external compiled forms in the RTS
1. Build and compile the form in VIFRED.
When you compile a form in VIFRED, you are prompted for the name of the file, and VIFRED then creates the specified file in your directory, describing the form in C.
2. Compile the C file into object code:
% cc -c formfile.c
3. Link the compiled form(s) into your RTS by modifying the cob command line to include the object 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 for Platforms that Do Not Accept the EXTERNAL Clause
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 steps force the external object to be loaded into your RTS and allow access to it through your ESQL/COBOL program.
To include external compiled forms in the RTS
1. Build and compile the form in VIFRED.
When you compile a form in VIFRED, you are prompted for the name of the file, and VIFRED then creates the specified file in your directory, describing the form in C.
2. Compile the C file into object code:
% cc -c formfile.c
3. Write a small embedded SQL/C procedure that just references the form and initializes it 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.
Example: addform statement usage
EXEC SQL BEGIN DECLARE SECTION;
  extern int *form1;
  extern int *form2;
EXEC SQL END DECLARE SECTION;
 add_form1()
{
EXEC FRS ADDFORM :form1;
}
add_form2()
{
EXEC FRS ADDFORM :form2;
}
4. Build the object code for the initialization of the compiled forms:
% esqlc filename.sc
% cc -c filename.c
where filename.sc is the name of the file containing the procedure written in Step 3.
5. 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 the object file resulting from Step 4, containing the initialization references to the forms form1 and form2.
6. 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:
EXEC FRS ADDFORM :form1 END-EXEC.
becomes:
CALL "add_form1".
7. To illustrate this procedure, assume you have compiled two forms in VIFRED, empform and deptform, and need to access them from your embedded SQL/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
8. Now create an embedded SQL/C file, for example, addforms.sc, that includes a procedure (or two) that initializes each one using the addform statement:
EXEC SQL BEGIN DECLARE SECTION;
extern int *empform;
extern int *deptform;
 
EXEC SQL END DECLARE SECTION;
 
add_empform()
{
    EXEC FRS ADDFORM :empform;
add_deptform()
{
    EXEC FRS ADDFORM :deptform;
   }
9. Now build the object code for the initialization of these 2 compiled forms:
esqlc addforms.sc
cc -c addforms.c
10. 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 \
...
11. Finally, be sure to replace the appropriate addform statements in your source code with COBOL CALL statements.
You can store all your compiled forms in an archive library so that the constant modification of a link script will not be required. The sample programs near the end of this section were built using such a method that included a single file, addforms.sc, and an archive library, compforms.a, that included all the compiled forms referenced in the sample programs.
If, at a later time you are able to directly reference EXTERNAL data items from your COBOL source code then the intermediate step of creating an embedded SQL/C ADDFORM procedure can be skipped, and your compiled forms declared as EXTERNAL PIC S9(9) COMP-5 data-items in your embedded SQL/COBOL source code:
01 empform IS EXTERNAL PIC S9(9) USAGE COMP-5.
...
EXEC FRS ADDFORM :empform END-EXEC.
The external object code for each form must still be linked into the RTS but there is no need to write an embedded SQL/C intermediate file, or call an external C procedure to initialize the compiled form for you.
Last modified date: 12/14/2023