Package Reference¶
adapya.adabas.api - Adabas Programming Interface¶
The adapya.adabas.api module defines the Adabas and Adabasx classes which implement the Adabas API.
-
class
adapya.adabas.api.
Adabas
(fbl=0, rbl=0, sbl=0, vbl=0, ibl=0, pmutex=None, noexceptions=0, thread=0, multifetch=0, archit=None, password='', cipher='')[source]¶ Define the data structures and methods for Adabas database access.
These are the Adabas control block and buffers for the Adabas call() and high level methods for the Adabas API
- Parameters
fbl – format buffer length - fb will be allocated of that size
rbl – record buffer length - rb will be allocated of that size
sbl – search buffer length - sb will be allocated of that size
vbl – value buffer length - vb will be allocated of that size
ibl – ISN buffer length - ib will be allocated of that size
>>> from adapya.adabas.api import * >>> a=Adabas(fbl=12,rbl=100) # create control block, format and record buffer >>> a.cb.dbid=8 # set database id >>> a.cb.fnr=11 # set file number >>> a.fb.value='AA,AB.' # select interesting fields >>> a.getiseq() # get ISN in sequence (I option) >>> print(a.rb.value) 50005500ALEXANDRE BRAUN
See the __init__() method for parameter details of creating an instance of the Adabas class.
-
bt
()[source]¶ Backout Transaction with database dbid - must be set before calling this function Note: not ET-data supported, no Multifetch option
-
call
(**cbfields)[source]¶ issue Call Adabas with the Adabas control block class variables
- Parameters
cbfields – list of key value pairs that can be used to set the control block before the call
>>> c1.call(cmd='L1', cid='ABCD', fnr=11, isn=12345)
-
checkpoint1
(flush=0, id='UCP1')[source]¶ Write Checkpoint.
- Parameters
flush – = 1 to start a bufferflush
id – checkpoint id as 4 byte characterstring
- Variables
self.cb.dbid – must be set before calling this function
-
checkpoint5
()[source]¶ Write User Checkpoint with data.
- Variables
self.cb.dbid – must be set before calling this function
self.rb – The record buffer may hold checkpoint data
-
close
(etdata=None)[source]¶ Close user session with database
- Parameters
etdata – (optional) ET data to write with end of transaction requires etid being set with
Adabas.open()
- Variables
self.cb.dbid – must be set before calling this function
-
delete
(isn=0, wait=0)[source]¶ delete record if wait is true: wait if record is in hold wait==0 return with RSP145 - ISN hold by other user
-
et
(etdata='')[source]¶ End Transaction with database.
- Parameters
etdata – (optional) ET data to write with end of transaction requires etid being set with
Adabas.open()
- Variables
self.cb.dbid – must be set before calling this function
Note
currently does not support Multifetch option
Function supports both Adabas and Adabasx calls.
-
find
(saveisn=0, sort='')[source]¶ Find records by selection
- Parameters
saveisn – 1 saves ISNs on WORK for later processing under CID
sort – ‘FNF2F3’ may specify up to 3 descriptors by which the selected records are sorted
-
first_unused
(dbid=0, fnr=0)[source]¶ return first unused ISN from FCB This number can be used as an upper bound to the number of records loaded. Do not use this function on an expanded file.
- Returns
first unused ISN
-
get
(isn=0, hold=0, wait=0)[source]¶ get record with ISN=isn
if hold is true: put record in hold (L4)
if wait is true: wait if record is in hold
-
getiseq
(isn=None, hold=0, wait=0, dmap=None)[source]¶ get record with ISN in ISN sequence
if hold is true: put record in hold (L4)
if wait is true: wait if record is in hold
if dmap set to a datamap and multifetch is set to > 1 in the Adabas class getiseq() returns the size of the record that is located in the datamap buffer at the offset
returns tuple (ISN, record_length)
Example with multifetch:
>>> while c.getiseq(dmap=emp): ... emp.lprint() 12345678 John W Adkinson 12345699 Peter O Smith
-
getnext
(hold=0, wait=0)[source]¶ get next record from ISN list after find()
if hold is true: put record in hold (L4)
if wait is true: wait if record is in hold
-
getopsys
()[source]¶ Return Operating System and Adabas Version
Adabas open() call must have been done before
- Returns
string containing Opesys and Adabas version of database nucleus
Example:
>>> c1.Adabas() >>> c1.cb.db=10025 >>> c1.open() >>> print(c1.getopsys()) Database 10025 is active, V8.3.1 arc=4, opsys=Mainframe (IBM/Siemens/Fujitsu), cluster nucid 54321, High-order-byte-first/EBCDIC/IBM-float
-
histogram
(seq='', descending=0, dmap=None)[source]¶ Histogram sequence generator
- Parameters
seq – histogram descriptor, e.g. seq=’AA’
descending – read descending if true (only with seq=’descriptor’ sequence)
dmap – Datamap object
- Returns
(value, quantity, lowest_ISN, PE_occurrcence)
datamap object if dmap set to a Datamap and multifetch is set to > 1 in the Adabas class. The function returns the Datamap object that is located in the datamap buffer at the offset. It can be printed with .lprint() (line) or .dprint() (detail)
Example with datamap:
>>> for isn, xemp in c.histogram(seq='AE', dmap=emp): ... xemp.lprint() 12345678 John W Adkinson 12345699 Peter O Smith
Example without datamap:
>>> emp.buffer = c.rb >>> for isn, _ in c.histogram(seq='AE'): ... emp.lprint() 12345678 John W Adkinson 12345699 Peter O Smith
-
hold
(isn=0, wait=0)[source]¶ Put record in hold with ISN=isn (prevent other users from updating the record)
if wait is true: wait if record is in hold
-
logapa
(loghdr='', before=0)[source]¶ Logging of Adabas call parameters for Acb
Options set in logopt determine which buffer to log
- Parameters
before – set to true if logging before the adabas call
-
multicall
(nc=0)[source]¶ Initialize Multi-call after Acb and buffers have been allocated
- Parameters
nc – number of commands
-
multifetch
(dmap)[source]¶ Generator function :param dmap: datamap of record buffer - offset will be advanced
- Returns
tuple (ISN, datamap)
Note: currently with ACB or ACBX with one RB/MB pair
-
newbuffer
(type, size)[source]¶ resize or define new buffer of <type> in ACB style if current size > size: old buffer will be reused
- Parameters
type – one of (‘F’,’R’,’S’,’V’,’I’)
size – if > 0: allocate buffer and set it for for further reference in call parameters
-
nextcid
()[source]¶ Returns integer of next CID value for sequence operations (obsolete: use cidn=-1 to let Adabas automatically return)
-
open
(mode=None, tna=0, tt=0, etid='', arc=None, acode=0, wcode=0, wcharset='', tz='')[source]¶ Open a user session with a database.
- Variables
self.cb.dbid – must be set before calling this function
- Parameters
acode – ECS code page number for client data encoding of A fields
arc – architecture key is the sum of the following values - 1: low order byte first, default: high order byte first - 2: EBCDIC, default: ASCII - 4: VAX floating-point - 8: IEEE floating-point, default: IBM 370 float - default: arc=0 will use data format native to caller’s machine
etid – 8 bytes Adabas transaction user id
mode – defines share mode of files, default None if mode is a string it may be a list of modes e.g. ‘UPD=2,ACC=3’
tna – time of non-activity
tt – transaction time
tz – Timezone name according to the Olson Timezone DB / pytz e.g. ‘Europe/Paris’
wcode – ECS code page number for client data encoding of W fields
wcharset – IANA name for W field encoding (ADABAS OpenSystems V5.1, Mainframe V7.4 only recognizes ‘UTF-8’ for other encodings use wcode)
-
rc
(cid=None, op1='', op2='')[source]¶ Release Command ID as specified in Adabas Control Block CID field
- Parameters
cid – optional parameter specifies the command id to be used for the RC
op1 – optional parameter specifies the value for command option 1 to be used for the RC (default = ‘ ‘)
op2 – optional parameter specifies the value for command option 2 to be used for the RC (default = ‘ ‘)
- Variables
self.cb.dbid – must be set before calling this function
Note: Currently not specific to any resource (ISN List, sequence or format)
-
read
(seq='', descending=0, hold=0, wait=0, dmap=None, startisn=0, toisn=0)[source]¶ Read in sequence generator
- Parameters
seq – read sequence * physical (default) or * by descriptor (e.g. seq=’AA’, search and value buffer must be set) * by ISN (seq=’ISN’ or seq=’I’) * get next (seq=’NEXT’ or seq=’N’)
descending – read descending if true (only with seq=’descriptor’ sequence)
hold – put record in hold if hold is true
wait – if wait is true: wait if record is in hold
dmap – Datamap object
- Returns
datamap object if dmap set to a Datamap and multifetch is set to > 1 in the Adabas class. The function returns the Datamap object that is located in the datamap buffer at the offset. It can be printed with .lprint() (line) or .dprint() (detail)
Example with datamap:
>>> for isn, xemp in c.read(dmap=emp): ... xemp.lprint() 12345678 John W Adkinson 12345699 Peter O Smith
Example without datamap:
>>> emp.buffer = c.rb >>> for isn, _ in c.read(seq='ISN'): ... emp.lprint() 12345678 John W Adkinson 12345699 Peter O Smith
-
readisnseq
(hold=0, wait=0, dmap=None)[source]¶ Read in ascending ISN sequence generator (experimental)
- if hold is true:
put record in hold (L4)
- if wait is true:
wait if record is in hold
if dmap set to a datamap and multifetch is set to > 1 in the Adabas class function returns the record that is located in the datamap buffer at the offset
yields tuple (ISN, dmap)
Example with multifetch:
>>> for isn, xemp in c.readisnseq(dmap=emp): ... xemp.lprint() 12345678 John W Adkinson 12345699 Peter O Smith
-
readphys
(hold=0, wait=0, dmap=None)[source]¶ Read in physical sequence generator (tested ok)
- Parameters
hold – put record in hold (L5) if hold is true
wait – if wait is true: wait if record is in hold
dmap – Datamap object
- Returns
datamap object if dmap set to a Datamap and multifetch is set to > 1 in the Adabas class. The function returns the Datamap object that is located in the datamap buffer at the offset. It can be printed with .lprint() (line) or .dprint() (detail)
Example with multifetch:
>>> for xemp in c.readphys(dmap=emp): ... xemp.lprint() 12345678 John W Adkinson 12345699 Peter O Smith
-
readphysical
(hold=0, wait=0, dmap=None)[source]¶ Read physical
- if hold is true:
put record in hold (L4)
- if wait is true:
wait if record is in hold
if dmap set to a datamap and multifetch is set to > 1 in the Adabas class readphysical() returns the size of the record that is located in the datamap buffer at the offset
Example with multifetch:
>>> while c.readphysical(dmap=emp): ... emp.lprint() 12345678 John W Adkinson 12345699 Peter O Smith
-
searchcrits
(view, crit)[source]¶ free text form search mapped to search and value buffer entries
- Parameters
view –
instance of Datamap with search fields attributed with fn=adabas_field_name
dict of Adabas shortname, length, format tuples accessed by longname or
crit –
selection criteria string (tokens separated by blank) e.g. ” name = BELL and department = ADM1* “
Comparison operators: < > <= >= = != and Adabas equivalent LT etc. with from-to written as field = ADKI* or field FROM ‘A’ TO ‘B’
Connecting operators: AND OR and Adabas defined D, O, R, Y, N
Currently no parenthesis: i.e. criteria evaluated from left to right execept the Y
-
searchfield
(fieldname, fieldlen, value, crit='', ffrm='', first=0, last=0)[source]¶ Insert a search value into the value buffer
If last character of value contains ‘*’ a from-to search is created
Supported are: string and unicode values (with even field length in bytes):
if the search criterion is TO, LT or LE: the value is expanded with 'ÿ' to fieldlen if crit == 'TO': crit = '' if the search criterion is other than EQ, set the input param crit to GE, GT, LE, LT or NE.
- Parm ffrm
one of Adabas formats gets inserted to search buffer if numeric format (U,P,F,B or G): the input integer value is converted to appropriate Adabas value in value buffer
- Parameters
first – if true it is the first search criterion in the buffers. Reposition search and value buffer to start positions
last – if true it is the last search criterion in the buffers Terminate search buffer
- Note: Don’t forget to terminate search buffer with ‘.’ or set the
parameter last=True
-
setadaid
(thread, adaidlev=3)[source]¶ Set Adabas communication id This method is called during intialization of Adabas/Adabasx object only if thread is not zero.
- Parameters
thread – thread number
-
setcb
(**cbfields)[source]¶ Set Adabas control block class variables in one call
cbfields = list of key value pairs that can be used to set the control block
>>> c1.setcb(cmd='L1', cid='ABCD', fnr=11, isn=12345)
-
showCB
(before=0)[source]¶ Print Adabas control block interpreted
- Parameters
before – if not zero show CB fields relevant for before the adabas call (e.g. no response code, cmd time)
-
sortisns
(saveisn=0, sort='ISN', cid='', descending=0)[source]¶ Sort ISN list saved on WORK or given in ISN buffer
- Parameters
cid – Command id of ISN list to be sorted. If cid is blank the ISN list is taken from the ISN buffer
descending – if the ISN list is to be sorted by desciptors setting descending=1 will sort by descending values otherwise it will be ascending
saveisn – 1 saves ISNs on WORK for later processing under CID
sort –
- ‘FNF2F3’ may specify up to 3 descriptors by which the
selected records are sorted.
’ISN’ sorts the ISNs in ISN sequence (default)
-
store
(isn=0, fastde=None)[source]¶ Store record into Adabas file
- Parameters
isn – ISN if record to be stored under that ISN otherwise let Adabas assign ISN
fastde – field name of descriptor that will be stored in ascending sequence. When specified the normal index blocks will be fully filled rather than half full due to not splitting the last block. This can half the number of new normal index blocks.
-
exception
adapya.adabas.api.
AdabasException
(value, apa)[source]¶ Instance will have set the following values:
self.value is the Adabas response string
- self.apa is the Adabas call parameters that were used when
the error occurred
Example on how to call it:
if subclassed e.g. with class DatabaseError(AdabasException) try: raise AdabasException(value,apa) except AdabasException as e: adalog.warning('AdabasException', e.value, e.__class__) dump(e.apa.acb,log=adalog.warning)
-
class
adapya.adabas.api.
Adabasx
(fbl=0, rbl=0, sbl=0, vbl=0, ibl=0, mbl=0, password='', pbl=0, pmutex=None, ubl=0, thread=0, multifetch=0, archit=None, noexceptions=0, cipher='', clientinfo=True)[source]¶ Set of Adabas classes to issue Adabas calls and write/read related buffers
-
addbuffer
(type, buffer)[source]¶ create ABD for buffer and add abd and buffer of <type> to list of bufs and abds :param type: buffer type is one of (‘F’,’R’,’M’,’S’,’V’,’I’,’P’,’U’) :param size: if size > 0: reallocate buffer :returns abd: related ABD for further reference :raises ProgrammingError: when invalid buffer type given
-
call
(**cbfields)[source]¶ issue Call Adabas with the Adabas control block class variables
- Parameters
cbfields – list of key value pairs that can be used to set the control block before the call
>>> c1.call(cmd='L1', cid='ABCD', fnr=11, isn=12345)
-
logapa
(loghdr='', before=0)[source]¶ Logging of Adabas call parameters for Acb
Options set in logopt determine which buffer to log
- Parameters
before – set to true if logging before the adabas call
-
newbuffer
(type, size)[source]¶ resize existing buffer <type> if smaller :param type: is one of (‘F’,’R’,’M’,’S’,’V’,’I’,’P’,’U’) :param size: if size > 0: reallocate buffer :returns abd: related ABD for further reference
-
open
(mode=None, tna=0, tt=0, etid='', arc=None, acode=0, wcode=0, wcharset='', tz='')[source]¶ Open a user session with a database.
C{self.cb.dbid} must be set before calling this function
- Parameters
acode – ECS code page number for client data encoding of A fields
arc – architecture key is the sum of the following values:
1: low order byte first, 2 - EBCDIC,
4: VAX
8: IEEE floating-point;
defaults: high order byte first, ASCII, IBM 370 float
if arc=0 will use data format native to caller’s machine
- Parameters
etid – 8 bytes Adabas transaction user id
mode – defines share mode of files, default None (in the future: list of sublist of mode, file elements)
tna – time of non-activity
tt – transaction time
tz – Timezone name according to the Olson Timezone DB / pytz e.g. ‘Europe/Paris’
wcode – ECS code page number for client data encoding of W fields
wcharset – IANA name for W field encoding (ADABAS OpenSystems V5.1, Mainframe only supports ‘UTF-8’)
-
-
class
adapya.adabas.api.
Mcbuh
(buffer=None, offset=0)[source]¶ Multicall Buffer Header with offsets to global or array of elements
-
class
adapya.adabas.api.
Mcstoff
(buffer=None, offset=0, nc=0)[source]¶ Multicall Buffer set up start offset array
-
adapya.adabas.api.
eventinfo
(dbid, printinfo=1, detailed=1, version='')[source]¶ return event information after response code initially only for response 145
- Parameters
dbid – dbid
printinfo – when set eventinfo will be printed
detailed – when set and printinfo is set eventinfo will be printed in detail
version – ‘8.2’ Adabas version 8.2 view ‘’ - latest version (default)
-
adapya.adabas.api.
getip
(family=<AddressFamily.AF_INET: 2>, host='10.255.255.255')[source]¶ Determine own IP address
-
adapya.adabas.api.
s1
(s, byteorder='@')[source]¶ return string s converted to bytes after 1 byte inclusive length
- Parameters
s – input string or (bytes,bytearray)
byteorder – byteorder for input unicode string may be ‘<’ little or ‘>’ big endian, default is unicode internal
-
adapya.adabas.api.
s2
(s, byteorder='@')[source]¶ return string s after 2 bytes inclusive length byteorder may be ‘<’ little or ‘>’ big endian
-
adapya.adabas.api.
setsaf
(userid, password, newpass='', encrypter=None)[source]¶ Set session userid and password with ADASAF databases.
- Parameters
userid – user id for security system where database resides
password – security system password
encrypter – optional call back routine that encrypts logon data matching installation-defined decryption in remote database
The data is used in the Adalnk for login to a protected database request userid and password.
-
adapya.adabas.api.
setuidpw
(dbid, userid, password, encrypter=None)[source]¶ - Set session userid and password with LUW databases.
Starting with LUW Adabas 6.5
- Parameters
dbid – database id to which userid and password apply
userid – user id for security system where database resides
password – security system password
encrypter – optional call back routine that encrypts logon data matching installation-defined decryption in remote database
The data is used in the Adalnk for login to a protected database request userid and password.
-
adapya.adabas.api.
sl4
(s, byteorder='@')[source]¶ return string with packed length of string. Used for AAL elements
-
adapya.adabas.api.
space_calculation_AC
(maxrec, blocksize=2544, rabnsize=3)[source]¶ Calculate space requirements for an Adabas file in in the Address Converter.
- Parameters
maxrec – number of records
blocksize – ASSO blocksize and
rabnsize – DATA storage RABN size defined for database (3 or 4)
>>> space_calculation_AC(5000,blocksize=2004) 8 >>> space_calculation_AC(5000,blocksize=2004,rabnsize=4) 10 >>> space_calculation_AC(10**9,rabnsize=4) 1572328 >>> space_calculation_AC(10**9,rabnsize=3) 1179246