Agent - Interaction between AE and OS/400

The following document is for administrators who want to understand the how the OS/400 Agent works together with the AE system via a TCP/IP interface.

This page includes the following:

Job Processing

In the AE, Jobs are defined and maintained in the form of objects that include various pages. Use Automation Engine scripting language to include complex logic on the Process page of the Job.

More Information:

On the Process page of the Job object, you write commands in the Job Control Language (CMD, CL or REXX). For more information, see Job Control Language Script Reference.

More Information:

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. For more information, see Execution Stages.

In OS/400, you can start jobs start by using the SBMJOB command which 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:

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 Page

! 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 Page

! 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 database.

Remote Status Capturing and Tracking

OS/400 Jobs might have the status MSGW (waiting for messages) which means that the Job waits for a reply to a specific message. This status is specific to OS/400 Jobs and they require additional objects to integrate them with the Automation Engine.

From the point of view of the Automation Engine, the OS/400 Job is active as any other Job (Windows, Unix, and so on). If you have OS/400 version IBM i 6.1 or higher, you can query if the Job is indeed waiting for a message (status MSGW) using an additional SQL command. To do so, you can create a SQLI variable (see SQLI VARA Objects) and use the following SQL command:

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

Note: You can decrease the interval in which the status of jobs is checked by changing the value for JOB_CHECKINTERVAL in the system settings. For more information, see UC_HOSTCHAR_DEFAULT - Host Characteristics. Be aware decreasing this value affects server performance.

If there is a Job with MSGW status, the SQLI variable that executes the query delivers the result with the following information:

EH_AH_Idnr: Run Id of the AE Job waiting on the message
EH_RemoteStatus: Predefined message insert number, representing this state on AE
EH_RemoteStatusIns: Text inserts used for resolving the message insert
EH_Alias: Name of the AE job which is waiting on message

You can translate the message inserts of the EH_RemoteStatus and EH_RemoteStatusIns fields using the GET_MSG_TXT script function, see GET_MSG_TXT. The script function returns the message text.

Example

U00020408 U02006018 Job Run-Id: '24212270' report status 'Message Wait' for Process '969637/UCPROD/MSGW'. Process is waiting for message reply on Message 'CPA5305', key '0000D220' in Message Queue: 'QSYS/QSYSOPR'.

You can also use the STR_SPLIT script function (see STR_SPLIT) to split the text of this field so that the content can be processes in script. The insert text includes the following data:

OS/400 Message Key: Key of the message in the OS/400 message queue, represented as 4byte hexadecimal string
OS/400 Message ID: ID of the OS/400 message which requires the reply, which initiated the MSGW status of the OS/400 Job
OS/400 Job name: Name of the OS/400 Job (Process ID) which is waiting on the message
OS/400 Message Queue: OS/400 queue name where the message is placed
Job Run ID: Run ID of the Job waiting on message

This information allows you to use the data of the EH_RemoteStatusIns field to create an additional OS/400 Job to reply to the request message. To do so, you can use the OS/400 Send Reply (SNDRPY) command.

Example

OS/400 Job send reply to the request message as found by the OS/400 message key (pre-process tab of the OS/400 Job):

! In case of MSGW

:SET &MSGW_MSGKEY# = STR_TRIM(&MSGW_MSGKEY#)

DCL VAR(&MSGKEY) TYPE(*CHAR) LEN(4)

! The MSGKEY# comes from outside

CHGVAR VAR(&MSGKEY) VALUE(X'&MSGW_MSGKEY#)

If there is a Job with MSGW status, use SNDRPY to reply (process tab of the OS/400 Job):

! Reply with 9999

SNDRPY MSGKEY(&MSGKEY) MSGQ(&MSGW_MSGQ#) RPY(9999) RJTDFTRPY(*ALWRJT)

For more information, see Process Pages.

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 FILE Event objects that refer to the library file system (QSYS.LIB). The OS/400 agent also supports events of type Console.
For more information, see Events (EVNT).

Executing FILE 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 - File Event Support.

CallAPI

You can use the CallAPI with a utility that can be called by using a CL script, for example.

For more information, see CallAPI for OS/400.