Module Dataset-XML V1.0.0 (Runtime)

This is the CDISC-Dataset-XML 1.0.0 runtime macro library.

Since: V1.7

Macro Summary
external

%cstutilcomparedatasets(_cstLibBase=, _cstLibComp=, _cstCompareLevel=16, _cstCompOptions=, _cstCompDetail=Y);
Compare 2 libraries with SAS data sets.
external

%datasetxml_read(_cstSourceDatasetXMLFile=, _cstSourceDatasetXMLLibrary=, _cstOutputLibrary=, _cstSourceMetadataLibrary=, _cstSourceMetadataDefineFile=, _cstSourceMetadataDefineFileRef=, _cstSourceMetadataMapFile=, _cstSourceDataMapFile=, _cstMaxLabelLength=256, _cstdatetimeLength=64, _cstAttachFormats=Y, _cstNumObsWrite=10000, _cstReturn=_cst_rc, _cstReturnMsg=_cst_rcmsg);
Create a SAS data set or a library of SAS data sets from Dataset-XML files.
external

%datasetxml_write(_cstSourceDataSets=, _cstSourceLibrary=, _cstOutputLibrary=, _cstSourceMetadataLibrary=, _cstSourceMetadataDefineFile=, _cstSourceMetadataDefineFileRef=, _cstSourceMetadataMapFile=, _cstOutputEncoding=UTF-8, _cstCreationDateTime=, _cstAsOfDateTime=, _cstOriginator=, _cstSourceSystem=, _cstSourceSystemVersion=, _cstHeaderComment=Produced from SAS data using SAS Clinical Standards Toolkit, _cstNumericFormat=best32., _cstCheckLengths=Y, _cstIndent=Y, _cstZip=N, _cstDeleteAfterZip=N, _cstReturn=_cst_rc, _cstReturnMsg=_cst_rcmsg);
Create Dataset-XML file from a SAS data set or from a library of SAS data sets
external

%xml_validate(xsdFile=, xmlFolder=, whereClause=);
Validate an XML file against a W3C schema file.

Macro Detail

%cstutilcomparedatasets(_cstLibBase=, _cstLibComp=, _cstCompareLevel=16, _cstCompOptions=, _cstCompDetail=Y);

[ Exposure: external ]
Compare 2 libraries with SAS data sets.

Expected Macro Variables:
_cstDebug - Turns debugging on or off for the session. Set _cstDebug=1
        before this macro call to retain work files created in this macro.
_cstResultSeq - Results: Unique invocation of macro
_cstSeqCnt - Results: Sequence number within _cstResultSeq
_cst_rc - Task error status
_cst_rcmsg - Message associated with _cst_rc
Parameters:
_cstLibBase - - required - The reference library of SAS data sets.
_cstLibComp - - required - The library of SAS data sets that is compared
        against the reference library.
_cstCompareLevel - - required - The minimum PROC COMPARE return code
        which is considered to be an error condition.
        Values greater than 0, but below the _cstCompareLevel value are
        considered warning conditions.
        Default: 16
_cstCompOptions - - optional - Extra options to be added to PROC COMPARE
        Examples:
        _cstCompOptions=%str(criterion=0.00000000000001)
        to do a less than exact compare
_cstCompDetail - - optional - Do a detailed PROC COMPARE for the SAS data
        that did not compare equal.
        Values: Y | N
        Default: Y
File: cstutilcomparedatasets.sas
First available in version: 1.7

%datasetxml_read(_cstSourceDatasetXMLFile=, _cstSourceDatasetXMLLibrary=, _cstOutputLibrary=, _cstSourceMetadataLibrary=, _cstSourceMetadataDefineFile=, _cstSourceMetadataDefineFileRef=, _cstSourceMetadataMapFile=, _cstSourceDataMapFile=, _cstMaxLabelLength=256, _cstdatetimeLength=64, _cstAttachFormats=Y, _cstNumObsWrite=10000, _cstReturn=_cst_rc, _cstReturnMsg=_cst_rcmsg);

[ Exposure: external ]
Create a SAS data set or a library of SAS data sets from Dataset-XML files.

