Tuxedo Job Enqueueing Service (TuxJES)

This chapter contains the following topics:

TuxJES Servers, Commands, and Utilities

TuxJES Job Operation

TuxJES Servers, Commands, and Utilities

This chapter describes servers, commands, and utilities included in the TuxJES feature.

Table 1 lists TuxJES commands and functions.

 

Table 1 TuxJES Servers, Commands and Utilities

Name	Description
genjesprofile	Generates the security profile for TuxJES system
genjesacl	Generates the encrypted job access authorization configuration file for TuxJES system
gensysprofile	Generates file to encrypt and store TuxJES Database connection information
artjesadmin	TuxJES command interface.
artjescleanlock	Cleans stale lock records in lock files in MP mode.
ARTJESADM	TuxJES administration server.
ARTJESCONV	TuxJES conversion server.
ARTJESINITIATOR	TuxJES job control API.
ARTJESPURGE	Purges job queue.
ARTJESCOBOLDB2MF	Invokes user programs (compiled by Micro Focus COBOL) that can access to DB2.
ARTJESCOBOLDB2CIT	Invokes user programs (compiled by COBOL-IT COBOL) that can access to DB2.
TuxJES Queue System	TuxJES Queue system.
TuxJES User Substitution	Defines the specific OS user to execute jobs
TuxJES Trace Message Control	Controls TuxJES Trace Messages

genjesprofile

Name

genjesprofile – Generates the security profile for TuxJES system

Synopsis

genjesprofile [-f userprofile]

Description

genjesprofile generates the TuxJES system security profile. When genjesprofile is launched, you are prompted to enter the Oracle Tuxedo application password, user name, user password, the database connection string for MT_DB_LOGIN, the database connection string for MT_GDG_DB_ACCESS, the database connection string for MT_DB_LOGIN2, and the database connection string for MT_CATALOG_DB_LOGIN, and the ftp password for MT_FTP_PASS.

The output is a security profile file that contains the Oracle Tuxedo application password, user name, user password, the database connection string for MT_DB_LOGIN, the database connection string for MT_GDG_DB_ACCESS, the database connection string for MT_DB_LOGIN2, and the database connection string for MT_CATALOG_DB_LOGIN with the file permission -rw-------, and the ftp password for MT_FTP_PASS.

Note:

The generated security profile file can be used by the artjesadmin tool to login to an Oracle Tuxedo domain.

Parameters and Options

genjesprofile supports the following parameters and options:

[-f <output_file>]

The location of the generated security profile file. If this option is not specified, the default value is ~/.tuxAppProfile.

See Also

artjesadmin

genjesacl

Name

genjesacl - Generates the encrypted job access authorization configuration file for TuxJES system.

Synopsis

genjesacl [-f <output_file>]

Description

genjesacl reads plain rules from STDIN line by line until EOF (pressing Ctrl+D at the beginning of the line in terminal can produce EOF), and then generates an encrypted configuration file. It must be used when JES_ACL_FILE_TYPE=ENCRYPTED is specified.

The generated encrypted configuration file can be used by the ARTJESADM tool to authorize TuxJES job access.

Parameters and Options

genjesacl supports the following parameters and options:

[-f <output_file>]

The location of the encrypted rule file that genjesacl generates. If this option is not specified, the default value is ~/.jesAclEncrypted.\

See Also

ARTJESADM

gensysprofile

Name

gensysprofile – Generates file to encrypt and store TuxJES Database connection information.

Synopsis

gensysprofile -d <JESROOT>

Description

gensysprofile generates file to encrypt and store TuxJES Database connection information.

Parameters and Options

gensysprofile supports the following parameters and options:

-d <JESROOT>

Specifies JESROOT directory, where this file is to be generated.

artjesadmin

Name

artjesadmin – TuxJES command interface.

Synopsis

•	artjesadmin -v

•	artjesadmin [-f [security_profile]]

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

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

•	artjesadmin [-f [security_profile]] [-t timeout(s)] [-o ejr option] [-y] -i|-I scriptfile

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

•	artjesadmin -f [security_profile] -x setjesacl aclfile=rulepath[,aclfiletype=PLAIN|ENCRYPTED[,aclmode=MAC|DAC]]

Description

artjesadmin is the TuxJES command interface.The TuxJES system must be started first.

Parameters and Options

artjesadmin supports the following parameters and options:

-h

Option -h prints artjesadmin usage information as listed above.

-v

Option -v indicates the current version of Oracle Tuxedo Application Runtime for Batch.

-f

The security profile file generated by genjesprofile. The default value is ~/.tuxAppProfile. It requires the owner of the security profile must be the user who runs artjesadmin. The user name in this profile is the owner of the submitted jobs. A job without a specified owner is assigned the owner name "*".

A job with a particular owner can only be controlled by that owner. A job without a particular owner (*) can be controlled by anyone. Any user can print all jobs.

Note:

•	If -f profile is specified, the specified profile file will be used;

•	If -f is specified while profile is not, ~/.tuxAppProfile will be used as the profile file;

If -f is not specified, nothing will be used as the profile file.

-p and -j

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

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

 

Table 2 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 does not exist.	N/A

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

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

 

Table 3 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 1 Sample: Job has been Finished Normally

00000002,JOBA,DONE,C0000

 

Listing 2 Sample: Job is Finished but Fails

00000002,JOBA,FAILED,U0568

 

Listing 3 Sample: Job is Running

00000002,JOBA,EXECUTING

 

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

Option -x is specified to control ARTJESINITIATOR servers. It must be showjobexec, resumejobexec, or stopjobexec. For more information, see Sub Commands.

-t <timeout>

Option -t <timeout> is specified to control the timeout threshold when submitting a job in synchronous mode, asynchronous mode, or console mode. With -t option, an integer can be specified to control the timeout. If no timer is specified, clients will wait forever.

•	In synchronous mode, the timer is used to wait for the job (from submission to execution) to finish.

•	In asynchronous mode or console mode, the timer is used to wait for the job (submission only) to finish.

-T

Option -T is specified to submit a job in test mode, which only do checks rather than executing this job. For more information about test mode, see -t file|NULL argument in EJR Syntax.

-o <Job Execution Engine Options>

