Maintaining Template Tables and Staged Tables Based on Adapter Changes :: SAS(R) IT Resource Management 3.21: Administrator's Guide, Second Edition

Working with the Maintain Staged Tables Wizard

About the Maintain Staged Tables Wizard

The data collectors on which template tables are based might change over time. These changes can require new columns in a template table or revisions to existing columns, such as label or character length. Therefore, when SAS IT Resource Management provides a new software release or update, the definitions for some template tables might also change. After a software update is installed, a preexisting staged table can differ from the new version of its corresponding template table.

The Maintain Staged Tables wizard enables you to perform the following tasks with software updates to template tables:

View updates that can be propagated to existing staged tables.
Commit updates to the corresponding staged tables within an IT data mart.
Commit updates to the corresponding staged tables across all IT data marts.
Add new columns and update existing columns to the corresponding staged tables.
Commit only updates that add new columns to the affected staged tables.
Commit only updates to the recommended columns in the corresponding staged tables.

If there are no staged tables to maintain, the HTML report is not produced.

Note: After operations with the Maintain Staged Tables wizard, you must redeploy any staging jobs that were updated. (Aggregation jobs do not require redeployment because the wizard does not affect the metadata of the aggregated tables.)

SAS IT Resource Management identifies affected template tables and their associated staged tables by the DataModelVersion field for each table. For example, a template table and a staged table are eligible for impact analysis and updates if the current DataModelVersion field of the table does not match the version that is associated with the software update.

For more information about using the Maintain Staged Tables wizard to maintain staged tables within an IT data mart, see Using the Maintain Staged Tables Wizard to Update Staged Tables within an IT Data Mart. For more information about using the Maintain Staged Tables wizard to maintain staged tables across all IT data marts, see Using the Maintain Staged Tables Wizard to Update Staged Tables across All IT Data Marts. For more information about maintaining staged tables using a batch process, see Maintaining Staged Tables in Batch Mode.

Using the Maintain Staged Tables Wizard to Update Staged Tables within an IT Data Mart

After you install software updates for SAS IT Resource Management, you can use the Maintain Staged Tables wizard to see whether any software changes to the template tables affect the staged tables that you use and propagate these template table changes to their corresponding staged tables. To do so, perform the following steps:

In the IT Data Marts tree view of SAS IT Resource Management, locate the IT data mart that contains the staged tables for which you want to view or commit updates.
Right-click the IT data mart and select Maintain Staged Tables to open the wizard.
Specify the scope of the operation that you want to perform with the Maintain Staged Tables wizard.

Note: If there are no staged tables to maintain, the HTML report is not produced.

Specify Scope of Operation Page in the Maintain Staged Tables Wizard
1. Select Commit updates with report to view a report of the template table changes that affect your staged tables and then commit the changes to the corresponding staged tables.
2. Select Create report only to view only a report of the template table changes that affect your staged tables but not commit the changes in this instance of the wizard.
3. Click Next.
Select an adapter for which you want to analyze the impact of table revisions that are available.

Note: This page is not displayed when accessing the wizard from a specific template table to commit updates across all IT data marts. For more information about using the Maintain Staged Tables wizard to maintain staged tables across all IT data marts, see Using the Maintain Staged Tables Wizard to Update Staged Tables across All IT Data Marts.

Specify Adapter Page in the Maintain Staged Tables Wizard
1. Click the adapter for which you want to analyze updates. The list of adapters includes all of the adapters that SAS IT Resource Management supports. However, you must select an adapter that is used in the IT data mart in order to complete the wizard successfully.
  
  Note: You can select only one adapter on this page and must perform updates for another adapter by using a separate instance of the wizard.
2. Click Next. If a message states that there are no staged tables that need maintenance, then there are no staged table updates required based on your selections and the latest software updates. You can close the message box and stop here. Otherwise, continue to the next step.
Select the staged tables for which you want to view changes or commit updates.

Select Staged Tables Page in the Maintain Staged Tables Wizard
1. Select the staged tables for which you want to analyze updates. The list of staged tables includes only the staged tables that are associated with the selected adapter.
  
  A tooltip is available for each staged table in the list. The tooltip shows the metadata path of the table in order to help distinguish between tables, especially tables that might have duplicate names.
  
  Note: If there are no updates to the template tables for the selected adapter, then the wizard displays a message to that effect.
