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 programs. 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.

%cstutil_setcstsroot;
data _null_;
call symput('studyRootPath',cats("&_cstSRoot",
            "/cdisc-sdtm-3.1.2-&_cstVersion/sascstdemodata"));
run;
%* Look for the data set named sasreferences in the specified folder ;
%cstutil_processsetup(_cstSASReferencesLocation=&studyrootpath/control);

The call to the %cstutil_setcstroot macro sets the SAS Clinical Standards Toolkit global macro variable &_cstSRoot to the sample library.

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 a supported standard (and standardversion) that has 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.

In the SAS Clinical Standards Toolkit 1.5, the cstutilvalidatesasreferences macro replaces the cstutil_checkds macro. This new macro checks the structure and content of the SASReferences data set against a defined gold standard.

If you have used previous versions of the SAS Clinical Standards Toolkit, you might see failures when you use the cstutilvalidatesasreferences macro against SASReferences data sets that were created in a version before the SAS Clinical Standards Toolkit 1.5. These failures are caused by the stricter adherence to the SASReferences metadata model that the cstutilvalidatesasreferences macro enforces.

Here is the syntax of this macro:

%macro cstutilvalidatesasreferences (_cstDSName=,_cstStandard=,_cstStandardversion=, _cstSASRefsGoldStd=, _cstallowoverride=, _cstResultsType=, _cstPreAllocated, _cstVerbose= );

_cstDSName specifies the two-level name of the data set to be validated. This value is required. The default value is &_cstSASRefs derived from the process setup macro.

_cstStandard specifies the name of a registered data standard. This value is required. The default value is CST-FRAMEWORK.

_cstStandardversion specifies the version of a registered data standard. This value is required. The default value is 1.2.

_cstSASRefsGoldStd specifies the two-level name of a comparative gold standard against which this SASReferences data set is compared. This value is required. By default, the global standards library metadata StandardSASReferences is assumed.

_cstallowoverride specifies whether to ignore one or more of the values defined above. Specify the check code in a blank-delimited string (for example, CHK01 CHK07). If null, all conditions are tested.

_cstResultsType specifies where to store report findings: in the SAS log or in the Results data set. This value is required. It must be either LOG or RESULTS. The default value is LOG.

_cstPreAllocated specifies whether to allocate librefs and filerefs when this macro is called. If they are not allocated, the validation of data sets and catalogs is performed based on paths and memnames, not on libref.memnames. This value is required. It must be either N or Y. The default value is N.

_cstVerbose specifies whether to report specific problems or the absence of problems in _cst_rc. Otherwise, only success or failure is reported. This value is required. It must be either N or Y. The default value is N.

This macro is typically used as a part of the normal process setup. It is called either before or as a part of cstutil_allocatesasreferences() or as a stand-alone call outside the context of use in the normal process setup. The macro sets the _cst_rc and _cst_rcmsg global macro variables to indicate that the SASReferences data set is valid (_cst_rc=0) or not valid (_cst_rc ne 0).

There are eight checks associated with this macro when validating a SASReferences data set.

CHK01: The data set is structurally correct.
CHK02: An unknown standard or standardversion exists.
CHK03: The referenced input and output files and folders can be accessed.
CHK04: All required look-throughs to the global standards library defaults work.
CHK05: All discrete character field values are found in the Standardlookup data set.
CHK06: For the given context, path and memname macro variables are resolved.
CHK07: Multiple fmtsearch records exist, but valid ordering is not provided.
CHK08: Multiple autocall records exist, but valid ordering is not provided.

In the SAS Clinical Standards Toolkit 1.5, additional columns are included in the SASReferences data set to facilitate internal validation. Two of these columns are iotype and filetype. To remain backward compatible, if the SASReferences data set is missing these two columns, CHK03 is ignored because the cstutil_validatesasreferences macro assumes that the SASReferences data set was created in a version before the SAS Clinical Standards Toolkit 1.5.

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_validatesasreferences macro. Solutions are suggested. All errors appear in the Results data set.

CHK01 - A problem with the structure of the data set exists.

The macro has detected a structural difference in the data set that needs to be addressed.

Fix the issues as described in the Results data set.
CHK02 - An unknown standard or standardversion value exists.

The macro has detected a standard or standardversion value that does not exist in the SAS Clinical Standards Toolkit. This can be caused by a typographical error for the value or by a standard that has not yet been registered with the SAS Clinical Standards Toolkit.

Correct the erroneous value or register the unknown standard.
CHK03 - The referenced input and output files cannot be accessed.

This check uses a new metadata variable in SASReferences called iotype. This variable is not available in previous versions of the SAS Clinical Standards Toolkit. To maintain backward compatibility, a special Boolean macro variable exists. It is named &_cstCurrentStyle and has a value of 1 (version 1.5 SASReferences) or 0 (previous version of SASReferences). When set to 0, the SAS Clinical Standards Toolkit ignores this check.

Based on the value of iotype, the macro has detected a specified input file, data set, or catalog that does not exist in the path provided by SASReferences. For iotype equal to 'output' or 'both,' the specified path is Read-Only and does not allow the SAS Clinical Standards Toolkit to create an output file.

Correct this issue by ensuring that pathnames, filenames, data set names, and catalog names are entered correctly. For output file references, ensure that the user account has Write access permission to the folders that are specified in SASReferences.
CHK04 - Required look-throughs to the global standards library defaults do not work.

For this check to be meaningful, ensure that a call to cst_insertStandardSASRefs has been performed before running this check. Otherwise, empty pathnames might exist that are populated with a call to cst_insertStandardSASRefs.

This check is not applicable to stand-alone use. This check detects pathnames that are missing or null.

Correct this issue by verifying that the call to cst_insertStandardSASRefs was made before running this check. Otherwise, provide a valid pathname for each missing value.
CHK05 - Not all discrete character fields were found in the Standardlookup data set.

This check detects missing or incorrect names for the following columns in SASReferences: reftype, type+subtype combinations, iotype, filetype, and allowoverwrite.

Note: Because iotype, filetype, and allowoverwrite are new to the SAS Clinical Standards Toolkit 1.5, these columns are ignored when &_cstCurrentStyle=0. (See check CHK03.)

Correct this issue by providing valid values for these columns in SASReferences. If needed, update the Standardlookup data set.

Note: Updating the Standardlookup data set is an advanced use of the SAS Clinical Standards Toolkit and should be performed by an administrator.
CHK06 - For the given context, all macro variables have not been resolved.

This check detects unresolved macro variables used in the memname and path columns.

Correct this issue by making sure all macro references used in SASReferences have been resolved.
CHK07

To ensure proper FMTSEARCH functionality in SAS, the order in which the fmtsearch string is built is very important for the proper functioning of the SAS Clinical Standards Toolkit. This check detects multiple fmtsearch records with invalid order values. Invalid order values could be missing or duplicate values.

Correct this issue by assigning valid order values for multiple fmtsearch records.
CHK08

To ensure proper AUTOCALL macro functionality in SAS, the order in which the autocall macro string is built is very important for the proper functioning of the SAS Clinical Standards Toolkit. This check detects multiple autocall records with invalid order values. Invalid order values could be missing or duplicate values.

Correct this issue by assigning valid order values for multiple autocall records.

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_validatesasreferences 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.