LIBNAME Statement Syntax

Processes an XML document.

Valid in:	Anywhere
Category:	Data Access

Syntax

LIBNAME libref engine <'SAS-library | XML-document-path'> <options>;

Required Arguments

libref: is a valid SAS name that serves as a shortcut name to associate with the physical location of the XML document. The name must conform to the rules for SAS names. A libref cannot exceed eight characters.

engine

is the engine nickname for the SAS XML LIBNAME engine that imports and exports an XML document.

XML: specifies the XML engine nickname that accesses the SAS 9.1.3 XML engine functionality. The syntax for functionality that is available only for the XML engine nickname is labeled with XML Only.

XMLV2: specifies the XML engine nickname that accesses the SAS 9.2 and 9.3 XML engine functionality. The syntax for functionality that is available only for the XMLV2 engine nickname is labeled with XMLV2 Only.

Alias:XML92

Note:If syntax is not labeled with either

XML
                                 Only

or XMLV2 Only, the functionality is available for both engine nicknames.

Tip:At your site, the engine nicknames could be different if your system administrator assigned an alias to the XML LIBNAME engine. See your system administrator to determine whether an alias is assigned.

'SAS-library | XML-document-path'

is the physical location of the XML document for export or import. Enclose the physical location in single or double quotation marks.

SAS-library ^{XMLV2 Only}: is the pathname for a collection of one or more files that are recognized by SAS and that are referenced and stored as a unit. For example, 'C:\My Documents\XML'.

XML-document-path: includes the pathname, filename, and file extension. For example, 'C:\My Documents\XML\myfile.xml'.

Operating Environment Information: For details about specifying the physical location of files, see the SAS documentation for your operating environment.

Interactions:You can use the FILENAME statement in order to assign a fileref to be associated with the physical location of the XML document to be exported or imported. If the fileref matches the libref, you do not need to specify the physical location of the XML document in the LIBNAME statement. For example, the following code writes to the XML document Fred.XML:

filename bedrock 'C:\XMLdata\fred.xml';

libname bedrock xml;

proc print data=bedrock.fred;
run;

To specify a fileref for the XML document that does not match the libref, you can use the XMLFILEREF= option. For example, the following code writes to the XML document Wilma.XML:

filename cartoon 'C:\XMLdata\wilma.xml';

libname bedrock xml xmlfileref=cartoon;

proc print data=bedrock.wilma;
run;

Optional Arguments

AUTOMAP=REPLACE | REUSE ^{XMLV2 Only}

specifies to automatically generate an XMLMap file to import an XML document. The XMLMap file contains specific syntax that describes how to interpret the XML markup into a SAS data set or data sets, variables (columns), and observations (rows). XMLMap syntax is generated by analyzing the structure of the specified XML document. To automatically generate the XMLMap file, you must specify an existing XML document and the physical location for the output XMLMap file.

REPLACE: overwrites an existing XMLMap file. If an XMLMap file exists at the specified physical location, the generated XMLMap file overwrites the existing one. If an XMLMap file does not exist at the specified physical location, the generated XMLMap file is written to the specified pathname and filename.

REUSE: does not overwrite an existing XMLMap file. If an XMLMap file exists at the specified physical location, the existing XMLMap file is used. If an XMLMap file does not exist at the specified physical location, the generated XMLMap file is written to the specified pathname and filename.

Restriction:Use this option when importing only.

Requirements:You must specify the physical location of an existing XML document with either the complete pathname, filename, and file extension, or with a file reference that is associated with the physical location for the DISK or TEMP device type only. The XML document must exist on disk. The AUTOMAP= option does not support accessing an XML document by using access methods such as FTP, SFTP, URL, or WebDAV.

You must include the XMLMAP= option to specify the physical location of the generated XMLMap file with either the complete pathname, filename, and file extension, or with a file reference that is associated with the physical location for the DISK or TEMP device type only. The AUTOMAP= option does not support accessing an XMLMap file by using access methods such as FTP, SFTP, URL, or WebDAV.

Tips:The functionality to automatically generate an XMLMap file is also available with SAS XML Mapper. The AUTOMAP= option provides the functionality for the XMLV2 LIBNAME engine so that the XMLMap is created and used with a single LIBNAME statement.

You can assign the generated XMLMap file to a temporary location, which is deleted at the end of the SAS session. To do this, associate a file reference to a physical location and specify the TEMP device type.