2. Click Next.
Compare table updates with the previous value of the tables and columns and specify the commit options.

Impact Analysis Page in the Maintain Staged Tables Wizard
1. Expand the folders in the grid to view the version of the tables and the table columns that have been modified or added to the corresponding template tables. The rows in the grid include the table name, version, description, or columns that are affected by the update. This comparison list also shows previous values before the update and the corresponding new values after the update.
  
  New columns that are added to the template table display the previous value as blank because the column did not exist in the previous version. New columns are also preceded by an asterisk (*) in the HTML report that the wizard generates.
  
  Note: Within a specific table, columns are matched by SASColumnName and SASColumnType (numeric or character). Therefore, if a column's SASColumnName or SASColumnType has been changed by the user, the column might not be recognized as a supplied column. Also, if a supplied column needs to have its SASColumnName or SAS ColumnType changed in the supplied template table definition, then it is treated as a new column.
2. If you choose to commit the updates that are detailed on this page, select one or more of the following Update Options that enable you to refine the scope of changes that you commit:
  
  Add new columns as well as update existing columns commits all of the changes that are detailed on this page of the wizard. This option must be deselected for the other options to be available.
  
  Add only new columns commits only the new columns.
  
  Update only recommended columns commits only the updates that affect the recommended columns in the associated template tables. For more information about recommended columns in template tables and determining which columns are recommended for a given template table, see Columns in Template Tables.
  
  Note: The Update Options are interdependent and the availability of each option in this window depends on whether the other options are selected or deselected. For example, if Add new columns as well as update existing columns is selected, then the other options are not available. If this option is deselected, then the other options are available. Likewise, if Add only new columns or Update only recommended columns is selected, then Add new columns as well as update existing columns is not available for selection.
3. Click Next.
View a summary of the impact analysis and update options that you selected for the staged tables.

Summary Page in the Maintain Staged Tables Wizard
1. Review the summary and ensure that it reflects the specifications and result that you expect.
2. Click Finish. The wizard then generates an HTML report and saves it to your workstation.
  
  Note: If there are no staged tables to maintain, the HTML report is not produced.
  
  On the client, the report is located in a directory that is determined based on the APPDATA environment variable.
  
  On Windows XP, this location is typically C:\Documents and Settings\userid\Application Data\SASHome\SASITResourceManagement\3.21\MaintainTableReportYYMMDDHHMMSS.htm.
  
  On Windows 7, this location is typically C:\Users\userid\AppData\Roaming\SASHome\SASITResourceManagement\3.21\MaintainTableReportYYMMDDHHMMSS.htm.
  
  If you selected Commit updates with report previously in the wizard, then the metadata for the selected staged tables is updated immediately. The physical data sets for these tables are then updated when the associated staging jobs are run.
  
  Note: The data model version of the staged tables is updated and stamped only when you select both Commit updates with report and Add new columns as well as update existing columns in the wizard.

Using the Maintain Staged Tables Wizard to Update Staged Tables across All IT Data Marts

The Maintain Staged Tables wizard enables you to see whether any software changes to the template tables affect the staged tables that you use. You can also propagate these template table changes to their corresponding staged tables across all IT data marts at once. To do so, perform the following steps:

In the Folders tree view of SAS IT Resource Management, expand the following folders to locate the template table: ProductsSAS IT Resource ManagementAdapters <adapter name>IT Template Tables<domain category> that corresponds to the template table for which you want to propagate updates to its corresponding staged tables.
Right-click the template table and select Maintain Staged Tables to open the wizard.
Complete the Maintain Staged Tables wizard. When you access the wizard from a specific template table as described in the previous steps, you are able to view and commit staged table updates across all IT data marts instead of within a single IT data mart. For more information about how to complete the Maintain Staged Tables wizard, see Using the Maintain Staged Tables Wizard to Update Staged Tables within an IT Data Mart. This topic includes instructions for reading and completing each page of the wizard.

Maintaining Staged Tables in Batch Mode

About Maintaining Staged Tables in Batch Mode

In order to run the Maintain Staged Tables process in batch mode that you need to invoke the command from the server tier where the SAS IT Resource Management data tier has been installed. You cannot perform this action from a client install.

Note: You must use the Maintain Staged Tables wizard if you want to update selected staged tables that are affected by an update. The BatchMaintainTable command does not provide the ability to specify staged tables to update. For more information about maintaining specific staged tables, see Using the Maintain Staged Tables Wizard to Update Staged Tables within an IT Data Mart.

