Porting library to OS/400

1 files changed, 245 insertions, 0 deletions

diff --git a/packages/OS400/README.OS400 b/packages/OS400/README.OS400
new file mode 100644
index 000000000..8b46b2c99
--- /dev/null
+++ b/packages/OS400/README.OS400
@@ -0,0 +1,245 @@
+$Id$
+
+Implementation notes:
+
+  This is a true OS/400 implementation, not a PASE implementation (for PASE,
+use AIX implementation).
+
+  The biggest problem with OS/400 is EBCDIC. Libcurl implements an internal
+conversion mechanism, but it has been designed for computers that have a
+single native character set. OS/400 default native character set varies
+depending on the country for which it has been localized. And more, a job
+may dynamically alter its "native" character set.
+  Several characters that do not have fixed code in EBCDIC variants are
+used in libcurl strings. As a consequence, using the existing conversion
+mechanism would have lead in a localized binary library - not portable across
+countries.
+  For this reason, and because libcurl was originally designed for ASCII based
+operating systems, the current OS/400 implementation uses ASCII as internal
+character set. This has been accomplished using the QADRT library and
+include files, a C and system procedures ASCII wrapper library. See IBM QADRT
+description for more information.
+  This then results in libcurl being an ASCII library: any function string
+argument is taken/returned in ASCII and a C/C++ calling program built around
+QADRT may use libcurl functions as on any other platform.
+  QADRT does not define ASCII wrappers for all C/system procedures: the
+OS/400 configuration header file and an additional module (os400sys.c) define
+some more of them, that are used by libcurl and that QADRT left out.
+  To support all the different variants of EBCDIC, non-standard wrapper
+procedures have been added to libcurl on OS/400: they provide an additional
+CCSID (numeric Coded Character Set ID specific to OS/400) parameter for each
+string argument. String values passed to callback procedures are NOT converted,
+so text gathered this way is (probably !) ASCII.
+
+  Another OS/400 problem comes from the fact that the last fixed argument of a
+vararg procedure may not be of type char, unsigned char, short or unsigned
+short. Enums that are internally implemented by the C compiler as one of these
+types are also forbidden. Libcurl uses enums as vararg procedure tagfields...
+Happily, there is a pragma forcing enums to type "int". The original libcurl
+header files are thus altered during build process to use this pragma, in
+order to force libcurl enums of being type int (the pragma disposition in use
+before inclusion is restored before resuming the including unit compilation).
+
+  Three SSL implementations were present in libcurl. Nevertheless, none of them
+is available on OS/400. To support SSL on OS/400, a fourth implementation has
+been added (qssl.[ch]). There is no way to have different certificate stores
+for CAs and for personal/application certificates/key. More, the SSL context
+may be defined as an application identifier in the main certificate store,
+or as a keyring file. As a consequence, the meaning of some fields have been
+slightly altered:
+_ The "certificate identifier" is taken from CURLOPT_SSLCERT if defined, else
+from CURLOPT_CAINFO.
+_ The certificate identifier is then used as an application identifier in the
+main certificate store. If successful, this context is used.
+_ If the previous step failed, the certificate identifier is used as the file
+name of a keyring. CURLOPT_SSLKEYPASSWD is used here as the keyring password.
+_ The default ca-bundle (CURLOPT_CAINFO) is set to the main certificate store's
+keyring file name: this allows to use the system global CAs by default. (In that
+case, the keyring password is safely recovered from the system... IBM dixit!)
+
+  Non-standard EBCDIC wrapper prototypes are defined in an additional header
+file: ccsidcurl.h. These should be self-explanatory to an OS/400-aware
+designer. CCSID 0 can be used to select the current job's CCSID.
+  Wrapper procedures with variable arguments are described below:
+
+_ curl_easy_setopt_ccsid()
+  Variable arguments are a string pointer and a CCSID (unsigned int) for
+options:
+        CURLOPT_CAINFO
+        CURLOPT_CAPATH
+        CURLOPT_COOKIE
+        CURLOPT_COOKIEFILE
+        CURLOPT_COOKIEJAR
+        CURLOPT_COOKIELIST
+        CURLOPT_CUSTOMREQUEST
+        CURLOPT_EGDSOCKET
+        CURLOPT_ENCODING
+        CURLOPT_FTPPORT
+        CURLOPT_FTP_ACCOUNT
+        CURLOPT_FTP_ALTERNATIVE_TO_USER
+        CURLOPT_INTERFACE
+        CURLOPT_KRBLEVEL
+        CURLOPT_NETRC_FILE
+        CURLOPT_POSTFIELDS
+        CURLOPT_PROXY
+        CURLOPT_PROXYUSERPWD
+        CURLOPT_RANDOM_FILE
+        CURLOPT_RANGE
+        CURLOPT_REFERER
+        CURLOPT_SSH_PRIVATE_KEYFILE
+        CURLOPT_SSH_PUBLIC_KEYFILE
+        CURLOPT_SSLCERT
+        CURLOPT_SSLCERTTYPE
+        CURLOPT_SSLENGINE
+        CURLOPT_SSLKEY
+        CURLOPT_SSLKEYPASSWD
+        CURLOPT_SSLKEYTYPE
+        CURLOPT_SSL_CIPHER_LIST
+        CURLOPT_URL
+        CURLOPT_USERAGENT
+        CURLOPT_USERPWD
+  Else it is the same as for curl_easy_setopt().
+  Note that CURLOPT_ERRORBUFFER is not in the list above, since it gives the
+address of an (empty) character buffer, not the address of a string.
+
+_ curl_formadd_ccsid()
+  In the variable argument list, string pointers should be followed by a (long)
+CCSID for the following options:
+        CURLFORM_FILENAME
+        CURLFORM_CONTENTTYPE
+        CURLFORM_BUFFER
+        CURLFORM_FILE
+        CURLFORM_FILECONTENT
+        CURLFORM_COPYCONTENTS
+        CURLFORM_COPYNAME
+        CURLFORM_PTRNAME
+  If taken from an argument array, an additional array entry must follow each
+entry containing one of the above option. This additional entry holds the CCSID
+in its value field, and the option field is meaningless.
+  It is not possible to have a string pointer and its CCSID across a function
+parameter/array boundary.
+  Please note that CURLFORM_PTRCONTENTS and CURLFORM_BUFFERPTR are considered
+unconvertible strings and thus are NOT followed by a CCSID.
+
+_ curl_easy_getinfo_ccsid
+  The following options are followed by a 'char * *' and a CCSID. Unlike
+curl_easy_getinfo(), the value returned in the pointer should be freed after
+use:
+        CURLINFO_EFFECTIVE_URL
+        CURLINFO_CONTENT_TYPE
+        CURLINFO_FTP_ENTRY_PATH
+  Other options are processed like in curl_easy_getinfo().
+
+  Standard compilation environment does support neither autotools nor make;
+in fact, very few common utilities are available. As a consequence, the
+config-os400.h has been coded manually and the compilation scripts are
+a set of shell scripts stored in subdirectory packages/OS400.
+
+  The "curl" command and the test environment are currently not supported on
+OS/400.
+
+
+Protocols currently implemented on OS/400:
+_ HTTP
+_ HTTPS
+_ FTP
+_ FTPS
+_ FTP with secure transmission.
+_ LDAP
+_ DICT
+_ TELNET
+
+
+
+Compiling on OS/400:
+
+  These instructions targets people who knows about OS/400, compiling, IFS and
+archive extraction. Do not ask questions about these subjects if you're not
+familiar with.
+
+_ As a prerequisite, QADRT development environment must be installed.
+_ Install the curl source directory in IFS.
+_ Enter shell (QSH)
+_ Change current directory to the curl installation directory
+_ Change current directory to ./packages/OS400
+_ Edit file iniscript.sh. You may want to change tunable configuration
+  parameters, like debug info generation, optimisation level, listing option,
+  target library, 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 makefile.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 CURL. All other objects will be stored in this library.
+_ Modules for all libcurl units.
+_ Binding directory CURL_A, to be used at calling program link time for
+  statically binding the modules (specify BNDSRVPGM(QADRTTS) when creating a
+  program using CURL_A).
+_ Service program CURL, to be used at calling program run-time when this program
+  has dynamically bound curl at link time.
+_ Binding directory CURL. To be used to dynamically bind libcurl when linking a
+  calling program.
+_ Source file H. It contains all the include members needed to compile a C/C++
+  module using libcurl, and an ILE/RPG /copy member for support in this
+  language.
+_ Standard C/C++ libcurl include members in file H.
+_ CCSIDCURL member in file H. This defines the non-standard EBCDIC wrappers for
+  C and C++.
+_ CURL.INC member in file H. This defines everything needed by an ILE/RPG
+  program using libcurl.
+_ LIBxxx modules and programs. Although the test environment is not supported
+  on OS/400, the libcurl test programs are compiled for manual tests.
+
+
+
+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.
+_ Do not use original source include files unless you know what you are doing.
+  Use the installed members instead (in /QSYS.LIB/CURL.LIB/H.FILE).
+
+
+
+ILE/RPG support:
+
+  Since 95% of the OS/400 programmers use ILE/RPG exclusively, a definition
+  /COPY member is provided for this language. To include all libcurl
+  definitions in an ILE/RPG module, line
+
+     h bnddir('CURL/CURL')
+
+must figure in the program header, and line
+
+     d/copy curl/h,curl.inc
+
+in the global data section of the module's source code.
+
+  No vararg procedure support exists in ILE/RPG: for this reason, the following
+considerations apply:
+_ Procedures curl_easy_setopt_long(), curl_easy_setopt_object(),
+  curl_easy_setopt_function() and curl_easy_setopt_offset() are all alias
+  prototypes to curl_easy_setopt(), but with different parameter lists.
+_ Procedures curl_easy_getinfo_string(), curl_easy_getinfo_long(),
+  curl_easy_getinfo_double() and curl_easy_getinfo_slist() are all alias
+  prototypes to curl_easy_getinfo(), but with different parameter lists.
+_ Procedures curl_multi_setopt_long(), curl_multi_setopt_object(),
+  curl_multi_setopt_function() and curl_multi_setopt_offset() are all alias
+  prototypes to curl_multi_setopt(), but with different parameter lists.
+_ The prototype of procedure curl_formadd() allows specifying a pointer option
+  and the CURLFORM_END option. This makes possible to use an option array
+  without any additional definition. If some specific incompatible argument
+  list is used in the ILE/RPG program, the latter must define a specialised
+  alias. The same applies to curl_formadd_ccsid() too.
+
+  Since RPG cannot cast a long to a pointer, procedure curl_form_long_value()
+is provided for that purpose: this allows storing a long value in the curl_forms
+array.