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.Abdx(**kw)[source]
class adapya.adabas.api.Acb(**kw)[source]
class adapya.adabas.api.Acbx(**kw)[source]
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
histo(descriptor='', descending=0)[source]

Read Index by descriptor (deprecated)

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

insert(isn=0, fastde=None)[source]

Alias for store()

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)

printopsys()[source]

Print Opsys and Adabas Version Adabas open() call must have been done before

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
readByIsn(getnext=0)[source]

Read Sequential by ISN getnext = 1 if getnext else 0

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)
setoffs(btyp)[source]

set start offsets within Multi-Call buffer

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.

update(hold=0, isn=0, wait=0)[source]

Update record hold==1 put record into hold status before update wait_on_hold==0 return with RSP145 - ISN hold by other user isn = record to update

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’)

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)

class adapya.adabas.api.Adaid(**kw)[source]
class adapya.adabas.api.Adasafinfo(**kw)[source]
class adapya.adabas.api.ClientInfoLuw(**kw)[source]
exception adapya.adabas.api.DataEnd(value, apa)[source]
exception adapya.adabas.api.DatabaseError(value, apa)[source]
exception adapya.adabas.api.Error[source]
class adapya.adabas.api.Infomap(*fields, **kw)[source]
class adapya.adabas.api.Infomap2(*fields, **kw)[source]
exception adapya.adabas.api.InterfaceError(value, apa)[source]
exception adapya.adabas.api.InvalidSearchString[source]
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

class adapya.adabas.api.Mfele(buffer=None, offset=0)[source]
class adapya.adabas.api.Mfhdr(buffer=None, offset=0)[source]
exception adapya.adabas.api.NotYetImplementedError[source]
exception adapya.adabas.api.ProgrammingError[source]
exception adapya.adabas.api.Warning[source]
adapya.adabas.api.cbyte(key)[source]

condense key string to one byte

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.s4(s, byteorder='@')[source]

return string s after 4 bytes inclusive length

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