C$XML

The C$XML routine allows to deal with XML documents. It allows to parse documents and change their content as well as create new documents from scratch.

When writing content to the XML document, the following data conversion rules are applied:

•	Text is encoded using the character set specified by the iscobol.encoding * property

•	Trailing spaces in alphanumeric parameters are trimmed

•	Leading zeros are kept in numeric values

Syntax:

CALL "C$XML" USING opCode                      parameters              GIVING returnCode

Parameters:

opCode	Is the function to be executed. Valid values, defined in ..., are:
	CXML-PARSE-FILE	Opens a XML file and returns the XML tree
	CXML-RELEASE-PARSER	Releases memory used by the XML tree
	CXML-GET-FIRST-CHILD	Returns the first child of a given element
	CXML-GET-NEXT-SIBLING	Returns the next sibling of a given element
	CXML-GET-PARENT	Returns the parent element of a given element
	CXML-GET-DATA	Returns the name and the CDATA of a given element
	CXML-GET-ATTRIBUTE-COUNT	Returns the number of attributes of a given element
	CXML-GET-ATTRIBUTE	Returns the name and the value of a given attribute
	CXML-GET-LAST-ERROR	Returns the last error
	CXML-OPEN-FILE	Opens a XML file without parsing it
	CXML-PARSE-STRING	Parses a string as XML
	CXML-PARSE-NEXT-RECORD	Parses the next record in the element
	CXML-GET-PREV-SIBLING	Returns the previous sibling of a given element
	CXML-NEW-PARSER	Creates an empty XML document in memory
	CXML-GET-ATTRIBUTE-BY-NAME	Returns the attribute with the given name along with its value
	CXML-GET-CHILD-BY-NAME	Returns the child element with the given name
	CXML-GET-CHILD-BY-CDATA	Returns the child element with the given CDATA
	CXML-GET-CHILD-BY-ATTR-NAME	Returns the child element with the given attribute
	CXML-GET-CHILD-BY-ATTR-VALUE	Returns the child element with the given attribute value
	CXML-GET-SIBLING-BY-NAME	Returns the sibling element with the given name
	CXML-GET-SIBLING-BY-CDATA	Returns the sibling element with the given CDATA
	CXML-GET-SIBLING-BY-ATTR-NAME	Returns the sibling element with the given attribute
	CXML-GET-SIBLING-BY-ATTR-VALUE	Returns the sibling element with the given attribute value
	CXML-GET-COMMENT	Returns the comment associated to a given element or document
	CXML-MODIFY-CDATA	Changes the CDATA of a given element
	CXML-MODIFY-ATTRIBUTE-VALUE	Changes the value of a given attribute
	CXML-ADD-CHILD	Adds a new child item to the given element
	CXML-ADD-SIBLING	Adds a new sibling item to the given element
	CML-ADD-ATTRIBUTE	Adds an attribute to a given element
	CXML-ADD-COMMENT	Adds a comment to a given element or document
	CXML-APPEND-COMMENT	Appends a new comment to a given element or document
	CXML-DELETE-ATTRIBUTE	Deletes an attribute from an element
	CXML-DELETE-ELEMENT	Deletes an element
	CXML-DELETE-COMMENT	Deletes comments from an element
	CXML-WRITE-FILE	Writes a XML document to file
	CXML-WRITE-STRING	Writes a String
	CXML-GET-PROC-INSTR-COUNT	Retrieves the number of processing instructions
	CXML-GET-PROC-INSTR	Retrieves processing instructions
	CXML-SET-PROC-INSTR	Sets processing instructions
	CXML-GET-VERSION	Returns the version of the XML document
	CXML-SET-VERSION	Changes the version of the XML document
	CXML-GET-ENCODING	Returns the encoding of the XML document
	CXML-SET-ENCODING	Changes the encoding of the XML document
	CXML-GET-STANDALONE	Returns the value of the standalone pseudo-attribute
	CXML-SET-STANDALONE	Changes the value of the standalone pseudo-attribute

Return code:

The definition and meaning of the returnCode depend on the opcode.

Examples:

Example - Read the content of file.xml and show it on the console.

working-storage section.        copy "iscobol.def".                77  xml-handle                          handle.        77  elem-handle                         handle.        77  xml-item-name                       pic x(32).        77  xml-item-value                      pic x(32).        77  attr-count                          pic 99.        77  i                                   pic 99.        77  attr-name                           pic x(32).        77  attr-value                          pic x(32).                procedure division.        read-xml.            call "c$xml" using cxml-parse-file                               "file.xml"                        giving xml-handle.                                    call "c$xml" using cxml-get-first-child                               xml-handle                        giving elem-handle.                                                       perform until 1 = 2              call "c$xml" using cxml-get-data                                 elem-handle                                 xml-item-name                                 xml-item-value              display "elem. name: " xml-item-name              display "elem. value: " xml-item-value                                               call "c$xml" using cxml-get-attribute-count                                 elem-handle                          giving attr-count                     display "attr. count: " attr-count              if attr-count > 0                 perform varying i from 1 by 1 until i > attr-count                   call "c$xml" using cxml-get-attribute                                      elem-handle                                      i                                      attr-name                                      attr-value                   display "attr. name: " attr-name                   display "attr. value: " attr-value                 end-perform              end-if              call "c$xml" using cxml-get-next-sibling                                  elem-handle                          giving elem-handle                if elem-handle = 0                 exit perform              end-if                                end-perform.            display ""

call "c$xml" using cxml-release-parser                               xml-handle.            accept omitted.            goback.