This section includes the following topics:
If you develop applications that contain embedded SQL and DB2 API calls, and you are using the Micro Focus compiler, 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 74. 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 74 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 batch file bldapicb, in %DB2PATH%\samples\cobol_mf, contains the commands to build a sample COBOL program. The parameter, %1, specifies the name of your source file.
@echo off rem bldapicb.bat file rem Build a DB2 API program using the Micro Focus COBOL compiler. rem Usage: bldapicb <prog_name> rem Compile the error-checking utility. cobol checkerr.cbl; rem Compile the program. cobol %1.cbl; rem Link the program. cbllink -l %1.obj checkerr.obj db2api.lib goto exit :error echo Usage: bldapicb <prog_name> :exit @echo on
| Compile and Link Options for bldapicb |
|---|
|
The batch file contains the following compile option:
|
|
The batch 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:
bldapicb 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 batch 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 %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.bat file rem Build a sample Cobol 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. 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 -l %1.obj checkerr.obj db2api.lib goto exit :error echo Usage: bldmfcob <prog_name> [ <db_name> [ < userid> <password> ]] :exit @echo on
| Compile and Link Options for bldmfcob |
|---|
|
The batch file contains the following compile option:
|
|
The batch 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 batch file bldmfcbs, in %DB2PATH%\samples\cobol_mf, contains the commands to build an embedded SQL stored procedure. The batch 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 %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 batch file uses the source file name, %1, for the DLL name.
@echo off rem bldmfcbs.bat file rem Builds a COBOL 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. 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 /case; rem Link the stored procedure and create a shared library. cbllink /d %1.obj db2api.lib rem Copy the stored procedure to the %DB2PATH%\function directory. 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 batch file contains the following compile options:
|
|
The batch file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the stored procedure, 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 batch file copies the stored procedure DLL, outsrv.dll, to the server in the path %DB2PATH%\function. For DB2DARI parameter style stored procedures where the invoked procedure matches the stored procedure DLL name, this location indicates that the stored procedure is fenced. If you want this type of stored procedure to be unfenced, you must move it 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.bat 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.