PERCobol calling HP COBOL II ---------------------------- This sample demonstrates PERCobol calling HP COBOL-II. It does require JDK 1.2; native code calling changed significantly in JDK 1.2. (It does not change so significantly again; JDK 1.3 is done in the same manner.) The sample itself is ready to run, including a precompiled and linked HP COBOL-II program (source included). To extract the tarfile, go to the Posix shell in a temporary directory. cd /usr/local/percobol mkdir cobolii cd cobolii {transfer the file in binary mode to the /usr/local/percobol/cobolii directory} tar xvfop percobol_hpcobolii.tar It includes directions in the readme_native.txt describing how to setup any arbitrary call to an HP COBOL-II. This appears complex, but is actually boilerplate/template code and generally only has to be done once per native program being called; we can help you through this when the time comes. (If familar with C programming, it would look very direct.) The result is that the native program looks like a normal PERCobol CALLable program. Native Code Calling on HP-3000 MPE/iX ------------------------------------- PERCobol runs in a Java environment, a completely separate environment from traditional code. There is, however, a bridge between the worlds called JNI (Java Native Interface); PERCobol includes support for JNI through an easier syntax which preserves the Cobol calling information, allowing that information to be more directly transferred through to HP COBOL-II. The following may sound complex, but the steps are relatively simple if the tools are on hand, and the steps are easier than dealing with raw JNI for calling Cobol. This JNI support is only valid in JDK 1.2 and above. (The interface does not change for JDK 1.3 or Hotspot.) The example program may be run directly by following the notes for step 5; setup the PERCobol program and run 'java callhpnative'. The stubs are precompiled for the given HP COBOL-II sample program already. Steps 1 through 4, the creation of the stubs, need only be done once for creation of an interface to existing code. If the native code is already working, then the stubs are created once, and then the PERCobol code may be used from then onwards. These tools and the creation of the stubs, etc. are not necessary for deployment; only the final PERCobol classes and the created interface are for deployment. The file libpercobol_native.sl is the file which may be called from PERCobol directly. It can include any valid C code, including calls to HP COBOL-II. Its source code is available, so it may be freely modified and used in conjunction with PERCobol; it may be re-built for any custom usage. There are two tools necessary for building this bridge: gcc and ld, the GNU Compiler Collection and linker. 1. Know the Cobol Program to Call The HP COBOL-II's external program name and its parameters must be known. >From the LaserROM documentation, HP COBOL-II's external names are formed from the internal program-id name, with each hyphen converted to an underscore, uppercase converted to lowercase, and name truncated at 30 characters. This is the name callable from C code. The PROGRAM-ID NATPGM is called 'natpgm' in C code. 2. Call it from C A small snippet of C code must be added to libpercobol_native.c. This snippet's job is to check if it's trying to call the desired program, and if so, call it using the correct number of parameters. If PERCobol compiles the calling program with a '-dt 4' for MPE datatypes, then the call is direct; the parameters will be in the correct format already, so if there are three parameters, those three parameters are passed directly. This example includes a call to natpgm; it should be removed when creating an actual library for other than testing. (Naturally, anything which may be done from C source code may be done from this point as well.) 3. Link the C to the Cobol The libpercobol_native.sl must be linked together from the percobol_native.c code (including the custom snippet) and the object code from the HP COBOL-II program. 4. Copy the linked file where it may be found The file libpercobol_native.sl must be findable from the PERCobol calling program; the environment variable LD_LIBRARY_PATH includes a path of directories which are searched. The /usr/local/percobol/bin directory is already included in the list from the '. ./setclasspath' statement, so it's common to leave libpercobol_native.sl in that directory. 5. Call it In PERCobol, the CALL statement name should be exactly the name checked for in percobol_native.c. --------------------------- NOTES ON PARTICULAR EXAMPLE --------------------------- 1. NATPGM is an HP COBOL-II source program. natpgm.o is the link object created by HP COBOL-II; it ends in .o so it may be known as an object by the linker. natpgm(param1,param2,param3) is the program name to call. 2. // A case-irrelevent comparison between the desired name and NATPGM if(cistrcmp(argv[0],"NATPGM")==0) { // We're trying to call NATPGM, which we know how to handle, // so we say the program is found result=STATUS_FOUND; // We call the program, using the three parameters which the // the program expects; we could do more error checking like // checking the argc (argument count), and argument lengths // to be sure that they're not too small or too large for the // Cobol program, but this code is leaving out the checking // to be sure that the purpose of the code is clear. // We're passing through three parameters; they're numbered // 1 to 3. natpgm(argv[1],argv[2],argv[3]); } 2. and 3. are handled by the Posix script make_mpe; it may be executed by: ./make_mpe 4. shell/iX> cp libpercobol_native.sl /usr/local/percobol/bin 5. Execute it from PERCobol The PERCobol files begin with callhpnative. The source code is callhpnative.cbl. The executable is callhpnative.class; all Java executables end in .class. With PERCobol setup on the system (cd /usr/local/percobol; . ./setclasspath), the program may be executed as: java callhpnative In the source code, the CALL is simply: PARAM-1 PIC X(10). PARAM-2 PIC X(20). PARAM-3 PIC X(30). CALL "NATPGM" USING PARAM-1 PARAM-2 PARAM_3