SUMMARY | DETAIL

Module Dataset-XML V1.0.0 (Runtime)

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

%datasetxml_createmap(_cstMapFile=, _cstMapType=metamap, _cstMapVersion=1.9, _cstOutputEncoding=UTF-8, _cstValueLength=2000, _cstNameSpace=def:);

Creates XML maps required by the Dataset-XML read and write macros.

Expected Macro Variables:

_cstDebug - Turns debugging on or off for the session. Set _cstDebug=1
        before this macro call to retain work files created by this macro.

Parameters:

_cstMapFile  - required - The path to the XML map file to create.

_cstMapType  - required - The type of XML map file to create.
        Values: metamap | datamap
        Default: metamap

_cstMapVersion  - required - The version of the XML map file to create.
        Default: 1.9

_cstOutputEncoding  - optional - The XML encoding to use for the
        XML map file to create.
        Default: UTF-8

_cstValueLength  - required - The length of the Value attribute.

_cstNameSpace  - optional - The extension namespace.
        Default: UTF-8

File: datasetxml_createmap.sas

First available in version: 1.7

%datasetxml_getStatic(_cstName=, _cstVar=);

Returns constant values that are used by other macros.

Parameters:

_cstName  The name of the value to retrieve.
        Values: DATASET_SASREF_TYPE_REFXML | DATASET_SASREF_TYPE_EXTXML |
        DATASET_SASREF_TYPE_SOURCEDATA |
        DATASET_SASREF_TYPE_SOURCEMETADATA |
        DATASET_SASREF_TYPE_TARGETDATA |
        DATASET_SASREF_SUBTYPE_XML | DATASET_SASREF_SUBTYPE_METAMAP |
        DATASET_SASREF_SUBTYPE_DATAMAP |
        DATASET_JAVA_PARAMSCLASS | DATASET_JAVA_IMPORTCLASS |
        DATASET_JAVA_EXPORTCLASS | DATASET_JAVA_PARSEXML
        DATASET_JAVA_PICKLIST

_cstVar  The macro variable to populate with the value.

File: datasetxml_getstatic.sas

First available in version: 1.7

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

Creates a SAS data set or a library of SAS data sets from Dataset-XML files.

Notes:
1. Any librefs referenced in the macro parameters must be pre-allocated.
2. Files that exist in the output location are overwritten.
3. Either _cstSourceDatasetXMLFile or _cstSourceDatasetXMLLibrary must be
specified. If neither of these parameters is specified, the macro
attempts to get these parameter values from the SASReferences data set
that is specified by the macro variable _cstSASRefs (type=externalxml).
When multiple type=externalxml records are specified, filenames must be
defined (with reftype=fileref and filetype=file). If no filenames are
specified, only the first record is used, and reftype=libref,
filetype=folder must be used.
4. _cstOutputLibrary must be specified. If this parameter is not specified,
the macro attempts to get this parameter value from the SASReferences
data set that is specified by the macro variable _cstSASRefs
(type=targetdata, reftype=libref, filetype=folder).
5. _cstSourceMetadataLibrary, _cstSourceMetadataDefineFile, or
_cstSourceMetadataDefineFileRef must be specified.
If none of these parameters is specified, the macro first attempts to get
_cstSourceMetadataLibrary from the SASReferences data set that is
specified by the macro variable _cstSASRefs (type=sourcemetadata,
subtype=, reftype=libref, filetype=folder).
If that fails, the macro attempts to get _cstSourceMetadataDefineFileRef
from _cstSASRefs (type=sourcemetadata, subtyp=, reftype=fileref,
filetype=folder).
6. If _cstSourceMetadataDefineFile or _cstSourceMetadataDefineFileRef is
specified, _cstSourceMetadataMapFile must be specified. If this parameter
is not specified, the macro attempts to get this parameter value from the
SASReferences data set that is specified by the macro variable
_cstSASRefs (type=referencexml, subtype=metamap, reftype=fileref,
filetype=file).
If the XML map file cannot be found, the datasetxml_createmap macro is
used to create the XML map file (_cstMapType=metamap).
7. _cstSourceDataMapFile must be specified. If this parameter is not
specified, the macro attempts to get the parameter value from the
SASReferences data set that is specified by the macro variable
_cstSASRefs (type=referencexml, subtype=datamap, reftype=fileref,
filetype=file).
If the XML map file is not found, the datasetxml_createmap macro is used
to create the XML map file (_cstMapType=datamap).
8. If _cstSourceMetadataLibrary is specified, these data sets must exist in
this library:
definedocument
study
metadataversion
itemgroupdefs
itemgroupdefitemrefs (CRT-DDS 1.0)
itemgroupitemrefs (Define-XML 2.0)
itemdefs
translatedtext (Define-XML 2.0)
9. The Define-XML metadata is used to look up ItemGroupDef/@OID and
ItemDef/@OID based on the data set name and variable name.

          