-o can be used to pass special options to the job execution engine. If the job is in KSH, the options are passed to KSH execution engine; if the job is in JCL, the options are passed to native JCL execution engine.

•	Available options for KSH Execution Engine are listed as follows.

-o “-f <envfile>”

Specifies full path of the environment file that includes environment variables for the current job. It must conform to syntax of shell script. In this file, environment variables should be set with “export <KEY>=<VALUE>” or “<KEY>=<VALUE>;export <KEY>”.

•	Available options for JCL Execution Engine are listed as follows.

-o “-e <envfile>”

Specifies full path of the environment file that includes environment variables for the current job. It must conform to syntax of “<KEY>=<VALUE>” format.

-y

Option -y is added to submit a job in the synchronous way. This option enables synchronous mode to wait for job end.

Note:

To submit a job in synchronous way, in TuxJES Configuration File, you must set EVENTPOST=A.

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

 

Table 4 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.

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

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

 

Table 5 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!

 

-i

Option -i is specified to submit KSH jobs. scriptfile should be full path or relative path to APPDIR environment variable, or to JOBREPOSITORY configuration item.

-I

Option -I is specified to submit JCL jobs. scriptfile should be full path or relative path to APPDIR environment variable, or to JOBREPOSITORY configuration item.

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

Option -x settracelevel is specified to set the TuxJES trace message level. For more information, see Sub Commands.

-x setjesacl aclfile=rulepath[,aclfiletype=PLAIN|ENCRYPTED[,aclmode=MAC|DAC]]

Option -x setjesacl is specified to change job access authorization. For more information, see Sub Commands.

Sub Commands

artjesadmin supports the following sub commands:

submitjob (smj) -i|-I scriptfilename [-t timeout] [-o ejr option]

Submits a job to TuxJES system. The scriptfilename parameter is the job script to be submitted.

Note:

artjesadmin is not responsible for scriptfile propagation. It must be located on a shared file system if the conversion and execution are not on same machines. The options are as follows:

•	-i scriptfilename: The option specified to submit KSH jobs.

•	-I scriptfilename: The option specified to submit JCL jobs.

•	-t timeout: Specifies to control the timeout threshold when submitting a job.

•	-o ejr option: Specifies the options passed to the EJR script file. For example, -f ejr option (-o "-f envfile") can be used to pass an environment file to KSH job; -e ejr option (-o "-e envfile") can be used to pass an environment file to JCL job.

showjobexec(she) [-n machine] | [-g groupid [-i serverid]]

Display the number of executing jobs of ARTJESINITIATOR servers.If no option is specified, display the number of executing jobs of all ARTJESINITIATOR servers.

-n machine:

The Tuxedo logic machine name that the ARTJESINITIATOR server is running on.

-g groupid:

The Tuxedo group id of the ARTJESINITIATOR server.

-i serverid:

The Tuxedo server id of the ARTJESINITIATOR server.

stopjobexec(ste) [-n machine] | [-g groupid [-i serverid]]

Stops ARTJESINITIATOR servers from picking up a new job to execute; the server continue finishing current jobs. If no option is specified, all ARTJESINITIATOR servers stop picking up new jobs.

-n machine:

The Tuxedo logic machine name that the ARTJESINITIATOR server is running on.

-g groupid:

The Tuxedo group id of the ARTJESINITIATOR server.

-i serverid:

The Tuxedo server id of the ARTJESINITIATOR server.

resumejobexec(rse) [-n machine] | [-g groupid [-i serverid]]

Resume ARTJESINITIATOR servers pick up of new jobs to execute. If no option is specified, all ARTJESINITIATOR servers resume picking up new jobs.

-n machine:

The Tuxedo logic machine name that the ARTJESINITIATOR server is running on.

-g groupid:

The Tuxedo group id of the ARTJESINITIATOR server.

-i serverid:

The Tuxedo server id of the ARTJESINITIATOR server.

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

Set the TuxJES trace message level of TuxJES client and server.

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.

-t tracelevel:

Specify the TuxJES trace message level parameter. -t tracelevel 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.

-n machine:

Specify the Tuxedo logic machine which the TuxJES server is running on.

-g groupid:

Specify the Tuxedo group which the TuxJES server belongs to.

-i serverid:

Specify the Tuxedo server ID of the TuxJES server.

setjesacl (sja) -f rulepath [-t PLAIN|ENCRYPTED] [-m MAC|DAC]

Dynamically change job access authorization. Only the Oracle Tuxedo user who is mapped to (or identical with) Unix/Linux root (referred to as super user) can use this sub command.

-f rulepath:

Specify the path of job access authorization configuration file. Its usage is just likes JES_ACL_FILE in JESCONFIG.

-t PLAIN|ENCRYPTED:

Specify the rule file is encrypted or not. If not specified, use the default value PLAIN. Its usage is just likes JES_ACL_FILE_TYPE in JESCONFIG.

-m MAC|DAC:

Specify the action when no matching rule is found for the user. If not specified, use its default value MAC. Its usage is just likes JES_ACL_MODE in JESCONFIG.

Error(s)

Once successfully invoked, the return format Job xxx is submitted successfully. If an error occurs, an error message is printed.

artjesadmin also supports direct job submission using the following format: artjesadmin [-o='xxx'] -i/-I scriptfile.

artjesadmin has a return code different from zero if there is an error occurs as listed in Table 6.

 

Table 6 Error Codes

Code	Description
0	No runtime error
251	artjesadmin it self command error returned by ARTJESADM server
252	JES2SUBMIT service error
Others	EJR none zero exit code

Printing

printjob(ptj) -n jobname | -j jobid | -c job_class |-a [-v][-t JCL|KSH][-m] | -l

Displays the existing jobs. If no option is specified, it displays all jobs. The options are as follows:

-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

-t JCL|KSH: Display JCL|KSH jobs

-m: Print the CPU time usage of each step in one JOB

-l: Display the number of jobs for each job class in each job status type

Note:

-l option is not supported when you use /Q to store and manage metadata of Batch jobs.

Listing 7 printjob Output

> ptj -a

JOBNAME JobID Owner Prty C Type Status

-------- -------- -------- --------- ------ --------

