[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]

XML Interface

Introduction

When working with XML documents, Creo Elements/Direct Modeling maintains an representation of the documents on the C++ level. The functions below provide an interface to read and manipulate these documents.

Note that the objects are not automatically garbage-collected. It is recommended to call the function sd-xml-clear-cache after processing of the XML document is done.

Example

Detailed example Lisp code about reading, writing and processing XML can be found here.

Functions

Read / Write XML files

Processing XML documents

Processing XML elements

Miscelleanous

Function Index Top of Page

SD-XML-READ-FILE  [function]

(sd-xml-read-file filename)
Description:
Reads an XML document from a file.

Parameters:
filename {STRING} - the name of the file to read

Return Value:
document {XML DOCUMENT} - reference to the XML document
nil - failure

Example:
(setf my-xml-document (sd-xml-read-file "d:/temp/document.xml"))
  

Function Index Top of Page

SD-XML-WRITE-FILE  [function]

(sd-xml-write-file document filename :pretty-print pretty-print :encoding encoding)
Description:
Writes an XML document to a file.

Parameters:
document {XML DOCUMENT} - reference to the XML document
filename {STRING} - name of the file to write
:pretty-print {BOOLEAN [t]} - optional parameter to write formatted output with line breaks and indentation
:encoding {STRING ["UTF-8"]} - optional parameter to specify the encoding
legal values are "UTF-8" and "UTF-16"

Return Value:
t - success
nil - failure

Example:
(setf result (sd-xml-write-file my-xml-document "d:/temp/document.xml"))
  

Function Index Top of Page

SD-XML-GET-ROOT-NAME  [function]

(sd-xml-get-root-name filename)
Description:
Reads only the root name of an XML document in a file. Reading only the root name is much more efficient than reading whole document and inquiring then the name of the root element. This function might be very useful if specific handlers are registered for xml files with certain root name.

Parameters:
filename {STRING} - the name of the file to read

Return Value:
name {STRING} - the root name

Example:
(setf root-name (sd-xml-get-root-name "d:/temp/document.xml"))
=> "root"
  

Function Index Top of Page

SD-XML-SERIALIZE  [function]

(sd-xml-serialize document)
Description:
Serializes an XML document into a string.

Parameters:
document {XML DOCUMENT} - reference to the XML document

Return Value:
content {STRING} - the document content as a string

Example:
(setf content (sd-xml-serialize my-xml-document))
=> "<root><element1/></root>"
  

Function Index Top of Page

SD-XML-DESERIALIZE  [function]

(sd-xml-deserialize content)
Description:
Creates an XML document from a string.

Parameters:
content {STRING} - the document content as a string

Return Value:
document {XML DOCUMENT} - an XML document

Example:
(setf my-xml-document (sd-xml-deserialize "<root><element1/></root>"))
  

Function Index Top of Page

SD-XML-CREATE-DOCUMENT  [function]

(sd-xml-create-document)
Description:
Creates a new document object in memory.

Return Value:
document {XML DOCUMENT} - pointer to the XML document

Example:
(setf my-xml-document (sd-xml-create-document))
  

Function Index Top of Page

SD-XML-DOCUMENT-GET-ROOT  [function]

(sd-xml-document-get-root document)
Description:
Gets the root element of the document.

Parameters:
document {XML DOCUMENT} - reference to the XML document

Return Value:
element {XML ELEMENT} - the root XML element

Example:
(setf root-element (sd-xml-document-get-root my-xml-document))
  

Function Index Top of Page

SD-XML-DOCUMENT-SET-ROOT  [function]

(sd-xml-document-set-root document element)
Description:
Sets the root element of the document.

Parameters:
document {XML DOCUMENT} - reference to the XML document
element {XML ELEMENT} - the new root XML element

Return Value:
element {XML ELEMENT} - the root element

Example:
(setf root-element (sd-xml-document-set-root my-xml-document element))
  

Function Index Top of Page

SD-XML-DOCUMENT-SELECT-ELEMENT  [function]

(sd-xml-document-select-element document xpath)
Description:
Gets a document element by its XPath.

Parameters:
document {XML DOCUMENT} - reference to the XML document
xpath {STRING} - the XPath of the element, might be single element path or element which has a certain attribute of specific value

Return Value:
element {XML ELEMENT} - the selected element

Example:
(setf element (sd-xml-document-select-element my-xml-document "/root/element1"))
(setf element (sd-xml-document-select-element my-xml-document "/root/element1[@key1='value1']"))
  

Function Index Top of Page

SD-XML-CREATE-ELEMENT  [function]

(sd-xml-create-element document name)
Description:
Creates a new XML element with specified name.

Parameters:
document {XML DOCUMENT} - reference to the XML document
name {STRING} - name of the element

Return Value:
element {XML ELEMENT} - the created XML element

Example:
(setf my-xml-element (sd-xml-create-element my-xml-document "element1"))
  

Function Index Top of Page

SD-XML-ELEMENT-GET-NAME  [function]

(sd-xml-element-get-name element)
Description:
Gets the name of an XML element.

Parameters:
element {XML ELEMENT} - the element to inquire the name from

Return Value:
name {STRING} - the element name

Example:
(setf element-name (sd-xml-element-get-name my-xml-element))
=> "element1"
  

Function Index Top of Page

SD-XML-ELEMENT-GET-CHILDREN  [function]

(sd-xml-element-get-children element)
Description:
Gets all children of the element.

Parameters:
element {XML ELEMENT} - the element to inquire

Return Value:
children {List of XML ELEMENTs} - a list of child elements

Example:
(setf element-children (sd-xml-element-get-children my-xml-element))
  

