Using the API in the OpenVMS Environment

How to: Create an Application Example: Using the EDAAPP Samples

The API requires some specific data structures in your applications, and has a number of numeric constants associated with certain method calls. C language descriptions of these data structures and symbolic definitions of the various constants are included in the eda.h and edasys.h header files. The eda.h file contains the symbolic constant and method prototypes. The edasys.h file is included by eda.h and contains OpenVMS-specific information. Similarly, edacpy.cpy contains a Cobol version of these definitions.

When you compile an API application written in C, C++, or Cobol, include the eda.h or edacpy.cpy header file in those sources where API method calls are referenced. If you are programming in a language other than C, C++, or Cobol, you must create the language-specific versions of the API data structures based upon the information in eda.h. Sample programs edaapp.c, edaapp.cpp, and edaapp.cbl are provided with the API.

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.

Procedure: How to Create an Application

1. Make sure you have properly declared EDAHOME and EDACONF as logicals.

2. Copy your API program to the EDACONF [.BIN] directory or a temporary work directory.
   1. Copy EDA.H and EDASYS.H (for C or C++ applications) or edacpy.cpy (for Cobol applications) from the EDAHOME [.BIN] directory to the EDACONF [.BIN] directory or the temporary work directory.
   2. Copy gencpgm.com from the EDAHOME [.BIN] directory to the EDACONF [.BIN] directory or the temporary work directory else use the full path name to its location in EDAHOME as needed.
   3. Compile and link your application from your 3GL source code, change the directory to EDACONF [.BIN] or the temporary work directory and execute the API program build procedure by issuing the following:

   @gencpgm -m api program_name 

   where:

   program_name reflects the name of the file assuming the API program is written using the C language. An executable for the program_name you specify will be created in your current directory plus a DCL command procedure helper script that sets logicals for runtime and invokes the actual program.

If your API program was written using Cobol, issue:

@gencpgm -c cobol -m api program_name 

If your API program was written using C++, issue:

@gencpgm -c c++ -m api program_name 

If your API program was written using Fortran, issue:

@gencpgm -c for -m api program_name 

To create a debuggable version of your API program, add the -g parameter. For example:

@gencpgm -g -m api program_name 

Note: Use the command "@gencpgm -help" to see a list of additional language and switch options that are available when executing gencpgm.com. The gencpgm script is also used for building sub-routines as described in the Stored Procedures manual.

3. The gencpgm script will also create an OpenVMS DCL command procedure (.com) as a wrapper to assist in invoking the API program. The script contains EDAHOME, EDACONF, and EDACS3 (communications configuration file) logicals with appropriate values and DCL to invoke the program image. The script will have the same name as the program, but will have a ".com" extension., and will run when preceded by a "@". If the .EXE for the application is moved to another directory, the location in the DCL file will need to be adjusted. Use of the script is not required if the environment is preset at a higher level such as a user's login.com, or the system login script. The DCL script is provided as an assistance.

To run the sample procedure after the compilation step, enter: @EDAAPP.

Example: Using the EDAAPP Samples

Sample application is included with the software and should be used as a test before building your own application to confirm that there is a properly working environment. The applications are called edaapp.c (C example), edaapp.cpp (C++ example), and edaapp.cbl (Cobol example) and are located in the etc directory of EDAHOME. To compile and execute, copy the application to the EDACONF [.BIN] directory and follow the standard directions above. The sample application is very similar to the 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 be built and tested.

Note: GENCPCM is written for simple cases. Complex linking requirements may mean the site must write custom scripts for the tasks. GENCPGM primary support is for C, but also supports Cobol, Pascal, Basic, and Fortran on OpenVMS. In writing complex applications, a DCL wrapper may be an ideal method to set up other site specific run-time tasks.