cjob 00000015 * 5 A KSH DONE

cjob 00000016 * 5 A KSH DONE

cjob 00000018 * 5 A KSH CONVING

 

total:3

success:3

 

•	JOBNAME: The job name.

•	JobID: The job ID generated by TuxJES system

•	Type: the job type (JCL or KSH)

•	Owner: Job Owner.

•	Prty: Job priority

•	C: The 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

In verbose mode, the job detail information is displayed:

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

If no option is specified, the "-a" option is assumed.

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

Hold the specified jobs which are in CONVING or WAITING status. The options are as follows:

-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

If no option is specified, the "-a" option is assumed.

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

Releases the jobs in HOLD_WAITING or HOLD_CONVING status so that they can be picked up by ARTJESCONV for conversion or ARTJESINITIATOR for running. The options are as follows:

-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

If no option is specified, the "-a" option is assumed.

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

Cancels a job and moves it to the output queue. For running jobs, this command informs the related ARTJESINITIATOR to invoke EJR with "-k" option. Other jobs are moved directly to the output queue. The TuxJES system assumes the job is terminated when EJR returns. The options are as follows:

-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

If no option is specified, the "-a" option is assumed.

purgejob(pgj) -n job name |-j jobid | -c job class | -s job status | -a

Completed jobs in the output queue 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. If ARTJESPURGE is not started, the job remains in the output queue.

The options are as follows:

-n jobname: Purge jobs with given job name

-j jobid: Purge a particular job

-c job class: Purge jobs with given job class

-s job status: Purge jobs with given job status

-a: Purge all jobs

If no option is specified, the "-a" option is assumed.

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

Changes the number of maximum concurrent executing jobs for the ARTJESINITIATOR server which is designated by the -g and -i options. The change takes effect with no need to restart the ARTJESINITIATOR server.

The options are as follows:

-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

The change is not persistent, which means the number is reset when the ARTJESINITIATOR server restarts.

printconcurrent(pco) -g groupname -i serverid

Displays the number of maximum concurrent executing jobs for the ARTJESINITIATOR server which is designated by -g and -i options.

The options are as follows:

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

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

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

This command tells artjesadmin to subscribe particular job event. The options are:

C: job conversion complete event; the event name is ARTJES_JOBCVT

E: job execution finish event; the event name is ARTJES_JOBEXEC

P: job purge event; the event name is ARTJES_ARTJESPURGE

L: job cancel completed event; the event name is ARTJES_JOBCANCEL

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. "off" will unsubscribe all event subscriptions.

If the subscribed event type is not configured in JESCONFIG, an error is reported.

verbose(v) on|off

Turn on /off verbose mode.

See Also

Oracle Tuxedo Application Runtime for Batch User Guide

artjescleanlock

Name

artjescleanlock – The utility to clean stale lock records in lock files in MP mode.

Synopsis

artjescleanlock -c [-y] [-h <hostname>] [-f <filefullpath>]

artjescleanlock -l [-h <hostname>] [-f <filefullpath>]

Description

Artjescleanlock, based on the filter criteria specified by its options, is used to list or clean lock records in lock files. Before running this utility, environment variable MT_ACC_FILEPATH must be set properly.

Parameters and Options

artjescleanlock supports following options:

-l

Specifies the users want to just list or display the lock records matching the specified filter criteria.

-c

Specifies the users want to clean the lock records matching the specified filter criteria.

Note:

One and only one of “-l” and “-c” must be set; they are exclusive to each other.

[ -h hostname ]

Optional: It specifies a hostname as the filter criteria. Only lock records matching such hostname are impacted.

[ -f filename ]

Optional: It specifies a filename as the filter criteria. Only lock records matching this filename are impacted.

Note:

If no filter criteria are supported, all lock records will be impacted.

[-y]

Optional: It specifies whether the users want to forcibly clean the lock records without confirmation. Without “-y”, the utility will ask for users’ confirmation before cleaning. This option can only be used with “-c”.

ARTJESADM

Name

ARTJESADM – TuxJES Administration server.

Synopsis

ARTJESADM

SRVGRP=”identifier”

SRVID=”number” CLOPT=” [-A][servopts options] -- -i JESCONFIG”

Description

ARTJESADM is an Oracle Tuxedo application server provided by TuxJES. The artjesadmin command communicates with ARTJESADM for most tasks.

ARTJESADM must be configured in the UBBCONFIG file in front of other TuxJES servers since others they access services provided by ARTJESADM. If JESCONFIG is changed, all TuxJES related servers must be restarted for new configurations to take effect.

Parameters and Options

ARTJESADM supports the following parameters and options:

-i JESCONFIG

JESCONFIG represents the full path name of the TuxJES system configuration file. It allows the following parameters:

JESROOT

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

JESROOT=/xxx/xxx

DEFAULTJOBCLASS

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

DEFAULTJOBCLASS=[A-Z],[0=9]

DEFAULTJOBPRIORITY

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

DEFAULTJOBPRIORITY=[0-15]

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. Event name: ARTJES_JOBSUBMIT

C: Job conversion complete event. Event name: ARTJES_JOBCVT

E: Job execution finish event. Event name: ARTJES_JOBFINISH

P: Job purge event. Event name: ARTJES_JOBPURGE

L: Job cancel completed event. Event Name: ARTJES_JOBCANCEL

A: All supported events.

If EVENTPOST is not specified, no events are posted. The data buffer with event pos is FML32 type and the fields are defined in JESDIR/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.
Because the JESCONFIG file and JES_ACL_FILE file are based on TuxJES security mechanism, it's important to well protect these two files at the very beginning. It is strongly recommended that read/write permissions for these two files should be granted to only the user who is responsible for booting the whole TuxJES domain (normally it is the root account).

JES_ACL_FILE_TYPE

The format of JES_ACL_FILE file. It can be set as PLAIN or ENCRYPTED (case insensitive). PLAIN means JES_ACL_FILE file is plain while ENCRYPTED means this file is encrypted. The encrypted file can be generated by genjesacl tool. 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 or DAC. MAC (Mandatory Access Control) means all operations are denied if no matching rule is found while DAC (Discretionary Access Control) means all operations are allowed if no matching rule is found. MAC is the default value. If JES_ACL_MODE is configured to invalid values, server ARTJESADM cannot boot up.

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 ( For more information, see JuxJES User Substitution in Oracle Tuxedo Application Runtime for Batch Reference Guide). 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.

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

