4 This is a true OS/400 implementation, not a PASE implementation (for PASE,
5 use AIX implementation).
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
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.
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).
42 Two SSL implementations are available to libcurl on OS/400: QsoSSL which is
43 obsolescent, does not support asynchronous I/O and only allows a single SSL
44 context within a job, and GSKit that does not suffer from these limitations
45 and is able to provide some information about the server certificate.
46 Both implementations of SSL are working on "certificate stores" or keyrings,
47 rather 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
53 SETOPT_SSLCERT to specify the application identifier.
54 To address an SSL context by keyring and certificate label, use CURLOPT_CAINFO
55 to 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
57 CURLOPT_KEYPASSWD to give the keyring password. If SSL is used without
58 defining any of these options, the default (i.e.: system) keyring is used for
59 server certificate validation.
61 Non-standard EBCDIC wrapper prototypes are defined in an additional header
62 file: ccsidcurl.h. These should be self-explanatory to an OS/400-aware
63 designer. CCSID 0 can be used to select the current job's CCSID.
64 Wrapper procedures with variable arguments are described below:
66 _ curl_easy_setopt_ccsid()
67 Variable arguments are a string pointer and a CCSID (unsigned int) for
75 CURLOPT_COPYPOSTFIELDS
82 CURLOPT_FTP_ALTERNATIVE_TO_USER
100 CURLOPT_RTSP_SESSION_UID
101 CURLOPT_RTSP_STREAM_URI
102 CURLOPT_RTSP_TRANSPORT
103 CURLOPT_SOCKS5_GSSAPI_SERVICE
104 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 Note: SSH not available on OS400.
105 CURLOPT_SSH_KNOWNHOSTS Note: SSH not available on OS400.
106 CURLOPT_SSH_PRIVATE_KEYFILE Note: SSH not available on OS400.
107 CURLOPT_SSH_PUBLIC_KEYFILE Note: SSH not available on OS400.
110 CURLOPT_SSL_CIPHER_LIST
114 CURLOPT_TLSAUTH_PASSWORD
116 CURLOPT_TLSAUTH_USERNAME
121 Else it is the same as for curl_easy_setopt().
122 Note that CURLOPT_ERRORBUFFER is not in the list above, since it gives the
123 address of an (empty) character buffer, not the address of a string.
124 CURLOPT_POSTFIELDS stores the address of static binary data (of type void *) and
125 thus is not converted. If CURLOPT_COPYPOSTFIELDS is issued after
126 CURLOPT_POSTFIELDSIZE != -1, the data size is adjusted according to the
127 CCSID conversion result length.
129 _ curl_formadd_ccsid()
130 In the variable argument list, string pointers should be followed by a (long)
131 CCSID for the following options:
137 CURLFORM_COPYCONTENTS
140 If taken from an argument array, an additional array entry must follow each
141 entry containing one of the above option. This additional entry holds the CCSID
142 in its value field, and the option field is meaningless.
143 It is not possible to have a string pointer and its CCSID across a function
144 parameter/array boundary.
145 Please note that CURLFORM_PTRCONTENTS and CURLFORM_BUFFERPTR are considered
146 unconvertible strings and thus are NOT followed by a CCSID.
148 _ curl_easy_getinfo_ccsid
149 The following options are followed by a 'char * *' and a CCSID. Unlike
150 curl_easy_getinfo(), the value returned in the pointer should be freed after
152 CURLINFO_EFFECTIVE_URL
153 CURLINFO_CONTENT_TYPE
154 CURLINFO_FTP_ENTRY_PATH
155 CURLINFO_REDIRECT_URL
157 CURLINFO_RTSP_SESSION_ID
159 Likewise, the following options are followed by a struct curl_slist * * and a
163 Lists returned should be released with curl_slist_free_all() after use.
164 Option CURLINFO_CERTINFO is followed by a struct curl_certinfo * * and a
165 CCSID. Returned structures sould be free'ed using curl_certinfo_free_all() after
167 Other options are processed like in curl_easy_getinfo().
169 Standard compilation environment does support neither autotools nor make;
170 in fact, very few common utilities are available. As a consequence, the
171 config-os400.h has been coded manually and the compilation scripts are
172 a set of shell scripts stored in subdirectory packages/OS400.
174 The "curl" command and the test environment are currently not supported on
178 Protocols currently implemented on OS/400:
183 _ FTP with secure transmission
189 _ IMAP with secure transmission
193 _ POP3 with secure transmission
197 _ SMTP with secure transmission
205 These instructions targets people who knows about OS/400, compiling, IFS and
206 archive extraction. Do not ask questions about these subjects if you're not
209 _ As a prerequisite, QADRT development environment must be installed.
210 _ Install the curl source directory in IFS.
212 _ Change current directory to the curl installation directory
213 - If the SSL backend has to be changed, edit file lib/config-os400.h
215 _ Change current directory to ./packages/OS400
216 _ Edit file iniscript.sh. You may want to change tunable configuration
217 parameters, like debug info generation, optimisation level, listing option,
219 _ Copy any file in the current directory to makelog (i.e.:
220 cp initscript.sh makelog): this is intended to create the makelog file with
222 _ Enter the command "sh makefile.sh > makelog 2>&1'
223 _ Examine the makelog file to check for compilation errors.
225 Leaving file initscript.sh unchanged, this will produce the following OS/400
227 _ Library CURL. All other objects will be stored in this library.
228 _ Modules for all libcurl units.
229 _ Binding directory CURL_A, to be used at calling program link time for
230 statically binding the modules (specify BNDSRVPGM(QADRTTS QGLDCLNT QGLDBRDR)
231 when creating a program using CURL_A).
232 _ Service program CURL.<soname>, where <soname> is extracted from the
233 lib/Makefile.am VERSION variable. To be used at calling program run-time
234 when this program has dynamically bound curl at link time.
235 _ Binding directory CURL. To be used to dynamically bind libcurl when linking a
237 _ Source file H. It contains all the include members needed to compile a C/C++
238 module using libcurl, and an ILE/RPG /copy member for support in this
240 _ Standard C/C++ libcurl include members in file H.
241 _ CCSIDCURL member in file H. This defines the non-standard EBCDIC wrappers for
243 _ CURL.INC member in file H. This defines everything needed by an ILE/RPG
244 program using libcurl.
245 _ LIBxxx modules and programs. Although the test environment is not supported
246 on OS/400, the libcurl test programs are compiled for manual tests.
250 Special programming consideration:
252 QADRT being used, the following points must be considered:
253 _ If static binding is used, service program QADRTTS must be linked too.
254 _ The EBCDIC CCSID used by QADRT is 37 by default, NOT THE JOB'S CCSID. If
255 another EBCDIC CCSID is required, it must be set via a locale through a call
256 to setlocale_a (QADRT's setlocale() ASCII wrapper) with category LC_ALL or
257 LC_CTYPE, or by setting environment variable QADRT_ENV_LOCALE to the locale
258 object path before executing the program.
259 _ Do not use original source include files unless you know what you are doing.
260 Use the installed members instead (in /QSYS.LIB/CURL.LIB/H.FILE).
266 Since 95% of the OS/400 programmers use ILE/RPG exclusively, a definition
267 /COPY member is provided for this language. To include all libcurl
268 definitions in an ILE/RPG module, line
270 h bnddir('CURL/CURL')
272 must figure in the program header, and line
274 d/copy curl/h,curl.inc
276 in the global data section of the module's source code.
278 No vararg procedure support exists in ILE/RPG: for this reason, the following
279 considerations apply:
280 _ Procedures curl_easy_setopt_long(), curl_easy_setopt_object(),
281 curl_easy_setopt_function() and curl_easy_setopt_offset() are all alias
282 prototypes to curl_easy_setopt(), but with different parameter lists.
283 _ Procedures curl_easy_getinfo_string(), curl_easy_getinfo_long(),
284 curl_easy_getinfo_double() and curl_easy_getinfo_slist() are all alias
285 prototypes to curl_easy_getinfo(), but with different parameter lists.
286 _ Procedures curl_multi_setopt_long(), curl_multi_setopt_object(),
287 curl_multi_setopt_function() and curl_multi_setopt_offset() are all alias
288 prototypes to curl_multi_setopt(), but with different parameter lists.
289 _ The prototype of procedure curl_formadd() allows specifying a pointer option
290 and the CURLFORM_END option. This makes possible to use an option array
291 without any additional definition. If some specific incompatible argument
292 list is used in the ILE/RPG program, the latter must define a specialised
293 alias. The same applies to curl_formadd_ccsid() too.
295 Since RPG cannot cast a long to a pointer, procedure curl_form_long_value()
296 is provided for that purpose: this allows storing a long value in the curl_forms