| |
| 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. |