1
2Implementation notes:
3
4  This is a true OS/400 implementation, not a PASE implementation (for PASE,
5use AIX implementation).
6
7It uses ASCII as internal character set. This has been accomplished using the
8QADRT library and include files, a C and system procedures ASCII wrapper
9library. See IBM QADRT description for more information.
10  This results in libssh2 being an ASCII library: any function string
11argument is taken/returned in ASCII and a C/C++ calling program built around
12QADRT may use libssh2 functions as on any other platform.
13  QADRT does not define ASCII wrappers for all C/system procedures: an
14additional module (os400sys.c) define some more of them, that are used by
15libssh2 and that QADRT left out.
16  Since standard library entry points expect and return ASCII character strings,
17additional procedures are provided for string transcoding (see below). No
18wrappers to standard procedures are provided: however, nested calls to
19transcoding procedures may be used.
20
21Crypto API is provided by the IBM QC3 API library. It supports RSA, but not DSA.
22
23
24  Standard compilation environment does support neither autotools nor make;
25in fact, very few common utilities are available. As a consequence, the
26libssh2_config.h has been coded manually and the compilation scripts are
27a set of shell scripts stored in subdirectory os400.
28
29  The test environment is currently not supported on OS/400.
30
31
32
33Compiling on OS/400:
34
35  These instructions target people who knows about OS/400, compiling, IFS and
36archive extraction. Do not ask questions about these subjects if you're not
37familiar with.
38
39_ As a prerequisite, QADRT development environment must be installed.
40_ Install the libssh2 sources directory in IFS.
41_ Enter shell (QSH)
42_ Change current directory to the libssh2 sources installation directory
43_ Change current directory to os400
44_ Edit file iniscript.sh. You may want to change tunable configuration
45  parameters, like debug info generation, optimisation level, listing option,
46  target library, zlib availability and location, etc.
47_ Copy any file in the current directory to makelog (i.e.:
48  cp initscript.sh makelog): this is intended to create the makelog file with
49  an ASCII CCSID!
50_ Enter the command "sh make.sh > makelog 2>&1'
51_ Examine the makelog file to check for compilation errors.
52
53  Leaving file initscript.sh unchanged, this will produce the following OS/400
54objects:
55_ Library LIBSSH2. All other objects will be stored in this library.
56_ Modules for all libssh2 units.
57_ Binding directory LIBSSH2_A, to be used at calling program link time for
58  statically binding the modules (specify BNDSRVPGM(QADRTTS) when creating a
59  program using LIBSSH2_A. Also give access to the zlib BNDDIR/SRVPGM if
60  libssh2 is compiled with zlib).
61_ Service program LIBSSH2.<soname>, where <soname> is extracted from the
62  src/Makefile.am VERSION variable. To be used at calling program run-time
63  when this program has dynamically bound libssh2 at link time.
64_ Binding directory LIBSSH2. To be used to dynamically bind libssh2 when
65  linking a calling program.
66_ Source file H. It contains all the include members needed to compile a C/C++
67  module using libssh2.
68_ LIBSSH2, SSH2_PKEY, SSH2_SFTP members in file H. These are the C/C++ header
69  files. Original fames have been mangled to fit member name allowed syntax.
70_ Source file LIBSSH2RPG. It contains all the ILE/RPG /INCLUDE members
71  needed to compile an ILE/RPG program calling libssh2 procedures.
72_ LIBSSH2, SSH2_PKEY, SSH2_SFTP members in file LIBSSH2RPG. These are
73  ILE/RPG translations of the corresponding C header files.
74
75
76
77Special programming consideration:
78
79QADRT being used, the following points must be considered:
80_ If static binding is used, service program QADRTTS must be linked too.
81_ Likewise, if libssh2 has been compiled with zlib support, access to the
82  zlib objects must be provided at link time.
83_ The EBCDIC CCSID used by QADRT is 37 by default, NOT THE JOB'S CCSID. If
84  another EBCDIC CCSID is required, it must be set via a locale through a call
85  to setlocale_a (QADRT's setlocale() ASCII wrapper) with category LC_ALL or
86  LC_CTYPE, or by setting environment variable QADRT_ENV_LOCALE to the locale
87  object path before executing the program.
88_ Do not use original source include files unless you know what you are doing.
89  Use the installed members instead (in /QSYS.LIB/LIBSSH2.LIB/H.FILE).
90
91
92
93String transcoding support:
94
95  To help passing arbitrarily encoded string arguments and/or receiving string
96values from/to the libssh2 API, three non-standard additional procedures are
97provided. They use a session pointer and a "string cache" pointer.
98  Each time a string is transcoded, it is cached in the given cache. It is
99the responsibility of the caller to release the cache when its associted strings
100are no longer needed. These procedures and the string cache type are defined
101in a new libssh2_ccsid.h header file.
102  To create a string cache, use:
103
104#include <libssh2_ccsid.h>
105libssh2_string_cache *  cache = NULL;
106
107  To release all strings in a cache, call:
108
109libssh2_release_string_cache(session, &cache);
110
111  The transcoding procedures are:
112
113char * libssh2_from_ccsid(LIBSSH2_SESSION *session,
114                          libssh2_string_cache **cache,
115                          unsigned short ccsid,
116                          const char *string, ssize_t inlen,
117                          size_t *outlen);
118char * libssh2_to_ccsid(LIBSSH2_SESSION *session,
119                        libssh2_string_cache **cache,
120                        unsigned short ccsid,
121                        const char *string, ssize_t inlen,
122                        size_t *outlen);
123
124where:
125    session      is a libssh2 session used for memory allocation.
126    cache        is the address of a string cache.
127    ccsid        is the external (i.e.: non libssh2) coded character set id.
128                 65535 means no conversion and 0 means the current job's CCSID.
129    string       is the string to convert.
130    inlen        is the source string length in bytes: set to -1 if
131                 null-terminated.
132    outlen       if not NULL, is the address of a variable that will receive
133                 the transcoded string length upon return.
134
135  libssh2_from_ccsid() transcodes the string from the given CCSID to libssh2
136internal encoding (UTF-8). It is intended to be used to convert API input
137parameters.
138  libssh2_to_ccsid() transcodes the string from libssh2 internal encoding
139(UTF-8) to the given CCSID. This has been implemented to get standard API
140string results in a program's native encoding.
141
142  Both these functions return a pointer to the null-terminated converted string,
143or NULL if an error occurred. In addition, the variable pointed by outlen
144receives the effective byte length of the (cached) translated string, or -1
145in case of error.
146
147
148
149ILE/RPG support:
150
151  Since 95% of the OS/400 programmers use ILE/RPG exclusively, a definition
152  /INCLUDE member is provided for this language. To include libssh2
153  definitions in an ILE/RPG module, line
154
155     h bnddir('LIBSSH2/LIBSSH2')
156
157must figure in the program header, and line
158
159     d/include libssh2/libssh2rpg,libssh2
160
161in the global data section of the module's source code.
162If required, members ssh2_sftp, ssh2_pkey and ssh2_ccsid may also be included.
163
164For IFS source compilations, include members are located in directory
165/libssh2/include/libssh2rpg and have their original names retained.
166
167ILE/RPG lacks a serious macro preprocessor, thus C macros requiring this
168feature have not been translated. However, function-like C macros have been
169implemented as procedures and therefore supported in ILE/RPG.
170