Notes:
(1) Any librefs referenced in macro parameters must be pre-allocated.
(2) Files that previously existed in the output location will be overwritten.
(3) Either _cstSourceDatasetXMLFile or _cstSourceDatasetXMLLibrary must be
specified. In case these parameters have not been specified, the macro
attempts to get these parameter values from the SASReferences data set
that has been specified by the macro variable _cstSASRefs
(type=externalxml). When multiple type=externalxml records have been
specified, filenames must be defined (with reftype=fileref and
filetype=file). In case no filenames are specified, only the first record
will be used, and reftype=libref, filetype=folder should be used.
(4) _cstOutputLibrary must be specified. In case this parameter has not been
specified, the macro will attempt to get this parameter value from the
SASReferences data set as specified by the macro variable _cstSASRefs
(type=targetdata, reftype=libref, filetype=folder).
(5) Either _cstSourceMetadataLibrary, _cstSourceMetadataDefineFile or
_cstSourceMetadataDefineFileRef must be specified.
In case these parameters are not specified, the macro will first attempt
to get _cstSourceMetadataLibrary from the SASReferences data set as
specified by the macro variable _cstSASRefs (type=sourcemetadata,
subtype=, reftype=libref, filetype=folder).
If that fails, the macro will try to get _cstSourceMetadataDefineFileRef
from _cstSASRefs (type=sourcemetadata, subtyp=, reftype=fileref,
filetype=folder).
(6) When _cstSourceMetadataDefineFile or _cstSourceMetadataDefineFileRef has
been specified, then _cstSourceMetadataMapFile needs to be specified. In
case this parameter has not been specified , the macro will attempt to
get this parameter value from the SASReferences data set as specified by
the macro variable _cstSASRefs (type=referencexml, subtype=metamap,
reftype=fileref, filetype=file).
In case the XML Map file can still not be found, the datasetxml_createmap
macro will be used to create the XML Map file (_cstMapType=metamap).
(6) _cstSourceDataMapFile needs to be specified. In case this parameter has
not been specified , the macro will attempt to get this parameter value
from the SASReferences data set as specified by the macro variable
_cstSASRefs (type=referencexml, subtype=datamap, reftype=fileref,
filetype=file).
In case the XML Map file can still not be found, the datasetxml_createmap
macro will be used to create the XML Map file (_cstMapType=datamap).
(7) When _cstSourceMetadataLibrary is specified, the following data sets
are expected to exist in this library:

definedocument
study
metadataversion
itemgroupdefs
itemgroupdefitemrefs (CRT-DDS 1.0)
itemgroupitemrefs (Define-XML 2.0)
itemdefs
translatedtext (Define-XML 2.0)

(8) The Define-XML metadata is used to look up ItemGroupDef/@OID and
ItemDef/@OID based on data set name and variable name.

Expected Macro Variables:
&_cstLRECL - File record length
_cstDebug - Turns debugging on or off for the session. Set _cstDebug=1
        before this macro call to retain work files created in this macro.
_cstResultSeq - Results: Unique invocation of macro
_cstSeqCnt - Results: Sequence number within _cstResultSeq
_cstStandard - Name of a standard registered to the SAS Clinical
        Standards Toolkit
_cstStandardVersion - Version of the standard referenced in _cstStandard
_cst_rc - Task error status
_cst_rcmsg - Message associated with _cst_rc
Parameters:
_cstSourceDatasetXMLFile - - conditional - The complete path to the
        the Dataset-XML file to convert.
        Required if _cstSourceLibrary is not specified.
_cstSourceDatasetXMLLibrary - - conditional - The libref of the source
        DatasetXML folder/library. Required if _cstSourceDatasetXMLFile is
        not specified.
_cstOutputLibrary - - required - The libref of the output data folder/
        library where the dataset-XML files are created.
_cstSourceMetadataLibrary - - conditional - The libref of the source
        metadata folder/library.
_cstSourceMetadataDefineFile - - conditional - The path to the Define-XML
        file.
_cstSourceMetadataDefineFileRef - - conditional - The file reference that
        specifies the location of the Define-XML file.
_cstSourceMetadataMapFile - - conditional - The path to the Map file to
        read Define-XML metadata from an XML file.
        If not provided it will be derived from SASReferences or created.
_cstSourceDataMapFile - - optional - The path to the Map file to read
        Dataset-XML data from an Dataset-XML file.
        If not provided it will be derived from SASReferences or created.
_cstMaxLabelLength - - required - Maximum value of labels to be created.
        Default: 256
_cstdatetimeLength - - required - Length of date and time related
        variables to be created.
        Default: 64
