ctmpsm

The ctmpsm utility performs functions affecting jobs or conditions in the active jobs database of the data center. It provides an alternative to using the Control‑M and enables you to perform many of the GUI functions directly in the data center. For command line invocation, see ctmpsm ctmpsm Utility Command Line Parameters.

The functions in this menu are divided into the following categories:

  • Active Jobs database functions provide various views of the Active Jobs database. Each view displays information about the jobs and provides options to perform such actions on the jobs as Hold, Free, Delete, Rerun, Why, Confirm, View or modify job details, and view the Control‑M log.

  • Resource Map functions enable you to view and modify Resource pools, lock resources, and prerequisite conditions. The first three of these functions activate the ecactltb, ecaqrtab, and ctmcontb utilities respectively.

  • Scheduling Functions enable you to order or force SMART folders or specific jobs in SMART folders. You can also generate monthly or yearly scheduling plans using the ctmrpln utility.

    If long names have been used for the In condition, jobname, override path, file_name, and doclib parameters, these values will be truncated in the output of the ctmpsm utility. To view the complete values for these parameters, use Control‑M. The following special characters are disabled when they occur in prerequisite condition names: ( ) | [blanks]

All Active Jobs database options display the following menu at the bottom of the screen:

Copy 
H) Hold, F) Free, D) Delete, U) Undelete, R) Rerun, W) Why, Z) Details
LO) LogOrd, LJ) LogJob, Cn) Confirm, Sx) Sort[x: 1.ORDERNO 2.JOBNAME]
J) Output A) Statistic V) View Script/JCL K) Force OK I) Dependencies 
Jobs Gx) Global action x [x:, H (Hold), F (Free), D (Delete), 
U (Undelete), R (Rerun)]
Q) Quit
Enter Option:

These actions are described in ctmpsm Active Jobs Database Actions.

Running the ctmpsm Utility Interactively

This procedure describes how to run the ctmpsm utility, which enables you to display the Control‑M Production Support menu.

Begin

  1. Do one of the following:

    • UNIX: Log in to a Control-M/Server account

    • Windows: Open a command prompt window where Control-M/Server is installed.

    In Control-M/Agent you can invoke the utility from the Control-M/Agent home directory.

  2. To run the utility interactively, type ctmpsm

    The Production Support Menu appears.

    If you want to invoke the utility through the command line, type ctmpsm-<parameter>. For more information about the command line parameters, see ctmpsm utility command line parameters.

ctmpsm Active Jobs Database Options

The following table lists options that are used to perform various tasks using information in the Active Jobs database:

Code

Option

Description

1

List All

Lists all jobs in the Active Jobs database and indicates if they are associated with a SMART folder (TBL) or Sub Folder (STB).

2

List All
(Show Started/Ended)

Lists all jobs in the Active Jobs database. Indicates which jobs have started or ended execution.

3

List All
(Show Application)

Lists all jobs in the Active Jobs database. Indicates the application to which each job belongs.

4

List All
(Show File Name)

Lists all jobs in the Active Jobs database. Indicates the File Name for each job.

5

List Jobs That
Ended OK

Lists jobs in the Active Jobs database with a completion Ended OK status.

6

List Jobs That
Ended NOTOK

Lists jobs in the Active Jobs database that have a completion Ended NOTOK status.

7

List Submitted/
Executing Jobs

Lists jobs in the Active Jobs database that are currently executing.

8

List Cyclic Jobs

Lists jobs in the Active Jobs database that are cyclic.

9

List Jobs Waiting for Time Window

Lists jobs in the Active Jobs database that are waiting to begin executing based on their Time From parameter.

10

List Jobs Waiting for Confirmation

Lists jobs in the Active Jobs database that are waiting for confirmation.

40

List Application/Sub-application Tree

Displays a summarized list of the applications and sub-applications for all jobs currently contained in the Active Jobs database.

41

List SMART folders

Displays a list of all SMART folders in the Active Jobs database.

42

List Ordered SMART folders

Displays a list of all ordered SMART folders in the Active Jobs database.

ctmpsm Active Jobs Database Actions

The following table lists actions you can perform on ctmpsm active jobs database options:

Option

Action

Description

H

Hold

Holds a job.

F

Free

Frees a previously held job.

D

Delete

Marks a job for deletion.

Jobs with Executing or Submitted status cannot be deleted.

U

Undelete

Undeletes a job marked for deletion.

R

Rerun

