Using the AS/400 Definition Type

The AS/400 Definition Type lets you work with jobs and files on a remote AS/400. For each remote AS/400 system, you need one dedicated Process Server, and preferably a dedicated Queue. There is no need to install any software on the AS/400 itself.

The AS/400 Definition Type can do the following:

• Run commands as AS/400 jobs (for example DSPJOB), wait for them to complete, and determine their return code.
• Create files.
• Delete files.
• List a file, directory, or library.
• Wait for AS/400 jobs submitted directly on the AS/400 to complete.
• Activate tracing of the AS/400 connections/commands made by RunMyJobs.

Running Commands as AS/400 Jobs

An AS/400 Process Definition can simply be the name of a command to run. For example:

DSPJOB

Note: The SBMJOB CMD() part of the command is added by the Process Server and should not be specified.

You can also supply a command name via a parameter. The command you specify for the parameter at submit time will executed.

${command}

If you specify a command, it can be followed by a single optional JobControl section, and zero or more Output sections. You might get no output if you have not specified any JobControl or Output sections.

DSPJOB

[JobControl]
Append=JOB(TestJob) JOBQ(EXTERNAL) LOG(2 50 *MSG) SPLFACN(*KEEP)

The above example will only work if you have a job Queue named External, adapt as necessary.

Note: In an AS/400 script, blank lines and lines starting with # are ignored.

Output Sections

[Output] sections are optional. If you do not specify any [Output] sections, output will be spooled to files with names based on the spool file name and number from the AS/400, and the stderr.log and stdout.log files will be empty. As soon as one section is specified, you have complete control over spooling. Sections are processed in the order they are specified (this is important if two [Output] sections point to the same file). Each[Output] section must have a unique identifier.

[Output[:<identifier>]]
spool=name of spool to fetch, required
number=number of spool to fetch, required, *ONLY and *LAST are accepted
append=true to append to the file, false to overwrite it.
jobfile=Name of the file
maxsize=Override the value of the parameter AS400JobSpoolMaxSize.
banner=Override the value of the parameter AS400JobSpoolBanner.
removecontrolcharacters=Override the value of the parameter AS400JobSpoolRemoveControlCharacters
SpoolMFRTYPMDL=

The order of precedence for values is:

1. The value in the [Output] section.
2. The Process Definition parameter value.
3. The Process Server parameter value.
4. The default value of the Process Server parameter.

Here is an example that specifies multiple [Output] sections.

DSPJOB

[JobControl]
Append=LOG(2 50 *MSG) SPLFACN(*KEEP)

[Output]
jobfile=stdout.log
spool=QPDSPJOB
number=1

[Output:stderr]
jobfile=stderr.log
spool=QPDSPLOG
number=*LAST

[Output:debug]
jobfile=stddbg.log
spool=QEZDEBUG
number=2

The JobControl Section

The [JobControl] section lets you control the options passed to SBMJOB when RunMyJobs submits the process. Any value that is valid for SBMJOB on your OS/400 release is valid here to be appended.

[JobControl]
Append=append these commands to the above, overriding the AS400JobAppend process definition parameter and Process Server parameter
jobappendlocal=append these commands after Append or AS400JobAppend

The order of precedence for values is:

1. The value in the [JobControl] section.
2. The Process Definition parameter value.
3. The Process Server parameter value.
4. The default value of the Process Server parameter.

The CL command sent to the AS/400 is:

SBMJOB CMD(command) [ AS400JobAppend|Append ] [ jobappendlocal ]

• AS400JobAppend: The Process Server or Process Definition parameter.
• Append: The Append entry in the JobControl section. This overrides AS400JobAppend.
• jobappendlocal: The jobappendlocal entry in the JobControl section. Commands here are appended to whatever has been previously specified.

Note: For information about SBMJOB commands/options, see Submit Job (SBMJOB).

The following options may be useful.

