IBM Support

Frequently Asked Questions about the Tivoli Storage Manager backend capacity-based licensing programs

Question & Answer


What are the Tivoli Storage Manager capacity-based licensing programs for backend and what are the typical questions or issues that occur when trying to perform a capacity license measurement?


The following FAQ questions and answers discuss common questions and solutions for issues relating to the IBM Tivoli Storage Manager "Suite for Unified Recovery" and "Suite for Unified Recovery - Archive Option" capacity licensing programs.


What are the IBM Tivoli Storage Manager capacity-based licensing programs?

IBM Tivoli Storage Manager provides three capacity-based pricing programs. These are referred to as “Suite for Unified Recovery” (SUR) and “Suite for Unified Recovery – Archive Option” (SUR-Archive). Additional details and explanation about each can be found at:

License ProgramLink
Note the following discussion in this document relates to the "SUR" and "SUR-Archive" licensing programs. The details about planning for and using the SUR-ProtectTier program are discussed in the document linked above.

What steps should I take to prepare for running the macro?
  • Read the information about the SUR and SUR-Archive programs to determine which is applicable and should be used. You can work with your IBM account team or sales specialist/representative to help understand which should be considered.
  • Download the appropriate macro(s) based on the license program. Consider that there are different versions of the macro depending upon the version of the TSM server.
    • Consider verifying that the downloaded macro looks correct by viewing it and comparing it to the example in this document.
  • If there is a non-production TSM server (test) in your environment, consider trying the macro on the test server to familiarize yourself with how it is invoked and used.
    • Consider verifying that the generated output is correct by comparing the output to the example in this document.
  • Plan to run the macro at a time when the server workload is light or when other administrative tasks are being performed.
Is is possible to do capacity-based license measurements for versions of the product that are no longer supported?

It is recommended that you upgrade your TSM servers to a supported version of the product. The table below also references how to download the capacity measurement macros for these no longer supported versions of the product.

How do I get the tool(s) that perform the capacity-based license measurement?

Macro NameUse For Server VersionUsed ByFTP Link
tsm_tb_cap_v5.macroV5.5SUR V5 Capacity Macro
tsm_tb_cap_v5_lite.macroV5.5SUR V5 Capacity Macro (Lite)
(See below for when and why to consider using this version of the macro for a V5.5 server)
tsm_tb_cap_v6.macroV6.1, V6.2SUR V6.1 and V6.2 Capacity Macro
tsm_tb_cap_v63.macroV6.3, V7.1, 7.1.1*SUR V6.3 and V7.1 Capacity Macro
tsm_ar_tb_cap_V63.macroV6.3, V7.1SUR-Archive V6.3 and V7.1 SUR-Archive Capacity Macro
tsm_tb_cap_v711_tgt.macroV7.1.1*SUR V7.1.1 Replication Target Managing Data Using Different Policies
tsm_tb_cap_v711_rc.macroV7.1.1*SURV7.1.1 Replication Source Manage Data Using Different Policies
*Note: TSM V7.1.1 introduces the ability for TSM servers that replicate data from a source to a target to manage the data using different policies at each site. The "tsm_tb_cap_v63.macro" should be used for V7.1.1 servers if TSM server to server replication is not being used or if replication is being used and the data is not being managed differently. If V7.1.1 is being used and replication is configured to use "DISSIMILAR POLICIES" (see command QUERY REPLSERVER), than the "tsm_tb_cap_v711_tgt.macro" and "tsm_tb_cap_v711_src.macro" macros should be used. The SUR link referenced in the question above ("What are the IBM Tivoli Storage Manager capacity-based licensing programs?") provides additional information about how to use these macros.

How do I download the macro from the FTP site?

How you download the macro from the FTP site will vary by your operating system and the browser that you are using. An example of how to do this is:

1. Click on the appropriate link from the table above.
2. For example the tsm_tb_cap_v6.macro, should appear as shown after downloading it. The example is only an excerpt and shows just the first 43 lines of the file. It is shown to illustrate the general layout and content of the macro.

3. From the browser, perform the “Save As” which is typically available from the “File” drop down menu on most browsers. It is recommended that it be saved as the name of the macro file so that the other instructions will reference the appropriate name.

For example, if you selected the macro “tsm_ar_tb_cap_v63.macro”, save this to your local disk as the same name (“tsm_ar_tb_cap_V63.macro”).

When performing the “Save As”, you want to only save the content of the page and not the HTML formatting or such that was applied when it was opened in the browser to view. On Mac OS, select “page source” to prevent saving it with the HTML tagging from the browser. From Windows, saving it as “Text Document (*.txt)” should be used as this will also prevent the HTML tagging from being embedded in the document.

4. To verify that you have done this correctly, you can open this in an editor and view the contents of the saved file and compare it to what was shown in the browser from step 2 above.

Note: The macro contains a number of lines that are many characters long and depending upon your editor settings, these may wrap (as shown above) or they may extend to the right and only be visible by scrolling to the right. It can be viewed either way, the important item is that the long lines are not broken up into many smaller lines with a “carriage return” or such imposed in the line.

What are the impacts or consequences of running the macro against my TSM server?

The macro is a TSM administrative command macro. It executes a number of SQL statements against the TSM server. The macro will require processing capacity (CPU) and memory from the TSM server. The SQL statements being run will read information from the TSM server’s database and as such it will generate I/O to the TSM server database and use memory for the database buffer pool and in-memory for the handling and processing itself.

For V6.1, V6.2, V6.3, or V7.1 servers, the SQL processing provided by DB2 is typically able to handle the resource needs of these SQL statements without issue. Notably, the statements usually run quickly on the order of minutes or tens of minutes.

