The %RMPDB2DM Macro

Using the %RMPDB2DM Macro

PDB migration is performed by invoking the %RMPDB2DM SAS macro that is part of the SAS IT Resource Management 3.3 software. This macro should be invoked in a SAS session on the same system where the workspace server for SAS IT Resource Management 3.3 is executed. For best results, execute this macro in batch rather than interactively from SAS IT Resource Management.
Note: For information about issues that should be addressed before you run this macros, see Migration Prerequisites.
The macro %RMPDB2DM creates a new IT data mart according to the parameters that are provided. It then migrates tables, definitions, and data for the adapters that are requested. When processing is complete, a status report is generated to the standard SAS output area.

%RMPDB2DM Syntax

%RMPDB2DM(
DEFAULTROOTPATH=root directory for the data mart
,ITDATAMART=name of the data mart to create
,METAPASSWORD=password for metauser
,METAPORT=service or port for the metadata server
,METASERVER=host-name or IP address for the metadata server
,METAUSER=user ID for metadata server access and definition
,PDB=SAS IT Resource Management 2.6 or 2.7 PDB path
,SITELIB=SAS IT Resource Management 2.6 or 2.7 SITELIB path
,WORKDIR=directory path for work files
<,ADAPTER=_ALL_ | blank-delimited list of adapters>
<,APPSERVER=SASITRM | user-specified logical workspace server>
<,CLEANUP=Y | N>
<,COMPRESSAGG=Y | N>
<,COPYDATA=Y | N>
<,DEVICE=z/OS UNIT=value for allocation>
<,HP_PCS=HPOVREP | HPOVPA>
<,NUMBEROFVOLS=1>
<,PRIMARYCYLS=z/OS primary space allocation cylinders>
<,SECONDARYCYLS=z/OS secondary space allocation cylinders>
<,SPINDEVICE=UNIT=value for allocation>
<,SPINPRIMARYCYLS=primary space allocation cylinders>
<,SPINSECONDARYCYLS=secondary space allocation cylinders>
<,UPGRADENUMERICLENGTHS=Y | N>
<,_RC=macro variable name to hold the return code>
);

%RMPDB2DM Required Parameters

DEFAULTROOTPATH=root directory for the data mart
specifies the default root path to the IT data mart. This parameter is used as the root path for the libraries and data created and contained in the IT data mart. A value for this parameter is required.
The syntax of the default root path determines the syntax that is used as the default for any other paths that are specified. For example, if you specify a default root path for a traditional z/OS file system, then the default paths to all the libraries in this IT data mart would be in the traditional z/OS file system.
ITDATAMART=name of the data mart to create
specifies the name of the IT data mart. A value for this parameter is required. The name of the IT data mart must be unique to avoid potential difficulty when using other SAS tools. The name can contain a maximum of 60 characters.
Note: The name of an IT data mart cannot contain any of the following characters: * ? " ' | \ / [ ] $ & > < ( ) { } : ; ` ~ % ^ @ # ! In addition, this field cannot contain a newline or tab character.
METAPASSWORD=password for metauser
specifies the password for connecting the user ID to the metadata server. A value for this parameter is required.
METAPORT=service or port for the metadata server
specifies the TCP/IP service name or port number that the metadata server is listening on. A value for this parameter is required.
METASERVER=host-name or IP address for the metadata server
specifies the host-name or TCP/IP address of the metadata server. A value for this parameter is required. The metadata server does not need to be on the same host platform as the application server.
METAUSER=user ID for metadata server access and definition
specifies the user ID for accessing the metadata server. A value for this parameter is required. For more information, see the SAS 9.3 Intelligence Platform: System Administration Guide.
PDB=SAS IT Resource Management 2.6 or 2.7 PDB path
specifies the path to the SAS IT Resource Management 2.6 or 2.7 PDB that is to be migrated. A value for this parameter is required.
SITELIB=SAS IT Resource Management 2.6 or 2.7 SITELIB path
specifies the path to the SAS IT Resource Management 2.6 or 2.7 SITELIB that has been associated with the PDB to be migrated. A value for this parameter is required.
WORKDIR=directory path for work files
specifies a directory where %RMPDB2DM can write temporary external files. If this directory does not exist, it is created. For z/OS, this parameter needs to be a UNIX System Services directory path (HFS or zFS file system). A value for this parameter is required.