Example:Importing an XML Document Using the AUTOMAP= Option to Generate an XMLMap

FORMATACTIVE=NO | YES

determines whether SAS formats are used.

For the CDISCODM markup type, FORMATACTIVE= specifies whether CDISC ODM CodeList elements, which contain instructions for transcoding display data in a CDISC ODM document, are to be converted to SAS formats, and vice versa.

NO ^{XML Only}: causes formatting controls to be suppressed for both importing and exporting.

YES ^{XML Only}: when importing, converts the CDISC ODM CodeList elements to the corresponding SAS formats, registers the SAS formats on the referenced variables, and stores the created SAS formats in the format catalog.

When exporting, converts the SAS formats to the corresponding CDISC ODM CodeList elements.

Tips:By default, the format catalog is created in the Work library. If you want to store the catalog in a permanent library, use theFORMATLIBRARY= option.

When the format catalog is updated, the default behavior is that any new SAS formats that are created by converting CDISC ODM CodeList elements will overwrite any existing SAS formats that have the same name. To prevent existing SAS formats from being overwritten, specify FORMATNOREPLACE=YES.

Example:Exporting an XML Document in CDISC ODM Markup

For the GENERIC markup type, specifies whether output values are affected by SAS formats.

NO: writes the actual data value to the XML markup.

YES: causes the XML markup to contain the formatted data value.

Restriction:For the GENERIC markup type, if you export a SAS data set with formatted data values, and then you try to import the XML document back into the existing SAS data set, the import might fail. Exporting a SAS data set with formatted data values can result in different variables or different variable attributes.

Default:NO

Restriction:Use this option for the CDISCODM and GENERIC markup types only.

FORMATLIBRARY=libref ^{XML Only}: specifies the libref of an existing SAS library in which to create the format catalog.

Restrictions:Use this option when importing an XML document only.

Use this option only for the CDISCODM markup type with FORMATACTIVE=YES.

FORMATNOREPLACE=NO | YES ^{XML Only}

specifies whether to replace existing format entries in the format catalog search path in cases where an existing format entry has the same name as a format that is being created by the XML engine when it converts a CDISC ODM CodeList element.

NO: does not replace formats that have the same name.

YES: replaces formats that have the same name.

Default:NO

Restrictions:Use this option when importing an XML document only.

Use this option for the CDISCODM markup type only.

INDENT=integer: specifies the number of columns to indent each nested element in the exported XML document. The value can be from 0 (which specifies no indention) through 32. This specification is cosmetic and is ignored by an XML-enabled browser.

Default:3

Restriction:Use this option when exporting an XML document only.

ODSCHARSET=character-set: specifies the character set to use for the output file. A character set includes letters, logograms, digits, punctuation, symbols, and control characters that are used for display and printing. An example of a character set is ISO-8859-1.

Restriction:Use this option when exporting an XML document only.

Requirement:Use this option with caution. If you are unfamiliar with character sets, encoding methods, or translation tables, do not use this option without proper technical advice.

Tip:The combination of the character set and translation table (encoding method) results in the file's encoding.

See:ODSCHARSET= Option in SAS National Language Support (NLS): Reference Guide.

ODSRECSEP= DEFAULT | NONE | YES ^{XML Only}

controls the generation of a record separator that marks the end of a line in the output XML document.

DEFAULT: enables the XML engine to determine whether to generate a record separator based on the operating environment where you run the SAS job.

The use of a record separator varies by operating environment.

Tip:If you do not transfer XML documents across environments, use the default behavior.

NONE: specifies to not generate a record separator.

The XML engine uses the logical record length of the file that you are writing to and writes one line of XML markup at a time to the output file.

Requirement:The logical record length of the file that you are writing to must be at least as long as the longest line that is produced. If the logical record length of the file is not long enough, then the markup might wrap to another line at an inappropriate place.

Interaction:Transferring an XML document that does not contain a record separator can be a problem. For example, FTP needs a record separator to transfer data properly in ASCII (text) mode.

YES: specifies to generate a record separator.

Default:The XML engine determines whether to generate a record separator based on the operating environment where you run the SAS job.

Restriction:Use this option when exporting an XML document only.

Interaction:Most transfer utilities interpret the record separator as a carriage return sequence. For example, using FTP in ASCII (text) mode to transfer an XML document that contains a record separator results in properly constructed line breaks for the target environment.