Perform the following steps to maintain the tables in a batch process:

Open a command prompt and enter the following command:
```
cd C:\Program Files\SASHome\SASITResourceManagementDataTier\3.21
```
Note: The locations that are specified in this and in other sections of the following instructions assume that you have installed SAS IT Resource Management to a SASHOME location of C:\Program Files\SAS.
Execute the BatchMaintainTable command, specifying options as required.

Tip
For best results, set all the options as needed but set the commit option to N. This setting produces a report that lists the actions that might be performed under the current settings of the command. However, if there are no staged tables to maintain, no HTML report is produced. After reviewing the report, if you are satisfied with the additions or updates that might be performed by using the options that you specified, simply change the commit option to Y and rerun the command.

Syntax for the Batch Maintain Table Command Line

BatchMaintainTable -Commit Y | N
-AdapterName “adapter-name”
<-ITDataMartName “ITDataMartName”>
<-TemplateTableName “TemplateTableName”>
<-AddAndUpdateColumns Y | N>
<-AddNewColumnsOnly Y | N>
<-UpdateRecommendedColumnsOnly Y | N>
<-profile profile>
<-user userID>
<-password password>
<-host hostname>
<-port port>
<-domain domain>
<-?>
<–help>

Note: The ITDataMartName and TemplateTableName parameters are mutually exclusive.

To invoke the BatchMaintainTable command, use the following code:

"C:\Program Files\Java\jre1.5.0_12\bin\java.exe"
   -Djava.system.class.loader=com.sas.app.AppClassLoader
   -Dsas.ext.config="C:\Program Files\SASHome\SASPlatformObjectFramework
                       \9.3\sas.java.ext.config"
   -Dsas.app.launch.config="C:\Program Files\SASHome
                              \SASITResourceManagementDataTier\3.21
                              \plugins\itrmdatatier\picklist"
   -Dsas.app.repository.path="C:\Program Files\SASHome
                                \SASVersionedJarRepository\eclipse"
   -Dlog4j.configuration="file:///C:\Program Files\SASHome
                                    \SASDataIntegrationStudioServerData\4.3
                                    \log4j.properties" 
   -Xmx1024m 
   -Xss1m 
   -classpath 
     "C:\Program Files\SASHome\SASVersionedJarRepository\
      \eclipse\plugins
      \sas.launcher.jar" 
   com.sas.solutions.itms.batch.maintaintable.BatchMaintainTable

Note: If you installed SAS IT Resource Management on the C: drive in Windows, the preceding locations should be used. If you installed in another location, adjust the preceding locations accordingly.

BatchMaintainTable Options

Note: The ITDataMartName and TemplateTableName parameters are mutually exclusive. When the command is entered, make sure that each option is preceded in the command line by a hyphen.

Commit Y | N

specifies whether to commit changes to the staged tables.
AdapterName “adapter-name”

specifies the adapter whose staged tables you want to update.

Note: Enclose adapter-name in double quotation marks.
ITDataMartName “IT-data-mart-name”

specifies the IT data mart where the adapter's staged tables are stored. This option is required if the TemplateTableName option is not set.

Note: Enclose IT-data-mart-name in double quotation marks.
TemplateTableName template-table-name

specifies the template table that you want to update. This option is required if the ITDataMartName option is not set.
AddAndUpdateColumns Y | N

specifies whether to add new columns and update all existing columns. If the AddAndUpdateColumns option is N then either or both of the AddNewColumnsOnly and the UpdateRecommendedColumnsOnly options should be set to Y.

Note: Setting this option to Y is recommended.
AddNewColumnsOnly Y | N

specifies whether to add only new columns. This option is required if the AddAndUpdateColumns option is not set to Y.
UpdateRecommendedColumnsOnly Y | N

specifies whether to update only recommended columns. This option is required if the AddAndUpdateColumns option is not set to Y.
profile profile

specifies the metadata server connection profile. This option can be used in place of the host, port, user, and password options.
user user-ID

specifies the user login identity. This option is required if the profile option is not set or if the profile does not contain connection credentials.
password password

specifies the user login password. This option is required if the profile option is not set or if the profile does not contain connection credentials.
host host-name

specifies the metadata server host. This option is required if the profile option is not set.
port port-number

