This section contains the following topics:
DB2 does not support the link386 linker that comes with the Micro Focus COBOL compiler. To link DB2 Micro Focus COBOL programs, you must use the ilink linker that is available from IBM compiler products. The cbllink command, used in the script files in this section, calls the ilink linker.
When building applications with the Micro Focus COBOL compiler that contain embedded SQL and DB2 API calls, keep the following points in mind:
set LIB=%DB2PATH%\lib;%LIB%
set COBCPY=%DB2PATH%\include\cobol_mf;%COBCPY%
Calls to all DB2 application programming interfaces must be made using calling convention 8. The DB2 COBOL precompiler automatically inserts a CALL-CONVENTION clause in a SPECIAL-NAMES paragraph. If the SPECIAL-NAMES paragraph does not exist, the DB2 COBOL precompiler creates it, as follows:
Identification Division
Program-ID. "static".
special-names.
call-convention 8 is DB2API.
Also, the precompiler automatically places the symbol DB2API, which is used to identify the calling convention, after the "call" keyword whenever a DB2 API is called. This occurs, for instance, whenever the precompiler generates a DB2 API run-time call from an embedded SQL statement.
If calls to DB2 APIs are made in an application which is not precompiled, you should manually create a SPECIAL-NAMES paragraph in the application, similar to that given above. If you are calling a DB2 API directly, then you will need to manually add the DB2API symbol after the "call" keyword.
The command file bldmfapi, in %DB2PATH%\samples\cobol_mf, contains the commands to build a DB2 API program. The parameter, %1, specifies the name of your source file.
@echo off rem bldmfapi command file (for programs that do not contain embedded SQL) rem Usage: bldmfapi <prog_name> rem Compile the error-checking utility. cobol checkerr.cbl; rem Compile the program. cobol %1.cbl; rem Link the program. cbllink %1.obj checkerr.obj db2api.lib db2gmf32.lib @echo on
| Compile and Link Options for bldmfapi |
|---|
|
The command file contains the following compile option:
|
|
The command file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the sample program client, from the source file client.cbl , enter:
bldmfapi client
The result is an executable file, client.exe. You can run the executable file against the sample database by entering the executable name (without the extension):
client
The command file bldmfcob, in %DB2PATH%\samples\cobol_mf, contains the commands to build an embedded SQL program.
The first parameter, %1, specifies the name of your source file. The second parameter, %2, specifies the name of the database to which you want to connect. The third parameter, %3, specifies the user ID for the database, and parameter %4, specifies the password. Only the first parameter, the source file name, is required. Database name, user ID, and password are optional. If no database name is supplied, the program uses the default sample database.
@echo off rem bldmfcob.cmd file rem Builds an embedded SQL program using the Micro Focus COBOL compiler. rem Usage: bldmfcob <prog_name> [ <db_name> [ < userid> <password> ]] rem Connect to a database. if "%1" == "" goto error if "%2" == "" goto case1 if "%3" == "" goto case2 if "%4" == "" goto error goto case3 :case1 db2 connect to sample goto continue :case2 db2 connect to %2 goto continue :case3 db2 connect to %2 user %3 using %4 goto continue :continue rem Precompile the program. If target mfcob is rem not specified target mfcob16 is assumed. db2 prep %1.sqb bindfile target mfcob rem Bind the program to the database. db2 bind %1.bnd rem Disconnect from the database. db2 connect reset rem Compile the error-checking utility. cobol checkerr.cbl; rem Compile the program. cobol %1.cbl; rem Link the program. cbllink %1.obj checkerr.obj db2api.lib db2gmf32.lib goto exit :error echo Usage: bldmfcob <prog_name> [ <db_name> [ < userid> <password> ]] :exit @echo on
| Compile and Link Options for bldmfcob |
|---|
|
The command file contains the following compile option:
|
|
The command file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the sample program updat, from the source file updat.sqb , enter:
bldmfcob updat
The result is an executable file, updat.exe. You can run the executable file against the sample database by entering the executable name (without the extension):
updat
The command file bldmfcbs, in %DB2PATH%\samples\cobol_mf, contains the commands to build an embedded SQL stored procedure. The command file compiles the stored procedure into a DLL on the server.
The first parameter, %1, specifies the name of your source file. The second parameter, %2, specifies the name of the database to which you want to connect. The third parameter, %3, specifies the user ID for the database, and parameter %4, specifies the password. Only the first parameter, the source file name, is required. Database name, user ID, and password are optional. If no database name is supplied, the program uses the default sample database. The command file uses the source file name, %1, for the DLL name.
@echo off rem bldmfcbs.cmd file rem Builds an embedded SQL stored procedure using the Micro Focus COBOL compiler. rem Usage: bldmfcbs <prog_name> [ <db_name> [ < userid> <password> ]] rem Connect to a database. if "%1" == "" goto error if "%2" == "" goto case1 if "%3" == "" goto case2 if "%4" == "" goto error goto case3 :case1 db2 connect to sample goto continue :case2 db2 connect to %2 goto continue :case3 db2 connect to %2 user %3 using %4 goto continue :continue rem Precompile the program. If target mfcob is rem not specified target mfcob16 is assumed. db2 prep %1.sqb bindfile target mfcob rem Bind the program to the database. db2 bind %1.bnd rem Disconnect from the database. db2 connect reset rem Compile the stored procedure. cobol %1.cbl; rem Link the stored procedure and create a shared library. cbllink /d %1.obj db2api.lib db2gmf32.lib rem Copy stored procedure to the %DB2PATH%\function directory. rem Substitute the path where DB2 is installed for %DB2PATH%. copy %1.dll %DB2PATH%\function goto exit :error echo Usage: bldmfcbs <prog_name> [ <db_name> [ < userid> <password> ]] :exit @echo on
| Compile and Link Options for bldmfcbs |
|---|
|
The command file contains the following compile option:
|
|
The command file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the stored procedure outsrv from the source file outsrv.sqb , enter:
bldmfcbs outsrv
The linker uses a default entry point unspecified by the user. The /d option is used to create the .dll file in order to build the stored procedure. The command file copies the stored procedure DLL, outsrv.dll, on the server in the path %DB2PATH%\function. For DB2DARI parameter style stored procedures where the invoked procedure matches the name of the stored procedure DLL, this location indicates that the stored procedure is fenced. If you want this type of stored procedure to be unfenced, you must move the DLL to the %DB2PATH%\function\unfenced directory. For all other types of DB2 stored procedures, you indicate whether it is fenced or not fenced with the CREATE FUNCTION statement in the calling program. For a full discussion on creating and using the different types of DB2 stored procedures, please see the "Stored Procedures" chapter in the Application Development Guide.
| Note: | An unfenced stored procedure runs in the same address space as the database manager and results in increased performance when compared to a fenced stored procedure, which runs in an address space isolated from the database manager. With unfenced stored procedures there is a danger that user code could accidentally or maliciously damage the database control structures. Therefore, you should only run unfenced stored procedures when you need to maximize the performance benefits. Ensure these programs are thoroughly tested before running them as unfenced. Refer to the Application Development Guide for more information. |
Once you build the stored procedure outsrv, you can build outcli that calls the stored procedure. You can build outcli using the bldmfcob.cmd file. Refer to "Embedded SQL Applications" for details.
To run the stored procedure, enter:
outcli
The client application passes a variable to the server program outsrv, which gives it a value and then returns the variable to the client application.