ctmloadset

The ctmloadset utility records current resource usage on an Agent computer in the Resource Pools table (previously named the Quantitative Resources table). This utility is typically invoked by a cyclic job that runs on the Agent computer and measures usage of a certain resource on the computer. Usage data is then used to update the Resource Pools table on the Control-M/Server computer.

ctmloadset is used when load balancing is implemented. The load‑balancing algorithm uses the data recorded in the Resource Pools table to determine to which Agent computer a job should be submitted.

Control‑M maintains the following information about usage of each resource pool:

Total Used: Units of the resource currently in use. This parameter represents the sum of the values specified in the other two rows of this table.
Used by ControlM: Units of the resource currently in use by jobs submitted by Control-M/EM database.
Used by Others: Units of the resource currently in use by nonControlM jobs.

Update resource usage values in the Resource Pools table in either of two ways:

Specify the value for Total Used for a resource. ctmloadset subtracts the value for Used by ControlM from the value you specify and places the remainder in the field Used by Others.
Specify the value for Used by Others for a resource. This value is added to the value Used by ControlM to calculate the value Total Used for the resource.

Values for the utility can be expressed as an absolute number of units or as a percentage of the total number of units defined (Max value).

The utility’s output is displayed as type Q rows in the Resource Pools window. However, the Mem Name field remains blank since this represents usage by one or more non‑Control‑M jobs.

Updating a Resource Pool Using the ctmloadset Utility

This procedure describes how to run the ctmloadset utility, which enables you to record current resource usage on an Agent computer in the Resource Pools table.

Begin

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.
  
  You can also run this utility in Control-M Agent by navigating to where Control-M/Agent is installed.
Type the following command to invoke the ctmloadset utility:

ctmloadset {TOTAL|OTHERS} <Resource name> <loadValue>[%]

ctmloadset Parameters

The following utility lists the ctmloadset parameters:

Parameter	Description
TOTAL	Indicates that the load value provided specifies the total usage of the resource by all jobs—both Control‑M jobs and non‑Control‑M jobs. When this option is specified, the utility calculates the usage of the resource by non‑Control‑M jobs and updates the table accordingly.
OTHERS	Indicates that the load value provided specifies the units of the resource used by one or more non‑Control‑M jobs.
<Resource Name>	Name of the resource pool to update.
<loadValue>	Number of units of the resource currently used. When % is specified, the amount of the resource currently used, expressed as a percentage of the maximum available units defined for this resource pool.

ctmloadset Example

A host group contains three Agent computers: Diana, Jacklin and Ruby. Each computer is defined in the resource pool table as having 200 units of resource CPU_load, representing the load on the computer’s CPU.

computer Jacklin is used exclusively to run jobs submitted by ControlM. The computer is currently executing a job that uses 120 units of resource CPU_load.
computer Ruby is used exclusively to run jobs submitted by ControlM. The computer is currently executing a job that uses 150 units of resource CPU_load.
computer Diana is used both for ControlM and nonControlM jobs. The computer is currently executing a job submitted by ControlM that uses 75 units of resource CPU_load.

A cyclic job is defined to run periodically on Diana to measure the total load on the CPU. The job updates the Resource Pools table using the ctmloadset utility to indicate to Control‑M exactly what the load is on that computer. The last run of this job determined that the load on the CPU is 80% of total capacity. The job invokes ctmloadset as follows:

ctmloadset TOTAL CPU@Diana 80%

The Total Used for Diana is set to 80% of 200, or 160. Since the usage by Control‑M jobs is currently 75 units, ctmloadset calculates that the "Other" (non‑Control‑M usage) is 160 - 75, or 85.

As a result, the Resource Pools table now contains the following values:

Resource	Max	Total used by Control-M	Total used by others	Free
CPU@Jacklin	200	120		80
CPU@Ruby	200	150		50
CPU@Diana	200	75	85	40

The Control‑M load‑balancing algorithm uses these values when determining where to submit the next job.

ctmloadset Example Represented by the ecaqrtab Utility

The following examples demonstrate the effect of ctmloadset on the Resource Pools table, as represented by the display generated by the ecaqrtab utility. All examples below are based on the following premise:

For Agent computer Diana, 30 units of resource CPU@Diana are currently used by Control‑M jobs.

The output from the ecaqrtab utility is as follows:

Resource Name	Type	Max-Avail	Reserved	Used	Free
CPU@Diana	L	50	0	30	20

The following command specifies that the current usage of the resource pool CPU@Diana by non‑Control‑M jobs is 12 units:

ctmloadset OTHERS CPU@Diana 12

As a result, the output from the ecaqrtab utility is now as follows:

Resource Name	Type	Max-Avail	Reserved	Used	Free
CPU@Diana	L	50	0	42	8

The following command specifies that the current usage of the resource pool CPU@Diana by non‑Control‑M jobs is 12%:

ctmloadset OTHERS CPU@Diana 12%

The non‑Control‑M usage of the resource is calculated as 12% of 50, or 6 units. As a result, the output from the ecaqrtab utility is now as follows:

Resource Name	Type	Max-Avail	Reserved	Used	Free
CPU@Diana	L	50	0	36	14

The following command specifies that the current total usage of the resource pool CPU@Diana by all jobs is 48 units:

ctmloadset TOTAL CPU@Diana 48

As a result, the output from the ecaqrtab utility is now as follows:

Resource Name	Type	Max-Avail	Reserved	Used	Free
CPU@Diana	L	50	0	48	2