How Is a SASReferences File Used?

Overview

After a SASReferences file has been created for a task, three key steps occur.

The name and location of the file must be communicated to the SAS Clinical Standards Toolkit.
The structural integrity and content of the file are assessed.
The file content is translated into allocated SAS libraries and filenames, system options are set, and required work files are created.

After these steps are completed, a SAS environment has been properly established to support subsequent SAS Clinical Standards Toolkit tasks.

Communicating the Filename and Location to the SAS Clinical Standards Toolkit

Three global macro variables are used to define the name and location of the SASReferences file:

The _cstSASRefsLoc macro provides the path to the SAS library that contains the file.
The _cstSASRefsName macro provides the SASReferences filename in _cstSASRefsLoc.
The _cstSASRefs macro provides libref.dset for the SASReferences file that is returned from the call to the cst_insertstandardsasrefs macro. The libref.dset is used in the SAS Clinical Standards Toolkit code for the remainder of the process.

Sample driver modules are provided with the SAS Clinical Standards Toolkit. These driver modules show how to perform the necessary setup tasks for SAS Clinical Standards Toolkit processes, and how to reference and use sample data that is provided with the SAS Clinical Standards Toolkit.

The key macro cstutil_processsetup is called in all sample driver modules. This macro interprets information about the location and name of the SASReferences file, and calls the cstutil_allocatesasreferences macro to allocate SAS librefs and filerefs based on SASReferences content.

Here is the macro code:

%macro cstutil_processsetup( _cstSASReferencesSource=SASREFERENCES,
           _cstSASReferencesName=sasreferences,
           _cstSASReferencesLocation=)  /des='CST: Setup Process Metadata';

This table lists the parameters that are supported by the cstutil_processsetup macro.

Parameters Supported by cstutil_processsetup

Parameter	Description
_cstSASReferencesSource	Specifies the initial source that setup should be based on. Valid values are SASReferences (default) or Results. If Results, then no other parameters are required, setup responsibility is passed to the cstutil_reportsetup macro, and the Results data set name must be passed to cstutil_reportsetup as libref.memname.
_cstSASReferencesLocation	Specifies the path (folder location) of the SASReferences data set. The default is the path to the Work library. This is the value of the global macro variable.
_cstSASReferencesName	Specifies the name of the SASReferences data set. The default is SASReferences. The value of the global macro variable _cstSASRefsName is set to this parameter value.

Excluding the SAS Clinical Standards Toolkit reporting processes, to communicate with a SASReferences file, use one of these two methods:

Note: The SAS Clinical Standards Toolkit reporting processes might use the _cstSASReferencesSource=RESULTS parameter.

Create and reference the SASReferences file in the SAS Work library.
```
%* The following call assumes the existence of work.sasreferences;
%cstutil_processsetup();
```

Reference an existing SASReferences file.

