Copyright: FFIGEN Utility Help  © Oracle Corporation 1997


yesyesyesyesFFIGEN Helpffigenyesyes14/03/97


Table of Contents
FFIGEN Help - Table of Contents

About The FFIGEN utility

Installation and Upgrading

The Startup Screen

FFIGEN Main Screen

The Define-A-Function Wizard

The Generate Wizard

Post Generation Steps

Preferences

The FFIGEN Data Model

Advanced Features


Help file produced by  HELLLP! v2.7d , a product of Guy Software, on 14/03/97 for Unregistered User.

The above table of contents will be automatically completed and will also provide an excellent cross-reference for context strings and topic titles.  You may leave it as your main table of contents for your help file, or you may create your own and cause it to be displayed instead by using the I button on the toolbar.  This page will not be displayed as a topic.  It is given a context string of _._ , but this is not presented for jump selection.

HINT:  If you do not wish some of your topics to appear in the table of contents as displayed to your users (you may want them ONLY as PopUps), move the lines with their titles and contexts to below this point.  If you do this remember to move the whole line, not part.  As an alternative, you may wish to set up your own table of contents, see Help under The Structure of a Help File.

  Do not delete any codes in the area above the Table of Contents title, they are used internally by HELLLP!

Wizard Preferences

Data type Preferences

Generate Preferences

Command Line Options:

Limitations in ORA_FFI

Wizard Preferences

Data Types

Generate Options

Use Hardcoded Location

Include Standard Error Routines

Code will only be called from Forms

Ensure Library is Loaded on Every Call

Include Pre-Load Procedure

Build PLL File

The FFIGEN_LIBRARY block

The FFIGEN_FUNCTION block

The FFIGEN_FUNCTIONARGS block

Generate

Save

Exit

Cut, Copy & PasteDefine-a-Function Wizard

Generate Wizard

Test Utility

Preferences

Help

Information about the code used in FFIGEN


About The FFIGEN Utility

About FFIGEN Version 2.0

FFIGEN is a PL/SQL code generator which was developed to make the job of interfacing with 3gl Shared Libraries (Windows .DLL files) simpler.

Developer/2000 provides a PL/SQL package called ORA_FFI, the Oracle Foreign Function Interface.  This PL/SQL package contains functions which handle the definition of the 3gl  PL/SQL interface and load the required shared library to make it accessible.

FFiGEN automates this task for you by allowing you to enter the definition of the 3gl function, and then generating the PL/SQL that will access it.  FFIGEN will prevent many of the common errors that can occur when programmers attempt to define an ORA_FFI interface from scratch, never the less you will find it easier to understand what FFIGEN is doing for you if you have already read up on the ORA_FFI package.

The ORA_FFI package is defined in the Procedure Builder Developer's Guide.

FFIGEN provides you with the following features:

•	Wizard driven interface to help define your 3gl function and to generate the PL/SQL Code

•	Pre-defined Error Handling for your PL/SQL Code

•	Built-in Testing utility

•	User Definable data types

•	Comes supplied with definitions for most common Windows data types as well as basic C datatypes

•	Export utility for definitions.

•	Reporting facility.


Installation and Upgrading

Installation and Upgrading

When you run FFIGEN for the first time, it will take you through the process of installing the Oracle Tables that it requires.

You should have resource privilege on your default tablespace in order to create the tables and sequences that FFIGEN requires.  If your DBA has stuck to the default segment sizes for your user then the FFIGEN installation will require about 140k of database space.

If required you can extract the SQL script that is used to create the FFIGEN objects and change the storage definitions for the objects.  See Command Line Options

If you have used the previous version of FFIGEN from the same schema as the new version FFIGEN will upgrade your definitions so that it can use them.  This upgrade process is non-destructive and you can continue to use the old version of FFIGEN concurrently.  You can upgrade the contents of the FFIGEN Version 1.0 tables at any time by using the Tools >> Maintenance >> Upgrade V1 Data menu option.  This Menu option is only enabled if the FFIGEN Version 1.0 tables are installed.

Note:  This upgrade process does not check for duplicate definitions, it will just create new definitions from the Version 1.0 Data, so you might have to delete unwanted duplicates.