Function Index Top of Page

SD-XML-ELEMENT-GET-NAMED-CHILDREN  [function]

(sd-xml-element-get-named-children element name)
Description:
Gets all children of the element with a given name.

Parameters:
element {XML ELEMENT} - the element to inquire
name {STRING} - the name of the children to inquire

Return Value:
children {List of XML ELEMENTs} - a list of child elements with specified name

Example:
(setf element-children (sd-xml-element-get-named-children my-xml-element "element2"))
  

Function Index Top of Page

SD-XML-ELEMENT-GET-NAMED-CHILD  [function]

(sd-xml-element-get-named-child element name)
Description:
Gets the first child of the element with a given name. It is basically the same function like sd-xml-element-get-named-children. Only the first child element is returned.

Parameters:
element {XML ELEMENT} - the element to inquire
name {STRING} - the name of the child to inquire

Return Value:
element {XML ELEMENT} - the first child element with this name

Example:
(setf element-child (sd-xml-element-get-named-child my-xml-element "element2"))
  

Function Index Top of Page

SD-XML-ELEMENT-ADD-CHILD  [function]

(sd-xml-element-add-child parent-element child-element)
Description:
Adds a child XML element to a given parent XML element.

Parameters:
parent-element {XML ELEMENT}
child-element {XML ELEMENT}

Return Value:
t - success
nil - failure

Example:
(setf result (sd-xml-element-add-child my-xml-element child-element))
  

Function Index Top of Page

SD-XML-ELEMENT-GET-TEXT  [function]

(sd-xml-element-get-text element)
Description:
Gets the text content of an XML element.

Parameters:
element {XML ELEMENT} - the element to inquire

Return Value:
content {STRING} - the text content

Example:
(setf text (sd-xml-element-get-text my-xml-element))
=> "XML element value"
  

Function Index Top of Page

SD-XML-ELEMENT-SET-TEXT  [function]

(sd-xml-element-set-text element text)
Description:
Sets the text content of an XML element.

Parameters:
element {XML ELEMENT} - the element to change the content
text {STRING} - the new text content

Return Value:
t - success
nil - failure

Example:
(setf result (sd-xml-element-set-text my-xml-element "XML element value"))
  

Function Index Top of Page

SD-XML-ELEMENT-GET-ATTRIBUTES  [function]

(sd-xml-element-get-attributes element)
Description:
Gets the keys of all attributes of an XML element.

Parameters:
element {XML ELEMENT} - the element to inquire

Return Value:
attributes {List of STRINGs} - a list of attribute keys
nil - element does not have any attribute

Example:
(setf attribute-keys (sd-xml-element-get-attributes my-xml-element))
=> ("key1" "key2")
  

Function Index Top of Page

SD-XML-ELEMENT-GET-ATTRIBUTE  [function]

(sd-xml-element-get-attribute element attribute-key)
Description:
Gets the attribute value of an XML element.

Parameters:
element {XML ELEMENT} - the element to inquire
attribute-key {STRING} - the attribute key to inquire

Return Value:
value {STRING} - the attribute value
nil - the attribute is not set

Example:
(setf attribute-value (sd-xml-element-get-attribute my-xml-element "key1"))
=> "value1"
  

Function Index Top of Page

SD-XML-ELEMENT-SET-ATTRIBUTE  [function]

(sd-xml-element-set-attribute element attribute-key attribute-value)
Description:
Sets the attribute value of an XML element for a specified attribute key.

Parameters:
element {XML ELEMENT} - the element to change
attribute-key {STRING} - the attribute key to change the value
attribute-value {STRING} - the new attribute value

Return Value:
t - success
nil - failure

Example:
(setf result (sd-xml-element-set-attribute my-xml-element "key1" "value_modified"))
  

Function Index Top of Page

SD-XML-ELEMENT-GET-PARENT  [function]

(sd-xml-element-get-parent element)
Description:
Gets the parent of an XML element.

Parameters:
element {XML ELEMENT} - the element to inquire

Return Value:
element {XML ELEMENT} - the parent element

Example:
(setf element-parent (sd-xml-element-get-parent my-xml-element))
  

Function Index Top of Page

SD-XML-ELEMENT-GET-DOCUMENT  [function]

(sd-xml-element-get-document element)
Description:
Gets the owner document of an XML element.

Parameters:
element {XML ELEMENT} - the element to inquire

Return Value:
document {XML DOCUMENT} - the owner document

Example:
(setf my-xml-document (sd-xml-element-get-document my-xml-element))
  

Function Index Top of Page

SD-XML-TRANSFORM-FILE  [function]

(sd-xml-transform-file document stylesheet outputFile)
Description:
Applies an XSLT transformation to an XML document.

Parameters:
document {XML DOCUMENT} - reference to the XML document
stylesheet {STRING} - path to a stylesheet file
outputFile {STRING} - path to a output XML file

Return Value:
t - success
nil - failure
On success XML file containing transformed document mentioned by outputFile parameter is created.

Example:
(sd-xml-transform-file my-xml-document "d:/temp/stylesheet.xsl" "d:/temp/outputfile.xml")
  

Function Index Top of Page

SD-XML-CLEAR-CACHE  [function]

(sd-xml-clear-cache)
Description:
Disposes all XML documents and elements created through the LISP interface. LISP references to any of the objects obtained by the LISP API will become invalid.

Example:
(sd-xml-clear-cache)
  

[Integration Kit Contents] [Integration Kit What's New] [Integration Kit Function Index] [More Documentation] [PTC]
© 2023 Parametric Technology GmbH
(a subsidiary of PTC Inc.), All Rights Reserved