1 2Implementation notes: 3 4 This is a true OS/400 implementation, not a PASE implementation (for PASE, 5use AIX implementation). 6 7 The biggest problem with OS/400 is EBCDIC. Libcurl implements an internal 8conversion mechanism, but it has been designed for computers that have a 9single native character set. OS/400 default native character set varies 10depending on the country for which it has been localized. And more, a job 11may dynamically alter its "native" character set. 12 Several characters that do not have fixed code in EBCDIC variants are 13used in libcurl strings. As a consequence, using the existing conversion 14mechanism would have lead in a localized binary library - not portable across 15countries. 16 For this reason, and because libcurl was originally designed for ASCII based 17operating systems, the current OS/400 implementation uses ASCII as internal 18character set. This has been accomplished using the QADRT library and 19include files, a C and system procedures ASCII wrapper library. See IBM QADRT 20description for more information. 21 This then results in libcurl being an ASCII library: any function string 22argument is taken/returned in ASCII and a C/C++ calling program built around 23QADRT may use libcurl functions as on any other platform. 24 QADRT does not define ASCII wrappers for all C/system procedures: the 25OS/400 configuration header file and an additional module (os400sys.c) define 26some more of them, that are used by libcurl and that QADRT left out. 27 To support all the different variants of EBCDIC, non-standard wrapper 28procedures have been added to libcurl on OS/400: they provide an additional 29CCSID (numeric Coded Character Set ID specific to OS/400) parameter for each 30string argument. String values passed to callback procedures are NOT converted, 31so text gathered this way is (probably !) ASCII. 32 33 Another OS/400 problem comes from the fact that the last fixed argument of a 34vararg procedure may not be of type char, unsigned char, short or unsigned 35short. Enums that are internally implemented by the C compiler as one of these 36types are also forbidden. Libcurl uses enums as vararg procedure tagfields... 37Happily, there is a pragma forcing enums to type "int". The original libcurl 38header files are thus altered during build process to use this pragma, in 39order to force libcurl enums of being type int (the pragma disposition in use 40before inclusion is restored before resuming the including unit compilation). 41 42 Three SSL implementations were present in libcurl. Nevertheless, none of them 43is available on OS/400. To support SSL on OS/400, a fourth implementation has 44been added (qssl.[ch]). There is no way to have different certificate stores 45for CAs and for personal/application certificates/key. More, the SSL context 46may be defined as an application identifier in the main certificate store, 47or as a keyring file. As a consequence, the meaning of some fields have been 48slightly altered: 49_ The "certificate identifier" is taken from CURLOPT_SSLCERT if defined, else 50from CURLOPT_CAINFO. 51_ The certificate identifier is then used as an application identifier in the 52main certificate store. If successful, this context is used. 53_ If the previous step failed, the certificate identifier is used as the file 54name of a keyring. CURLOPT_KEYPASSWD is used here as the keyring password. 55_ The default ca-bundle (CURLOPT_CAINFO) is set to the main certificate store's 56keyring file name: this allows to use the system global CAs by default. (In that 57case, the keyring password is safely recovered from the system... IBM dixit!) 58 59 Non-standard EBCDIC wrapper prototypes are defined in an additional header 60file: ccsidcurl.h. These should be self-explanatory to an OS/400-aware 61designer. CCSID 0 can be used to select the current job's CCSID. 62 Wrapper procedures with variable arguments are described below: 63 64_ curl_easy_setopt_ccsid() 65 Variable arguments are a string pointer and a CCSID (unsigned int) for 66options: 67 CURLOPT_CAINFO 68 CURLOPT_CAPATH 69 CURLOPT_COOKIE 70 CURLOPT_COOKIEFILE 71 CURLOPT_COOKIEJAR 72 CURLOPT_COOKIELIST 73 CURLOPT_CUSTOMREQUEST 74 CURLOPT_EGDSOCKET 75 CURLOPT_ENCODING 76 CURLOPT_FTPPORT 77 CURLOPT_FTP_ACCOUNT 78 CURLOPT_FTP_ALTERNATIVE_TO_USER 79 CURLOPT_INTERFACE 80 CURLOPT_KEYPASSWD 81 CURLOPT_KRBLEVEL 82 CURLOPT_NETRC_FILE 83 CURLOPT_COPYPOSTFIELDS 84 CURLOPT_PROXY 85 CURLOPT_PROXYUSERPWD 86 CURLOPT_RANDOM_FILE 87 CURLOPT_RANGE 88 CURLOPT_REFERER 89 CURLOPT_SSH_PRIVATE_KEYFILE 90 CURLOPT_SSH_PUBLIC_KEYFILE 91 CURLOPT_SSLCERT 92 CURLOPT_SSLCERTTYPE 93 CURLOPT_SSLENGINE 94 CURLOPT_SSLKEY 95 CURLOPT_SSLKEYTYPE 96 CURLOPT_SSL_CIPHER_LIST 97 CURLOPT_URL 98 CURLOPT_USERAGENT 99 CURLOPT_USERPWD 100 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 101 CURLOPT_CRLFILE 102 CURLOPT_ISSUERCERT 103 CURLOPT_USERNAME 104 CURLOPT_PASSWORD 105 CURLOPT_PROXYUSERNAME 106 CURLOPT_PROXYPASSWORD 107 CURLOPT_NOPROXY 108 CURLOPT_RTSP_SESSION_UID 109 CURLOPT_RTSP_STREAM_URI 110 CURLOPT_RTSP_TRANSPORT 111 CURLOPT_SOCKS5_GSSAPI_SERVICE 112 CURLOPT_MAIL_FROM 113 CURLOPT_TLSAUTH_USERNAME 114 CURLOPT_TLSAUTH_PASSWORD 115 CURLOPT_TLSAUTH_TYPE 116 Else it is the same as for curl_easy_setopt(). 117 Note that CURLOPT_ERRORBUFFER is not in the list above, since it gives the 118address of an (empty) character buffer, not the address of a string. 119CURLOPT_POSTFIELDS stores the address of static binary data (of type void *) and 120thus is not converted. If CURLOPT_COPYPOSTFIELDS is issued after 121CURLOPT_POSTFIELDSIZE != -1, the data size is adjusted according to the 122CCSID conversion result length. 123 124_ curl_formadd_ccsid() 125 In the variable argument list, string pointers should be followed by a (long) 126CCSID for the following options: 127 CURLFORM_FILENAME 128 CURLFORM_CONTENTTYPE 129 CURLFORM_BUFFER 130 CURLFORM_FILE 131 CURLFORM_FILECONTENT 132 CURLFORM_COPYCONTENTS 133 CURLFORM_COPYNAME 134 CURLFORM_PTRNAME 135 If taken from an argument array, an additional array entry must follow each 136entry containing one of the above option. This additional entry holds the CCSID 137in its value field, and the option field is meaningless. 138 It is not possible to have a string pointer and its CCSID across a function 139parameter/array boundary. 140 Please note that CURLFORM_PTRCONTENTS and CURLFORM_BUFFERPTR are considered 141unconvertible strings and thus are NOT followed by a CCSID. 142 143_ curl_easy_getinfo_ccsid 144 The following options are followed by a 'char * *' and a CCSID. Unlike 145curl_easy_getinfo(), the value returned in the pointer should be freed after 146use: 147 CURLINFO_EFFECTIVE_URL 148 CURLINFO_CONTENT_TYPE 149 CURLINFO_FTP_ENTRY_PATH 150 Other options are processed like in curl_easy_getinfo(). 151 152 Standard compilation environment does support neither autotools nor make; 153in fact, very few common utilities are available. As a consequence, the 154config-os400.h has been coded manually and the compilation scripts are 155a set of shell scripts stored in subdirectory packages/OS400. 156 157 The "curl" command and the test environment are currently not supported on 158OS/400. 159 160 161Protocols currently implemented on OS/400: 162_ HTTP 163_ HTTPS 164_ FTP 165_ FTPS 166_ FTP with secure transmission. 167_ LDAP 168_ DICT 169_ TELNET 170 171 172 173Compiling on OS/400: 174 175 These instructions targets people who knows about OS/400, compiling, IFS and 176archive extraction. Do not ask questions about these subjects if you're not 177familiar with. 178 179_ As a prerequisite, QADRT development environment must be installed. 180_ Install the curl source directory in IFS. 181_ Enter shell (QSH) 182_ Change current directory to the curl installation directory 183_ Change current directory to ./packages/OS400 184_ Edit file iniscript.sh. You may want to change tunable configuration 185 parameters, like debug info generation, optimisation level, listing option, 186 target library, etc. 187_ Copy any file in the current directory to makelog (i.e.: 188 cp initscript.sh makelog): this is intended to create the makelog file with 189 an ASCII CCSID! 190_ Enter the command "sh makefile.sh > makelog 2>&1' 191_ Examine the makelog file to check for compilation errors. 192 193 Leaving file initscript.sh unchanged, this will produce the following OS/400 194objects: 195_ Library CURL. All other objects will be stored in this library. 196_ Modules for all libcurl units. 197_ Binding directory CURL_A, to be used at calling program link time for 198 statically binding the modules (specify BNDSRVPGM(QADRTTS QGLDCLNT QGLDBRDR) 199 when creating a program using CURL_A). 200_ Service program CURL.<soname>, where <soname> is extracted from the 201 lib/Makefile.am VERSION variable. To be used at calling program run-time 202 when this program has dynamically bound curl at link time. 203_ Binding directory CURL. To be used to dynamically bind libcurl when linking a 204 calling program. 205_ Source file H. It contains all the include members needed to compile a C/C++ 206 module using libcurl, and an ILE/RPG /copy member for support in this 207 language. 208_ Standard C/C++ libcurl include members in file H. 209_ CCSIDCURL member in file H. This defines the non-standard EBCDIC wrappers for 210 C and C++. 211_ CURL.INC member in file H. This defines everything needed by an ILE/RPG 212 program using libcurl. 213_ LIBxxx modules and programs. Although the test environment is not supported 214 on OS/400, the libcurl test programs are compiled for manual tests. 215 216 217 218Special programming consideration: 219 220QADRT being used, the following points must be considered: 221_ If static binding is used, service program QADRTTS must be linked too. 222_ The EBCDIC CCSID used by QADRT is 37 by default, NOT THE JOB'S CCSID. If 223 another EBCDIC CCSID is required, it must be set via a locale through a call 224 to setlocale_a (QADRT's setlocale() ASCII wrapper) with category LC_ALL or 225 LC_CTYPE, or by setting environment variable QADRT_ENV_LOCALE to the locale 226 object path before executing the program. 227_ Do not use original source include files unless you know what you are doing. 228 Use the installed members instead (in /QSYS.LIB/CURL.LIB/H.FILE). 229 230 231 232ILE/RPG support: 233 234 Since 95% of the OS/400 programmers use ILE/RPG exclusively, a definition 235 /COPY member is provided for this language. To include all libcurl 236 definitions in an ILE/RPG module, line 237 238 h bnddir('CURL/CURL') 239 240must figure in the program header, and line 241 242 d/copy curl/h,curl.inc 243 244in the global data section of the module's source code. 245 246 No vararg procedure support exists in ILE/RPG: for this reason, the following 247considerations apply: 248_ Procedures curl_easy_setopt_long(), curl_easy_setopt_object(), 249 curl_easy_setopt_function() and curl_easy_setopt_offset() are all alias 250 prototypes to curl_easy_setopt(), but with different parameter lists. 251_ Procedures curl_easy_getinfo_string(), curl_easy_getinfo_long(), 252 curl_easy_getinfo_double() and curl_easy_getinfo_slist() are all alias 253 prototypes to curl_easy_getinfo(), but with different parameter lists. 254_ Procedures curl_multi_setopt_long(), curl_multi_setopt_object(), 255 curl_multi_setopt_function() and curl_multi_setopt_offset() are all alias 256 prototypes to curl_multi_setopt(), but with different parameter lists. 257_ The prototype of procedure curl_formadd() allows specifying a pointer option 258 and the CURLFORM_END option. This makes possible to use an option array 259 without any additional definition. If some specific incompatible argument 260 list is used in the ILE/RPG program, the latter must define a specialised 261 alias. The same applies to curl_formadd_ccsid() too. 262 263 Since RPG cannot cast a long to a pointer, procedure curl_form_long_value() 264is provided for that purpose: this allows storing a long value in the curl_forms 265array. 266