Common Usage Scenarios for the Framework :: SAS(R) Clinical Standards Toolkit 1.7: User's Guide, Second Edition

Overview

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

Microsoft Windows

!sasroot/cstframework/sasmacro
UNIX

!sasroot/sasautos

For complete macro documentation, see the SAS Clinical Standards Toolkit: Macro API Documentation.

Initializing the Framework's Global Macro Variables

The framework requires certain global macro variables to execute properly. You should initialize these global macro variables at the start of each SAS Clinical Standards Toolkit session. The same requirement might exist for a standard. The standard might need global macro variables to call its macros. The framework provides a macro to help with this requirement.

/*
initialize the global macro variables needed by the framework
*/
%cst_setstandardproperties(
_cstStandard=CST-FRAMEWORK
,_cstSubType=initialize
);

This code looks at the global SASReferences data set for a properties entry with a SubType value of initialize. By default, this entry is located here:

global standards library directory/standards/cst-framework-1.7/programs/initialize.properties

Global macro variables are initialized based on the name-value pairs in this properties file. After this macro has been called once, you do not need to call it again during the SAS session, unless you want to override macro variables or reset them.

Referencing the Default Version of a Standard

If the default version of a standard is to be used, the version information can be omitted. The default version is specified in the global standards library metadata Standards data set. Here is an example of the code to initialize CDISC SDTM 3.2 properties:

/*
initialize the global macro variables needed by CDISC SDTM
*/
%cst_setstandardproperties(
_cstStandard=CDISC-SDTM
,_cstSubType=initialize
);

In this example, the initialization properties for the default version of the CDISC SDTM standard (currently 3.2) are used without needing to specify a version.

Getting a List of the Standards That Are Installed

It is programmatically possible to get a list of the current standards that are registered to the framework. This code can be used:

/*
get a list of the registered standards
*/
%cst_getregisteredstandards(
_cstOutputDS=work.regStds
);

The data set work.regStds contains the information from the global standards library metadata Standards data set. The work.regStds data set's content matches the information provided in Global Standards Library: Metadata Standards Data Set.

Determining Which Revision (Release) of a Standard Version Is Installed

It is programmatically possible to determine which revision of a standard version is installed. This code can be used:

/* 
initialize the global macro variables needed by the framework
*/
%cst_setstandardproperties(
    _cstStandard=CST-FRAMEWORK
    ,_cstSubType=initialize
    );
/*
get a list of the registered standards
*/
%cst_getregisteredstandards(
    _cstOutputDS=work.regStds
    );

The data set work.regStds contains the information from the global standards library metadata Standards data set. The last column is productRevision. This column contains the revision of each standard version. If the productRevision column is blank, then the standard was originally registered with SAS Clinical Standards Toolkit 1.2.

Here is another, simpler method to determine the current SAS Clinical Standards Toolkit release:

%put CST Version: %cstutil_getcstversion;

You can also use the _cstVersion global macro variable:

%put &_cstVersion

Getting a List of the Files and Data Sets That Are Associated with a Registered Standard

When standards are registered, information about the files and data sets that comprise the standard is registered also. This macro call returns records from the StandardSASReferences data set that are associated with the specified standard. It returns records for standardversion if applicable.

%cst_getstandardsasreferences(
_cstStandard=CST-FRAMEWORK
,_cstOutputDS=sasrefs
);

The parameters that are used in this macro call specify the standard CST-FRAMEWORK and the data set to create to contain the information. Because the standard version is omitted, the default standard version is used. The data set that is returned is a SASReferences data set. For the macro call, this display shows the first few columns of data that are returned.

StandardSASReferences Returned in work.sasrefs Data Set (Column Subset)

Note: If the %CST_SETSTANDARDPROPERTIES macro has not been called before invoking the %CST_GETSTANDARDSASREFERENCES macro, these errors are reported in the SAS log:

WARNING: Apparent symbolic reference _CSTDEBUG not resolved.
ERROR: A character operand was found in the %EVAL function or 
%IF condition where a numeric operand is required. The condition was: 
(&_cstDebug))
ERROR: The macro CST_GETSTANDARDSASREFERENCES will stop executing.

Calling the %CST_SETSTANDARDPROPERTIES macro to create global macro variables for the SAS Clinical Standards Toolkit session is a prerequisite for most SAS Clinical Standards Toolkit tasks.

Creating Data Sets Used by the Framework

Many macro calls to the framework require tables to be passed in or referenced. The structure of these tables can be difficult to build manually, so the SAS Clinical Standards Toolkit provides functionality to create table shells that can be filled in. Here is an example of the macro call:

/*
Create the empty SASReferences data set used in the next
step
 */
%cst_createdsfromtemplate(
    _cstStandard=CST-FRAMEWORK,
    _cstType=control,
    _cstSubType=reference,
    _cstOutputDS=work.sasrefs
    );

The Type and SubType identify that it is a SASReferences table. The Standard identifies the module to be used. If the standard version is not specified, then the default for standard version is used. The output is a data set named work.sasrefs that contains 0 observations.

Creating Table Shells Based on a Data Standard

