Table of Contents Previous Next PDF


Tuxedo Job Enqueueing Service (TuxJES)

Tuxedo Job Enqueueing Service (TuxJES)
This chapter describes servers, commands and utilities included in the TuxJES feature.
Table 1 lists TuxJES commands and functions.
 
TuxJES command interface.
TuxJES administration server.
TuxJES conversion server.
TuxJES job control API.
TuxJES Queue system.
genjesprofile
Name
genjesprofile – Generates the security profile for TuxJES system
Synopsis
genjesprofile [-f userprofile]
Description
This utility generates the security profile for TuxJES system. When genjesprofile is launched, you are prompted to enter the Oracle Tuxedo application password, user name, user password and the database connection (MT_DB_LOGIN). The output is a security profile file which contains the Oracle Tuxedo application password, user name, user password and the database connection with the file permission “-rw-------”.
Note:
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
artjesadmin
Name
artjesadmin – TuxJES command interface.
Synopsis
Description
artjesadmin is the TuxJES command interface. It requires 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.
-y and -t
Descriptions
Option -y and -t are added to submit a job in the synchronous way. Table 2 shows some details.
 
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.
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.
Exit code
Table 3 lists the exit codes for artjesadmin if -y is specified.
 
Table 3 Exit Code
Standard Output
Information shown on Table 4 will be printed to stdout in the following format.
<JOBID>,<JOBNAME>,<JOBSTATUS>,<JOB RETURN CODE>
 
Listing 1 Sample: Job is Executed Successfully
00000002,JOBA,DONE,C0000
 
Listing 2 Sample: Job Fails
00000002,JOBA,FAILED,U0568
 
Listing 3 Sample: Timeout Occurs
00000002,JOBA,Already Timeout!
 
-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
Job status = EXECUTING
Job status = HOLD_CONVING
Job status = HOLD_WAITING
This status will occur if tpenqueue() fails.
When a job is running, if JES server ARTJESINITIATOR is shutdown and then restarted, the job status will be INDOUBT.
Standard Output
Information shown on Table 6 will be printed to stdout with the following format.
<JOBID>,<JOBNAME>,<JOBSTATUS>,<JOB RETURN CODE>
 
 
Listing 4 Sample: Job has been Finished Normally
00000002,JOBA,DONE,C0000
 
Listing 5 Sample: Job is Finished but Fails
00000002,JOBA,FAILED,U0568
 
Listing 6 Sample: Job is Running
00000002,JOBA,EXECUTING
 
artjesadmin supports the following sub commands:
submitjob(smj ) [-o='xxx'] -i scriptfile
Submits a job to TuxJES system. The scriptfile 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:
-o='xxx': Specifies the options passed to the EJR script file using the -i option.
-i =scriptfile: The script file.
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 scriptfile
artjesadmin has a return code different from zero if there is an error occurs as listed in Table 7
 
Table 7 Error Codes
printjob(ptj) -n jobname | -j jobid | -c job_class |-a [-v]
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
Listing 7 printjob Output
> ptj -a
JOBNAME JobID Owner Prty C Status
-------- -------- -------- --------- ---------
cjob 00000015 * 5 A DONE
cjob 00000016 * 5 A DONE
cjob 00000018 * 5 A CONVING
 
total:3
success:3
 
JOBNAME: The job name.
JobID: The job ID generated by TuxJES system
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:
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 | -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
-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
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.
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.
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.
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
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
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.
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:
1.
2.
3.
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
Note:
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.
 
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.
 
When artjesadmin is executed with...
When PRIVILEGE_MODE is set to...
USER_IDENTICAL or USER_MAPPING
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".
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.
 
 
Enabling User Substitution in TuxJES
To enable the user substitution in TuxJES, the following operations should be done:
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:
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.
 

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.