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:

•	genappprofile

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.

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,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.

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.

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 Tuxedo application has not security configured, the genappprofile utility still can be used to enforce job owner permission checking.

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.

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

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

•	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.

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

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.

Event Subscribing/Unsubscribing

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

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

S: job submission event

C: job conversion complete event

E: job execution finish event

P: job purge 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