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 Two SSL implementations are available to libcurl on OS/400: QsoSSL which is 43obsolescent, does not support asynchronous I/O and only allows a single SSL 44context within a job, and GSKit that does not suffer from these limitations 45and is able to provide some information about the server certificate. 46 Both implementations of SSL are working on "certificate stores" or keyrings, 47rather than individual certificate/key files. Certificate stores, as weel as 48"certificate labels" are managed by external IBM-defined applications. 49 There are two ways to specify an SSL context: 50- By an application identifier. 51- By a keyring file pathname and (optionally) certificate label. 52 To identify an SSL context by application identifier, use option 53SETOPT_SSLCERT to specify the application identifier. 54 To address an SSL context by keyring and certificate label, use CURLOPT_CAINFO 55to set-up the keyring pathname, CURLOPT_SSLCERT to define the certificate label 56(omitting it will cause the default certificate in keyring to be used) and 57CURLOPT_KEYPASSWD to give the keyring password. If SSL is used without 58defining any of these options, the default (i.e.: system) keyring is used for 59server certificate validation. 60 61 Non-standard EBCDIC wrapper prototypes are defined in an additional header 62file: ccsidcurl.h. These should be self-explanatory to an OS/400-aware 63designer. CCSID 0 can be used to select the current job's CCSID. 64 Wrapper procedures with variable arguments are described below: 65 66_ curl_easy_setopt_ccsid() 67 Variable arguments are a string pointer and a CCSID (unsigned int) for 68options: 69 CURLOPT_CAINFO 70 CURLOPT_CAPATH 71 CURLOPT_COOKIE 72 CURLOPT_COOKIEFILE 73 CURLOPT_COOKIEJAR 74 CURLOPT_COOKIELIST 75 CURLOPT_COPYPOSTFIELDS 76 CURLOPT_CRLFILE 77 CURLOPT_CUSTOMREQUEST 78 CURLOPT_DNS_SERVERS 79 CURLOPT_EGDSOCKET 80 CURLOPT_ENCODING 81 CURLOPT_FTP_ACCOUNT 82 CURLOPT_FTP_ALTERNATIVE_TO_USER 83 CURLOPT_FTPPORT 84 CURLOPT_INTERFACE 85 CURLOPT_ISSUERCERT 86 CURLOPT_KEYPASSWD 87 CURLOPT_KRBLEVEL 88 CURLOPT_LOGIN_OPTIONS 89 CURLOPT_MAIL_FROM 90 CURLOPT_MAIL_AUTH 91 CURLOPT_NETRC_FILE 92 CURLOPT_NOPROXY 93 CURLOPT_PASSWORD 94 CURLOPT_PROXY 95 CURLOPT_PROXYPASSWORD 96 CURLOPT_PROXYUSERNAME 97 CURLOPT_PROXYUSERPWD 98 CURLOPT_RANDOM_FILE 99 CURLOPT_RANGE 100 CURLOPT_REFERER 101 CURLOPT_RTSP_SESSION_UID 102 CURLOPT_RTSP_STREAM_URI 103 CURLOPT_RTSP_TRANSPORT 104 CURLOPT_SOCKS5_GSSAPI_SERVICE 105 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 Note: SSH not available on OS400. 106 CURLOPT_SSH_KNOWNHOSTS Note: SSH not available on OS400. 107 CURLOPT_SSH_PRIVATE_KEYFILE Note: SSH not available on OS400. 108 CURLOPT_SSH_PUBLIC_KEYFILE Note: SSH not available on OS400. 109 CURLOPT_SSLCERT 110 CURLOPT_SSLCERTTYPE 111 CURLOPT_SSL_CIPHER_LIST 112 CURLOPT_SSLENGINE 113 CURLOPT_SSLKEY 114 CURLOPT_SSLKEYTYPE 115 CURLOPT_TLSAUTH_PASSWORD 116 CURLOPT_TLSAUTH_TYPE 117 CURLOPT_TLSAUTH_USERNAME 118 CURLOPT_URL 119 CURLOPT_USERAGENT 120 CURLOPT_USERNAME 121 CURLOPT_USERPWD 122 CURLOPT_XOAUTH2_BEARER 123 Else it is the same as for curl_easy_setopt(). 124 Note that CURLOPT_ERRORBUFFER is not in the list above, since it gives the 125address of an (empty) character buffer, not the address of a string. 126CURLOPT_POSTFIELDS stores the address of static binary data (of type void *) and 127thus is not converted. If CURLOPT_COPYPOSTFIELDS is issued after 128CURLOPT_POSTFIELDSIZE != -1, the data size is adjusted according to the 129CCSID conversion result length. 130 131_ curl_formadd_ccsid() 132 In the variable argument list, string pointers should be followed by a (long) 133CCSID for the following options: 134 CURLFORM_FILENAME 135 CURLFORM_CONTENTTYPE 136 CURLFORM_BUFFER 137 CURLFORM_FILE 138 CURLFORM_FILECONTENT 139 CURLFORM_COPYCONTENTS 140 CURLFORM_COPYNAME 141 CURLFORM_PTRNAME 142 If taken from an argument array, an additional array entry must follow each 143entry containing one of the above option. This additional entry holds the CCSID 144in its value field, and the option field is meaningless. 145 It is not possible to have a string pointer and its CCSID across a function 146parameter/array boundary. 147 Please note that CURLFORM_PTRCONTENTS and CURLFORM_BUFFERPTR are considered 148unconvertible strings and thus are NOT followed by a CCSID. 149 150_ curl_easy_getinfo_ccsid 151 The following options are followed by a 'char * *' and a CCSID. Unlike 152curl_easy_getinfo(), the value returned in the pointer should be freed after 153use: 154 CURLINFO_EFFECTIVE_URL 155 CURLINFO_CONTENT_TYPE 156 CURLINFO_FTP_ENTRY_PATH 157 CURLINFO_REDIRECT_URL 158 CURLINFO_PRIMARY_IP 159 CURLINFO_RTSP_SESSION_ID 160 CURLINFO_LOCAL_IP 161 Likewise, the following options are followed by a struct curl_slist * * and a 162CCSID. 163 CURLINFO_SSL_ENGINES 164 CURLINFO_COOKIELIST 165Lists returned should be released with curl_slist_free_all() after use. 166 Option CURLINFO_CERTINFO is followed by a struct curl_certinfo * * and a 167CCSID. Returned structures sould be free'ed using curl_certinfo_free_all() after 168use. 169 Other options are processed like in curl_easy_getinfo(). 170 171 Standard compilation environment does support neither autotools nor make; 172in fact, very few common utilities are available. As a consequence, the 173config-os400.h has been coded manually and the compilation scripts are 174a set of shell scripts stored in subdirectory packages/OS400. 175 176 The "curl" command and the test environment are currently not supported on 177OS/400. 178 179 180Protocols currently implemented on OS/400: 181_ DICT 182_ FILE 183_ FTP 184_ FTPS 185_ FTP with secure transmission 186_ GOPHER 187_ HTTP 188_ HTTPS 189_ IMAP 190_ IMAPS 191_ IMAP with secure transmission 192_ LDAP 193_ POP3 194_ POP3S 195_ POP3 with secure transmission 196_ RTSP 197_ SMTP 198_ SMTPS 199_ SMTP with secure transmission 200_ TELNET 201_ TFTP 202 203 204 205Compiling on OS/400: 206 207 These instructions targets people who knows about OS/400, compiling, IFS and 208archive extraction. Do not ask questions about these subjects if you're not 209familiar with. 210 211_ As a prerequisite, QADRT development environment must be installed. 212_ Install the curl source directory in IFS. 213_ Enter shell (QSH) 214_ Change current directory to the curl installation directory 215- If the SSL backend has to be changed, edit file lib/config-os400.h 216 accordingly. 217_ Change current directory to ./packages/OS400 218_ Edit file iniscript.sh. You may want to change tunable configuration 219 parameters, like debug info generation, optimisation level, listing option, 220 target library, etc. 221_ Copy any file in the current directory to makelog (i.e.: 222 cp initscript.sh makelog): this is intended to create the makelog file with 223 an ASCII CCSID! 224_ Enter the command "sh makefile.sh > makelog 2>&1' 225_ Examine the makelog file to check for compilation errors. 226 227 Leaving file initscript.sh unchanged, this will produce the following OS/400 228objects: 229_ Library CURL. All other objects will be stored in this library. 230_ Modules for all libcurl units. 231_ Binding directory CURL_A, to be used at calling program link time for 232 statically binding the modules (specify BNDSRVPGM(QADRTTS QGLDCLNT QGLDBRDR) 233 when creating a program using CURL_A). 234_ Service program CURL.<soname>, where <soname> is extracted from the 235 lib/Makefile.am VERSION variable. To be used at calling program run-time 236 when this program has dynamically bound curl at link time. 237_ Binding directory CURL. To be used to dynamically bind libcurl when linking a 238 calling program. 239_ Source file H. It contains all the include members needed to compile a C/C++ 240 module using libcurl, and an ILE/RPG /copy member for support in this 241 language. 242_ Standard C/C++ libcurl include members in file H. 243_ CCSIDCURL member in file H. This defines the non-standard EBCDIC wrappers for 244 C and C++. 245_ CURL.INC member in file H. This defines everything needed by an ILE/RPG 246 program using libcurl. 247_ LIBxxx modules and programs. Although the test environment is not supported 248 on OS/400, the libcurl test programs are compiled for manual tests. 249 250 251 252Special programming consideration: 253 254QADRT being used, the following points must be considered: 255_ If static binding is used, service program QADRTTS must be linked too. 256_ The EBCDIC CCSID used by QADRT is 37 by default, NOT THE JOB'S CCSID. If 257 another EBCDIC CCSID is required, it must be set via a locale through a call 258 to setlocale_a (QADRT's setlocale() ASCII wrapper) with category LC_ALL or 259 LC_CTYPE, or by setting environment variable QADRT_ENV_LOCALE to the locale 260 object path before executing the program. 261_ Do not use original source include files unless you know what you are doing. 262 Use the installed members instead (in /QSYS.LIB/CURL.LIB/H.FILE). 263 264 265 266ILE/RPG support: 267 268 Since 95% of the OS/400 programmers use ILE/RPG exclusively, a definition 269 /COPY member is provided for this language. To include all libcurl 270 definitions in an ILE/RPG module, line 271 272 h bnddir('CURL/CURL') 273 274must figure in the program header, and line 275 276 d/copy curl/h,curl.inc 277 278in the global data section of the module's source code. 279 280 No vararg procedure support exists in ILE/RPG: for this reason, the following 281considerations apply: 282_ Procedures curl_easy_setopt_long(), curl_easy_setopt_object(), 283 curl_easy_setopt_function() and curl_easy_setopt_offset() are all alias 284 prototypes to curl_easy_setopt(), but with different parameter lists. 285_ Procedures curl_easy_getinfo_string(), curl_easy_getinfo_long(), 286 curl_easy_getinfo_double() and curl_easy_getinfo_slist() are all alias 287 prototypes to curl_easy_getinfo(), but with different parameter lists. 288_ Procedures curl_multi_setopt_long(), curl_multi_setopt_object(), 289 curl_multi_setopt_function() and curl_multi_setopt_offset() are all alias 290 prototypes to curl_multi_setopt(), but with different parameter lists. 291_ The prototype of procedure curl_formadd() allows specifying a pointer option 292 and the CURLFORM_END option. This makes possible to use an option array 293 without any additional definition. If some specific incompatible argument 294 list is used in the ILE/RPG program, the latter must define a specialised 295 alias. The same applies to curl_formadd_ccsid() too. 296 297 Since RPG cannot cast a long to a pointer, procedure curl_form_long_value() 298is provided for that purpose: this allows storing a long value in the curl_forms 299array. 300