ODSTRANTAB=table-name: specifies the translation table to use for the output file. The translation table (encoding method) is a set of rules that are used to map characters in a character set to numeric values. An example of a translation table is one that converts characters from EBCDIC to ASCII-ISO. The table-name can be any translation table that SAS provides or any user-defined translation table. The value must be the name of a SAS catalog entry in either the SASUSER.PROFILE catalog or the SASHELP.HOST catalog.

Restriction:Use this option when exporting an XML document only.

Requirement:Use this option with caution. If you are unfamiliar with character sets, encoding methods, or translation tables, do not use this option without proper technical advice.

Tip:The combination of the character set and translation table results in the file's encoding.

See:ODSTRANTAB= Option in SAS National Language Support (NLS): Reference Guide.

TAGSET=tagset-name: specifies the name of a tagset to override the default tagset that is used by the markup type that is specified with XMLTYPE=.

To change the tags that are produced, you can create a customized tagset and specify it with the TAGSET= option. For information about creating customized tagsets, see the TEMPLATE procedure in the SAS Output Delivery System: User's Guide.

Restriction:Use this option when exporting an XML document only.

Requirement:Use this option with caution. If you are unfamiliar with XML markup, do not use this option.

See:Understanding and Using Tagsets for the XML Engine

Example:Exporting an XML Document Using a Customized Tagset

CAUTION:

If you alter the tagset when exporting an XML document and then attempt to import the XML document generated by that altered tagset, the XML engine might not be able to translate the XML markup back to a SAS proprietary format.

XMLCONCATENATE=NO | YES: specifies whether the file to be imported contains multiple, concatenated XML documents. Importing multiple, concatenated XML documents can be useful (for example, if an application is producing a complete document per query or response as in a Web form).

Alias:XMLCONCAT=

Default:NO

Restriction:Use this option when importing an XML document only.

Requirement:Use XMLCONCATENATE=YES cautiously. If an XML document consists of concatenated XML documents, the content is not standard XML construction. The option is provided for convenience, not to encourage invalid XML markup.

Example:Importing Concatenated XML Documents

XMLDATAFORM=ELEMENT | ATTRIBUTE: specifies whether the tag for the element to contain SAS variable information (name and data) is in open element or enclosed attribute format. For example, if the variable name is PRICE and the value of one observation is 1.98, the generated output for ELEMENT is <PRICE> 1.98 </PRICE> and for ATTRIBUTE is <COLUMN name="PRICE"value="1.98" />.

Default:ELEMENT

Restrictions:Use this option when exporting an XML document only.

Use this option for the GENERIC markup type only.

XMLDOUBLE=DISPLAY | INTERNAL

controls the results of importing or exporting numeric values.

DISPLAY

when exporting, the SAS XML LIBNAME engine retrieves the stored value for the numeric variable, determines an appropriate display for the value in a readable form, and writes the display value to the XML document. The display value is affected by the specified engine nickname and whether a format is assigned.

The XML engine nickname uses an assigned format. The maximum value is 16 digits. For example, if a numeric variable has an assigned format width that is 20 digits, such as BEST20., the engine truncates the exported value. If there is not an assigned format, the engine displays the value using BEST10.
The XMLV2 engine nickname ignores any assigned format and displays the value using BEST16.

When importing, the SAS XML LIBNAME engine retrieves PCDATA (parsed character data) from the named element in the XML document and converts the data into numeric variable content.

Alias:FORMAT

INTERNAL: when exporting, the SAS XML LIBNAME engine retrieves the stored value for the numeric variable and writes the raw value to a generated attribute value pair (of the form rawvalue="value"). SAS uses the base64 encoding of a portable machine representation. (The base64 encoding method converts binary data into ASCII text and vice versa and is similar to the MIME format.)

When importing, the SAS XML LIBNAME engine retrieves the stored value from the rawvalue= attribute from the named element in the XML document. It converts that value into numeric variable content. The PCDATA content of the element is ignored. When importing, XMLDOUBLE=INTERNAL is not supported for the XMLV2 engine nickname.

Alias:PRECISION

Tip:Typically, you use XMLDOUBLE=INTERNAL to import or export an XML document when content is more important than readability.

Default:DISPLAY

Restriction:You can specify the XMLDOUBLE= option for the GENERIC markup type only.

Examples:Exporting Numeric Values

Importing an XML Document with Numeric Values

XMLENCODING='encoding-value': overrides the SAS data set's encoding for the output file. If an encoding value contains a hyphen, enclose the value in quotation marks.