Rerun a job. Rerun actions cannot be performed on a sub application.

W

Why

Displays why a job has not yet been submitted.

Z

Details

Enables you to view or modify (zoom and save) the job parameters.

When a job is being viewed, it is automatically held. After changes are made and saved, the job is freed.

If prerequisite conditions are added to or deleted from a job in the Active Jobs database using the Z option, the changes are automatically saved when you quit.

If a cyclic job is terminated by a Do Stop Cyclic,
-dostopcyclic, or DO ACTION="SPCYC" parameter, the view will contain Cyclic:T where T indicates Terminated.

LO

LogOrd

Lists Control‑M log entries for a specific Order ID.

LJ

LogJob

List Control‑M log entries for a specific Job Name.

Cn

Confirm

Confirms submission of a job.

S1

Sort (by Order No.)

Sorts jobs displayed by Order number.

S2

Sort (by Job Name)

Sorts jobs displayed by Job Name.

J

Output

Displays the job OUTPUT.

A

Statistic

Displays the job statistics

V

View Script/JCL

Enables you to view the job script or JCL.

This option is available if Control-M/EM database is active.

K

Set to OK

Sets the status of a job to OK.

I

Dependencies Jobs

Displays all jobs that depend on the specified job.

GH

Global Action (Hold)

Holds all jobs in the displayed list.

GF

Global Action (Free)

Frees all jobs in the displayed list.

GD

Global Action (Delete)

Marks all jobs in the displayed list for deletion.

GU

Global Action (Undelete)

Undeletes all jobs marked for deletion.

GR

Global Action (Rerun)

Reruns all jobs in the displayed list.

Rerun actions cannot be performed on a group entity.

The R (Rerun) option and the Global options (GH, GF, GD, GU, and GR) affect only jobs and not SMART folders.

Resource Map Options

The following table lists resource map options for the ctmpsm utility:

Code

Option

Description

61

Lock Resources

Lists the Lock resources currently used in the Active jobs database. Activates the ecactltb utility.

62

Resource Pool

Allows you to list, add, modify, or delete the Resource Pool in the Active jobs database. Activates the ecaqrtab utility.

63

Prerequisite Conditions

Allows you to view, add or delete prerequisite conditions in the Active jobs database. Activates the ctmcontb utility.

64

Lock Resources Usage

Shows the current Lock resource usage by jobs in the Active Jobs database.

65

Resource Pool Usage

Shows current Resource pool usage by jobs in the Active Jobs database.

Scheduling Function Options

The following table lists scheduling function options for the ctmpsm utility:

Code

Option

Description

71

Folders

Lists SMART folders and jobs defined in the Control‑M/Server database. Allows you to force SMART folders or jobs, add or delete SMART folders and generate scheduling reports.

72

Order Folders/Jobs

Allows you to order SMART folders or jobs. You are prompted to specify:

  • SMART folder

  • Job Name (optional)

  • Odate (YYYYMMDD/ODAT)

  • Odate_option (VALUE_DATE|RUN_DATE) [VALUE_DATE]

  • Hold Option (Y|N)

For more information about ordering jobs and SMART folders, see ctmorder

ctmpsm Folder Option Output Example

When the Folders option is selected, output similar to the following is displayed:

Copy 
Folders
 ----------------------
 Folder name           Daily name                             Folder type
1)  tab_1                                                       SMART folder
2)  temp                                                        REGULAR
3)  inventory                                                   SMART folder
4)  Payroll              Monthly  
5)  inventory            SYSTEM                                 SMART folder
6)  RE_OUTPUT            output                                 REGULAR
D#) Delete UserDaily Folder #          U#) Update folder #
F#) Force folder            #          J#) List jobs    #
A)  Add.          R) Remove Folder     Q)  Quit.
Option []:

ctmpsm Options for Scheduling Functions

The following table lists options for the scheduling functions:

If a folder that is associated with more than one Order method is modified using Control‑M/EM and then uploaded to Control-M/Server, that folder is removed from all User dailies except the one that is associated with it in Control‑M/EM.

Code

Option

Description

A

Add

Adds an order method to an existed folder. When selected, you are prompted for the Folder name and Order method name.

D#

Delete UserDaily Folder #

Removes an instance of a Folder from the Control‑M/Server database.

If the specified instance is the only instance of the folder (that is, that folder is ordered by only one order method), the Folder and all its associated jobs are deleted.

If the specified instance is not the only instance of the folder, then only the specified instance is removed from the Control‑M/Server database.