data _null_;
  select("&sysver");
   when("9.1") call symput('studyRootPath',
        '!sasroot/../SASClinicalStandardsToolkitSDTM312/
         1.4/sample/cdisc-sdtm-3.1.2/sascstdemodata');
   otherwise   call symput('studyRootPath',
         '!sasroot/../../SASClinicalStandardsToolkitSDTM312/
         1.4/sample/cdisc-sdtm-3.1.2/sascstdemodata');
  end;
run;
%* Look for the data set named sasreferences in the specified folder ;
%cstutil_processsetup(_cstSASReferencesLocation=&studyrootpath/control);

Assessing Structural Integrity and Content

Overview

Two SAS Clinical Standards Toolkit framework utility macros perform key functions in assessing whether the SASReferences file is valid.

The cst_insertstandardsasrefs macro looks up missing paths and memnames in the constructed SASReferences file from each StandardSASReferences data set. For example, this macro sets the path and memname values for lines 8 and 9 and 11 and 12 in the example in Sample SASReferences File for CDISC SDTM Validation. This macro attempts to update only records for supported standards (and standardversions) that have missing path and memname information. It does not update records with non-null values, and it does not add any records from the StandardSASReferences data set. If this macro runs successfully, then the resulting data set has paths for all records and memnames for all records that require them. This does not include autocall and sourcedata records. By default, the resulting data set is referenced by the &_cstSASRefs global macro variable.

The cstutil_checkds macro checks the structure and content of the data sets used by the SAS Clinical Standards Toolkit, including SASReferences. This macro validates that SASReferences has the structure and content defined by the StandardSASReferences and Standardlookup data sets.

Here is the syntax of this macro:

%cstutil_checkds(_cstdsname=, _csttype=, _cstsubtype=, _cststandard, _cststandardversion);

_cstdsname specifies a two-level name of the data set to be validated. This value is required.

_csttype specifies the type of the data set to be validated. This value is required. This value comes from the Type column in the registered SASReferences for the standard-version combination.

_cstsubtype specifies the subtype for the corresponding type. This value comes from the Subtype column in the registered SASReferences for the standard-version combination. If the type has no subtypes registered, then this option can be omitted. Otherwise, this value is required.

_cststandard specifies the name of the data standard to validate against. This value is optional. By default, all standards are included.

_cststandardversion specifies the version of the data standard to validate against. This value is optional. By default, all standard versions are included.

Results are written to the Results data set defined by the &_cstResultsDS global macro variable.

Common Errors and Solutions

This list describes the most common errors detected by the cstutil_checkds macro. It suggests solutions as well.

A standard-specific macro cannot be found. For example:
```
%odm_write;
WARNING: Apparent invocation of macro ODM_WRITE not resolved
```
Reported in the SAS log.

The autocall path has not been set correctly.

Common causes:
- SASReferences does not contain a type=autocall for that standard.
- In the same SAS session, you change the standard you are working with and fail to issue these statements first:
  
  %let _cstReallocateSASRefs=1; %include "&_cstGRoot/standards/cst-framework-1.4/ programs/resetautocallpath.sas";
Input parameters to macro insufficient for cstutil_checkds macro to run.

Reported in the Results data set.

Cause: One of the required macro variable options is missing.
Location for Results data set is undefined.

Reported in the SAS log.

Solution: Define the Results data set in the macro variable _cstResultsDS.
Data set could not be opened.

Reported in the Results data set.

Cause: The data set that is passed in via the _cstdsname parameter cannot be opened.

Solution: Make sure that you do not have the data set open in another window. Verify you have Read access to the data set.
Differences found between data set and the template data set.

Reported in the Results data set.

Cause: The data set that is passed in via the _cstdsname parameter has a different structure than the template data set.

Solution: Use the cst_createds macro to create a valid empty version of the data set, and then populate this data set with your data.
Null values are not permitted for column.

Reported in the Results data set.

Cause: Some columns are required to be non-null. If you receive this error, then you are also informed which column must contain a value.

Solution: Enter a non-null value for this column.
Invalid value for column column_name, row ## in data set.

Reported in the Results data set.

Cause: Some columns are limited to a set of values. This error indicates that the value for column_name, listed in row ##, has an invalid value.

The list of valid values is in the Standardlookup data set that is registered with each data standard.

Solution: Review the list of valid values, and update the column value.

Translating Content for a SAS Session

After the SASReferences file has been built, its content must be translated for use by a SAS Clinical Standards Toolkit process. A call to the SAS Clinical Standards Toolkit framework utility macro %cstutil_processsetup performs the translation. If this macro runs successfully, then the SAS session is properly configured for any tasks (such as validation) that follow.

When the %cstutil_processsetup macro is called, these events happen:

The cstutil_allocatesasreferences macro is called.
The cst_insertstandardsasrefs macro is called to insert paths into any records that are missing that information. The information is retrieved from the StandardSASReferences data set for each standard.
The cstutil_checkds macro is called to perform internal validation on the SASReferences data set updated in step 2.
All filerefs and librefs are allocated.
Any property files are passed to %cst_setproperties to create global macro variables.
The format search path is set if any type=fmtsearch records are found, based on the order that is specified.
The autocall path is set if any type=autocall records are found, based on the order that is specified. By default, the framework macro library was added to the autocall path when the SAS Clinical Standards Toolkit was deployed.
A Messages data set is created to contain records from each standard, based on the properties or global macro variables _cstMessages and _cstMessageOrder. The Messages data set is used for the duration of the process to add fully resolved messages to the Results data set.

After all of these steps have been performed, all libraries should be allocated, all paths and global macros should be set, and the global status macro variable _cst_rc should be set to 0. The process is ready to proceed.

CAUTION:

SASReferences is key to the process, and any errors will cause the process to fail.

This is a common process failure point because of the importance of the SASReferences file, and the strict structural and content expectations of the file. For tips on debugging problems with the SASReferences file, see Common Errors and Solutions.

Tip

Best Practice Recommendation: Each SASReferences file is customized for the specific task to be completed. Later sections describe SASReferences implementations required by these specific tasks.