XML for RPG and Procedural Languages Documentation |
|
Programming Guide
Initializing the XML Parser environment
QxmlTerm procedure or the equivalent QxmlTerm_rtnHandleCount procedure. The latter returns the number of handles still allocated at termination time. An excessive number of handles allocated may be an indication that your application is not doing appropriate object handle cleanup.
Any objects that were used in the process of interfacing with the parser must also be deleted before the program ends. To delete an object you simply pass the object to the delete routine of the corresponding object type. This call will be of the form: Qxml<Object Type>_delete . For instance, if you had a DOMParser object you would call the API procedure QxmlDOMParser_delete .
Due to the nature of the XML4PR interfacing with the underlying parser constructs of the XML4C parser, most objects used by the XML4PR parser are allocated from heap. Within an XML parser initialized session, between the QxmlInit and the QxmlTerm routines, the parser will recycle handles to objects that are returned to the XML4PR interface through the above mentioned delete requests. It is especially important to return handles that are no longer used to the parser for this purpose. This will help to keep down the number of objects allocated on the heap and provide for a longer running application environment. In addition, the XML4PR does use teraspace for heap allocations to allow for longer running applications. Handling API Exceptions
encoding attribute in the XML header. If encoding is not specified the parser assumes the document is in an ASCII encoding (like 819). If a file's encoding cannot be determined as the default, you must specify the encoding with the encoding attribute. For instance, if the file is in the US-English EBCDIC codepage the XML header would be:
<?xml version="1.0" encoding="IBM037"?>
If the parser returns an error that it finds an unrecognized character on or near line #1 of the file then the encoding may not be set to the correct value. Other possible warning messages may be: See the encoding string table for a list of the recognized encoding strings and corresponding code pages. Note that this list may not be complete as added function can results in additions.
XMLCh arrays (a unicode string) or DOMString s. As C, RPG and COBOL programs on the iSeries typically work with characters and strings encoded in EBCDIC and of the form char or char*, additional parameters are provided on the XML4PR APIs to allow your application to specify the type of encoding for char type values for both input and output.
Using QxmlTranscode to convert strings The XML Parser Interface Wrappers provide a procedure named QxmlTranscode that can be used to convert strings to and from various encodings. The instringind and outstringind parameters take the coded character set ID numeric of the source and target code pages respectively. There are two special cases:
Two more constants have been defined. Qxml_CCSID37 corresponds to the IBM037 code page (an EBCDIC code page) and is set to 37. Qxml_UNICODE is used when the code page for the string is UNICODE. Even though these two code pages are explicitly defined as constants, any code page supported by ICONV can be used with QxmlTranscode by using the corresponding code page numeric value.
To perform the code page transformation using QxmlTranscode the input string must be null terminated and the procedure must know how much space is allocated for the output string (the ouputstring parameter). It is important to note that if you are transforming from a single-byte character set to a double-byte character set you must provide 2 times the space required for the input string. The bytesprovided parameter specifies how many bytes are allocated for the output string. The bytesavailable parameter is set inside the procedure to how many bytes are used in the transformed string.
Although DOMString is used quite frequently throughout the C++ APIs, the XML4PR interface offers flexibility on what is acceptable for the type of string being passed to many of the API procedures. Whether you pass in a DOMString or a character string it is important to set the string indicator (typically documented as stringind ) parameter to reflect whether the value is a DOMString or a character string. If a DOMString is passed as a parameter then the string indicator must be set to Qxml_INDOMSTR or -1. If a character string is passed then the string indicator is set to the coded character set ID numeric of the string. Many of the samples are using Qxml_CCSID37 , but you can provide the correct string indicator for your string variable. For example of the string content is in the French code page, you would provide value stringind value as 297 for EBCDIC France.
Also note that a DOMString is not simply a character array and therefore must be translated into a character string by using the QxmlTranscode API procedure before the data in the DOMString can be used in non-XML API calls (such as C standard library calls). Another way of returning the data in char*/string form is to use QxmlDOMString_transcode , but this will return the string data in the default code page of the XML4C parser, which on iSeries is EBCDIC 37.
XMLCh Characters and Strings
QxmlTranscode .
RPG Note: RPG's Internal Data Type "C" is a Unicode character and data initialized as this type can be passed to the XML4PR APIs in place of XMLCh characters and strings where appropriate.
What the XMLFormatter does The XMLFormatter provides a way to output XML data in the desired encoding and provides an interface to automatically generate the appropriate escape characters necessary to create a well-formed XML document. Providing the necessary escape characters for XML document content (within elements and attributes) that contain such markup characters as <, >, ", &, and ' is key when streaming out XML documents. A number of flags are provided to control whether various optional formatting operations are performed. The basic operation is Unicode encoded data (in Unicode strings, Unicode characters or DOMStrings) is passed into the formatter and it is transcoded to the encoding specified and directed to the output. By setting various flags on the XMLFormatter the data that is printed out can be affected. XMLFormatter escape flags can be set with QxmlXMLFormatter_setEscapeFlags . If the Escape flags for a particular group are set then any characters written through the XMLFormatter that match a character in the group will be escaped (printed in the form &Character; ). Here are the XMLFormatter escape flag options:
The XMLFormatter can also affect how characters which are unrepresentable in the target encoding are handled. Here are the XMLFormatter unrepresentable character flags options: How to use the XMLFormatter Create a new XMLFormatter by calling QxmlXMLFormatter_new . The following parameters are expected:
The following XMLFormatter methods are used to write text to the output: To see an example of how the XMLFormatter is used look at the source code for the DOMPrint sample.
To provide a consistent interface for writing XML data to a stream file the XML4PR Interface Wrappers provide procedures for operating on stream files. Three of the procedures are used to open and close a stream file: QxmlOpenNewOutputStream and QxmlAppendOutputStream are used to return a file descriptor for an open stream file in the IFS. Both calls are passed the same parameters:
QxmlOpenNewOutputStream is called to create a file that already exists. Check the value of error to get more specific information about what caused the error by running DSPMSGD CPE#### where #### corresponds to the value stored in error . Otherwise the value returned is the file descriptor that will be used to refer to the file.
When all of the data has been written to the stream file and it is no longer needed the FileDescriptor needs to be closed. Use the QxmlCloseOutputStream procedure to do that.
Writing to an IFS stream file The preferred way to write to an open stream file is to use the FileFormatTarget and the XMLFormatter. Read the XMLFormatter Information above for information about the benefits it provides for printing XML data. To direct the output of the XMLFormatter to a stream file follow these steps:
The second way to write data to an open stream file is to use the QxmlWriteOutputStream procedure. The return value is an error return code, with 0 indicating success. The string indicator (stringind ) parameter functions the same way it does on other API calls. If the string to write is a DOMString the string indicator is Qxml_INDOMSTR or -1 and to write in the JOBCCSID the string indicator is QxmlJOBCCSID or 0. Otherwise it is the value of the code page numeric. The code page of the output stream must also be specified in the open_fd_codepage parameter. This will be the same value that was used when the file was opened with the QxmlOpenNewOutputStream command. All strings will be automatically converted to the specified output code page by the procedure call.
EBCDIC Linefeed Mappings can cause Invalid Characters
Also note that if you are using QxmlWriteOutputStream in a C program and you wish to use \n as a carriage-return / line-feed character then you must create the C module with SYSIFCOPT(*IFSIO) set (that is from the System interface options when prompting on crtcmod ). If this is not set the '\n' character translates to EBCDIC character 15(hex) and no line break will occur in the output.
|
|
![]() | XML4PR - XML4C Interface Wrapper for RPG, C and COBOL
Copyright 2000,2001,2002 International Business Machines. All Rights Reserved. |