x

UNIX, Linux, IBM i, USS:

{path}gencpgm.sh [-h] [-x] [-q] [-l EDAHOMELIB] [-p LOADLIB]
 [-d directory | -w directory] [-g] [-c language] [-m application type]
 [-b lib/srvprg] [-j jarname] {path}{program name}[.{extension}]

Windows:

{path}gencpgm.bat [-h] [-x] [-q] [-d directory | -w directory] [-g]
 [-c language] [-m application type] [-j jarname]
 {path}{program name}[.{extension}]

OpenVMS:

@{path}gencpgm.com [-h] [-x] [-q] [-d directory | -w directory] [-g]
 [-c language] [-m application type] [-j jarname]
 {path}{program name}[.{extension}]

where:

Switch/Option	Description
-h	Outputs this Help text.
-x	Turns on set -x shell tracing to assist in debugging.
-q	Quite switch to redirect output to nul:, does nothing on UNIX.
-L EDAHOMELIB	Server for z/OS in a PDS deployment only. Indicates installation home {HLQ}.HOME of ETC.H for picking up standard IBI C include files (needed for some samples).
-C EDACONFHLQ	Server for z/OS in a PDS deployment only. Indicates installation configuration {HLQ} of ETC for picking up standard IBI files (ie server and communications configuration files).
-A APPROOTHLQ	Server for z/OS in a PDS deployment. Indicates installation configuration {HLQ} of APPS (APPROOT) for picking up application files for HLI applications.
-S SCRIPTSPDS	Server for z/OS in a PDS deployment only. Indicates PDS to copy application build JCL and run time execution scripts for batch JCL and interactive CLIST and REXX of the application.
-p LOADLIB	Server for z/OS in a PDS deployment only. Indicates JCL type compilation and points to the load lib to use. The load lib must be in run time STEPLIB.
-d directory	Work in the given directory. The C file should be in this directory. All resulting files will be generated in this directory. This is for COMPILED DEFINE purposes and not intended for customer use.
-w directory	Write final executable (and any helper scripts) in the given target directory.
-i directory	Include directory. Multiple uses allowed.
-g	Generate a debuggable program by including debug switch in the compilation and link.

The -c option is described in the following chart:

