Defining a normal STM object

The majority of objects that TOM manages are normal objects. Generally, TOM starts a normal object when MVS initializes and the object runs for the life of the IPL. This section describes how to specify the required fields using the object add or edit dialog in the TOM user interface (UI) to define a simple normal object, and also provides some tips for some often-used fields that are not required.

Note

These procedures do not show how to enter values for every field in the object add or edit dialog. Every field in the object add or edit dialog has online help.

To find more information about any field (from minimum to maximum field lengths or recommendations for values), position the cursor on the field and press PF1 or the HELP key. The help is displayed in pop-up windows that overlay part of your screen.

To specify a name for a normal object

Enter the ADD primary command on the TOBJ view.The Specify Object Name and Managed ObjectType dialog is displayed.
                 Specify Object Name and Managed ObjectType
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE


  Enter the name of the Object:
  BBPLEX01.SJSC.TSO

Specify managed object type:
  S STM Started Task Management
  _ UPM USS Process Management
  _ WRM WLM Resource Management
  _ GSM Generic Stateless Mgmt


Next - Next step
CANcel - Cancel dialog
HELP - Display help for step
(required) In the Enter the name of the Object: field, specify a name for the object.
This is a required field; values can be 1 to 64 characters long (including blanks) and you can use mixed case letters. You cannot use the following characters in the object name:
- a plus sign (+) as the object name
- a slash (/) anywhere within the name of the object
Tip
You should plan an object naming standard for defining objects in your system such as:
sysplex_name.system_name.object_name
This example procedure defines the TSO object that will run in a sysplex named BBPLEX01 and on a system named SJSC. The following shows the object name that uses this naming pattern:
BBPLEX01.SJSC.TSO
Use system_name.stc_name for non-moveable objects (one Valid System List entry)
Use sysplex_name.stc_name for moveable objects (multiple VSL entries).
Select the object type of STM Started Task Management for an MVS object, UPM USS Process Management.
The TSO object in this example is an STM Started Task Management object.
To proceed to the next panel in the dialog, enter NEXT. in the COMMAND line.
The Specify General Object Information panel is displayed.

To specify general information

The fields on the Specify General Object Information panel are all optional. This section describes recommended values that help identify the object and can define which systems TOM can manage the object.

(optional) In the Description field, enter a brief description of the object.
                     Specify General Object Information
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

General Information
  Description:
  Short Name:
  Pattern:

    Valid systems: 1
  Affinity to primary system:   High   Med    Low

    Schedules: 0
    Calendar Overrides: 0

  Transient:   Yes

  MdlFrom:
  Is this a model:   Yes

    Suspend Options: None
  Reinstate at IPL:    Yes
    IPL count:
    Verify reinstatement:   Yes
    Default reply:   Yes   No    Var
    Timeout:                                   (hh:mm:ss/var)

  IPL Level:          (? for defined list)

  Cmd console name:                                   (name/var)
(optional) In the Short Name field, specify a 1 to 8 character identifier for the object.
Tip
The Short Name value that you enter is an identifier that BMC AMI Ops Automation uses as part of the names of SHARED variables in the automation variable pool. These variables are useful if you decide to write additional automation (EXECs) for this object with the TOMEXEC API functions.
(optional) In the Valid Systems field, enter the ADD primary command to add the names of additional systems that this object can run on.
Tip
Every object must have at least one system in the Valid System List (VSL). By default, when you define an object, it will run of the system you are defining the object on. In this example, the add operation is being performed on SJSC; to make edits or additions to the VSL, you can do the following procedures:
- To change the default starting system for this object to another system, enter the E (edit) line command.
- To add additional systems that this object can run on to the Valid Systems list, enter the ADD primary command.
- To save your changes to the VSL, enter the END command.
The General Object Information panel is redisplayed.
The following shows an example of the Valid Systems panel with SJSC already entered because this is the system where the object is being defined.
                 Valid Systems
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Line commands: Edit, DELete, Up, Down, Top, Bottom

