Introduction
This is part of the Heirloom Computing EBP Elastic Batch Platform forum on paas.heirloomcomputing.com.
Configuration parameters may be set by modifying the ebp.properties file in the Web application deployment directory or by using the config Web service. Configuration settings persist until and unless the EBP subsystem is redeployed under the application server. Below is a list of settable configurations.
Warning: Updating Elastic Batch Platform to a new version will replace your ebp.properties file with the default for that version, removing existing settings. Use the SAVE button to save configurations and LOAD button after the upgrade. See Configuration Web Page for more info.
Externalizing Configuration
It is also possible to specify a directory external to the war file that contains an ebp.properties file. This externalizes the config and is useful in cloud and Kubernetes environments such as AWS, Azure and OpenShift. This is done through the use of a system environment variable ebppropdir.
For example in Linux
export ebppropdir=/home/tomcatTells EBP to look in the /home/tomcat directory for the ebp.properties file. If this environment variable is set the ebp.properties file MUST be in this directory or ebp will fail to start.
Parameter Naming Conventions
EBP configuration parameters follow several naming patterns:
- ebp. prefix — Every actual configuration property in ebp.properties requires the ebp. prefix(e.g., ebp.hourglass.active, ebp.cobolconfig)
- ebp.dcb. prefix — DCBDB related settings. See the dedicated DCBDB: Database-Backed DCB for full details.
- ebp.rac. prefix — Resource Access Control / LDAP settings. See the dedicated RAC Configuration Guide for full details.
- Suffixed with .n — Numbered entries allowing multiple values (e.g., systemlib.1, systemlib.2)
- Suffixed with .XXXX — Named entries where XXXX is a user-defined key (e.g., output.A, parmlib
Configuration Parameters
Below is a list of settable configurations, organized by category.
Logging and Messages
| Parm | Description | Units, Default |
|---|---|---|
| messages | Indicates whether messages are generated on the application server's output and error logs or in the output.CONSOLE output spooler specification. |
yes|no. Default yes |
| errorlevel | Indicates the level of error messages reported on the application server's output and error logs. Specified as S, E, W, I or D for severe, error, warning, informational, or debugging message level. Set to D when using rac.debug or hsortlog for detailed diagnostics. |
Default I |
Spool and Directory Settings
| Parm | Description | Units, Default |
|---|---|---|
| tempspool | Specifies the default location of temporary datasets and working directories for running programs. See also keeptempfiles to retain these files after a job completes. |
Default: temp_spool |
| jobspool | Specifies the default input spool directory. This directory holds submitted datasets. | Default: job_input_queue |
| outputspool | Specifies the default output spool directory. This directory holds output datasets associated with SYSOUT=class DD cards or standard out and error files for scripts and command line programs. Referenced by output.XXXX when using the hold disposition. |
Default: job_output_queue |
Library and Classpath Settings
| Parm | Description | Units, Default |
|---|---|---|
| systemlib.n | Specifies locations of system library directories where main programs on the EXEC PGM= statement may be found. For example, systemlib.9=/usr/bin would allow EXEC=echo,PARM='hi' to execute the Linux echo command. May be directories or Java packages. May contain environment variables, which themselves may be path-separated (e.g., $PATH). Special variable $HOME is the Web server's deployment home directory. See also alias.XXXX to redirect program names found here. |
Default: com.heirloomcomputing.pgm, /data |
| datalib.n | Specifies the location where datasets referenced on DD cards may be found. May contain environment variables. Special variable $HOME is the Web server's deployment home directory. Also used as the default location for database-based DCB files (VDB, VSQL); see Data Control Block Configuration. | Default: /data |
| jcllib.n | Specifies the location where system cataloged procedures referenced in EXEC PROC steps are found. May contain environment variables. Special variable $HOME is the Web server's deployment home directory. | Default: $HOME/jcl_system_lib |
| classlib.n | Specifies the CLASSPATH entries passed to programs such as ecobol and java that have a '-cp' option. They are Java path-separator separated entries which are either a directory (containing .class files) or jar files. The Linux path separator is colon and the Windows path separator is semicolon. For example, classlib.4=/usr/local/lib/postgresql-9.2-1003.jdbc4.jar:/usr/local/lib/db2jcc4.jar:/home/bud/myclassfiles. Note: J2EE servers and servlet containers such as Tomcat often do not pass $CLASSPATH environment variables through to applications. You may need to explicitly set the directory. See also DCBDB configuration if your JDBC drivers need to be available for database-backed DCB. |
Default: $CLASSPATH |
Execution Commands
| Parm | Description | Units, Default |
|---|---|---|
| javajarcommand | Command to issue to start programs that are contained in a jar file, such as the COBOL executables. See also classlib.n for setting the classpath available to these programs. |
Default: java -jar |
| javacommand | Command to issue to start programs that are found ending in .class, such as standard utilities. See also classlib.n for classpath settings. |
Default: java |
| ebpstartcommand | A command that sets operating system resource restrictions before starting the Java, Python or executable specified on the EXEC card. CPU time specifications in job class and JOB and STEP cards are regulated by EBP with this "wrapper." OS-specific versions are distributed with EBP but must be specified here as a relative path, e.g., ../../bin/ebpstart_Linuxx86_64. Where applicable, other job class restrictions are also enforced this way. |
Default: none — CPU time specifications are not enforced |
| pythoncommand | Command issued to start scripts that are running under a Python interpreter class and by TSO for % Python scripts (found in SYSEXEC DD datasets with .PY suffix). Scripts should start with #!/usr/bin/python and contain job parameters on the second line, # //MYJOB JOB 111,CLASS=P. |
Default: python |
| shellcommand | Command issued to start scripts that are running under a Shell interpreter class and by TSO for % Shell scripts (found in SYSEXEC DD datasets with .sh suffix). Scripts should start with #!/bin/sh or #!/bin/bash to indicate the interpreter and contain job parameters on the second line, # //MYJOB JOB 111,CLASS=P. |
Default: sh |
| rexxcommand | Command issued by TSO for % REXX scripts (found in SYSEXEC DD datasets with any other suffix). | Default: rexx |
Parameter Handling
| Parm | Description | Units, Default |
|---|---|---|
| parmcount | As parameters are passed to a program through a JCL PARM= clause of an EXEC, they can be divided into UNIX style argc/argv parameters (based on splitting the parm by spaces) or remain one large character string. This controls the number of args that will be passed to the program. Use 1 for IBM MVS compatibility and 256 for Linux/UNIX compatibility. See also parmempty for related behavior. |
Number 1–256. Default: 256 |
| parmempty | As parameters are passed to a program through a JCL PARM= clause of an EXEC, parameters evaluating to "" (no value) may be passed either as a single zero-length argument or no argument at all. Use no for IBM MVS compatibility and yes for Linux/UNIX compatibility. See also parmcount for related behavior. |
yes|no. Default: no |
| immediatesymbolreplacement | Replace symbolic parameters (e.g., &DEPT) inside immediate file (DD *) data if yes. See Symbolics and the PARMLIB for the full list of available symbolics. | Default: no |
Output Classes
| Parm | Description | Units, Default |
|---|---|---|
| output.XXXX | Output class specifiers, by class name (A, B, C) or DEFAULT or CONSOLE. The value for each may be: none (discard), hold in the outputspool directory under a job name subdirectory, log log-name to invoke the Java Logger (typically log4j) to log-name (EBP by default), lpr parms (pipe to lpr), or an arbitrary command, arguments and redirection specification such as cat >>afile (save to afile). DEFAULT is for all output classes not overridden. CONSOLE is for messages appearing on the EBP system console; CONSOLE set to hold will roll the log each day and place it in the outputspool location. When messages is set to yes, CONSOLE output also appears in the application server logs. Note: Output spool can contain &CLASS (the output class), &WRITER (the output writer) and &FORM (the output form) from the DD SYSOUT=(class,writer,form) statement along with PARMLIB symbolics. Note: log4j or other Java Loggers may need to be configured within the servlet container or Java Application Server hosting EBP. |
DEFAULT=hold, CONSOLE=none, L=log, P=lpr, S=cat >>/tmp/out&CLASS.txt, Y=hold, Z=none |
| msgclasscombine | Combine all SYSOUT=* output into a single MSGCLASS output dataset for convenience. Applies to all output classes defined in output.XXXX. |
yes|no. Default: yes |
PARMLIB, Aliases, and Standard Labels
| Parm | Description | Units, Default |
|---|---|---|
| parmlib.XXXX | Various user-definable PARMLIB values, such as a company wide DEPT code of 3250. These values become available as symbolics (e.g., &DEPT) in JCL. See Symbolics and the PARMLIB for built-in symbolics and immediatesymbolreplacement for using symbolics in immediate data. |
None |
| alias.XXXX | Replace EXEC PGM names with aliases, such as SORT having a value SYNCSORT, to force SYNCSORT as the default over Linux sort. The alias is resolved before searching systemlib.n directories. |
None |
| stdlbl.XXXX | Define VSE JCS standard labels for the label named XXXX. Label value contains a datasource name and disposition that will be added to each JCS job step unless overridden by a DLBL or ASSGN statement for that step. For example, stdlbl.SYSUT2=SYSCAT.MYDSN,DAT,DISP=MOD. Datasets referenced here are located via datalib.n. |
None |
Scheduling and Cloud Service
| Parm | Description | Units, Default |
|---|---|---|
| application | Schedule tasks for this application name from the hciservice portal; '*' for all tasks. |
Default: my-scheduled-tasks |
| hciservice | RESTful service end-point for cloud (global or local) scheduler. Used by scheduler polling and application task retrieval. |
Default: https://paas.heirloomcomputing.com/rest/2017-01-01/ |
| scheduler | Poll the scheduler at hciservice every few seconds. |
Default: yes |
| taskscope | Scope of tasks to be retrieved from scheduler (user, group or all) based on subscriber ID. Only relevant when scheduler is enabled. |
Default: user |
| scheduling | Currently polling scheduler for incoming jobs (read only). | Default: yes |
Job Timing and Delays
| Parm | Description | Units, Default |
|---|---|---|
| jobstepdelay | Delay up to n milliseconds between steps within a job. See also jobdelay for inter-job delays and initiatordelay for idle polling. |
Default: 100 (0.1 sec) |
| jobdelay | Delay up to n milliseconds between jobs within an initiator. See also jobstepdelay and initiatordelay . |
Default: 10000 (10 sec) |
| initiatordelay | Delay up to n milliseconds while idle or quiesced initiators look for jobs. See also jobdelay and jobstepdelay . |
Default: 30000 (30 sec) |
| maxjobage | Automatically purge completed jobs after an amount of time in minutes. Purged job output is removed from the outspool directory. |
Default: 0 (never purge) |
Dataset Naming
| Parm | Description | Units, Default |
|---|---|---|
| newdsndirectory | New DSNs created as directory hierarchies; 'A.B.C(D)' becomes 'A/B/C/D' if yes, 'A.B.C/D' if no. Affects how datasets are stored within datalib.n directories. See also newdsnlowercase. |
Default: no |
| newdsnlowercase | New DSNs created as lower case; 'A.B.C(D)' becomes 'a/b/c/D' or 'a.b.c/D' if yes. Works in combination with newdsndirectory. |
Default: no |
EBP-Plex (Multi-Node)
| Parm | Description | Units, Default |
|---|---|---|
| ebpplexnode | When operating a multi-node EBP (EBP-Plex), the Web service location of this node (e.g., http://10.20.30.40:8080/ebp). Must be set together with ebpplexpeer. |
None |
| ebpplexpeer | When operating a multi-node EBP, the Web service location of one other node in the EBP-Plex (e.g., http://10.20.30.41:8080/ebp). Must be set together with ebpplexnode. |
None |
| ebpplexauth | When operating a multi-node EBP, the basic HTTP authentication string (before encryption) used between secure servers (e.g., myuser:mypassword). Required when ebpplexnode and ebpplexpeer are configured and the servers require authentication. Security note: Ensure the ebp.properties file is properly access-controlled when this value is set. |
None |
System and Locale
| Parm | Description | Units, Default |
|---|---|---|
| sysname | Banner setting on console and logs. Also available as the &SYSNAME symbolic. | Default: HCI EBP |
| language | International locale codes indicating alternative EBP error message language (set to blank to use server/JVM locale). Works together with country. |
Default: en |
| country | International locale codes indicating alternative EBP error message files (set to blank to use server/JVM locale). Works together with language. | Default: US |
| timezone | Timezone for dates within MSG and SYSOUT dataset messages. Also affects the local-time symbolics (LDATE, LHHMMSS, etc.). |
Default: GMT |
Miscellaneous
| Parm | Description | Units, Default |
|---|---|---|
| keeptempfiles | Set to YES if you wish EBP to retain temp files created for a JOB run. Temp files are stored in the tempspool directory. |
yes|no. Default: no |
| ebp.abort.runningjobs.onrestart | Set to YES if you wish EBP to mark all running jobs as ABEND when server restarts. | yes|no. Default: no |
| showsqlexceptionincobol | Set to true if you want to add COBOL Runtime Option argument RUN_SHOW-SQL-EXCEPTION=true. This enables logging of extra SQL related information in case SQLException is thrown in the code. The default value of false does not add the COBOL Runtime Option at all. Requires errorlevel set to D or I for messages to appear in logs. |
true|false. Default: false |
| hsortlog | Set to true if you want to have additional logging in HSORT such as number of records written to files periodically. Requires errorlevel set to D for full detail. |
true|false. Default: false |
| ebp.stepexithandler | Set to a program (for example STEPEXIT) that should be executed after the end of the step. The program must be locatable via systemlib.n. See also ebp.jobexithandler for job-level exits. |
No default value; ignored if not set |
| ebp.jobexithandler | Set to a program (for example JOBEXIT) that should be executed after the end of the job. The program must be locatable via systemlib.n. See also ebp.stepexithandler for step-level exits. |
No default value; ignored if not set |
| ebp.previewsizekbs | Set a value of maximum file size in KB that is displayed in the EBP UI. Note that large files will negatively affect browser performance. | Default: 10 KB |
| ebp.cobolconfig | Path to the COBOL configuration file used by EBP to tell the COBOL runtime where to find the DCB configuration file. This avoids passing sensitive information (such as database credentials) on the java command line. Example: ebp.cobolconfig=/data/system/ebp.cobolconfig. See DCBDB configuration for details on the file format. |
None |
Read-Only Parameters
| Parm | Description |
|---|---|
| quiesced | System is in Quiesced state. |
| builddate | EBP Build Date. |
| buildversion | EBP Build Version. |
Security Parameters (RAC)
Resource Access Control parameters for authentication and authorization via LDAP are documented separately. See the RAC Configuration Guide for the full list of rac.* and ebp.rac.* parameters, including LDAP connection settings, user/role/resource lookups, advanced dataset authorization, and the RACF sidefile feature.
Saving and Restoring Configuration
You may want to occasionally back up your EBP configurations, such as when upgrading from one version to the next. Normally, when upgrading EBP all settings are reverted to their default setting. Use the SAVE button to save the current configuration in your local file named "config" (your browser may pop up a dialog box allowing you to rename it). After upgrading EBP, use CHOOSE FILE to locate that file on disk and LOAD to upload it to EBP.
CHOOSE FILE and LOAD can also be used to load Data Control Block (dataset catalog) information from .dcb files. See Data Control Block Configuration below.
Symbolics and the PARMLIB
Symbolics are available to JCL in the PARMLIB and are referenced with &NAME. You can set symbolics with the SET statement and initial procedure parameter values on the PROC statement or through the configuration setting parmlib.NAME. Certain symbolics are "built in" to EBP and generally follow all of those supported by IBM JCL. The following is a list of the built-in symbolics, including some EBP extensions to the standard set. You can reference the &NAME within an "immediate" file if the configuration flag immediatesymbolreplacement is set.
| Symbolic | Description | Origin | Example |
|---|---|---|---|
| DATE | The current date | JES | 20160101 |
| DAY | The current day of month | JES | 31 |
| DS | The DS code | JES | 601 |
| DEPT | Your department name (example symbolic) | EBP | IT |
| dynampartition | CA Dynam/D "==" partition name. Symbolic "===" is replaced with partition and CPU number. | CA JCS | AA |
| dynamcpu | CA Dynam/D "@" CPU number | JCS | A |
| (##) | CA Dynam/D "##" is replaced by increasing sequence characters (AA, AB, ..., ZY, ZZ). | CA JCS | ZY |
| HHMMSS | The current time | JES | 125959 |
| HR | The current hour | JES | 12 |
| JDAY | The current Julian day | JES | 364 |
| JOBID | The currently executing job ID | HCI | JOB12345 |
| JOBNAME | The currently executing job name | JES | MYJOB |
| LDATE | The current local (timezone) date |
JES | 16.12 |
| LDAY | The current local (timezone) day |
JES | 31 |
| LHHMMSS | The current local (timezone) time |
JES | 125959 |
| LHR | The current local (timezone) hour |
JES | 12 |
| LJDAY | The current local (timezone) Julian day |
JES | 364 |
| LMIN | The current local (timezone) minute |
JES | 59 |
| LMON | The current local (timezone) month |
JES | 06 |
| LSEC | The current local (timezone) second |
JES | 59 |
| LTIME | The current local (timezone) time |
JES | 125959 |
| LWDAY | The current local (timezone) weekday |
JES | 3 |
| LYR2 | The current local (timezone) 2-digit year |
JES | 16 |
| LYR4 | The current local (timezone) 4-digit year |
JES | 2016 |
| LYYMMDD | The current local (timezone) date |
JES | 161231 |
| MIN | The current minute | JES | 59 |
| MON | The current month | JES | 06 |
| SEC | The current second | JES | 59 |
| SEQ | An ever-increasing sequence number | JES | 10001 |
| STEPNAME | The currently executing step name | EBP | STEP01 |
| SYSALVL | The architecture level of the system (J for Java) | JES | J |
| SYSCLONE | Shorthand notation for the name of the system | JES | HC |
| SYSGID | The current group | JES | EBP |
| SYSNAME | The name of the system (see sysname) |
JES | HCIEBP |
| SYSPLEX | The name of the SYSPLEX | JES | HCIEBP |
| SYSR1 | The IPL Volume Serial name | JES | HCI001 |
| SYSUID | The current user | JES | EBP |
| TIME | The current time | JES | 03 |
| WDAY | The current weekday | JES | 3 |
| YR2 | The current 2-digit year | JES | 16 |
| YR4 | The current 4-digit year | JES | 2016 |
| YYMMDD | The current date | JES | 161231 |
Data Control Block Configuration
Data control block (catalog) information about datasets is managed by EBP in .dcb files within the directory containing that file. For database-based "files" (e.g., VDB or VSQL file formats), they are often obtained in the first datalib.1 configured directory. You can also save dataset-specific DCB information directly in the EBP configuration if, for example, it is not created by EBP jobs. A DEFAULT DCB setting applies to all existing dataset references by jobs' DD cards for which there is no .dcb file or catalog entry for that dataset. These are loaded on the configuration form on the Default DCB line. Set a specific dataset name (e.g., MYVSAM.DAT) or the word DEFAULT and select a DCB type followed by a value for that DCB attribute.
| DCB Attribute | Description | Values | Default |
|---|---|---|---|
| PROTOCOL | The file format protocol handler or external file handler to be used when accessing this file. | none — regular Java file; EC — Heirloom Computing ISAM; MF3 — Micro Focus IDX3 ISAM; MF8 — Micro Focus IDX8 ISAM; ACU — Micro Focus Acu v4 ISAM; VDB — Heirloom Computing ISAM file in a record-oriented database table; VSQL — Heirloom Computing ISAM file in a column-oriented database table; IBM — fixed length EBCDIC sequential record file with mainframe 4 byte record-descriptor-word; IBMV — variable length EBCDIC sequential record file with 4 byte RDW; IBMVB — variable length blocked EBCDIC sequential record file with 4 byte BDW and 4 byte RDW | none |
| ORGANIZATION | The file organization. | PS — Physical sequential; PO — Partitioned organization; GDG — Generation data group; VS — "VSAM" indexed sequential; TAPE — Tape sequential file | PS |
| ORIENTATION | The file orientation. | INDEXED — VSAM KSDS like (ISAM); NONINDEXED — VSAM ESDS like; LINEAR — VSAM ESDS like; RELATIVE — VSAM RRDS like; LINESEQUENTIAL — new line separated sequential records | LINESEQUENTIAL |
| RECORD FORMAT | The record format of the file. | V — Variable length records; F — Fixed length records; VB — Variable blocked; FB — Fixed Block | V |
| RECORD LENGTH | The (maximum or fixed) length of records in the file. | Any size | none |
| BLOCK SIZE | The block size (unit of buffering multiple records). | Any size | none |
| KEY OFFSET | The key offset for the first index on ISAM files. | 0 to record length | 0 (from IDCAMS) |
| KEY LENGTH | The key length for the first index on ISAM files. | record length − key offset | 64 (from IDCAMS) |
This is not a complete list of DCB entries, only the ones that can be set with the config Web service form. Any DCB attribute may be set by importing .dcb files.
DCBDB: Database-Backed DCB
When using DCBDB, a setting is added to the ebp.properties file to tell the COBOL runtime where to find the DCB configuration file. This avoids passing sensitive information (such as database credentials) on the java command line. See ebp.cobolconfig for the property that points to this file.
Example ebp.properties entry:
ebp.cobolconfig=/data/system/ebp.cobolconfigThe current implementation supports Table DCB only. Example DCB configuration file (using SQL Server):
dcb.db.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
dcb.db.pass=<password>
dcb.db.url=jdbc:sqlserver://111.22.33.444;databaseName=db_test
dcb.db.user=<user>
dcb.db.table=_06
dcb.mode.db=trueSecurity note: Ensure this configuration file has appropriate file-system permissions, as it contains database credentials.
The JDBC driver jar file corresponding to the Table DCB database must be present in a suitable location, for example in Tomcat's $CATALINA_BASE/lib directory. You may also need to add the driver to classlib.n.
Configuring Batch HourGlass
EBP has support for IBM HourGlass, which allows time simulation for batch jobs. The following parameters control the HourGlass integration. When active, HourGlass affects the time-related symbolics available to JCL.
| EBP Property Parameter | Description | Allowed values |
|---|---|---|
| ebp.hourglass.active | Controls the activation of the HourGlass system. | yes/no (Default: no) |
| ebp.hourglass.prefix | The prefix that the HourGlass dummy DD statements use as identifier. | Any two ASCII characters, e.g., HG (Default: empty) |
Once set up, you can configure your DD Dummy cards with the prefix and the HourGlass parameters.
Example with prefix "HG":
//HG095032 DD DUMMYSupport
For additional help:
- Review EBP logs with debug logging enabled (
errorlevelset to D) - See the RAC Configuration Guide for all security and LDAP settings
- Contact Heirloom Computing support with specific examples
0 Comments