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