Data standards like CDISC SDTM have reference metadata that describes the tables and columns that comprise the data standard. Creating table shells using this metadata is useful and saves time. Here is the code to do this:

/*
Create the table shells for CDISC SDTM 3.1.3 in the work library
*/
%cst_createtablesfordatastandard(
    _cstStandard=CDISC-SDTM
    ,_cststandardVersion=3.1.3
    ,_cstOutputLibrary=work
    );

This code creates the domains described by CDISC SDTM version 3.1.3 in the Work library. Each domain contains 0 observations.

Getting a Copy of the Reference Metadata for a Data Standard

The SAS representation of many standards (such as CDISC SDTM) includes table and column metadata for all domains that are specific to each standard. The SAS Clinical Standards Toolkit framework provides a way to create and populate the metadata files.

/*
Step 1. Create the empty SASReferences data set used in
the next step
 */
%cst_createdsfromtemplate(
    _cstStandard=CST-FRAMEWORK,
    _cstType=control,
    _cstSubType=reference,
    _cstOutputDS=work.sasrefs);
/*
Step 2. Prep the type of information to be returned.
 */
data work.sasrefs;
    if 0 then set work.sasrefs;
    standard='CDISC-SDTM';
    standardVersion='3.1.2';
    * ----- REFERENCE METADATA -----;
    * tables metadata;
    type='referencemetadata';
    subType='table';
    sasRef='work';
    refType='libref';
    memname='refTables';
    iotype=’input’;
    filetype=’dataset’;
    allowoverwrite=’N’;
    output;
    * columns metadata;
    type='referencemetadata';
    subType='column';
    sasRef='work';
    refType='libref';
    memname='refColumns';
    output;
run;
/*
Step 3. Call the macro to get the metadata.
 */
%cst_getstandardmetadata(
    _cstSASReferences=work.sasrefs
    );

Step 1 uses one macro to create an empty SASReferences data set named work.sasrefs.

Step 2 determines the information to be returned. The standard and version is CDISC SDTM 3.1.2. The type and subType identify the types of metadata to be returned. The sasRef and memname identify the target library and name for each data set.

Step 3 is the actual macro call that does the processing. The data set work.sasrefs is read, and the global metadata is used to fulfill the request.

The outcome of these steps is two data sets. The data set work.refTables contains metadata about the CDISC SDTM 3.1.2 domains. The data set work.refColumns contains metadata about each of the columns defined in the domains.

Inserting Information from Registered Standards into a SASReferences File

When a standard is registered, information about the data sets and files that comprise the standard is registered. These data sets and files are in a default folder hierarchy within the global standards library. The SAS Clinical Standards Toolkit provides a mechanism to reference the location of, and metadata about, these data sets and files. As a result, you do not have to specify paths and member names in each SASReferences file that you create. When a SAS Clinical Standards Toolkit process encounters an incomplete file reference in a SASReferences file, it looks in the standard-specific folder hierarchy for the information. This mechanism is useful for a number of reasons:

Programmers do not need to know all of the locations.
If the global standards library needs to move, it can without having to change all of the SASReferences files that use a standard.
To change standard versions, you need only to change the contents of the standardversion column.

This code creates a partial SASReferences file:

/*
Step 1. Initialize the global macro variables needed by the
framework.
*/
%cst_setstandardproperties(
    _cstStandard=CST-FRAMEWORK
    ,_cstSubType=initialize
    );
/*
Step 2. Create the empty SASReferences data set.
*/
%cst_createdsfromtemplate(
    _cstStandard=CST-FRAMEWORK,
    _cstType=control,
    _cstSubType=reference,
    _cstOutputDS=sasrefs
    );
/*
Step 3. Fill in the minimal information for a series of
records
*/
data sasrefs;
    if 0 then set sasrefs;
         
    standard='CST-FRAMEWORK';
    standardversion='1.2';
    type='messages';
    subtype='';
    sasref='cstmsg';
    reftype='libref';
    order=1;
    iotype='input';
    filetype='dataset';
    allowoverwrite='N';
    output;
    standard='CST-FRAMEWORK';
    standardversion='1.2';
    type='lookup';
    subtype='';
    sasref='cstlkup';
    reftype='libref';
    order=1;
    iotype='input';
    filetype='dataset';
    allowoverwrite='N';
    output;
    standard='CST-FRAMEWORK';
    standardversion='1.2';
    type='results';
    subtype='validationresults';
    sasref='cstrslt';
    reftype='libref';
    order=1;
    iotype='output';
    filetype='dataset';
    allowoverwrite='Y';
    output;
run;

The following display shows what the data set looks like:

Example SASReferences Data Set

The path and memname columns are missing. The user has specified the standard, standardversion, type, subtype, SASref, and reftype. This information is sufficient. The rest of the information is available from the registered standard's metadata.

This macro call attempts to insert the missing information if it is found in a registered standard's metadata:

/*
Step 4. Insert the missing information from registered
standard.
*/
%cst_insertstandardsasrefs(
    _cstSASReferences=sasrefs
    ,_cstOutputDS=outSASRefs
    );

The following display shows what the output data set looks like:

work.outSASRefs Data Set with Added Content