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 systemThis 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), and the database login information to access Oracle Database for GDG management (MT_GDG_DB_ACCESS). 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: 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.artjesadmin – TuxJES command interface.artjesadmin is the TuxJES command interface. It requires 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.-y and -t
Table 2 Option -y and -t Descriptions 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.
Table 3 Exit Code Information shown on Table 4 will be printed to stdout in the following format.
Table 4 Standard Output Listing 1 Sample: Job is Executed SuccessfullyListing 2 Sample: Job FailsListing 3 Sample: Timeout Occurs-p and -jTable 5 lists the exit codes for artjesadmin if -p is specified.
Table 5 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. Information shown on Table 6 will be printed to stdout in the following format.
Table 6 Standard Output Listing 4 Sample: Job has been Finished NormallyListing 5 Sample: Job is Finished but FailsListing 6 Sample: Job is Runningartjesadmin supports the following sub commands: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.
• -i =scriptfile: The script file.
• -I: The option specified to submit JCL jobs.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 7.
Table 7 Error Codes -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 jobsListing 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-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.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.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 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. 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 8. You can modify the script to adapt to your environment, but must adhere to the following: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 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 10 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 11 and Table 12 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 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 13 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