z/OS Agent

system=

Name of the AE system.
This entry must be identical to the entry made in the Automation Engine's INI file.

name=

Name of the agent.

The agent name is limited to 32 of the following characters: A-Z, 0-9, _, ., $, @, - and #.

The host name is used instead if this parameter remains undefined. Lowercase letters are converted to uppercase letters.

Hyphens ("-") are only allowed in agent names. They must not be used in the names of any other objects.

Language that should be used for the logging. You can specify a primary and a secondary language.

Allowed values: "E", "D", "F"
Default: "E,D" (primary English, secondary German)

If there is no message in the primary language, the system searches for a message in the secondary language.

The number signs serve as placeholders for a series in numerical order. Log files are renamed at agent start so that the most current log file always has the number "00".

If you comment this parameter, the log file is stored in JES. Refer to the parameter logpurgeclass= which is described below.

The following parameters can be added when the log is written to a dataset (after the dataset name and separated by semicolons):

"recfm" = (all 27 z/OS plus * and A record formats are valid)
"lrecl" = (0, each positive number up to 32760 and X for each reclen)
"blksize" = (0, each positive number up to 32760)
"space" = ([CYL,TRK],(prim,sec,directory))

logpurgeclass=

MVS Sysout class for log files.

Allowed values: A-Z and 0-9
Default value: "A"

This parameter can be used to route log files to the specified MVS Sysout class.

The Sysout class is only considered when the parameter logging= is commented (";").

The parameter logcount= is important for the routing log files. The number of log files that is defined in this parameter is created. The oldest log file is routed to the Sysout class if this number is exceeded.

For example:

The parameter logcount= is set to 3. The first log file is routed to the Sysout class when the fourth log file is created.

helplib=

Name of the message file.

Allowed values: "ALL" (default value), "NONE", "CONTROLS"

"ALL" = The complete message file is held in the RAM.
"NONE" = Always read message file from the hard drive.
"CONTROLS" = All language dependent strings that are necessary for displaying a dialog program are held in the RAM (does not apply to agents).

Allowed values: "1" to "9"
"1" to "9" = Agent's license class

askRACF=

Verification of the access authorizations with RACF for jobs and file transfers before the agent starts (password verification for the user of the job/file transfer and dataset authorization check in file transfers). Doing so generates more accurate agent error messages and avoids useless task starts if there is no appropriate authorization. The security system checks the running job in any case.

You can deactivate this entry with the value "0" if no RACF is installed on this host.

Allowed values: "0" to "15"
Default value: "7"

Values

"0" - no verification

"1" - Login check for jobs

"2" - Login check for file transfers

"3" - Login check for jobs and file transfers

"4" - File access check for file transfers with the Login's userid

"5" - Login check for jobs and file access check for file transfers with the Login's userid

"6" - Login check for file transfers and file access check for file transfers with the Login's userid

"7" - Login check for jobs and file transfers and file access check for file transfers with the Login's userid

"8" - File access check for file transfers with the Agent's userid

"9" - Login check for jobs and file access check for file transfers with the Login's userid

"10" - Login check for file transfers and file access check for file transfers with the Agent's userid

"11" - Login check for jobs and file transfers and file access check for file transfers with the Agent's userid

"12" - File access check for file transfers with the Login's and Agent's userid

"13" - Login check for jobs and file access check for file transfers with the Login's and Agent's userid

"14" - Login check for file transfers and file access check for file transfers with the Login's and Agent's userid

"15" - Login check for jobs and file transfers and file access check for file transfers with the Login's and Agent's userid

completeJobout=

This parameter determines the complexity of the job protocol.

Allowed values: "0" (default value), "1"

"0" = Only JES statistics (JESMSGLG, JESJCL and JESYSMSG) are stored in AE.
"1" = The entire job protocol (JES statistics+ job output) is stored in AE.

 This setting can be overruled in the Job object and in the script using attributes. More detailed information is provided in the document that describes message classes.

Allowed values: "0" (default value), "1"

"0" = The job log remains in the JES without changes.
"1" = The job log is deleted from the JES.

 This setting can be overruled in the Job object and in the script using attributes. More detailed information is provided in the document that describes the message classes.

relMsgClass=

This parameter releases the job log for printing.

Allowed values: "0" (default value), "1"

"0" = The job log is not released.
"1" = The job log is released for printing.

 This setting can be overruled in the Job object and in the script using attributes. More detailed information is provided in the document that describes message classes.

getMsgClass=

Message classes that should be read and routed.

Enter one or several message classes. Examples: "A", "ABC", "X1". You can use any order.

 This setting can be overruled in the Job object and in the script using attributes. More detailed information is provided in the document that describes the message classes.

routeMsgClass=

Message classes to which the class should be routed.

After the transfer to the AE, the job log can also be routed to the specified message classes (e.g., for an Output Management System).