One Oracle Tuxedo user must be mapped to one OS user only, and it is recommended that one OS user is mapped to one Tuxedo user as well.

USE_DB

Enable to use Database to store job management data. Values could be:
ORACLE: Use Oracle Database to store job management data.
DB2: Use DB2 as storage to store job information.
BDB: Use BDB as storage to store job information.
NOT SET: Use /Q to store job information.

Example(s)

UBBCONFIG example:

ARTJESADM

SRVID=1 SRVGRP=SYSGRP CLOPT="-A -- -i /nfs/users/jes/jesconfig"

See Also

Oracle Tuxedo Application Runtime for Batch User Guide

ARTJESCONV

Name

ARTJESCONV – TuxJES conversion server.

Synopsis

ARTJESCONV

SRVGRP=”identifier”

SRVID=”number” CLOPT=” [-A][servopts options] -- ”

Description

The TuxJES conversion server. It is responsible for invoking the EJR to do the job conversion.

Example(s)

UBBCONFIG example:

ARTJESCONV

SRVID=2 SRVGRP=SYSGRP CLOPT="-A -- "

See Also

Oracle Tuxedo Application Runtime for Batch User Guide

ARTJESINITIATOR

Name

ARTJESINITIATOR – Job Initiator

Synopsis

ARTJESINITIATOR

SRVGRP=”identifier”

SRVID=”number” CLOPT=” [-A][servopts options] -- -C jobclasses [-n concurrent_num] [-d]”

Description

ARTJESINITIATOR is an Oracle Tuxedo application server provided the TuxJES. It is responsible for invoking the EJR to execute the jobs.

Once a ARTJESINITIATOR is killed or shutdown while it has job running, it will put the job in the INDOUBT state when it is restarted.

Parameters and Options

ARTJESINITIATOR supports the following parameters and options:

-c jobclasses[jobclass]

Specifies the job classes this ARTJESINITIATOR server is associated. If this option is not specified, ARTJESINITIATOR associates with all job classes.

-n concurrent_num

Specifies the number of maximum concurrent executing jobs for this ARTJESINITIATOR server. The default value is 1.

-d

Specifies the number of maximum concurrent executing jobs for this ARTJESINITIATOR server can be change by artjesadmin changeconcurrent command.

Example(s)

UBBCONFIG example:

ARTJESINITIATOR

SRVID=3 SRVGRP=SYSGRP MIN=10 CLOPT="-A -- -c AHZ"

In this example, ten ARTJESINITIATOR instances are configured and are associated with the "A","H" and "Z" job classes.

See Also

Oracle Tuxedo Application Runtime for Batch User Guide

ARTJESPURGE

Name

ARTJESPURGE – Purges job queue

Synopsis

ARTJESPURGE

SRVGRP=”identifier”

SRVID=”number” CLOPT=” [-A][servopts options] -- ”

Description

ARTJESPURGE monitors the purge queue. If it finds a job in the purge queue, it removes the job in the queue and deletes the directory JESROOT/<JOBID>.

See Also

Oracle Tuxedo Application Runtime for Batch User Guide

ARTJESCOBOLDB2MF

Name

ARTJESCOBOLDB2MF – TuxJES COBOL server for invoking user programs (compiled by Micro Focus COBOL) that can access to DB2

Synopsis

ARTJESCOBOLDB2MF

SRVGRP="identifier"

SRVID="number" CLOPT=" [-A][servopts options] -- [-m cobol_mode]"

Description

ARTJESCOBOLDB2MF is a TuxJES COBOL server for invoking user programs (compiled by Micro Focus COBOL) that can access to DB2. Do the followings to configure Oracle Tuxedo for accessing DB2 database.

1.	Set environment variable for DB2 (DB2DIR and the like).

2.	Add a definition for DB2 Connect to the Tuxedo resource manager definition file ($TUXDIR/udataobj/RM).

3.	Use the following command line to build TMS_UDB: buildtms -o $JESDIR/bin/TMS_UDB -r UDB_XA.

4.	Set up the Tuxedo configuration file to reference the DB2 server. In the *GROUPS section of the UBBCONFIG file, add an entry like this:

UDB_GRP LMID=simp GRPNO=3

TMSNAME=TMS_UDB

TMSCOUNT=2 OPENINFO="UDB_XA:db=sample,uid=username,pwd=password,tpm=tuxedo"

Parameters and Options

ARTJESCOBOLDB2MF supports the following parameters and options:

-m cobol_mode

Specifies user COBOL program invocation/cancel method (Micro Focus COBOL only). Environment variable "JES_COBOL_MODE" can also be used to control it. Table 7 lists its variable values; the default value is MF_SUBSYS. If both ARTJESCOBOLDB2MF -m option method and JES_COBOL_MODE method are used, ARTJESCOBOLDB2MF -m option takes precedence.

 

Table 7 JES_COBOL_MODE Variable Values

Value	Description
MF_SUBSYS	Use SUBSYSTEM method.
MF_COBFUNC	Use COBFUNC method.
MF_DEFAULT_CANCEL	Use cobcall with default CANCEL behavior.
MF_PHYSICAL_CANCEL	Use cobcall with physical CANCEL behavior.
MF_LOGICAL_CANCEL_STANDARD	Use cobcall with logical CANCEL behavior. Physically cancel .dll code and shared object code as part of a logical cancel operation.
MF_LOGICAL_CANCEL_SPECIAL	Use cobcall with logical CANCEL. Do not physically cancel .dll code and shared object code as part of a logical cancel operation.
MF_NOCANCEL	Use cobcall without CANCEL behavior.

Example(s)

UBBCONFIG example:

ARTJESCOBOLDB2MF

SRVGRP= UDB_GRP SRVID=1 CLOPT = "-A --"

ARTJESCOBOLDB2CIT

Name

ARTJESCOBOLDB2CIT – TuxJES COBOL server for invoking user programs (compiled by COBOL-IT COBOL) that can access to DB2

