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