Using Tuxedo Job Enqueueing Service (TuxJES)

This chapter contains the following topics:

•

Overview

•	Configuring a TuxJES System

•	Using TuxJES

Overview

The batch job system is an important mainframe business application model. The Tuxedo Job Enqueueing Service (TuxJES) emulation application provides smooth mainframe application migration to open systems. TuxJES implements a subset of the mainframe JES2 functions (for example, submit a job, display a job, hold a job, release a job, and cancel a job).

TuxJES addresses the following batch job phases:

•

Input

•	Conversion

•	Processing

•

Purge

Requirements

TuxJES is an Oracle Tuxedo application; Oracle Tuxedo is required in order to run TuxJES.

A shared file system (for example, NFS) is required in order to deploy TuxJES in distributed environment.

TuxJES Components

TuxJES includes the following key components:

•	genjesprofile

Generates the security profile for Oracle Tuxedo applications

•	artjesadmin

TuxJES command interface. It is an Oracle Tuxedo client

•

ARTJESADM

TuxJES administration server. It is an Oracle Tuxedo server.

•	ARTJESCONV

TuxJES conversion server. It is an Oracle Tuxedo server.

•	ARTJESINITIATOR

TuxJES Job Initiator. It is an Oracle Tuxedo server.

•	ARTJESPURGE

TuxJES purge server. It is an Oracle Tuxedo server.

For more information, see the Oracle Tuxedo Application Runtime for Batch Reference Guide.

Configuring a TuxJES System

Setting up TuxJES as an Oracle Tuxedo Application

TuxJES is an Oracle Tuxedo application. Most of the TuxJES components are Oracle Tuxedo client or Oracle Tuxedo servers. You must first configure TuxJES as an Oracle Tuxedo application. The environment variable JESDIR must be configured correctly which points to the directory where TuxJES installed.

Oracle Tuxedo Configuration File

Listing 1 shows is an Oracle Tuxedo configuration file (UBBCONFIG) example segment for a TuxJES system.

Listing 1 Oracle Tuxedo UBBCONFIG File Example for the TuxJES System

*GROUPS

QG

LMID=L1 GRPNO=2 TMSNAME=TMS_QM TMSCOUNT=2

OPENINFO="TUXEDO/QM:/jes2queue/QUE:JES2QSPACE"

ARTG

LMID=L1 GRPNO=4

EVTG

LMID=L1 GRPNO=8

*SERVERS

DEFAULT:

CLOPT="-A"

TMUSREVT SRVGRP=EVTG SRVID=1 CLOPT="-A"

TMQUEUE

SRVGRP = QG SRVID = 1

RESTART = Y CONV = N MAXGEN=10

CLOPT = "-s JES2QSPACE:TMQUEUE -- -t 5 "

ARTJESADM SRVGRP =ARTG SRVID = 1 MIN=1 MAX=1

CLOPT = "-A -- -i jesconfig"

ARTJESCONV SRVGRP =ARTG SRVID = 20 MIN=1 MAX=1

CLOPT = "-A --"

ARTJESINITIATOR SRVGRP =ARTG SRVID = 30

CLOPT = "-A -- -c ABCDEFG

ARTJESPURGE SRVGRP =ARTG SRVID = 100

CLOPT = "-A --"

 

The following TuxJES servers should be included in the Oracle Tuxedo configuration file (UBBCONFIG):

•

ARTJESADM

•	ARTJESCONV

•	ARTJESINITIATOR

•	ARTJESPURGE

Note:

Multiple instances of ARTJESADM, ARTJESCNOV, ARTJESINITIATOR and ARTJESPURGE can be configured.

For the TuxJES administration server ARTJESADM, a TuxJES configuration file should be specified using the -i option. In the Oracle Tuxedo configuration file (UBBCONFIG), ARTJESADM should be configured in front of ARTJESCONV, ARTJESINITIATOR, or ARTJESPURGE servers.

For more, see the Oracle Tuxedo Application Runtime for Batch Reference Guide.

TuxJES uses the Oracle Tuxedo /Q component, therefore an Oracle Tuxedo group with an Oracle Tuxedo messaging server TMQUEUE with TMS_QM configured is required in the UBBCONFIG file. The name of the /Q queue space should be configured as JES2QSPACE.

TuxJES uses the Oracle Tuxedo Event component, therefore an Oracle Tuxedo user event server, TMUSREVT is required in the UBBCONFIG file.

A TuxJES system can be either an Oracle Tuxedo SHM application which runs on a single machine, or an Oracle Tuxedo MP application which runs on multiple machines.

For more information on how to set up Oracle Tuxedo application, see Oracle Tuxedo related documentation.

Block Time in UBBCONFIG for TuxJES

You can specify the number of timeout periods for blocking messages, transactions, and other system activities by setting the SCANUNIT and BLOCKTIME parameter. The value you assign must be a positive multiple of 5.

 

