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'