Enter one or the number of message classes specified in the parameter getMsgClass=. The correct order is significant.

For example:

The following message classes are read: "ABC"
and routed to: "DEF"

Class "A" is routed to "D", "B" to "E" and "C" to "F".

This setting can be overruled in the Job object and in the script by using attributes. More detailed information is provided in the document that describes the message classes.

jes=

Job Entry Subsystem (JES) that has been installed on the host.

Allowed values: "JES2" (default value), "JES3"

jobACF2=

This parameter generates the job card in ACF2 format.

Allowed values: "0" (default value), "1"

"0" = There is no job-card generation in ACF2 format.
"1" = The job card is generated in ACF2 format.

userid_type=

This parameter provides an additional way of allowing or rejecting access to certain users.

Allowed values: "INCL", "EXCL"

"INCL" = Access must be granted to each individual user under [USERID].
"EXCL" = Users who are specified under [USERID] are excluded. All other users can start jobs.

Allowed values: "0", "1" (Default value)

"0" = No parentheses are used for the accounting information
"1" = Parentheses are used for the accounting information

jobCancel=

This is a command that serves to cancel jobs and is sent to the console.

Allowed values:

$C &01 = The job name is inserted at position &01.
$C &02 = The JobID in JOB12345 format is inserted at the position &02 (default value).
$CJ&03 = The JobID in 12345 or 1234 format is inserted at the position &03.

All settings support 5,6 and 7 digit JobIDs.  

jobOutputAllocation=

Allocation of the job's output (first extent cylinders, secondary cylinders).

Format: (number of cylinders, number of cylinders)

Default value: (1,1)

The parameter "jobSubmitContext=" can be set to one of these values:

AGENT (default): The Job is submitted to the internal reader in the agent context.

USER: The Job is submitted to the internal reader in the context of the Job user specified in the Login object used in the Job.

Format: string

vanishedRetry=

If the agent runs across a status change or an erroneous attempt to retrieve the status while checking a job (rarely occurs), the job's status cannot clearly be determined. This parameter can be used to specify how often the agent retries to check the status before it reports the status  "ENDED_VANISHED".

Allowed values: 0 - 9999
Default value: "6"

waitSpoolRetry=

Repetition of the waiting time (see parameter waitSpoolReady)

Allowed values: 0 – 99
Default value: "6"

waitSpoolReady=

Waiting time for the spool in hundredths of seconds.

Occasionally, it can take a while until the spool is available. This happens when the agent runs in a Parallel Sysplex on a different LPAR. You can use this parameter to extend the waiting time.

Allowed values: 0 – 9999
Default value: "50"

WaitOnJobEnd=

Waiting for the job's end.

By default, the agent waits until the job is available in the output queue or disappears. Occasionally, the job has already ended but cannot be found in the output queue because it is still waiting for a system event (e.g. tape swapping). Use this parameter to define whether the agent should check the job's end status after it has ended. If the job is not found in the output queue, it is monitored via the periodical job checking.

Allowed values: "0" and "1" (default value)

"0" - The agent does not wait.
"1" - The agent waits for the job to end.

ignoreEmptyJCL=

Handling of blanks in JCL.

Allowed values: "0" and "1" (default values)

"0" - The JCL remains the same
"1" - The agent automatically removes blanks in the JCL before it is processes.

ft_temp_file=

Creates temporary files in file transfers.

Allowed values: "yes" and "no" (default value)

"yes" - The file obtains a temporary name which is composed of the dataset name of the file to be transferred plus a suffix. The suffix includes the letter"T" and an alphabetic string originating from the RUN#. The new file transfer additionally appends a file ID to obtain a unique file name because basically, only a RunID is provided. The file is renamed after it has been transferred.

The file immediately obtains its final name if the temporary file name would exceed the z/OS maximum of 44 characters.

"no" - The agent assigns the final file name when the file transfer starts.

The USS file system requires the parameter file_temp_file_uss to be used.

EventCheckIntervall=

Periodical event check in seconds

Default value: 3600

Do not specify the value too low in order to avoid a high server workload.

Usage of uppercase and lowercase letters in passwords.

Allowed values "0" (default) and "1"

"0" - The agent converts all passwords into upper-case letters.
"1" - The password remains unchanged.

Ensure that the password settings comply with those on your system as otherwise, the agent's login attempt will fail.

Default value: "Yes"

Allowed values: "Yes" or "No"

• Value "Yes": On starting the FileTransfer a switch inside the FileTransfer's thread will be executed to the user context of the user, whose data has been entered in the Login object, which is referenced in the FileTransfer object. Any input and output will be executed with the permissions of the user starting the FileTransfer.
• Value "No": The authorization of the user starting the FileTransfer will be checked, but the FileTransfer will be executed with the authorization of the user starting the agent.

