Maintenance Usage Scenarios :: SAS(R) Clinical Standards Toolkit 1.5: User's Guide

Overview

The following sections describe usage scenarios that the framework accommodates. Code that is required to complete the usage scenario included in each section. All macros that are provided in the usage scenarios are in the primary SAS Clinical Data Standards Toolkit autocall path:

Microsoft Windows

!sasroot/cstframework/sasmacro
UNIX

!sasroot/sasautos

Note: All of the maintenance usage scenarios require that you have Write access to the global standards library.

For complete macro documentation, see the online macro API reference documentation.

Tip

Best Practice Recommendation: Do not modify global standards library files provided by SAS. Instead, modify copies of these files. Leaving the SAS files intact enables these files to be updated without concern about overwriting or losing your changes.

Registering a New Version of a Standard

This code defines and registers a new standard. The code can also be used to register a new version of an existing standard.

/*
Step 1. Ensure that the macro variable pointing to the global standards
library exists.
*/
%cstutil_setcstgroot;
/*
Step 2. Register the standard with the Toolkit global standards
library
*/
%cst_registerstandard(
    _cstRootPath=%nrstr(&_cstGRoot./standards/myStandard),
    _cstControlSubPath=control,
    _cstStdDSName=standards,
    _cstStdSASRefsDSName=StandardSASReferences),
    _cstStdLookupDSName=standardlookup;

Step 1 ensures that the macro variable that contains the global standards library path is set. Step 2 registers the standard by passing this information:

The main path to the directory that contains the standard version's files.
The path to the registration data sets that are used to populate the global standards library metadata data sets. This is the name of the subfolder in the _cstRootPath parameter value.

Note: This subfolder must exist before registering the standard.
The names of the Standards and StandardSASReferences data sets. These data sets have the same structure as the data sets in the global standards library metadata directory. Both of these data sets are required to define a new standard or a new version of a standard.
The name of the Standardlookup data set. This data set has the same structure as the data set in the global standards library directory/metadata directory. This data set is optional.

The _cstRootPath parameter uses %nrstr(&_cstGroot) so that the &_cstGroot is registered as a macro variable. This specification allows the global standards library to be moved or copied without reregistering the full path of the new standard.

When defining and registering a new standard, you should evaluate which of the metadata files described in Common Framework Metadata should be provided to support new standard functionality. For example:

Should a sample SASReferences file be created to perform some task?
Should a Messages data set be added to provide standard-specific informational messages?
Should properties files be provided to set standard-specific global macro variables?

For more information about the metadata files that support the SAS Clinical Standards Toolkit, see Metadata File Descriptions. You can define new metadata types. These new metadata types should be documented in the standard-specific StandardSASReferences and Standardlookup data sets, and in the SAS Clinical Standards Toolkit framework Standardlookup data set.

Setting the Default Version for a Standard

When multiple versions of a standard exist, the first version that is installed is set as the default. The default version is used when multiple versions of a standard have been registered, and a specific version is not provided in a macro call or in a SASReferences file. This code modifies the default version of a specific standard:

%cst_setstandardversiondefault(
    _cstStandard=CDISC-SDTM
    ,_cstStandardVersion=3.1.1
    );

The version 3.1.1 is set as the default version for the CDISC SDTM standard.

Unregistering a Standard Version

If a standard becomes obsolete and needs to be unregistered, then use the framework to do this. Unregistering a standard might be needed during the development of a custom standard.

This macro call unregisters the CDISC SDTM 3.1.1 standard, removes it from the global standards library metadata Standards data set, and removes all records for 3.1.1 from the StandardSASReferences data set:

%cst_unregisterstandard(
    _cstStandard=CDISC-SDTM
    ,_cstStandardVersion=3.1.1
    );

Unregistering an Old Version of a Standard, and Then Registering a New Version of a Standard

Suppose that the SAS Clinical Standards Toolkit 1.4 is currently installed and used. The SAS Clinical Standards Toolkit 1.5 is released. You want the product updates for a standard version. In the following steps, the CDISC SDTM standard is used as an example. However, the steps apply to all other standard versions. You want to set version 3.1.3 as the default version for the CDISC SDTM standard. The SAS Clinical Standards Toolkit installation process does not do this automatically because you might have made updates to the SAS Clinical Standards Toolkit 1.4 code base or metadata that you want to preserve. Or, you might want to test the SAS Clinical Standards Toolkit 1.5 CDISC SDTM 3.1.3 implementation before declaring it the new default version.

Step 1: Confirm that multiple versions of the standard are available. Confirm that registration of a new version is needed.

Navigate to the global standards library Standards directory global standards library directory/standards.
Confirm that multiple libraries exist for the same standard version.

In this example, two subdirectories exist for CDISC SDTM 3.1.1.

Multiple Versions per Standard in the Global Standards Library

The cdisc-sdtm-3.1.1–1.4 directory contains files installed with the SAS Clinical Standards Toolkit 1.4. The cdisc-sdtm-3.1.1-1.5 directory contains files installed with the SAS Clinical Standards Toolkit 1.5.
Confirm which revision of the standard version is currently in use.
- Assign a LIBNAME to the metadata subdirectory in the global standards library.
- Open the Standards data set in the library, and confirm that the older version is the one being used.
  
  This display shows that the registered version CDISC SDTM 3.1.1.-1.4 indicates that it is the original version that was shipped with the SAS Clinical Standards Toolkit 1.4. It is defined as the default version for the CDISC SDTM standard.
  
  Global Standards Library Metadata Standards Data Set before Updates

Step 2: Register the updated CDISC SDTM 3.1.1 metadata in the global standards library to use the SAS Clinical Standards Toolkit 1.5.

Navigate to the Standards directory in the global standards library. Go to the programs directory of the revision of the standard version that needs to be registered. For example, go to global standards library directory/standards/cdisc-sdtm-3.1.1-1.5/programs.
Start a SAS session. Make sure that the current directory is the programs directory.

To unregister the currently installed revision and version, submit this code:

%cstutil_setcstgroot;
/* 
Set the framework properties used for the uninstall
*/
%cst_setstandardproperties(
    _cstStandard=CST-FRAMEWORK,
    _cstSubType=initialize
    );

/*
If the version to be replaced is the default, you must 
make another version the default.
In this case, this is the desired final outcome anyway.
*/
%cst_setstandardversiondefault(
    _cstStandard=CDISC-SDTM
    ,_cstStandardVersion=3.1.2
    );

/*
Unregister the standard
*/
%cst_unregisterstandard(
    _cstStandard=CDISC-SDTM
    ,_cstStandardVersion=3.1.1
    );

Note: The cst_setStandardVersionDefault macro call needs to be used only if the version being updated is the default version of the standard.

Check the Results data set. By default, the data set is work._cstResults. The final line in the data set should report that the standard version is no longer registered as a standard.
Open and submit the registerstandard.sas file from the programs directory into the Program Editor.
Confirm that the new revision was registered.
- Assign a LIBNAME to the metadata subdirectory in the global standards library.
- Open the Standards data set in the library, and confirm that the newer revision is the one being used.
  
  This display shows that the CDISC SDTM 3.1.1 standard is now reregistered, the product revision in use is 1.5, and CDISC SDTM 3.1.2 is registered as the default standard.
  
  Global Standards Library Metadata Standards Data Set after Updates