258 lines
11 KiB
Plaintext
258 lines
11 KiB
Plaintext
$Id: README.OS400,v 1.10 2008-10-17 13:17:41 patrickm Exp $
|
|
|
|
Implementation notes:
|
|
|
|
This is a true OS/400 implementation, not a PASE implementation (for PASE,
|
|
use AIX implementation).
|
|
|
|
The biggest problem with OS/400 is EBCDIC. Libcurl implements an internal
|
|
conversion mechanism, but it has been designed for computers that have a
|
|
single native character set. OS/400 default native character set varies
|
|
depending on the country for which it has been localized. And more, a job
|
|
may dynamically alter its "native" character set.
|
|
Several characters that do not have fixed code in EBCDIC variants are
|
|
used in libcurl strings. As a consequence, using the existing conversion
|
|
mechanism would have lead in a localized binary library - not portable across
|
|
countries.
|
|
For this reason, and because libcurl was originally designed for ASCII based
|
|
operating systems, the current OS/400 implementation uses ASCII as internal
|
|
character set. This has been accomplished using the QADRT library and
|
|
include files, a C and system procedures ASCII wrapper library. See IBM QADRT
|
|
description for more information.
|
|
This then results in libcurl being an ASCII library: any function string
|
|
argument is taken/returned in ASCII and a C/C++ calling program built around
|
|
QADRT may use libcurl functions as on any other platform.
|
|
QADRT does not define ASCII wrappers for all C/system procedures: the
|
|
OS/400 configuration header file and an additional module (os400sys.c) define
|
|
some more of them, that are used by libcurl and that QADRT left out.
|
|
To support all the different variants of EBCDIC, non-standard wrapper
|
|
procedures have been added to libcurl on OS/400: they provide an additional
|
|
CCSID (numeric Coded Character Set ID specific to OS/400) parameter for each
|
|
string argument. String values passed to callback procedures are NOT converted,
|
|
so text gathered this way is (probably !) ASCII.
|
|
|
|
Another OS/400 problem comes from the fact that the last fixed argument of a
|
|
vararg procedure may not be of type char, unsigned char, short or unsigned
|
|
short. Enums that are internally implemented by the C compiler as one of these
|
|
types are also forbidden. Libcurl uses enums as vararg procedure tagfields...
|
|
Happily, there is a pragma forcing enums to type "int". The original libcurl
|
|
header files are thus altered during build process to use this pragma, in
|
|
order to force libcurl enums of being type int (the pragma disposition in use
|
|
before inclusion is restored before resuming the including unit compilation).
|
|
|
|
Three SSL implementations were present in libcurl. Nevertheless, none of them
|
|
is available on OS/400. To support SSL on OS/400, a fourth implementation has
|
|
been added (qssl.[ch]). There is no way to have different certificate stores
|
|
for CAs and for personal/application certificates/key. More, the SSL context
|
|
may be defined as an application identifier in the main certificate store,
|
|
or as a keyring file. As a consequence, the meaning of some fields have been
|
|
slightly altered:
|
|
_ The "certificate identifier" is taken from CURLOPT_SSLCERT if defined, else
|
|
from CURLOPT_CAINFO.
|
|
_ The certificate identifier is then used as an application identifier in the
|
|
main certificate store. If successful, this context is used.
|
|
_ If the previous step failed, the certificate identifier is used as the file
|
|
name of a keyring. CURLOPT_KEYPASSWD is used here as the keyring password.
|
|
_ The default ca-bundle (CURLOPT_CAINFO) is set to the main certificate store's
|
|
keyring file name: this allows to use the system global CAs by default. (In that
|
|
case, the keyring password is safely recovered from the system... IBM dixit!)
|
|
|
|
Non-standard EBCDIC wrapper prototypes are defined in an additional header
|
|
file: ccsidcurl.h. These should be self-explanatory to an OS/400-aware
|
|
designer. CCSID 0 can be used to select the current job's CCSID.
|
|
Wrapper procedures with variable arguments are described below:
|
|
|
|
_ curl_easy_setopt_ccsid()
|
|
Variable arguments are a string pointer and a CCSID (unsigned int) for
|
|
options:
|
|
CURLOPT_CAINFO
|
|
CURLOPT_CAPATH
|
|
CURLOPT_COOKIE
|
|
CURLOPT_COOKIEFILE
|
|
CURLOPT_COOKIEJAR
|
|
CURLOPT_COOKIELIST
|
|
CURLOPT_CUSTOMREQUEST
|
|
CURLOPT_EGDSOCKET
|
|
CURLOPT_ENCODING
|
|
CURLOPT_FTPPORT
|
|
CURLOPT_FTP_ACCOUNT
|
|
CURLOPT_FTP_ALTERNATIVE_TO_USER
|
|
CURLOPT_INTERFACE
|
|
CURLOPT_KEYPASSWD
|
|
CURLOPT_KRBLEVEL
|
|
CURLOPT_NETRC_FILE
|
|
CURLOPT_COPYPOSTFIELDS
|
|
CURLOPT_PROXY
|
|
CURLOPT_PROXYUSERPWD
|
|
CURLOPT_RANDOM_FILE
|
|
CURLOPT_RANGE
|
|
CURLOPT_REFERER
|
|
CURLOPT_SSH_PRIVATE_KEYFILE
|
|
CURLOPT_SSH_PUBLIC_KEYFILE
|
|
CURLOPT_SSLCERT
|
|
CURLOPT_SSLCERTTYPE
|
|
CURLOPT_SSLENGINE
|
|
CURLOPT_SSLKEY
|
|
CURLOPT_SSLKEYTYPE
|
|
CURLOPT_SSL_CIPHER_LIST
|
|
CURLOPT_URL
|
|
CURLOPT_USERAGENT
|
|
CURLOPT_USERPWD
|
|
CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
|
|
CURLOPT_CRLFILE
|
|
CURLOPT_ISSUERCERT
|
|
CURLOPT_USERNAME
|
|
CURLOPT_PASSWORD
|
|
CURLOPT_PROXYUSERNAME
|
|
CURLOPT_PROXYPASSWORD
|
|
Else it is the same as for curl_easy_setopt().
|
|
Note that CURLOPT_ERRORBUFFER is not in the list above, since it gives the
|
|
address of an (empty) character buffer, not the address of a string.
|
|
CURLOPT_POSTFIELDS stores the address of static binary data (of type void *) and
|
|
thus is not converted. If CURLOPT_COPYPOSTFIELDS is issued after
|
|
CURLOPT_POSTFIELDSIZE != -1, the data size is adjusted according to the
|
|
CCSID conversion result length.
|
|
|
|
_ curl_formadd_ccsid()
|
|
In the variable argument list, string pointers should be followed by a (long)
|
|
CCSID for the following options:
|
|
CURLFORM_FILENAME
|
|
CURLFORM_CONTENTTYPE
|
|
CURLFORM_BUFFER
|
|
CURLFORM_FILE
|
|
CURLFORM_FILECONTENT
|
|
CURLFORM_COPYCONTENTS
|
|
CURLFORM_COPYNAME
|
|
CURLFORM_PTRNAME
|
|
If taken from an argument array, an additional array entry must follow each
|
|
entry containing one of the above option. This additional entry holds the CCSID
|
|
in its value field, and the option field is meaningless.
|
|
It is not possible to have a string pointer and its CCSID across a function
|
|
parameter/array boundary.
|
|
Please note that CURLFORM_PTRCONTENTS and CURLFORM_BUFFERPTR are considered
|
|
unconvertible strings and thus are NOT followed by a CCSID.
|
|
|
|
_ curl_easy_getinfo_ccsid
|
|
The following options are followed by a 'char * *' and a CCSID. Unlike
|
|
curl_easy_getinfo(), the value returned in the pointer should be freed after
|
|
use:
|
|
CURLINFO_EFFECTIVE_URL
|
|
CURLINFO_CONTENT_TYPE
|
|
CURLINFO_FTP_ENTRY_PATH
|
|
Other options are processed like in curl_easy_getinfo().
|
|
|
|
Standard compilation environment does support neither autotools nor make;
|
|
in fact, very few common utilities are available. As a consequence, the
|
|
config-os400.h has been coded manually and the compilation scripts are
|
|
a set of shell scripts stored in subdirectory packages/OS400.
|
|
|
|
The "curl" command and the test environment are currently not supported on
|
|
OS/400.
|
|
|
|
|
|
Protocols currently implemented on OS/400:
|
|
_ HTTP
|
|
_ HTTPS
|
|
_ FTP
|
|
_ FTPS
|
|
_ FTP with secure transmission.
|
|
_ LDAP
|
|
_ DICT
|
|
_ TELNET
|
|
|
|
|
|
|
|
Compiling on OS/400:
|
|
|
|
These instructions targets people who knows about OS/400, compiling, IFS and
|
|
archive extraction. Do not ask questions about these subjects if you're not
|
|
familiar with.
|
|
|
|
_ As a prerequisite, QADRT development environment must be installed.
|
|
_ Install the curl source directory in IFS.
|
|
_ Enter shell (QSH)
|
|
_ Change current directory to the curl installation directory
|
|
_ Change current directory to ./packages/OS400
|
|
_ Edit file iniscript.sh. You may want to change tunable configuration
|
|
parameters, like debug info generation, optimisation level, listing option,
|
|
target library, etc.
|
|
_ Copy any file in the current directory to makelog (i.e.:
|
|
cp initscript.sh makelog): this is intended to create the makelog file with
|
|
an ASCII CCSID!
|
|
_ Enter the command "sh makefile.sh > makelog 2>&1'
|
|
_ Examine the makelog file to check for compilation errors.
|
|
|
|
Leaving file initscript.sh unchanged, this will produce the following OS/400
|
|
objects:
|
|
_ Library CURL. All other objects will be stored in this library.
|
|
_ Modules for all libcurl units.
|
|
_ Binding directory CURL_A, to be used at calling program link time for
|
|
statically binding the modules (specify BNDSRVPGM(QADRTTS QGLDCLNT QGLDBRDR)
|
|
when creating a program using CURL_A).
|
|
_ Service program CURL.<soname>, where <soname> is extracted from the
|
|
lib/Makefile.am VERSION variable. To be used at calling program run-time
|
|
when this program has dynamically bound curl at link time.
|
|
_ Binding directory CURL. To be used to dynamically bind libcurl when linking a
|
|
calling program.
|
|
_ Source file H. It contains all the include members needed to compile a C/C++
|
|
module using libcurl, and an ILE/RPG /copy member for support in this
|
|
language.
|
|
_ Standard C/C++ libcurl include members in file H.
|
|
_ CCSIDCURL member in file H. This defines the non-standard EBCDIC wrappers for
|
|
C and C++.
|
|
_ CURL.INC member in file H. This defines everything needed by an ILE/RPG
|
|
program using libcurl.
|
|
_ LIBxxx modules and programs. Although the test environment is not supported
|
|
on OS/400, the libcurl test programs are compiled for manual tests.
|
|
|
|
|
|
|
|
Special programming consideration:
|
|
|
|
QADRT being used, the following points must be considered:
|
|
_ If static binding is used, service program QADRTTS must be linked too.
|
|
_ The EBCDIC CCSID used by QADRT is 37 by default, NOT THE JOB'S CCSID. If
|
|
another EBCDIC CCSID is required, it must be set via a locale through a call
|
|
to setlocale_a (QADRT's setlocale() ASCII wrapper) with category LC_ALL or
|
|
LC_CTYPE, or by setting environment variable QADRT_ENV_LOCALE to the locale
|
|
object path before executing the program.
|
|
_ Do not use original source include files unless you know what you are doing.
|
|
Use the installed members instead (in /QSYS.LIB/CURL.LIB/H.FILE).
|
|
|
|
|
|
|
|
ILE/RPG support:
|
|
|
|
Since 95% of the OS/400 programmers use ILE/RPG exclusively, a definition
|
|
/COPY member is provided for this language. To include all libcurl
|
|
definitions in an ILE/RPG module, line
|
|
|
|
h bnddir('CURL/CURL')
|
|
|
|
must figure in the program header, and line
|
|
|
|
d/copy curl/h,curl.inc
|
|
|
|
in the global data section of the module's source code.
|
|
|
|
No vararg procedure support exists in ILE/RPG: for this reason, the following
|
|
considerations apply:
|
|
_ Procedures curl_easy_setopt_long(), curl_easy_setopt_object(),
|
|
curl_easy_setopt_function() and curl_easy_setopt_offset() are all alias
|
|
prototypes to curl_easy_setopt(), but with different parameter lists.
|
|
_ Procedures curl_easy_getinfo_string(), curl_easy_getinfo_long(),
|
|
curl_easy_getinfo_double() and curl_easy_getinfo_slist() are all alias
|
|
prototypes to curl_easy_getinfo(), but with different parameter lists.
|
|
_ Procedures curl_multi_setopt_long(), curl_multi_setopt_object(),
|
|
curl_multi_setopt_function() and curl_multi_setopt_offset() are all alias
|
|
prototypes to curl_multi_setopt(), but with different parameter lists.
|
|
_ The prototype of procedure curl_formadd() allows specifying a pointer option
|
|
and the CURLFORM_END option. This makes possible to use an option array
|
|
without any additional definition. If some specific incompatible argument
|
|
list is used in the ILE/RPG program, the latter must define a specialised
|
|
alias. The same applies to curl_formadd_ccsid() too.
|
|
|
|
Since RPG cannot cast a long to a pointer, procedure curl_form_long_value()
|
|
is provided for that purpose: this allows storing a long value in the curl_forms
|
|
array.
|