The name and the path of the file that includes the authentication package (company-key file).

This parameter must be specified if you use the authentication methods "Server" or "Server and Agent". Any attempt to log in fails if the company-key file cannot be found.

When the agent starts, it reads the company-key file and stores its information in the file that is specified in the parameter KeyStore=. The first file is deleted afterward.

The name and the path of the file that includes the information of the authentication package (see parameter InitialPackage=).

If no file name and/or path is specified, the system uses the name (file ending *.kstr) or the path of the agent's INI file. If you define a file name, the ending *.kstr is not automatically appended.

The KeyStore file is created when the agent starts for the first time. You must not delete, rename or move it subsequently. Regardless of the authentication method that you use, any attempt to log in will fail if the agent cannot find this file when it starts. In this case, you must open the menu item "Renew transfer key" in the affected agent's System Overview.

[JCL Exit]

name=

Name of the JCL-Exit module based on Assembler.

The Assembler-based module is used when you do not specify the c-based JCL Exit (the parameter ExitModul= is missing or does not contain any value).

maxJclRecords=

Size of the output area.

Name of the DLL file of the JCL Exit module based on the programming language C.

The Assembler-based JCL Exit is used when you do not specify this parameter or when it does not include a value.

Name of the module's function that implements the JCL Exit.

It refers to the JCL Exit module that is specified in the parameter ExitModul=.

The agent calls this function before it runs the job JCL. If this function returns a code other than 0, the JCL will not be processed and the job aborts.

Default value: "jcl_exit"

Function that initializes the JCL Exit module (allocating memory, for example) and is called when the agent starts.

If this function returns a code other than 0, the c-based JCL Exit is deactivated.

This parameter is optional and refers to the JCL Exit module that is specified in the parameter ExitModul=.

Function that should be called when the agent ends in order to run final processes such as releasing memory).

This parameter is optional and refers to the JCL Exit module that is specified in the parameter ExitModul=.

[USERID]

Specification of authorized z/OS users in the format:
User name=START

Specification of non-authorized z/OS users in the format:
User name=NO_START

This section describes the parameters you have to set for checks which will determine, if and how a z/OS job shall be added to the Job Entry Subsystem (JES) queue.

The parameters don't guarantee that every job that is submitted to the JES (shows the status 'Active' in the AE) will immediately run, due to multiple reasons:

1. Nature of the checks:
   1. If the initiator check is only done on SYSPLEX level, jobs may be submitted even though no single system has free capacity.
   2. The duplicate job check doesn't take jobs into account which were submitted by other agents, processes or users.
2. Timing issues: It may happen that a resource becomes unavailable in the short time span between resource check and submission of the job.
3. Job routing: The resource checks don't take into account whether jobs will be routed to certain systems (due to SYSTEM/SYSAFF parameters) after submission.
   Example: The agent may find that the required scheduling environment is available on system A and submit the job, but due to the SYSAFF parameter the job is routed to system B where the scheduling environment is not available.

The default job class is inquired by the agent only once at startup (either from JES or from the INI parameter "defaultJobclass", if set).
This means that when the default job class is changed while the agent is running, the scheduling environment and initiator checks will not work correctly for jobs without specified job class.
The agent has to be restarted in this case for the checks to work properly again.

If you set this parameter to "YES", the agent doesn't submit a job to the JES if the scheduling environment job attribute is not available on any suitable system.
The evaluation sequence of this parameter is the following: SCHENV parameter in job definition panel, value of 'SCHENV=' in additional fields parameter, default SCHENV of specified or default jobclass of job.
In case no scheduling environment can be determined, the check will be ignored.

Allowed values: "YES" or "NO"

Default value is "NO"

If you set this parameter to "SYSPLEX" or "SYSTEM", the agent doesn't submit a job to the JES, if the Workload Manager (WLM) would not start a new initiator for the specified job class (respectively the default job class if no job class is specified in the job object). There are 2 levels of checking:

SYSPLEX - Agent checks if the Sysplex-wide XEQCOUNT current value is less than the maximum value.
SYSTEM - Agent performs a SYSPLEX check and additionally checks the XEQCOUNT values for each available Sysplex member.

Allowed values: "NO", "SYSPLEX" or "SYSTEM"

Default value: "NO"

If this parameter is set to YES, the agent doesn't submit a job to the JES, if a job with the same job name is already running.

This check only considers jobs with the same name which were earlier submitted by the agent itself. Jobs submitted by other agents and/or users of the system are not taken into account.

Allowed values: "YES" or "NO"

Default value: "NO"

If you set this parameter to "YES", a detailed explanation will be written to the agent's log file whenever a job is blocked.
This explanation is more detailed than the one in the remote status and job report.

Allowed values: "YES" or "NO"

Default value: "NO"