Table 1 Characteristics of the SCANUNIT and BLOCKTIME Parameters

Parameter	Characteristics
SCANUNIT	Controls the granularity of checking intervals and timeouts. SCANUNIT must be a multiple of 5 and between 0 and 60 seconds. Example: SCANUNIT 20 The default is 10.
BLOCKTIME	BLOCKTIME controls how much time can a message block before it times out. SCANUNIT * BLOCKTIME must not exceed 32767. The default time of SCANUNIT * BLOCKTIME is approximately 60 seconds.

Listing 2 Example Settings

*RESOURCES

IPCKEY 113333

DOMAINID jesdomain

MASTER SITE1

MODEL SHM

MAXACCESSERS 200

MAXSERVERS 50

NOTIFY SIGNAL

SCANUNIT 20

BLOCKTIME 50

 

In this example, sanity scans are performed in every 20 seconds and request block for no more than 20 * 50 = 1000 seconds.

Oracle Tuxedo /Q Queue Space and Queue Creation

A /Q queue space with name JES2QSPACE must be created for a TuxJES system. And some /Q queues should be created within this queue space. TuxJES provides a sample shell script (jesqinit) to create the queue space (JES2QSPACE) and the queues. For more information, see the Oracle Tuxedo Application Runtime Batch Reference Guide.

File System Configuration

TuxJES uses a file system to communicate with Batch Execution Engine. A directory is created on the file system for the communication between TuxJES and Batch Execution Engine. The name of the directory should be specified in the TuxJES configuration file. This directory should reside at a shared file system (for example, NFS) if you want to deploy the TuxJES system on multiple machines.

TuxJES Configuration File

A configuration file can be specified for the TuxJES administration server ARTJESADM. The following parameters can be configured in the configuration file:

JESROOT

The root directory to store job information. It is a mandatory attribute. If this directory does not exist, ARTJESADM creates it automatically.

DEFAULTJOBCLASS

The default job class if the job class is not set in JCL. It is an optional attribute. The default job class is A if this attribute is not set.

DEFAULTJOBPRIORITY

The default job priority if the job priority is not set in JCL. It is an optional attribute. The default job priority is 0 if this attribute is not set.

DUPL_JOB=NODELAY

If it is not set, only one job can be in execution status for a job name. NODELAY will remove the dependency check. The default value is delay execution.

EVENTPOST=S,C,E,P,L,A

Specifies whether events are posted for a job at particular stages.

S: Job submission event.

C: Job conversion complete event.

E:Job execution complete event.

P: Job purge event.

L: Job cancel completed event.

A: all supported events.

If EVENTPOST is not specified, no events are posted. The data buffer with event post is FML32 type and the fields are defined in tuxjes/include/jesflds.h.

JOBREPOSITORY

The path of the job repository where jobs are stored. The script file path inputted in job submitting may be a relative path in JOBREPOSITORY if it is set.

PRIVILEGE_MODE

Specifies whether and how to enable the user substitution (See TuxJES User Substitution). The values are:

NONE: Default value. Indicates jobs are executed by the OS user who starts JES system. This is compatible with all previous implementations on JES system.

USER_IDENTICAL: Indicates jobs are executed by the Oracle Tuxedo user with which JES client joins JES system. Make sure that each Oracle Tuxedo user corresponds to an existing OS user before you choose this value.

USER_MAPPING: When this value is specified, the JES system looks up the TuxJES user mapping file and finds out the OS user corresponding to the Oracle Tuxedo user with which JES client joins JES system, and then appoints this OS user as the job executor.

USER_MAPPING_FILE

The full path where TuxJES user mapping file is stored. It is used along with PRIVILEGE_MODE when its value is USER_MAPPING.

TuxJES Security Configuration

TuxJES leverages the Oracle Tuxedo security mechanism to implement authentication. If authentication is enabled, a security profile should be generated using the genapprofile utility and it should be used as a artjesadmin parameter to access the TuxJES system. The user used in the profile will be the job owner. A job only can be administrated by its owner, such as cancel, purge, hold and release. A job can be viewed by everybody. If a job is without owner, it can be manipulated by everyone.

Even if an Oracle Tuxedo application does not have security configured, the genjesprofile utility still can be used to enforce job owner permission checking and store the database connection MT_DB_LOGIN.

TuxJES User Mapping File

User mapping file is loaded and takes effect when PRIVILEGE_MODE value is specified to MAPPING_CREDENTIAL. It defines the mapping relationship between Oracle Tuxedo users and OS users. Every line in the mapping file is in the format as below:

tuxedousername OSusername

It is recommended that the owner of user mapping file is root and the file permission is "-rw-------".

Listing 3 shows a segment example of user mapping file for the TuxJES system.