There is no reverse engineering facility from FFIGEN Version 2.0 to Version 1.0.  However, the PL/SQL code generated by FFIGEN Version 2.0 will work with Developer/2000 release 1.n.  You will have to move the generated PL/SQL Text File (.PLD)  back to the required version of Developer/2000.

The FFIGEN base tables are not designed for access by multiple users, there is no concept of Definition ownership or access control.

See the FFIGEN data Model.


The Define-A-Function Wizard

The Define-A-Function Wizard

The Define-A-Function Wizard will take you through the basic steps required to create a 3gl function definition that FFIGEN can then use to generate PL/SQL code from.

The Wizard will take you through the following steps:

1	Select the 3gl library file that the function is contained in.  On Windows this will be a .DLL or .EXE file.  On UNIX ports the extension for a sharable library varies, but is usually .so

2	Enter the name of the function that you want to access.  Note that this is case sensitive.

3	Define the data type that the function returns.  A list is provided for you to select from, and there is a checkbox to indicate that the value returned is a pointer.  You can customize the list of data types that appear using the Preferences dialog

4	Define the Calling standard:  The calling standard defines how the 3gl function evaluates and cleans up its stack.  If you choose the incorrect option here you will probably get a GPF when you run the generated code, so check the calling standard with the supplier of the Library.  As a guideline, most 32 bit Windows Functions and UNIX functions will use the C standard, and 16 bit Windows functions the PASCAL standard.  Be aware though, that may Windows API functions still use the PASCAL standard even if they are 32 bit.

5	Finally you need to define the name and data types of all of the arguments to the function.  The names of the arguments are arbitrary and not case sensitive.


The Generate Wizard

The Generate Wizard

The Generate Wizard will take you through the simple steps required to build your PL/SQL code.  The Generate wizard is the only automatic way that you can combine definitions for several different 3gl libraries into a single PL/SQL library.

The Wizard will take you through the following steps:

1	The Wizard provides you with a list of all the libraries that you have defined.  You just need to check those that you require.

2	Specify the name for the PLD and PLL files.  The FFIGEN utility builds a Text version of the library which is the .PLD file.  And depending on your Generate Options may then compile that PLD into a PLL file.


Startup Screen

The Startup Screen

When FFIGEN starts up it will display an Options Screen which will allow you to choose from one of three options:

Edit the definitions Manually:

Selecting this option will take you into the main FFIGEN screen where you are in a conventional Form with Three blocks.  Here you can view and alter your definitions, and have access to the various wizards and tools.

Use the Define-a-Function Wizard:

For First time users the Define-a-Function Wizard will take you through the process of defining a function.

Use the Generate Wizard:

If you have already defined your 3gl functions then you can use the Generate Wizard to take you through the process of building your PL/SQL code from them

The startup screen also has a checkbox which you can de-select to hide this screen in future.  You can cause the screen to display again by using the Preferences Dialog


Preferences

Preferences

The preferences dialog allows you to alter the settings that FFIGEN uses:

Three tabs are presented:

Wizards

Data Types

Generate Options


FFIGEN Data Model

FFIGEN Data Model

This diagram illustrates the relationships between the tables used by the FFIGEN utility.  When these tables are installed the data dictionary is fully populated with constraints and comments relating to all of the objects.


Wizard Preferences
Wizard Preferences: Allows you to switch the start screen of each of the wizards on and off.


Data type Preferences
Data type Preferences: Allows you to customize the list of datatypes that are presented when defining the return types from, and data types of Functions


Generate Preferences
Generate Preferences: Allows you to change the settings used by FFIGEN when it generates PL/SQL code.  This includes inserting error handling, defining initialization style etc.


Command Line Options:

Command Line Options:

FFIGEN is designed to run with the USESDI=YES parameter so that the Form runs without an MDI window.

The other command line options that can be used are:

DUMP_SQL = YES|NO	If this parameter is set to YES then FFIGEN will prompt you for the 	name of a file, and will then dump out a SQL script containing all the DML and DDL used to build the utility.

FORCE_REBUILD = YES|NO	Forces FFIGEN to drop and rebuild it's base tables when it starts up.  Only use this option when you don't mind loosing your existing definitions.

