Getting Started with the zOS Agent

Requirements for Starting the Agent

There are two ways to start the TA Agent for z/OS, from OMVS or from a Started Task script. Each has its own prerequisite that must be configured to be successful.

OMVS

The TSO user starting the TA Agent for z/OS from OMVS must be configured for a minimum of 1024000 of virtual storage. The user can configure the SIZE parameter by logging onto TSO and specifying the parameter on the TSO logon screen. For example, tso tidal size(1024000).

Note: If starting the agent from OMVS, ensure that the user account has an OMVS segment defined in their profile and sufficient privileges to access and manipulate the z/OS file system directories used by the agent.

Started Task Script

If starting the TA Agent for z/OS from a Started Task script, the started procedure must have the parameter REGION=ØK specified on the EXEC statement. This parameter enables the Java Virtual Machine to start with the necessary virtual storage.

With either method, OMVS or Started Task script, the user starting the TA agent must have Operator Level Authority because the agent inherits the user’s level of authority during startup and running of the agent.

Authority Requirements

To run a job in z/OS, the TA agent for z/OS must be started by a user with Operator Level Authority since the agent inherits the user’s level of authority during the startup and running of the agent. If any of the user rights listed below are missing, then the TA agent cannot successfully launch, track and manage the completion of a job.

The Operator Level Authority must include the rights to run these commands:

  • JES Commands

    $DJ (JES Display Job command)

    $CJ (JES Cancel Job command)

    $TOJ,Q (Change MSGCLASS)

    $OJ (Release Held output)

  • MVS Commands (In SYSPLEX, these commands may be ROUTED)

    D J (MVS Display Job command)

    RESET job, A=<address space>, QUIESCE and RESET (Suspending/Resuming Jobs command)

  • SYSPLEX Operator Commands (routed from the TA Agent to support SYSAFFINITY)

    ROUTE sys, D J, job (MVS Display Job command)

    ROUTE sys RESET job, A=asid, quiesce (Suspending Job command)

    ROUTE, sys RESET job, A=asid, resume (Resuming Job command)

Note: The ROUTE command is used in conjunction with D J and the two RESET commands so that the command is executed on the appropriate subsystem or LPAR.

Assigning APF Authorization to TA Agent Files

During the installation process, the TA installation script automatically assigns APF authority attributes to specific TA agent library files.

However, when a patch or an updated file replaces the original installation files, the APF authority is typically removed and needs to be reassigned to the agent files. Verify the APF authority attributes for the TA agent files with this procedure:

Note: The command to APF authorize libraries should be used with caution. It should only be used during installation and as advised by technical support.

To assign APF authorization:

  1. Log in and navigate into OMVS.

  2. Go to the agent’s lib/ZOS directory.

  3. List the files in the command prompt by typing:

    ls –E

    These files require APF authority:

    <agent dir>/lib/ZOS/mvslnk
    <agent dir>/lib/ZOS/tjb

    • If either of these two files do not display the “+ap” attribute, then you must reassign the APF authorization to that file. (You should also verify that the other permissions and the group are correct for these files). Reassign the APF authorization, by typing this at the command prompt, replacing <filename> with the name of the file extattr +aps <filename>.

    • If necessary, change the group for the file by entering this at the command prompt, replacing <filename> with the name of the file:

    chmod 6750 <filename> 
    chgrp <grp> <filename>

Viewing the Status of Agent Instances

To view the status of an agent, go to the bin directory and enter ./tagent <agent name> status.

Starting and Stopping Agents

From the bin directory, you can start or stop an agent by entering at the command prompt:

./tagent <agent name> start

OR

./tagent <agent name> stop

You can use a Started Task script to automate agent startup during IPL. Refer to Started Task Script of this manual for more information.

Note: Stop the z/OS agent before rebooting the master. We recommend that you add the agent stop command to a system shutdown script to be used when restarting the system.