_cstAttachFormats - - optional - Attach formats to data?
        These are the formats as define in the ItemDef/@DisplayFormat
        Define-XML attribute.
        If not provided, Yes is assumed.
        Values: Y | N
        Default: Y
_cstNumObsWrite - - required - Maximum number of observations to write
        in final data step (per loop). This can be used for performance
        tuning.
        Default: 10000
_cstReturn - - required - The macro variable that contains the return
        value as set by this macro.
        Default: _cst_rc
_cstReturnMsg - - required - The macro variable that contains the return
        message as set by this macro.
        Default: _cst_rcmsg
File: datasetxml_read.sas
First available in version: 1.7

%datasetxml_write(_cstSourceDataSets=, _cstSourceLibrary=, _cstOutputLibrary=, _cstSourceMetadataLibrary=, _cstSourceMetadataDefineFile=, _cstSourceMetadataDefineFileRef=, _cstSourceMetadataMapFile=, _cstOutputEncoding=UTF-8, _cstCreationDateTime=, _cstAsOfDateTime=, _cstOriginator=, _cstSourceSystem=, _cstSourceSystemVersion=, _cstHeaderComment=Produced from SAS data using SAS Clinical Standards Toolkit, _cstNumericFormat=best32., _cstCheckLengths=Y, _cstIndent=Y, _cstZip=N, _cstDeleteAfterZip=N, _cstReturn=_cst_rc, _cstReturnMsg=_cst_rcmsg);

[ Exposure: external ]
Create Dataset-XML file from a SAS data set or from a library of SAS data sets

Notes:
(1) Any librefs referenced in macro parameters must be pre-allocated.
(2) Files that previously existed in the output location will be overwritten.
(3) Either _cstSourceDataSets or _cstSourceLibrary must be specified.
In case these parameters have not been specified, the macro will attempt
to get these parameter values from the SASReferences data set that has
been specified by the macro variable _cstSASRefs (type=sourcedata).
When multiple type=sourcedata records have been specified, memnames must
be defined. In case no memnames are specified, only the first record will
be used.
(4) _cstOutputLibrary must be specified. In case this parameter has not been
specified, the macro will attempt to get this parameter value from the
SASReferences data set as specified by the macro variable _cstSASRefs
(type=externalxml).
(5) Either _cstSourceMetadataLibrary, _cstSourceMetadataDefineFile or
_cstSourceMetadataDefineFileRef must be specified.
In case these parameters are not specified, the macro will first attempt
to get _cstSourceMetadataLibrary from the SASReferences data set as
specified by the macro variable _cstSASRefs (type=sourcemetadata,
subtype=, reftype=libref).
If that fails, the macro will try to get _cstSourceMetadataDefineFileRef
from _cstSASRefs (type=sourcemetadata, subtyp=, reftype=fileref).
(6) When _cstSourceMetadataDefineFile or _cstSourceMetadataDefineFileRef has
been specified, then _cstSourceMetadataMapFile needs to be specified. In
case this parameter has not been specified , the macro will attempt to
get this parameter value from the SASReferences data set as specified by
the macro variable _cstSASRefs (type=referencexml, subtype=metamap).
In case the XML Map file can still not be found, the datasetxml_createmap
macro will be used to create the XML Map file (_cstMapType=metamap).
(7) When _cstSourceMetadataLibrary is specified, the following data sets
are expected to exist in this library:

definedocument
study
metadataversion
itemgroupdefs
itemgroupdefitemrefs (CRT-DDS 1.0)
itemgroupitemrefs (Define-XML 2.0)
itemdefs

(8) The Define-XML metadata is used to look up ItemGroupDef/@OID and
ItemDef/@OID based on data set name and variable name.
In case the data set can not be matched, a warning will be written and
the ItemGroupData/@ItemGroupOID attribute will be generated as
"IG.<TABLE>". In case the data set variable can not be matched, a warning
will be written and the ItemData/@ItemOID attribute will be generated as
"IT.<TABLE>.<COLUMN>".
In case the following metadata can not be found, it will be generated:
ODM/@FileOID as "DEFINE" (used as ODM/@PriorFileOID)
ODM/Study/@OID as "STUDY1"
(used as [ReferenceData|ClinicalData]/@StudyOID)
ODM/Study/MetaDataVersion/@OID as "MDV1"
(used as [ReferenceData|ClinicalData]/@MetaDataVersionOID)
(9) The macro allows for zipping the Dataset-XML file (_cstZip=Y), and
optionally deleting the Dataset-XML file after zipping
(_cstDeleteAfterZip=Y).

