Adapya - Adabas Api For Python: Software AG © 2008 Company Confidential Page 1/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
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.
Page 3/26
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
Page 4/26
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>
Page 5/26
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.
Page 6/26
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
Page 7/26
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)
Page 8/26
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
Page 9/26
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.rabd.send=8
# put data into format buffer

# ..
record buffer
c1.store()
# issue N1
23
c1.cb.cid='abcd'
Command id is set with a 4 byte string
26
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
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):
Page 10/26
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
Page 11/26
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'
# individual attribute access
Page 12/26
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
Page 13/26
adapya 0.7
September 1, 2008
The Lob Demo Center application requires Apache, mod_python and PIL.
Page 14/26
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
Page 15/26
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:').
Page 16/26
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
Page 17/26
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
Alias /apps "C:/ADA/WEB/apps"
<Directory "C:/ADA/WEB/apps">
AllowOverride All
Order allow,deny
Allow from all
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'
Page 18/26
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
Page 19/26
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
Page 20/26
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
Page 21/26
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.'
Fields extracted for Telephone List Webapp

PERSONNEL-ID FIRST-NAME MIDDLE LAST-NAME
BIRTH COUNTRY
AREA-CODE PHONE DEPT JOB-TITLE
Page 22/26
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
Page 23/26
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
Page 24/26
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:
Alias /apps "C:/ADA/WEB/apps"
# emplist.py must be copied here as well as images/ subdirectory
<Directory "C:/ADA/WEB/apps">
AllowOverride All
Order allow,deny
Allow from all
PythonDebug On
PythonPath "sys.path+['c:/ADA/python/dev']"
SetEnv HTMLDIR "C:/ADA/WEB/apps"
</Directory>
Page 25/26
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*
Page 26/26

Adapya - Adabas Api For Python: Software AG © 2008 Company Confidential Page 1/26

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Adapya - Adabas Api For Python: Software AG © 2008 Company Confidential Page 1/26

Hochgeladen von

Copyright:

Verfügbare Formate

adapya Adabas Api for Python

Adabas Api for Python

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

Adabas Api for Python

adapya does not implement a SQL interface as defined with the

Adabas Api for Python

4 Setting up an Execution Environment for MS-Windows

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

We have tested on WinXP with:

Adabas Api for Python

4.2 Installation of adapya

4.2.1 Windows PYTHONPATH installation

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

4.2.2 Windows Standard Installation

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

Change directory to that temp folder e.g.

Run normal python packages installer

Adabas Api for Python

4.2.3 Unix/Linux PYTHONPATH Installation

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

# add APYDIR to PYTHONPATH

# show status of database 12

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

Adabas Api for Python

5 Using the Adabas API

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

# allocate set of buffers ACBX,

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

# put data into format buffer

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

except DatabaseError, (line, apa):

Adabas Api for Python

5.1.1 Adabasx Objects

Adabas Api for Python

# set control block fields

Here we make a hex print of the extended control block

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

5.1.2 String Buffers

Adabas Api for Python

Opening a User Session

5.1.3 Storing a Record

# put data into format buffer

5.1.4 Reading a Record

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

5.1.5 Backing-out the Transaction

5.1.6 Closing the User session

5.1.7 Response Code Checking vs. Exception Handling

Adabas Api for Python

The block within

5.2 Further Details of adapya

# Access Abuf class

# Allocate buffer of 8 bytes

# store 'Bell' into buffer a

# same in slice notation

# extract part of buffer

# modify buffer at offset 0

# read() 5 bytes of the buffer

# read() next bytes (only 3 left)

# position to start of buffer

# write first 3 characters

Adabas Api for Python

5.2.2 Working with Structures with Datamap