%RMPDB2DM Optional Parameters

ADAPTER=_ALL_ | blank-delimited list of adapters
specifies the list of SAS IT Resource Management 2.6 or 2.7 collectors that are eligible to migrate from the PDB that is specified by the PDB parameter. A value for this parameter is optional. If this parameter is not specified, then all collectors are migrated. This action is the same as specifying the special keyword value _ALL_ for this parameter.
For the list of collectors, separate each collector by white space. For example, to migrate tables for the NTSMF and PATROL collectors, specify Adapter=NTSMF PATROL. The values for this parameter are not case sensitive.
A list of values for the ADAPTER parameter is available in the SAS IT Resource Management 2.6 and 2.7 Collectors column in the cross-reference table of collectors and adapters in Cross-Reference Table of Collectors and Adapters.
Note: This list of possible valid values for this parameter is not exclusive. SAS IT Resource Management 2.6 or 2.7 users can manually modify adapter names for in-house, generic collectors, and these values might be valid for the Adapter parameter. If you specify a value that is not in the preceding list, then verify that the value that you specify is correct. The %RMPDB2DM macro does not generate an error or warning message for invalid values.
APPSERVER=SASITRM | user-specified logical workspace server
specifies the logical workspace server to use when registering data libraries that are created as part of the IT data mart. A value for this parameter is optional. The default value is SASITRM.
CLEANUP=Y | N
The %RMPDB2DM macro generates numerous intermediate items to complete its work. All of these intermediate items are cleaned up when the macro terminates, regardless of success or failure. Specifically, the macro performs the following tasks:
  • creates text files in the directory that is specified by the WORKDIR parameter
  • creates SAS data sets and catalogs in the WORK library
  • creates macro variables
  • sets certain system options
This parameter enables you to skip the cleanup phase. If you have problems with the %RMPDB2DM macro, then SAS Technical Support might request that you specify Cleanup=N in order to investigate the problem. A value for this parameter is optional. If it is not specified, the default value is Y. The value for this parameter is not case sensitive. You might choose to start with a fresh IT data mart based on a SAS IT Resource Management 2.6 or 2.7 PDB. A value for this parameter is optional.
COMPRESSAGG=Y | N
specifies whether to compress the aggregation tables that are being migrated.
If it is not specified, the default value is Y. The value for this parameter is not case sensitive.
COPYDATA=Y | N
The %RMPDB2DM macro essentially performs two types of work:
  • defining the metadata for the libraries, tables, folders, jobs, and formulas
  • copying data to the new IT data mart from the existing SAS IT Resource Management PDB
This parameter enables you to choose not to perform the data copy operation. You might choose to start with a fresh IT data mart based on a SAS IT Resource Management PDB. A value for this parameter is optional. If it is not specified, the default value is Y. The value for this parameter is not case sensitive.
DEVICE=z/OS UNIT=value for allocation
specifies the UNIT allocation parameter to use for allocation of IT data mart libraries in a z/OS traditional file system. A value for this parameter is optional. If a value is not specified, then it defaults to the value of the FILEDEV SAS system option. The value for this parameter is not case sensitive.
HP_PCS=HPOVREP | HPOVPA
This parameter is required if any of the SAS IT Resource Management 2.6 or 2.7 tables to be migrated are for the HP-PCS collector. In SAS IT Resource Management 3.3, this data can be staged by two separate mechanisms:
  • Select HPOVREP if you are staging this data from the database for HP OpenView Reporter.
  • Select HPOVPA if you are staging this data from the text file from HP OpenView Performance Agent.