F#

Force folder #

Forces a specific Folder (for example, specify F6 to force folder RE_OUTPUT).

J#

List jobs #

Lists content of a folder and provides options to force a specific job or Sub Folder or generate a report (for example, specify J1 to list the jobs in folder supply).

R

Remove Folder

Deletes a specific Folder and all its associated jobs (for example, specify R RE_OUTPUT to delete folder RE_OUTPUT).

U#

Update folder #

Updates the Order method name for a specific Folder (for example, specify U6 to update the Order method name for folder RE_OUTPUT).

ctmpsm Options in the SMART folder List Jobs Menu

The following table lists options in the SMART folder List Jobs menu:

Code

Option

Description

F#

Force job #

Forces a specific job (for example, specify F2 to force job DAYS_30_FEB).

M#

Month Schedule Plan

Generates a monthly Job Order report for the folder. You are prompted to enter the year and month in format YYYYMM.

Y#

Year Schedule Plan for job #

Generates a yearly Job Order report for a specific job. You are prompted to enter the year in format YYYY.

Values in STATE and STATUS ctmpsm Fields

The following table displays the values that are listed in the STATE and STATUS fields when ctmpsm is executed:

Value

Description

STATUSES

OK

The job completed okay.

NOTOK

The job did not complete okay.

STATES

Wait Sche

The job is waiting to be scheduled.

Wait Conf

The job is waiting for user confirmation.

Wait Reru

The job is waiting to be rerun.

Wait Time

The job is waiting for its time frame.

Wait Cond

The job is waiting for a condition.

Wait Reso

The job is waiting for a resource.

Wait Host

The host(s) to which the job is being submitted is unavailable, either because of host's restriction, or because of network availability.

Wait Workload

One or more of the workloads with which the job is associated has reached its maximum jobs limit policy.

Submitted

The job was submitted (that is, the job was sent to an Agent).

Retry Sub

The job is waiting for a submission retry.

Executing

The job is executing.

Ended

The job has ended.

Analyzed

The job is being analyzed.

Disappear

The job has disappeared in the Agent.

Post proc

The job has performed its post processing activities.

Wait ODAT

The job is waiting for the appropriate ODAT.

Post ODAT

The appropriate ODAT of the job already passed.

Unknown

The status of the job is unknown.

ctmpsm Utility Command Line Parameters

The following table lists the valid values for each parameter of the ctmpsm utility command line interface:

Parameter

Description

CHILD

Lists dependent jobs with IN conditions that are created by the job whose order ID is specified in this command.

ctmpsm -CHILD <order_ID> [<tasktype>]

order_ID:Identifies the parent job.

tasktype:

  • B: Batch job

  • D: Detached

  • C: Command

  • U: Dummy

  • X: External job

IMPORT_CAL

Imports a calendar from the Control‑M/EM.

ctmpsm -IMPORT_CAL <ECS exported file name> [overwrite]

<ECS exported file Name> is the full path name of the calendars file to be imported from Control-M/EM.

The file must be imported from Control‑M/EM in XML mode only.

If overwrite is specified, when the specified calendar to be imported from Control‑M/EM already exists in the Control-M/Server database, the import action will overwrite it. Default: overwrite is not specified.

There is a line of output for every calendar handled by the import_cal option.

After a successful import of a calendar, the following message is displayed:

Calendar <x>, for year <y>, has been imported.

Assume calendar <x>, that is being imported, already exists in the Control-M/Server database, and that the overwrite option has not been specified. The following message is displayed:

Calendar <x>, for year <y>, that already exists, has not been imported.

LISTCAL

Lists available calendars. The list can be restricted by calendar name and year.

ctmpsm -LISTCAL [<calendar name>][<calendar year>]

  • <calendar name>: Restricts the list to calendars with the specified name or prefix, indicated by * at the end.

  • <calendar year>: Restricts the list to calendars for the specified year.

LISTALL

Lists jobs in the Active Jobs database. The list can be filtered by time, application, and member name. The list can be sorted by order ID or job name.