Synopsis

ARTJESCOBOLDB2CIT

SRVGRP="identifier"

SRVID="number" CLOPT=" [-A][servopts options] -- "

Description

ARTJESCOBOLDB2CIT is a TuxJES COBOL server for invoking user programs (compiled by COBOL-IT COBOL) that can access to DB2. Do the followings to configure Oracle Tuxedo for accessing DB2 database.

1.	Set environment variable for DB2 (DB2DIR and the like).

2.	Add a definition for DB2 Connect to the Tuxedo resource manager definition file ($TUXDIR/udataobj/RM).

3.	Use the following command line to build TMS_UDB: buildtms -o $JESDIR/bin/TMS_UDB -r UDB_XA.

4.	Set up the Tuxedo configuration file to reference the DB2 server. In the *GROUPS section of the UBBCONFIG file, add an entry like this:

UDB_GRP LMID=simp GRPNO=3

TMSNAME=TMS_UDB

TMSCOUNT=2 OPENINFO="UDB_XA:db=sample,uid=username,pwd=password,tpm=tuxedo"

Example(s)

UBBCONFIG example:

ARTJESCOBOLDB2CIT

SRVGRP= UDB_GRP SRVID=1 CLOPT = "-A --"

TuxJES Queue System

In order to emulate the z/OS JES2 system, TuxJES system uses a queue mechanism for batch job life cycle management. All queues are created in one queue space called "JES2QSPACE". A batch job is represented by a message that resides and is transferred to queues listed in Table 8.

 

Table 8 TuxJES Queues

Queues	Description
JCL Conversion Queue	When a JCL job is submitted to the TuxJES system, it is put in the JCL conversion queue first. There is only one JCL conversion queue in the system. A JCL converted job is moved from the "JCL conversion queue" to the "conversion queue". The jobs in the queue are processed in FIFO order. Queue name: CONV_JCL
Conversion Queue	When a batch job is submitted to the TuxJES system, it is put in the conversion queue first. There is only one conversion queue in the system. A converted job is moved from the "conversion queue" to the "execution queue". The jobs in the queue are processed in FIFO order. Queue name: CONV
ExecGroup Queue	This queue is necessary if NJESUPPORT is enabled in jesconfig file. This queue maintains the mapping of each job and its execution group when the job is in the Execution Queue. Queue name: EXECGRP
Hold Queue	If a job is in the HOLD state (JCLHOLD or HOLD), it is put in the hold queue. Once released, it is moved to the conversion queue or waiting queue based on the typrun parameter. Queue name: HOLD
Execution Queue	There are 36 job classes (A-Z and 0-9). A job also has a priority value ranging from 0 to 15. The jobs are scheduled based on the job class and priority. One job class is mapped to one /Q queue, (36 queues all together). These are the queues where the job is stored staying and waits for execution. The job priority is mapped to the queue message priority. All queues are created based on priority. Queue names: [A-Z], [0-9].
Executing Queue	This queue stores running/executing jobs. There is only one "executing queue" in the system. When a job is picked up from an "execution queue" and successfully goes to running state, the job is moved to the "executing queue". The jobs in this queue are processed in FIFO order. Queue name: EXEC
Output Queue	When a job is completed or an error occurs, it is sent to the "output queue". There is only one "output queue". The jobs in the queue are processed in FIFO order. Queue name: OUTPUT
Purge Queue	When a job is to be purged, it is moved to the purge queue. There is only one "purge queue" in the system. Queue name: PURGE
Internal Queues	ART JES also has some internal queues on the JES2QSPACE for internal usage.

The TuxJES Queue Creation Script

The TuxJES system provides a sample shell script (jesqinit) to create the queue space (JES2QSPACE) and the queues listed in Table 8. You can modify the script to adapt to your environment, but must adhere to the following:

5.	Queue order can not be changed

6.	Fixed queue names and queue space name

7.	The script can be customized for queue space/queue creation parameters

Recommended /Q Creation Values

Device Size of Pages: 10000

Queue Space Size of Pages: 5000 (We assume the max number of jobs is 10000, each job will consume 2k bytes and the page size is 4k)

Number of Messages in Queue: 10000

Number of Concurrent Transactions: 1000

Number of Concurrent processes in queue: 100

Recommended queue space size: 4K x (number of jobs per day) x (days jobs stay in JES queues before being auto purged)

Note:

These parameters can be customized according to the specific environment.

TuxJES User Substitution

JES supports defining the specific OS user to execute jobs. With the Tuxedo User-OS User mapping mechanism, JES system is able to associate the Tuxedo AAA credential adhering to a job with an OS user who has the limited permission to access resources when operating a job.

Terms

Table 9 lists the terms you need to know for a good understanding of the user substitution feature described in this section.

 

Table 9 User Substitution Terms

Term	Description
Job submitter	The OS user who submits a JES job with artjesadmin
Job owner	The Oracle Tuxedo user who is displayed as the owner of a JES job
Job user	The OS user who submits, cancels or prints a JES job with artjesadmin
Job executor	The OS user who executes the EJR to execute a JES job

Job Owner Designation in Different Scenarios

The Job owner designated by JES system depends on the combination of configurations on artjesadmin and PRIVILEGE_MODE. Table 10 shows the relation between job owner designation and different configuration scenarios.

 

Table 10 Job Owner Designation in Different Configuration Scenarios

Configuration Scenario		Job Owner
When artjesadmin is executed with...	When PRIVILEGE_MODE is set to...
a profile containing a user name	NONE	Oracle Tuxedo user
a profile containing a user name	USER_IDENTICAL or USER_MAPPING	Oracle Tuxedo user Note: Oracle Tuxedo SECURITY parameter must be set to USER_AUTH, ACL or MANDATORY_ACL, otherwise JES system fails to start up and the following error message is printed into ULOG: "ERROR: The current Tuxedo security level disallow the given privilege mode".
no profile or a profile containing no user name	NONE	* A job with an owner “*” can be controlled by anyone.
no profile or a profile containing no user name	USER_IDENTICAL or USER_MAPPING	artjesadmin fails to login and the following error message is displayed: "ERROR: failed to join application."

Permissions of Job Operations

