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