Using the API in the UNIX Environment

How to:

Create an Application

Example:

Using the EDAAPP Samples

Reference:

OS-Specific DLL Environment Search Variables

Compiling a Cobol Program on UNIX

Creating Cobol, Fortran, and other 3GL programs

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 UNIX-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.


Top of page

Procedure: How to Create an Application

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

  1. 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. Important: Step b is for OS/390 and z/OS only.

    3. Copy the libeda*.* files from the EDAHOME etc directory to the EDACONF bin directory or the temporary work directory with:
    4. cp $EDAHOME/etc/libeda*.* 
    5. Copy gencpgm.sh 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
    6. 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:
    7. gencpgm.sh -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 DLL helper script that sets logicals for runtime and invokes the actual program.

  1. The gencpgm script will also create a UNIX command shell procedure (.sh) as a wrapper to assist in invoking the API program. The script contains EDAHOME, EDACONF, EDACS3 (communications configuration file) and the shared library path variables for your platform with appropriate values and an exec to invoke the program image. The script will have the same name as the program, but will have a ".sh" extension. If the binary for the application is moved to another directory, the location in the shell command file will need to be adjusted. The OS/400 environment additionally creates (and compiles) CL and CMD files in the current library to allow application execution directly from the OS/400 command line. Use of these scripts is not required if the environment is preset at a higher level such as the user's profile script. The scripts are provided as an assistance.


Top of page

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) 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 and is all that can be built with the tool in the UNIX environment. Use of other languages such as Cobol or Fortran on UNIX requires the user to provide the build tool. In writing complex applications, the shell script wrapper may be an ideal method to set up other site specific run-time tasks.


Top of page

Reference: OS-Specific DLL Environment Search Variables

Operating System

Variable

AIX

LIBPATH

HP-UX

SHLIB_PATH

OS/400

See "OS/400 Users" below

All Others

LD_LIBRARY_PATH

OS/400 Users:

The gencpgm.sh compiles and creates programs into *CURLIB and creates an IFS symbolic link to the current directory for API programs. CURLIB should be set appropriately if a system or other library is the desired final location. The resulting client shell script for running the application will also do a "liblist -a" for the location so end users do not need to set or know the physical location if using the script.


Top of page

Reference: Compiling a Cobol Program on UNIX

Note: Testing was done Micro FOCUS Express 2.0.11 on AIX using the standard EDAAPP Cobol example supplied with the product. We have no reason to believe that compilers on other platforms and from other vendors do not work. These other combinations are just untested due to availability and there are no specific plans to test other environments due to the logistics of obtaining, maintaining and testing what could be many combinations. The Cobol example tested is the same example tested on OpenVMS and MVS so there is no question of program quality. If you are attempting to use an untested environment and are having specific problem, the first step are to check the supported general features of the compiler, specifically how the compiler supports the use of external DLL libraries and get the standard EDAAPP example working before attempting a custom application. Customer Support will glad to assist in researching issues and bringing them to the attention of the development staff for resolution if need.

Older versions of Micro Focus Cobol required an customer written interface stub and prefacing of calls with special syntax to link and use external libraries; this is no longer required in recent Micro Focus Cobol releases and programs link much like C. However, this may be indicative of the complexity of using other third party compliers, so BEWARE.

Micro Focus Cobol may have the word "Focus" in it, but is not a product of Information Builders.

  1. Required variables for compilation are EDAHOME and the library path for the machine (AIX uses LIBPATH, HP/UX uses SHLIB_PATH and LD_LIBRARY_PATH on other UNIX systems. The library path will also require Micro Focus's Cobol library directory and the EDAHOME bin directory. It is also convenient to have the Micro Focus Cobol bin directory is on the PATH so full path names are not needed for the "cob" command.

  1. The actual Micro Focus Cobol compile command on UNIX is:

    cob -V -x myprogram.cbl -L $EDAHOME/bin -l edaapi
  1. Create a shell script with appropriate variables set and execute of the actual binary. The required variables are EDAHOME (software install location), EDACONF (software configuration location), EDACS3 (full path name of communications set up file, usually $EDACONF/etc/odin.cfg) and the shared library path variable for you machine with $EDAHOME/bin added. Alternately, the variables may be declared in the .profile and the binary just executed.


Top of page

Reference: Compiling a Cobol Program on OS/400

The gencpgm.sh program on OS/400 supports a -c cobol switch and may be used to build Cobol programs. It assumes the Cobol program in in the current directory with a .cbl or .cob extension or it will check for the source in QCBLLESRC.


Top of page

Reference: Compiling Fortran or Other 3GL Programs on UNIX

Specific information for the UNIX environment is not available due to the number of vendors in the market, though the environments vary and adjust accessibility to the products. However, we have no reason to believe that these compilers on UNIX 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 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.


iWay Software