Operation

This page describes how the SMA OpCon Unikix Connector runs Unikix BPE jobs, how JCL files are pre-processed, how steps are reported back to OpCon, and how return codes are handled.

What is it?

The Unikix Connector is the runtime component that OpCon invokes to submit a JCL job to Unikix BPE. The connector reads a property file, copies and pre-processes the daily JCL, reports JCL steps back to OpCon, runs the JCL through Unikix BPE, and returns a status to OpCon based on the Unikix job result.

For a higher-level description of the connector, see Overview. For installation and INI file details, see Installation.

Workflow at a glance

When OpCon submits a job to the connector, the connector runs the following phases in order:

#	Phase	Purpose
1	Parse the command line	Read the job name, class, date, JID, and optional restart step.
2	Read the property file	Load directory paths and logging settings from unikix_connector.properties.
3	Pre-process and tailor the JCL	Copy the daily JCL into EXEC_DIR and keep only the sections that match the JID.
4	Report steps to OpCon	Send up to 100 step names to OpCon so the job can be restarted on step.
5	Run the job on Unikix BPE	Submit the tailored JCL using unikixjob.
6	Copy history files	Move the matching Unikix log file into the class subdirectory under HISTORY_DIR.
7	Return the result	Return 0 on success, or 10 with the failed step name on failure.

JCL master and daily repository management

The Unikix server holds the source JCL files in a folder that acts as the master repository. Each day, an OpCon job that is set up separately copies all of the JCL files from the master repository to a daily repository.

:::note Daily repository naming The name of the daily repository is the DAILY_DIR value followed by an underscore and the run date in yy-MM-dd form. With DAILY_DIR=daily, a run on September 21, 2026 uses daily_26-09-21. The date passed with -d is used exactly as given, so it must be in the same form. :::

This pattern allows daily changes to the source JCL without affecting the master repository. When a job runs, the JCL file is copied into the directory used for submission, pre-processed, and then run on Unikix BPE.

All paths involved are configurable in the connector property file. See Installation for the parameter list.

Connector workflow

The following sections describe each phase of the connector workflow in detail. Some phases are dedicated to specific customer needs.

1. Parse the command line

The connector is invoked with the following command line:

unikix_connector.jar jobname [sma_restart=<step>] -c <arg> [-d <arg>] [-j <arg>] [-R <arg>]

The job name is also the name of the JCL file to be run. It must come first. The connector accepts at most one further value of this kind, and that value must begin with sma_restart=.

Argument	Required	Description
-c, --class <arg>	Yes	Class of the job. Allowed values: a, b, c, f, i, t.
-d, --date <arg>	No	Date in yy-MM-dd format. Defaults to today.
-j, --jid <arg>	No	JID number used to select sections of the JCL file.
-R, --restart-step <arg>	No	Starting step of the job. Ignored when sma_restart= is present.
sma_restart=<step>	No	Not an option but a second value after the job name. OpCon adds it automatically for a Restart on Step request. Takes precedence over -R.

:::caution Class names are case sensitive Use the lowercase letters a, b, c, f, i, or t for the -c argument. The connector rejects any other class name. :::

Restart options

A job can be restarted on a specific step in two ways:

• Use the OpCon Restart on Step action available in Enterprise Manager on a job that has already run at least once in the daily. OpCon adds sma_restart=<step> to the command line for you.
• Pass the -R option with the step name on the connector command line.

:::caution The two routes are not interchangeable

When sma_restart= is present, -R is ignored without a warning. A job definition that carries a permanent -R therefore has no effect on an Enterprise Manager restart, which will use the step selected in Enterprise Manager instead. The connector log records which route was taken.

:::

2. Read the property file

The connector requires a property file named unikix_connector.properties. The file must be placed in the same directory as the JAR file.

For the parameter descriptions and an example, see Installation.

3. Pre-process and tailor the JCL

The connector reads the JCL file from DAILY_DIR and writes the tailored copy into EXEC_DIR. Depending on the JID number, some sections of the file can be omitted.

The tailored file does not keep the original name. It takes the JCL file name padded with random characters to 14 characters — so PDRIC600 becomes something like PDRIC600a9_Q2x — and that name is what appears in the unikixjob command and in the Unikix log. The tailored file is deleted when the job returns 0 and left in place when it does not, so a failed job leaves its tailored JCL in EXEC_DIR for examination.

