Table 1 lists TuxJES commands and functions.
Generates the security profile for TuxJES system TuxJES command interface. TuxJES administration server. TuxJES conversion server. TuxJES job control API. TuxJES Queue system. genjesprofile – Generates the security profile for TuxJES systemgenjesprofile 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.genjesprofile supports the following parameters and options:The location of the generated security profile file. If this option is not specified, the default value is ~/.tuxAppProfile.genjesacl - Generates the encrypted job access authorization configuration file for TuxJES system.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.genjesacl supports the following parameters and options:The location of the encrypted rule file that genjesacl generates. If this option is not specified, the default value is ~/.jesAclEncrypted.\gensysprofile – Generates file to encrypt and store TuxJES Database connection information.gensysprofile generates file to encrypt and store TuxJES Database connection information.gensysprofile supports the following parameters and options:Specifies JESROOT directory, where this file is to be generated.artjesadmin – TuxJES command interface.artjesadmin is the TuxJES command interface.The TuxJES system must be started first.artjesadmin supports the following parameters and options:Option -v indicates the current version of Oracle Tuxedo Application Runtime for Batch.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 "*".
• If -f profile is specified, the specified profile file will be used;
• If -f is not specified, nothing will be used as the profile file.-p and -j
Table 2 Exit Code Job status = DONE Job status = FAIL Job status = CANCEL Job status = CONVING Job status = EXECUTING Job status = HOLD_CONVING Job status = HOLD_WAITING Job status = WAITING Job status = DISCARD This status will occur if tpenqueue() fails. Job status = INDOUBT When a job is running, if JES server ARTJESINITIATOR is shutdown and then restarted, the job status will be INDOUBT.
Table 3 Standard Output Listing 1 Sample: Job has been Finished NormallyListing 2 Sample: Job is Finished but FailsListing 3 Sample: Job is RunningOption -x is specified to control ARTJESINITIATOR servers. It must be showjobexec, resumejobexec, or stopjobexec. For more information, see Sub Commands.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.
• 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.Option -o ejr option specifies the options passed to the EJR script file.Option -y is added to submit a job in the synchronous way. This option enables synchronous mode to wait for job end.
Table 4 Exit Code Information shown on Table 5 will be printed to stdout in the following format.
Table 5 Standard Output Listing 4 Sample: Job is Executed SuccessfullyListing 5 Sample: Job FailsListing 6 Sample: Timeout OccursOption -x settracelevel is specified to set the TuxJES trace message level. For more information, see Sub Commands.Option -x setjesacl is specified to change job access authorization. For more information, see Sub Commands.artjesadmin supports the following sub commands: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 script file.
• -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.Display the number of executing jobs of ARTJESINITIATOR servers.If no option is specified, display the number of executing jobs of all ARTJESINITIATOR servers.The Tuxedo logic machine name that the ARTJESINITIATOR server is running on.The Tuxedo group id of the ARTJESINITIATOR server.The Tuxedo server id of the ARTJESINITIATOR server.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.The Tuxedo logic machine name that the ARTJESINITIATOR server is running on.The Tuxedo group id of the ARTJESINITIATOR server.The Tuxedo server id of the ARTJESINITIATOR server.Resume ARTJESINITIATOR servers pick up of new jobs to execute. If no option is specified, all ARTJESINITIATOR servers resume picking up new jobs.The Tuxedo logic machine name that the ARTJESINITIATOR server is running on.The Tuxedo group id of the ARTJESINITIATOR server.The Tuxedo server id of the ARTJESINITIATOR 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.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.Specify the path of job access authorization configuration file. Its usage is just likes JES_ACL_FILE in JESCONFIG.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.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.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 artjesadmin it self command error returned by ARTJESADM server JES2SUBMIT service error -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
• 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
• If no option is specified, the "-a" option is assumed.-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 jobsIf no option is specified, the "-a" option is assumed.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 jobsIf no option is specified, the "-a" option is assumed.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 jobsIf no option is specified, the "-a" option is assumed.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.-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 jobsIf no option is specified, the "-a" option is assumed.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.-n concurrent_num: the number of maximum concurrent executing jobsThe change is not persistent, which means the number is reset when the ARTJESINITIATOR server restarts.Displays the number of maximum concurrent executing jobs for the ARTJESINITIATOR server which is designated by -g and -i options.C: job conversion complete event; the event name is ARTJES_JOBCVTE: job execution finish event; the event name is ARTJES_JOBEXECP: job purge event; the event name is ARTJES_ARTJESPURGEL: job cancel completed event; the event name is ARTJES_JOBCANCELA: 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.artjescleanlock – The utility to clean stale lock records in lock files in MP mode.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.artjescleanlock supports following options:
Note: 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 – TuxJES Administration server.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.ARTJESADM supports the following parameters and options:JESCONFIG represents the full path name of the TuxJES system configuration file. It allows the following parameters: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.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.S: Job submission event. Event name: ARTJES_JOBSUBMITC: Job conversion complete event. Event name: ARTJES_JOBCVTE: Job execution finish event. Event name: ARTJES_JOBFINISHP: Job purge event. Event name: ARTJES_JOBPURGEL: Job cancel completed event. Event Name: ARTJES_JOBCANCELA: 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.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).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.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.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.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.The full path where TuxJES user mapping file is stored. It is used along with PRIVILEGE_MODE when its value is USER_MAPPING.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. This is currently not supported.
NOT SET: Use /Q to store job information.ARTJESCONV – TuxJES conversion server.ARTJESINITIATOR – Job InitiatorARTJESINITIATOR 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.ARTJESINITIATOR supports the following parameters and options:Specifies the job classes this ARTJESINITIATOR server is associated. If this option is not specified, ARTJESINITIATOR associates with all job classes.Specifies the number of maximum concurrent executing jobs for this ARTJESINITIATOR server. The default value is 1.Specifies the number of maximum concurrent executing jobs for this ARTJESINITIATOR server can be change by artjesadmin changeconcurrent command.In this example, ten ARTJESINITIATOR instances are configured and are associated with the "A","H" and "Z" job classes.ARTJESPURGE – Purges job queueARTJESPURGE 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>.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 7.
Table 7 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. 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. The TuxJES system provides a sample shell script (jesqinit) to create the queue space (JES2QSPACE) and the queues listed in Table 7. You can modify the script to adapt to your environment, but must adhere to the following:Table 8 lists the terms you need to know for a good understanding of the user substitution feature described in this section.
Table 8 User Substitution Terms The OS user who submits a JES job with artjesadmin The Job owner designated by JES system depends on the combination of configurations on artjesadmin and PRIVILEGE_MODE. Table 9 shows the relation between job owner designation and different configuration scenarios.
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."Table 10 and Table 11 show the permissions of users with different identities when operating jobs in TuxJES system enabling the user substitution.
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.
• 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.
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.DEFAULT: CLOPT="-A"
•
•
•
•
•
•
•
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 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 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.All TuxJES job related fields are defined at $JESDIR/udataobj/jesflds. The corresponding header file is at $JESDIR/include/jesflds.h. Table 12 illustrates the fields used in job operation.
It carries error information for particular jobs. Unlike JES2_JOB_ERROR, JES2_JOB_MSG carries general failure information. 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.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.
•
Note: If JES2_JOB_OWNER is not specified, this job is deemed to "*" user, meaning no ownership of this job.
• 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.
• 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.If a general operation is failed, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.
• 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.
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.If a general operation is failed, the JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.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.
• 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.
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.If a general operation is failed, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.
• 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.
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.If a general operation failed, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.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.
• 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.
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.If a general operation is failed, JES2_JOB_ERROR carries the error message and tperrno is set to TPESVCFAIL.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.
Since the event post depends on JESCONFIG configurations in ARTJESADM, the switch must be turned on if all or some event want to.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.Listing 9 Sample of submitting a job