packages/OS400/README.OS400

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