JID-specific sections are marked with the following statements:

Statement	Meaning
#JI,ID=1	Beginning of a section for JID = 1.
#JEND	End of a JID-specific section.

When the JID number matches, the lines between the markers are written to the output file. The #JI and #JEND statements are removed from the output.

:::caution Terminate every JID section with #JEND

#JEND is what re-enables output after a section that did not match. If a section is left unterminated, every remaining line in the file is dropped — including ENDJOB — and the tailored JCL is incomplete rather than merely reduced.

:::

Supported #JI syntax

Syntax	Match
#JI,ID=N	Matches integer N only.
#JI,ID=(N-M)	Matches integers between N and M inclusive. Parentheses are optional.
#JI,ID=(N,M)	Matches integer N and integer M only. Parentheses are optional.

Example: tailoring by JID

Given the input JCL below, the connector produces a different output for each JID value.

Input JCL:

BEGINJOB mode='MVS'
#JI,ID=1
EBMSYSCMD << !
echo "SCHID 1" >> /tmp/OPCON_test.log
!
#JI,ID=2
EBMSYSCMD << !
echo "SCHID 2" >> /tmp/ OPCON_test.log
!
#JEND
ENDJOB

Output when JID=1:

BEGINJOB mode='MVS'
EBMSYSCMD << !
echo "SCHID 1" >> /tmp/OPCON_test.log
!
ENDJOB

Output when JID=2:

BEGINJOB mode='MVS'
EBMSYSCMD << !
echo "SCHID 2" >> /tmp/ OPCON_test.log
!
ENDJOB

Output when JID does not equal 1 or 2:

BEGINJOB mode='MVS'

ENDJOB

4. Report steps to OpCon

A JCL file can contain steps. The connector reports each step back to OpCon during the job run using the sma_job_step program included in the bin folder of the OpCon Unix Agent. The daily job can then be restarted on a specific step from Enterprise Manager.

:::caution 100-step limit per job The connector reports a maximum of 100 steps per job. This limit was introduced in version 2.1.0 to stay within the 32,000-byte message limit between the OpCon Unix Agent and the OpCon SAM. :::

To report step number 3 named STEP030, the connector runs:

$SMA_BINDIR/sma_job_step 3 STEP030

How steps are identified in JCL

Statement	Purpose
LABEL name=STEPxxx	Marks a step in the JCL file.
EXECPROC procname='PROC' stepname='STEPxxx'	Calls a procedure. Steps inside the procedure are also reported.

Example: nested steps from a procedure call

Given the following JCL file:

BEGINJOB mode='MVS'
LABEL name=STEP010
EBMSYSCMD << !
echo "Begin job"
!
LABEL name=STEP020
EXECPROC procname='TESTPROC' stepname='STEP020'
LABEL name=STEP030
EBMSYSCMD << !
echo "End job"
!
ENDJOB

And procedure TESTPROC:

BEGINPROC procname='TESTPROC'
LABEL name=STEP010P
EBMSYSCMD << !
echo "Hello world"
!
LABEL name=STEP020P
ASSGNDD ddname='SYSUT1' filename='fileinput.txt' disp='i'
ASSGNDD ddname='SYSUT2' filename='fileoutput.txt' disp='o'
EXECPGM pgmname='IEBGENER' stepname='STEP020P'
ENDPROC

The following steps are reported to OpCon:

• STEP010
• STEP020
• STEP020.STEP010P
• STEP020.STEP020P
• STEP030

5. Run the job on Unikix BPE

After the JCL file is tailored, copied into EXEC_DIR, and the steps have been reported to OpCon, the tailored JCL is run on Unikix BPE.

The Unikix command used to start the job is:

cd <WORKSPACE> && unikixjob <tailored file> -c <class> -w -j

When a restart step was requested, -R <stepname> is appended:

cd <WORKSPACE> && unikixjob <tailored file> -c <class> -w -j -R <stepname>

Argument	Description
-c <class>	Class of the job.
-w	Waits for the job to complete before returning.
-j	Directs the job number to standard output so the connector can read it.
-R <stepname>	Restarts the job at the specified step. Present only when a restart step was requested.