This detailed message enables users to analyze more easily why a job is blocked (for example the scheduling environment is available on a particular system, but on this system the maximum number of initiators has been reached).

Examples:

DUPLICATE(6988930,GAHTEST,J0966338)
Explanation: A job with the name GAHTEST, JobID=J0966338, RunNR=6988930 is already running.

SCHENV(REGTEST01,S901-A,S902-NA)
Explanation: REGTEST01 scheduling environment is available on S901 member, but not on S902.

INIT(CLASS=H,SYSPLEX(M=-1,C=2)),S901(M=1,C=1),S902(M=1,C=1))
Explanation: Even though sysplex is unlimited, WLM would not start a new initiator for job class 'H', because both systems are maximized for 1 and on each a job is currently running.

If defined, the value of this parameter will be used as default job class instead of inquiring the default job class from JES.

Format: Single alphanumeric character (optional)

[TRACE]

The number signs serve as placeholders for a series in numerical order. When you start a trace, the trace files are renamed so that the most current trace file always has the number "00".

The following parameters can be added (after the dataset name and separated by semicolons) if the log is written to a dataset:

"recfm" = (all 27 record formats of z/OS plus * and A are valid)
"lrecl" = (0, each positive number up to 32760 and X for each reclen)
"blksize" = (0, each positive number up to 32760)
"space" = ([CYL,TRK],(prim,sec,directory))

Allowed values: "0" (default value) to "9"

Trace flags must only be used in close cooperation with Automic Support.

trcmode=

Method used for the trace files.

Allowed values: "0" to "3"
Default value: "1"

"0" - The trace file is normally written.
"1" - All file buffers are written to the disk after each trace line.
"2" - Close/Open is used for the trace file after each trace line. Do not use this option in combination with FileSystem events because it causes an event for each line which can lead to recursive endless loops.
"3" - Trace outputs are also written to the log file.

[TCP/IP]

cp=

The address of the AE system's communication process to which the agent should connect.

Allowed formats:
DNS Name:Port number
TCP/IP Address:Port number

port=

The agent's port number .

Other agents and the Job Messenger use this port number to establish a connection to the agent.

bindaddr=

IP address or host name for the agent connection.

Use this parameter if the connection should be established via a particular IP address (e.g., if the computer has more than one network interface card).

Alternately, you can also specify the IP address or host name in port=
(Format: port=IP address:port or DNS name:port). Specifications made in bindaddr= are then ignored.

bindlocal=

Consideration of the local host (127.0.0.1).

This parameter is to be used in combination with bindaddr=.

Allowed values: "0" (default value), "1"

"0" - No listen socket is created.
"1" - An additional listen socket is created on the local host.

connect=

Time interval in seconds in which the agent tries to establish a connection to the Automation Engines (when rebooting or lost connection).

Default value: 120 seconds

This parameter only applies until the agent has successfully logged on to the AE system. Afterwards, the parameter RECONNECT_TIME (see host characteristics) is used.

report=

Time interval in seconds in which the agent sends the logging to the Automation Engine.

Default value: 60 seconds

connwait=

Time interval in seconds during which the agent waits for a communication partner response (CP or a different agent). If this time limit is exceeded, the connection to the communication partner is terminated.

Default value: 20 seconds

AsyncConnect=

The agent tries to connect to a communication process if the connection was lost. If it is not successful, it tries to log on to a different communication system after a particular waiting period. Automic recommends specifying AsyncConnect=1 which causes the waiting period to be reduced.

Size of the TCP/IP input buffer for messages that should be sent (Byte).

Default value: 262144 Byte

Size of the TCP/IP input buffer for messages that should be received (Byte).

Default value: 262144 Byte

Setting of keep-alive packets in order to maintain the connection between the agent and the event monitor.

Allowed values: "n" and "y" (default value)

"y" - Keep alive packets are sent.
"n" - Keep alive packets are not sent.

Specifies the maximum number of connection requests queued for the listening socket of the agent.

This parameter cannot be used to provide a higher number than the system parameter SOMAXCONN.

For example, if Listen=500 is set here, and the system parameter SOMAXCONN is set to 10, the maximum of 10 is used.

Therefore, it makes the most sense to set both parameters to the same value. The value depends on the number of parallel connections of messengers and file transfers. However, the recommended technique is to use the SMF based messaging technique rather than IP messenger.

For more information on the SOMAXCONN statement in the system's TCP/IP profile, see http://www-01.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.halz001/somaxconnstatement.htm.

[HOSTS]

[CP_LIST]

List of communication processes.

This list is created when the agent starts and it is extended when new communication processes are activated. More detailed information about establishing a connection is provided in the chapter Multi-Server Operation.

The communication process that is defined in the parameter cp= (section [TCP/IP]) is not included in the cp list.

Format:
Port number=DNS name
or
Port number=TCP/IP address