Table 11 and Table 12 show the permissions of users with different identities when operating jobs in TuxJES system enabling the user substitution.

 

Table 11 Permissions of Job Operations When PRIVILEGE_MODE is set to "USER_IDENTICAL"

User	Permission
Oracle Tuxedo user "root"	print, hold, release, cancel, purge, and control jobs
Owner of the job	print, hold, release, cancel, purge, and control jobs
Oracle Tuxedo users who have the read and execution permissions to the corresponding job directory	print jobs

 

Table 12 Permissions of Job Operations When PRIVILEGE_MODE is set to "USER_MAPPING"

User	Permission
Oracle Tuxedo user who is mapped to OS user "root"	print, hold, release, cancel, purge, and control jobs
Oracle Tuxedo user who is mapped to job executer	print, hold, release, cancel, purge, and control jobs
Oracle Tuxedo user who is mapped to a OS user with read and execution permissions to the corresponding job directory	print jobs

Enabling User Substitution in TuxJES

To enable the user substitution in TuxJES, the following operations should be done:

•	Configuring JESCONFIG in TuxJES

•	Booting Up JES System by Root User

•	Configuring Tuxedo UBBCONFIG

•	Configuring File System Permission

Configuring JESCONFIG in TuxJES

The value of PRIVILEGE_MODE in JESCONFIG should be specified to MAPPING_CREDENTIAL or IDENTITY_CREDENTIAL.

If the value of PRIVILEGE_MODE in JESCONFIG is MAPPING_CREDENTIAL, the value of USER_MAPPING_FILE should be specified and the user mapping file should contain the mapping between Oracle Tuxedo users and OS users.

Booting Up JES System by Root User

When JES is working in SHM mode, it should be booted up by root user.

When JES is working in MP mode, do one of the following:

•	Execute tmboot by root when JES system is running on the master machine of a MP domain.

•	Execute tlisten by root when JES system is running on a slave machine of a MP environment.

It is recommended that all machines involved in a JES system use the same NIS system.

Configuring Tuxedo UBBCONFIG

All job users should have full permissions to IPC resource of the JES system.

The SECURITY parameter in RESOURCE section of TUXCONFIG should be USER_AUTH, ACL or MANDATORY_ACL.

Note:

If SECURITY parameter is set to APP_PW and AUTHSVC parameter is configured, the SECURITY level is regarded as USER_AUTH by Oracle Tuxedo.

Here is an example of UBBCONFIG:

Listing 8 Oracle Tuxedo UBBCONFIG File Example When Enabling User Substitution in TuxJES System

# (c) 2011 Oracle. All Rights Reserved.

#

*RESOURCES

IPCKEY <IPCKEY> # for example 132770

DOMAINID jessample

MASTER SITE1

MODEL SHM

MAXACCESSERS 200

MAXSERVERS 50

NOTIFY SIGNAL

PERM 0666 #Adding "PERM=0666" in RESOURCES section

SECURITY USER_AUTH

AUTHSVC "AUTHSVC"

 

*MACHINES

#

<uname -n>

LMID = SITE1

TUXDIR ="<full path of TUXEDO software>"

TUXCONFIG = "<full path of APPDIR>/tuxconfig"

TLOGDEVICE ="<full path of APPDIR>/TLOG"

TLOGSIZE=10

APPDIR = "<full path of APPDIR>"

ULOGPFX = "<full path of APPDIR>/ULOG"

 

*GROUPS

 

ARTGRP

LMID = SITE1 GRPNO = 1

QUEGRP

LMID = SITE1 GRPNO = 2

TMSNAME = TMS_QM TMSCOUNT = 2

OPENINFO = "TUXEDO/QM:<full path of APPDIR>/QUE:JES2QSPACE"

 

EVTGRP

LMID= SITE1 GRPNO=3

 

#

*SERVERS

# Adding RQPERM=0666 RPPERM=0666 in all JES servers entry in SERVERS section

DEFAULT: CLOPT="-A"

 

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

RQPERM=0666 RPPERM=0666

 

TMQUEUE

SRVGRP = QUEGRP SRVID = 1

GRACE = 0 RESTART = Y CONV = N MAXGEN=10

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

RQPERM=0666 RPPERM=0666

 

ARTJESADM SRVGRP =ARTGRP SRVID = 1 MIN=1 MAX=1

CLOPT = "-A -- -i jesconfig"

RQPERM=0666 RPPERM=0666

 

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

CLOPT = "-A --"

RQPERM=0666 RPPERM=0666

 

ARTJESINITIATOR SRVGRP =ARTGRP SRVID =30

CLOPT = "-A -- -n 20 -d"

RQPERM=0666 RPPERM=0666

 

ARTJESPURGE SRVGRP =ARTGRP SRVID = 100

CLOPT = "-A --"

 

AUTHSVR SRVGRP=ARTGRP SRVID=104 CLOPT="-A"

RQPERM=0666 RPPERM=0666

 

*SERVICES

 

Configuring File System Permission

To enable the user substitution successfully, you need to make sure the permission of the file system for users with different identities have been configured to meet the following requirements:

•	All job executors should have read and execute permissions to the following folders:

•	$JESDIR/bin/artjesadmin