CMD I System   System Notes
--- - -------- --------------------------------
       SJSC     MVTOM Ready

ADD - Add new system
ALL - List all in sysplex
MERGE - Merge inherited records
END
CANcel
Help
To save changes to the Valid Systems list, enter the END command.The General Object Information panel is redisplayed.
To proceed to the next panel in the dialog, enter NEXT in the COMMAND line.
The Specify Started Task Information panel is displayed.

To specify started task information

The fields on the Specify Started Task Information panel are all optional. This section describes recommended values that can help TOM by providing information that TOM uses to determine the actual status of the object in the system.

(optional) In the Started Task name field, enter the STC (started task) name or jobname.
                 Specify Started Task Information
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Started Task Information
  Started Task name:   TSO                            (Variable permitted)
  Step name:                                          (Variable permitted)

  _ Start validations:   0
  _ Stop validations:    0
  _ ABEND validations:   0
Note that in this figure, TSO is entered by default as the Started Task name.
Tip
Although the Started Task name field is optional, you should either determine and enter a the correct job/STC name or, ensure a name is inherited from a model object. It is important for TOM processing that the started task object has the correct name so that TOM can perform automatic detection and also properly define events for the object. If you do not specify a name for the started task object, TOM might not be able to correctly manage the availability of the object.
(optional) In the Step name field, specify the step name of the started task.
Tip
Sometimes the started task name alone is not enough to uniquely identify an object in the system. If TOM will manage multiple definitions of the same started task in the system, you should also specify the object's step name in the Step name field.
(optional) Enter the E (edit) line command in the following fields to define start, stop, or abend validation events for the object:
- Start validations
- Stop validations
- ABEND validations
Tip
TOM uses the values that you enter in the Start, Stop and Abend validation fields to identify when an object starts, stops, or has abended.
By default, TOM defines a system entry event with the IEF403I message ID to determine that the object has started on the system so you do not need to explicitly define a start event. However, you must ensure that jobname monitoring messages are enabled so that TOM can detect IEF403I.
If messages are disabled, TOM sets the status of the object to FAILURE-REC-INIT when IEF403I is used as the start validation event.
To determine if jobname monitoring messages are disabled, enter the command DISPLAY OPDATA,MONITOR and examine the response. The example belows shows an a sample response:
RESPONSE=<sys-name>
CNZ1100I 12.30.46 MONITOR DISPLAY nnn
SPACE=OFF DSNAME=ON   TIMESTAMP=ON
MSGTYPE   SETCON MN NUMBER OF RECEIVERS
JOBNAMES OFF             0 CONSOLES
SESS      OFF             0 CONSOLES
STATUS    OFF             0 CONSOLES
Notice that for MSGTYPE JOBNAMES, SETCON MN is OFF and NUMBER OF RECEIVERS is 0 CONSOLES. This means that the messages are disabled.
TOM also defines a default end-of-memory (EOM) event for the object. Whenever the object stops, the EOM event notifies TOM that the object has stopped.
You can identify and define your own start, stop, or abend events for each normal object with these fields. Typically, there is no need to define stop validation events for an object.
After you enter the E line command in the Start validations field, the Startup Validations panel is displayed.

To specify startup event validations information

The fields on the Startup Validations panel are all optional. This section describes entering events that TOM uses to identify when an object has started on the system. This example shows entering the IKT005I message ID that when fired, signifies to TOM that the TSO object has started.

(optional) On the COMMAND line, enter the ADD primary command to add a start event for the object.
                 Startup Validations
COMMAND ===> ADD                                         SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Line commands: Edit, DELete, Repeat, Merge, Up, Down, Top, Bottom


CMD I STC                  Proc/Job             Type    ID or
       Name                 Step Name                    Queue
--- - -------------------- -------------------- ------- ----------------

