Using the API in the Microsoft Windows Environment

In this section: Creating a C/C++ Program Creating a Visual Basic Program How to: Build and Execute an C/C++ Program Build and Execute a Visual Basic Program

The API requires that application programs contain specific data structures and employ specific numeric constants in certain method calls. All API method calls are implemented in Microsoft and expect their parameters to be passed to them using standard call-by-reference (pointers to variables) conventions.

EDAAPI.DLL is a fully WIN32 compliant 32-bit DLL that operates in Windows 9x, Windows ME, Windows NT^®, Windows^® 2000, Windows XP, and Windows 2003.

Working samples are provided in various languages. The first step in writing an API application should be to confirm that the desired sample language properly compiles, links, and runs to ensure there is a properly working environment.

The C, C++, and VB samples have been tested with Visual Studio 6 and Visual Studio .NET 2003, however, the step by step instructions are for Visual Studio 6. The Visual Studio .NET 2003 instructions are similar.

Creating a C/C++ Program

When you compile an API application written in Microsoft Visual C/C++^® language, you should include the EDA.H header file in those sources referencing API method calls. EDA.H contains symbolic constants and method prototypes. EDASYS.H, which contains Windows-specific declarations, is included by EDA.H.

See your compiler's manual for further information on calling C/C++ subroutines and passing parameters by reference.

To create an application using the API, compile the application in the usual manner and include the stub library, EDAAPI.LIB, in your link command. Linking your application with this stub library will insert the appropriate reference to the API DLL, EDAAPI.DLL. When you execute your application, the API requires that EDAAPI.DLL be available to load from the DLL search path. As the API operates, it will look for other DLLs for communications and other purposes.

The installation media installs sample client applications (edaapp.c and edaapp.cpp) located in, depending if the client or server software is installed:

drive:\ibi\client71\home\etc

or

drive:\ibi\srv71\home\etc

The sample application is very similar to the DOS rdaapp program that is used to verify a server as operational, to test the connection to your server, and to run simple commands. If this step is successful, a customer-written application can then be built and tested.

Procedure: How to Build and Execute an C/C++ Program

1. Set the Microsoft System User Environment Path Variable. Add one of the following the path locations to edaapi.dll:

   drive:\ibi\client71\home\bin

   drive:\ibi\srv71\home\bin

2. Create your own Microsoft C/C++ application or use the sample edaapp.c.

3. Compile and link the application. Perform the following steps:
   1. Select Tools and Options from the Microsoft C/C++ toolbar.
   2. Select the Directories tab from the Options window.
   3. Select Include Files from Show Directories. Add one of the following the path locations for eda.h:

   drive:\ibi\client71\home\bin

   drive:\ibi\srv71\home\bin

   4. Select Library Files from Show Directories. Add one of the following the path locations for edaapi.lib:

   drive:\ibi\client71\home\bin

   drive:\ibi\srv71\home\bin

   5. Select Build and Compile from the Microsoft C/C++ toolbar. Compile the application.
   6. Select Project and Settings from the Microsoft C/C++ toolbar.
   7. Select the Link tab from Project Settings. Add edaapi.lib to the existing Object/Library module list. Click OK.

4. Build the application in the usual C/C++ manner to obtain an executable file. Select Build and Build *.exe from the Microsoft Visual C/C++ toolbar, where * is the name of the application.

5. At run time, the edaapi.dll file needs to be in a directory on the PATH variable. The default location of this directory is ibi\client71\home\bin or drive:\ibi\srv71\home\bin. The adjustment to the PATH variable may be made to the machine/user profile or by creating a .bat file to wrapper the executable. Alternatively, the Microsoft compilation environment supports a void declaration of "__declspec(dllexport) " to find the required dll dynamically.

6. To run the program, double-click *.exe (or the .bat file if you have chosen to create one) which is located in the subdirectory Debug (unless the default path location was changed in step 3g).

Creating a Visual Basic Program

When you are writing an API application in Microsoft Visual Basic, you must include the edaglob.bas header file, which contains symbolic constants and method prototypes.

The system user environment variables must also be set to establish the path location of all required modules. For example, when you execute your application, the API requires that EDAAPI.DLL be available to the DLL search path.

The installation process installs a zip file (edaappvb.zip) containing a sample client application and associated files (edaapp.bas, edaapp.frm, and edaapp.vbp) located in one of the following directories:

drive:\ibi\client71\home\etc

drive:\ibi\srv71\home\etc

The sample application is similar to the Test Tool program that is used to verify a server as operational, to test the connection to your server, and to run simple commands. If this step is successful, a customer-written application may now be built and tested.

Procedure: How to Build and Execute a Visual Basic Program

1. Unzip the edaappvb.zip file into an empty directory.

2. Create your own Microsoft Visual Basic application or use the sample program edavb.vbp. The module edaglob.bas must explicitly be included as part of the project or copied into the same directory from the EDAHOME etc directory. Perform the following steps:
   1. Select Project and Add Module from the Microsoft Visual Basic toolbar.
   2. Select Existing and edaglob.bas from one of the following paths:

   drive:\ibi\client71\home\etc

   drive:\ibi\srv71\home\etc

3. Compile the application in the usual Visual Basic manner to obtain an executable file. Select File and Make *.exe from the Microsoft Visual Basic toolbar, where * is the name of the application.

4. At run time, the edaapi.dll file will need to be in a directory on the PATH variable. The default location of this directory is ibi\client71\home\bin or drive:\ibi\srv71\home\bin. The adjustment to the PATH variable may be made to the machine/user profile or by creating a .bat file to wrapper the executable.

5. To run the program, double-click *.exe (or the .bat file if you have chosen to create one) which is located in the current directory.

Note: This sample application was originally designed with a pre-VB6 release under a prior name (EDAFUNC). For the 5.3 release, the name was changed to be consistent with the other API samples and some unused references were cleaned up. It is otherwise the same and verified for use with VB6 and Visual Studio .NET 2003. VB7 does not use the same type of project file, and there are syntax differences, but VB7 has an import feature which was successfully used to build and run the VB6 edaapp sample. There are no plans at this time to created a pure VB7 sample, the import feature should be used.

Creating Programs with GENCPGM.BAT

Gencpgm.bat is a DOS batch file for the compilation of C, C++, and Visual Basic (VB6) using Visual Studio 6 and C and C++ using Visual Studio .NET 2003 programs from a DOS command line. This batch file provides a simple compilation method for simple compilation cases. It does not support the full capabilities that a Windows development IDE provides. The use of GENCPGM is not required to build an application provided a proper development environment exists. To use this method, use the "-?" option for a list of features (most features follow the UNIX version of this script).

Creating Cobol, Fortran, and other 3GL programs

Specific build information for the Windows environment for Cobol, Fortran, and other 3GL programs is not available due to the number of vendors in the market. Though the environments vary, there is no reason to believe that the various compilers on Windows for these languages would not work since compilation on other platforms and using various other vendors does work. It is simply a question of understanding the product requirements and methods for creating and using external DLL libraries. Customer Support will glad to assist in researching issues and bringing them to the attention of the development staff for resolution if needed.

A Cobol API example (edaapp.cbl) is supplied in the etc directory, however, there is no Fortran API example.