EXPORT_PRESERVE_DATATYPES = YES|NO	When you use the Export Facility to write your definitions to an .SQL file, setting this option to YES prevents the utility from resolving the datatypes used to their base types.  By default, the export converts to base types, as we can guarentee that any other FFIGEN user would have these datatypes

FFIGEN_DEBUG = SQL|RESOURCES|NO	Switches on internal debugging for the utility.

The FFIGEN_DEBUG = SQL option causes all statements submitted to the database using the FORMS_DDL built-in to be logged to a file called FFIGEN.TRC in the working directory.  This is of most use when trying to debug installation problems when FFIGEN is trying to build it's base tables

The FFIGEN_DEBUG = RESOURCES option switches on debugging in the D2k_RES package and should only be used if you get a RESOURCE NOT FOUND error in the utility.


Advanced Features

Advanced Features and Further Information

The following features of FFIGEN may be of interest:

Command Line Options for FFIGEN

Limitations in ORA_FFI

Information on the code used in FFIGEN


Limitations in ORA_FFI

Limitations in ORA_FFI & FFIGEN

The major limitation with the Oracle Foreign Function interface is that it can only handle "Simple" C datatypes.  There is not direct way of passing Structures and arrays from PL/SQL to the 3gl function.

As a result there is a limited list of possible data types available to you.  FFIGEN does, however, allow you to define synonyms for the common C data types that are more suitable for the functions that you are defining for.

If you have a 3gl function that takes a structure as an argument then you will have to build a "Wrapper" function which takes simple arguments, and creates the structure or array to pass through to the problem function in turn.

FFIGEN Generates PL/SQL code from your C function definition.  This imposes a PL/SQL limitation on object nameing allowed.  PL/SQL Program units and variables can only be up to 30 characters in length.  There are also restrictions in the characters that can be used in Program Units and Variable names.

FFIGEN reserves 3 characters for it's own use, so the maximium length of say a function name is 27 characters.

This will only cause a problem in a few cases.  Should you have a function name that is greater than 27 characters in length generate your FFI code with the truncated name,  then simply correct the name in the relevant ORA_FFI.REGISTER_FUNCTION() call to the full length.

Likewise should the function name contain illegal characters then just alter the above line, post generation.

This is the only change required.

The names of arguments to functions are arbitrary and not used when talking to the C function, so you can safely keep these below 27 characters without harming the functionality.


Wizard Preferences

Wizard Preferences

This screen presents three check boxes which you can use to switch on or off the front screen for each of the Wizards.


Data Types

Data Types

The Data types screen allows you to define the list if Data  types that are displayed in the Poplists throughout the FFIGEN application.

Data types are classified in a Simple Master Detail fashion.  Data Types are grouped into Sets;  the Base C Data Type and Windows Data Type Sets are pre defined for you.  Each Set contains one or more data type definitions, each of which has to map back to a Base C Data Type.

You can choose for one or more Sets of data types to be included in your poplists, by simply checking the Display Set in List option.  Additionally you can alter the contents of any set (apart from the base set)

When you define a new data type you have to supply three pieces of information

1) 	The name you want to have for this data type.

2) 	The mapping back to the base c data type (done via a pop-list)

3) 	If the data type is always a pointer or not.  Some common Windows data types are defined as pointers for instance LPSTR which is equivalent to char *.  In order to ensure that the pointer flag is always set when this data type is used you can check the Type is Pointer option

For additional information, When you select the base data type, FFIGEN shows you what PL/SQL data type will be mapped to.


Generate Options

Generate Options

FFIGEN provides you with the ability to tailor the code that it generates.  Click on the options below for an explanation of each:


Use Hardcoded Location
Checking this option will hard-code the location of the library into the ORA_FFI.LOAD_LIBRARY() call.  It is worth setting this option whilst you are testing the interface, but for production distribution you are unlikely to put the library in exactly the same location on every machine, so you would unset this option and ensure that the library was on the path.


Include Standard Error Routines
Checking this option will make FFIGEN insert it's standard error handler into your code.  This error handler uses theTOOL_ERR package to determine what caused any errors. (see the Procedure Builder Developer's Guide for more information about TOOL_ERR).  It is strongly recommended that you use this option.

If this option is not set then FFIGEN will insert a stub exception handler which you can customize yourself.