ADD - Add new event
MERGE - Merge inherited records
LEFT - Scroll left
RIGHT - Scroll right
The Startup Validations panel is displayed.
                 Startup Validations
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Specify Event Type

  Type: _MSG   _ALRT _CMD   _JRNL
This example shows entering the IKT005I message ID that when fired, signifies to TOM that the TSO object has started.
(optional) Select the MSG event type in the Startup Validations panel.
                 Startup Validations
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Specify Event Type

  Type: SMSG _ALRT _CMD   _JRNL

Next
CANcel
Help
The Specify Startup Validation Message panel is displayed.
                 Specify Startup Validation Message
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Startup Validation Message Information

Message ID:        IKT005I
Originating STC:   &@STCNAME                      (required)
Proc/Jobstep:

Message:

* Value inherited from model
(optional) Enter the IKT005I message ID as the start event.
Tip
&@STCNAME is a special variable that TOM resolves and keeps internally, identifying the started task name.
Enter the END command to save the start validation event and return to the Startup Validations panel.
Enter NEXT in the COMMAND line to display to the Start Command Information panel.

To specify start command information

Most of the fields on the Specify Start Command Information panel are optional. This section describes entering a start command that TOM uses to start an object on the system, which is a required object attribute. This example shows entering the S (START) command that TOM will use to start the TSO object.

(required) On the Start commands field, enter the E (edit) line command to add a start command for the object.
                 Specify Start Command Information
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Object Start/Initiation Information

  _ Reset start count at term?:     Yes
  _ Reset start count after:               (hh:mm:ss)
  _ Restart only?:                  Yes

  Max start count:   3                    (0-99999)
  _ Start commands:         0
  _ Default Start cmd:                                 (variable allowed)
  _ Pre-Start commands:     0
  _ Start-retry commands:   0
  _ Post-Start commands:    0

  Verify start?:       Yes
    Default reply:     Yes   No    Var
    Timeout:                                    (hh:mm:ss/var)

State Detection

    Active Check Program:                              (Partial)
  Automatic Detection      No
Tip
The Max start count field allows you to specify how many times TOM issues the start command while attempting to start the object. Although this field is optional, a best practice is to specify a value greater than 1, thereby allowing TOM more than one attempt to start the object. In this example, the Max start count field is edited to 3 and TOM will make 3 attempts to issue the start command when starting this object.
In addition to specifying a Max start count value, you should also consider entering values for one (or both) of the following fields:
- Enter Yes for the Reset start count at term? field.
  This allows TOM to reset the command count to 3 after TOM stops the object and, TOM will have 3 attempts to start the object the next time.
- Enter a time period in the Reset start count after field.
  This also allows TOM to reset the number of start attempts to a value 3 after a period of time has passed.
By also entering either Yes or a period of time, or even using both fields together, TOM will always have the maximum number of start counts available when starting the object.
The Start Commands panel is displayed.
                 Start Commands
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Line commands: Edit, Repeat, Merge, DELete, Up, Down, Top, Bottom



CMD I Command (partial)
--- - -----------------------------------------------------------

ADD - Add new command
MERGE - Merge inherited records
LEFT - Scroll left
RIGHT - Scroll right
(required) Enter the ADD primary command
The Specify Start Command panel is displayed.
                            Specify Start Command
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Specify Command Information

Command type:   s MVS       EXEC      USS       AOSV
Timeout:          00:03:00                         (hh:mm:ss)
User Id:                                           (variable permitted)
Spawn job name:                                    (variable permitted)

Command label:                                     (? for OMODE List)

Description:

Command:

S TSO

