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.

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 (passwordA secret combination of characters for a Automation Engine user. 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"

Value	Login check for jobs	Login check for file transfers	File-access check for file transfers with the login's UserID	File-access check for file transfers with the agent's UserID
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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.

Nagle algorithm usage for file transfers and all the agent's other sockets.

Allowed values: yes (default value) and no

no = Activates the Nagle algorithm.
yes = This procedure is not applied.

Activating the Nagle algorithm can improve the performance of file transfers, especially if you transfer many small files.

The BS2000 agent always uses the Nagle algorithm. Therefore, it does not include this INI-file parameter.

Note that this parameter should only be set in close cooperation with Automic Support!

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.

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.

Default value: "No"

Allowed values: "Yes" or "No"

• 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.
• 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.

(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

(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.

Maximum length of messages (in bytes) that the agent accepts.

Default value: 500 000

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)

Assignment of an agent's name to its address (DNS name or TCP/IP address) if it cannot directly be accessed through the address that is stored in the server. Specify several assignments line by line, there is no upper limit for the number of assignments.

In file transfers, the sending agent obtains the destination agent's internal address from the Automation Engine. The sending agent replaces this internal address by the external address that is defined here.

This setting is only required if you run file transfers with agents that cannot directly establish a TCP/IP connection between each other by using the address that they have received from the Server. This can happen if the agents that are involved in the file transfer are located on different networks or if a firewall is used.

(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