Sie sind auf Seite 1von 26

adapya Adabas Api for Python

adapya 0.7
September 1, 2008

Table of Contents
1 What is adapya ? ...........................................................................................3
2 adapya License .............................................................................................3
3 Change History .............................................................................................4
4 Setting up an Execution Environment for MS-Windows ...........................................4
4.1 Prerequisites ............................................................................................4
4.2 Installation of adapya ................................................................................5
4.2.1 Windows PYTHONPATH installation .......................................................5
4.2.2 Windows Standard Installation.............................................................5
4.2.3 Unix/Linux PYTHONPATH Installation ....................................................6
4.2.4 Installation of adapya-v.r.l.zip with easy_install.....................................6
5 Using the Adabas API ......................................................................................7
5.1 Simple ACBX Example..................................................................................7
5.1.1 Adabasx Objects ................................................................................8
5.1.2 String Buffers ....................................................................................9
5.1.3 Storing a Record ................................................................................10
5.1.4 Reading a Record...............................................................................10
5.1.5 Backing-out the Transaction ................................................................10
5.1.6 Closing the User session .....................................................................10
5.1.7 Response Code Checking vs. Exception Handling ...................................10
5.2 Further Details of adapya............................................................................11
5.2.1 Read/Write Buffers with Abuf ..............................................................11
5.2.2 Working with Structures with Datamap .................................................12
5.3 LOB Demo Center Sample Web Application......................................................13
5.3.1 Configuration of the Apache http.conf file (example): .............................15
5.3.2 Configuration of Adabas and Net-Work .................................................15
5.4 UDHR Browser ...........................................................................................17
5.4.1 Configuration of the Apache http.conf file (example): .............................18
5.4.2 UDHR text stored as LOB or MU field ....................................................18
5.4.3 Storing from the NLTK Corpora ............................................................18
5.4.4 Configuring the scripts readudhr/readudhr2.py ......................................19
6 Event Replication for Adabas............................................................................20
6.1 Additional Prerequisites ..............................................................................20
6.2 outq.py Reptor Output Queue Client .............................................................20
6.3 inq.py Reptor Input Queue Client .................................................................21

Software AG 2008

Company Confidential

Page 1/26

Adabas Api for Python

adapya 0.7

September 1, 2008

6.4 Demo Application Employee Telephone List ......................................................22


6.4.1 Reptor Parameters .............................................................................22
6.4.2 Configuration ....................................................................................23
6.4.3 Intial-State Request for Selected Records .............................................23
6.4.4 Trace of Client Processing a Record ......................................................23
6.4.5 Reading the Replicated File on the Target Database ...............................24
6.4.6 Web Application Employee Telephone List...........................................25

Software AG 2004-2008

Page 2/26

Adabas Api for Python

adapya 0.7

September 1, 2008

1 What is adapya ?
With adapya you can access Adabas databases from Python programs using the Adabas API.
It comes with sample programs to show its use and demonstrates new Adabas features like reading
and storing of large binary objects using the extended Adabas API (ACBX).

Adabas is a commercial database system that runs on Windows, Unix and mainframe systems.
For more information see
http://en.wikipedia.org/wiki/Adabas and
http://www.softwareag.com/corporate/products/adabas/default.asp
in the download area you may also find an Adabas community version for Windows.
Here is the Adabas product documentation http://documentation.softwareag.com/adabas/

Python is a scripting language that allows rapid prototyping, object-oriented or functional style
programming. It is open source and is used in a large number of projects.
Note:

adapya does not implement a SQL interface as defined with the


Python DBAPI.
You may implement Adabas DBAPI access with the product ADABAS SQL
Gateway via ODBC interface.
adapya requires a good knowledge of the Adabas API.

adapya is a pure Python package: it does not require compilation of extensions. It should work on
all platforms where CPython and Adabas are available. It has been tested on Windows, Solaris and
z/Linux. It can access local Adabas databases and with the product NET-WORK remote Adabas
databases on all platforms including mainframe (z/OS, VSE, BS2000).
Prerequisite for adapya is Python version 2.5, or Python version 2.3 and 2.4 where it requires the
extra ctypes package.
adapya can be downloaded from
http://tech.forums.softwareag.com/viewforum.php?f=171&C=11

2 adapya License
Copyright 2004-2008 Software AG
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Software AG 2004-2008

Page 3/26

Adabas Api for Python

adapya 0.7

September 1, 2008

3 Change History
adapya 0.7 is the first public release.

4 Setting up an Execution Environment for MS-Windows


4.1 Prerequisites
1. Install Adabas (ADA OS V6.1 or higher)
or alternatively
Net-Work for Windows for remote Adabas access (NET-WORK WCP V7.3, or WCL V1.1.2.3 or
higher) and on mainframe ADA V8.1 and Net-Work V6.1.
Older versions of Adabas or NET-WORK WCP can be used but they do not support extended
ACB calls (ACBX) and LOB fields.

2. Python V2.3, V2.4 and V2.5 are supported.


If you have no Python on the system it is recommended to use Python V2.5 with the
Windows Python installer downloaded from
http://www.python.org/download/