Expected Macro Variables:
&_cstLRECL - File record length
_cstDebug - Turns debugging on or off for the session. Set _cstDebug=1
        before this macro call to retain work files created in this macro.
_cstResultSeq - Results: Unique invocation of macro
_cstSeqCnt - Results: Sequence number within _cstResultSeq
_cstStandard - Name of a standard registered to the SAS Clinical
        Standards Toolkit
_cstStandardVersion - Version of the standard referenced in _cstStandard
_cst_rc - Task error status
_cst_rcmsg - Message associated with _cst_rc
Parameters:
_cstSourceDataSets - - conditional - A list of source data sets to
        convert. Specified as a blank sperated list of: (libref.)datasete
        Required if _cstSourceLibrary is not specified.
_cstSourceLibrary - - conditional - The libref of the source data folder/
        library. Required if _cstSourceDataSets is not specified.
_cstOutputLibrary - - required - The libref of the output data folder/
        library where the dataset-XML files are created.
_cstSourceMetadataLibrary - - conditional - The libref of the source
        metadata folder/library.
_cstSourceMetadataDefineFile - - conditional - The path to the Define-XML
        file.
_cstSourceMetadataDefineFileRef - - conditional - The file reference that
        specifies the location of the Define-XML file.
_cstSourceMetadataMapFile - - optional - The path to the Map file to
        read Define-XML metadata from an XML file.
        If not provided it will be derived from SASReferences or created.
_cstOutputEncoding - - optional - The XML encoding to use for the
        Dataset-XML file that is created.
        Default: UTF-8
_cstCreationDateTime - - optional - The date/time at which the XML
        document was created. In case no value has been specified the
        current date and time will bu used (ISO 8601).
_cstAsOfDateTime - - optional - The date/time at which the source
        database was queried in order to create this document (ISO 8601).
_cstOriginator - - optional - The organization that generated the ODM
        file.
_cstSourceSystem - - optional - The computer system or database
        management system that is the source of the information in this
        file.
_cstSourceSystemVersion - - optional - The version of _cstSourceSystem.
_cstHeaderComment - - optional - The short comment that is added to the
        top of the Dataset-XML file that is produced.
        Default: Produced from SAS data using the SAS Clinical Standards
        Toolkit
        _cstNumericFormat - required - Format used to write numeric data.
        Default: best32.
_cstNumericFormat - Parameter description not provided
_cstCheckLengths - - optional - If Y, then the actual value lengths of
        variables with DataType=text will be check agaist that lengths as
        defined in the metadata. In case lengths as defined in the metadata
        are too short, a warning will be written to the LOG.
        Values: N | Y
        Default: N
_cstIndent - - optional - If Y, then indent the Dataset-XML file.
        Values: N | Y
        Default: Y
_cstZip - - optional - If Y, then zip the Dataset-XML file to a zip file
        in the same folder and the same name as the Define-XML file.
        Values: N | Y
        Default: N
_cstDeleteAfterZip - - optional - If Y, then delete the Dataset-XML file
        after it has been zipped (_cstZip=Y).
        Values: N | Y
        Default: N
_cstReturn - - required - The macro variable that contains the return
        value as set by this macro.
        Default: _cst_rc
_cstReturnMsg - - required - The macro variable that contains the return
        message as set by this macro.
        Default: _cst_rcmsg
File: datasetxml_write.sas
First available in version: 1.7

%xml_validate(xsdFile=, xmlFolder=, whereClause=);

[ Exposure: external ]
Validate an XML file against a W3C schema file.

Notes:
(1) This macro uses PROC GROOVY, and will only run in SAS versions 9.3 or
later.

Parameters:
xsdFile - - required - The full path to the W3C XML Schema XML file.
xmlFolder - - required - The full path to the folder with XML files to
        validate against the W3C XML Schema.
whereClause - - optional - A valid SAS WHERE clause used in a datastep to
        restrict the XML files in the folder to be validated.
        Examples:
        whereClause=%nrstr(where index(upcase(xmlfile), "DEFINE") eq 0)
        whereClause=%nrstr(where index(upcase(xmlfile), "DEFINE") ge 1)
File: xml_validate.sas
First available in version: 1.7