170 lines
7.5 KiB
Plaintext
170 lines
7.5 KiB
Plaintext
|
|
Implementation notes:
|
|
|
|
This is a true OS/400 implementation, not a PASE implementation (for PASE,
|
|
use AIX implementation).
|
|
|
|
It 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 results in libssh2 being an ASCII library: any function string
|
|
argument is taken/returned in ASCII and a C/C++ calling program built around
|
|
QADRT may use libssh2 functions as on any other platform.
|
|
QADRT does not define ASCII wrappers for all C/system procedures: an
|
|
additional module (os400sys.c) define some more of them, that are used by
|
|
libssh2 and that QADRT left out.
|
|
Since standard library entry points expect and return ASCII character strings,
|
|
additional procedures are provided for string transcoding (see below). No
|
|
wrappers to standard procedures are provided: however, nested calls to
|
|
transcoding procedures may be used.
|
|
|
|
Crypto API is provided by the IBM QC3 API library. It supports RSA, but not DSA.
|
|
|
|
|
|
Standard compilation environment does support neither autotools nor make;
|
|
in fact, very few common utilities are available. As a consequence, the
|
|
libssh2_config.h has been coded manually and the compilation scripts are
|
|
a set of shell scripts stored in subdirectory os400.
|
|
|
|
The test environment is currently not supported on OS/400.
|
|
|
|
|
|
|
|
Compiling on OS/400:
|
|
|
|
These instructions target 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 libssh2 sources directory in IFS.
|
|
_ Enter shell (QSH)
|
|
_ Change current directory to the libssh2 sources installation directory
|
|
_ Change current directory to os400
|
|
_ Edit file iniscript.sh. You may want to change tunable configuration
|
|
parameters, like debug info generation, optimisation level, listing option,
|
|
target library, zlib availability and location, 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 make.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 LIBSSH2. All other objects will be stored in this library.
|
|
_ Modules for all libssh2 units.
|
|
_ Binding directory LIBSSH2_A, to be used at calling program link time for
|
|
statically binding the modules (specify BNDSRVPGM(QADRTTS) when creating a
|
|
program using LIBSSH2_A. Also give access to the zlib BNDDIR/SRVPGM if
|
|
libssh2 is compiled with zlib).
|
|
_ Service program LIBSSH2.<soname>, where <soname> is extracted from the
|
|
src/Makefile.am VERSION variable. To be used at calling program run-time
|
|
when this program has dynamically bound libssh2 at link time.
|
|
_ Binding directory LIBSSH2. To be used to dynamically bind libssh2 when
|
|
linking a calling program.
|
|
_ Source file H. It contains all the include members needed to compile a C/C++
|
|
module using libssh2.
|
|
_ LIBSSH2, SSH2_PKEY, SSH2_SFTP members in file H. These are the C/C++ header
|
|
files. Original fames have been mangled to fit member name allowed syntax.
|
|
_ Source file LIBSSH2RPG. It contains all the ILE/RPG /INCLUDE members
|
|
needed to compile an ILE/RPG program calling libssh2 procedures.
|
|
_ LIBSSH2, SSH2_PKEY, SSH2_SFTP members in file LIBSSH2RPG. These are
|
|
ILE/RPG translations of the corresponding C header files.
|
|
|
|
|
|
|
|
Special programming consideration:
|
|
|
|
QADRT being used, the following points must be considered:
|
|
_ If static binding is used, service program QADRTTS must be linked too.
|
|
_ Likewise, if libssh2 has been compiled with zlib support, access to the
|
|
zlib objects must be provided at link time.
|
|
_ 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/LIBSSH2.LIB/H.FILE).
|
|
|
|
|
|
|
|
String transcoding support:
|
|
|
|
To help passing arbitrarily encoded string arguments and/or receiving string
|
|
values from/to the libssh2 API, three non-standard additional procedures are
|
|
provided. They use a session pointer and a "string cache" pointer.
|
|
Each time a string is transcoded, it is cached in the given cache. It is
|
|
the responsibility of the caller to release the cache when its associted strings
|
|
are no longer needed. These procedures and the string cache type are defined
|
|
in a new libssh2_ccsid.h header file.
|
|
To create a string cache, use:
|
|
|
|
#include <libssh2_ccsid.h>
|
|
libssh2_string_cache * cache = NULL;
|
|
|
|
To release all strings in a cache, call:
|
|
|
|
libssh2_release_string_cache(session, &cache);
|
|
|
|
The transcoding procedures are:
|
|
|
|
char * libssh2_from_ccsid(LIBSSH2_SESSION *session,
|
|
libssh2_string_cache **cache,
|
|
unsigned short ccsid,
|
|
const char *string, ssize_t inlen,
|
|
size_t *outlen);
|
|
char * libssh2_to_ccsid(LIBSSH2_SESSION *session,
|
|
libssh2_string_cache **cache,
|
|
unsigned short ccsid,
|
|
const char *string, ssize_t inlen,
|
|
size_t *outlen);
|
|
|
|
where:
|
|
session is a libssh2 session used for memory allocation.
|
|
cache is the address of a string cache.
|
|
ccsid is the external (i.e.: non libssh2) coded character set id.
|
|
65535 means no conversion and 0 means the current job's CCSID.
|
|
string is the string to convert.
|
|
inlen is the source string length in bytes: set to -1 if
|
|
null-terminated.
|
|
outlen if not NULL, is the address of a variable that will receive
|
|
the transcoded string length upon return.
|
|
|
|
libssh2_from_ccsid() transcodes the string from the given CCSID to libssh2
|
|
internal encoding (UTF-8). It is intended to be used to convert API input
|
|
parameters.
|
|
libssh2_to_ccsid() transcodes the string from libssh2 internal encoding
|
|
(UTF-8) to the given CCSID. This has been implemented to get standard API
|
|
string results in a program's native encoding.
|
|
|
|
Both these functions return a pointer to the null-terminated converted string,
|
|
or NULL if an error occurred. In addition, the variable pointed by outlen
|
|
receives the effective byte length of the (cached) translated string, or -1
|
|
in case of error.
|
|
|
|
|
|
|
|
ILE/RPG support:
|
|
|
|
Since 95% of the OS/400 programmers use ILE/RPG exclusively, a definition
|
|
/INCLUDE member is provided for this language. To include libssh2
|
|
definitions in an ILE/RPG module, line
|
|
|
|
h bnddir('LIBSSH2/LIBSSH2')
|
|
|
|
must figure in the program header, and line
|
|
|
|
d/include libssh2/libssh2rpg,libssh2
|
|
|
|
in the global data section of the module's source code.
|
|
If required, members ssh2_sftp, ssh2_pkey and ssh2_ccsid may also be included.
|
|
|
|
For IFS source compilations, include members are located in directory
|
|
/libssh2/include/libssh2rpg and have their original names retained.
|
|
|
|
ILE/RPG lacks a serious macro preprocessor, thus C macros requiring this
|
|
feature have not been translated. However, function-like C macros have been
|
|
implemented as procedures and therefore supported in ILE/RPG.
|