• LOG(2 50 *MSG): This changes the message logging values used to determine the amount and type of information sent to the log. There are three elements: the message (or logging) level, the message severity, and the level of message text. The values in this example specify a logging level of 2 (messages to the process's external message queue and program message queue that exceed the severity) and a severity of 50 and indicate that the message text should be written to the log (*MSG).
• SPLFACN(*KEEP): This keeps spooled files even after the job has ended, allowing the connector to parse the job log and determine the return code.

You may want to run some jobs in a different queue or subsystem. You can do this by changing the AS/400 queue that the jobs run in (the AS/400 job then determines the subsystem). There are two ways to do this:

• Use JOBQ(QUEUENAME) in Submit control parameter to change the queueon a per-job basis.

• Change the default Queue for the AS/400 user. (For more information, contact your AS/400 operator).

If you need to specify multiple options, separate them with a space. For example:

LOG(2 50 *MSG) SPLFACN(*KEEP)

JOBQ(EXTERNAL) LOG(2 50 *MSG) SPLFACN(*KEEP)

Note: To be able to retrieve the return code from the process, Redwood Server requires the CPF1164 message in the log file. If this is not present, RunMyJobs will detect the job has finished, but it will be unable to detect the appropriate return code for the process.

Note: The SPLFACN(*KEEP) option is recommended by Redwood. This makes detection of completion of the job more accurate, because RunMyJobs can see it go into *OUTQ.

Raising Events on Active States

You can raise RunMyJobs events on active states (ACTIVE_JOB_STATUS) by specifying one or more onactivestate sections, using the following syntax.

[onactivestate:<job_status>]
raiseevent=<partition>.<event>
raisecomment=<raiser_comment>

See IBM Knowledge Center (class com.ibm.as400.access.Job ) for a list of active states. Any value of the String constants with the ACTIVE_JOB_STATUS prefix is supported.

Example:

QSH CMD('/HOME/EXAMPLE/script.qsh')

[JobControl]
Append=JOBQ(*JOBD) LOG(2 50 *MSG) SPLFACN(*KEEP)

[onactivestate:TIMA]
raiseevent=EXAMPLE.MyEvent
raisecomment=Event raised while job is in Active state

Converting SMBJOB Commands to AS/400 Jobs

Assume that an AS/400 operator currently uses the following SBMJOB command to submit a job via the command line, and now they want to do this automatically in RunMyJobs.

SBMJOB CMD(CALL PGM(J12345) PARM('P12345 ' 'U012V0001 ')) JOB(PROD_PLAN) JOBQ(QGPL/ESPINTER)

The SBMJOB CMD() part is added by the Process Server, so the command is actually this:

CALL PGM(J12345) PARM('P12345 ' 'U012V0001 ') and JOB(PROD_PLAN) JOBQ(QGPL/ESPINTER)

Because this was outside of the CMD() call, it must be appended manually:

JOB(PROD_PLAN) JOBQ(QGPL/ESPINTER)

Taking the above into account, the Source field in the Process Definition should read as follows:

CALL PGM(J12345) PARM('P12345    ' 'U012V0001 ')

[JobControl]
Append=JOB(PROD_PLAN) JOBQ(QGPL/ESPINTER)

Note: To be able to retrieve the return code from the process, RunMyJobs requires the CPF1164 message in the log file. If this is not present, Redwood Server will detect that the job has finished, but it will be unable to detect the return code for the process. You may need to override the LOG() and SPLFACN() calls for the job log to be available for reading, and for return code determination to work.

Installing AIX jtool

To install jtool on an AS/400, copy the jtool executable from an AIX Platform Agent to the UNIX-style file system on the AS/400, then issue the following command.

QSH CMD('/path/to/jtool install')

Note: If you use FTP, you must use the binary mode to transfer the file.

This will install the jtool binaries. You can then use these as you would on other platforms.

Note: Binaries that rely on -job-context will not work on the AS/400, even if they are executed as a RunMyJobs process, because this option requires a Platform Agent context.

Working with AS/400 Files

This section describes commands for creating, deleting, and listing files on an AS/400 computer.

Creating an AS/400 File

The create action tries to create the file specified by the filename= key. If the file exists, then the action attempts to delete it. If this fails, the process is set to status Error. If it succeeds, the file is opened, a single byte (0) is written to the file, and then the file is closed. If this succeeds, the process is set to status Completed. Otherwise it is set to Error.

[action]
action=file.create
filename=${filename}

Deleting an AS/400 File

The delete action first checks to see if the file specified by the filename= key exists. If the file does not exist, the action does nothing and the process is set to status Completed. If the file exists, the action attempts to delete it. If it succeeds, the process is set to status Completed. Otherwise it is set to Error.

[action]
action=file.delete
filename=${filename}

Listing AS/400 Files

The list action tries to open the file or directory specified by the filename= key. If it exists, the action tries to list its contents. If this fails, the process is set to status Error. If it succeeds, then:

• If there are no files in the directory, “No files found” is printed.
• If one or more files are found in the directory, the number of files found is printed, followed by one line for each file.
  • If the file is a directory, _D _ is printed before its name.
  • If the file is not a directory, __ is printed before its name.
• Errors during directory listing are written to the error file, but listing continues.

[action]
action=file.list
filename=${filename}

Waiting for Existing AS/400 Jobs

To wait for existing jobs, no command is necessary. Just specify that the action is to wait for jobs.

[Action]
action=job.waitForJobs
<inclusion criteria>
[exclusion criteria]

In addition, you can specify inclusion criteria for the wait. This action will wait for all jobs with name matching name= and user matching user= to complete.

The action will first wait for at least one matching one job to start, then wait for all jobs matching the criteria to reach a final state, including any jobs that start after monitoring has started.

The inclusion criteria available are as follows.

• NAME=<job name>
• USER=<job user>
• ACTIVE_JOB_STATUS=<an active job status>: Selects jobs based on active job status.
• INITIAL_USER=<user>: Selects jobs based on the user name for a process's initial thread.
• JOB_NUMBER=<number>: Selects jobs based on job number.
• JOB_QUEUE=<queue name>: Selects jobs based on job Queue.
• JOB_QUEUE_STATUS_HELD=<true or false>: Includes or excludes held jobs.
• JOB_QUEUE_STATUS_READY=<true or false>: Includes or excludes ready jobs.
• JOB_QUEUE_STATUS_SCHEDULE=<true or false>: Includes or excludes scheduled jobs.
• JOB_TYPE=<type>: Selects jobs based on job type <type>.
• JOB_TYPE_ENHANCED=<number>: Selects jobs based on the enhanced job type <number>
• SERVER_TYPE=<type>: Selects jobs based on the server type <type>.

Note: The above criteria for job.waitForJobs are not case-sensitive.

Redwood uses the class com.ibm.as400.access.JobList and sets the name and user selection criteria. Generally these should be exact matches for the job name and user. You can find more information about possible values by browsing to Class JobList - IBM JavaDocs and searching for JobList.

You may also specify exclusion criteria. The syntax for each criterion is as follows. See the table below for an explanation of the variables.

exclude.<Text>.<Identifier>.<before|after>[.equal]=<Parameter Name>

Identifiers correspond to get<XXX>Date() methods on Job objects. For more information, see Class Job - IBM JavaDocs.

If any exclusion rule matches a job, that job is excluded.

Below is an example action to wait for the nightlybatch job to complete, excluding any jobs before a date specified in the parameter P_DATE.

[Action]
action=job.waitForJobs
name=nightlybatch
user=DOEJ
exclude.old.JobPutOnJobQueueDate.before=${P_DATE}

Note that the Process Definition in the example above has two parameters: one named P_DATE of type DateTimeZone, and another named P_DATE_FORMAT containing a SimpleDateFormat. This makes it easier to use date functions from REL in the P_DATE parameter.

Activate Tracing

You can activate tracing and specify trace categories using the trace.dynamic action. If you specify All, all trace categories will be turned on. Otherwise you can specify which categories you would like. The output is stored in the stdout.log file.

[Action]
action=trace.dynamic
category.<name>=<AnyValue>

• <name>: Options include All, Conversion, Datastream, Diagnostic, Error, Information, JDBC, PCML, Proxy, Thread, and Warning. The available categories depend on the JTOpen version. Look for com.ibm.as400.access.Trace.set<Name>On(boolean).
• <AnyValue>: Set this to enabled for readability. Any value, including true, false and yellow, is interpreted as enabled.

Variables and Parameters

All AS/400 Process Server parameters can be specified as parameters with the same name to override Process Server defaults.

You do not have to create or specify these parameters on your Process Definitions. If they are not present, the Process Server defaults are used. If they are present, they override the Process Server defaults.

There are three special cases:

• The AS400User parameter should be overridden using the Process Definition Run As User.
• The AS400Server parameter can be used to specify the Process Server that the process will run on using a parameter rather than a Queue.

You can also define your own parameters, but they cannot start with AS400, because this is reserved for the AS/400 Connector. Custom parameters can be used to substitute values inside the script text, using the format ${parameterName}. Substitutions are only valid inside values, not inside keys (in other words, only after the =).

Note: When a process reaches status Error, the Out values of parameters are not always set. You can use a Post Running action to set them if required.

AS400Server Parameter

The AS400Server parameter specifies the AS/400 to run the job on. This must be the name of the AS/400 Process Server. If you submit an individual process and specify this parameter, then the constraints will prevent you from selecting an incorrect Queue. If the process is part of a Chain, and you specify a Queue that does not contain the Process Server specified by the AS400Server parameter, then the system will automatically reroute your process to the first Queue (in alphabetical, case insensitive order) that:

• Has only the Process Server specified in AS400Server (preferred).
• Has the Process Server specified in AS400Server, and potentially other Process Servers.

In all cases, the process will be forced to run on the Process Server specified by AS400Server, regardless of whether other Process Servers on the Queue can run the process.

If you want to submit a process on a Queue with multiple AS/400 Process Servers and use the load balancing features, do not specify a value for the AS400Server parameter.

Process Server Parameter Overrides

The following table lists all Process Server parameters that can be overridden in your Source field. Note that the table does not contain jobAppendLocal, because it does not override the Process Server parameter.

Example AS/400 Jobs

This example submits a DSPJOB Job.

DSPJOB

This example passes a parameter value to an AS/400 job.

WRKOUTQ OUTQ(${outputqueue})

This example submits a job and restricts log retrieval to a maximum of 10MB.

DSPJOB

[JobControl]
# This AS/400 system does not create job logs or keep spool files by default, so override the behavior.
Append=LOG(2 50 *MSG) SPLFACN(*KEEP)
notes=true

[Output]
# Capture QPDSPJOB (number 1) to stdout, as long as it is less than 10Mb
jobfile=stdout.log
spool=QPDSPJOB
number=1
maxsize=10000000

This example submits a job and raises an event on a specific status.

DLYJOB 20

[JobControl]
Append=JOBQ(*JOBD) LOG(2 50 *MSG) SPLFACN(*KEEP)

[onactivestate:DLYW ]
raiseevent=FORMS.MyEvent
raisecomment=Event raised on ACTIVE_JOB_STATUS_WAIT_DELAY state

Example File Actions

This example lists files and subdirectories, using a filename parameter on the Process Definition. You can use something like this to make sure a specific file is in a specific location when you want to add file events.

[action]
action=file.list
filename=${filename}

Result:

Listing files: '/QSYS.LIB/USERX.LIB'
13 files found.
   IICTST1.PGM
   MSGTEST.PGM
   MSGTEST2.PGM
   MSGTEST2B.PGM
   MSGTEST3.PGM
D  ABCDEFGHIJ.FILE
D  AETEST.FILE
D  ARR2511221.FILE
D  ARR2511223.FILE
D  QCLSRC.FILE
D  QDDSSRC.FILE
D  QPJOBLOG.FILE
D  QRPGLESRC.FILE

This example creates a file. It requires a Process Definition parameter named PATH.

[Action]
action=file.create
filename=${PATH}

Result:

 /QSYS.LIB/USERX.LIB/ABCDEFGHIJ.FILE

This example deletes a file. It requires a Process Definition parameter named PATH.

[Action]
action=file.delete
filename=${PATH}

Result:

 /QSYS.LIB/USERX.LIB/ABCDEFGHIJ.FILE

Note that this action will complete regardless of whether the file was deleted. If the file cannot be deleted, an Operator Message will be raised.

AS/400 Resources

• Supported versions of OS/400
• IBM i Information Centre
• The Integrated File System (IFS)
• There are useful pages on the different file systems under the IFS (File systems) and their features and limitations. See File system comparison for more information.
• CL introduction - Wikipedia
• Control language
• Submit Job (SBMJOB)
• RunMyJobs uses the open source JTOpen version of IBM Toolbox for Java to connect to the AS/400). For more information, see Java.