Debian Codegraph @

os400/README400

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