This is part of the Heirloom Computing Elastic Batch Platform forum on paas.heirloomcomputing.com.
Invoking PL/I Applications from EBP / JCL
EBP can invoke your Elastic PL/I applications through JCL. The following JCL snippet will invoke the program JOBA and associate three DD names with it.
//MYJOB JOB (1111,2222),'RUN PL/I',CLASS=A,MSGCLASS=A,
// MSGLEVEL=(2,2)
//STEPID02 EXEC PGM=JOBA,PARM='JOBA INPUT'
//SYSIN DD DUMMY
//SYSOUT DD SYSOUT=*
//MYFILE DD DISP=SHR,DSN=ABC00.A.B.JOBAIN
The DSNs are relative to the Data LIbrary settings in the EBP configuration, the default being /data or d:\data directories. Applications define DD names by declaring FILE variables within the PL/I program and, if a RECORD file, a record structure describing the data (STREAM FILEs require no such structure).
joba: proc(arg) options(main);
dcl arg char(100) varying;
dcl myfile file record;
dcl 1 record,
2 data char(80);
open file(myfile) input;
read file(myfile) into(record);
put skip list(arg, ' data:', data);
end;
In order for the Elastic PL/I compiler to assign the PL/I RECORD or STREAM files with a DD Name referenced in JCL declare FILE variables with an 8-character name or specify the DDNAME option in the FILE declaration ENVIRONMENT clause. You can use the Elastic PL/I Eclipse plug-in to edit, compile, run and debug your PL/I program. You can also submit a batch job to EBP referencing the built-in JCL PROC HCEPLI to compile, load (package into a jar) and go (run) your application. You can also compile through the Elastic PL/I command line interface
epli -rc:ebp joba.pli
The -rc:ebp compiler option indicates that Elastic PL/I should return EBP-style return codes (0 OK, 4 warning, 8 error, 16 severe) that can be tested with subsequent JCL EXEC card COND clauses. Package all of the classes of the job into a jar file together with the Elastic PL/I runtime library (and optionally license properties file) with the command:
jar -cfe joba.jar Joba *.class eplirt.jar elasticcobol.properties
The elasticcobol.properties file is the license to run Elastic PL/I and is shared with other Heirloom Computing, Inc. producs such as Elastic COBOL and Elastic Batch Platform licenses. It is usually stored in your home directory as to be accessible by the Eclipse plug-ins for Elastic COBOL and Elastic PL/I. If the license file is not packaged in the jar, it will use the one on the deployment server. The eplirt.jar file will be in the library section of where you installed Elastic PL/I. If you installed Elastic PL/I under Eclipse this will be in the Eclipse "plugins" directory.
- /c/Program\ Files/eclipse/plugins/com.heirloomcomputing.epli_xx.yy.zz/
Finally, run your application by submitting a batch job that references the main program (PROC OPTIONS(MAIN) procedure) from a JCL EXEC card as shown above.
Within Eclipse File > Export using the Elastic PL/I Deploy Wizard. The resulting jar file must be placed in a JOBLIB or STEPLIB library directory or in the System Library. See EBP configuration settings to establish the System Library path.
You can also compile and deploy the batch executable from the Elastic PL/I IDE (Eclipse).
Then the Elastic PL/I Deployment Wizard will package the JAR with license file
Deploy batch programs anywhere on the deployment server. For deploying in cloud Heirloom instances, use the Cloud deployment option and select the started instance from the list. Even if this is not a Web application it may be deployed under any of the cloud servlet engines or application servers. The location of the deployment must be specified in the EBP Configuration Settings, two of which are applicable to finding executable programs:
- systemlib.n - individual directories which include, by default, the same d:\data or /data used for datasets in datalib.1..datalib.9 configuration settings
- classlib.n - the classpath directories or colon-separated (Linux) or semi-colon-separated (Windows) path variables and/or environment variables $CLASSPATH
- datalib.n - directories containing datasets, the first of which that is writable is where DISP=NEW datasets will be created.
Other EBP configuration settings control the directory ordering (A.B.C.D as A.B/C/D) and case (A.B.C.D as a.b.c.d) when datasets are created by EBP.
Multiple PL/I main and sub procedures can be deployed into the same jar file. To reference them in the EBP EXEC PGM=NAME statement the NAME refers to either a jar file or a class within a jar file. Elastic PL/I uses the Java class naming standards by default so a PL/I main program "joba" is compiled into a file named "Joba.java" resulting in a Java class named "Joba.class". Camel-case is used for procedures containing underscores. A PL/I main program "my_job_a" would produce a main class "MyJobA." Thus, the name need not be in a file called NAME.jar or name.jar. When the main program cannot be found in name.jar the JOBLIB and STEPLIB DD cards are searched for any jar (as are the EBP classlib.n configurations) that contains a class name with a static main(String []) method defined. EBP will start the program with that entry point.
HCEPLI Cataloged Procedure
You can batch compile your PL/I programs from within EBP as well. Use the HCEPLI built-in procedure contained in the default system PROCLIB. The procedure can compile individual .PLI files and link (i.e., create a JAR file) them together. Here's such a job:
//* :....1....:....2....:....3....:....4....:....5....:....6....:....7.
//COMP17 JOB (HCIACCT),'PL/I COMPILE',CLASS=A,MSGCLASS=A,
// MSGLEVEL=(2,2)
//*
//* compile and run PL/I programs using built-in
//* HCEPLI cataloged procedure
//*
//STEP1 EXEC HCEPLI,PGMID=Joba,GO=YES,GOPARM='JOBA INPUT'
//COPY.SYSUT1 DD *
joba: proc(arg) options(main);
dcl arg char(100) varying;
dcl myfile file record;
dcl 1 record,
2 data char(80);
open file(myfile) input;
read file(myfile) into(record);
put skip list(arg, ' data:', data);
end;
/*
//GO.SYSOUT DD SYSOUT=*
//GO.MYFILE DD DISP=SHR,DSN=ABC00.A.B.JOBAIN
//*
//* :....1....:....2....:....3....:....4....:....5....:....6....:....7.
Description
The HCEPLI cataloged procedure compiles, links and runs Elastic PLI applications. The Elastic PLI compiler (epli or epli.exe and eplirt.jar) must be installed separately from EBP on the server machine and accessible on the pathlib configuration setting that, by default, includes the system path $PATH environment variable. The compiler license file elasticcobol.properties or licensing.properties must also be present in the server user's home directory. Beyond that, a number of procedure keywords control the operation and data definition cards define the input and output of each step.
Up to four steps are executed in this PROC depending upon the parameters to it.
Steps
- COPY - copy the PL/I source file into temporary spool directory for the job. In general all of the intermediate files are left in the temporary spool and removed at job conclusion
- COMPILE - run the Elastic PL/I compiler
- LINK - link all available class files generated from the COMPILE step and combine them with the Elastic PLI runtime libraries into an executable jar file. The LINK.SYSOUT DD card indicates the output of the link (jar) process but by default leaves it in the temp spool for the GO step, if included
- GO - run the resulting program if the corresponding parameter is turned on.
Parameters
- COMPILE=YES|NO - compile source PLI program (default: YES)
- LINK=YES|NO - link into an executable Java archive (jar) file after compile (default: YES)
- GO=YES|NO - run the program after link (default: NO)
- PGMID - the PL/I PROC OPTIONS(MAIN) name of the program being compiled (required) must match the Java class name generated by the compiler which uses camel case for classes (JOBA: PROC OPTIONS(MAIN)" becomes Joba.class and is also the entry point (main class) in the executable jar created with when LINK=YES.
- OPT - Elastic PL/I compiler options (optional)
- GOPARM - the runtime parameters to the program during GO
- REQ - Elastic PL/I required options (default -rc:ebp)
Data Definitions
- COPY.SYSUT1 - input PL/I source program (found in datalib)
- COPY.SYSOUT - IEBGENER report during pgm source copy (defaultDUMMY)
- COPY.SYSERR - IEBGENER report during pgm source copy (defaultDUMMY)
- COMPILE.SYSOUT - Elastic PL/I compiler errors/warnings
- COMPILE.SYSERR - Java compiler errors/warnings
- LINK.SYSIN - eplirt.jar + etrans.jar (found in datalib)
- LINK.SYSERR - Java jar command errors
- LINK.SYSOUT - output jar file (dflt &PGMID..jar in temp spool)
- GO.SYSOUT - output of running program (dflt SYSOUT=*)
- GO.SYSERR - error output of running program (dflt DUMMY)
- GO.ddname - other DDNames referenced in the SELECT ASSIGN clause of a file definition
Notes:
- epli or epli.exe commands must be found in a directory found in the systemlib.n configuration or the STEPLIB or JOBLIB of the deck.
- javac and jar commands must be found in a directory specified in the systemlib.n configuration
- eplirt.jar, ecobol.jar and etrans.jar must be found in a directory specified in one of the EBP datalib.n configurations; e.g. datalib.4=/usr/local/lib if ecobol.jar and etrans.jar are contained in this directory. Note Elastic COBOL runtimes are required to use ISAM/VSAM/VDB files and/or ETP transaction libraries
- eplirt.jar, ecobol.jar and etrans.jar must be in the Java classpath, specified in one of the EBP classlib.n configurations; e.g., classlib.4=/usr/local/lib/eplirt.jar:/usr/local/lib/ecobol.jar:/usr/local/lib/etrans.jar
- EBP classlib configurations can include directories (containing class variables), explicit jar files (packed with class files) or environment variables ($PATH, $CLASSPATH). Each configuration may include multiple entries specified as colon- (Linux) or semi-colon-separated (Windows) entries.
Example
See the following end-to-end example of constructing a PL/I application and running it under EBP in Tips & Tricks Forum
- https://heirloomcomputing.zendesk.com/entries/End-to-End-PLI-in-EBP
Another comprehensive example (compiling, executing and running a database program) is also attached to this forum article as TESTC6.JCL.
0 Comments