summaryrefslogtreecommitdiff
path: root/os400/README400
diff options
context:
space:
mode:
Diffstat (limited to 'os400/README400')
-rw-r--r--os400/README400214
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)