Common Usage Scenarios for the Framework

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 can be found in the primary SAS Clinical Data Standards Toolkit autocall path:

!sasroot/cstframework/sasmacro

For complete macro documentation, see Macro Application Programming Interface.

Initializing the Framework's Global Macro Variables

The framework requires certain global macro variables to execute properly. A user 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 of initialize. By default, this entry is located at:

<global standards library directory>/standards/cst-framework-1.3/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, a user does not need to call it again during the SAS session, unless the user wants to override macro variables or reset them.

Referencing the Default Version of a Standard

If a version must be specified, then the specification can usually be omitted if the default version is to be used. The default version is specified in the global standards library metadata Standards data set. For example, the code to initialize CDISC SDTM 3.1.2 properties can be written as:

/*
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.1.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. The following 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. The following 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.

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. The following 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, the following 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, then the following 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 cst_setStandardProperties 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. The following is an example of the macro call:

/*
Create the empty SASReferences data set used in the next
step
 */
%cst_createDS(
    _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 and 10 columns.

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. The following is the code to do this:

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

This code creates the 25 domains described by CDISC SDTM version 3.1.1 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_createDS(
    _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';
    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 32 CDISC SDTM 3.1.2 domains. The data set work.refColumns contains metadata about each of the 723 columns defined in the 32 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, users do not have to specify paths and member names in each SASReferences file they 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 only need to change the contents of the standardversion column.

The following 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_createDS(
    _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='messages';
    reftype='libref';
    order=1;
    output;
    standard='CST-FRAMEWORK';
    standardversion='1.2';
    type='lookup';
    subtype='';
    sasref='template';
    reftype='libref';
    order=1;
    output;
    standard='CST-FRAMEWORK';
    standardversion='1.2';
    type='results';
    subtype='results';
    sasref='template';
    reftype='libref';
    order=1;
    output;
run;

Here is 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.

The following 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
    );

Here is what the output data set looks like:

work.outSASRefs Data Set with Added Content