Listing 3 User Mapping File Example For the TuxJES System

tuxedouser1 OSuser1

tuxedouser2 OSuser2

 

Using TuxJES

After the TuxJES system starts, you can use the artjesadmin utility to submit a job, hold a job, release a job, cancel a job, purge a job, display the job information, or subscribe event for job status change.

Submitting a Job

You can submit a job using the artjesadmin subcommand submitjob:

submitjob(smj) -i scriptfile

The scriptfile parameter is the job script to be submitted. The job script is generated by Oracle Tuxedo ART Workbench from a JCL.It can be an absolute path format, a relative path in the current working directory, or a relative path in JOBREPOSITORY if it is set. Its length is limited to 1023.

artjesadmin also supports direct job submission using the following format:
artjesadmin -i scriptfile

Submitting a Job in Synchronous Way

You can submit a job in synchronous way by using artjesadmin with the following format:

artjesadmin [-f [security_profile]] [-o ejr_option] [-s shell_option] [-y [-t timeout(s)]] -i scriptfile

Note:

To submit a job in synchronous way, in TuxJES Configuration File, it's required to set EVENTPOST=A; in UBBCONFIG file, it’s required to set NOTIFY to DIPIN and set server TMUSREVT.

-y and -t

Descriptions

Option -y and -t are added to submit a job in the synchronous way. Table 2 shows some details.

 

Table 2 Option -y and -t Descriptions

Option	Value Range	Descriptions	Notes
-y	N/A	Enables synchronous mode to wait for job end.	N/A
-t	1 ~ (2^31 -1)	Specifies the timeout value.	Optional. If -t is omitted, artjesadmin will wait infinitely. While timeout occurs, artjesadmin command line will exit but the job will run by JES continuously without impact.

Exit Code

Table 3 lists the exit codes for artjesadmin if -y is specified.

 

Table 3 Exit Code

Exit Code	Descriptions	Notes
0	Job is finished successfully.	N/A
1	Command execution fails.	The code will be returned by either invalid timeout value or a command line syntax error.
2	Job conversion fails.	Job is submitted successfully, but job conversion fails.
3	Job execution fails.	Job is submitted successfully, but job execution fails.
4	Job is canceled.	Job is submitted successfully, but is canceled before reaching final status.
20	Timeout occurs.	Job has not been finished within the time specified by -t option.

Standard Output

Information shown on Table 4 will be printed to stdout in the following format.

<JOBID>,<JOBNAME>,<JOBSTATUS>,<JOB RETURN CODE>

 

Table 4 Standard Output

Output Content	Descriptions	Sample
<JOBID>	Job ID	00005097
<JOBNAME>	Job name	JOBA
<JOBSTATUS>	Job final status (only available if job is finished before the timeout occurs)	DONE
<JOB RETURN CODE>	Job return code from EJR (only available if a job is finished before the timeout occurs)	C000

Listing 4 Sample: Job is Executed Successfully

00000002,JOBA,DONE,C0000

 

Listing 5 Sample: Job Fails

00000002,JOBA,FAILED,U0568

 

Listing 6 Sample: Timeout Occurs

00000002,JOBA,Already Timeout!

 

Displaying Job Information

You can display the information of a job or a series of jobs using the artjesadmin subcommand printjob:

printjob(ptj) -n jobname | -j jobid | -c job_class |-a [-v]

-n jobname: Display jobs with given job name

-j jobid: Display a particular job information

-c job_class: Display a particular class jobs information

-a: Display all jobs

-v: Verbose mode

The output of the printjob subcommand includes:

•	JOBNAME: The job Name

•	JobID: The Job ID generated by TuxJES system

•	Owner: The submission user of the job

•	Prty: Priority of the job

•	C: Job Class

•	Status: Job Status

EXECUTING: a job is running

CONVING: a job waiting for conversion

WAITING: a job waiting for execution

DONE: a job finished successfully

FAIL: a job finished but failed

HOLD_WAITING: a job is in hold state after conversion

HOLD_CONVING: a job is in hold state without conversion

INDOUBT: a job is in doubt state due to its initiator restarted

CANCELED: a job is canceled

•	Submit time: The submit time of the job

•	Step: The current running job step. It is only applicable to running jobs.

•	Type Run: The TYPRUN definition of the job.

•	Machine: Only for running/done/failed jobs. It is the machine name that the job is/was running on.

•	CPU usage: The user CPU usage and system CPU usage for the job execution.

•	Execution status: Job execution status.

•	Result: Job operation result, “OK” or error message.

Note:

If there are too many jobs in JES2 system, printing all jobs' status in console may lead to time out; to avoid this situation, users need to configure long enough block time in ubbconfig of JES.

For more information about how to set block time, please refer to Block Time in UBBCONFIG for TuxJES.

Getting Job Status in Synchronous Way