The Unikix job number is captured from standard output of the unikixjob command. The connector matches the following regular expression to find the job number:

JOB (\d+):\s+Ready

The job number is then used to retrieve the Unikix job return code.

6. Copy history files

Unikix writes log files into UNIKIX_LOG_DIR. The connector copies these files to another location, configurable in the INI file as HISTORY_DIR, with one subdirectory per JCL class.

To find and move the history file for the job that was just run, the connector:

1. Browses the UNIKIX_LOG_DIR directory and looks for files whose names start with the job name.
2. Moves the last modified matching file into the HISTORY_DIR subdirectory for the job's class.

7. Return the result

The connector return code tells OpCon whether the Unikix job succeeded.

Connector return code	Meaning
0	unikixjob returned 0. The job succeeded.
1	An unexpected error. The connector writes the exception detail to the log.
2	The command line could not be parsed — an invalid or missing class, a missing job name, or too many values. The usage text is written to the log.
3	A required parameter is missing from the configuration file. The message names which of WORKSPACE, DAILY_DIR, EXEC_DIR, and PROC_DIR were not found.
4	The daily directory or the JCL file inside it does not exist. Check the daily repository name against Daily repository naming.
10	unikixjob did not return 0. The connector also writes the name of the failed step to standard output.

Codes 2, 3, and 4 mean the job never reached Unikix BPE. Code 10 means it ran and failed.

Identifying the failed step

To find the failed step in a Unikix job, the connector runs the Unikix lststs command. For example, for job number 512:

lststs -j512 -c

The connector parses each message in the response against three regular expressions. If a message matches one of the following conditions, the second word of that message is the name of the step that failed:

Match condition	Required third word
Message matches was executed.+COND-CODE=[^0][0-9]*$	MA2522
Message matches EBMSYSCMD.+Job Status : ABORT$	EBMSYSCMD
Message matches ASSGNDD.+Job Status : ABORT$	ASSGNDD

Example: in the output below, the second message matches the first condition, so step STEP01 is reported as the failed step:

PDRIC600(58) STEP01 MA2517 (I) starting step STEP01
PDRIC600(58) STEP01 MA2522 (I) was executed RETURN-CODE=9999 , COND-CODE=255

FAQs

Which JCL classes does the connector accept?

The connector accepts only the classes a, b, c, f, i, and t. Class names are case sensitive.

How are JID-specific sections of a JCL file handled?

The connector reads #JI markers in the JCL file and writes only the sections whose ID matches the JID passed on the command line. The #JI and #JEND markers are removed from the output JCL.

How many steps can the connector report per job?

The connector reports a maximum of 100 steps per job. This limit keeps the message between the OpCon Unix Agent and the SAM within the 32,000-byte limit. The 100-step limit was introduced in version 2.1.0.

How can a job be restarted on a specific step?

Use the OpCon Restart on Step action in Enterprise Manager for a job that has already run at least once in the daily, or pass the -R <stepname> option to the connector on the command line.

What return codes does the connector send to OpCon?

The connector returns 0 when the underlying unikixjob command returns 0, and 10 when it does not — writing the name of the failed step to standard output. It also returns 2 for a command line it cannot parse, 3 for a missing required parameter, 4 when the daily directory or JCL file is not found, and 1 for an unexpected error. Codes 2, 3, and 4 mean the job never reached Unikix BPE.

Glossary

Term	Definition
Unikix	A mainframe rehosting solution provided by Clerity Solutions (now Dell).
Unikix BPE	Batch Processing Environment. The batch platform within the Unikix solution that runs JCL files.
Class	Also called Unikix activity class. Identifies the class of a Unikix job. The connector accepts only a, b, c, f, i, and t, and the class name is case sensitive.
JID	Also called SCHID. An integer that determines which sections of the JCL file are run.
Procedure	A program run by a JCL file in Unikix.
Master repository	The folder on the Unikix server that holds the source JCL files.
Daily repository	A dated copy of the master repository that the connector uses for the day's runs. The folder name is the DAILY_DIR value followed by an underscore and the run date in yy-MM-dd form — for example daily_26-09-21.

Related topics:

• Overview
• Installation
• Release Notes