Application Building Guide

FORTRAN 77

This section contains the following topics:

• Using the Compiler

• DB2 API Applications

• Embedded SQL Applications

• Embedded SQL Stored Procedures

Using the Compiler

If you develop applications that contain embedded SQL and DB2 API calls, and you are using the WATCOM FORTRAN 77 compiler, keep the following points in mind:

• The WATCOM compiler treats lines with a D or d in column 1 as conditional lines. You can either compile these lines for debugging or treat them as comments.

  The precompiler always treats lines with a D or d in column one as comments.

• In the Fortran examples that call DB2 APIs, the Administrative API Reference uses %val() to show parameters passed by value, and %ref() to show parameters passed by reference. Remove these modifiers when you code applications for WATCOM FORTRAN 77. They are not required.

  The DB2 include files for WATCOM FORTRAN 77 use the compiler's pragma mechanism to indicate which parameters should be passed by reference and which by value. As long as your application includes the appropriate file, parameters are passed correctly.

• The precompiler allows only digits, blanks, and tab characters within columns 1-5 on continuation lines.

• .sqf source files do not support Hollerith constants.

DB2 API Applications

The command file bldapi, in %DB2PATH%\samples\fortran, contains the commands to build a DB2 API program. The parameter, %1, specifies the name of your source file.

@echo off
rem  bldapi command file
rem  Builds a FORTRAN DB2 API program
rem  Usage: bldapi <prog_name>
 
if "%1" == "" goto error
 
rem Compile the util.for error checking utility.  
wfc386 /debug /d2 /noref util.for
rem Compile the program.                                   
wfc386 /debug /d2 /noref %1.for                            
 
rem Link the program.                                      
wlink debug all sys os2v2 file %1.obj file util.obj library db2api.lib option stack=64000
 
goto exit
 
:error
echo Usage: bldapi prog_name
 
:exit
@echo on

To build the sample program, client, from the source file, client.f, enter:

   bldapi client

The result is an executable file, client. You can run the executable file against the SAMPLE database by entering the executable name:

   client

Embedded SQL Applications

The command file, bldfor, in %DB2PATH%\samples\fortran, 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. 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 bldfor command file
rem Builds a FORTRAN program that contains embedded SQL
rem Usage: bldfor <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.sqf bindfile
 
rem Compile the util.for error-checking utility.
wfc386 /debug /d2 /noref util.for
 
rem Compile the program.
wfc386 /debug /d2 /noref %1.for
 
rem Link the program.
wlink debug all sys os2v2 file %1.obj file util.obj library db2api.lib 
    option stack=64000
 
rem Bind the program to the database.
db2 bind %1.bnd
 
rem Disconnect from the database.
db2 connect reset
 
goto exit
 
:error
echo Usage: bldfor <prog_name> [ <db_name> [ < userid> <password> ]]
 
:exit
@echo on

To build the sample program, updat, from the source file, updat.sqf, enter:

 
   bldfor updat

The result is an executable file, updat. You can run the executable file against the sample database by entering the executable name:

   updat

Embedded SQL Stored Procedures

When building FORTRAN stored procedures on OS/2, you require the following statement in your stored procedure:

   c$pragma aux <stored_proc_name> parm caller[]  (data_reference, data_reference, \
   c                                   data_reference, data_reference)

caller [] allows the parameters to be put on a stack instead of in registers. This complies with the calling convention that DB2 APIs use.

The command file bldforsr, in %DB2PATH%\samples\fortran, contains the commands to build a 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. 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 bldforsr command file
rem Builds a FORTRAN embedded SQL stored procedure
rem Usage: bldforsr <stored_proc_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.sqf bindfile
 
rem Compile the program.
wfc386 /noref %1.for
 
rem Link the program.
wlink sys os2v2 dll export %1 file %1.obj library db2api.lib 
    library os2386.lib option stack=64000
 
rem Bind the program to the database.
db2 bind %1.bnd
 
rem Disconnect from the database.
db2 connect reset
 
rem Copy the dynamic link library to the function subdirectory.
rem Note: Substitute the DB2 instance directory for %db2path%
copy %1.dll %db2path%\function
 
goto exit
 
:error
echo Usage: bldforsr <prog_name> [ <db_name> [ < userid> <password> ]]
 
:exit
@echo on

To build the outsrv.sqf stored procedure, enter:

 
   bldforsr outsrv

Note:

The command file does not use a module definition file. Instead, the linker accepts an entry point as an argument for the export option. In this case, the entry point for the stored procedure is the same name as the source file. This may not be the case for other stored procedures you build. If it is different, modify the command file to accept another argument for the entry point, and modify the link step to have the export option accept the entry point argument (instead of %1, as it does now). For example, if the entry point was the fifth argument, you would write the link step as: wlink sys os2v2 dll export %5 file %1.obj library db2api.lib library os2386.lib option stack=64000

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 the client application, outcli, that calls the stored procedure. You can build outcli using the command file bldfor. Refer to "Embedded SQL Applications" for details.

To access the stored procedure, run the sample client application by entering:

   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.

[ DB2 List of Books | Search the DB2 Books ]