-
Notifications
You must be signed in to change notification settings - Fork 0
/
$README.txt
204 lines (163 loc) · 9.63 KB
/
$README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
SQLITE 3.8.7 for z/OS
=====================
Sqlite is a self-contained, server-less, zero-configuration,
transactional SQL database engine. This is the standard sqlite library
which is available on many UNIX and Linux systems. The code was compiled
with almost no changes. The code is dependent on z/OS UNIX System
Services. The original code supports EBCDIC in addition to the normal
ASCII. This distribution has been compiled to support EBCDIC characters
and IEEE (BFP) floating point numbers. This latter is important because
most other z/OS languages use the historical HFP floating point.
At present, the code only has C language bindings on z/OS. There is a
"shim" or "stub" HLASM interface program which can be called from COBOL
or PL/I to access the C subroutines. It is named SQLITE3A. The
parameters passed into this routine are the same ones as documented in
the sqlite C API, except that the first parameter is a C style
null-delimited character string which is the name of the C subroutine to
be invoked. In COBOL, this is a Z'...' character string. The COBSQLTE
and PLISQLTE members are the COBOL COPY book and PL/I %INCLUDE members
which define COBOL or PL/I variables which contain these strings. In the
case of COBOL, the underscore characters shown in the C API names are
replace by a dash because an underscore is not valid in a COBOL data
name. The variable names are in upper case, but the values are in lower
case, due to the fact that the C subroutine names are in lower case.
Sqlite 3.8.7 is documented at http://sqlite.org, and this code runs as
described there. Therefore, no futher documentation is supplied at
present. When the COBOL and PL/I bindings are done, those will be
documented here.
This document does _not_ attempt to teach you how to use sqlite. It
assumes you already know how to use it, or can learn it yourself. It
does attempt to explain how to use it on z/OS by showing some COBOL and
PL/I examples. If you have a C license, I strongly suggest writing your
code in C. It will be more understandable to most.
Wish list items.
----------------
1. At present, the file which contains the sqlite database must reside
in a UNIX subdirectory. This means that the user of sqlite must have
an z/OS UNIX identity. I would like to be able to use a VSAM Linear
Dataset for storing the sqlite data at some time. Mainly due to the
number of shops which have not really embraced z/OS UNIX. This may
be possible using a "shim" sqlite VFS as documented here:
http://sqlite.org/vfs.html which would use a VSAM LDS as the backing
store for a sqlite in-memory data base.
2. Write a REXX interface.
3. Write a batch program based on the sqlite3 UNIX command. This would
allow SQL commands to be run in a step in a batch job.
4. JDBC for Java access.
Members in this library:
------------------------
- $README - This member. The README in markdown format.
- ASMACL - The JCL to compile and link the SQLITE3A assembler program.
- COBSQLTE - The COBOL copy book which defines various SQLITE3 related
variables and initializes them. The member contains a fair
number of comments on how to use SQLITE3A in a COBOL
program to invoke each of the 204(!) different sqlite
subroutines.
- COBTEST1 - The JCL to run the TESTCOB1 program.
- COBTEST2 - The JCL to run the TESTCOB2 program.
- IGYWCL - The JCL to compile and link the TESTCOB1 program.
- LINK - The JCL to link the SQLITE3 object code into a LINKLIB.
This composite links in the C and LE library subroutines.
- LINKLIB - XMIT copy of the SQL384.LINKLIB library containing the
z/OS batch executable programs: SQLITE3A, TESTCOB1, and
TESTCOB2.
- PAXFULL - This is a compressed pax archive for the entire SQLITE3
application, Including all source code and make
information.
- PAXRUN - This is a compressed pax archive containing only the files
needed to use SQLITE. This is really all you need if you
want to develop C language programs which use SQLITE. This
is not needed for COBOL or HLASM programs.
- PLICB - The JCL to compile a PL/I program.
- PLISQLTE - The PL/I %INCLUDE member to define and initialize a number
of variables to ease the use of SQLITE3A.
- SQLITE3A - LE enabled HLASM subroutine which presents an API to the
SQLITE3 C subroutines which is designed for use by COBOL or
PL/I code. It is composite (statically) bound with the C
object code.
This code has not been fully tested yet and may contain
errors.
- SQLITE3O - The object code for SQLITE to be bound into the
application. This was compiled on z/OS 1.13, but the C
compiler options were for compatibility with z/OS 1.11 or
higher.
- SQLITE3S - This is a UNIX "shared object", aka DLL, containing the
sqlite3 run time. This should be usable by anything which
can use DLLs, such as C code, instead of statically binding
the SQLITE3O object code into the program object. This
should be binary copied into the proper UNIX subdirectory
and named libsqlite3.so. This subdirectory needs to be
specified in the LIBPATH environment variable.
A UNIX copy command might be:
cp -B "//'this.pds(SQLITE3S)'" /some/lib/libsqlite3.so
- SQLITE3X - This is a UNIX DLL "side deck" used by the program binder
for dynamic resolution of names in the libsqlite3.so DLL.
A UNIX copy might might be:
cp -B "//'this.pds(SQLITE3X)'" /some/directory/libsqlite3.x
- TESTCOB1 - Example Enterprise COBOL program. It is very basic. It
uses the SQLITE3A stub to invoke SQLITE3 operations.
If you look at this, you will realize that I am very
"wordy" and am definitely not an advanced COBOL programmer.
- TESTCOB2 - Example Enterprise COBOL program. It is very basic.
It's main example is of how to retrieve a double
precision floating point number, COMP-2, from an
sqlite data base, converting it from BFP to HFP format.
The table is defined like:
CREATE TABLE xz (int INTEGER, fd DOUBLE);
This table can be created and loaded from a z/OS UNIX shell
prompt using the "sqlite3" UNIX command.
From my testing, it appears that sqlite, unlike most other
RDMS systems is case sensitive for the names of objects
such as columns and tables.
- TESTDB - A pax archive which contains the testdb.sqlite3 UNIX file
used by the TESTCOB2 program. This needs to be restored
to a subdirectory (/tmp in the example code). This can be
done with a UNIX command sequence such as:
cd /tmp
pax -rzf "//sqlite38.cntl(testdb)"
- TSTPLI1 - Example Enterprise PL/I program. It is very basic.
It is functionally equivalent to TESTCOB1.
This is not working at present.
I don't normally program in PL/I because I have never
worked in a shop which used it.
- UNPAX - The JCL needed to unwind either the PAXFULL or PAXRUN
member into a z/OS UNIX subdirectory.
Notes on the SQLITE3A interface program.
----------------------------------------
Notes on how to use SQLITE3A with COBOL.
----------------------------------------
1. One major oddity which can be quite confusing is that the C language
calling sequence is quite different from the normal COBOL calling
sequence. This difference is why many of the parameters being passed
to sqlite3 _must_ be BY VALUE instead of BY REFERENCE. In particular
things such as integers (COMP-?) and doubles must be passed BY VALUE.
Character strings are passed BY REFERENCE, but generally require that
they be terminated with by LOW-VALUES byte. In modern COBOLs, this
type of string can be initialized using the Z'value' construct.
2. When reading the C API documentation, the main thing to remember is
that when you see a varible prefixed with an ampersand, you need to
pass it BY REFERENCE. If you see a variable suffixed with an
asterisk, this indicates that the variable name in COBOL needs to be
defined as USAGE POINTER. This is also passed BY VALUE.
3. Another critical point is that when you see a function return an
"int", which is a 32 bit integer, or a name prefixed by an asterisk,
you receive these into a COBOL variable by using the phrase RETURNING
cobol-var-name. All other types of returned variables, such as
double floating point, are received by inserting a BY REFERENCE
phrase as the second parameter in the CALL verb's USING clause.
Please review TESTCOB2 for an example.
4. Unlike most z/OS languages, sqlite stores floating point numbers in
IEEE 754 format. On the z, this is called a BFP or Binary Floating
Point number. After retrieving a BFP number from sqlite, you need to
call the function "CONVERT-BFP-TO-HFP". Likewise, before sending a
value to sqlite, you need to convert it to BFP by calling the
"CONVERT-HFP-TO-BFP" function. The former is shown in the TESTCOB2
example. My suggestion is to define BFP number in your COBOL as
COMP-2 variables, perhaps suffixed with -BFP. Use COMP-2 for your
COBOL floating point number also, not COMP-1. Both of these formats
use an 8 bytes for storage.
Notes on how to use SQLITE3A with PL/I.
---------------------------------------
Note: This member is in "markdown" compatible format. For more
information on markdown, go to
http://daringfireball.net/projects/markdown/