3. -you may skip this step when using easy_install since it takes care of prerequisites -ctypes (required) for Python versions below 2.5 - it is already included in Python 2.5).
Download Win32 installer or tar file from
http://sourceforge.net/projects/ctypes/

4. (Optional for LOB and other web demo programs) Install additional software.
For Windows you may select the installers depending on the Python version.
a. apache (optional). Used for the demo web applications.
http://httpd.apache.org/download.cgi
b. mod_python (optional). Used for the demo web applications.
http://www.internet.bs/apache.org/httpd/modpython/
c. PIL - Python Image Library (optional). Used with LOB Demo Center application
http://www.effbot.org/zone/pil-index.htm
Note:

PIL and mod_python packages have Python extensions (i.e. separately compiled
dynamic loadable modules). They only work with the Python version that they're
compiled with. Make sure that you select the binary for your Python version.
As of August 2008 current versions of the components are: python-2.5.2, ctypes1.0.2, apache-2.2.9 or apache-2.0.63, mod_python-3.3.1, PIL-1.1.6.

We have tested on WinXP with:


python-2.3.5, ctypes-0.9.9.6, apache-2.0.55, mod_python-3.2.8, PIL-1.1.5.
Python-2.5.1, apache-2.0.61 (for mod_python at least apache-2.0.59 required),
mod_python-3.3.1, PIL-1.1.5
Note: Users not familiar with Python are recommended to read the Python Tutorial available with
function key F1 in the IDLE Python GUI or at
http://docs.python.org/tut/tut.html

Software AG 2004-2008

Page 4/26

Adabas Api for Python

adapya 0.7

September 1, 2008

For the very prudent there are some introductory Video Tutorials at
http://showmedo.com/videos/series?name=pythonOzsvaldPyNewbieSeries

4.2 Installation of adapya


On Windows installation can be done in 2 ways (PYTHONPATH and standard)
On Unix/Linux systems only the PYTHONPATH installation was tested.
As an alternative, an easy_install installation may be done.

4.2.1 Windows PYTHONPATH installation


