Generic_JCL_Script_Factory

Generic JCL script factory

JEM provides some JCL factories out-of-the-box which can use the script language as JCL (Bash, Windows CMD and Windows Powershell). To address specific customization necessary when the OOTB factories are not able to manage or if a specific script language is missing, JEM provides a generic JCL factories that the user can configure to execute own JCL based own customization.

How to configure

A generic JCl script factory must be configured inside of JEM environment configuration file where all JCL factories are defined. To add a custom JCL factory you should add the following configuration:

<factory className="org.pepstock.jem.ant.GenericScriptFactory">
	<properties>
		<property name="jem.generic.jcl.type" value="myps"/>
		<property name="jem.generic.jcl.type.description" value="My Powershell implementation"/>
		<property name="jem.generic.jcl.comment" value="#"/>
		<property name="jem.generic.jcl.tag" value="MY-JCL"/>
		<property name="jem.generic.jcl.mode" value="batchfile"/>
		<property name="jem.generic.command" value="powershell.exe -noninteractive -executionpolicy bypass -nologo -command '&amp;${script.file.name}'"/>
	</properties>
</factory>

The class name of the factory is a JEM class, org.pepstock.jem.ant.GenericScriptFactory. All properties available to configure the factory are the following:

Property Name	Description	Mandatory
jem.generic.jcl.type	you must set the type of JCL, assigning a unique tag to recognize the JCL type	Yes
jem.generic.jcl.type.description	you must set the description of JCL	Yes
jem.generic.jcl.comment	you must set the comment string used by the JCL language to insert comments. All metadata of JCL will be searched inside the comments of script	Yes
jem.generic.jcl.tag	you can define the main tag to use inside the comments to identify the JEM metadata part	No, default is JEM-[JCL type], in uppercase, if missing
jem.generic.jcl.mode	you can define the mode to show the JCL based on the script. Available tags are sh, batchfile, groovy, java, javascript, properties, text, textfile or xml	No, default is batchfile
jem.generic.command	you must define the command line to execute the JCL written on specific script language. You can use the variable ${script.file.name} which contains the absolute path of script to be executed	Yes

Special Tokens

All necessary information, which must be read by JEM to execute the script, are passed by comments inside the script. But JEM needs to be aware that what is managing is your JCL script file. For this reason, all metadata written as comment must be included in 2 token (XML like):

#
# <MY-JCL>
# jem.job.name=JOB-NAME
# jem.job.affinity=JOB-AFFINITY
# jem.job.user=JOB-USER
# </MY-JCL>
#
....
...

JEM is able to read all comments, reading and using all information between jem.generic.jcl.tag token. All properties are managed at row level, that means the JEM reads and interpret every line (not multi line properties). BE aware that JCL script file will be executed inside of ANT file.

Properties definition

To use JCL script file inside JEM, the file must contain the mandatory and optional properties that JEM needs, described in JCL Reference, as following:

• Job Name is optional string property, called jem.job.name . If missing, the file name will be used.
• Environment is optional string property, called jem.job.environment.If missing, the JEM node environment definition is used.
• Domain is optional string property, called jem.job.domain. If missing, default value (***) will be used.
• Affinity is optional string property, called jem.job.affinity. If missing, default value (***) will be used.
• User is optional string property, called jem.job.user. If missing, default value (null) will be used. An exception occurs if the user, who submitted the job, is not authorized to change the user job execution.
• Locking Scope is optional string property, called jem.job.lockingScope. If missing, default value (job) will be used. If the value is not equals to one the possible values (job, step , task), an exception occurs.
• Hold is optional boolean property, called jem.job.hold. If missing, default value (false) will be used.
• Priority is optional integer property, called jem.job.priority. If missing, default value (10) will be used (highest priority is 1).
• Memory is optional integer property, called jem.job.memory. If missing, default value (128) will be used. Be aware the unit is MegaBytes.
• Classpath is optional string property, called jem.job.classPath. Defining a classpath, it will be able to import ANT task definitions of 3rd parties. The value is a string and the files are separated by semicolons ;. If the file doesn't represent an absolute path, JEM will use relative position from jem.classpath folder. You could use variables that JEM substitutes in string value. If missing, default value (null) will be used. The paths will be added at the end of default classpath, build by JEM.
• Prior Classpath is optional string property, called jem.job.priorClassPath. Defining a classpath, it will be able to import ANT task definitions of 3rd parties. The value is a string and the files are separated by semicolons ;. If the file doesn't represent an absolute path, JEM will use relative position from jem.classpath folder. You could use variables that JEM substitutes in string value. If missing, default value (null) will be used. The paths will be added at the beginning of default classpath, build by JEM.
• Emails Notification is optional string property, called jem.job.emailsNotification. If missing, default value (null) will be used.

