← Files on AS/400 Raise EventsRedwood Server OS Support →

Using the AS/400 Definition Type

The AS/400 definition type allows you to 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:

  • Run commands as AS/400 jobs (for example DSPJOB), wait for them to complete, and determine their return code.
  • Work with AS/400 files
    • 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 Redwood Server

Run commands as AS/400 jobs

The format of the script text is simple, blank lines and lines starting with a # are ignored. The simplest possible process definition is just the command to run:

DSPJOB
note

The SBMJOB CMD() part of the command is added by the process server and should not be specified.

You can also simply specify a parameter, the command you specify in 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)
note

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

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 stderr.log and stdout.log 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. Value in [Output] section.
  2. Process definition parameter value.
  3. Process server parameter value.
  4. Default value of process server parameter.

Specifying 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 allows you to control the options passed to SBMJOB when Redwood Server 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. Value in [JobControl] section.
  2. Process definition parameter value.
  3. Process server parameter value.
  4. Default value of 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, overrides AS400JobAppend
  • jobappendlocal - the jobappendlocal entry in the JobControl section; commands here are appended to whatever has been previously specified

You can find the commands/options for SBMJOB on the IBM website:

Submit Job (SBMJOB)

Useful options are:

  • LOG(2 50 *MSG) - change the message logging values used to determine the amount and type of information sent to the log. This has three elements: the message (or logging) level, the message severity, and the level of message text. The values specify a logging level of 2 (messages to the process's external message queue and program message queue that exceed the severity), a severity of 50 and to write the message text to the log (*MSG).
  • SPLFACN(*KEEP) - Keep spooled files even after the job has ended, this allows 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. This is achieved by changing the AS/400 queue that the jobs run in (the AS/400 job then determines the subsystem). There are two ways, use JOBQ(QUEUENAME) in Submit control parameter to change it on a per job basis, or change the default queue for the AS/400 user (Contact your AS/400 operator).

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

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, Redwood Server will detect the job has finished, however, 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 (since Redwood Server can see it go into *OUTQ).

Raise Events on Active States

You raise Redwood Server 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 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 submit job (SMBJOB) commands from the command line to AS/400 Jobs

Your AS/400 operator currently uses the following SBMJOB command to submit the job at the command line, and now wants to do this automatically in Redwood Server

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

You know the SBMJOB CMD() part is added by the process server, so that leaves us with this:

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

The following must be appended (it was outside of the CMD() call):

JOB(PROD_PLAN) JOBQ(QGPL/ESPINTER)

So your Source should read:

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, Redwood Server requires the CPF1164 message in the log file. If this is not present, Redwood Server will detect the job has finished, however, it will be unable to detect the appropriate return code for the process. You may need to override the LOG() and SPLFACN() in order for the job log to be available to be read, and for return code determination to work.

Installing AIX Jtools

You copy the jtool executable from an AIX platform agent to the UNIX-style file system on the AS/400 and issue the following command:

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

This will install the jtool binaries. You can then use these as you would on UNIX; note that the binaries relying on -job-context will not work on the AS/400, even if they are executed as a Redwood Server process as this option requires a platform agent context.

note

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

Work with AS/400 files

The different file actions available are:

  • file.delete - delete a file specified by filename=
  • file.create - create a file specified by filename= (the file will be deleted first if it already exists)
  • file.list - list files in directory specified by filename=

Create 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 this succeeds, then the file is opened and a single byte (0) is written to the file and the file is closed. If this succeeds then the process is set to status Completed, otherwise it is set to Error.

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

Delete an AS/400 file

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

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

List AS/400 files

The list action tries to open the file or directory specified by the filename= key. If it exists, then the action attempts to list its contents. If this fails the process is set to status Error. If this 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, then the number of files found is printed, followed by one line for each file.
    • If the file is a directory then _D _ is printed before its name.
    • If the file is not a directory then __ is printed before its name.
  • Errors during directory listing are written to the error file, but the listing will continue.
[action]
action=file.list
filename=${filename}

Wait for Existing AS/400 Jobs

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

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

In addition you need to 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:

  • NAME=<job name>
  • USER=<job user>
  • ACTIVE_JOB_STATUS=<an active job status> - job selection based on active job status.
  • INITIAL_USER=<user> - job selection based on the user name for a process's initial thread.
  • JOB_NUMBER=<number> - job selection based on job number.
  • JOB_QUEUE=<queue name> - job selection based on job queue.
  • JOB_QUEUE_STATUS_HELD=<true or false> - include held jobs or not
  • JOB_QUEUE_STATUS_READY=<true or false> - include ready jobs or not
  • JOB_QUEUE_STATUS_SCHEDULE=<true or false> include scheduled jobs or not
  • JOB_TYPE=<type> - job selection based on job type <type>.
  • JOB_TYPE_ENHANCED=<number> - job selection based on the enhanced job type <number>
  • SERVER_TYPE=<type> - job selection 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:

exclude.<Text>.<Identifier>.<before|after>[.equal]=<Parameter Name>
VariableDescriptionValues
TextDescriptive TextFree form combination of characters 0-9, A-Z, a-z.
IdentifierThe date-property of the job to match on.Date, JobActiveDate, JobDate, JobEndedDate, JobEnterSystemDate, JobPutOnJobQueueDate, ScheduleDate
beforeafterbefore or after.
[.equal]Also exclude those jobs equal to the date.

Parameter NameA String or DateTimeZone parameter. String parameters will either be in a fixed format (date and time only), or converted. If a parameter called <Parameter Name>_Format also exists, it will contain a SimpleDateFormat. If a DateTimeZone or Format parameter is used then the time zone on the DateTimeZone will be ignored since the AS/400 system does not support time zones as such.

Identifiers correspond to get<XXX>Date() methods on Job:

Class Job - IBM JavaDocs

If any exclusion rule matches a job it is excluded.

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 a second parameter named P_DATE_FORMAT containing a SimpleDateFormat. This makes it easier to use date functions from the Redwood Expression Language in the P_DATE parameter.

Activate tracing

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

[Action]
action=trace.dynamic
category.<name>=<AnyValue>
  • <name> - one of All, Conversion, Datastream, Diagnostic, Error, Information, JDBC, PCML, Proxy, Thread, Warning will depend on JTOpen version, look for com.ibm.as400.access.Trace.set<Name>On(boolean)
  • <AnyValue> - value should be set to enabled for readability, any value, including true, false and yellow, means 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 don't 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 - this should be overridden using the process definition Run As User.
  • The AS400Server parameter - this 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 can't start with AS400, as this is reserved for the connector. These parameters can be used to substitute values inside the script text, using ${name}. Substitutions are only valid inside values, not keys (for example 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.

The AS400User Parameter and the Run As User

The Run As User can be used to override the default values specified by the process server parameters of the same name. The Run As User is either specified as Username/Password or Username (in this case a credential must exist for this user and Endpoint the hostname (AS400Server process server parameter value, usually the FQDN of the AS/400 server). The password part of this parameter will automatically be encrypted when you save it. The encrypted value starts with {RedwoodSecureStorage}.

The 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 if 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 as that does not override the process server parameter.

Process Server ParameterDescriptionOverride KeywordSource Section
AS400JobAppendDefault job control options (appended to the end of the SBMJOB command). This parameter controls how the output is written to the output file. Set the value to true if you want the output to be appended to the output file; if you set this to false, the output file will be overwritten.Append[JobControl]
AS400JobExitedOkExceptionsExceptions treated as OK (separated by commas).ExitedOkExceptions[JobControl]
AS400JobFailOnActiveStatusStates to deliberately fail on (separated by commas).FailOnActiveStatus[JobControl]
AS400JobIgnoredExceptionsAS/400 exceptions to be ignored (separated by commas).IgnoredExceptions[JobControl]
AS400JobIndependentQPJOBLOGRetrieve QPJOBLOG independently of output queue settings?IndependentQPJOBLOG[JobControl]
AS400JobLanguageLanguage used in the AS/400 system (en, de, nl).Language[JobControl]
AS400JobLogLevelDefault log level for the stdlog file.LogLevel[JobControl]
AS400JobMaxWaitMaximum time to wait for the job to complete (seconds).MaxWait[JobControl]
AS400JobOperatorMessageReplyAllow operators to reply to AS/400 messages from the corresponding operator message.OperatorMessageReply[JobControl]
AS400JobOperatorTraceFull operator trace output?OperatorTrace[JobControl]
AS400JobParseLogNotesParse messages in the log file into job notes.ParseLogNotes[JobControl]
AS400JobSecondaryQueueListList of IFS paths of output queues to check for output files.SecondaryQueueList[JobControl]
AS400JobSpoolBannerDefault banner prefixed to the spool. Parameter substitutions use @{name}. You can use \t and \n for tabs and new lines.SpoolBanner[Output]
AS400JobSpoolMaxSizeSpool files larger than this will not be retrieved (bytes).SpoolMaxSize[Output]
AS400JobSpoolMFRTYPMDLDefault Printer for Spooling Output (Manufacturer, Type, and Model).SpoolMFRTYPMDL[Output]
AS400JobSpoolRemoveControlCharactersRemove control characters from job spools?SpoolRemoveControlCharacters[JobControl]
AS400JobSpoolWSCSTDefault workstation if the MFRTYPMDL is set to *WSCST (default). May be explicitly set to null to be ignored.SpoolWSCST[JobControl]
AS400JobTerminalStatesStates that signal the end of the job (separated by commas).TerminalStates[JobControl]
AS400JobUseQueueCriteriaInclude the output queue in the criteria when searching for output files.UseQueueCriteria[JobControl]
AS400JobUseTimeCriteriaInclude the job start and end times in the criteria when searching for output files.UseTimeCriteria[JobControl]

Examples

Examples of submitting AS/400 Jobs

Submit a DSPJOB Job:

DSPJOB

Pass a Parameter Value to an AS/400 job:

WRKOUTQ OUTQ(${outputqueue})

Submit a Job, Configure log Retrieval for 10 Mb, Maximum:

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

Submit a job, raise 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

Examples of file actions

List files and subdirectories (requires a filename parameter on the process definition)

This is used 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

Create Files (requires process definition parameter PATH):

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

Result

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

Delete files (requires process definition parameter PATH):

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

Result

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

Note that this will complete regardless of whether the file was deleted. An operator message will be raised if the file cannot be deleted.

AS/400 Resources

See Also

← Files on AS/400 Raise EventsRedwood Server OS Support →