Language	Compiler to use for a given language source.
cc	Use standard C compiler to compile "progname.c". C is the default compiler language.
assembler	Use assembler compiler. Only implemented for z/OS currently. HFS usage requires source to have a .s file extension.
fortran for f	Use default Fortran to compile Fortran with a .fortran extension. Use default Fortran to compile Fortran with a .for extension. Use default Fortran to compile Fortran with a .f extension. Supply explicit extension to override extension. If default compiler is not available, GNU g77 will be checked for availability and used.
f77 f90 f95 old_f77	Use a specific Fortran compiler to compile. Fortran implementation on UNIX is limited to Sun SUNWspro f95 and GNU (g77/f77) as most UNIX OS vendors do not supply Fortran compilers. OpenVMS supports F90 (default), F77 (Compaq Specification and OLD_F77 (DEC Specification).
g77	Use the GNU Fortran (g77/f77) compiler to compile "progname.f". GNU is only selectively supported as we do not have it installed on all platforms, but should work because GNU is GNU.
gcc	Use the GNU C (gcc) compiler to compile "progname.c". GNU is only selectively supported as we do not have it installed on all platforms, but should work because GNU is GNU.
CC CXX cpp	Use the "C++" compiler to compile "progname.cpp". C++ (C++ programs are expected to have .cpp suffix, c++ however, MVS OE requires .C as an explicit extension.
rpg	IBM i Only: Use RPG compiler to compile IFS "progname". Default extension is .rpg. Source may alternately exist as member in *CURLIB/QRPGLESRC.
pl1	z/OS Only: PL/1
basic bas	OpenVMS Only: Basic
pascal pas	OpenVMS Only: Pascal
cobol cob cbl	Use COBOL compiler to compile "progname.cobol".Use COBOL compiler to compile "progname.cob".Use COBOL compiler to compile "progname.cbl". Supply explicit extension to override.
java	Dummy placeholder, -m cjava is the driving factor for Java compilation.

The -m option is described in the following chart:

Application Type	Type of Application to Build
hli	Generate an HLI program linked to the EDA HLI library that opens and modifies FOCUS data files.
odbc	Generate an ODBC API client program linked to the ODBC API driver w/o Visigenics Driver Manager.
cpgm dll	Generate a "callpgm" server program library or sub routine (aka Fuselib routine). Default is a C source with .c extension unless specified by explicit (known) extension or specific -c compiler flag.
cjava	Generate a class in a jar for "calljava" server program usage. Multiple .java sources are allowed under this feature. Default jar file name is the same as the first named java source (use -j to create specific jar file names). Not supported on OpenVMS.
cl	IBM i only: Compile CL command file. Default extension of .cl; LIB/FILE(MBR) type of file specification allowed if quote enclosed to prevent sub shell interpretation by the command line parser.
cmd	IBM i Only: Compile CMD command file. Default extension of .cmd; LIB/FILE(MBR) type of file specification allowed if quote enclosed to prevent sub shell interpretation by the command line parser.
dds	IBM i Only: Compile DDS screen file. Default extension is .dds. Source may alternately exist as member in *CURLIB/QDDSSRC. DDS is an IBM i only extension for compiling screen handling files for RPG and other IBM i languages that use DDS.
-b lib/srvprg	IBM i Only: Bind in additional IBM i service programs during the link phase.
-ansi	OpenVMS Only: Indicates /ANSI switch should be added to compiler string. For COBOL this allows line numbers. For C this uses ANSI C aliasing rules.
-ieee	OpenVMS Only: Indicates /FLOAT=IEEE should be added to compile string. The G_FLOAT version of the product automatically does /FLOAT=G_FLOAT, this switch allows IEEE to be forced by the G_FLOAT version.
-gfloat	OpenVMS Only: Indicates /FLOAT=G_FLOAT should be added to compile string. The IEEE version of the product automatically does /FLOAT=IEEE, this switch allows G_FLOAT to be forced by the IEEE version.
-j jarname	Used solely in conjunction with -m cjava to specify a specific jar to create. A .jar extension may be supplied, but extensions other than .jar are ignored and automatically switched to .jar. If the switch is not included, the first java source will be used to form the jar name (ie myapp.java yields myapp.jar).
[{path}]{program name}[[.extension}]	Name of source program to build. Must be last argument. All arguments after program name are ignored. Extension is optional, but can serve to override a language default for a -c language specification. A path to a source is allowed (ie source/foo.c), but non system includes must be in current directory or the -i option must be used. Server for z/OS in a PDS deployment, a dataset name or pds name may be specified if -p option is in use, however, the use of parenthesis characters in the specification also requires that the name to be quoted to prevent sub shell interpretation by the command line parser.

x

This section outlines the steps required to compile and link a sample procedure provided with the product:

1. Copy GENCPGM from the EDAHOME bin directory to your working directory or use the full path name to the location, and:
   • For a CALLPGM program or to build the CALLPGM sample program (CPT, SPG*.CBL, or SPG*.RPG), copy the sample program and any required include files from the etc/src3gl directory of EDAHOME to your working directory.
   • For user exits, copy the desired sample exit from the etc/src3gl directory of EDAHOME to your working directory.
   • For user routines, write the routine or copy and modify an existing routine to your working directory. (This document provides MTHNAME samples for C, COBOL, RPG, and Fortran, which you can use for reference.)
2. Issue an environment variable for the EDAHOME directory. For example:

   Windows	SET EDAHOME=C:\ibi\srv71\home
   IBM i (formerly known as i5/OS)	export EDAHOME=/home/iadmin/ibi/srv71/home
   UNIX	export EDAHOME=/home/iadmin/ibi/srv71/home
   USS	export EDAHOME=/home/iadmin/ibi/srv71/home
   OpenVMS	DEFINE EDAHOME IADMIN:[IADMIN.IBI.SRV71.HOME]

3. If building an API program, also issue an environment variable for the EDACONF directory. For example:

   Windows	SET EDACONF=C:\ibi\srv71\ffs
   IBM i	export EDACONF=/home/iadmin/ibi/srv71/ffs
   UNIX	export EDACONF=/home/iadmin/ibi/srv71/ffs
   USS	export EDACONF=/home/iadmin/ibi/srv71/ffs
   OpenVMS	DEFINE EDACONF IADMIN:[IADMIN.IBI.SRV71.FFS]

4. Run GENCPGM. For example, on UNIX:

   gencpgm.sh -m cpgm mysub.c

x

While there may not be a sample in every language for every application type, the first step is to confirm that there is a working environment by building one of the standard samples for the desired application type and confirming that it runs. If the samples do not work, there is little hope that a custom program will work.

Switches function similarly on all implementations, although, some are platform/need specific.

Programs generated for HLI will also have command file shell wrappers created with the system variables used for run time execution (that is, EDAHOME, EDACONF, EDACS3 and the library path needed for HLI to load) producing a self contained environment for runtime execution. At runtime, all application setup needs are self-contained within the wrapper so that the application simply runs. The explicit use of a GENCPGM-generated application wrapper is not required if the settings within a given wrapper are issued elsewhere (such as in a system or login profile) and the executable is directly used.

On IBM i CL and CMD, wrappers are also created in *CURLIB so applications can also be called directly on the IBM i command line. On z/OS PDS deployment, JCL, CLIST, and REXX wrappers are created as appnameJ, appnameC and appnameR (respectively), if the application is 7 characters (or less) and the -S switch has been used to indicate a save PDS name. Since the running interactive or batch and selecting a preferred language are strictly run time choices, PDS mode creates all three scripts to be prepared for all situations.

Due to the numerous third party vendors of COBOL, Fortran and other languages, inconsistency of switches between third party vendors and across platforms, GENCPGM has only limited testing of third party compilers. The actual supplied COBOL and Fortran sample programs themselves are known to work on several platforms where we do have compilers so if GENCPGM for you platform doesn't support a particular language the sole question is of figuring out how to compile and link them in order to work. Please also note that some samples (particularly COBOL) have comments of specific platform related changes that must be made for to accomplish proper compilation such as changing the PROGRAM-ID to a quoted lowercase string to achieve a properly created program entry point.

For CALLJAVA applications (-m cjava) more than one source to compile is allowed and the resulting classes are created into a single jar is supported. Java sources must have file extension of .java and specifying the actual extension on the GENCPGM command line is optional. If there are multiple source and no -j jar switch is supplied, the first source will be used to form the jar name.

The language parameter value for -c drives the default extension for a given language (except for Java), but supplying a full program name (ie mthname.cbl) will override a default.

If the compilation was for CALLPGM, a user exit, or a routine, the final step is to either copy the resulting routine to the user directory of EDACONF or set the environment variable IBICPG to the name of the actual working directory (and restart the server). This final step puts the resulting routine in a path that the server searches for routines at run time. User exits are not explicitly covered in this manual, but follow the same rules as a routine.

x

Theoretically any compiled 3GL language can be used to create an HLI, Call Procedural Program, or Subroutine programs. C is generally considered the standard language and is universally tested and implemented on all supported platforms with samples for all application types. Other languages are more selective in terms of applications for which samples exist and platforms in which they can be tested (usually due to complier availability on a given platform).

Java and Javascript do not have options for generating Dynamic Load Libraries (DLLs), and, as such, cannot be used for creating HLI, Call Procedural Program, or Subroutine programs. However, in a language like C, it is possible to create a wrapper that loads and passes parameters to Java and receives parameters back. Thus, while Java is feasible, it is not direct and would present performance issues if done in this context and thus can not be recommended or officially supported.

Fortran: It is possible to build DLLs and programs using Fortran on any platform, however, at this time GENCPGM is only coded for Fortran on z/OS, OpenVMS, UNIX GNU g77 and SunOS SUNWspro. Additionally, there is only a sample for SubrRoutine usage. The -c fortran switch on SunOS defaults to f77 usage on AMD64 and f90 on Sparc9, use the -c f77/f90/f95 switch to force other specific levels. The -c fortran switch on UNIX's will attempt to use g77, if found on the path.

COBOL:COBOL: It is possible to build routines using Cobol on any platform. At this time gencpgm is coded to do Cobol only on select platforms and using select Cobol vendors, specifically ... on UNIX with MicroFOCUS Cobol (using the mf* switches), OpenVMS using HP's Cobol, on IBM i using IBM ILE Cobol and IBM z/OS using Enterprise Cobol in -p mode. MicroFOCUS Cobol use has some additional use restrictions as described in the -c mfcobol section of the gencpgm chart.

On IBM i: Only ILE compilers are supported. Only the IBM i C compiler can directly compile files on the IFS file system. GENCPGM on IBM i does this feat for other languages by checking the default library location (for a given source type) for the existence of the desired file and if it does not exist it does a CPYFRMSTMF to duplicate the file into the library for the compilation process. If GENCPGM does a source file copy to a library, it will also remove the file afterwards so extra copies aren't floating around. In this way, sources on IBM i can exist as either IFS or library files.

On z/OS PDS Deployment: The script in hlq.HOME.ETC(GENCPGM) is an OMVS shell script and is not JCL, so it cannot be directly run from the PDS. To use under PDS deployment, copy the GENCPGM member to HFS, do a chmod +x to the script, and use as described below with z/OS switches.

Once the script is copied to an HFS directory, it is executed with the -L, -C, -A, -,S and -p options, which creates and then submits a JCL compilation stack that is language- and application-specific. If the JCL is successful, the resulting program will end up in the specified -p PDS. Regardless of build success, the JCL stack is always left behind and is saved in the current directory as the program name with a .jcl extension, as well as in the -S location if a -S switch was used. Additionally the -s switch will allow you to directly generate JCL into an HFS file or DSN, but not execute. The -s switch (lowercase s is required) is useful for sites where standard IBM libraries locations are not used for compiler and link library updates (as is commonly done at sites for add on features and updates), thus allowing a site to generate and then "adjust" the JCL for site specific needs before submission. The -S switch (uppercase S is required) does actual compilation plus saves build and run time scripts into the specified PDS for later use.

On OpenVMS: Special Oracle and Rdb relinking options are supported (-relink oracle, -relink rdb and -relink rdball (rdball is for when Multi Release Rdb is in use) for when library identity mismatches occur and require on-site linking. Do not use these options unless an explicit problem has been identified with customer support and you are requested to do so.

x

Should you chose to write a build script instead of using GENCPGM, the rules are fairly simple.

DLLs for Subroutine and CALLPGM Usage: Library name (less extension and any prefix such as lib) and entry point name must match. Some compilers are case sensitive on entry point name usage and some are not or uppercase entry points automatically; thus some require special coding to force lower case names as in mentioned COBOL cases. Specifically entry points must be lowercase.

Executables for HLI Usage: Must link in edahli DLL and create an executable with a main. Various environment variables must be set in order for application to run, the wrapper created by building the appropriate test sample should be used as a template as it contains any general and platform specific coding.

In both cases it is suggested that you use the standard test samples for your language of choice with the -x switch to examine the precise build switches used in any particular environment to assist in any custom built scripts.

Top of page

Example: Generating a Subroutine Program From a C Source File

The following example will generate a debuggable callpgm program library from a C source code file named myprog.c using the standard C compiler.

Optionally, the explicit API switch could have been used:

gencpgm -g -m cpgm myprog

Top of page

Example: Generating an HLI Program From a C Source File

Because the Standard C compiler and HLI mode are default options, the following example will generate a debuggable HLI program from a sample C source file named myprog.c using the standard C compiler.

Optionally, the explicit HLI switch could have been used:

gencpgm -g -m hli myprog

Top of page

Example: Generating a CALLPGM Program From a C Source File

The following example will generate a debuggable callpgm program library from a C source code file named myprog.c using the standard C compiler.

gencpgm -g -m cpgm myprog

For actual CALLPGM code samples, see Writing a 3GL Compiled Stored Procedure Program.