History:

   2014-09-16

Removed the _cstNumObsWrite parameter.

   2014-10-13

Replace xmlv2 for Dataset-XML with javaobj.

   2016-02-01

Added file:/// protocol to javaobj method call.
DE6058: Revert javaobj back to xmlv2.

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 in which to create the dataset-XML files.

_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 specified, the value is derived from SASReferences or is
        created.

_cstSourceDataMapFile  - optional - The path to the map file to read
        Dataset-XML data from an Dataset-XML file.
        If not specified, the value is derived from SASReferences or is
        created.

_cstMaxLabelLength  - required - The maximum length of labels to create.
        Default: 256

_cstdatetimeLength  - required - The length of date- and time-related
        variables to create.
        Default: 64

_cstAttachFormats  - optional - Attach formats to the data.
        These are the formats as defined in the ItemDef/@DisplayFormat
        Define-XML attribute.
        Values: Y | N
        Default: Y

_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);

Creates a Dataset-XML file from a SAS data set or a library of SAS data sets.

Notes:
1. Any librefs referenced in macro parameters must be pre-allocated.
2. Files that exist in the output location are overwritten.
3. Either _cstSourceDataSets or _cstSourceLibrary must be specified.
If neither of these parameters is specified, the macro attempts to get
these parameter values from the SASReferences data set that is specified
by the macro variable _cstSASRefs (type=sourcedata).
If multiple type=sourcedata records are specified, memnames must be
defined. If no memnames are specified, only the first record is used.
4. _cstOutputLibrary must be specified. If this parameter is not specified,
the macro attempts to get this parameter value from the SASReferences
data set that is specified by the macro variable _cstSASRefs
(type=externalxml).
5. _cstSourceMetadataLibrary, _cstSourceMetadataDefineFile, or
_cstSourceMetadataDefineFileRef must be specified.
If none of these parameters are specified, the macro attempts to get
_cstSourceMetadataLibrary from the SASReferences data set that is
specified by the macro variable _cstSASRefs (type=sourcemetadata,
subtype=, reftype=libref).
If that fails, the macro attempts to get _cstSourceMetadataDefineFileRef
from _cstSASRefs (type=sourcemetadata, subtyp=, reftype=fileref).
6. If_cstSourceMetadataDefineFile or _cstSourceMetadataDefineFileRef has
been specified, _cstSourceMetadataMapFile must be specified. If this
parameter is not specified , the macro attempts to get this parameter
value from the SASReferences data set that is specified by the macro
variable _cstSASRefs (type=referencexml, subtype=metamap).
If the XML mapfile cannot be found, the datasetxml_createmap macro
is used to create the XML mapfile (_cstMapType=metamap).
7. If _cstSourceMetadataLibrary is specified, these data sets must 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 the data set name and variable name.
If the data set cannot be matched, a warning is written and the
ItemGroupData/@ItemGroupOID attribute is generated as "IG.<TABLE>". If
the data set variable cannot be matched, a warning is written and the
ItemData/@ItemOID attribute is generated as "IT.<TABLE>.<COLUMN>".
If this metadata cannot be found, it is 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).

          

History:

   2016-02-01

Added nrbquote to fix unbalanced quotes (DE6033).

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-separated list of: (libref.)dataset
        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 in which to create the dataset-XML files.

_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 specified, it is derived from SASReferences or is created.

_cstOutputEncoding  - optional - The XML encoding to use for the
        Dataset-XML file to create.
        Default: UTF-8

_cstCreationDateTime  - optional - The date/time at which the XML
        document was created. If no value is specified, the current date
        and time are 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 to produce.
        Default: Produced from SAS data using the SAS Clinical Standards
        Toolkit

_cstNumericFormat  - required - The format used to write numeric data.
        Default: best32.

_cstCheckLengths  - optional - The actual value lengths of variables
        with DataType=text are checked against the lengths as defined in
        the metadata. If the lengths as defined in the metadata are too
        short, a warning is written to the log file.
        Values: N | Y
        Default: Y

_cstIndent  - optional - Indent the Dataset-XML file.
        Values: N | Y
        Default: Y

_cstZip  - optional - Zip the Dataset-XML file to a zip file in the same
        folder and with the same name as the Define-XML file.
        Values: N | Y
        Default: N

_cstDeleteAfterZip  - optional - Delete the Dataset-XML file after it is
        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