specifies the metadata server port. This option is required if the profile option is not set.
domain domain

specifies the user authentication domain.
? (or -help)

prints help information.

Note: By default, running the BatchMaintainTable command always produces a report of the results unless there are no staged tables to be maintained. In that case, no HTML report is produced.

Examples of the Batch Maintain Table Command Line

Example 1

This example shows how to run the Batch Maintain Table command on Windows. The command examines the staged tables in an IT data mart called “My IT Data Mart” that were generated for the BMC Performance Manager adapter. Any new or changed columns that apply to the staged tables for the BMC Performance Manager adapter are not performed, but are included in the report that is produced by the Batch Maintain Table command.

 
"C:\Program Files\Java\jre1.5.0_12\bin\java.exe"
   -Djava.system.class.loader=com.sas.app.AppClassLoader
   -Dsas.ext.config="C:\Program Files\SASHome\SASPlatformObjectFramework
                       \9.3\sas.java.ext.config"
   -Dsas.app.launch.config="C:\Program Files\SASHome\SASITResourceManagementDataTier
                              \3.21\plugins\itrmdatatier\picklist"
   -Dsas.app.repository.path="C:\Program Files\SASHome\SASVersionedJarRepository\eclipse"
   -Dlog4j.configuration="file:///C:\Program Files\SASHome\
               SASDataIntegrationStudioServerData\4.3\log4j.properties" 
   -Xmx1024m 
   -Xss1m 
   -classpath "C:\Program Files\SASHome\SASVersionedJarRepository\eclipse\plugins
     \sas.launcher.jar" 
   com.sas.solutions.itms.batch.maintaintable.BatchMaintainTable 
   -Commit N 
   -Adapter "BMC Perf Mgr" 
   -ITDataMartName "My IT Data Mart" 
   -AddAndUpdateColumns Y
   -profile MyMetadataServerProfile

Example 2

This example shows how to run the Batch Maintain Table command in Windows. The command examines tables across all IT data marts on the application server that were generated for the BMC Performance Manager adapter and the PTCACHE template table. Only changes to the recommended columns are made. A report of these updates is produced.

"C:\Program Files\Java\jre1.5.0_12\bin\java.exe"
   -Djava.system.class.loader=com.sas.app.AppClassLoader
   -Dsas.ext.config="C:\Program Files\SASHome\SASPlatformObjectFramework
                       \9.3\sas.java.ext.config"
   -Dsas.app.launch.config="C:\Program Files\SASHome\SASITResourceManagementDataTier
                              \3.21\plugins\itrmdatatier\picklist"
   -Dsas.app.repository.path="C:\Program Files\SASHome\SASVersionedJarRepository\                                \eclipse"
   -Dlog4j.configuration="file:///C:\Program Files\
                  SASHome\SASDataIntegrationStudioServerData\4.3\log4j.properties" 
   -Xmx1024m 
   -Xss1m 
   -classpath "C:\Program Files\SASHome\SASVersionedJarRepository\eclipse\plugins
     \sas.launcher.jar" 
   com.sas.solutions.itms.batch.maintaintable.BatchMaintainTable 
   -Commit Y 
   -Adapter "BMC Perf Mgr" 
   -TemplateTableName PTCACHE 
   -AddNewColumnsOnly Y 
   -UpdateRecommendedColumnsOnly Y
   -profile MyMetadataServerProfile

Sample Batch Maintain Table Commands for Windows, UNIX and z/OS Operating Environments

Batch Maintain Table Command for Windows Operating Environments

"C:\Program Files\Java\jre1.5.0_12\bin\java.exe"
   -Djava.system.class.loader=com.sas.app.AppClassLoader
   -Dsas.ext.config="C:\Program Files\SASHome\SASPlatformObjectFramework
                       \9.3\sas.java.ext.config"
   -Dsas.app.launch.config="C:\Program Files\SASHome\SASITResourceManagementDataTier
                              \3.21\plugins\itrmdatatier\picklist"
   -Dsas.app.repository.path="C:\Program Files\SASHome\SASVersionedJarRepository
                                \eclipse"
   -Dlog4j.configuration="file:///C:\Program Files\SAS
                                    \SASDataIntegrationStudioServerData\4.3
                                    \log4j.properties" 
   -Xmx1024m 
   -Xss1m 
   -classpath "C:\Program Files\SASHome\SASVersionedJarRepository\eclipse\plugins
     \sas.launcher.jar" 
   com.sas.solutions.itms.batch.maintaintable.BatchMaintainTable 
   -host <host-name>
   -port (port-number)
   -user <userID>
   -password <password> 
   -domain DefaultAuth
   -Commit N 
   -AdapterName "<adapter-name>"
   -TemplateTableName <template-table-name>
   -AddAndUpdateColumns Y
   -AddNewColumnsOnly N
   -UpdateRecommendedColumnsOnly N

