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