The zip file adapya-v.r.l.zip contains a directory adabas/*

Unzip adapya-v.r.l.zip to a convenient location e.g. "C:\ADA\Python" maintaining the


subdirectory structure

Create a file py25.bat with the following content, adapt it to your environment and save it
to a directory that is in the system PATH:
REM Python installation directory
set PY=C:\Python25
REM Adabas Python directory: Python will pick up Adabas python
modules
set PYTHONPATH=C:\ada\python\adapya-v.r.l
REM add paths for Python runtime if not done at Python installation
PATH=%PY%;%PY%\DLLs;%PATH%
REM cd to Adabas demo files directory
cd %PYTHONPATH%\adabas\demo

When the Python interpreter is started it evaluates the environment variable PYTHONPATH and
adds any directories listed to its search path for modules.
Check successful installation with dblist.py to show the status of active Adabas database <dbid>
python dblist.py d <dbid>

4.2.2 Windows Standard Installation


The zip file contains a directory adabas/*

Unzip adapya-v.r.l.zip to a temp folder e.g. "C:\temp" maintaining the subdirectory


structure

Change directory to that temp folder e.g.


cd C:\temp\adapya-v.r.l

Run normal python packages installer


python setup.py install

Check successful installation with doing an open to an active Adabas database <dbid>
python %PY%\scripts\dblist.py d <dbid>

Software AG 2004-2008

Page 5/26

Adabas Api for Python

adapya 0.7

September 1, 2008

4.2.3 Unix/Linux PYTHONPATH Installation


The PYTHONPATH environment variable defines an extra search path for python modules. If the
path to the Adabas Python directory is added to the variable it is included in the search.
cd /FS/disk01

# root directory

gunzip -c adapya-0.7.0.tar.gz | tar xf - # unpack to adapya-0.7.0


setenv APYDIR "/FS/disk01/adapya-0.7.0"
setenv PYTHONPATH $APYDIR':'$PYTHONPATH

# add APYDIR to PYTHONPATH

cd $APYDIR/adabas/demo

# go to demo directory

python dblist.py d 12

# show status of database 12

4.2.4 Installation of adapya-v.r.l.zip with easy_install


This will also install the CTYPES prerequisite if not yet present
easy_install -Z <http-url-or-zipfile>
For example with Python 2.4, if the Python installation directory was at C:\Python24\ on Windows
this will store the package under the directory
C:\Python24\Lib\site-packages\adapya-0.7.0-py2.4.egg\
Note: easy_install is a package installer that needs to be installed once with ez_setup.py. For more
information see http://peak.telecommunity.com/DevCenter/EasyInstall

If your local internet is protected by a http proxy you may need to set the
HTTP_PROXY environment variable before running easy_install (CYGWIN):
SET HTTP_PROXY=http://<httpprox.your-local.net>:<httpprox-port>
Not setting it may result in timing out operations.

Software AG 2004-2008

Page 6/26

Adabas Api for Python

adapya 0.7

September 1, 2008

5 Using the Adabas API


5.1 Simple ACBX Example
The following program inserts a record into the Employees demo file, reads it and backs it out.
File: adabas/demo/n1_acbx.py
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

"""Store and Read record then BT and CL"""


import adabas
import adabas.dump
from adabas.api import *
from adabas.datamap import *
FNR=11;DBID=8
FB='AA,8,A.'

# Employees

c1=Adabasx(fbl=64,rbl=64)

# allocate set of buffers ACBX,


# abd+format and record buffer

c1.dumpcb=c1.dumpfb=c1.dumprb=c1.dumpbefore=1 # print buffers


try:
# print Adabas call buffers before and after
c1.cb.dbid=DBID
# for ACBX; c1.dbid=DBID for ACB
c1.cb.fnr=FNR
# set control block fields
c1.open(mode=UPD)

# issue OP

c1.cb.cid='abcd'
c1.cb.isn=0
c1.fb.value=FB
c1.rb.value='ABCDEFGE'
c1.rabd.send=8

# put data into format buffer


# ..
record buffer
# set send size for record buffer

c1.store()

# issue N1

# c1.rb.value='4'*8
c1.rabd.send=0

# don't initialize rb
# reset send size !

c1.get()

# issue L1

print repr(c1.rb.value), 'returned size', c1.rabd.recv


c1.bt()
c1.close()

# issue backout
# issue close

except DatabaseError, (line, apa):


print line
dump.dump(apa.acbx, header='Control Block')
raise

Some explanations in the following sections. You may also look into source adabas/api.py

Software AG 2004-2008

Page 7/26

Adabas Api for Python

adapya 0.7

September 1, 2008

5.1.1 Adabasx Objects


Adabas requests are based on a set of parameters: a control block and a number of data buffers
that are shipped with the Adabas call. In Python such a set of call parameters is mapped to a
Adabasx object
10 c1=Adabasx(fbl=64,rbl=64)
c1 is an instance of the Adabasx class. It is an extented Adabas control block and set of buffers
that will be used in an Adabas call. The Adabasx class and Adabas class for the ACB are defined in
adabas/api.py.
The ACBX control block fields are defined in the Acbx datamap class that allows access to the buffer
per attribute name similar to the struct in C or DSECT in assembler.
class Acbx(Datamap):
def __init__(self, **kw):
fields=(
Uint1( 'typ'),
Char(
'rsv1'),
String( 'ver', 2),
Int2(
'len'),
String( 'cmd', 2),
Int2(
'rsv2'),
Int2(
'rsp'),
String( 'cid', 4),
Uint4( 'dbid'),
Uint4( 'fnr'),
Uint8( 'isn'),
Uint8( 'isl'),
Uint8( 'isq'),
Char(
'op1'),
Char(
'op2'),
Char(
'op3'),
Char(
'op4'),
Char(
'op5'),
Char(
'op6'),
Char(
'op7'),
Char(
'op8'),
String( 'ad1', 8),
Uint4( 'ad2'),
String( 'ad3', 8),
String( 'ad4', 8),
String( 'ad5', 8),
String( 'ad6', 8),
String( 'rsv3', 4),
Uint8( 'erra'),
String( 'errb', 2),
# Field name or offset
Uint2( 'errc'),
# Subcode
Char(
'errd'),
# Buffer type
Bytes( 'erre', 1),
Uint2( 'errf'),
# Buffer number
Uint2( 'subr'),
Uint2( 'subs'),
String( 'subt', 4),
Uint8( 'lcmp'),
Uint8( 'ldec'),
Uint8( 'cmdt'),
Bytes( 'usr', 16),
Bytes( 'rsv4', 24)
)
Datamap.__init__(self, 'Acbx', *fields, **kw)

Software AG 2004-2008

Page 8/26

Adabas Api for Python

adapya 0.7

September 1, 2008

When creating the Adabasx object Python calls the __init__() method defined in the Adabas class.
The method does the following
a) create a buffer of length ACBXLEN and assign it to the attribute acbx of the Adabasx instance:
self.acbx=Abuf(ACBXLEN)
b) define a mapping of Acbx fields to the buffer
self.cb=Acbx(buffer=self.acbx)
Statement 18 assigns the file number 11 to c1.cb.fnr This is the file number field in the Adabas
control block cb used in the Adabasx instance c1.
18

c1.cb.fnr=11

# set control block fields

Here we make a hex print of the extended control block


43

dump.dump(c1.acbx, header='Control Block')

5.1.2 String Buffers


One related set of buffers may be allocated when creating the Adabasx instance with specifying
individual buffer lengths: fbl, rbl, sbl, vbl, ibl.
Additional buffers may be added to the Adabasx instance with addbuffer(): e.g.
c1.addbuffer('I', buffer)
Note:

Python's built-in string type can also be used as a buffer with the Adabas call. However,
since strings are immutable they could only be used for read-only buffers like format or
search buffers.

Adabas Python defines a buffer class Abuf(size) which is backed by the CTYPES character buffer.
Abuf() defines slice and fileIO operations and is used as read/write buffer throughout the code (see
below).
Internally, Python has no concept to store data of different variables physically together as in a
assembler DSECT or C struct. But with pack() and unpack() functions from the built-in Python struct
module variables can be mapped to a buffer (or string).
With the adabas/datamap module such a mapping may be defined equivalent to C structs (see
below).
In the c1 initialization Adabasx.__init__() the following 2 statements create a ACBX
buffer c1.acbx and overlay this buffer with the Acbx datamap:
self.acbx=Abuf(ACBXLEN)
self.cb=Acbx(buffer=self.acbx)
c1.cb.fnr is then file number at ACBXFNR in the ACBX buffer

Software AG 2004-2008

Page 9/26

Adabas Api for Python

adapya 0.7

September 1, 2008

Opening a User Session


20
c1.open(mode=UPD)
# issue OP
c1 calls the open method of the Adabasx class which issues an Adabas OP command. Note that
before the call dbid is set in the ACBX.

5.1.3 Storing a Record


23
24
25
26
27
28
29

c1.cb.cid='abcd'
c1.cb.isn=0
c1.fb.value=FB
c1.rb.value='ABCDEFGE'
c1.rabd.send=8

# put data into format buffer


# ..
record buffer
# set send size for record buffer

c1.store()

# issue N1

23
c1.cb.cid='abcd'
Command id is set with a 4 byte string
26
c1.rb.value='ABCDEFGE'
c1.rb is the record buffer. Make sure that you assign a value with c1.rb.value or with the slice
operator
c1.rb[0:8]='ABCDEFGE'
27
c1.rabd.send=8
# set send size for record buffer
With ACBX the size of the buffers to send must be set. c1.rabd is the record buffer ABD.

5.1.4 Reading a Record


31
32
33
34
35
36
37

# c1.rb.value='4'*8
c1.rabd.send=0

# don't initialize rb
# reset send size !

c1.get()

# issue L1

print repr(c1.rb.value), 'returned size', c1.rabd.recv

5.1.5 Backing-out the Transaction


38

c1.bt()

# issue backout

5.1.6 Closing the User session


39

c1.close()

# issue close

5.1.7 Response Code Checking vs. Exception Handling


15 try:
41 except DatabaseError, (line, apa):

Software AG 2004-2008

Page 10/26

Adabas Api for Python

42
43
44

adapya 0.7

September 1, 2008

print line
dump.dump(apa.acbx, header='Control Block')
raise

The block within


try: and except:
contains several Adabas calls. Any Adabas response code will raise a DatabaseError
exception: No need to check the response code after each call.

5.2 Further Details of adapya


5.2.1 Read/Write Buffers with Abuf
Implemented in adabas/__init__.py
Read/write buffers are not directly available in Python only indirectly with I/O routines.
The adabas.Abuf class provides such a buffer. It is used for the Adabas control block and other
buffers.
>>> from adabas import Abuf

# Access Abuf class

>>> a=Abuf(8)

# Allocate buffer of 8 bytes

>>> a.value='Bell'

# store 'Bell' into buffer a

>>> a.raw
'bell\x00\x00\x00\x00'

# show contents of a

>>> a[0:8]
'bell\x00\x00\x00\x00'

# same in slice notation

>>> a[0:4]
'bell'

# extract part of buffer

>>> a[0]='W'
'Well\x00\x00\x00\x00'

# modify buffer at offset 0

>>> a.read(5)
'Well\x00'

# read() 5 bytes of the buffer

>>> a.read(5)
'\x00\x00\x00'

# read() next bytes (only 3 left)

>>> a.tell()
8

# inquire position

>>> a.seek(0)

# position to start of buffer

>>> a.write('Sun')
'Sunl\x00\x00\x00\x00'

# write first 3 characters

Software AG 2004-2008

Page 11/26

Adabas Api for Python

adapya 0.7

September 1, 2008

5.2.2 Working with Structures with Datamap


Implemented in adabas/datamap.py
The datamap module defines the Datamap class that allows to define structure within a byte buffer.
This is similar to a DSECT or C struct. This is being used for setting up the Adabas control block and
the other buffers.

5.2.2.1 Datamap Data Types


The following data types require a name and a length:
String
- alpha numeric string
Unicode
- Unicode string (in UTF-16, each character takes 2 bytes)
Bytes
- similar to String but hexadecimal contents
The other data types take only the name:
Char
- 1 byte character
Int1/2/4/8
- signed integer of 1, 2, 4 or 8 bytes
Uint1/2/4/8
- unsigned integer of 1, 2, 4 or 8 bytes
Float
- single precision float (IEEE format)
Double
- double precision float (IEEE format)

5.2.2.2 Basic Usage example


>>> from adabas.datamap import *
>>> dm=Datamap('mymap',
String('name',6),
Int2('age'))
>>> dm.getsize()
8
>>> a=Abuf(8)
>>> dm.buffer=a
>>> dm.name='Bell'
>>> dm.age=64

# use buffer a with datamap dm


# assign name
# assign age

>>> dm.dprint()
# print out values of datamap dm
mymap at offset X'0000'
name = "Bell"
age = 64
>>> dm.age
64
>>> dm.name
'Bell'

Software AG 2004-2008

# individual attribute access

Page 12/26

Adabas Api for Python

adapya 0.7

>>> dm.name='12345678'
>>> dm.name
'123456'

# silent truncation

>>> dm.name='1234
>>> dm.name
'1234'

# silent blank truncation on return

'

September 1, 2008

5.2.2.3 Example showing the different data types


p = Datamap( 'test_all_formats',
String( 'str8', 8),
Unicode('uni4', 4),
# unicode 4 chars = 8 bytes
Utf8(
'utf8', 8),
Bytes( 'byt4', 4),
Char(
'cha1'),
Int1(
'int1'),
Uint1( 'uin1'),
Int2(
'int2'),
Uint2( 'uin2'),
Int4(
'int4'),
Uint4( 'uin4', opt=T_STCK),
# Uint4 STCK
Int8(
'int8'),
Uint8( 'uin8', opt=T_STCK),
# Uint8 STCK
Float( 'flo4'),
Double( 'dou8'),

)
With Uint4 and Uint8 the additional option T_STCK indicates that the value is a timestamp value in
mainframe STCK format. This is evaluated with the dprint() function to print the timestamp in
readable ISO format.

5.3 LOB Demo Center Sample Web Application


The LOB Demo Center (LDC) is a sample web application that allows to show, store and retrieve
images with a web browser.
With the application you can

Select a database with the LDC file.

Show the database status

List the records of the LDC file in text or thumbnail view

Select individual records and show the stored image

Select a predefined set of images for display and storage into the LDC file

Enter the URL of an image to display or store it into the LDC file

Software AG 2004-2008

Page 13/26

Adabas Api for Python

adapya 0.7

September 1, 2008

The Lob Demo Center application requires Apache, mod_python and PIL.

Software AG 2004-2008

Page 14/26

Adabas Api for Python

adapya 0.7

September 1, 2008

5.3.1 Configuration of the Apache http.conf file (example):


LoadModule python_module modules/mod_python.so
Alias /ADALOBdemo
Alias /Images

"C:/ADA/WEB/LobDemoCenter"
"C:/ADA/WEB/LobDemoCenter/images"

<-

 map external alias to directory

<Directory "C:/ADA/WEB/LobDemoCenter">
- directory of the LobDemoCenter files
Options Indexes MultiViews
AllowOverride All
Order allow,deny
Allow from all
AddHandler mod_python .py
PythonHandler mod_python.publisher
PythonDebug On
PythonPath "sys.path+['c:/ADA/python/dev','C:/ADA/WEB/LobDemoCenter']"  optional
</Directory>

Adding extra paths to PythonPath for directories of python programs that have not been installed
with the Python installer setup.py

5.3.2 Configuration of Adabas and Net-Work


Minimum settings depend on the maximum size of a LOB being stored/read. For LOBs of up to 5
Mbytes

5.3.2.1 Adabas Mainframe


NAB = 1500
LU = 5500000
NISNHQ=5000

5.3.2.2 NET-WORK (WCP V6.1)


NAB=800
LU=5500000

5.3.2.3 Adabas Open Systems


LAB=6M
LWP=5M
LBP=10M
WORK size=20M

Software AG 2004-2008

Page 15/26

Adabas Api for Python

adapya 0.7

September 1, 2008

5.3.2.4 Loading the LobDemoCenter File on mainframe


Sample JCL loblob88_jcl.txt is in the fdt subdirectory of the LobDemoCenter directory (i.e.
./adabas/demo/LobDemoCenter/fdt/)
FDT of the LobDemoCenter file
ADACMP
ADACMP
ADACMP
ADACMP
ADACMP
ADACMP
ADACMP

COMPRESS NUMREC=0
FNDEF='01,A1,025,A,DE,NU'
FNDEF='01,A2,004,A,DE,NU'
FNDEF='01,A3,008,A'
FNDEF='01,L1,0,A,LB,NV,NB,NU'
FNDEF='01,L2,0,A,LA,NV'
FNDEF='01,X1,180,A,NU'

5.3.2.5 Loading the LobDemoCenter File on Windows


Sample JCL mf_loblob88_jcl.txt is in the fdt subdirectory of the LobDemoCenter directory (i.e.
./adabas/demo/LobDemoCenter/fdt/)
set ADA
set FDUFDT=win_lobdemo.fdt
rem adafdu db=<dbid> file=<base_file> lobfile=<lobfile>
adafdu file=88 lobfile=89

FDT of the LobDemoCenter file


01,A1,025,A,DE,NU
01,A2,004,A,DE,NU
01,A3,008,A
01,L1,0,A,LB,NV,NB,NU
01,L2,0,A,LA,NV
01,X1,180,A,NU

;filename w/o extension


;extension
;loblength as string
;lob
;thumbnail if jpeg or gif
;url of origin

5.3.2.6 LobDemoCenter Configuration File 'settings.py'


Basic configuration of the LobDemoCenter application is done in the settings.py file.
Here you should set the maximum buffer sizes, proxy configuration and selectable databases as
appropriate for you installation. The IMAGES variable defines the URLFILE2 drop-down selection of
images taken from the local directory ('file:') or remote locations ('http:').

Software AG 2004-2008

Page 16/26

Adabas Api for Python

adapya 0.7

September 1, 2008

5.4 UDHR Browser


The UDHR browser allows to browse the UN Declaration of Human Rights database that is stored in
an Adabas file.
This input data for this file is obtained from the UDHR corpora of the Natural Language Toolkit at
http://nltk.sourceforge.net/
This data is very useful for showing the internationalization features of Adabas. It provides text
samples in virutually all scripts/languages of the world.

The browser is implemented as a mod_python script. It can be called with e.g. the following URL
http://localhost/apps/readudhr2.py/browse
or with extra parameters
http://localhost/apps/readudhr2.py/browse?maxlines=10;dbid=12

Software AG 2004-2008

Page 17/26

Adabas Api for Python

adapya 0.7

September 1, 2008

5.4.1 Configuration of the Apache http.conf file (example):


The following configuration lines define
LoadModule mod_python.so must be loaded
Alias /apps and the underlying script directory where readudhr.py or readudhr2.py reside":
C:/ADA/WEB/apps
HTMLDIR for readudhr.html file
Defines the mod_python handler for this directory
LoadModule python_module modules/mod_python.so
Alias /apps "C:/ADA/WEB/apps"
<Directory "C:/ADA/WEB/apps">
Options Indexes MultiViews
AllowOverride All
Order allow,deny
Allow from all
AddHandler mod_python .py
PythonHandler mod_python.publisher
PythonDebug On
PythonPath "sys.path+['c:/ADA/python/dev']"
SetEnv HTMLDIR "C:/ADA/WEB/apps"
</Directory>

5.4.2 UDHR text stored as LOB or MU field


There are 2 choices of Adabas file
1. UDHR text stored in wide LOB field
win_adafdu_udhr.cmd, win_udhr.fdt, storeudhr.py, readudhr.py
2. UDHR text stored in wide MU field with default length
udhr2.fdt, storeudhr2.py, readudhr2.py
All resources are found in adabas/demo/udhr/ directory
Load the empty UDHR file in to a free file/database

5.4.3 Storing from the NLTK Corpora


The command line scripts storeudhr.py (LOB) or storeudhr2.py (MU field) extract the UDHR data
from the NLTK Corpora zip file and store it into the Adabas file.
Before running, update the script with the correct settings of the following variables:
FNR=47
DBID=12
ZF='C:/z/install/nltk/nltk-corpora-0.8.zip'

Software AG 2004-2008

Page 18/26

Adabas Api for Python

adapya 0.7

September 1, 2008

5.4.4 Configuring the scripts readudhr/readudhr2.py


Copy the readudhr.html and readudhr.py or readudhr.py to your APPS directory defined in the web
server configuration.
Before running, update the script with the correct settings of the following variables:
FNR=47
DBID=12

http://localhost/apps/readudhr.py?browse

Note that the following URL parameters could be specified when calling it from the browser:
dbid
fnr
maxlines
name

database id
file number of UDHR file
maximum number of lines to display
Name of language to start browsing from

Example:
http://localhost/apps/readudhr.py?browse?maxlines=100;dbid=12
Displaying individual texts is implemented with the select function:
http://localhost/apps/readudhr.py/select?isn=1
or
http://localhost/apps/readudhr.py/select?name=English

Software AG 2004-2008

Page 19/26

Adabas Api for Python

adapya 0.7

September 1, 2008

6 Event Replication for Adabas


The adapy contains an experimental API tothe mainframe Event Replicator for Adabas using EntireX
broker.
The Event Replication for Adabas (ARF) is an add-on product to Adabas that allows to replicate
database data to other systems. Client programs (also called target adapters) receive event
replication data through a messaging system like MQ series or EntireX Broker.
In the following the command line clients and the Emptel sample replication with Adabas to Adabas
replication via Entire X are described.

6.1 Additional Prerequisites


Install
EntireX V7.1 or higher
alternatively install the entirexminiruntime.exe
On Windows this file can be found in the EntireX/Etc/ folder. Optionally unzip the file
Control.zip in the EntireX/Etc/ folder. This zip file contains the EntireX control center GUI
program that allows to view and control the status of EntireX broker and its resources.

6.2 outq.py Reptor Output Queue Client


outq.py listens to the Reptor output queue and prints each Reptor message according to its
interpreted URB* blocks.
The program is terminated by CTRL-C or when some severe Broker return code occurs.
>outq.py -h
outq.py -- Reptor output queue reader
Reads messages from the Reptor output queue
via EntireX Broker ACI call interface
and prints the data
Usage: python [-O] outq.py [options]
-O

run optimzied, debug code not generated


do not display interpreded URB*

Options:
-h,
-b,
-c,
-n,
-s,
-u,
-t,

--help
--broker ..
--class ..
--name ..
--service ..
--userid ..
--trace ..

display this help


id of broker ETBxxxxx or hostname:port
server class
server name
service (Reptor output queue)
user id to be used
sum of trace flags
1 - dump buffers before Broker call
2 after call
4 - print broker calls
8 - detailed print of URB buffers

Example:
python outq.py -b ETB50019 -u MM -s MMSERV

Software AG 2004-2008

Page 20/26

Adabas Api for Python

adapya 0.7

September 1, 2008

6.3 inq.py Reptor Input Queue Client


inq.py sends input requests to the Reptor and terminates.
The following input requests are defined:

Status

Initial-state-request

Prior-transaction request

>inq.py
---- inq.py -- Reptor input queue writer ---Write messages to the Reptor input queue
via EntireX Broker ACI call interface
Usage: python inq.py [options]
Options:
-h, --help
-b, --brokerid ..
-c, --class ..
-n, --name ..
-s, --service ..
-u, --userid ..
-k, --token
-r, --rnam ..
-e, --arc ..

display this help


id of broker ETBxxxxx or hostname:port
server class
server name
service (Reptor input queue)
user id to be used
token
response destination name
architecture of input URB* and of data
is the integer of the sum of
0/1 - high/low order byte first
0/2 - ASCII/EBCDIC
0/4/8 - IBM390/VAX/IEEE floating point

-t, --trace ..

sum of trace flags


1 - dump buffers before Broker call
2 after call
4 - print broker calls
for type subscription status (STAT)
-p, --snam ..
subscription
-d, --dnam ..
destination
for
-p,
-d,
-q,

type Prior transaction request (TRAN)


--snam ..
subscription
--dnam ..
destination
--tseq ..
transaction sequence number

for
-a
-f
-i
-l
-v
-g
-w

type Initial-state request (INST)


--dbid ..
database id
--fnr ..
file number or fnr_list (see below)
--inam ..
initial-state name
--isnl ..
ISN or isn_list (see below)
--value
value_string for selection criteria
--acode ..
encoding of alpha values in value_string
--wcode ..
encoding of wide values in value_string
An encoding is specified as cpX with
X = ECS code page number, e.g. cp37 for
US EBCIDIC code page 37, or
as a name defined in ecscodec.py, e.g.
utf8 for ECS code page 4091)

fnr_list

list of files for which initial state


is to be requested
e.g. (1,2,3,4) requests it for files 1-4
no space can be within the parenthesises
otherwise it must be surrounded by double
quotes

isn_list

list of ISNs or ISN ranges surrounded by


parenthesis. e.g.
(1,2,3,4,10-1000,2001-2999,9999)
No spaces allowed unless list enclosed in
double quotes

Software AG 2004-2008

Page 21/26

Adabas Api for Python

value_string

adapya 0.7

September 1, 2008

value string matching the selection


criterion define in the INIITALSTATE
parameters. A sequence of values can be
specified by enclosing the comma separated
values with parenthesis. No spaces allowed
unless enclosed in double quotes. In
addition a sequence element may be also:
x'hexvalue' for a hexadecimal value
e'string'
for a string to be converted
to EBCDIC

Examples:
python inq.py -b ETB50019 -u MM -c REPTOR -n MMSERV -s IN1 -d OUT1
python inq.py -b ETB50019 --userid MM --class REPTOR --name MMSERV
--service IN1 -dnam OUT1
python inq.py -b ETB50019 --userid MM --class REPTOR --name MMSERV
--service IN1 --rnam OUT1 --token TOKTOK
--inam ICOLOR --dbid 12345 --fnr (1,2)
----- = file_list
python inq.py ... --isnl (1,2,3,11-20,25)
requests initial state for ISNs 1,2,3 11 thru 20 and 25
python inq.py ... --value (GR001,x'89AB',e'"ABC "') or alternatively
"(GR001,x'89AB',e'ABC ')"
with value being composed of 'GR001',x'89AB',x'C1C2C340'
python inq.py ... --value "A B " --arc 9 --acode cp1252 --wcode utf8

6.4 Demo Application Employee Telephone List


The demo application processes the replication for the Adabas example file EMPLOYEE.
In the Reptor definitions the format EMPLTEL defines a subset of the original EMPLOYEE fields. This
shows how to reduce overhead in only replicating required information or how to hide sensitive
information.

6.4.1 Reptor Parameters


ADARPD
ADARPD
ADARPD
ADARPD
ADARPD
*
ADARPD
ADARPD
ADARPD
ADARPD

SUBSCRIPTION NAME=EMPLOYEE
SACODE=819,SWCODE=4091,SARC=9
SDESTINATION='OUT1'
SFILE=11,SFDBID=10006
SGFORMATAI=EMPLTEL
GFORMAT NAME=EMPLTEL
GFB='AA,AC,AD,AE,'
GFB='AH,8,U,AL,'
GFB='AN,AM,AO,AP.'

Software AG 2004-2008

Fields extracted for Telephone List Webapp


PERSONNEL-ID FIRST-NAME MIDDLE LAST-NAME
BIRTH COUNTRY
AREA-CODE PHONE DEPT JOB-TITLE

Page 22/26

Adabas Api for Python

adapya 0.7

September 1, 2008

6.4.2 Configuration
The following lines configure the client program - see out1Config.py.
# define the mapping of data in record buffer to attributes
# of EmpTel class
empTelFormat='AA,AC,AD,AE,AH,8,U,AL,AN,AM,AO,AP.'
# create datamap object for Employees-Telephone-List
emp=Datamap('EmplTel',
String('personnel_id', 8),
String('firstname',
20),
String('m_initial',
20),
String('lastname',
20),
String('birth',
8),
String('country',
3),
String('areacode',
6),
String('phone',
15),
String('department',
6),
String('jobtitle',
25)
)
# define formats and mapping for each file specified in subscription
psf=ParmsSfile(sdbid=10006,sfnr=9,tdbid=12,tfnr=7,\
fb=empTelFormat,dmap=emp)
# define subscription with all its sfiles defined
psu=ParmsSubscription(subscription='EMPLOYEE',sversion='01',sfiles=[psf])
# define Reptor Broker parameters
pbs=ParmsBrokerService(\
broker_id='ETB50019',\
server_class='REPTOR',
server_name='MMSERV',
service='OUT1',
user_id='UEmplTel')

6.4.3 Intial-State Request for Selected Records


The following requests Initial-state for the EMPLOYEE file selecting records 20002000 through
20003999
>python inq.py --inam IEMPLAA --dbid 10006 --fnr 9
--value 2000200020003999
--acode cp819 --wcode utf8 --arc 9
--rnam OUT2 --token TOKTOTOK

6.4.4 Trace of Client Processing a Record


>python rcOut1.py
URBR -- initial state record fnr 9 isn 828
URBD(1) after image
0000 32303030 32393030 544F4D20 20202020
0010 20202020 20202020 20202020 20202020
1 identical line(s) suppressed
0030 44494C57 4F525448 20202020 20202020
0040 20202020 30303430 30323234 55534130
0050 31303120 20283231 39293436 342D3234
0060 32312020 4D474D54 31305345 43524554
0070 41525920 20202020 20202020 20202020
0080 202020

20002900TOM
DILWORTH
00400224USA
101 (219)464-2
21 MGMT10SECRE
ARY

Enter URBD handler: R A, isn 828


cmd=E1 op1/2= / dbid=12 fnr=7 rsp=113
cid=
isn=828 isl=0 isq=0
Note: Before Image not found ISN 828
cmd=N2 op1/2= / dbid=12 fnr=7 rsp=0
cid=
isn=828 isl=0 isq=0

Software AG 2004-2008

Page 23/26

Adabas Api for Python

adapya 0.7

September 1, 2008

Exit URBD handler: R A, isn 828/828, num recs 18


URBE -- end of transaction 0 for subscription EMPLOYEE
Enter URBE handler: EMPLOYEE tsnr 0, in TA 1, cnt 9
End Transaction 0 for subscription EMPLOYEE with 9 updates
cmd=ET op1/2= / dbid=12 fnr=7 rsp=0
cid=
isn=828 isl=0 isq=0
Exit URBE handler: EMPLOYEE, tsnr 0, in TA 0, cnt 9

6.4.5 Reading the Replicated File on the Target Database


>python EmpltelReadIsn.py
Read by ISN on Employees-Telephonelist file 7 on database 12
starting from ISN 0 for 1100 records
820 20002100 Forrest, Mona D.
USA 0101
821 20002200 Dekker, Sylvia Jennifer USA 0101
822 20002300 Smith, Elsa R.
USA 0101
823 20002400 Ferrari, Shirly Phyllis USA 0101
824 20002500 Alexander, Holly P.
USA 0101
825 20002600 Mcdonald, Rosa Jennifer USA 0101
826 20002700 Romerio, Virginia S.
USA 0101
827 20002800 Davenport, Ann Phyllis USA 0101
828 20002900 Dilworth, Tom
USA 0101
Sequential Read by ISN returned 9 record(s).

(312)824-9206
(213)183-1707
(213)793-6785
(415)822-9155
(608)793-6137
(316)409-2438
(301)738-5508
(415)538-7860
(219)464-2421

SALE40
TECH10
TECH10
SALE20
SALE20
SALE20
MGMT30
TECH10
MGMT10

0028-09-23
0026-03-05
0027-09-02
0034-12-31
0046-01-02
0056-07-16
0045-04-06
0048-12-25
0040-02-24

Secretary (*)
Dba
Programmer
Sales Person
Sales Person
Sales Person
Manager
Analyst
Secretary

(*) The full name and position are stored upper-case in the database and capitalized for display

Software AG 2004-2008

Page 24/26

Adabas Api for Python

adapya 0.7

September 1, 2008

6.4.6 Web Application Employee Telephone List


The Employee Telephone List web application is implemented by the function select() in module
emplist.py
It is executed as publishing handler under the open source Apache web server using the mod_python
extension. Components:
The Apache configuration file hppt.conf needs the following additional lines:
LoadModule python_module modules/mod_python.so
Alias /apps "C:/ADA/WEB/apps"
# emplist.py must be copied here as well as images/ subdirectory
<Directory "C:/ADA/WEB/apps">
Options Indexes MultiViews
AllowOverride All
Order allow,deny
Allow from all
AddHandler mod_python .py
PythonHandler mod_python.publisher
PythonDebug On
PythonPath "sys.path+['c:/ADA/python/dev']"
SetEnv HTMLDIR "C:/ADA/WEB/apps"
</Directory>

Software AG 2004-2008

Page 25/26

Adabas Api for Python

adapya 0.7

September 1, 2008

To browse the telephone list enter the URL e.g.


http://localhost/apps/emplist.py/select
To select with search criteria on name or department enter the URL e.g.
http://localhost/apps/emplist.py/select?name=S*;dept=M*

Software AG 2004-2008

Page 26/26