Monday 21 September 2015

Chapter 12: i5/OS Jobs



Chapter 12: i5/OS Jobs


i5/OS Jobs :

The i5/OS job lets you run a program or issue a command on an i5/OS system. You can 
run i5/OS jobs in the following file systems: 
■ Root file system 
■ Open systems file system (QOpenSys) 
■ Library file system (QSYS) 
Note: To run these jobs, your system requires CA WA Agent for i5/OS. 
You can specify the following details in an i5/OS job definition: 
■ Library name, library list, and current library for running a program 
■ The i5/OS job name, options under which the job will run, where it will run, and 
which user will run it 
■ Ending exit value of the program, such as a severity code 
You can define parameter values that you want to pass to a program at the time the 
program is invoked. 
Note: Default values may be set for certain parameters, such as the i5/OS user ID that 
the jobs run under. Contact your agent administrator about the parameters set in the 
agentparm.txt file. 
 i5/OS Jobs 

Running UNIX Workload on a System i5 Computer 
In addition to scheduling native i5/OS jobs, you can schedule most UNIX workload, such 
as UNIX scripts, in the PASE environment on i5/OS. 
To run both native and UNIX jobs on the same i5/OS computer, you must install two 
i5/OS agents and configure the oscomponent.targetenvironment parameter in the 
agentparm.txt file to handle the appropriate job type. For more information about 
configuring the parameter, see the CA Workload Automation AE UNIX Implementation 
Guide or Windows Implementation Guide. 
Note: For more information about UNIX workload that can run in the PASE 
environment, see the IBM i5/OS documentation. 
i5/OS Naming Conventions 
When specifying i5/OS paths and names in your workload, you can use the following 
naming conventions, depending on where the file is located on the i5/OS system: 
■ Root file system 
To specify a file in the root file system, use UNIX path and file formats. 
■ Open systems file system (QOpenSys) 
To specify a file in QOpenSys, use UNIX path and file formats. QOpenSys file names 
are case-sensitive. 
■ Library file system (QSYS) 
To specify an object in QSYS, use one of the following formats (unless described 
differently in the job definition syntax): 
– Path format 
/QSYS.LIB/library.LIB/object.type/ 
To specify *FILE objects, use the following format: 
/QSYS.LIB/library.LIB/object.FILE/member.MBR 
– i5/OS standard format 
library/object/type 
To specify *FILE objects, use the following format: 
library/object/*FILE(member) 
Note: *FILE is optional when member is specified. That is, you can specify a file 
member using the following format: 
library/object(member) Define an i5/OS Job 
Chapter 12: i5/OS Jobs 317 
Notes: 
■ The values for library, object, type, and member can be up to 10 characters each. 
■ You can use *ALL to match any name. 
■ You can use *FIRST for member. 
■ You can use generic names for library and object. 
Define an i5/OS Job 
You can define an i5/OS job to schedule workload to run on an i5/OS system. The job 
can run a program or an i5/OS command. You can run i5/OS jobs in the root file system, 
open systems file system (QOpenSys), and library file system (QSYS). 
Note: To run these jobs, your system requires CA WA Agent for i5/OS. 
Follow these steps: 
1. Insert a job and specify the following attributes in the definition: 
job_type: I5 
Specifies that the job type is i5/OS. 
machine 
Specifies the name of the machine on which the job runs. 
i5_name 
Specifies the program, the source file for the program, or the command that 
you want to run. 
Note: The value must correspond to the i5_action value. If you do not specify 
the i5_action attribute, the job interprets the corresponding i5_name value as 
a command by default. 
2. (Optional) Specify optional i5/OS attributes: 
■ fail_codes 
■ i5_action 
■ i5_cc_exit 
■ i5_curr_lib 
■ i5_job_desc 
 Define an i5/OS Job 
318 User Guide 
■ i5_job_name 
■ i5_job_queue 
■ i5_lda 
■ i5_lib 
■ i5_library_list 
■ i5_others 
■ i5_params 
■ i5_process_priority 
■ job_class 
■ max_exit_success 
■ success_codes 
3. (Optional) Specify common attributes that apply to all jobs. 
The i5/OS job is defined. 
Notes: 
■ Attributes that have a default value automatically apply to the job definitions; 
therefore, they are optional. For example, jobs with no specified job type are 
defined as command jobs by default. Other optional attributes specify information 
that is not required but affects how or when a job runs, such as attributes that 
specify scheduling conditions. 
■ Some optional attributes are common to all job types but others apply to certain 
jobs types only. Optional attributes that apply to all job types are known as 
common optional attributes. For more information about common optional 
attributes and the values that you can specify for them (including their default 
values when applicable), see the Reference Guide. 
■ For information about required attributes and job type specific optional attributes, 
see the procedure topics that provide instructions for defining jobs. 
■ This guide provides instructions for defining jobs interactively. You also create job 
definitions in script files and then import them using the jil command or use CA 
WCC to define them. For more information about the JIL command and JIL syntax, 
see the Reference Guide. For more information about using CA WCC to define the 
job, see the CA Workload Control Center Workload Scheduling Guide. 
Example: Run an i5/OS Command 
This example runs the command named DSPJOBLOG on the i5agent computer. 
insert_job: i5job_runcmd 
job_type: I5 
machine: i5agent 
i5_name: DSPJOBLOG Attributes with Default Values 
Chapter 12: i5/OS Jobs 319 
Attributes with Default Values 
Attributes that have a default value automatically apply to the job definition. Therefore, 
you do not have to specify those attributes in the definition. Your agent administrator 
can define some default values on the agent in the agentparm.txt file. 
If you specify the attribute in a job definition, it overrides the default. 
The following i5/OS job attributes have default values: 
i5_action 
Specifies whether to run a program or issue a command. 
Default: COMMAND (The job interprets the i5_name value to be a command.) 
i5_cc_exit 
Specifies the type of exit code returned by an i5/OS job. 
Default: *SEVERITY (The job sends the ending severity code as the exit code.) 
i5_job_desc 
Specifies the job description for the submitted program. 
Default: os400.default.jobdname agent parameter, if specified 
i5_job_queue 
Specifies the i5/OS job queue for the submitted program. 
Note: os400.default.jobqname agent parameter, if specified 
i5_process_priority 
Specifies the process priority of the i5/OS job. 
Default: NORMAL 
owner 
Specifies the user ID that the job runs under. 
Default: The user ID who invokes jil to define the job (the owner of the job) 
Note: For more information about JIL job types and other job definition attributes, the 
values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 
 Pass Positional Parameters
320 User Guide 
Example: Override Default Values 
This example runs an i5/OS program. A default job queue is defined in the agent's 
agentparm.txt file. The i5_action and i5_job_queue attributes in this job definition 
override the default values. 
insert_job: i5job_lib 
job_type: I5 
machine: i5agent 
i5_action: RUN_PROGRAM 
i5_name: PAYLOAD 
i5_job_queue: /QYS.LIB/QBASE.LIB/JQUEUE.JOBQ 
Pass Positional Parameters 
When running workload, you might need to pass data between jobs and across 
platforms. You can pass positional parameters to an i5/OS program in your job 
definition. Positional parameters are variables that can be passed to a program at the 
time the program is invoked. The parameters are assigned in the order they are passed. 
Follow these steps: 
1. Define an i5/OS job (see page 317). 
2. Add the following attribute to the job definition: 
i5_params 
Defines the parameter values that you want to pass to the program at the time 
the program is invoked. 
3. Run the job. 
The specified positional parameters are passed to the i5/OS program. 
Note: For more information about JIL job types and other job definition attributes, the 
values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 
Example: Pass Multiple Parameters to an i5/OS Job 
This example passes six parameters to an i5/OS program named PAYJOB. The parameter 
VALUE C is enclosed with double quotation marks because it contains a space. 
insert_job: i5job_lib 
job_type: I5 
machine: i5agent 
i5_action: RUN_PROGRAM 
i5_name: PAYJOB 
i5_params: ABC 1 P "VALUE C" X r Use a User's Library List 
Chapter 12: i5/OS Jobs 321 
Use a User's Library List 
The agent uses the library list in the job's job description by default. However, if the user 
is defined, you can set up your job definition to use the user's library list instead. 
Follow these steps: 
1. Define an i5/OS job (see page 317). 
2. Do one of the following: 
■ Add the following attribute to the job definition: 
i5_curr_lib: (*USRPRF) 
Specifies that the job uses the user's current library when it runs. 
■ Add the following attributes to the job definition: 
i5_job_desc: (*JOBD) 
Specifies that the job uses the job description assigned to the user to 
access the library list. 
i5_library_list: (*USRPRF) 
Specifies that the job accesses the user’s library list when it runs. 
3. Run the job. 
The job uses the user's library list. 
Note: For more information about JIL job types and other job definition attributes, the 
values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 
Pass Keyword Parameters to SBMJOB 
When CA Workload Automation AE submits a job to the i5/OS system, the job must pass 
through the SBMJOB command to execute. The following JIL attributes map to 
parameters for the SBMJOB command: 
JIL Attributes SBMJOB Parameters 
i5_user USER 
i5_job_desc JOBD 
i5_library_list INLLIBL 
i5_job_queue JOBQ 
i5_curr_lib CURLIB 
i5_job_name JOB Pass Keyword Parameters to SBMJOB 
322 User Guide 
You can also pass additional keyword parameters, such as OUTQ(*JOBD), to the SBMJOB 
command. 
Follow these steps: 
1. Define an i5/OS job (see page 317). 
2. Add the following attribute to the job definition: 
i5_others 
Specifies SBMJOB command keyword and value combinations. 
3. Run the job. 
The specified keywords and values are passed to the SBMJOB command. 
Notes: 
■ The special values for these SBMJOB parameters, such as *USRPRF and *JOBD, also 
apply to the JIL attributes. You can use these special values in your job definitions. 
For more information about the SBMJOB parameters and their special values, see 
the IBM documentation. 
■ For more information about JIL job types and other job definition attributes, the 
values that you can specify for those attributes, and JIL syntax, see the Reference 
Guide. 
Example: Specify the Printer and Output Queue for an i5/OS Job 
This example runs a program named PAYJOB on an i5/OS system. The printer and 
output queue information is taken from the job definition. 
insert_job: i5job_lib 
job_type: I5 
machine: i5agent 
i5_action: RUN_PROGRAM 
i5_name: PAYJOB 
i5_others: PRTDEV=*JOBD,OUTQ=*JOBD Responding to Suspended Jobs that Require Manual Intervention 
Chapter 12: i5/OS Jobs 323 
Responding to Suspended Jobs that Require Manual 
Intervention 
A program run on an i5/OS system can temporarily suspend itself until it receives 
additional feedback from the end user. In this scenario, CA WA Agent for i5/OS notifies 
the scheduler that a manual response is required. The scheduler sets the job status to 
the WAIT_REPLY state. A WAIT_REPLY_ALARM is raised with text containing the query 
of the i5/OS program as well as the set of expected responses. For the i5/OS job to 
resume program execution, you must send a response to the job. For example, suppose 
that you schedule an i5/OS job to save data in a file. If the file already contains data, the 
i5/OS program prompts you to confirm that the data in the file can be overwritten. 
To respond to suspended jobs that require manual intervention, issue the following 
command: 
sendevent -J job_name -E REPLY_RESPONSE -r response 
The response is sent to the CA WA Agent for i5/OS and the job resumes running. 
Returning a Job's Exit Status to CA Workload Automation AE 
A job’s exit code indicates whether the job completed successfully or failed. By default, 
the agent sends the job’s ending severity code to CA Workload Automation AE when a 
job completes. CA Workload Automation AE interprets an exit code of zero (0) as job 
success and any other number as job failure. 
In addition to sending the job’s ending severity code, you can return a job’s exit status in 
other ways. For example, you can send the return code of an ILE program or module as 
the exit status or you can specify a user-defined exit code of 100 as success. 
You can return a job's exit status to CA Workload Automation AE using the following 
methods: 
■ Send a program’s return code using the i5_cc_exit attribute 
■ Send a user-defined exit code using the success_codes or fail_codes attribute 
■ Return an exit status using the EXIT_SUCCESS and EXIT_FAILURE macros 
 Returning a Job's Exit Status to CA Workload Automation AE 
324 User Guide 
Send a Program’s Return Code 
When a job completes, the agent sends the job’s exit code to CA Workload Automation 
AE. By default, the agent sends the job’s ending severity code as the job's exit code. 
Instead of sending the job's ending severity code, the agent can send the return code of 
one of the following: 
■ An ILE program or module 
■ An OPM program 
For example, if your job runs an ILE C, ILE RPG, OPM RPG, or OPM Cobol program that 
contains an exit or return statement, the agent can send that return code as the exit 
code. 
Follow these steps: 
1. Define an i5/OS job (see page 317). 
2. Add one of the following attributes to the job definition: 
i5_cc_exit: *USER 
Specifies that the return code of an ILE program or module is sent as the exit 
code. 
i5_cc_exit: *PROGRAM 
Specifies that the return code of an OPM program is sent as the exit code. 
3. Run the job. 
The program's return code is sent instead of the job’s ending severity code. 
Note: For more information about JIL job types and other job definition attributes, the 
values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 
Example: Send an OPM COBOL Program’s Return Code as the Job’s Exit Code 
This example runs an OPM COBOL program named PAYROLL. The agent sends the 
PAYROLL program’s return code to CA Workload Automation AE. 
insert_job: i5job_returnOPM 
job_type: I5 
machine: i5agent 
i5_action: RUN_PROGRAM 
i5_name: PAYROLL 
i5_cc_exit: *PROGRAM Returning a Job's Exit Status to CA Workload Automation AE 
Chapter 12: i5/OS Jobs 325 
Example: Send an ILE C Program's Return Code as the Job's Exit Code 
This example runs a C language program named SALARY. The agent sends the SALARY 
program’s return code to CA Workload Automation AE. Ending severity codes of 1 or 10 
indicate job success. 
insert_job: i5job_returnC 
job_type: I5 
machine: i5agent 
i5_action: RUN_PROGRAM 
i5_name: SALARY 
i5_cc_exit: *USER 
success_codes: 1,10 
Note: The i5 system always writes the job’s ending severity code to the job’s spool file. 
You can check the spool file for the job’s ending severity code for more information 
about the job status. For example, suppose that the C program's return code indicates 
failure, but the ending severity code shown in the spool file is 10, which might indicate 
that the job ran with a minor issue. Assuming that this issue can be ignored, you can 
indicate ending severity codes of 10 as job success using the success_codes attribute. 
Send a User-defined Exit Code 
By default, CA Workload Automation AE interprets an exit code of 0 (zero) as job success 
and any other number as job failure. However, you can map exit codes other than 0 as 
job success. 
Follow these steps: 
1. Define an i5/OS job (see page 317). 
2. Add one of the following attributes to the job definition: 
success_codes 
Defines which exit codes indicate job success. 
Default: 0 (zero) 
fail_codes 
Defines which exit codes indicate job failure. 
Default: Any non-zero exit code 
3. Run the job. 
The specified user-defined exit code is sent. 
Note: For more information about JIL job types and other job definition attributes, the 
values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 
 Returning a Job's Exit Status to CA Workload Automation AE 
326 User Guide 
Example: Send Exit Code 100 as Success 
This example runs the PAYPROG program. The program is considered to have completed 
successfully if it returns an exit code of 1 or 100. 
insert_job: i5job_succ 
job_type: I5 
machine: i5agent 
i5_action: RUN_PROGRAM 
i5_name: PAYPROG 
i5_cc_exit: *PROGRAM 
success_codes: 1,100 
Example: Send Exit Code 40 as Failure 
This example runs the RECPROG program. The program is considered to have failed if if 
it returns an exit code of 40. All other exit codes in the range from 50 to 255 indicate job 
success. 
insert_job: i5job_fail 
job_type: I5 
machine: i5agent 
i5_action: RUN_PROGRAM 
i5_name: RECPROG 
i5_cc_exit: *PROGRAM 
fail_codes: 40 
success_codes: 50-255 Specify Data for a Local Data Area 
Chapter 12: i5/OS Jobs 327 
Specify Data for a Local Data Area 
The local data area is a temporary 1024-byte storage area that exists for the duration of 
an i5/OS job. You can use the local data area to pass data to the job and to other 
programs that run as part of the job. When the job is submitted, the agent initializes the 
local data area with the specified data. When the job completes, the local data area is 
destroyed automatically by the operating system. 
Follow these steps: 
1. Define an i5/OS job (see page 317). 
2. Add the following attribute to the job definition: 
i5_lda 
Specifies data for the local data area in an i5/OS job. 
3. Run the job. 
The data is specified for a local data area. 
Note: For more information about JIL job types and other job definition attributes, the 
values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 
Example: Specify Data for the Local Data Area in Hexadecimal Format 
This example defines an i5/OS job with data for the local data area. When the job is 
submitted, the agent initializes the local data area with the hexadecimal data abcd. 
When the job completes, the local data area is destroyed automatically by the operating 
system. 
insert_job: i5job_lda 
job_type: I5 
machine: i5agent 
i5_action: COMMAND 
i5_name: IVP 
i5_lda: x'abcd' 

No comments:

Post a Comment