For V5.5 servers, the SQL processing is highly dependent upon the CPU, memory, and I/O to the server database. In most cases, the macro is able to run in minutes, tens of minutes, or hours. In a few cases, we have seen that the macro takes many hours to run. The reason it can take a long time to run is that the SQL processing on V5.5 servers is not as efficient as what is available to the V6 and V7 TSM servers. It is also highly dependent upon the available system resources, so if the server is already near or exceeding its operational limits, than running the macro may take a long time.

For V5.5 servers, if the “tsm_tb_cap_v5.macro” macro is not able to complete or taking a long time to run, there is an alternate version of the macro available for use. See the topic in this document that discusses “What is the tsm_tb_cap_V5_lite.macro?” for more details on the purpose and use of this.

What is the “tsm_tb_cap_v5_lite.macro”?

This “lite” version of the macro reduces the complexity of the capacity measurement macro but it can only be used if the TSM server does not have any of the following types of data stored on it:

  • TSM server to server virtual volumes. This server cannot be a target for a TSM server to server virtual volume configuration.
  • TSM for Sharepoint or HSM for Windows. This server cannot store data from a TSM for Sharepoint or HSM for Windows clients or agents.
  • Data replicated from FastBack. This server cannot store data from a FastBack server replicating to this TSM server as a target.

If any of these types of data are being stored to this V5.5 server, then the “lite” version of the macro may not be used. If this V5.5 server is not storing any of these types of data, then the “lite” version of the macro can be used. Often times, it is able to run in less time and using less resources so it can complete in a shorter, more manageable timeframe.

The "tsm_tb_cap_v5_lite.macro" should be used for the following circumstances:

  • The V5.5 TSM server is already overloaded with regards to workload or available resources. For example: The server is at or near the limits of the resource capacity (CPU, memory, I/O) or the daily workloads (client data ingest, server maintenance) are taking all or most of the time available in a 24 hour window to complete.
  • The "tsm_tb_cap_v5.macro" has been tried but it takes too long to run, ran and never completed, or fails to run in this V5.5 TSM server environment.

How do I get the macro on the machine (system) where my TSM server is running?

If the system the TSM server runs on has access to the internet and the FTP link to the appropriate macro, then the macro can be accessed and saved directly from the FTP site to that system.

If the system the TSM server runs on does not have access to the internet, then the appropriate macro needs to be saved to your local environment and then transferred to the system where the TSM server is running. This can be done using file transfer tools like FTP, scp, WinSCP, or many other techniques or tools.

The macro file is simply a text file. It should be transferred from machine to machine as just a normal text file. It does not require any special handling such as to transfer it as “Binary” or such.

How do I run the macro?

The macro is run from a command prompt and uses the administrative command line client. The macro should be invoked using the following command syntax:

      dsmadmc -id=<yourid> -password=<yourpassword> -dataonly=yes -outfile=<output_file_name> macro <macro_name>

The input parameters that must be specified by the administrator when this is executed are the items enclosed in '<' and '>' respectively. The specific input parameters are:

  • <yourid> - This is the administrative user id that will be used to connect to the server.

  • <yourpassword> - This is the password for the administrative user id that will be used to connect to the server.

  • <capacity_file_name> - The results from the macro will be stored to this file. Select an appropriate file name use. For example, consider using the server name such as "server1.capacity".

  • <macro_name> - The name of the macro to be run which is tsm_ar_tb_cap_v63.macro.

An example of how the macro would be invoked against a Unix, Linux, or AIX server using an xterm (or equivalent) type of interface is:

Note: The macro is invoked from the command line administrative client being run in batch mode. The macro should not be run from the command line administrative client in interactive mode.

What is the output of the macro?

The macro writes its output to the file designated by the “-outfile=…” parameter when it is invoked. See the topic “How do I run the macro?” for more explanation about how to invoke (run) the macro. An example output report for a V6 server is:

This is the general format of the report. For V5.5 servers, the “Deduplication Benefits” section simply references that TSM offers deduplication in newer versions of the product and it does not otherwise report a value. In this example, 42 TB is not being counted in the capacity measurement because the data was deduplicated and this is the savings result from the elimination of that duplicate data.

The “Details on Excluded Data” section will vary depending upon what exclusions are found. If there is no data of a specific type identified and excluded, then nothing is shown in the report. In this example, the server is using storage pools of TYPE=COPY or TYPE=ActiveData. In this case, 51 TB is identified and excluded from measurement.

This example is provided as a “guide” to understand what a typical report looks like. If the output of the macro differs significantly from what is shown this usually indicates that the macro was not correctly run. The typical reason for a significant difference in the formatting of this report is that the macro was run from the command line administrative client in interactive mode instead of being run from the system command line and using the administrative client in batch mode.

What do I do if the value reported from the macro seems wrong or incorrect?

Contact IBM service. Please provide the following information:

  • Identify the server where you are seeing the incorrect or unexpected result.
  • Provide the macro that was run to create the capacity report with the value in question:
    • Include information about the command syntax that was used to invoke the macro.
  • Provide the created capacity report that contains the value in question.
    • This is the output file specified from “-outfile=…” parameter when the administrative command line client was invoked to run the macro.
  • Collect and provide the following data from the TSM server:

[{"Product":{"code":"SSGSG7","label":"Tivoli Storage Manager"},"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Component":"Server","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"5.5;6.1;6.2;6.3;7.1;7.1.1","Edition":"All Editions","Line of Business":{"code":"LOB26","label":"Storage"}}]

Document Information

Modified date:
17 June 2018