LIBNAME Statement Syntax

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.

XML | XML92

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.

XML92

specifies the XML engine nickname that accesses new engine functionality with additional enhancements and changes. The documentation for the new functionality is labeled with the symbol XML92 Only.

Note:   At your site, the XML engine nickname could be different if your system administrator assigned an alias to the XML engine. See your system administrator to determine whether an alias was 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.

XML92 Only SAS-library

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'

Restriction:	The functionality is available for the XML92 engine nickname only.
Tip:	You can use a wildcard character to substitute for document names. For example: 'C:\My Documents\XML\*.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.  

Interaction:

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;

The following options are the basic options for the XML engine:

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.

FORMATACTIVE=NO | YES

For the CDISCODM markup type, 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

causes formatting controls to be suppressed for both importing and exporting.

YES

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.

Default:	NO
Tip:	By default, the format catalog is created in the Work library. If you want to store the catalog in a permanent library, use the FORMATLIBRARY= option.
Tip:	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.

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.

FORMATLIBRARY=libref

specifies the libref of an existing SAS library in which to create the format catalog.

Restriction:

Use this option only when importing an XML document for the CDISCODM markup type and when FORMATACTIVE=YES.

FORMATNOREPLACE=NO | YES

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
Restriction:	Use this option only when importing an XML document for the CDISCODM markup type.

XMLCONCATENATE | XMLCONCAT=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/response, as in a Web form).

Default:	NO
Restriction:	Use this option when importing an XML document only.
Restriction:	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.
Featured in:	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 it is <COLUMN name="PRICE" value="1.98" />.

Default:

ELEMENT

Restriction:	Use this option when exporting an XML document only.
Restriction:	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 XML 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. In some cases, values might not be displayed completely, or they might show truncation or rounding artifacts.

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

Alias:

FORMAT

INTERNAL

when exporting, the XML 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 a 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 XML engine retrieves the value from the rawvalue= attribute from the named element in the XML document and converts that value to numeric variable content. The PCDATA content of the element is ignored.

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

Alias:

PRECISION

Default:	For the GENERIC markup type, the default is XMLDOUBLE=DISPLAY.
Restriction:	You can specify the XMLDOUBLE= option for the GENERIC markup type only.
Interaction:	The EXPORT markup type uses XMLDOUBLE=INTERNAL. You cannot specify XMLDOUBLE=DISPLAY for the EXPORT markup type.
Featured in:	Exporting Numeric Values and Importing an XML Document with Numeric Values

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.

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.

Alias:	DATA NONE, NO, IGNORE SCHEMADATA FULL, YES
Default:	DATA
Restriction:	Use this option for the MSACCESS markup type only.
Interaction:	For XMLMETA=SCHEMADATA, if XMLSCHEMA= is specified, separate metadata-related information is written to the physical location specified with XMLSCHEMA=. The data content is written to the physical location of the XML document specified in the LIBNAME statement. If XMLSCHEMA= is not specified, the metadata-related information is embedded with the data content in the XML document.
Tip:	Before 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.
Featured in:	Exporting an XML Document Containing SAS Dates, Times, and Datetimes

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 &amp;. 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 &apos; and the double-quotation mark character (") can be represented as &quot;.

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.

Restriction:	Non-escaped angle brackets in character data are not accepted.
Restriction:	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
Featured in:	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.

Restriction:	Use this option only when exporting an XML document and with XMLMETA=SCHEMADATA specified.
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, and 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.
Featured in:	Exporting an XML Document with Separate Metadata

XMLTYPE=GENERIC | CDISCODM| EXPORT | MSACCESS | ORACLE | XMLMAP

specifies the XML markup type:

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

GENERIC

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.
Featured in:	Exporting an XML Document Containing SAS Dates, Times, and Datetimes, Exporting Numeric Values, Importing an XML Document Using the GENERIC Markup Type, and several examples throughout the document.

CDISCODM

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.

Note:   The functionality is available for the XML engine nickname only. The CDISCODM markup type is not available for the XML92 engine nickname.  

Tip:	Use the FORMATACTIVE=, FORMATNOREPLACE=, and FORMATLIBRARY= options to specify how display data are read and stored in the target environment.
Featured in:	Importing a CDISC ODM Document and Exporting an XML Document in CDISC ODM Markup

EXPORT

is an alias to specify the XML format that is most commonly used in the industry. Specifying XMLTYPE=EXPORT is the same as specifying XMLTYPE=OIMDBM.

Note:   The functionality is available for the XML engine nickname only. The EXPORT markup type is not available for the XML92 engine nickname.  

MSACCESS

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.

Note:   The functionality is available for the XML engine nickname only. The MSACCESS markup type is not available for the XML92 engine nickname.  

Featured in:

Importing an XML Document Created by Microsoft Access

ORACLE

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.

Featured in:

Exporting an XML Document for Use by Oracle

XML92 Only XMLMAP

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 on the LIBNAME statement, see XMLMAP=.

Restriction:	The functionality is available for the XML92 engine nickname only.
Restriction:	Use this option when exporting an XML document only.

The following options are for National Language Support (NLS) support, which is the ability of a software program to handle more than one language, country, and cultural setting.

CAUTION:

These options should be used with caution.

If you are unfamiliar with character sets, encoding methods, or translation tables, do not use these options without proper technical advice.   

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.
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): User's Guide.

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.
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): User's Guide.

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.
Tip:	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.
Tip:	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): User's Guide.

The following advanced options provide customization:

ODSRECSEP= DEFAULT | NONE | YES

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 in order 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.

TAGSET=tagset-name

specifies the name of a tagset in order to override the default tagset that is used by the markup type that is specified with XMLTYPE=. For more information on tagsets, see Understanding and Using Tagsets for the XML Engine.

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 PROC TEMPLATE in the SAS Output Delivery System: User's Guide.

Restriction:	Use this option with caution. If you are unfamiliar with XML markup, do not use this option.
Restriction:	Use this option when exporting an XML document only.
Featured in:	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 SAS proprietary format.   

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. See Creating an XMLMap for the XML tag names and descriptions.

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 (table) named 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;

Restriction:	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.
Featured in:	Importing XML Documents Using an XMLMap

Copyright © 2007 by SAS Institute Inc., Cary, NC, USA. All rights reserved.