Restriction:Use this option when exporting an XML document only.

Requirement:Use this option with caution. If you are unfamiliar with character sets, encoding methods, or translation tables, do not use this option without proper technical advice.

Tips:When transferring an XML document across environments (for example, using FTP), you must be aware of the document's content to determine the appropriate transfer mode. If the document contains an encoding attribute in the XML declaration, or if a byte-order mark (BOM) precedes the XML declaration, transfer the XML document in binary mode. If the document contains neither of these and you are transferring the document across similar environments, transfer the XML document in text mode.

The combination of the character set and translation table (encoding method) results in the file's encoding.

See:XMLENCODING= option in SAS National Language Support (NLS): Reference Guide.

XMLFILEREF=fileref

is the SAS name that is associated with the physical location of the XML document to be exported or imported. To assign the fileref, use the FILENAME statement. The XML engine can access any data referenced by a fileref. For example, the following code writes to the XML document Wilma.XML:

filename cartoon 'C:\XMLdata\wilma.xml';

libname bedrock xml xmlfileref=cartoon;

proc print data=bedrock.wilma;
run;

Tip:When using the URL access method to reference a fileref that is assigned to an XML document, you should also specify an XMLMap. Specifying an XMLMap causes the XML engine to process the XML document with a single pass. Whether you need to specify an XMLMap depends on your Web server. For an example, see Referencing a Fileref Using the URL Access Method.

XMLMAP=fileref | 'XMLMap'

specifies an XML document that you create that contains specific XMLMap syntax. The syntax tells the XML engine how to interpret the XML markup for importing or exporting. The XMLMap syntax is itself XML markup.

fileref: is the SAS name that is associated with the physical location of the XMLMap. To assign a fileref, use the FILENAME statement.

Tip:To assign a fileref to an XMLMap using the URL access method, your Web server might require that the file extension be .xml instead of .map.

'XMLMap': is the physical location of the XMLMap. Include the complete pathname and the filename. It is suggested that you use the filename extension .map. Enclose the physical name in single or double quotation marks.

For example, the following statements import an XML document named MY.XML and specify the XMLMap named MY.MAP, which contains specific XMLMap syntax. The XML engine interprets the XML document as a SAS data set named TEST.MY. In this example, XMLMAP= is used as an option in the LIBNAME statement:

libname test xml 'C:\XMLdata\my.xml' xmlmap='C:\XMLdata\my.map';

proc print data=test.my;
run;

Restrictions:The XMLV2 engine nickname supports XMLMap syntax versions 1.2, 1.9, and 2.1. The XMLV2 engine nickname does not support XMLMap versions 1.0 or 1.1.

The XML engine nickname supports XMLMap syntax versions 1.0, 1.1, and 1.2. The XML engine nickname does not support XMLMap syntax versions 1.9 or 2.1.

Requirement:If you specify an XMLMap, specify XMLTYPE=XMLMAP or do not specify a markup type. If you explicitly specify a markup type other than XMLMAP (such as XMLTYPE=GENERIC), an error occurs.

See:XMLMap Syntax: Overview

Example:Importing XML Documents Using an XMLMap

XMLMETA=DATA | SCHEMADATA | SCHEMA

specifies whether to include metadata-related information in the exported markup, or specifies whether to import metadata-related information that is included in the input XML document.

Metadata-related information is metadata that describes the characteristics (types, lengths, levels, and so on) of columns within the table markup. Including the metadata-related information can be useful when exporting an XML document from a SAS data set to process on an external product.

DATA: ignores metadata-related information. DATA includes only data content in the exported markup and imports only data content in the input XML document.

SCHEMADATA: includes both data content and metadata-related information in the exported markup and imports both data content and metadata-related information in the input XML document.

SCHEMA: ignores data content. SCHEMA includes only metadata-related information in the exported markup and imports only metadata-related information in the input XML document.

Default:DATA

Restriction:Use this option for the GENERIC and MSACCESS markup types only.

Interaction:If XMLMETA=SCHEMADATA and XMLSCHEMA= is specified, the data is written to the physical location of the XML document specified in the LIBNAME statement. Separate metadata-related information is written to the physical location specified with XMLSCHEMA=. If XMLSCHEMA= is not specified, the metadata-related information is embedded with the data content in the XML document.

Tip:Prior to SAS 9, the functionality for the XMLMETA= option used the keyword XMLSCHEMA=. SAS 9 changed the option keyword XMLSCHEMA= to XMLMETA=. SAS 9.1 added new functionality using the XMLSCHEMA= option.