Here is the sample about the properties definition, in JCL script file (previous defined in the example) as comments:

#
# <MY-JCL>
# jem.job.name=JOB1
# jem.job.environment=ENV1
# jem.job.domain=domain
# jem.job.affinity=classA
# jem.job.priority=99
# jem.job.user=newUSER
# jem.job.lockingScope=task
# jem.job.hold=true
# jem.job.memory=1024
# jem.job.classPath=/test/ant-taskdefs-lib.jar
# jem.job.priorClassPath=/test/commons.jar
# jem.job.emailsNotification=m1@pepstock.org;m2@pepstock.org
# </MY-JCL>
#

Data Descriptions and Datasets in Generic JCL

Data descriptions and datasets are implemented by properties, together with all the other properties (between jem.generic.jcl.tag token). Data descriptions could be defined as following:

# <MY-JCL>
# ...
# jem.dataDescription.name-of-data-description=SYSOUT,DISP=NEW
# jem.dataDescription.name-of-data-description=DSN=datasetName,DISP=NEW/MOD/OLD/SHR
# jem.dataDescription.name-of-data-description=DSN=gdgName,DISP=NEW/MOD/OLD/SHR
# jem.dataDescription.name-of-data-description=DSN=@@temp,DISP=NEW
# ...
# </MY-JCL>

Data description needs a mandatory name, which must be inside of key name. All properties name for data descriptions, start with jem.dataDescription..

This name is used inside the JCL script file to access to datasets therefore this name must be unique in the task definition. The SYSOUT attribute is optional one that if there is means that the data description is a sysout. The DISP attribute is optional and must be a valid value, one of the following string enumeration: NEW, MOD, OLD or SHR.

Datasets could be defined as following:

DSN=dsn, DISP=NEW/MOD/OLD/SHR

Datasets could represent:

• file name (absolute or relative path), composed by properties if necessary. If it's a relative path, JEM adds the content of jem.data variable, used to identify the global file system with all data.
• GDG file name, following the same rules of a normal file name (see previous item).
• Temporary prefix file name
• if the text assigned to the property doesn't match with the abpve description, a INLINE file will be created, with the content of the property

Using data descriptions, the programmer is able to develop own job batch programs, avoiding strong references with physical files but logical ones, by environment variables. To reduce the risk to use variables already used on system, all variables names have DD_prefix.

Here is an example, how to access to data description:

# <MY-JCL>
# ...
# jem.dataDescription.INPUT=DSN=/gdg/jemtest(0),DISP=SHR
# jem.dataDescription.OUTPUT=DSN=/gdg/jemtest(+1),DISP=NEW
# ...
# </MY-JCL>

cp ${DD_INPUT} ${DD_OUTPUT}

Locks in Generic JCL

Locks are implemented by specific propertie. They could be defined as following:

# <MY-JCL>
# ...
# jem.locks=LABEL1, LABEL2
# ...
# </MY-JCL>

Lock names are defined a value, comma-separated, of a property named jem.locks. These names are used to create a lock inside the JEM environment in exclusive. This name must be unique in the task definition.