README.OS400 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390
  1. Implementation notes:
  2. This is a true OS/400 ILE implementation, not a PASE implementation (for
  3. PASE, use AIX implementation).
  4. The biggest problem with OS/400 is EBCDIC. Libcurl implements an internal
  5. conversion mechanism, but it has been designed for computers that have a
  6. single native character set. OS/400 default native character set varies
  7. depending on the country for which it has been localized. And more, a job
  8. may dynamically alter its "native" character set.
  9. Several characters that do not have fixed code in EBCDIC variants are
  10. used in libcurl strings. As a consequence, using the existing conversion
  11. mechanism would have lead in a localized binary library - not portable across
  12. countries.
  13. For this reason, and because libcurl was originally designed for ASCII based
  14. operating systems, the current OS/400 implementation uses ASCII as internal
  15. character set. This has been accomplished using the QADRT library and
  16. include files, a C and system procedures ASCII wrapper library. See IBM QADRT
  17. description for more information.
  18. This then results in libcurl being an ASCII library: any function string
  19. argument is taken/returned in ASCII and a C/C++ calling program built around
  20. QADRT may use libcurl functions as on any other platform.
  21. QADRT does not define ASCII wrappers for all C/system procedures: the
  22. OS/400 configuration header file and an additional module (os400sys.c) define
  23. some more of them, that are used by libcurl and that QADRT left out.
  24. To support all the different variants of EBCDIC, non-standard wrapper
  25. procedures have been added to libcurl on OS/400: they provide an additional
  26. CCSID (numeric Coded Character Set ID specific to OS/400) parameter for each
  27. string argument. Callback procedures arguments giving access to strings are
  28. NOT converted, so text gathered this way is (probably !) ASCII.
  29. Another OS/400 problem comes from the fact that the last fixed argument of a
  30. vararg procedure may not be of type char, unsigned char, short or unsigned
  31. short. Enums that are internally implemented by the C compiler as one of these
  32. types are also forbidden. Libcurl uses enums as vararg procedure tagfields...
  33. Happily, there is a pragma forcing enums to type "int". The original libcurl
  34. header files are thus altered during build process to use this pragma, in
  35. order to force libcurl enums of being type int (the pragma disposition in use
  36. before inclusion is restored before resuming the including unit compilation).
  37. Non-standard EBCDIC wrapper prototypes are defined in an additional header
  38. file: ccsidcurl.h. These should be self-explanatory to an OS/400-aware
  39. designer. CCSID 0 can be used to select the current job's CCSID.
  40. Wrapper procedures with variable arguments are described below:
  41. _ curl_easy_setopt_ccsid()
  42. Variable arguments are a string pointer and a CCSID (unsigned int) for
  43. options:
  44. CURLOPT_ABSTRACT_UNIX_SOCKET
  45. CURLOPT_ACCEPT_ENCODING
  46. CURLOPT_ALTSVC
  47. CURLOPT_AWS_SIGV4
  48. CURLOPT_CAINFO
  49. CURLOPT_CAPATH
  50. CURLOPT_COOKIE
  51. CURLOPT_COOKIEFILE
  52. CURLOPT_COOKIEJAR
  53. CURLOPT_COOKIELIST
  54. CURLOPT_CRLFILE
  55. CURLOPT_CUSTOMREQUEST
  56. CURLOPT_DEFAULT_PROTOCOL
  57. CURLOPT_DNS_INTERFACE
  58. CURLOPT_DNS_LOCAL_IP4
  59. CURLOPT_DNS_LOCAL_IP6
  60. CURLOPT_DNS_SERVERS
  61. CURLOPT_DOH_URL
  62. CURLOPT_EGDSOCKET
  63. CURLOPT_FTPPORT
  64. CURLOPT_FTP_ACCOUNT
  65. CURLOPT_FTP_ALTERNATIVE_TO_USER
  66. CURLOPT_HAPROXY_CLIENT_IP
  67. CURLOPT_HSTS
  68. CURLOPT_INTERFACE
  69. CURLOPT_ISSUERCERT
  70. CURLOPT_KEYPASSWD
  71. CURLOPT_KRBLEVEL
  72. CURLOPT_LOGIN_OPTIONS
  73. CURLOPT_MAIL_AUTH
  74. CURLOPT_MAIL_FROM
  75. CURLOPT_NETRC_FILE
  76. CURLOPT_NOPROXY
  77. CURLOPT_PASSWORD
  78. CURLOPT_PINNEDPUBLICKEY
  79. CURLOPT_PRE_PROXY
  80. CURLOPT_PROTOCOLS_STR
  81. CURLOPT_PROXY
  82. CURLOPT_PROXYPASSWORD
  83. CURLOPT_PROXYUSERNAME
  84. CURLOPT_PROXYUSERPWD
  85. CURLOPT_PROXY_CAINFO
  86. CURLOPT_PROXY_CAPATH
  87. CURLOPT_PROXY_CRLFILE
  88. CURLOPT_PROXY_ISSUERCERT
  89. CURLOPT_PROXY_KEYPASSWD
  90. CURLOPT_PROXY_PINNEDPUBLICKEY
  91. CURLOPT_PROXY_SERVICE_NAME
  92. CURLOPT_PROXY_SSLCERT
  93. CURLOPT_PROXY_SSLCERTTYPE
  94. CURLOPT_PROXY_SSLKEY
  95. CURLOPT_PROXY_SSLKEYTYPE
  96. CURLOPT_PROXY_SSL_CIPHER_LIST
  97. CURLOPT_PROXY_TLS13_CIPHERS
  98. CURLOPT_PROXY_TLSAUTH_PASSWORD
  99. CURLOPT_PROXY_TLSAUTH_TYPE
  100. CURLOPT_PROXY_TLSAUTH_USERNAME
  101. CURLOPT_RANDOM_FILE
  102. CURLOPT_RANGE
  103. CURLOPT_REDIR_PROTOCOLS_STR
  104. CURLOPT_REFERER
  105. CURLOPT_REQUEST_TARGET
  106. CURLOPT_RTSP_SESSION_ID
  107. CURLOPT_RTSP_STREAM_URI
  108. CURLOPT_RTSP_TRANSPORT
  109. CURLOPT_SASL_AUTHZID
  110. CURLOPT_SERVICE_NAME
  111. CURLOPT_SOCKS5_GSSAPI_SERVICE
  112. CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
  113. CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256
  114. CURLOPT_SSH_KNOWNHOSTS
  115. CURLOPT_SSH_PRIVATE_KEYFILE
  116. CURLOPT_SSH_PUBLIC_KEYFILE
  117. CURLOPT_SSLCERT
  118. CURLOPT_SSLCERTTYPE
  119. CURLOPT_SSLENGINE
  120. CURLOPT_SSLKEY
  121. CURLOPT_SSLKEYTYPE
  122. CURLOPT_SSL_CIPHER_LIST
  123. CURLOPT_SSL_EC_CURVES
  124. CURLOPT_TLS13_CIPHERS
  125. CURLOPT_TLSAUTH_PASSWORD
  126. CURLOPT_TLSAUTH_TYPE
  127. CURLOPT_TLSAUTH_USERNAME
  128. CURLOPT_UNIX_SOCKET_PATH
  129. CURLOPT_URL
  130. CURLOPT_USERAGENT
  131. CURLOPT_USERNAME
  132. CURLOPT_USERPWD
  133. CURLOPT_XOAUTH2_BEARER
  134. All blob options are also supported.
  135. In all other cases, it ignores the ccsid parameter and behaves as
  136. curl_easy_setopt().
  137. Note that CURLOPT_ERRORBUFFER is not in the list above, since it gives the
  138. address of an (empty) character buffer, not the address of a string.
  139. CURLOPT_POSTFIELDS stores the address of static binary data (of type void *)
  140. and thus is not converted. If CURLOPT_COPYPOSTFIELDS is issued after
  141. CURLOPT_POSTFIELDSIZE != -1, the data size is adjusted according to the
  142. CCSID conversion result length.
  143. _ curl_formadd_ccsid()
  144. In the variable argument list, string pointers should be followed by a (long)
  145. CCSID for the following options:
  146. CURLFORM_BUFFER
  147. CURLFORM_CONTENTTYPE
  148. CURLFORM_COPYCONTENTS
  149. CURLFORM_COPYNAME
  150. CURLFORM_FILE
  151. CURLFORM_FILECONTENT
  152. CURLFORM_FILENAME
  153. CURLFORM_PTRNAME
  154. If taken from an argument array, an additional array entry must follow each
  155. entry containing one of the above option. This additional entry holds the CCSID
  156. in its value field, and the option field is meaningless.
  157. It is not possible to have a string pointer and its CCSID across a function
  158. parameter/array boundary.
  159. Please note that CURLFORM_PTRCONTENTS and CURLFORM_BUFFERPTR are considered
  160. unconvertible strings and thus are NOT followed by a CCSID.
  161. _ curl_easy_getinfo_ccsid()
  162. The following options are followed by a 'char * *' and a CCSID. Unlike
  163. curl_easy_getinfo(), the value returned in the pointer should be released with
  164. curl_free() after use:
  165. CURLINFO_CONTENT_TYPE
  166. CURLINFO_EFFECTIVE_URL
  167. CURLINFO_FTP_ENTRY_PATH
  168. CURLINFO_LOCAL_IP
  169. CURLINFO_PRIMARY_IP
  170. CURLINFO_REDIRECT_URL
  171. CURLINFO_REFERER
  172. CURLINFO_RTSP_SESSION_ID
  173. CURLINFO_SCHEME
  174. Likewise, the following options are followed by a struct curl_slist * * and a
  175. CCSID.
  176. CURLINFO_COOKIELIST
  177. CURLINFO_SSL_ENGINES
  178. Lists returned should be released with curl_slist_free_all() after use.
  179. Option CURLINFO_CERTINFO is followed by a struct curl_certinfo * * and a
  180. CCSID. Returned structures should be freed with curl_certinfo_free_all()
  181. after use.
  182. Other options are processed like in curl_easy_getinfo().
  183. _ curl_easy_strerror_ccsid(), curl_multi_strerror_ccsid(),
  184. curl_share_strerror_ccsid() and curl_url_strerror_ccsid() work as their
  185. non-ccsid version and return a string encoded in the additional ccsid
  186. parameter. These strings belong to libcurl and may not be freed by the caller.
  187. A subsequent call to the same procedure in the same thread invalidates the
  188. previous result.
  189. _ curl_pushheader_bynum_cssid() and curl_pushheader_byname_ccsid()
  190. Although the prototypes are self-explanatory, the returned string pointer
  191. should be released with curl_free() after use, as opposite to the non-ccsid
  192. versions of these procedures.
  193. Please note that HTTP2 is not (yet) implemented on OS/400, thus these
  194. functions will always return NULL.
  195. _ curl_easy_option_by_name_ccsid() returns a pointer to an untranslated option
  196. metadata structure. As each curl_easyoption structure holds the option name in
  197. ASCII, the curl_easy_option_get_name_ccsid() function allows getting it in any
  198. supported ccsid. However the caller should release the returned pointer with
  199. curl_free() after use.
  200. _ curl_easy_header_ccsid() works as its non-CCSID counterpart but requires an
  201. additional ccsid parameter specifying the name parameter encoding. The output
  202. hout parameter is kept in libcurl's encoding and should not be altered.
  203. _ curl_from_ccsid() and curl_to_ccsid() are string encoding conversion
  204. functions between ASCII (latin1) and the given CCSID. The first parameter is
  205. the source string, the second is the CCSID and the returned value is a pointer
  206. to the dynamically allocated string. These functions do not impact on Curl's
  207. behavior and are only provided for user convenience. After use, returned values
  208. must be released with curl_free().
  209. Standard compilation environment does support neither autotools nor make;
  210. in fact, very few common utilities are available. As a consequence, the
  211. config-os400.h has been coded manually and the compilation scripts are
  212. a set of shell scripts stored in subdirectory packages/OS400.
  213. The test environment is currently not supported on OS/400.
  214. Protocols currently implemented on OS/400:
  215. _ DICT
  216. _ FILE
  217. _ FTP
  218. _ FTPS
  219. _ FTP with secure transmission
  220. _ GOPHER
  221. _ HTTP
  222. _ HTTPS
  223. _ IMAP
  224. _ IMAPS
  225. _ IMAP with secure transmission
  226. _ LDAP
  227. _ POP3
  228. _ POP3S
  229. _ POP3 with secure transmission
  230. _ RTSP
  231. _ SCP if libssh2 is enabled
  232. _ SFTP if libssh2 is enabled
  233. _ SMTP
  234. _ SMTPS
  235. _ SMTP with secure transmission
  236. _ TELNET
  237. _ TFTP
  238. Compiling on OS/400:
  239. These instructions targets people who knows about OS/400, compiling, IFS and
  240. archive extraction. Do not ask questions about these subjects if you're not
  241. familiar with.
  242. _ As a prerequisite, QADRT development environment must be installed.
  243. For more information on downloading and installing the QADRT development kit,
  244. please see https://www.ibm.com/support/pages/node/6258183
  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 Qshell (QSH, not PASE)
  252. _ Change current directory to the curl installation directory
  253. _ Change current directory to ./packages/OS400
  254. - If you want to change the default configuration parameters like debug info
  255. generation, optimization level, listing option, target library, ZLIB/LIBSSH2
  256. availability and location, etc., copy file config400.default to
  257. config400.override and edit the latter. Do not edit the original default file
  258. as it might be overwritten by a subsequent source installation.
  259. _ Copy any file in the current directory to makelog (i.e.:
  260. cp initscript.sh makelog): this is intended to create the makelog file with
  261. an ASCII CCSID!
  262. _ Enter the command "sh makefile.sh > makelog 2>&1"
  263. _ Examine the makelog file to check for compilation errors. CZM0383 warnings on
  264. C or system standard API come from QADRT inlining and can safely be ignored.
  265. Without configuration parameters override, this will produce the following
  266. OS/400 objects:
  267. _ Library CURL. All other objects will be stored in this library.
  268. _ Modules for all libcurl units.
  269. _ Binding directory CURL_A, to be used at calling program link time for
  270. statically binding the modules (specify BNDSRVPGM(QADRTTS QGLDCLNT QGLDBRDR)
  271. when creating a program using CURL_A).
  272. _ Service program CURL.<soname>, where <soname> is extracted from the
  273. lib/Makefile.am VERSION variable. To be used at calling program run-time
  274. when this program has dynamically bound curl at link time.
  275. _ Binding directory CURL. To be used to dynamically bind libcurl when linking a
  276. calling program.
  277. - CLI tool bound program CURL.
  278. - CLI command CURL.
  279. _ Source file H. It contains all the include members needed to compile a C/C++
  280. module using libcurl, and an ILE/RPG /copy member for support in this
  281. language.
  282. _ Standard C/C++ libcurl include members in file H.
  283. _ CCSIDCURL member in file H. This defines the non-standard EBCDIC wrappers for
  284. C and C++.
  285. _ CURL.INC member in file H. This defines everything needed by an ILE/RPG
  286. program using libcurl.
  287. _ IFS directory /curl/include/curl containing the C header files for IFS source
  288. C/C++ compilation and curl.inc.rpgle for IFS source ILE/RPG compilation.
  289. - IFS link /curl/bin/curl to CLI tool program.
  290. Special programming consideration:
  291. QADRT being used, the following points must be considered:
  292. _ If static binding is used, service program QADRTTS must be linked too.
  293. _ The EBCDIC CCSID used by QADRT is 37 by default, NOT THE JOB'S CCSID. If
  294. another EBCDIC CCSID is required, it must be set via a locale through a call
  295. to setlocale_a (QADRT's setlocale() ASCII wrapper) with category LC_ALL or
  296. LC_CTYPE, or by setting environment variable QADRT_ENV_LOCALE to the locale
  297. object path before executing the program.
  298. _ Do not use original source include files unless you know what you are doing.
  299. Use the installed members instead (in /QSYS.LIB/CURL.LIB/H.FILE and
  300. /curl/include/curl).
  301. ILE/RPG support:
  302. Since most of the ILE OS/400 programmers use ILE/RPG exclusively, a
  303. definition /INCLUDE member is provided for this language. To include all
  304. libcurl definitions in an ILE/RPG module, line
  305. h bnddir('CURL/CURL')
  306. must figure in the program header, and line
  307. d/include curl/h,curl.inc
  308. in the global data section of the module's source code.
  309. No vararg procedure support exists in ILE/RPG: for this reason, the following
  310. considerations apply:
  311. _ Procedures curl_easy_setopt_long(), curl_easy_setopt_object(),
  312. curl_easy_setopt_function(), curl_easy_setopt_offset() and
  313. curl_easy_setopt_blob() are all alias prototypes to curl_easy_setopt(), but
  314. with different parameter lists.
  315. _ Procedures curl_easy_getinfo_string(), curl_easy_getinfo_long(),
  316. curl_easy_getinfo_double(), curl_easy_getinfo_slist(),
  317. curl_easy_getinfo_ptr(), curl_easy_getinfo_socket() and
  318. curl_easy_getinfo_off_t() are all alias prototypes to curl_easy_getinfo(),
  319. but with different parameter lists.
  320. _ Procedures curl_multi_setopt_long(), curl_multi_setopt_object(),
  321. curl_multi_setopt_function() and curl_multi_setopt_offset() are all alias
  322. prototypes to curl_multi_setopt(), but with different parameter lists.
  323. _ Procedures curl_share_setopt_int(), curl_share_setopt_ptr() and
  324. curl_share_setopt_proc() are all alias prototypes to curl_share_setopt,
  325. but with different parameter lists.
  326. _ Procedure curl_easy_setopt_blob_ccsid() is an alias of
  327. curl_easy_setopt_ccsid() supporting blob encoding conversion.
  328. _ The prototype of procedure curl_formadd() allows specifying a pointer option
  329. and the CURLFORM_END option. This makes possible to use an option array
  330. without any additional definition. If some specific incompatible argument
  331. list is used in the ILE/RPG program, the latter must define a specialised
  332. alias. The same applies to curl_formadd_ccsid() too.
  333. _ Since V7R4M0, procedure overloading is used to emulate limited "vararg-like"
  334. definitions of curl_easy_setopt(), curl_multi_setopt(), curl_share_setopt()
  335. and curl_easy_getinfo(). Blob and CCSID alternatives are NOT included in
  336. overloading.
  337. Since RPG cannot cast a long to a pointer, procedure curl_form_long_value()
  338. is provided for that purpose: this allows storing a long value in the
  339. curl_forms array. Please note the form API is deprecated and the MIME API
  340. should be used instead.
  341. CLI tool:
  342. The build system provides it as a bound program, an IFS link to it and a
  343. simple CL command. The latter however is not able to provide a different
  344. parameter for each option since there are too many of those; instead,
  345. parameters are entered in a single field subject to quoting and escaping, in
  346. the same form as expected by the standard CLI program.
  347. Care must be taken about the program output encoding: by default, it is sent
  348. to the standard output and is thus subject to transcoding. It is therefore
  349. recommended to use option "--output" to redirect output to a specific IFS file.
  350. Similar problems may occur about the standard input encoding.