* Value inherited from model
(required) Select the MVS option.
In this example, the command type to start the object is an MVS command.
(required) Enter a time in the Timeout field, using the format hh:mm:ss.
In this example, the time is 00:03:00. TOM will wait for up to 3 minutes after issuing the command before timing out.
If you specify (optional) start retry commands, TOM issues those retry commands (when the timeout value is reached) one at a time until TOM receives either the system entry event or the start event, signifying that the TSO object started. If TOM issues all of the start retry commands without successfully starting the TSO object, the TSO object will have a status of FAILURE-REC-INIT.
Tip
You can set a timeout value as low as 00:00:00. Note that with such a short timeout period, TOM expects the object to start and its status become ACTIVE almost immediately when the command is issued.
If TOM is processing a start request and the command is issued, TOM expects notification before reaching the end of the period. If TOM doesn't receive a notification, TOM issues a status of FAILURE-REC-INIT for the start request.
Therefore, you should carefully consider the timeout value. The best result will come when you have a clear idea about the time it takes for an object to start once the start command is issued.
(required) Enter a start command in the Command field.
In this example, the start command is S TSO (START TSO).
Tip
In this example, because the Started Task name field contains the value TSO, you can use the reference variable of &@STCNAME instead of the value TSO in this start command. This improves the flexibility of the object definition and can make administration of the object simpler.
To use &@STCNAME in this example use the following start command instead of S TSO:
S &@STCNAME
TOM resolves the &@STCNAME variable value when TOM issues the start command for the object.
Enter the END command to save the start command definitions and return to the Start Commands panel.
Enter the END command to return to the Start Command Information panel.
Enter NEXT in the COMMAND line to display to the Stop Command Information panel.

To specify stop command information

Similar to the specify Stop Command Information panel, most of the fields on the panel are optional. This section describes entering a stop command that TOM uses to stop an object on the system, which is a required object attribute. This example shows entering the P (STOP) command that TOM will use to stop the TSO object.

(required) On the Stop commands field, enter the E (edit) line command to add a stop command for the object.
                      Specify Stop Command Information
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Object Stop/Termination Information

  STOP in dependency order:     No
  Lock at next IPL:             Yes
  Shutdown quick:               Yes

    Stop commands:       0
    Default Stop cmd:
    Pre-Stop commands:     0
    Stop-retry commands:   0
    Post-Stop commands:    0

  Verify stop:          Yes
    Default reply:      Yes   No    Var
    Timeout:                                    (hh:mm:ss/var)

Object ABEND Information
    Recovery Commands:         0
  Move if object failure:        Yes
  Move if system failure:        No
The Stop Commands panel is displayed.
                 Stop Commands
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Line commands: Edit, Repeat, Merge, DELete, Up, Down, Top, Bottom



CMD I Command (partial)
--- - -----------------------------------------------------------

ADD - Add new command
MERGE - Merge inherited records
LEFT - Scroll left
RIGHT - Scroll right
END
CANcel
Help
(required) Enter the ADD primary command
The Specify Stop Command panel is displayed.
                             Specify Stop Command
COMMAND ===>                                              SCROLL ===> PAGES

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Specify Command Information

Command type:   s MVS       EXEC      USS       AOSV
Timeout:          00:03:00                         (hh:mm:ss)
User Id:                                           (variable permitted)
Spawn job name:                                    (variable permitted)

Command label:

Description:

Command:

P TSO

* Value inherited from model
(required) Select the MVS option.
In this example, the command type to stop the object is an MVS command.
(required) Enter a time in the Timeout field, using the format hh:mm:ss.
In this example, the time is 00:03:00. TOM will wait for up to 3 minutes after issuing the command before timing out.
If you specify (optional) stop retry commands, TOM issues those retry commands (when the timeout value is reached) one at a time until TOM receives either the EOM event or the stop event, signifying that the TSO object stopped. If TOM issues all of the stop retry commands without successfully stopping the TSO object, the TSO object will have a status of FAILURE-REC-TERM.

