Previous Page | Next Page

LIBNAME Statement for the XML Engine

LIBNAME Statement Syntax

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 the symbol XML Only.

XML92

specifies the XML engine nickname that accesses the new SAS 9.2 XML engine functionality. The syntax for functionality that is available only for the XML92 engine nickname is labeled with the symbol XML92 Only.

Note:   In the third maintenance release for SAS 9.2, the XML92 functionality is production except for the WSDL markup type, which is preproduction.   [cautionend]

Interaction: If syntax is not labeled with either the XML Only or XML92 Only symbols, 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 XML92 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.  [cautionend]

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;
Options

The following table lists the available LIBNAME statement options. The [check] symbol indicates whether the option is available for an engine nickname.

LIBNAME Statement Options
Task Option XML XML92
When importing Web service results with the WSDL markup type

Specify an HTTP proxy server host name PROXYHOST=
[check]

Specify an HTTP proxy server password PROXYPASSWORD=
[check]

Specify an HTTP proxy server port PROXYPORT=
[check]

Specify an HTTP proxy server user name PROXYUSERNAME=
[check]

Specify a Web server password WEBPASSWORD=
[check]

Specify a Web server user name WEBUSERNAME=
[check]
Determine whether SAS formats are used FORMATACTIVE=
 [check] [check]
When importing or exporting a CDISC ODM XML document with the CDISCODM markup type

Determine whether SAS formats are used FORMATACTIVE=
 [check]

Specify the libref to create a format catalog FORMATLIBRARY=
 [check]

Replace existing format entries in the format catalog FORMATNOREPLACE=
 [check]
Indent nested elements in exported XML document INDENT=
 [check] [check]
Specify the character set to use for the output file ODSCHARSET=
 [check] [check]
Control the generation of a record separator ODSRECSEP=
 [check] [check]
Specify the translation table to use for the output file ODSTRANTAB=
 [check] [check]
Override the default tagset TAGSET=
 [check] [check]
Import concatenated XML documents XMLCONCATENATE=
 [check] [check]
Specify the tag format to contain SAS variable information XMLDATAFORM=
 [check] [check]
Control the results of numeric values XMLDOUBLE=
 [check] [check]
Override the SAS data set's encoding for the output file XMLENCODING=
 [check] [check]
Specify a fileref for the XML document XMLFILEREF=
 [check] [check]
Specify an XMLMap XMLMAP=
 [check] [check]
Determine whether metadata-related information is included XMLMETA=
 [check] [check]
Determine whether to process nonconforming character data XMLPROCESS=
 [check] [check]
Specify an external file to contain exported metadata-related information XMLSCHEMA=
 [check] [check]
Specify the XML markup type XMLTYPE=
 [check] [check]

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.

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.
Featured in: 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.

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

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.
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.
PROXYHOST='hostname' XML92 Only

specifies an HTTP proxy server host name. An example is proxyhost='proxygw.abc.sas.com'.

Restriction: Use this option for the WSDL markup type only.
Restriction: The functionality is for the third maintenance release for SAS 9.2.
PROXYPASSWORD='password' XML92 Only

specifies an HTTP proxy server password. This option is required only if your proxy server requires credentials. The password is case sensitive and must be enclosed in single or double quotation marks. An example is proxypassword='Abc_123'.

Restriction: Use this option for the WSDL markup type only.
Restriction: The functionality is for the third maintenance release for SAS 9.2.
PROXYPORT=number XML92 Only

specifies an HTTP proxy server port. An example is proxyport=80.

Restriction: Use this option for the WSDL markup type only.
Restriction: The functionality is for the third maintenance release for SAS 9.2.
PROXYUSERNAME='user-ID' XML92 Only

specifies an HTTP proxy server user name. This option is required only if your proxy server requires credentials. The user ID is case sensitive and must be enclosed in single or double quotation marks. An example is proxyusername='test_acc'.

Restriction: Use this option for the WSDL markup type only.
Restriction: The functionality is for the third maintenance release for SAS 9.2.
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=.

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 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 also: Understanding and Using Tagsets for the XML Engine
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.   [cautionend]
WEBPASSWORD='password' XML92 Only

specifies a password for either Basic or NTLM Web server authentication. The password is case sensitive and must be enclosed in single or double quotation marks. An example is webpassword='MyPW'.

Restriction: Use this option for the WSDL markup type only.
Restriction: The functionality is for the third maintenance release for SAS 9.2.
WEBUSERNAME='user-ID' XML92 Only

specifies a user name for either Basic or NTLM Web server authentication. The user ID is case sensitive and must be enclosed in single or double quotation marks. An example is webusername='mydomain\myuserid'.

Restriction: Use this option for the WSDL markup type only.
Restriction: The functionality is for the third maintenance release for SAS 9.2.
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.
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.
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 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 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.
Featured in: Exporting Numeric Values and 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.
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): 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;
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 Files for the XML Engine
Featured in: 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.

Alias:
DATA

NONE, NO, IGNORE

SCHEMADATA

FULL, YES
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: 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 with Separate Metadata and 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 &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 when exporting an XML document only.
Restriction: Use this option only for the GENERIC and MSACCESS markup types with XMLMETA=SCHEMADATA.
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.
Featured in: Exporting an XML Document with Separate Metadata
XMLTYPE=GENERIC | CDISCODM | EXPORT | MSACCESS | ORACLE | WSDL | 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

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.
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 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.
Featured in: Importing a CDISC ODM Document and Exporting an XML Document in CDISC ODM Markup
EXPORT XML Only

is an alias to specify the XML format that is most commonly used in the industry. For the XML engine, specifying XMLTYPE=EXPORT is the same as specifying XMLTYPE=OIMDBM, which was deprecated in SAS 9. Future releases will upgrade this format specification, as needed.

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.

Featured in: 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.

Featured in: Exporting an XML Document for Use by Oracle
WSDL XML92 Only (Preproduction)

is the XML markup type that interacts with a WSDL file to invoke a Web service and import the Web service results. The WSDL markup type interacts with a WSDL file that supports the markup standards of WSDL 1.1.

Restriction: The functionality is for SAS 9.2 Phase 2 and later.
Restriction: Use this option to import Web service results only.
Restriction: The import element, which references other WSDL files, is not supported.
Restriction: For data types that are defined in the type= attribute in an XML schema element element, only the integer, string, and double data types are supported.
Restriction: For the complexType element, which determines the set of attributes and the content of an element, the name= attribute is not supported.
Restriction: The simpleType element is not supported.
Requirement: The Web service must specify a document-oriented SOAP operation. Therefore, the WSDL file must include the soap:operation element style= attribute that is either set or defaults to the document value. For information about the soap:operation element style= attribute, see the W3C WSDL 1.1 specification.
Requirement: The Web service must require both input and output parameters. A Web service that does not accept input parameters or has no return value is not supported.
See: Importing Web Service Results Using the WSDL Markup Type (Preproduction)
See also: PARMS= Data Set Option
XMLMAP XML92 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, see XMLMAP=.

Restriction: Exporting an XML document that is controlled by an XMLMap is limited to a single SAS data set.
Featured in: Using an XMLMap to Export an XML Document with a Hierarchical Structure

Previous Page | Next Page | Top of Page

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