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'