diff options
Diffstat (limited to 'os400/README400')
| -rw-r--r-- | os400/README400 | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/os400/README400 b/os400/README400 new file mode 100644 index 0000000..6c16de9 --- /dev/null +++ b/os400/README400 @@ -0,0 +1,214 @@ + +Implementation notes: + + This is a true OS/400 implementation, not a PASE implementation (for PASE, +use an AIX implementation). + + The biggest problem with OS/400 is EBCDIC. The current libxml2 implementation +uses UTF-8 internally. To ease encoding conversion between the calling +applications and libxml2, supplementary "convert and latch" functions are +provided (See below). To bind the EBCDIC OS/400 system calls and libxml2, +an ASCII run-time environment (QADRT) has been used and wrapper functions have +been designed. + +Other problems are: +- Source code line length: to be stored in DB2 members, source files may not + have lines longer than 100 characters. Some header and documentation files + have been modified accordingly. +- va_list dereferencing: the OS/400 implementation of va_list type is an array + but the compiler forbids explicit array dereferencing. Source files have + been updated accordingly. +- Depending on the compilation/execution environment, it is possible that + stdin/stdout/stderr are not associated with a file descriptor; as a side + effect, open() may return a file descriptor value 0, 1 or 2 that is NOT + a C standard file. Thus using such a number may be inaccurate. +- iconv_open() arguments: OS/400 uses non-standard encoding names and does not + support standard names. For this reason, a name wrapper has been designed. +- dlopen() (support for xmodule): the function and its corollaries are not + provided by the OS/400 library. However a local implementation is provided. + + +Compiling on OS/400: + +_ As a prerequisite, QADRT development environment must be installed. +_ Install the libxml2 source directory in IFS. +_ Enter shell (QSH) +_ Change current directory to the libxml2 installation directory +_ Change current directory to ./os400 +_ Edit file iniscript.sh. You may want to change tunable configuration + parameters, like debug info generation, optimisation level, listing option, + target library, zlib availability, etc. +_ Copy any file in the current directory to makelog (i.e.: + cp initscript.sh makelog): this is intended to create the makelog file with + an ASCII CCSID! +_ Enter the command "sh make.sh >makelog 2>&1' +_ Examine the makelog file to check for compilation errors. + + Leaving file initscript.sh unchanged, this will produce the following +OS/400 objects: +_ Library LIBXML2. All other objects will be stored in this library. +_ Modules for all libxml2 units, with full debug info and no code optimization. +_ Binding directory LIBXML2_A, to be used at calling program link time for + statically binding the modules (specify BNDSRVPGM(QADRTTS QGLDCLNT QGLDBRDR) + when creating a program using LIBXML2_A). +_ Service program LIBXML2. To be used at calling program run-time + when this program has dynamically bound libxml2 at link time. +_ Binding directory LIBXML2. To be used to dynamically bind libxml2 when + linking a calling program. +_ Source file LIBXML. It contains all the header members needed to compile a + C/C++ module using libxml2. +_ Standard and additional C/C++ libxml2 header members (possibly renamed) in + file LIBXML. +_ IFS directory /libxml2 with subdirectory include/libxml containing all + C/C++ header files for IFS-based compilation. +_ Source file LIBXMLRPG. It contains all the include members needed to compile a + ILE/RPG module/program using libxml2 (ILE/RPG binding). +_ ILE/RPG binding include members (possibly renamed) in file LIBXMLRPG. +_ IFS subdirectory /libxml2/include/libxmlrpg containing all ILE/RPG include + files for IFS-based compilation. + + +Renamed header files in DB2 members: + DB2 member names are limited to 10 characters, thus the following C/C++ +header members are renamed as: + parserInternals.h --> PARSERINTE + schemasInternals.h --> SCHEMASINT + xmlautomata.h --> XMLAUTOMAT + xmlschemastype.h --> SCHMTYPES + xpathInternals.h --> XPATHINTER +IFS header files are NOT renamed. +ILE/RPG headers are processed likewise. + + +Special programming consideration: + +QADRT being used, the following points must be considered: +_ If static binding is used, service program QADRTTS must be linked too. +_ The EBCDIC CCSID used by QADRT is 37 by default, NOT THE JOB'S CCSID. If + another EBCDIC CCSID is required, it must be set via a locale through a call + to setlocale_a (QADRT's setlocale() ASCII wrapper) with category LC_ALL or + LC_CTYPE, or by setting environment variable QADRT_ENV_LOCALE to the locale + object path before executing the program. +_ Always use *IFSIO or *IFS64IO to compile calling programs. + + + +Supplementary (non libxml2 standard) support procedures for OS/400. + + As cited above, there are some procedures to ease encoding conversion of +libxml2 function arguments and results: the mechanism is based on +dictionaries. The functions convert a string, latch the result in a dictionary +to ensure its persistence and return its address. It is the caller's +responsibility to clean the dictionary when it becomes too big or disappears. + +The procedures are: + +#include <libxml/transcode.h> + +const char * xmlTranscodeResult(const xmlChar * s, + const char * encoding, + xmlDictPtr * dict, + void (*freeproc)(const void *)); + +const xmlChar * xmlTranscodeString(const char * s, + const char * encoding, + xmlDictPtr * dict); + +const xmlChar * xmlTranscodeWString(const char * s, + const char * encoding, + xmlDictPtr * dict); + +const xmlChar * xmlTranscodeWString(const char * s, + const char * encoding, + xmlDictPtr * dict); + +where: +s is the string to translate. +encoding is the alternate character encoding. If null, the current job's + encoding (CCSID) is used. +dict is the address of the latching directory. If NULL, the procedure + functions as a simple non-latching encoding converter and + its result value should be freed by the caller. +freeproc is a procedure to release the original string, or NULL. + +xmlTranscodeResult() converts from UTF-8 to the given alternate encoding. +xmlTranscodeString() converts from the given 8-bit encoding to UTF-8 (note that + UTF-8 itself is considered as a 8-bit encoding). +xmlTranscodeWString() converts from the given 16-bit encoding to UTF-8. +xmlTranscodeHString() converts from the given 32-bit encoding to UTF-8. + + +To shorten statements using these functions, shorthands are defined: + +xmlTR for xmlTranscodeResult +xmlTS for xmlTranscodeString +xmlTW for xmlTranscodeWString +xmlTH for xmlTranscodeHstring + +These shorthands may be disabled by defining XML_NO_SHORT_NAMES before +libxml/transcode.h inclusion. + +A directory pointer must be preset to NULL before the first call using it to +one of the above procedure. + +To release a latching directory, use function + +void xmlZapDict(xmlDictPtr * dict); + + +Example: + +#include <libxml/transcode.h> +#include <libxml/tree.h> + +xmlDocPtr mySimpleXMLDoc(char * element, char * text) +{ + xmlDocPtr doc; + xmlNodePtr node; + xmlDictPtr dict = NULL; + + /* element and text are encoded in the current job's encoding. */ + + doc = xmlNewDoc(); + xmlNewTextChild((xmlNodePtr) doc, NULL, xmlTS(element, NULL, + &dict), xmlTS(text, NULL, &dict)); + xmlZapDict(&dict); + return doc; +} + + +Additionally, a formatter into latched/dynamic storage is provided: + +const char * xmlVasprintf(xmlDictPtr * dict, + const char * encoding, + const xmlChar * fmt, + va_list args); + + + +ILE/RPG binding: + + All standard types and procedures are provided. Since ILE/RPG does not +support macros, they have not been ported, with the exceptions of the more +useful ones and the global/threaded variables access macros. These variables +can be read with function get_xxx(void), where xxxx is the name of the +variable; they may be set by calling function set_xxxx(value), where value is +of the same type as the variable. + + The C va_list is not implemented as such in ILE/RPG. Functions implementing +va_list and associated methods are provided: + + /include "libxmlrpg/xmlstdarg" + + d xmlVaStart pr + d list like(xmlVaList) + d lastargaddr * value + d lastargsize 10u 0 value + + d xmlVaArg pr + d list like(xmlVaList) + d dest * value + d argsize 10i 0 value + + d xmlVaEnd pr + d list like(xmlVaList) |