Knowledge Base > Automation Engine and Target Systems > OS/400 > Agent - Combining the AE and OS/400

Agent - Interaction Between the Automation Engine and OS/400

The OS/400 agent works together with the AE system via a TCP/IP interface.

The OS/400 agent provides the following functions:

Job Processing
Remote Status Capturing and Tracking
Execution of file transfers
Execution of file events
Event Handling
CallAPI

Job Processing

In AE, jobs are defined and maintained in the form of objects that include various tabs. The JCL (CMD, CL or REXX) is stored in the Process tab. Its logic can be very complex if you make use of AE's script elements.
See: User Guide - Job and Job - Execution

In AE, jobs start either manually or via control mechanisms such as workflows or schedules.The Automation Engine then generates an executable job and sends it to the OS/400 agent via a file transfer.
See: Inside AE Guide - Executing Objects

In OS/400, you can start jobs start by using the SBMJOB commandwhich calls the AE job shell (IRSTRJOB program in the supplied library). Among other information, the job shell obtains the following parameters - the job's name that is generated by the Automation Engine, and the name of the file member under which the job has been stored. Depending on the job type, it executes the following:

CMD
The job shell executes every line of the file member. If an error occurs in a particular line, the severity code is set as the job's return code and only the Job Messenger is called at the job's end.
ILE CL
The job shell converts the file member and creates a temporary CL program. If the conversion is successful, the job shell processes the CL program.
REXX
The job shell calls the REXX interpreter and assigns the name of the file member that includes the REXX script.

Each job notifies the agent (Job Messenger) about the beginning and end of an execution. The agent then passes this information on to the Automation Engine. The job's return code is available in AE.

The agent monitors the job's status in regular intervals. This ensures that an abnormal end can be determined if a job vanishes (ABEND or CANCEL). This job is then considered lost within the AE system.

The states of jobs that have been executed while the agent was terminated are also retrieved. Doing so is possible because of the start and end messenger outputs.

Note that on OS/400, the JCL is compiled to a program and then executed. An uncontrolled termination can occur which could have the effect that the job's status is not correctly displayed. Use the MONMSG command in order to identify program terminations and to react to them. To use this command, you require the job setting "Type" - "ILE CL".

The following example monitors the execution of the JCL by using the MONMSG command and sets the job status accordingly:

Pre-Process tab:

! Activates the start and end messenger output for the status recovery.
:SET&UC_QPRINT = 10
! The OS/400 CL command monitors all exceptions and skips to the ERROR label.
MONMSG CPF0000 (GOTO ERROR)

Process tab:

! Command to be executed by the job. All active processes are shown in this case.
wrkactjob *print
! Sets the job's return code to the value 0.
CHGVAR &RETCODE '0'
! Calls the end messenger.
GOTO END
! The adequate return code is set if an error occurs.
ERROR:
CHGVAR &RETCODE '99'

The job report (Spool) consists of the spool contents (depending on the job definition only QPJOBLOG or the entire contents). It is written to a file that is specified by the Automation Engine. If specified in the job, the agent transfers the report to the Automation Engine which stores it in the AE databaseA database is an organized collection of data including relevant data structures..

Remote Status Capturing and Tracking

If you have OS/400 version IBM i 6.1 or above, you may use the following SQL statement examples to check, if any OS/400 jobs have the status MSGW (= waiting for messages):

List all jobs in MSGW status:

select count(*) from EH where EH_RemoteStatus = 2006018 AND EH_Client = &$CLIENT#

Return all necessary information to perform actions on jobs, which are in MSGW status:

select EH_AH_Idnr, EH_RemoteStatus, EH_RemoteStatusIns, EH_Alias from EH where EH_RemoteStatus = 2006018 AND EH_Client = &$CLIENT#

You may decrease the interval, in which the status of jobs is being checked by changing the value for JOB_CHECKINTERVAL in the system Variable UC_HOSTCHAR_DEFAULT. Be aware, that a decrease of this value will affect server performance.

Executing File Transfers

In AE, file transfers are defined and maintained in the form of objects that include various tabs. They are executed with the character conversions that are defined in these tabs (such as EBCDIC_00037).

For more information see: OS/400 Agent - File Transfer Support

Event Handling

In AE, events are defined and maintained in the form of objects that include various tabs. You can define FileSystem events that refer to the library file system (QSYS.LIB). The OS/400 agent also supports events of type Console.
See: User Guide - Event

Executing FileSystem Event Objects

There are some peculiarities that must be considered when you use file events with an OS/400 agent.

For more information see: OS/400 Agent - FileSystem Event Support

CallAPI

You can use the CallAPI with a utility that can be called by using a CL script, for example.
See: User Guide - CallAPI