This parameter has no default value, and the valid values are not case sensitive.
NUMBEROFVOLS=1
specifies the number of volumes that SAS libraries can span when using the z/OS traditional file system. A value for this parameter is optional. If a value is not specified, then it defaults to 1.
PRIMARYCYLS=z/OS primary space allocation cylinders
specifies the number of primary cylinders to use when allocating IT data mart libraries in a z/OS traditional file system. A value for this parameter is optional. If a value is not specified, then it defaults to the value of the FILESPPRI SAS system option.
SECONDARYCYLS=z/OS secondary space allocation cylinders
specifies the number of secondary cylinders to use when allocating IT data mart libraries in a z/OS traditional file system. A value for this parameter is optional. If a value is not specified, then it defaults to the value of the FILESPSEC SAS system option.
SPINDEVICE=Z/OS UNIT=value for allocation
specifies the UNIT allocation parameter to use for allocation of IT data mart libraries in a z/OS traditional file system. A value for this parameter is optional. If a value is not specified, then it defaults to the value of the SAS system option used for the Admin library. The value for this parameter is not case sensitive.
SPINPRIMARYCYLS=z/OS primary space allocation cylinders
specifies the number of primary cylinders to use when allocating Spin libraries in a z/OS traditional file system. A value for this parameter is optional. If a value is not specified, then it defaults to the value of the SAS system option used for the Admin library.
SPINSECONDARYCYLS=z/OS secondary space allocation cylinders
specifies the number of secondary cylinders to use when allocating Spin libraries in a z/OS traditional file system. A value for this parameter is optional. If a value is not specified, then it defaults to the value of the SAS system option used for the Admin library.
UPGRADENUMERICLENGTHS=Y | N
specifies whether numeric columns keep their length as specified in the PDB.
Note: If you run a data model upgrade on the IT data mart that was created by PDB migration, then the numerics all have lengths of 8 bytes.
If it is not specified, the default value is N. The value for this parameter is not case-sensitive.
_RC=macro variable name to hold the return code
specifies the name of a macro variable that holds the return code value from the execution of this macro. The value for this optional parameter is not case sensitive.

%RMPDB2DM Notes

