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