19.2.4 Steps to Create 3GL Built-In Functions on Windows/Linux/IBM i
1. Design the Built-In Function by giving the Built-In Function program a name according to the 19.2.3 Naming Conventions for 3GL BIFs on Windows/Linux.
2. Complete a Built-In Function definition form. You can print the example supplied in 19.4 Built-In Function Sample Form or one that you have designed yourself. Refer to an example of a 3GL BIF definition, such as 19.2.5 Example - A Simple Averaging Function, to understand the composition of the BIF definition.
Note: This step is not compulsory but it is recommended, especially if you are creating your first Built-In Function. It is meant as an aid to translating your Built-In Function design into the necessary data.
3. Enter the relevant information into the Built-In Function definition files.
Note: The next two steps must be performed. If the Built-In Function is not described in these files then it will not be recognized by LANSA. If this data is incorrect, then the Built-In Function will not work as expected.
4. Create Definitions in LX_F47 and LX_F48
There are two available methods for creating Definitions in LX_F47 and LX_F48.
Method 1: Define the BIF on IBM i and port to Windows
a. Define your Built-In Function into the IBM i based table DC@F47 as described in the 19.1 Create your own 3GL Built-In Functions on IBM i for RDML Functions.
b. Define your Built-In Function's arguments and return values into the IBM i based table DC@F48 as described in the Examples in 19.1 Create your own 3GL Built-In Functions on IBM i for RDML Functions.
c. Optionally, design, code and test an IBM i based version of your Built-In Function. The LANSA Built-In Function facility is designed to be a generic interface between LANSA applications and multiple platforms.
Note: If you need to supply Built-In Functions that will eventually be required on multiple platforms, you may consider producing fatal error "stubs" for your Built-In Function(s) on all supported platforms. This means that if your Built-In Function is accidentally invoked on a non-supported platform (e.g. the IBM i) then a neat "fatal error" explaining the situation will result, rather than a more complex problem involving compile and/or run time linkage problems.
d. Export the definition of your Built-In Function from the IBM i Repository using the standard LANSA REQUEST(PCMAINT) facility.
e. Import the definition of your Built-In Function into each Visual LANSA system that will need to use it. To do this, use the standard Visual LANSA import facilities from CD or shared folder. This facility will update SQL tables LX_F47 and LX_F48 with details of the Built-In Functions exported from the IBM i in step 4.
Method 2: Define the BIF via SQL directly in Windows
This is an alternative method, which can be used where the IBM i is non-existent or if you are familiar with inserting and updating your database on the Windows/Linux platform using SQL statements. This method requires you to directly enter your definitions into the LX_F47 and LX_F48 files.
Note: Inserting/updating records in the LX_F47 and LX_F48 internal LANSA tables via SQL, if not completed correctly, can potentially cause database corruption. If you require assistance with inserting/updating records in the LX_F47 and LX_F48 internal LANSA files via SQL, you should consult your Database Administrator.
Example of an insert to file LX_F47
INSERT INTO "LX_DTA"."LX_F47" VALUES('UD_AVERAGE',413,'Get the Average','C','U_BIF413','N',2,1)
Example of an insert to file LX_F48
INSERT INTO "LX_DTA"."LX_F48" VALUES('UD_AVERAGE','ARG',1,1,'A','First Value','R','N',7,7,0,0,10,0,'')
5. If you are writing a BIF specifically for Windows or you require 64 bit support on Windows then you may find the LANSA User Defined BIF Wizard an easier method than the remainder of these steps 6 - 9. Instead go to Define Built In Functions with a Visual Studio Wizard It is particularly useful for existing Visual Studio users and when requiring more than one user defined BIF.
6. Create copies of the following files that are installed in your x_win95\x_lansa\source directory. Change the "NNN" portion of the name to the unique identifier assigned to your Built-In Function.
For example, if you were making Built-In Function 445, and working from the C: drive then you might use these commands:
CD \X_WIN95\X_LANSA\SOURCE COPY U_BIFNNN.* U_BIF445.*These are the files that are installed in your x_win95\x_lansa\source directory:
|
U_BIFNNN.C |
A sample/skeleton of a user Built-In C program. |
|
U_BIFNNN.MAK |
A sample/skeleton of a make file required to compile and link your C program with Microsoft Visual C/C++ into a DLL under the Windows Operating System. |
|
U_BIFNNN.DEF |
A sample/skeleton of a module definition file required to link your C program with Microsoft Visual C/C++ into a DLL under the Windows Operating System. |
|
u_bifnnn.unx |
A sample/skeleton of a make file required to compile and link your C program into a shared library under a supported Linux operating system. |
|
U_BIFNNN.ISB |
A sample/skeleton of a module definition file required to link your C program into a service program on IBM i. |
7. Edit each of the copied files using a standard source editor such as E or EPM:
| File | Description Of Changes |
|
.C |
Scan/Replace all "nnn" with "xxx" where xxx is the unique id. Include code appropriate for your requirement. |
|
.MAK |
Only required if compiling with Microsoft Visual C/C++. Replace "nnn" with "xxx" in the BIFNAME line, where xxx is the unique id. |
|
.DEF |
Only required if compiling with Microsoft Visual C/C++. Replace "nnn" with "xxx" where xxx is the unique id. Replace xxxxxxxx in DESCRIPTION with a short description of the Built-In Function |
|
.unx |
(Only if planning to execute this BIF on Linux.) Scan/Replace all "nnn" with "xxx" where xxx is the unique id. |
|
.ISB |
Only required if planning to execute this BIF on IBM i.) Replace "nnn" with "xxx" where xxx is the unique id. Replace xxxxxxxx in the comment area (/* */) with a short description of the Built-In Function |
8. Back up your .C, .MAK, .WMK, .DEF, .unx and .ISB files as soon as possible. This is source code and it needs to be backed up frequently. Accidental loss of source code is a very common problem on unsecured PC systems.
9. Compile your Built-In Function using one of the following examples depending on the platform you are using:
Compile your Built-In Function on Windows