$Id: README.OS400,v 1.13 2009-12-21 12:26:48 patrickm Exp $ 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_KEYPASSWD 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_KEYPASSWD CURLOPT_KRBLEVEL CURLOPT_NETRC_FILE CURLOPT_COPYPOSTFIELDS 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_SSLKEYTYPE CURLOPT_SSL_CIPHER_LIST CURLOPT_URL CURLOPT_USERAGENT CURLOPT_USERPWD CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 CURLOPT_CRLFILE CURLOPT_ISSUERCERT CURLOPT_USERNAME CURLOPT_PASSWORD CURLOPT_PROXYUSERNAME CURLOPT_PROXYPASSWORD CURLOPT_NOPROXY CURLOPT_SOCKS5_GSSAPI_SERVICE CURLOPT_MAIL_FROM CURLOPT_MAIL_RCPT 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. CURLOPT_POSTFIELDS stores the address of static binary data (of type void *) and thus is not converted. If CURLOPT_COPYPOSTFIELDS is issued after CURLOPT_POSTFIELDSIZE != -1, the data size is adjusted according to the CCSID conversion result length. _ 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 QGLDCLNT QGLDBRDR) when creating a program using CURL_A). _ Service program CURL., where is extracted from the lib/Makefile.am VERSION variable. 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.