Code will only be called from Forms
If this option is checked then FFIGEN will use the Forms Message() built-in in the error handler that it generates.  If you are going to use the code from Graphics and Reports, uncheck this option so that the PLL will compile.

If this option is  not selected, then error codes and messages will be written to package header variables, where the programmer can pick them up.


Ensure Library is Loaded on Every Call
Check that the 3gl Library is loaded into memory every time the function is accessed.  If this option is not selected then the library will just be loaded when the PL/SQL package is first instanciated.  Testing for the library every time will slow down the function call, but may be required when the forms calling the functions are being continually loaded and unloaded, and there is a danger that the library may be unloaded by another process.


Include Pre-Load Procedure
With this option set FFIGEN will build an extra procedure in the package specification to Pre-Load the library into memory.  This will then reduce the time taken to call the first function, if the pre-load was called when the application started.


Build PLL File
If checked, FFIGEN will call the Forms Compiler module to build a .PLL file from the generated .PLD


Post Generation Steps:

Post Generation Steps:

You should open (or convert and open) your FFIGEN generated code in the Developer/2000 tool that you are using and Compile All.  Forms Programmers will often find it useful to temporarily drag the generated Package Headers and Bodies into Local Program Units within their Form to make debugging of the code simpler.

FFIGEN will build literal PL/SQL wrappers for the 3gl functions that you have defined.  You may want to alter the generated code manually to hide some of the arguments from your programmers who will be using the package.

An example of this would be in many of the Windows API functions which take a char * argument for a buffer and an int parameter describing how long that buffer is.  As you know how big your varachar2 variable is that will make up the buffer you may want to remove the int buffer length argument from the external PL/SQL definition and hard code it  in the package body.


FFIGEN Main Screen

The Main Screen

The main screen of the FFIGEN utility is made up of a conventional Master - Detail - Detail structure of blocks.  You have areas on the screen to define the 3gl Library being called, the functions within it, and finally the arguments to that function Click on an area below to see what it is:

The Toolbar:

The toolbar gives you access to commonly used FFIGEN functions, such as the invoking of the Wizards, and the preference screen.

Right Mouse Button Menu:

Is available on the main screen and provides more shortcuts for both edit commands, testing and generation of the current package:

Comments:

Both the Library block and Function block allow you to associate comments with a function or package.  Anything you enter here will be inserted into the generated PLD file as comments, so can be used for Usage and Versioning information.

Reporting on the FFIGEN definitions:

A report (ffigen.rdf) has been written for you, which pulls out basic information about the current library definition.  This report can be run off of the File Menu.

If you want to write more complex reports then the FFIGEN Data Model is provided, and objects within the schema are fully documented within the data dictionary.


The FFIGEN_LIBRARY block
The FFIGEN_LIBRARY block, contains the definition for a particular 3gl library


The FFIGEN_FUNCTION block
The FFIGEN_FUNCTION block defines each of the functions for the current library.


The FFIGEN_FUNCTIONARGS block
The FFIGEN_FUNCTIONARGS block defines each of the arguments for the current function.


Generate
Generate: Clicking here on the toolbar will generate a definition for the current library


Save
Save: Clicking here will save any changes you have made


Exit
Exit: Clicking here will exit the FFIGEN application


Cut, Copy & Paste
Cut, Copy & Paste: The standard editing shortcuts


Define-a-Function Wizard
Define-a-Function Wizard: Call up the wizard to simplify the job of creating an initial definition for a library and function.


Generate Wizard
Generate Wizard: call up  the Generate Wizard to simplify the job of generating your PL/SQL code, and to allow you to generate code for several libraries at once.


Test Utility
Test Utility:  The Test utility checks that the file specified in the library definition can be found, and that all the specified functions exist in it.


Preferences
Preferences: Show the preferences screen to allow you to change generate options and data types.


Help
Help: Call up the Help system


Information about the code used in FFIGEN:
Information about the code used in FFIGEN

Information about the code used in FFIGEN:

As you will see if you examine the source code of the FFIGEN utility, FFIGEN uses a number of program units in the PL/SQL library d2kcomn.pll.  An example of this is the d2k_res package which FFIGEN uses extensively to read text strings from the resource file ffigenus.res.

See the various packages in the library for detailed information on their function.