You can get job status in synchronous way by using artjesadmin with the following format:

artjesadmin [-f [security_profile]] -p -j jobid

-p and -j

Descriptions

Option -p and -j are added to get job status without interaction in artjesadmin console.

Exit Code

Table 5 lists the exit codes for artjesadmin if -p is specified.

 

Table 5 Exit Code

Exit Code	Descriptions	Notes
0	Job is finished normally. Job status = DONE	A job is finished successfully.
1	Command execution fails.	The failure is caused by an internal error, a network error, or a syntax error.
3	Job status = FAIL	JOB execution fails.
4	Job status = CANCEL	A job is canceled.
5	Job status = CONVING	A job is waiting for conversion.
6	Job status = EXECUTING	A job is running.
7	Job status = HOLD_CONVING	A job is in hold state without conversion.
8	Job status = HOLD_WAITING	A job is in hold state after conversion.
9	Job status = WAITING	A job is waiting for execution.
10	Job status = DISCARD	This status will occur if tpenqueue() fails.
11	Job status = INDOUBT	When a job is running, if JES server ARTJESINITIATOR is shutdown and then restarted, the job status will be INDOUBT.
22	Job doesn’t exist.	N/A

Standard Output

Information shown on Table 6 will be printed to stdout in the following format.

<JOBID>,<JOBNAME>,<JOBSTATUS>,<JOB RETURN CODE>

 

Table 6 Standard Output

Output Content	Descriptions	Sample
<JOBID>	Job ID	00005097
<JOBNAME>	Job name	JOBA
<JOBSTATUS>	Job current status	DONE
<JOB RETURN CODE>	Job return code from EJR (only available if a job has finished)	C000

Listing 7 Sample: Job has been Finished Normally

00000002,JOBA,DONE,C0000

 

Listing 8 Sample: Job is Finished but Fails

00000002,JOBA,FAILED,U0568

 

Listing 9 Sample: Job is Running

00000002,JOBA,EXECUTING

 

Holding a Job

You can hold a job or a series of jobs which are in CONVING or WAITING status using the artjesadmin subcommand holdjob:

holdjob(hj) -n job name | -j jobid | -c job_class | -a

-n jobname: hold jobs with given job name

-j jobid: hold a particular job

-c job_class: hold a particular class jobs

-a: hold all jobs

Releasing a Job

You can release a job or a series of jobs which are in HOLD_WAITING or HOLD_CONVING status using the artjesadmin subcommand releasejob:

releasejob(rlj) -n job name | -j jobid | -c job_class | -a

-n jobname: release jobs with given job name

-j jobid: release a particular job

-c job_class: release a particular class jobs

-a: release all jobs

Canceling a Job

You can cancel a job or a series of jobs using the artjesadmin subcommand canceljob:

canceljob(cj) -n job name | -j jobid | -c job_class | -a

-n jobname: cancel jobs with given job name

-j jobid: cancel a particular job

-c job_class: cancel a particular class jobs

-a: cancel all jobs

Purging a Job

You can purge a job or a series of jobs using the artjesadmin subcommand purgejob:

purgejob(pgj) -n job name | -j jobid | -a

-n jobname: purge jobs with given job name

-j jobid: purge a particular job

-a: purge all jobs

Completed jobs in the DONE or FAIL status are moved to the purge queue. For other jobs, purgejob has same effect as canceljob. The purgejob command does not purge the job directly. The ARTJESPURGE server deletes the job from the TuxJES system.

Displaying/Changing ARTJESINITIATOR Configuration

You can display the number of maximum concurrent executing jobs of an ARTJESINITIATOR server using the artjesadmin subcommand printconcurrent:

printconcurrent(pco) -g groupname -i serverid

-g groupname: the Tuxedo group name of the ARTJESINITIATOR server

-i serverid: the Tuxedo server id of the ARTJESINITIATOR server

You can change the number of maximum concurrent executing jobs of an ARTJESINITIATOR server using the artjesadmin subcommand changeconcurrent:

changeconcurrent(chco) -g groupname -i serverid -n concurrent_num

-g groupname: the Tuxedo group name of the ARTJESINITIATOR server

-i serverid: the Tuxedo server id of the ARTJESINITIATOR server

-n concurrent_num: the number of maximum concurrent executing jobs

Event Subscribing/Unsubscribing

You can subscribe or unsubscribe job status change event using the artjesadmin subcommand event:

event (et) [-t C,E,P,L,A] on|off

C: job conversion complete event

E: job execution finish event

P: job purge event

L: job cancel completed event

A: all supported events. If the event is set to "on", A is the default.

on |off: The submission is on or off. the "on" setting can be used with the -t option.

After subscribing to an event, you are notified on the artjesadmin console when the corresponding event is generated.

See Also

•	Oracle Tuxedo Application Runtime for Batch Reference Guide