Tip
You can set a timeout value as low as 00:00:00. Note that with such a short timeout period, TOM expects the object to stop and its status change to STOPPED/LOCKED/BLOCKED almost immediately when the command is issued.
If TOM is processing a stop request and the command is issued, TOM expects notification before reaching the end of the period. If TOM doesn't receive a notification, TOM issues a status of FAILURE-REC-TERM for the stop request.
Therefore, you should carefully consider the timeout value. The best result will come when you have a clear idea about the time it takes for an object to stop once the stop command is issued.
(required) Enter a stop command in the Command field.
In this example, the start command is P TSO (STOP TSO) or, S &@STCNAME.
Enter the END command to save the stop command definitions and return to the Stop Commands panel.
Enter the END command to return to the Stop Command Information panel.
Enter NEXT in the COMMAND line to display to the Dependency & Client/Server Information panel.

To specify dependency and client/server information

Most objects will have a dependency on another object, meaning that the object will not start (or stop) unless another object is also started (or stopped). TOM keeps track of this dependency structure and uses it to start and stop objects in the correct order. From this panel, you can define the immediate parents of the object (that is, the object(s) that needs to be started before TOM starts this object).

(optional) On the Dependency field, enter the E (edit) line command to add a dependency definition for the object.
               Specify Dependency, Client/Server Information
COMMAND ===>                                              SCROLL ===> PAGE

Sysplex: BBPLEX01   DefBase: SAMPLE
Object: BBPLEX01.SJSC.TSO
Product: Started Task Management

Object Dependency Information
   Dependency:    0
   Dependency formula:                                     (Partial)
Parent strength:     STRONG   WEAK   Var

User Property Information
   User Properties:   0

Client/Server Information
   Servers:   0

User Attributes
User1:
User2:
User3:
User4:
User5:
User6:
User7:
User8:

   User Notes:                                    (Partial)
The Dependencies panel is displayed.
                 Dependencies
  COMMAND ===>                                              SCROLL ===>

   Sysplex: BBPLEX01   DefBase: SAMPLE
   Object: BBPLEX01.SJSC.TSO
   Product: Started Task Management

  Line commands: Edit, Merge, DELete, Up, Down, Top, Bottom


  CMD I Parent Object Name
  --- - ----------------------------------------------------------------

  ADD - Add new dependency
  MERGE - Merge inherited records
  LEFT - Scroll left
  RIGHT - Scroll right
  END
  CANcel
  Help
(optional) Enter the ADD primary command
The Specify Parent Property panel is displayed.
                          Specify Parent Property
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Dependency Information
Expression ID:            (Required for dependency formula)

Parent object or set name:

Child to Parent Dependency
   Strength:      STRONG   WEAK   Var

Parent actions for this child object:
                  Start     Stop     Restart

Property:   @STATUS (? for list)
On System:                                    (variable allowed)

  Condition:   S EQ   NE   LT   GT   LE   GE

Property Value:     (Enter ? below for list)
ACTIVE
(optional) Enter the name of a parent object or set in the Parent object or set name: field.
Tip
If you are not sure what to enter, you can enter a question mark (?) to display a list of objects you can choose from.
If the object depends on the parent having the status of ACTIVE, you can complete this panel by entering the property of @STATUS, the condition of EQ (equal), and the property value of ACTIVE.
Enter the END command to save the parent definition and return to the Dependencies panel.
Enter the END command to return to the Specify Dependency, Client/Server Information panel.
This is the last panel of the object add/edit dialog. Enter the END command to save the TSO object definition.The Confirm Object Definition Add panel is displayed.
Select Yes in the Proceed with Add?: and press Enter to confirm that you want to save the TSO object definition.
Confirm Object Definition Add
COMMAND ===>                                              SCROLL ===> PAGE

  Sysplex: BBPLEX01   DefBase: SAMPLE
  Object: BBPLEX01.SJSC.TSO
  Product: Started Task Management

Object Wizard Exit Confirmation:

  Proceed with Add?:            _ Yes _ No

ENTER - Terminate dialog
CANcel - Return to previous step
HELP
The TSO object definition is written to the registry. TOM redisplays the TOBJ view where you can view the newly added object.