Examples:Exporting an XML Document with Separate Metadata

Importing an XML Document Created by Microsoft Access

XMLPROCESS=CONFORM | PERMIT

determines how the XML engine processes character data that does not conform to W3C specifications.

CONFORM: requires that the XML conform to W3C specifications. W3C specifications state that for character data, certain characters such as the left angle bracket (<), the ampersand (&), and the apostrophe (') must be escaped using character references or strings like &. For example, to allow attribute values to contain both single and double quotation marks, the apostrophe or single quotation mark character (') can be represented as ' and the double quotation mark character (") can be represented as ".

PERMIT: permits character data that does not conform to W3C specifications to be accepted. That is, in character data, non-escaped characters such as the apostrophe, double quotation marks, and the ampersand are accepted.

Restrictions:Non-escaped angle brackets in character data are not accepted.

Use XMLPROCESS=PERMIT cautiously. If an XML document consists of non-escaped characters, the content is not standard XML construction. The option is provided for convenience, not to encourage invalid XML markup.

Default:CONFORM

Example:Importing an XML Document with Non-Escaped Character Data

XMLSCHEMA=fileref | 'external-file'

specifies an external file to contain metadata-related information.

fileref: is the SAS name that is associated with the physical location of the output file. To assign a fileref, use the FILENAME statement.

'external-file': is the physical location of the file to contain the metadata-related information. Include the complete pathname and the filename. Enclose the physical name in single or double quotation marks.

Restrictions:Use this option when exporting an XML document only.

Use this option only for the GENERIC and MSACCESS markup types with XMLMETA=SCHEMADATA.

Example:Exporting an XML Document with Separate Metadata

XMLTYPE=GENERIC | CDISCODM | MSACCESS | ORACLE | XMLMAP

specifies the XML markup type.

GENERIC: is a simple, well-formed XML markup type. The XML document consists of a root (enclosing) element and repeating element instances. GENERIC determines a variable's attributes from the data content.

Requirement:When importing, the GENERIC markup type requires a specific physical structure.

See:Understanding the Required Physical Structure for an XML Document to Be Imported Using the GENERIC Markup Type

Examples:Exporting an XML Document Containing SAS Dates, Times, and Datetimes

Exporting Numeric Values

Importing an XML Document Using the GENERIC Markup Type

CDISCODM ^{XML Only}: is the XML markup type for the markup standards that are defined in the Operational Data Model (ODM) that was created by the Clinical Data Interchange Standards Consortium (CDISC). The XML engine supports the ODM 1.2 schema specification. ODM supports the electronic acquisition, exchange, and archiving of clinical trials data and metadata for medical and biopharmaceutical product development.

Tip:Use the FORMATACTIVE=, FORMATNOREPLACE=, and FORMATLIBRARY= options to specify how display data are read and stored in the target environment.

Examples:Importing a CDISC ODM Document

Exporting an XML Document in CDISC ODM Markup

MSACCESS ^{XML Only}: is the XML markup type for the markup standards supported for a Microsoft Access database (.mdb). If the Microsoft Access file contains metadata-related information, then you must specify MSACCESS rather than the default GENERIC markup type. If there is an embedded XML schema, specifying MSACCESS and the XMLMETA=SCHEMADATA option causes a variable's attributes to be obtained from the embedded schema. If there is not an embedded schema, MSACCESS uses default values for attributes.

Example:Importing an XML Document Created by Microsoft Access

ORACLE ^{XML Only}: is the XML markup type for the markup standards equivalent to the Oracle 8i XML implementation. The number of columns to indent each nested element is one, and the enclosing element tag for the contents of the SAS data set is ROWSET.

Example:Exporting an XML Document for Use by Oracle

XMLMAP ^{XMLV2 Only}: specifies that XML markup is determined by an XMLMap, which is an XML document that you create that contains specific XMLMap syntax. The XMLMap syntax tells the XML engine how to map the SAS data back into the specific XML document structure. To specify the XMLMap in the LIBNAME statement, use the XMLMAP= option.

Restriction:Exporting an XML document that is controlled by an XMLMap is limited to a single SAS data set.

Example:Using an XMLMap to Export an XML Document with a Hierarchical Structure

Default:GENERIC

Tip:You can control the markup by specifying options such as INDENT=, XMLDATAFORM=, XMLMETA= (when applicable), and TAGSET=.