•	$JESDIR/locale/*

•

$MT_ROOT

•	All job executors should have full permissions to the following folders:

•	$DATA_SOURCE

•

$DATA

•

$MT_LOG

•

$SPOOL

•

$MT_TMP

•	$MT_ACC_FILEPATH

•

$JESROOT

•	All job users should have read permission to the following folders:

•

$TUXDIR

•	$TUXCONFIG

Note:

It is recommended that all job executors have the write permission to ULOG, stdout, and stderr, otherwise the log and output messages cannot be written successfully.

TuxJES Trace Message Control

TuxJES trace messages are stored in TuxJES trace file. By default, TuxJES trace file is stored in ${APPDIR}/Logs directory; before running Batch Runtime, you can change the directory by setting the environment variable JES_TRACE_PATH.

There are four TuxJES trace messages levels: ERROR, WARN, INFO, and DEBUG. WARN is used by default. You can use environment variable JESTRACE to set the TuxJES trace message level, or use command artjesadmin to dynamically change it, determining which level of messages will be displayed.

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

TuxJES Job Operation

TuxJES supports a standard job operation interface. A set of FML32 fields are defined for the service contract. The utility artjesadmin shipped in TuxJES uses typical Tuxedo ATMI APIs (See Oracle Tuxedo API: ATMI for more details) to submit,, control, and print job information. Customers are also supported to write personalized applications, which communicate with TuxJES job management system. This documentation explains the general steps and programming approaches.

FML32 Fields in Use for TuxJES Job Operation

All TuxJES job related fields are defined at $JESDIR/udataobj/jesflds. The corresponding header file is at $JESDIR/include/jesflds.h. Table 13 illustrates the fields used in job operation.

 

Table 13 FML32 Fields in Use for TuxJES Job Operation

Field Name	Type	Descriptions
JES2_JOB_ID	STRING	The job ID generated by TuxJES job management if a job is successfully submitted to the system. The range is [1-99999999].
JES2_JOB_NAME	STRING	The job name given to this job. It is supplied by users in the shell script.
JES2_JOB_CLASS	STRING	The job class.
JES2_JOB_PRTY	SHORT	The job priority ranged in [0-15].
JES2_JOB_TYPRUN	STRING	The job type. It is supplied by users for job submission in the shell script.
JES2_JOB_SCRIPT	STRING	The ksh job script name. It can be in the format of absolute path or relative path. The later case will be extended from current working directory.
JES2_JOB_EJROPTION	STRING	The options passed to EJR itself.
JES2_JOB_OWNER	STRING	The job owner. It is supplied when a job is submitted and returned by server to query job information.
JES2_JOB_SUBMITTIME	LONG	The submitted timestamp of a job. It is the seconds since Epoch time.
JES2_JOB_STATUS	STRING	The job status returned by server.
JES2_JOB_ERROR	STRING	If the operation encounters some errors, the field carries the information.
JES2_JOB_MSG	STRING	It carries error information for particular jobs. Unlike JES2_JOB_ERROR, JES2_JOB_MSG carries general failure information.
JES2_JOB_CURRENT	STRING	The current step of a job.
JES2_JOB_ENDTIME	LONG	The timestamp of a terminated job. It is seconds since Epoch time.
JES2_JOB_EXECTIME	LONG	The timestamp of an executing job. It is seconds since Epoch time.
JES2_JOB_EXECMAC	STRING	The host for the running job.
JES2_JOB_USRSEC	LONG	The user-level CPU time in seconds.
JES2_JOB_USRUSEC	LONG	The user-level CPU time for the microseconds portion in one second.
JES2_JOB_SYSSEC	LONG	The system-level CPU time in seconds.
JES2_JOB_SYSUSEC	LONG	The system-level CPU time for the microseconds portion in one second.

To use the above fields, you must include header file $JESDIR/include/jesflds.h in your source code, and use Tuxedo FML32 APIs to manipulate the FML32 buffer of input and output. For more information, please refer to Programming An Oracle Tuxedo ATMI Application Using FML.

ATMI Services in Use for TuxJES Job Operation

ARTJESADM server provides the following ATMI services as the job handling entries. Client programs can call these services using standard ATMI APIs, such as tpcall with FML32 buffer, in which the fields are prepared or retrieved for input and output.

•	JES2SUBMIT

•

JES2PRINT

•

JES2HOLD

•	JES2RELEASE

•	JES2CANCEL

•

JES2PURGE

JES2SUBMIT

This service provides the functionality to submit a job.

Input

Required Fields

JES2_JOB_SCRIPT

Optional Fields

JES2_JOB_OWNER

Note:

If JES2_JOB_OWNER is not specified, this job is deemed to "*" user, meaning no ownership of this job.

Output

Success

Output buffer will contain the following fields.

•	JES2_JOB_ID

•	JES2_JOB_NAME

•	JES2_JOB_CLASS

•	JES2_JOB_TYPRUN

•	JES2_JOB_PRTY

•	JES2_JOB_OWNER

Failure

If the submission fails, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.

JES2PRINT

This service is used to query job information. The interface allows you to get a particular job with job ID, a set of jobs with the same job name and job class, or all jobs. If multiple job instances are got in the results, they will be in FML32 occurrence style, in which occurrence starts at 0. For example, if three jobs are returned, the first job will be at occurrence of 0, the second job will be at 1, and the third job will be at 2.

Input

Required Fields

None. If nothing specified, the server will print all jobs.

Optional Fields

•	JES2_JOB_ID (if it is specified, only this job will be retrieved)

•	JES2_JOB_NAME (if it is specified, only the jobs of this name will be retrieved)

•	JES2_JOB_CLASS (if it is specified, only the jobs of this class will be retrieved)

Note:

ARTJESADM checks fields in the sequence of job ID, name, and class; once a field is checked, ARTJESADM stops checking.

Output

Success

If the retrieving is completed successfully, the following fields will be returned.

•	JES2_JOB_ID

•	JES2_JOB_NAME

•	JES2_JOB_CURRENT

•	JES2_JOB_STATUS

•	JES2_JOB_SUBMITTIME

•	JES2_JOB_CLASS

•	JES2_JOB_TYPRUN

•	JES2_JOB_PRTY

•	JES2_JOB_OWNER

•	JES2_JOB_EXECMAC

•	JES2_JOB_USRSEC

•	JES2_JOB_USRUSEC

•	JES2_JOB_SYSSEC

•	JSE2_JOB_SYSUSEC

Notes:

•	JES2_JOB_ID is mandatory to use; others are optional.

•	It's suggested to use the occurrence of JES2_JOB_ID as the field manipulation base.

•	If there is something wrong with a particular job, JES2_JOB_MSG will be available in the corresponding sequence specified by JES2_JOB_ID. For partially wrong cases, tperrno will be TPOK.

Failure

If a general operation is failed, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.

JES2HOLD

This service is used to hold a job not in running nor end status. The interface of job collection is the same with JES2PRINT.

Input

Required Fields

None. If nothing specified, the server will hold all jobs.

Optional Fields

•	JES2_JOB_ID (if it is specified, only this job will be held)

•	JES2_JOB_NAME (if it is specified, only the jobs of this name will be held)

•	JES2_JOB_CLASS (if it is specified, only the jobs of this class will be held)

Note:

ARTJESADM checks fields in the sequence of job ID, name, and class; once a field is checked, ARTJESADM stops checking.

Output

Success

If the operation is completed successfully, the following fields will be returned.

•	JES2_JOB_ID

•	JES2_JOB_NAME

Note:

If there is something wrong with a particular job, JES2_JOB_MSG will be available in the corresponding sequence specified by JES2_JOB_ID. For partially wrong cases, tperrno will be TPOK.

Failure

If a general operation is failed, the JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.

JES2RELEASE

This service is used to release a job in hold status. The job can be in hold status by a hold operation, submitting time typerun. The interface of job collection is the same with JES2PRINT.

Input

Required Fields

None. If nothing specified, the server will release all jobs.

Optional Fields

•	JES2_JOB_ID (if it is specified, only this job will be released)

•	JES2_JOB_NAME (if it is specified, only the jobs of this name will be released)

•	JES2_JOB_CLASS (if it is specified, only the jobs of this class will be released)

Note:

ARTJESADM checks fields in the sequence of job ID, name, and class; once a field is checked, ARTJESADM stops checking.

Output

Success

If the operation is completed successfully, the following fields will be returned.

•	JES2_JOB_ID

•	JES2_JOB_NAME

Note:

If there is something wrong with a particular job, JES2_JOB_MSG will be available in the corresponding sequence specified by JES2_JOB_ID. For partially wrong cases, tperrno will be TPOK.

Failure

If a general operation is failed, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.

JES2CANCEL

This service is used to cancel a job. The interface of job collection is the same with JES2PRINT.

Input

Required Fields

None. If nothing specified, the server will cancel all jobs.

Optional Fields

•	JES2_JOB_ID (if it is specified, only this job will be canceled)

•	JES2_JOB_NAME (if it is specified, only the jobs of this name will be canceled)

•	JES2_JOB_CLASS (if it is specified, only the jobs of this class will be canceled)

Note:

ARTJESADM checks fields in the sequence of job ID, name, and class; once a field is checked, ARTJESADM stops checking.

Output

Success

If the operation is completed successfully, the following fields will be returned.

•	JES2_JOB_ID

•	JES2_JOB_NAME

Note:

If there is something wrong with a particular job, JES2_JOB_MSG will be available in the corresponding sequence specified by JES2_JOB_ID. For partially wrong cases, tperrno will be TPOK.

Failure

If a general operation failed, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.

JES2PURGE

This service is used to purge a job. If a job is not finished yet, the effect is the same with JES2CANCEL. The interface of job collection is the same with JES2PRINT.

Input

Required Fields

None. If nothing specified, the server will purge all jobs.

Optional Fields

•	JES2_JOB_ID (if it is specified, only this job will be purged)

•	JES2_JOB_NAME (if it is specified, only the jobs of this name will be purged)

•	JES2_JOB_CLASS (if it is specified, only the jobs of this class will be purged)

Note:

ARTJESADM checks fields in the sequence of job ID, name, and class; once a field is checked, ARTJESADM stops checking.

Output

Success

If the operation is completed successfully, the following fields will be returned.

•	JES2_JOB_ID

•	JES2_JOB_NAME

Note:

If there is something wrong with a particular job, JES2_JOB_MSG will be available in the corresponding sequence specified by JES2_JOB_ID. For partially wrong cases, tperrno will be TPOK.

Failure

If a general operation is failed, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.

Event Subscriptions for Job Status Changes

TuxJES provides an event notification mechanism based on Tuxedo EventBroker (See Subscribing to Events for more details). The following user-level events are provided when something happens at each stage. The data buffer of each event is FML32 buffer for a particular job.

 

Table 14 Available TuxJES Events for Subscription

Event Name	Descriptions
ARTJES_JOBSUBMIT	A new job is submitted.
ARTJES_JOBCVT	A job conversion is completed.
ARTJES_JOBCVT_FAIL	A job conversion fails.
ARTJES_JOBEXEC	A job is finished successfully.
ARTJES_JOBEXEC_FAIL	A job's execution fails.
ARTJES_JOBPURGE	A job is purged.
ARTJES_JOBCANCEL	A job is canceled.

Since the event post depends on JESCONFIG configurations in ARTJESADM, the switch must be turned on if all or some event want to.

Security Consideration

The application using the job management service interface must be compliant to Tuxedo ATMI security convention (see Introducing ATMI Security for more details). The proper application password and username/password must be prepared for tpinit() in a client application. To control the permission of services, adequate ACL or MANDATORY ACL should be configured in UBBCONFIG for the services listed in ATMI Services in Use for TuxJES Job Operation.

Sample of Submitting a Job

The following sample demonstrates how to submit a job. -I $JESDIR/include must include CFLAGS.

Listing 9 Sample of submitting a job

#include <stdio.h>

#include <tpadm.h>

#include <fml32.h>

#include <jesflds.h>

 

main(int argc, char *argv[])

{

FBFR32 *input;

FBFR32 *output;

long buflen;

 

if (tpinit((TPINIT *) NULL) == -1) {

(void)fprintf(stderr, "Tpinit failed: %s\n", tpstrerror(tperrno));

exit(1);

}

 

input = tpalloc("FML32",NULL,1024);

output = tpalloc("FML32",NULL,1024);

 

if (input == NULL || output == NULL) {

(void)fprintf(stderr, "Tpinit failed: %s\n", tpstrerror(tperrno));

exit(1);

}

if (Fappend32(input,JES2_JOB_SCRIPT, "JOBA", 0) < 0 ) {

(void)fprintf(stderr, " Fappend32 failed: \n");

exit(1);

}

Findex32(input,0);

if (tpcall("JES2SUBMIT", input, 0, &output,&buflen,0) < 0 ) {

(void) fprintf(stderr, "Can't send request to service JES2SUBMIT");

exit(1);

}else {

char *jobid;

jobid = Ffind32(output,JES2_JOB_ID,0,NULL);

if (jobid != NULL) {

fprintf(stdout,"Job %s is submitted\n",jobid);

}

}

tpfree(input);

tpfree(output);

(void)tpterm();

return(0);

}