Skip to main content

IBMi/AS400 Agent Installation Guide

This document shows how to install and manage the IBMi / AS400 agent for Unmeshed Job Scheduling Platform. The agent is a Java-based application which runs natively on the IBMi machine and executes the scheduled jobs as configured on the Unmeshed Platform. The integration between agent and Unmeshed platform is protected by an access key and secret and happens over an HTTPS connection.

Installation Files​

Main Execution Engine: app-all.jar​

This is the main Java program that will be running the agent application in the IBMi server.

Job Control SAVF File: unmeshedlib.savf​

This file is the exported library which contains the control commands such as start, stop and status under a library named UNMSHLIB which can be used by the operator to start and stop the agent job.

Application Configuration: unmeshed.properties​

This property file will hold the relevant fields to connect the agent to the Unmeshed server. The following contents are a sample for this file and can be used as a template to create the file.

CLIENT_ID=<Client id generated by Unmeshed Server>
CLIENT_SECRET=<Client secret generated by Unmeshed Server>     
UNMESHED_URL=https://yourserverurl.unmeshed.com/
UNMESHED_STEP_NAMES=default:ibmicommand;default:ibmicommand.default;
FieldDescription
CLIENT_IDThis is a generated field from the Unmeshed Platform when you create a client application
CLIENT_SECRETThis is a generated field from the Unmeshed Platform when you create a client application
UNMESHED_URLHTTPS URL for the Unmeshed server the agent should connect to
UNMESHED_STEP_NAMES<namespace>:<name>;<namespace>:<name>

This describes the step names that this agent will listen to for job executions from the Unmeshed platform.

Example: default:ibmicommand.server1
Implies that this agent will listen to all steps named ibmicommand.server1 under the namespace default

This works like a selector for the jobs that this specific agent is allowed to run.
Request Access

Contact your Unmeshed support team to request download links for the following agent binaries:

  • app-all.jar - Main execution engine
  • unmeshedlib.savf - Job control library

Installation​

Pick a folder to use as the unmeshed application home folder. The logs from this app will be written to this directory. We will assume the use of /home as the default folder.

Follow the steps to install:

  1. Upload the files to the application home directory using SCP
  2. Run the CL installation commands as shown in the table CL Installation Commands and take note of the paths used to refer to the uploaded files
  3. Verify the installation as shown in table CL Verification Commands

Operating Unmeshed Agent​

See the table CL Operating Commands for starting and stopping job and take note of the home directory of the app which is required in the param for the start command.

Upgrading Unmeshed Agent​

Follow these steps to upgrade:

  1. Stop the agent based on the commands in table CL Operating Commands
  2. If there is a change to the Installation files such as app-all.jar or savf files, upload the new files to the same location as the original installation
  3. If there is an upgrade to the CL files, follow the same steps as Installation. There is no need to create the data area again.
  4. Start the agent based on the commands in table CL Operating Commands

Command Tables​

CL Installation Commands​

/* 1. Delete previous savf file in QGPL if it exists */
DLTF  FILE(QGPL/UNMCLIB)  

/* 2. Create a savf file in QGPL to receive the save file */
CRTSAVF  FILE(QGPL/UNMCLIB)  

/* 3. Copy the uploaded savf file into the savf file, change location as needed */
CPYFRMSTMF FROMSTMF('/home/unmeshedlib.savf') TOMBR('/QSYS.LIB/QGPL.LIB/UNMCLIB.FILE') MBROPT(*REPLACE)  

/* 4. View or verify contents */
DSPSAVF  QGPL/UNMCLIB  OUTPUT(*)  

/* 5. Create or update the UNMSHLIB from the savf file */
RSTLIB  SAVLIB(UNMSHLIB) DEV(*SAVF) SAVF(QGPL/UNMCLIB)  

/* 6. Create or data area flag to enable or disable unmeshed agent */
CRTDTAARA  DTAARA(QUSRSYS/UNMSHDCTRL) TYPE(*CHAR) LEN(1) VALUE('0') TEXT('Stop flag for Unmeshed service (0 = run, 1 = stop)')

CL Verification Commands​

/* Display library components */
DSPLIB UNMSHLIB 

/* Check status */
CALL PGM(UNMSHLIB/UNMSHSTAT)

CL Operating Commands​

/* Command to check if the job is enabled */
CALL PGM(UNMSHLIB/UNMSHSTAT)  

/* Command to stop the running agent, it will take up to a minute for agent to exit */
CALL PGM(UNMSHLIB/UNMSHSTOP)  

/* Command to start the agent, it will take up to a minute for agent to start */
/* The parameter should be the folder where the unmeshed installation files and access key is uploaded */
CALL PGM(UNMSHLIB/UNMSHSTRT) PARM('/home')

FAQs & Notes​

  1. Duplicate Job Errors: If you run into duplicate job errors, remove the spool files if present that is duplicating jobs with name UNMESHED
  2. Spool File Management: Make sure the spool files and operator queues are cleared regularly
  3. User Permissions: Make sure the user running the agent has the permissions to run the required commands supplied by job scheduler
  4. Health Monitoring: A scheduled job with a hello world command can be used to check that the agent is up and running every few minutes and operators can be alerted if the agent is down
  5. Client Credentials: To create a client ID and secret, contact your system administrator for Unmeshed platform
  6. Auto-restart: What happens if the JVM crashes? The system will automatically restart the agent unless the restart is disabled with the Data Area flag.