Job Execution
This chapter describes processing mechanism and features of tjclrun, which is the runner that executes jobs. Additionally describes JCL parsing, job execution, and the outputs from job execution.
1. Overview
Job execution describes the process of running batch jobs in TJES. First, a user submits a job to the scheduler and then, after the job is successfully scheduled, the operating system executes the scheduled job. Job execution is carried out by tjclrun.
Each step of the job execution process is as follows:
-
Jobs are allocated (scheduled) to a specific Runner slot for execution according to a number of scheduling parameters, such as the job class, the schedule priority presented by the scheduler, and status of available Runner slots.
-
The Runner slot loads the required JCL into the job spool and invokes tjclrun.
-
tjclrun then executes the job as described in the JOB JCL received through the job SPOOL.
-
Once the job is complete, tjclrun reports the job’s results back to the Runner Slot and this result is stored in the JOBQ managed by TJES.
The user can review, delete or print the results of a job.
This chapter discusses the behaviours and features of tjclrun, a component for executing jobs. The JCL syntax and statements regarding this process are not discussed here. For information about JCL, refer to the mainframe’s JCL Reference Guide.
2. Executing a Job
When tjclrun is called to execute a job, it first performs some execution initialization processes, then parses the JCL files received from the job spool, and finally executes the job according to the results of the parsed JCL.
tjclrun processes each job step of a job described in a JCL file. Each job step is made up of a number of tasks, such as data set allocation or batch application execution.
After using the PGM parameter in the EXEC statement to execute a batch program specified in a job step, tjclrun monitors the program execution and periodically reports information about it while waiting for the program to terminate. tjclrun also sends SYSIN data set information to the program, receives the SYSOUT data set, and then writes it to the job spool. If the batch program terminates during a job step for whatever reason, tjclrun reports the termination result to TJES. Depending on the status given for the termination, tjclrun either proceeds to the next job step or stops the job when an exception condition is satisfied.
Once all steps specified in the JCL file (up to and including the last job step) are complete, tjclrun reports the job execution result to TJES, frees the resources allocated to the job execution process, including any allocated data sets, and then exits.
The following table lists the internal tasks in the job execution process.
| Task | Execution Process |
|---|---|
Execution |
|
Resource |
|
Control/Monitoring |
|
Miscellaneous |
|
2.1. Execution Initialization
The following mandatory resources require allocation before the Runner is called from the Runner Slot or SUBMITOR.
-
JOBID
-
Job entry in JOBQ
-
Runner slot
-
Job spool (INPJCL)
The following are the execution initialization steps.
-
Command Line Arguments
When tjclrun is invoked, the Runner slot parses command line arguments and extracts the JOBID, the location of the JCL file, and other parameters.
Normally, tjclrun is executed from TJES’s Runner slot. However, for debugging and other special purposes tjclrun can be executed from the shell. If tjclrun is executed independently of TJES, it is excluded from TJES’s job management system and may not execute all processes in order.
-
Reading Configuration File
Appropriate methods of executing tjclrun are determined by reading each section and key from the tjclrun subject in OpenFrame Configuration.
-
Execution Account
By default, when a job is executed, tjclrun processes are owned by any user who executes TJES. It means that if TJES is launched by the user 'obm', tjclrun and any batch application run through it will be run under the 'obm' user ID.
However, if the VALUE of the SETUID key is set to YES, in the ACCOUNT section from the tjclrun subject under OpenFrame Configuration, the tjclrun process can be executed by the USER specified in the JCL JOB statement. For more information, refer to setuid root tjclrun in Security.
-
SYSLIB Initialization
tjclrun tries to locate the applications specified in the job step from the directory path set in the SYSLIB section from the tjclrun subject under OpenFrame Configuration. If the SYSLIB section is not configured, the directory specified in the user’s environment variables is searched. If JCL contains JOBLIB DD or STEPLIB DD, SYSLIB is superseded by them.
Under certain Unix system settings, environment variables may be deleted when tjclrun is executed as root. Therefore, the SYSLIB section of the tjclrun subject in OpenFrame Configuration must be configured. Otherwise, tjclrun execution fails during operation of applications specified in JCL or while being loaded. For more information, refer to setuid root tjclrun in Security.
-
Opening SYSMSG DD
The SYSMSG log, located in a job’s spool directory, stores any results and errors regarding the tasks from a job that has been executed by tjclrun. tjclrun activates SYSMSG in the initialization stage (before starting the job) so that it can store internal log messages.
Two types of logs are stored in SYSMSG as follows:
-
tjclrun internal log: used for problem analysis in the case of an internal error or system function failure in tjclrun
To display the logs for analysing problems of tjclrun, the VALUE of the PROFILE key must be set to YES, in the DEBUG section from the tjclrun subject under OpenFrame Configuration.
-
stderr: displayed through the OpenFrame library
stderr, which is printed through the OpenFrame library and follows the general OpenFrame log format, has a different output format from SYSMSG.
-
-
Reporting Job Start
tjclrun reports to TJES when a job starts.
-
Opening Job Spool
tjclrun opens the job spool, which is used in the job execution process.
|
For more information about the tjclrun subject, refer to OpenFrame Configuration Guide. |
2.2. Input JCL Parsing
tjclrun first parses the JCL file (INPJCL) stored in the job spool and then executes the job. The JCL file and the job statement executed by tjclrun are collectively referred to as the job stream.
-
JCL Procedure Parsing
During the course of executing a job, tjclrun parses the JCL file multiple times. The INPJCL file that includes job statements is parsed and then executed sequentially. When a call is made to a JCL procedure, the procedure is parsed and then executed. After the JCL procedure has finished executing, tjclrun continues the execution of INPJCL.
-
JCLLIB/JOBPARM PROCLIB
tjclrun locates the JCL procedure in the JCL library (library and PDS data set) specified in the JCLLIB statement. In addition, any data set names (ddname) specified in the PROCLIB parameter of the JOBPARM command are searched for in the JCL libraries. If the correct library cannot be found, all libraries from the default system directory (SYS1.PROCLIB) are searched. If the correct library still cannot be located, the job exits with FLUSH status (abnormal exit).
If the JOBPARM command is specified in the INPJCL (job stream), the ddname in the PROCLIB parameter must already be configured with the key in the PROCLIB section of the tjes subject under the configuration table.
-
INCLUDE
When processing INCLUDE statements, the parser searches for the specified JCL in the JCLLIB and PROCLIB parameters of the JOBPARM command.
2.3. Execution Process
tjclrun parses the INPJCL (job stream) for a job and then executes the job steps in the order described in the JCL.
|
If a JCL job statement contains a RESTART parameter, the job step with this parameter is executed first. |
Execution Steps
Once parsing is complete, job is executed in two phases.
-
Lock phase
Locks the data set used by the target job.
-
Exec phase
Executes the job steps in order.
Prior to execution, tjclrun analyzes INPJCL and the JCL procedures to get a list of data sets used in the target job. Then, tjclrun requests locks on these data sets to prevent deadlock conditions, which occur frequently when multiple jobs simultaneously have exclusive use of the same data set.
Once all of the data set lock requests for a job have been accepted, the execution phase begins. The execution phase consists of two main steps.
-
EXEC PGM step
The EXEC PGM command allows job steps to execute a batch application. tjclrun executes the batch application as a child process and waits until the application terminates before continuing. Data set I/O statistics from the batch program are periodically reported to TJES.
-
EXEC PROC step
If a job step calls a JCL procedure using the EXEC PROC command, the JCL procedure is parsed and executed. It is possible to call another JCL procedure within the first; this is referred to as a nested JCL procedure call. A maximum of 15 levels of nesting are allowed. After executing a JCL procedure, control flow is returned to the parent job step of the EXEC call, which continues the job process.
Conditional Execution
Job steps can be conditionally executed using the following JCL commands.
-
EXEC COND
The COND parameter of an EXEC command allows for the conditional execution of an EXEC step based on the return codes of any of the previous steps. Depending on the previous step, TJES bypasses or processes that step.
-
JOB COND
The COND parameter of a job statement allows for the conditional execution of an EXEC step based on return code of the preceding EXEC step. If any argument in a COND statement tests as true, the job terminates.
The COND parameter of a job statement is not satisfied, the next job step is carried out.
-
IF-THEN/ELSE/ENDIF
These commands specify the conditions (IF-THEN / ELSE / ENDIF) for executing or terminating a job step.
2.4. EXEC PGM Processing
The most important task of tjclrun is to execute user-specified batch applications. Execution of user-specified batch applications by tjclrun consists of the following.
EXEC COND
Before processing the EXEC PGM step, any COND parameters in the EXEC statement are evaluated. If a return code from any step matches an EXEC COND, TJES bypasses that step.
The first job step of a job is always considered as being with a non-satisfying EXEC COND parameter.
If the EXEC COND parameter is not satisfactory, the job step (EXEC PGM step) is executed in the following order.
-
Report Step progress
Report the submission of the EXEC PGM step to TJES.
-
PGM Execution Privilege
If the batch application specified in the EXEC PGM step is a main utility, TACF verifies if the USER specified in the JOB statement holds the execute permission for the application. The privilege verification occurs only when the VALUE of the CHECK_UTAUTH key is set to YES, in the TACF section of the tjclrun subject under OpenFrame Configuration.
-
Step DD Allocation
The EXEC PGM step calls the batch application and the data set used in the batch application as specified by the DD statement. If the same DD is present more than once in a step, the subsequent occurrences is changed to another DD by tjclrun, preventing them from being executed in the batch application. After DD statements are processed, data sets are immediately allocated. Special DD statements at the job step level are processed at this point as well. STEPCAT DD and STEPLIB DD are examples of special DD statements.
-
PGM Parameter
PARM is a runtime parameter passed to a batch application specified by the EXEC PGM step. It is passed like a Unix application argument and can be read by the argv and argc libraries.
PARM values specified in an EXEC PROC command override the EXEC PGM PARM values defined in a JCL procedure.
-
Call/Execute
Use system functions to fork a batch application specified in the EXEC PGM step. In TJES, a batch application is executed as a child process of tjclrun. To do this, the child process is forked and then an EXEC command is used to launch the specified batch application.
-
SYSIN/SYSOUT Pipe
In OpenFrame, the SYSIN DD and SYSOUT DD used in batch applications are implemented in the same way as the stdin and stdout streams in standard Unix applications.
Basically, tjclrun can be seen as a wrapper for the execution of batch applications, by shell commands. In this sense, tjclrun reads the content of SYSIN DD and writes it to the stdin stream of the batch application. This allows batch applications to read the content of SYSIN from stdin.
Similarly, tjclrun reads data from a batch application’s stdout stream and outputs it to the SYSOUT DD of the target data set or the job spool.
By linking SYSIN DD and SYSOUT DD to Unix standard streams, UNIX applications can launch batch applications without having to interface with OpenFrame’s data set API.
-
The Unix stderr stream is also written to the SYSOUT DD’s stdout stream. stdout and stderr are both default output streams and since there is no DD specifically for the stderr stream, it also contains SYSOUT DD content.
-
tjclrun processes the SYSOUT DD and SYSPRINT DD from a JCL file in the same way. If a job step contains both of these statements, SYSOUT DD overrides SYSPRINT DD, which is ignored.
-
-
Report/Waiting Monitoring
tjclrun waits for the batch application specified in the EXEC PGM step to start and end, and periodically reports the number of data set I/O operations performed by the application.
-
Step DD Post Processing
Once a batch application from a job step terminates, any post-processing specified in the DISP (disposition) parameter of the DD statement is initiated, based on the value of the exit status.
If the batch application exits normally, the post-processing specified for a normal disposition is processed. However, if the application exits abnormally then the post-processing specified for an abnormal disposition is processed. The types of DISP are PASS, KEEP, CATLG, UNCATLG, and DELETE.
JOB COND
When a batch application exits, the returned exit status is compared with the defined job conditions (JOB COND). If they match (exception state), the job exits. Otherwise, the job proceeds to the next step.
Return Code check
After checking the JOB COND, tjclrun checks the return code from the completed batch program and decides whether to proceed normally with the next job step. If the return code is normal, execution proceeds as normal. However, if the return code is an error code, the relevant job step is terminated abnormally and any steps defined for the abnormal step condition (STEP COND) is executed instead. The two condition parameters for abnormal execution conditions are EVEN and ONLY.
|
Return codes are specified in the rc subject under OpenFrame Configuration. For more information, refer to OpenFrame Configuration Guide. |
2.5. EXEC PROC Processing
During the EXEC PROC step, tjclrun parses the procedures in a JCL file and then executes them in order. After executing the last step in a procedure, the return code is passed back to the job that called the JCL procedure and the next step of the job is processed.
An EXEC PROC step can be categorized according to where the content of the procedure is stored.
-
Input Stream Procedure (INSPROC)
The input stream procedure is called from the INPJCL, which stores the procedure.
-
Catalog Procedure (CATPROC)
The catalog procedure is a JCL procedure registered in the JCL library, which contains JCL procedures as members. When a catalog procedure is called, the procedures that are registered to a JCL library must be called with the 'PROC=procname' statement, where 'procname' is the member name. The PROCLIB library contains a number of JCL procedures; this library can be used by catalog procedures to call other JCL procedures.
When processing an EXEC PROC statement, tjclrun first searches for the specified procedure in INPJCL. If no procedure is found, tjclrun assumes that the procedure is a catalog procedure and searches all of the JCL libraries specified in the JCLLIB statement or the PROCLIB parameter of the JOBPARM command.
If the procedure is located in one of the JCL libraries specified in JCLLIB, the search is terminated and the remaining libraries are not searched.
However, if a search of the libraries specified in JCLLIB does not locate the procedure, tjclrun searches through the DD listed in the JOBPARM PROCLIB command. Note that the libraries specified in the JCLLIB statement take priority.
A ddname that can be specified in the JOBPARM PROCLIB=ddname option must be specified in the PROCLIB section of the tjes subject under OpenFrame Configuration. Multiple JCL library names can be specified in a single ddname, and in the similar way as JCLLIB, it can be configured to search for the specified procedures in order from earliest to latest in multiple JCL libraries.
|
2.6. DD Processing
tjclrun allocates data sets to batch applications launched from JCL DD statements. Generally, batch applications themselves do not allocate data sets; instead, they simply inherit the data sets allocated by tjclrun.
Data set allocation occurs when the batch application is launched in the EXEC PGM step. Once the batch application is executed, tjclrun performs post-processing on the allocated data sets. When tjclrun and the job terminate, the allocated data set is released.
Data set allocation varies according to the characteristics of the data set specified in the DD statement.
-
Normal Data Set
For most data sets, the data set name is specified in the DSNAME parameter. OpenFrame’s data set allocation module is used to allocate and make the data set available to applications. Allocated data sets are passed to the application’s environment.
-
SYSOUT Data Set
The SYSOUT data set contains a SYSOUT parameter in its DD statement. This data set is mainly used for storing job execution results in the job spool.
There is a difference between a data set with a ddname of SYSOUT and a DD statement with SYSOUT as a parameter; the latter describes the SYSOUT data set. The former is a normal data set with SYSOUT as a ddname. This is a commonly made mistake, since the SYSOUT data set is generally coded as 'SYSOUT DD SYSOUT=*'.
-
Temporary Data Set
A temporary data set is a data set with a name that begins with '&&' in the DSNAME parameter of the DD statement, or a non-SYSOUT data set with an unspecified DSNAME parameter. In the latter case, tjclrun internally assigns a unique name to the temporary data set. Temporary data sets are created when a job is executed and deleted when the job terminates.
Other than the temporary data sets specified by the user, tjclrun uses several temporary data sets for internal purposes, such as input stream data set.
-
Input Stream Data Set
The input stream data set is written as DD * or DD DATA format in the INPJCL (job stream).
tjclrun stores the input stream data set in the job spool and assigns it an internal data set name. Then, as with regular data sets, the OpenFrame data set processing module allocates the data set and allows the batch application to access it. The input stream data set is created as a temporary data set in the job spool directory so that it can easily be deleted when the job terminates.
-
2.7. Special DD
DD statements are coded in JCL as follows:
//ddname DD [parameters,...]
Special DD statements have a specific ddname with a special purpose in the system.
|
Users can only use a special DD’s ddname for special purpose tasks. |
TJES supports the following special DDs.
-
SYSIN DD
If the SYSIN DD statement is specified in a job step, tjclrun SYSIN reads the data set contents specified in the DD statement and sends the data to the stdin stream of the batch application executed in the job step. This allows applications to read the data set contents allocated by SYSIN DD.
-
SYSOUT DD/SYSPRINT DD
If the current job step specifies a SYSOUT DD or SYSPRINT DD instead of the batch application, tjclrun opens the data set. The batch application reads the data that was printed by the stdout and stderr streams and prints it to the data set opened by tjclrun. In this way, most of the applications, which directly display messages on to stdout or stderr without using the OpenFrame data set I/O functions, can be flexibly executed using JCL.
SYSOUT DD and SYSPRINT DD use the same semantics. If both of these DDs are defined, SYSOUT DD is used instead of SYSPRINT DD.
-
JOBLIB DD/STEPLIB DD
JOBLIB DD and STEPLIB DD specify the PDS data set (library path) that tjclrun uses to locate the batch applications specified in an 'EXEC PGM=pgmname' command.
Classification Description JOBLIB DD
The JOBLIB DD can be specified in the first EXEC statement in INPJCL. JOBLIB DD comes after the corresponding job step is specified within the EXEC statement. It specifies the PDS that the job step uses to call the corresponding program. Multiple PDS can be specified in the DD statement by using concatenation.
STEPLIB DD
It is located after the EXEC statement of the job step. Multiple PDS (library) can be specified in the DD statement by using concatenation. If STEPLIB DD is specified, tjclrun searches through the PDS library specified in STEPLIB DD for the batch program called in the job step. If STEPLIB is set, the JOBLIB DD command is ignored.
JOBLIB DD is used in a job step that contains no STEPLIB DD. If neither JOBLIB DD nor STEPLIB DD is specified, tjclrun searches for batch programs in the path specified in the SYSLIB section of the tjclrun subject under OpenFrame Configuration.
For more information about concatenation in JOBLIB or STEPLIB DD, refer to the mainframe’s JCL Reference Guide.
-
JOBCAT DD/STEPCAT DD
JOBCAT DD and STEPCAT DD specify the data set catalog that the job step uses. Multiple data set catalogs can be specified in either DD statement by using concatenation.
Classification Description JOBCAT DD
Must come after the job statement and before the first EXEC statement in the job stream. It specifies the default data set catalogs to be used by the job.
STEPCAT DD
Comes after the EXEC statement of a job step. It specifies the data set catalogs to be used by that particular job step.
If both JOBCAT and STEPCAT DDs are specified, STEPCAT takes precedence. If JOBCAT is specified but STEPCAT is not, JOBCAT is used by the job step. If neither DD is specified, the OpenFrame master catalog is used.
If JOBCAT or STEPCAT is specified, but the data set catalog is not cataloged, the master catalog is used to locate catalog information for the corresponding data set.
2.8. OUTPUT Processing
JCL OUTPUT is a JCL statement that is used to display the output method or to control the SYSOUT data set output generated by the job spool. One or more output statements can be used to set the type of output processing.
|
The parameters used in an OUTPUT statement can be set directly in a DD statement within the SYSOUT data set, instead of being set with the OUTPUT statement. However, as the original purpose of the DD statement is to avoid redundant output and refine output options, using the OUTPUT statement is a better choice. Additionally, some options that can be configured in an OUTPUT statement are unavailable for a SYSOUT DD statement. |
2.9. Job Spool
tjclrun uses the job spool during many of its job processing steps for various purposes. The data sets that tjclrun generates in the job spool and the purpose of each are as follows:
-
INPJCL
INPJCL is a JCL file that contains the job streams run by tjclrun.
Unlike other such files generated by tjclrun in the job spool, INPJCL is created as soon as the SUBMITOR (obmjmsvr) submits the job and makes the file available to tjclrun. The contents of INPJCL are identical to the JCL file the user has submitted.
-
CATPROC
CATPROC is a spool data set that stores the contents of the catalog procedures used during runtime as a part of job processing by tjclrun.
Since one job can call multiple catalog procedures, the contents of multiple catalog procedures are stored in CATPROC. These catalog procedures are stored in the order in which they were run, and a message that states whether or not a catalog procedure was called by the job step is concatenated to the beginning of each catalog procedure message.
-
INSDSET
INSDSET is a temporary data set that tjclrun creates in the job spool. tjclrun takes the input stream data from INPJCL (in the format described in the following.) to create the temporary data set in the job spool.
The following example configures an input stream data set.
//ddname DD * line1 line2 ... lineN /*
In this example, INSDSET is a temporary data set with the contents 'line1, line2…'. It is created for each job step and deleted once the job step is terminated. Such routines are called INSDSET SHUNT.
The record length is specified in the VALUE of the INSDSET_LRECL key in the DD section from the tjclrun subject under OpenFrame Configuration. This value can be from 1 up to 4096. If not specified, the default value is 80. If the input stream is shorter than the record length, the stream is padded with spaces. If longer than the default length, the excess data from the stream is discarded.
-
tjclrun executes INSDSET SHUNT to coherently process the concatenation of input streams. Since non-VSAM data sets can be concatenated with the input stream data set, shunting the extracted data sets from INPJCL allows the input data stream data set to be coherently concatenated using non-VSAM SDS concatenation logic.
-
For more information about how to configure INSDSET_LRECL, refer to "3.14.3.1. INSDSET_LRECL" in OpenFrame Configuration Guide.
-
-
JESJCL
JESJCL is a text formatted file containing the output from tjclrun parsing INPJCL, INSPROC, and other catalog procedures. It is generally used for debugging purposes.
-
JESMSG
The JESMSG data set in the job spool is output from the Runner slot when tjclrun terminates. It contains information about the job that was processed, including statistical data and information related to the job steps. It also contains summary information related to job processing; this information is important for the TJES system.
-
SYSMSG
SYSMSG is a log containing important messages related to tjclrun. It stores low level progress information, processing results, and any error messages raised during job processing. The contents of SYSMSG are recorded in chronological order based on specific operations or behaviors from jobs or job steps executed by tjclrun.
The contents printed in SYSMSG are as follows:
-
The name of the job step that is being processed
-
Information about the data sets allocated for the current job
-
Name and process identifiers (pid) of any external programs executed by tjclrun
-
The termination state of any such external programs
-
Commands processed by tjclrun
-
Success/failure of tjclrun processes
-
stderr messages from the OpenFrame library inside tjclrun
-
-
SYSOUT
SYSOUT data sets are DD statements that have the SYSOUT parameters shown in the following. Unlike other data sets, SYSOUT data sets are stored in the job spool and generally store output data.
The following example configures a SYSOUT data set.
//REPORT EXEC PGM=MONTHLY //SYSIN DD * 2007-07-01,2007-08-01 /* //SYSOUT DD SYSOUT=* //RPTOUT DD SYSOUT=* //RPTERR DD SYSOUT=*
While most of the data sets in the job spool are data sets required by TJES for job processing, SYSOUT data sets are additional, user-allocated data sets. Multiple data sets can be specified within a job or a job step. In the example above, for instance, SYSOUT, RPTOUT, and RPTERR are all SYSOUT data sets.
SYSOUT data set contents are printed from the batch program the user has specified. TJES does not add or remove information from the SYSOUT data set. TJES only manages the printer or the steps required for SYSOUT data set processing (depending on the output class setting).
2.10. Job Control
It is possible to suspend, resume, or stop (forcibly terminate) an active job after the scheduling step has finished. Such lower-level action controls for active jobs are referred to as JOB CONTROL. You can send control commands to any jobs initiated through user interfaces such as tjesmgr or the [Batch] menu in OpenFrame Manager.
|
For more information about how to use job control commands, refer to TJESMGR Commands and OpenFrame Manager User Guide." |
When job control commands are entered for any job executed by the user, they are processed in the following order.
-
If a user initiates a job control command for an active job, TJES sends a signal (SIGUSR1) to tjclrun.
-
When tjclrun receives the SIGUSR1, it determines the type of request (SUSPEND, RESUME, or STOP) that was made.
-
The appropriate signal (i.e. SIGSTOP, SIGCONT, or SIGKILL) is sent to all sub-processes.
-
A sub-process that received the signal is suspended, resumed or terminated according to the signal type.
-
After job control processing is finished for all sub-processes, tjclrun reports the results to TJES.
-
If tjclrun receives a SUSPEND signal, tjclrun sends the SIGSTOP signal to all of its sub-processes. If tjclrun receives a STOP signal, it terminates (exit) the processes. If the signal is RESUME, TJES sends the SIGCONT signal to tjclrun to resume the processes.
|
Since the job control of tjclrun is implemented using the job control signal (SIGSTOP/SIGCONT/SIGKILL) on a Unix system, if a different effective userid is used, an error may occur when sending a signal to the sub-processes because of insufficient privileges, and thus the job control can be limited. To avoid such occurrences and ensure successful job controls at all times, the system operator must grant the root access to tjclrun. For more information, refer to setuid root tjclrun in Security. |
2.11. Job-level Report
tjclrun reports various events to TJES while processing a given job. The information reported can be categorized into information that applies to the whole job and information that applies only to a specific job step.
The job-related information that tjclrun reports to TJES is as follows:
-
Job Start/Finish
tjclrun informs TJES of the start and end of jobs with the JOB START and JOB FINISH commands. If tjclrun terminates successfully, the event is reported to TJES. Upon termination of job, the termination state, termination code, and any return codes are sent to TJES.
-
Job Control State
TJES can suspend, resume, or stop a job that tjclrun is processing. After tjclrun has completed any job controls, it reports the current state of the job back to TJES.
-
Data Set Lock Standby
Before processing a job, tjclrun requests the data set lock to be used by the job. If tjclrun discovers that a requested data set has already been locked by another process, tjclrun sends the request to TJES and waits until the lock is released before proceeding with the current job. The system administrator can monitor these messages to identify which jobs are pending because of a lock on a required data set.
2.12. STEP-Level Report
The job step-related information that tjclrun reports to TJES is shown in the following.
-
STEP START/FINISH
tjclrun informs TJES of the start and end of each job step with the STEP START and STEP FINISH commands.
STEP START reports the step path (STEPPATH), which indicates the location in the job stream, and the type of job step (PGM or PROC) that is being executed. STEP FINISH also reports the state after termination, the termination code, and the time it took to process the job step.
-
Data Set Allocation
tjclrun allocates the data set required by the batch program before sending a batch program call. The data set to be allocated is specified in the JCL DD statements.
Since the data set allocation information is very important for OpenFrame, the ddname allocated by tjclrun and the name of the data set are written to two places: the SYSMSG log (located in the job spool) and the dsalc log (located in the OpenFrame log directory, OpenFrame_HOME/log).
-
Data Set I/O Reporting
tjclrun periodically reports statistics about the data set I/O processes of active batch programs. System administrators can use these statistics to monitor how many READ or WRITE commands occur during each job step.
2.13. Security
TACF Support
tjclrun supports the following two TACF security functions.
-
Verifying if the user holds the execute permission to run the program specified in EXEC PGM in a job step.
-
Verifying if the user holds the access permission to the data sets specified in DD statements.
In either cases, if the user has no permissions, the job is terminated abnormally.
|
For more information about TACF user rights and control of TACF users, refer to OpenFrame TACF Administrator’s Guide. |
TACF Surrogate User
Typically, to execute jobs with a specific user right, the USER (User ID) and PASSWORD parameters have to be specified in the job statement. However, if the PASSWORD parameter is saved as plain text and the JCL file is not protected in any way, security becomes compromised. To prevent this problem, TJES supports the surrogate user function. A surrogate user has the same access rights as an execution user, but does not require a password. When a surrogate user submits a job, the job is executed at the same authorization level as that of an execution user. The surrogate user can only submit jobs on behalf of the execution user; these submissions only work if the PASSWORD parameter is not specified.
|
For more information about specifying a surrogate user for job execution in TACF, refer to OpenFrame TACF Administrator’s Guide. |
setuid root tjclrun
In Unix systems, the 'setuid' flag is typically used to temporarily give elevated user privileges (such as root user) to a normal user for the purpose of making system calls to a file. This allows a normal user to execute a program file as the file’s owner. However, users that wish to execute programs through tjclrun must have execution privileges for those particular programs. Using the 'setuid root' flag allows the users to execute a specific program using root user access rights.
The process user mentioned here indicates effective userid of the Unix process. Regardless of the settings in the tjclrun configuration, tjclrun does not modify the 'real userid' information during the process execution. File and system resource authentication in Unix systems occurs only for users with valid userids.
The user information is used to identify the actual users who invoke processes. The user in this context is the operating system user (not a TACF user).
After installing OpenFrame TJES, but before assigning root user privileges to tjclrun, consider the following points.
-
If a batch program is run by two different effective user levels in Unix as a part of job control, and one effective user has insufficient user privileges, then tjclrun is unable to successfully finish the signal-based job control. In order to successfully run job control, the root execution privilege must be specified for tjclrun.
Such condition occurs only in very rare cases and can be resolved manually, which however could increase the work load for system administrators.
For example, this type of problem can occur when a user without the effective user privilege accesses a tjclrun process after modifying it using the setuid tool.
-
To run tjclrun and the job step procedures using the USER parameter of a job step, you must set the VALUE of the SETUID key to YES, in the ACCOUNT section from the tjclrun subject under OpenFrame Configuration as well as grant root user privileges to tjclrun. Root user privileges are necessary for using the command line interface to modify the user profile while the system process is running.
To avoid such limitations, the entire TJES system can be run using a root user privilege. However, this is not recommended for security and maintenance issues. Instead, tjclrun programs must be run with root user permissions by using the 'setuid root' flag (as shown in the following).
The following executes a 'setuid root' procedure.
$ cd $OPENFRAME_HOME/bin
$ su
$ chown 0:0 tjclrun
$ chmod u+s tjclrun
$ ls -l tjclrun
-rwsr-xr--x root system {size} {date-time} tjclrun
$ exit
In this example, the file permissions are set to -rwsr-xr--x and the user access right is set to root.
|
For more information, refer to "man chmod" and "man chown" in Unix User Guide. |
Once the program is initiated, tjclrun with root access can modify the process user by using the USER parameter in the program JCL. Only a limited number of tjclrun processes are run as root, while the majority of tasks are run as the USER specified by the JCL.
The 'setuid' flag and the tjclrun configuration settings are only necessary for job control commands and the invocation of other commands that directly control job processes.
|
In IBM AIX, if there are programs running that are affected by 'setuid root', the operating system removes the LIBPATH environment variable pointing to the shared libraries for security reasons. As a result, the shared library for OpenFrame products cannot be loaded if tjclrun is run after executing the 'setuid root' procedure. This problem can be resolved by installing tjclrun on the customer’s system and trying to re-link. This means that when programs search for required libraries, they rely not on the LIBPATH environment variable but on directories linked from previous link attempts. The IBM AIX operating system adheres to this policy to prevent the process, which has root permission, accessing system resources using their modified shared library. |
The following example re-links tjclrun in IBM AIX.
$ cd $OPENFRAME_HOME/bin $ cp tjclrun tjclrun.bak $ cc -q64 -brtl -o tjclrun.new ¥ > ./tjclrun ¥ > -L$OPENFRAME_HOME/lib -L$TB_HOME/client/lib -L$TMAXDIR/lib64 ¥ > -ljcl -licf -ldsio -lspool -ltjes -ljmcliout -lsms -lsaf ¥ > -ldsalc -lpgmdd -lams -lbinfmt -lofcom -llockm -lcli $ cp tjclrun.new tjclrun
After re-linking, follow the 'setuid root' procedures as previously described. The libraries that need to be linked by tjclrun ('-ljcl' to '-lcli' in the previous example) are included in OpenFrame products and can be retrieved by using the ldd tjclrun command.
In other Unix platforms (such as Linux, for example), trusted libraries can be registered, such as in the ld.so.conf. file. Using this configuration file, OpenFrame product-related libraries can also be made searchable - without creating any dependencies on environment variables that are related to shared library searching.
If tjclrun is installed after applying 'setuid root', the LIB_PATH, BIN_PATH key must be specified explicitly in the SYSLIB section of the tjclrun subject under OpenFrame Configuration. This setting is particularly necessary in a system such as IBM AIX where it becomes a required environment variable. Even if it is not, allowing tjclrun to only use the search paths specified in the SYSLIB section of the tjclrun subject under OpenFrame Configuration is better for security and system performance reasons. In this case, the permissions to modify the configurations of OpenFrame must be strictly controlled.
2.14. tjclrun Call
tjclrun is invoked with the following options.
TJES’s Runner slot is called together with options appropriate for the status of TJES at the time when the job execution was allocated.
tjclrun RUNMODE JOBID INITINDEX JOBSTREAM JOBPOS [keyword args ...]
Descriptions for each option of tjclrun are as follows:
| Option | Description |
|---|---|
RUNMODE |
JOB (normal run) or JEM (Job Emulation) test. |
JOBID |
Unique job ID (ex: JOBnnnnn). |
INITINDEX |
Runner slot index. |
JOBSTREAM |
Path of the job stream containing the JCL statements. |
JOBPOS |
Position of the job in the job stream. |
-
[keyword args]
RESTART=*|stepname|stepname.procstepname
Specifies the job step to restart.An asterisk (*) indicates the first job or process, stepname indicates the job step, and stepname.procstepname indicates the PROC step of stepname.procstepname.
tjclrun can be run directly from the shell command line. If it is, however, then job management steps, like submission and scheduling, are skipped.
2.15. PERFORM Processing through NICE
A parameter called PERFORM exists in JCL JOB and STEP statements. In mainframes, this parameter specifies a performance group for the job or job step; this performance group controls the CPU usage priority of the job or job step.
In UNIX, however, such a performance group does not exist. Instead, the users can control CPU usage priority with a process-based function called NICE. OpenFrame supports NICE by mapping it to the PERFORM parameter.
Whether to use the PERFORM parameter and mapping between PERFORM and NICE values can be specified by setting the key in the PERFORM section of the tjclrun subject under OpenFrame Configuration. For more information, refer to OpenFrame Configuration Guide.
|