IFSXml provide mid-level API for produce XML structure with low data control. Thus, id you add many time the same attribute on a element. IFSXml not intended to be an XML validation tools, it’s just a few lines of code to streamline its production.
You are encouraged to adapt it to your needs.
Usage
- Get a Handle
- Set output method
- Define a root name
- Add elements, attributes, comments…
- Close the flow
- Release the handle
Context management
Handle
Each XML resource is identified by a Handle. Technically it’s a pointer but it preferable to declare it with the template m_ifsxml_handle. This Handle is a context, it is transmitted to each functions
d hXml...
d s like(m_ifsxml_handle)
Get and Free a Handle
d ifsxml_new...
d pr like(m_ifsxml_handle)
d ifsxml_free...
d pr n
d hXml...
d value like(m_ifsxml_handle)
Each Handles created by ifsxml_new() must be released with ifsxml_free(). Don’t get a Handle with variable that already contains one because you will cannot released the space of this first, except ending activation group.
Error management
Retrieve the error status or the last error
d ifsxml_isError...
d pr n
d hXml...
d value like(m_ifsxml_handle)
d ifsxml_getError...
d pr like(m_txtErreur)
d hXml...
d value like(m_ifsxml_handle)
d ifsxml_errorJobLog...
d pr
d hXml...
d value like(m_ifsxml_handle)
d mode...
d n const options(*nopass)
ifsxml_isError() return *on if the last operation fail. ifsxml_getError() return the text of them. ifsxml_errorJobLog() send the last error to the joblog. Specify *ON for always send errors to the joblog.
Setting up a output
You must specify your writing method before use any editing functions.
Outputting to a file on IFS
d ifsxml_createFile...
d pr n
d hXml...
d value like(m_ifsxml_handle)
d path...
d 16384a const varying
d codePage...
d 10u 0 const options(*nopass)
Use ifsxml_createFile() to specify a output file and code page. By default, the file is created on UTF-8 (1208). The function don’t overwrite a existing file.
Outputting by callback
d ifsxml_setWriter...
d pr n
d hXml...
d value like(m_ifsxml_handle)
d proc...
d * value procptr
With ifsxml_setWriter() you can receive the flow formatted by the service. In a nutshell, you create a pipe from IFSXML to your app. Your function must be an implementation of the prototype bellow.
d custom_writer...
d pr
d hXml...
d value like(m_ifsxml_handle)
d buffer...
d * value
d len...
d 10u 0 const
Four samples programs demonstrate how to use and why.
Document management
Adding an XML Header (optional)
d ifsxml_setXmlHeader...
d pr n
d hXml...
d value like(m_ifsxml_handle)
d version...
d 32a const varying
d encoding...
d 32a const varying
Use ifsxml_setXmlHeader() to create specific XML Header, otherwise IFSXML add one with 1.0 and encoding= »UTF-8″. The function don’t evaluate the coherence of your input. Must be called before setting the root name.
Setting the root name (Required)
d ifsxml_setRootName...
d pr n
d hXml...
d value like(m_ifsxml_handle)
d name...
d const like(m_ifsxml_nodeName)
The root name must be defined before using any data functions. You can add attributes with ifsxml_addAttribute() (eg : Namespaces)
Closing the document
d ifsxml_close...
d pr n
d hXml...
d value like(m_ifsxml_handle)
Adding the the end of document and close the file. Close all elements previously opened with ifsxml_openElement() and, if necessary, close the file.
Getting the len
d ifsxml_getLen...
d pr 10u 0
d hXml...
d value like(m_ifsxml_handle)
Return the len of the flow produced.
Editing
Adding element
d ifsxml_addElement...
d pr
d hXml...
d value like(m_ifsxml_handle)
d name...
d const like(m_ifsxml_nodeName)
d value...
d const options(*nopass)
d like(m_ifsxml_value)
With ifsxml_addElement() you create a simple element like <name>value</name>. If value is not specify, ouput <name/>
Openning and closing elements
d ifsxml_openElement...
d pr
d hXml...
d value like(m_ifsxml_handle)
d name...
d const like(m_ifsxml_nodeName)
d ifsxml_closeElement...
d pr
d hXml...
d value like(m_ifsxml_handle)
d name...
d const options(*nopass)
d like(m_ifsxml_nodeName)
ifsxml_closeElement() close the last element opened with ifsxml_openElement(). If you specify an name, close all the element previously opened and this last. For close all elements and back to the root, specify *blank or » in the name.
Adding attributes
d ifsxml_addAttribute...
d pr
d hXml...
d value like(m_ifsxml_handle)
d name...
d value like(m_ifsxml_nodeName)
d value...
d value like(m_ifsxml_value)
d
Add attribute to the lasted element. Does not provide control on the existing.
Can be used after these functions :
- ifsxml_addXmlHeader()
- ifsxml_openElement()
- ifsxml_addElement()
- ifsxml_addPI()
Adding processing instructions
d ifsxml_addPI...
d pr
d hXml...
d value like(m_ifsxml_handle)
d name...
d const like(m_ifsxml_nodeName)
Add a processing instruction like <?name?>.
Adding comment
d ifsxml_addComment...
d pr
d hXml...
d value like(m_ifsxml_handle)
d comment...
d 16384a value varying
Add comment like <!– comment –>.
Querying
Actual positionning
d ifsxml_isRoot...
d pr n
d hXml...
d value like(m_ifsxml_handle)
d ifsxml_getDepth...
d pr 10i 0
d hXml...
d value like(m_ifsxml_handle)
General
d ifsxml_setPretty...
d pr n
d hXml...
d value like(m_ifsxml_handle)
d format...
d 10i 0 const
d crlf...
d 2a const varying options(*nopass)
Setting up the output formatting. Must be used before ifsxml_setRootName().
Supported values are :
- IFSXML_TABINDENT_NEWLINE : Indent with TAB and CRLF after element (default)
- IFSXML_SPCINDENT_NEWLINE : Indent with CRLF and CRLF after element
- IFSXML_NOINDENT_NEWLINE : No indent and CRLF after element
- IFSXML_NONE : No formatting (flow).
You can specify you CRLF character or use one of the three proposed constants.
- IFSXML_CHAR_CRLF (default)
- IFSXML_CHAR_CR
- IFSXML_CHAR_LF
Comment
d ifsxml_commentStyle...
d pr 10i 0
d hXml...
d value like(m_ifsxml_handle)
d style...
d 10i 0 const options(*nopass)
Get (when style not specified) or set comment output process.
Supported values :
- IFSXML_INDENT: Write comment at the same level of element. (default)
- IFSXML_NOINDENT: Comments are not indented
- IFSXML_NO_OUTPUT : Comments are not write.
Tests and diagnostics
Adding internal comment
d ifsxml_trace...
d pr
d hXml...
d value like(m_ifsxml_handle)
d comment...
d 16384a value varying
d ifsxml_setTraceFormat...
d pr
d hXml...
d value like(m_ifsxml_handle)
d format...
d 10i 0 const
Add a comment, like ifsxml_addComment(), prefixed with a stamp, for internal usage (debug, test). There no outputted by default.
Formats supported :
- IFSXML_INDENT: Write at the same level of element.
- IFSXML_NOINDENT: Not indented
- IFSXML_NO_OUTPUT : No write (default)
Stamp
d ifsxml_stampStart...
d pr
d hXml...
d value like(m_ifsxml_handle)
d ifsxml_stampStop...
d pr n
d hXml...
d value like(m_ifsxml_handle)
d ifsxml_getStamp...
d pr z
d hXml...
d value like(m_ifsxml_handle)
d event...
d 10i 0 const
Use ifsxml_stampStart() and ifsxml_stampStop() for define the period you want test.
Get it with ifsxmlGetStamp()
- IFSXML_STAMP_ROOT : ifsxml_setRootName()
- IFSXML_STAMP_CLOSE : ifsxml_close()
- IFSXML_STAMP_USERSTART : ifsxml_stampStart()
- IFSXML_STAMP_USEREND : ifsxml_stampStop()
Memory usage
d ifsxml_getMemoryUsage...
d pr 10u 0
d hXml...
d value like(m_ifsxml_handle)
Return in byte the memory space actually allocated for the context