ctmpsm -LISTALL [<ODAT|TIME|APPLICATION|FILENAME|ALL|ALLFIELDS_ALLFIELDS_FULL]
[-SORT {ORDERID|JOBNAME>]

In addition to the order ID and the job name, one of the following fields must also be included in the LISTALL output:

  • ODAT: Order date.

  • TIME: Time execution started and ended.

  • APPLICATION: Application to which the job belongs.

  • FILENAME: File name for the job.

  • ALL: – Includes ODAT, FROMTIME and UNTIL fields.

  • ALLFIELDS: Includes ODAT, FILENAME, and APPLICATION fields.

  • ALLFIELDS_FULL: Includes ODAT,FILENAME, APPLICATION fields and full size for the JOBNAME column.

  • –SORT: Indicates the order in which the jobs should be listed. Valid values: ORDERID and JOBNAME.

    The following additional job statuses are visible only when using the LISTALL option:

    • WAIT_ODAT: The Job’s Odate is later than the Control-M/Server working date for the relevant timezone. The job is waiting for the relevant day (Odate) to begin.

    • POST_ODAT: The job’s Odate is earlier than the Control-M/Server working date for the relevant timezone. The job will be deleted during the next run of the New Day procedure.

    These job statuses are used in the Control‑M/Server Active Jobs database. However, in Control‑M/EM, jobs with these statuses will appear with Wait Condition status. In non-interactive mode, WAIT_Condition and WAIT_CONFIRM are both displayed as Wait Con.

LISTJOB

Lists jobs that are cyclic, as well as jobs in the Active Jobs database with a specified status. Jobs can be filtered by status: OK, NOTOK, executing, waiting for the end of a time interval, waiting for confirmation.

ctmpsm -LISTJOB
<OK|NOTOK|EXECUTING|CYCLIC| WAITTIME|WAITCONFIRM}
[-SORT {ORDERID|JOBNAME>]

  • OK: Jobs with a completion Ended OK status.

  • NOTOK: Jobs with a completion Ended NOTOK status.

  • EXECUTING: Jobs that are currently executing.

  • CYCLIC: Jobs that are cyclic.

  • WAITTIME: Jobs waiting to begin executing based on the time specified in their Time From parameter.

  • WAITCONFIRM: Jobs waiting for confirmation.

  • –SORT: Indicates the order in which the jobs should be listed. Valid values: ORDERID and JOBNAME.

LISTSUB_APPLICATION

Lists jobs in the specified Sub Application that are associated with a Specified Application.

ctmpsm -LISTSUB_APPLICATION <application> <sub application>> [<scheduling date>]

Wildcard characters can be used as part of the specified application or sub-application names, as follows:

  • *: represents any number of characters.

  • ?: represents any single character.

LISTAJFFLD

Lists jobs in the Active Jobs database that were ordered from the specified SMART folder.

ctmpsm -LISTAJFFLD <folder name>

Wildcard characters can be used as part of the specified application or sub-application names, as follows:

  • *: represents any number of characters.

  • ?: represents any single character.

FOLDER

Lists SMART folders and jobs defined in the Control‑M/Server database, and allows you to add or delete SMART folders.

ctmpsm -FOLDER

<LISTFOLDER <folder name>|-UPDATE <row number> <udaily name>|

-ADD <folder name> <udaily name>|-DUDAILY <row number>|

-REMOVE <folder name>|-LISTJOBS <row number> [FULL]

  • -LISTFOLDER: Lists all instances of SMART folders that match the specified name or mask.

    If a SMART folder is ordered by two different user dailies, that folder will appear twice in the output of this option.

    Wildcards can be used as part of the folder name for this option.

    • *: represents any number of characters.

    • ?: represents any single character.

  • -UPDATE: Updates the User Daily name for a specific SMART folder.

  • -ADD: Adds a User Daily to an existing folder. The Folder name and Order method name must be specified when this option is used.

  • -UDAILY_NAME: Removes an instance of a SMART folder from the Control‑M/Server database.

    If the specified instance is the only instance of the folder (that is, that folder is ordered by only one order method), the SMART folder and all its associated jobs are deleted.

    If the specified instance is not the only instance of the folder, then only the specified instance is removed from the Control‑M/Server database.

  • -REMOVE: Deletes a specific SMART folder and its associated jobs.

  • -LISTJOBS: Lists jobs in a SMART folder.

LISTOUTPUT

List the OUTPUTs for an order ID. The list can be restricted by runcount number.

ctmpsm -LISTOUTPUT <orderID> [OUTPUTNUMBER {<number>|ALL}]

These parameters are described below.

To define a viewer to which the display of the OUTPUT of a job is redirected, specify the CTMPSM_VIEWER parameter in the ~<controlm_owner>/ctm_server/data/config.dat file. For more information about the CTMPSM_VIEWER parameter, see System configuration.

  • order_ID: Identifies the job whose OUTPUTs are listed.

  • number: Restricts the list to the OUTPUT whose runcount is specified. If ALL is specified, the output will contain only a list of all OUTPUTs related to the specified order ID.

LISTDETAILS

Lists the details of the job associated with the specified order ID.

LISTDETAILS <orderID>

LISTFULLDETAILS

Lists the parameters of a specified job in the Active Jobs database. In addition to the data provided by LISTDETAILS (above), LISTFULLDETAILS provides data about In conditions, Out conditions, and Variable values. (LISTFULLDETAILS was added for use with the "Zoom and Save" option in WebAccess.)

ctmpsm -LISTFULLDETAILS <orderID>

UPDATEAJF

Performs a specified command or updates conditions for a job in the Active Jobs database that is associated with a specified order ID.

ctmpsm -UPDATEAJF <orderID> <command>

The command is one of the following:

  • HOLD: Set the status of a job to HELD.

  • FREE: Free a previously held job.

  • DELETE: Mark a job for deletion.

    Jobs with Executing or Submitted status cannot be deleted.

  • UNDELETE: Undelete a job marked for deletion.

  • RERUN: Rerun a job.

  • CONFIRM: Confirm submission of a job.

  • SET TO OK: Set the status a job to be OK.

    SET TO OK can only be applied to inactive jobs (that is, jobs that are not running).

  • STATISTICS: Display a job’s statistics.

  • CONDADDIN <cond> <date> <AND|OR>: Add the specified IN condition with the specified date reference. You can include one or more additional IN conditions by using the AND or OR conjunctional parameter.

  • CONDADDOUT <cond> <date> <+|->: Add the specified OUT condition with the specified date reference. Use + to indicate that the condition must be present. Use - to indicate that the condition must not be present.

  • CONDDELIN <cond>: Delete the specified IN condition.

  • CONDDELOUT <cond>: Delete the specified OUT condition.

    Conditions specified using this mode apply only to the specified instance of the job in the Active Jobs database. Subsequent orders of that job are not affected.

UPDATESUBAPPLICATION

Applies a specified command to jobs in the specified Sub Application that are associated with the specified Application.

ctmpsm -UPDATESUB_APPLICATION <application> <sub application> <command>

<command> is one of the following:

  • HOLD: Set the status of a job to HELD.

  • FREE: Free previously held jobs.

  • DELETE: Mark the jobs for deletion.

  • UNDELETE: Undelete the jobs marked for deletion.

  • CONFIRM: Confirm submission of the jobs.

UPDATEFOLDER

Applies a specified command to jobs in the Active Jobs database that were ordered from the specified folder.

ctmpsm -UPDATEFOLDER <folder> <command>

<command> is one of the following:

  • HOLD: Set the status of a job to HELD.

  • FREE: Free previously held jobs.

  • DELETE: Mark the jobs for deletion.

  • UNDELETE: Undelete the jobs marked for deletion.

  • RERUN: Rerun the jobs.

  • CONFIRM: Confirm submission of the jobs.

XML

Lists jobs in the Active Jobs database in XML format. The job output formats can be changed according to the specified parameter, such as order date, time, application, or member name can be added to the output.

ctmpsm -XML [{ODAT|TIME|APPLICATION|MEMNAME|ALL|ALLFIELDS}]
[-SORT <ORDERID|JOBNAME>]

To list jobs in the Active Jobs database in XML format, specify ctmpsm -XML plus at least one of the following fields:

  • ODAT: Order date.

  • TIME: Time execution started and ended.

  • APPLICATION: Application to which the job belongs.

  • FILENAME: File name for the job.

  • ALL: Includes ODAT and TIME fields.

  • ALLFIELDS: Includes ODAT, FILENAME, and APPLICATION fields.

In addition, you can specify the following:

  • –SORT: indicates the order in which the jobs should be listed.
    Valid values:

    • ORDERID

    • JOBNAME

To change the output format in the Active Jobs database according to the file name of the job, specify the following:

ctmpsm -XML FILENAME

To sort the list in Example 1 above according to job name, specify the following:

ctmpsm -XML FILENAME -SORT JOBNAME

To display the most recent OUTPUT of the job whose order ID is 1234, specify the following command:

ctmpsm -listoutput 1234

To display the second OUTPUT of the job whose order ID is 1234, specify the following command:

ctmpsm -listoutput 1234 -outputnumber 2