Here are some notes about %RMPDB2DM to consider when using the macro:
  • Each time %RMPDB2DM is executed, a new IT data mart is created. (PDB Migration fails if you attempt to create an IT Data Mart with the same name as an existing IT Data Mart.)
  • A PDB can be migrated multiple times because each migration results in a new IT data mart.
  • If the directory that is specified by the WORKDIR parameter already exists, then make sure that it is empty before executing %RMPDB2DM.
  • The syntax of a path is validated according to its operating environment. For example, if you specify a default root path for a traditional z/OS file system, then the paths to the administrative and spin libraries, as well as the staged data, simple data, and summarized data locations also default to the traditional z/OS file system.
    For Windows operating environments that run SAS IT Resource Management, the following characters * ? " | < > / \ are not allowed. In addition, the newline and tab characters are not allowed.
    For UNIX operating environments and zFS and HFS file systems on z/OS operating environments that run SAS IT Resource Management, the following characters &* @ \ / | [ ] ^ { } $ ! > < ( ) % ? " ' ; are not allowed. In addition, the space, newline, tab, and open quotation character are not allowed.
    For traditional z/OS file system operating environments that run SAS IT Resource Management, the following rules apply:
    • The length of the data set name can be a maximum of 44 characters. (A portion of the 44 characters is needed by SAS IT Resource Management in order to completely specify the associated locations. In this case, the maximum length of the data set name is 35 characters.)
    • The data set name consists of segments that are separated by a period. The length of each segment can be a maximum of eight characters.
    • z/OS restricts the following characters in a segment name:
      • Numerals (0–9), the pound character, and the hyphen character are not allowed as the first character of a segment name.
      • The first character of each name must be either an alphabetic character (Aa–Zz) or a dollar sign ($).
      • The remaining seven characters of a segment name can include alphabetic characters (Aa–Zz), numeric characters (0–9), dollar signs ($), pound characters (#), and hyphens (-).
  • Individual tables can be omitted from migration by marking them as not kept in SAS IT Resource Management 2.6 or 2.7.
  • %RMPDB2DM is not intended for migrating across different host platforms. For example, migrating a PDB on Windows to an IT data mart on UNIX is not supported. For more information about migrating between platforms, see Cross-Platform PDB Migration.
  • SAS IT Resource Management 2.6 or 2.7 tables that are created by the %CPAVAIL macro are migrated as if they were generic collector tables. Staging code is not provided for these tables. For best results when performing migration, mark these tables as not kept in SAS IT Resource Management 2.6 or 2.7. Do not attempt to migrate these tables to SAS IT Resource Management 3.3.
  • You might see one of the following notes in your SAS log:
    Note: Could not load classloader itmsapi.   Using default classloader.
    NOTE: Could not initialize,classpath., Classpath variable is not set.
    These notes can be ignored.

%RMPDB2DM Examples

Example 1: Migrate All Tables for All Collectors in a UNIX Environment

In this UNIX example, the /u/itrm/prod-pdb PDB is migrated to the Production Metrics IT data mart. 
%RMPDB2DM(
    PDB=/u/itrm/prod-pdb,
    WORKDIR=/tmp/itrm/migrate,
    METASERVER=myserver01,
    METAPORT=8561,
    METAUSER=myuserID,
    METAPASSWORD=mypassword,
    ITDATAMART=Production Metrics,
    DEFAULTROOTPATH=/u/itrm/prod-itdm,
    SITELIB=/u/itrm/sitelib
    );

Example 2: Migrate Specified Collectors in a Windows Environment

In the following Windows example, the PDB called c:\my-pdb is migrated to the Server Metrics IT data mart. Only the data for the PATROL and NTSMF collectors is migrated in this example. 
%RMPDB2DM (
    PDB=c:\my-pdb,
    WORKDIR=c:\temp\migrate,
    METASERVER=myserver01,
    METAPORT=8561,
    METAUSER=myuserID,
    METAPASSWORD=mypassword,
    ITDATAMART=Server Metrics,
    DEFAULTROOTPATH=c:\my-itdm,
    SITELIB=c:\sitelib,
    ADAPTER=Patrol NTSMF
    );

Example 3: Migration Using the z/OS Traditional File System

In this z/OS example, the SYS2.ITRM.RMF.PDB PDB is migrated to the z/OS RMF IT data mart. The physical storage for the IT data mart is in the traditional z/OS file system. Space and Unit allocation values are provided.
Note: The WORKDIR parameter must be in a z/OS UNIX file system such as HFS or zFS. In addition, the metadata server does not have to be on z/OS. 
%RMPDB2DM(
    PDB=SYS2.ITRM.RMF.PDB,
    WORKDIR=/tmp/itrm/migrate,
    METASERVER=myserver01,
    METAPORT=8561,
    METAUSER=myuserID,
    METAPASSWORD=myuser_password,
    ITDATAMART=%str(zOS RMF),
    DEFAULTROOTPATH=SYS2.RMF.DATAMART,
    SITELIB=SYS2.ITRM.SITELIB,
    DEVICE=DISK,
    PRIMARYCYLS=50,
    SECONDARYCYLS=20
    );

Example 4: Migration Using the z/OS UNIX File System

In this z/OS example, the SYS2.ITRM.RMF.PDB PDB is migrated to the z/OS RMF IT data mart. The physical storage for the IT data mart is in the z/OS UNIX System Services hierarchical file system. 
%RMPDB2DM(
    PDB=SYS2.ITRM.RMF.PDB,
    WORKDIR=/tmp/itrm/migrate,
    METASERVER=myserver01,
    METAPORT=8561,
    METAUSER=myuserID,
    METAPASSWORD=mypassword,
    ITDATAMART=%str(z/OS RMF),
    DEFAULTROOTPATH=/u/itrm/rmf_dm,
    SITELIB=SYS2.ITRM.SITELIB
    );

How to Recover If %RMPDB2DM Fails to Run Successfully

If does not complete successfully, perform the following actions:
  1. Correct the problem that caused the failure. For example, if the problem was caused by insufficient disk space, determine how much space you need and allocate it accordingly.
  2. Using the SAS IT Resource Management client, perform an Erase action against the IT Data Mart that was created by the failed %RMPDB2DM invocation.
    Note: This might not fully succeed, because metadata might have been defined for libraries that were never physically created.
  3. If step 2 did not remove the IT data mart from view in the client, perform a Delete action against the IT data mart.
  4. Verify that any physical libraries that were created as part of the IT data mart have been physical deleted.
  5. Clear out the directory pointed to by the WORKDIR= parameter on the invocation of %RMPDB2DM.
    Note: This directory should include a subdirectory called api.
  6. Re-run %RMPDB2DM.
Copyright © SAS Institute Inc. All rights reserved.