The following Listing shows 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"
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

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

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
  

A /Q queue space with name JES2QSPACE must be created for a TuxJES system (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 for Batch Reference Guide

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.

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.

NJESUPPORT=ON

If it is not set, NJE support will be disabled and thus jobs cannot be run on the specified server group by Batch Runtime API m_JobSetExecLocation. The default value is OFF.

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.

JES_ACL_FILE

The full path of job access authorization configuration file. This file can be plain or encrypted, see JES_ACL_FILE_TYPE for more information.

JES_ACL_FILE_TYPE

The format of JES_ACL_FILE file. It can be set as PLAIN or ENCRYPTED (case insensitive). The default value is PLAIN.

JES_ACL_MODE

The action when no matching rule is found for the tuple of user, operation, and job in JES_ACL_FILE. It can be set as MAC (Mandatory Access Control) or DAC (Discretionary Access Control). The default value is MAC.

JOBLANG

JCL or KSH.

JCL: support JCL job, user can only submit JCL job.

KSH: support KSH job, user can only submit KSH job.

Not set: act as if KSH is set.

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.

You can specify multiple path names, delimit them with a colon (:). For example,JOBREPOSITORY=<path1>:<path2>:<path3>. To find job to submit, Batch Runtime searches from these paths in the order that you specify (in JOBREPOSITORY). When finding a job name match, Batch Runtime stops searching, and submits this matched job.

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.

USE_COBOL_SERVER

If it is set to Y, TuxJES COBOL server (ARTJESCOBOLDB2MF/ARTJESCOBOLDB2CIT) invokes user program; if it is set to N or if it is not set, TuxJES COBOL server does not invoke user program. USE_COBOL_SERVER configuration is only supported for JCL job in Database mode.

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.

USE_DB

ORACLE or DB2.

ORACLE: Use Oracle Database to store job management data.

DB2: (not supported) Use DB2 Database to store job management data.

Not set: Use /Q to store job information.

SYSLOG=OFF,ON,DAILY,WEEKLY,MONTHLY

OFF: Specifies no logs.

ON: Specifies writing to SYSLOG. Default value. The SYSLOG is entitled "jessys.log". You can change its path from the default "$JESROOT/jessys.log" to other directories by using SYSLOG_PATH.

DAILY: Specifies writing to SYSLOG. A new log file is created daily. The SYSLOG is entitled "jessys.log.<mmddyy>". For example, the SYSLOG entitled "jessys.log.032715" stands for the log file created for the day of March 27, 2015. You can change its path from the default "$JESROOT/jessyslog/jessys.log.<mmddyy>" to other directories by using SYSLOG_PATH.

WEEKLY: Specifies writing to SYSLOG. A new log file is created weekly. The SYSLOG is entitled "jessys.log.<mmddyy>", where the "dd" means the first day of current week (Sunday is the first day of the week). For example, the SYSLOG entitled "jessys.log.032215" stands for the log file created for the week from March 22, 2015 (Sunday) to March 28, 2015 (Saturday). You can change its path from the default "$JESROOT/jessyslog/jessys.log.<mmddyy>" to other directories by using SYSLOG_PATH.

MONTHLY: Specifies writing to SYSLOG. A new log file is created monthly. The SYSLOG is entitled "jessys.log.<mmddyy>", where the "dd" means the first day of current month. For example, the SYSLOG entitled "jessys.log.030115" stands for the log file created for the month of March 2015. You can change its path from the default "$JESROOT/jessyslog/jessys.log.<mmddyy>" to other directories by using SYSLOG_PATH.

SYSLOG_PATH

Specifies the path of SYSLOG files.

When SYSLOG=ON is set, you get the SYSLOG entitled "$SYSLOG_PATH/jessys.log" and located in the directory where you specify through this SYSLOG_PATH.

When SYSLOG=DAILY,WEEKLY,MONTHLY is set, you get the SYSLOG entitled "$SYSLOG_PATH/jessys.log.<mmddyy>" and located in the directory where you specify through this SYSLOG_PATH. The "jessys.log.<mmddyy>" confirms to the naming rules for SYSLOG=DAILY,WEEKLY,MONTHLY.

If you do not specify SYSLOG_PATH, the SYSLOG files are still located in $JESROOT/jessyslog (when SYSLOG is set to DAILY, WEEKLY, or MONTHLY) or $JESROOT (when SYSLOG is set to ON) by default.

QSPACE_THRESHOLD

Percentage: 1 ~ 99. This is a threshold value for queue space usage rate, while the usage of queue space reach this threshold, new job can be submitted but warning message will be shown in the output of artjesadmin. And auto purge will be performed if it isenabled. The default is 80.

AUTOPURGE

Integer number: 0 ~ 32767 (2^15-1).

0: Disable the automatic purging. Default value.

N(>=1): Enable the automatic purging and purge the first finished N Jobs one time.

If N>=(size of OUTPUT queue), all the jobs in OUTPUT queue are purged.

AUTOPURGE_KEEPFILES

ON: Backup folder <JESROOT>/<JOB_ID> to <JESROOT>/<JOB_ID>.bak while automatic purging, just delete the relevant message from "OUTPUT" queue.

If AUTOPURGE=0, this item is ignored. Default value.

OFF: Delete all the files belong to the job (in folder <JESROOT>/<JOB_ID>) while automatic purging.

JESROOT=/nfs/users/john_doe/jreroot
DEFAULTJOBCLASS=B
DEFAULTJOBPRIORITY=9
EVENTPOST=S,C,E,P,L,A
QSPACE_MAX_USAGE=80
AUTOPURGE=10
AUTOPURGE_KEEPFILES=ON

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

Based on this security mechanism, ART for Batch provides a lightweight job access authorization mechanism to control user's job operation actions. This authorization only needs simple configuration without involving any authorization server or even third-party security product. For more information, see Authorizing TuxJES Job Access.

User mapping file is loaded and takes effect when PRIVILEGE_MODE value is specified toMAPPING_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-------".

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

Listing 5 User Mapping File Example For the TuxJES System

tuxedouser1 OSuser1

tuxedouser2 OSuser2

• UBBCONFIG
  
• JESCONFIG
  

This section contains the following topics:

• Getting Database Credential
  
• Create Tables
  
• Set Up Database TAF for Oracle (Optional)
  

Do the followings to set up DB2 database:

• Getting Database Credential
  
• Creating Tables
  
• Managing Job in DB2
  

Do the followings to set up BDB database:

• Getting Database Credential
  
• Creating Tables
  

You can get job status synchronously by using artjesadmin in the following format:

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

-p and -j

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

Exit Code

The following table lists the exit codes for artjesadmin if -p.

Standard Output

Information shown in Table 5 is printed to stdout in the following format.

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

Listing 11 Sample: Job has been Finished Normally

00000002,JOBA,DONE,C0000

Listing 12 Sample: Job is Finished but Fails

00000002,JOBA,FAILED,U0568

Listing 13 Sample: Job is Running

00000002,JOBA,EXECUTING

• Set Warning Threshold for Queue Space
  

You can control ARTJESINITIATOR servers synchronously by using artjesadmin in the following format:

artjesadmin [-f [security_profile]] -x showjobexec|resumejobexec|stopjobexec [[lmid=machine|grpid=groupid|grpid=groupid,srvid=serverid];...]

-x showjobexec [[lmid=machine|grpid=groupid|grpid=groupid,srvid=serverid];...]:

Displays the number of executing jobs for all ARTJESINITIATOR servers, logical machine servers, servers by group id, or servers by group id and server id.

-x stopjobexec [[lmid=machine|grpid=groupid|grpid=groupid,srvid=serverid];...]:

Stops pick up of new jobs to execute for all ARTJESINITIATOR servers, logical machine servers, servers by group id, or server by group id and server id.

-x resumejobexec [[lmid=machine|grpid=groupid|grpid=groupid,srvid=serverid];...]:

Resumes pick up of new jobs to executefor all ARTJESINITIATOR servers, ogical machine servers, servers by group id, or server by group id and server id.

The JES_ACL_FILE file where you set rules can be plain or encrypted.

• Plain JES_ACL_FILE File
  
• Encrypted JES_ACL_FILE file
  

In terms of multiple matching rules, the first matching rule takes precedence. A matching rule means that the user, operation and job fields are all matched.

If no rule is found to match the user, operation and job, the configuration of JES_ACL_MODE in JESCONFIG file takes effect. If JES_ACL_MODE is not set, its default value JES_ACL_MODE=MAC takes effect, meaning that the operation is denied.

Listing 17 Example for Processing Rules

ALLOW; tpuser1;*;*

DENY; tpuser1;*; JOBA

Though the above two rules are both matching rules, the first matching rule takes precedence, meaning that user tpuser1 is authorized to operate on JOBA and the second matching rule does not take effect.

If you want user tpuser1 to operate all the jobs except for JOBA, exchange the sequence of the above two rules.

The lines (ignoring leading space) starting with character # are considered as comments. For example:

# This is comment

      # This is also comment.

ALLOW;tpuser1;*;JOBA:JOBB

Do not write comments right after the rule in the same line. For example, the #C in the following line is not considered as a comment.

ALLOW;tpuser1;*;JOBA:JOBB#C

The following are the list of examples:

• Example for Using Difference Ways to Set Rules
  
• Example for Using Wildcards to Set Rules
  
• Example for Using JES_ACL_MODE
  

You should set environment variable JESTRACE before running Batch Runtime. Once you set JESTRACE, it will set the TuxJES trace message level of all TuxJES clients and servers that your UBBCONFIG SERVERS section specifies.

For more information about JESTRACE, see Setting Environment Variables.

You can dynamically change TuxJES trace message level, using artjesadmin command:

artjesadmin [-f [security_profile]] -x settracelevel [trclvl=trace_level[,[lmid=machine|grpid=groupid|grpid=groupid,srvid=serverid];...]]

You can also use artjesadmin sub command:

settracelevel(stl) -t tracelevel [-n machine] | [-g groupid [-i serverid]]

The parameter trclvl and -t can be set as 0, 1, 2, or 3. 0 indicates ERROR level; 1 indicates WARN level; 2 indicates INFO level; 3 indicates DEBUG level.

If none of the machine, groupid, and serverid parameter is specified, the artjesadmin will change the TuxJES trace message level of the current client and all servers that your UBBCONFIG SERVERS section specifies. Once you specify one or more parameters, the artjesadmin will only change the TuxJES trace message level of the servers that you specifies; the current client will not be changed.

• Example A:Change TuxJES trace message level to DEBUG for the current client and all servers that your UBBCONFIG SERVERS section specifies. You can use artjesadmin command as Listing 20 or use artjesadmin sub command as Listing 21.
• Example B: Change TuxJES trace message level to ERROR for the TuxJES servers which are running on SITE1 machine. You can use artjesadmin command as Listing 22 or use artjesadmin sub command as Listing 23
• Example C: Change TuxJES trace message level to INFO for all TuxJES administration servers that belong to group 1. You can use artjesadmin command as Listing 24 or use artjesadmin sub command as Listing 25
• Example D: Change TuxJES trace message level to INFO for a TuxJES administration server; this server belongs to group 1, and its server ID is 1. You can use artjesadmin command as Listing 26 or use artjesadmin sub command as Listing 27

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

Listing 20 Example A: artjesadmin Command

artjesadmin -x settracelevel trclvl=3

Listing 21 Example A: artjesadmin Sub Command

artjesadmin

settracelevel -t 3

Listing 22 Example B: artjesadmin Command

artjesadmin -x settraceleveltrclvl=0,lmid=SITE1

Listing 23 Example B: artjesadmin Sub Command

artjesadmin

settracelevel -t 0 -n SITE1

Listing 24 Example C: artjesadmin Command

artjesadmin -x settracelevel trclvl=2,grpid=1

Listing 25 Example C: artjesadmin Sub Command

artjesadmin

settracelevel -t 2 -g 1

Listing 26 Example D: artjesadmin Command

artjesadmin -x settracelevel trclvl=2,grpid=1,srvid=1

Listing 27 Example D: artjesadmin Sub Command

artjesadmin

settracelevel -t 2 -g 1 -i 1