Note: Double quotation marks are needed in this command line wherever a part of an address (for example, “Program Files”) contains a space.

Batch Maintain Table Command for UNIX Operating Environments

This example is enclosed in a shell script. It was run on the H64 UNIX operating environment.

#!/bin/sh

export SASHOME=<full-path-to-SASHOME directory>
echo $SASHOME is $SASHOME
export DISPLAY=<hostname:displaynumber.screennumber>
echo DISPLAY is $DISPLAY

cd $SASHOME/SASITResourceManagementDataTier/3.21  

$JAVA_HOME/jre1.5.0.08/bin/java \ 
-Djava.system.class.loader=com.sas.app.AppClassLoader \
-Dsas.ext.config=$SASHOME/SASPlatformObjectFramework/9.3/sas.java.ext.config \ 
-Dsas.app.launch.config=$SASHOME/SASITResourceManagementDataTier
                        /3.21/plugins/itrmdatatier/picklist \ 
-Dsas.app.repository.path=$SASHOME/SASVersionedJarRepository/eclipse \ 
-Dlog4j.configuration="file://$SASHOME/SASITResourceManagementDataTier
                              /3.21/log4j.properties" \ 
-Djava.awt.headless=false \ 
-Xmx1024m \ 
-Xss1m \ 
-classpath $SASHOME/SASVersionedJarRepository/eclipse
           /plugins/sas.launcher.jar \ 
com.sas.solutions.itms.batch.maintaintable.BatchMaintainTable \ 
-host <metadata-server-hostname> \
-port <metadata-server-port-number> \
-user <unrestricted-metadata-server-userID> \
-password <password-for-specified-user> \
-domain DefaultAuth \ 
-Commit N \ 
-AdapterName "BMC Perf Mgr" \ 
-TemplateTableName PTCACHE \ 
-AddAndUpdateColumns Y \ 
-AddNewColumnsOnly N \ 
-UpdateRecommendedColumnsOnly N

Batch Maintain Table Command for z/OS Operating Environments

This example is enclosed in a shell script. It was run on the z/OS operating environment.

#!/bin/sh

echo JAVA_HOME is $JAVA_HOME
export SASHOME=<full-path-to-SASHOME-directory>
echo $SASHOME is $SASHOME 
export DISPLAY=<hostname:displaynumber.screennumber>

echo DISPLAY is $DISPLAY

cd $SASHOME/SASITResourceManagementDataTier/3.21 
$JAVA_HOME/bin/java \

-Djava.awt.headless=false \ 
-Djava.system.class.loader=com.sas.app.AppClassLoader \ 
-Dsas.ext.config=$SASHOME/SASIntelligencePlatformLogicalTypes
                 /9.3/sas.java.ext.config \ 
-Dsas.app.launch.config=$SASHOME/SASITResourceManagementDataTier
                        /3.21/plugins/itrmdatatier/picklist \ 
-Dsas.app.repository.path=$SASHOME/SASVersionedJarRepository/eclipse \ 
-Dlog4j.configuration="file://$SASHOME/SASITResourceManagementDataTier
                              /3.21/log4j.properties" \ 
-Xmx1024m \ 
-Xss1m \ 
-classpath $SASHOME/SASVersionedJarRepository/eclipse/plugins/sas.launcher.jar \ 
com.sas.solutions.itms.batch.maintaintable.BatchMaintainTable \ 
-host <metadata-server-hostname> \
-port <metadata-server-port-number> \
-user <unrestricted-metadata-server-userID> \
-password <password-for-specified-user> \
-domain DefaultAuth \ 
-Commit N \ 
-AdapterName "BMC Perf Mgr" \ 
-TemplateTableName PTCACHE \ 
-AddAndUpdateColumns Y \ 
-AddNewColumnsOnly N \ 
-UpdateRecommendedColumnsOnly N