Python API Reference

Information

• When installing PLANTA project, you can either select Python version 3.4.3 or 3.6.0 or 3.8.5.
• In case a result of a method or function call could not be retrieved or did not exist, Python's "None" will usually be returned.
• Empty alpha numeric fields return an empty string.
• For detailed information on coding conventions, see: http://www.python.org/dev/peps/pep-0008/
• String values stored in DIs via Python API will be trimmed to match the maximum length specified by the respective DI's DB length if necessary.

Macro example

mod_obj = ppms.get_target_module()

def on_load():
    if (ppms.uvar_get('@G119') == 'foo'):
        ppms.uvar_set('@G119', 'bar')
        ppms.ui_message_id('0000')

def on_initial_focus():
    mod_obj.menu(12)
    mod_obj.open_module('005544')

def on_focus():
    ppms.ui_message_box('focus message', 'Hello World')

def on_reset():
    mod_obj.menu(12)

Custom exceptions

Information

• Python/C API makes it possible to define and use custom exception types (classes)
• PPMS/Python API now has a possibility of using custom exceptions as well
  • custom exception definitions are part of ppms.

Class Hierarchy

BaseException (Python standard library)
 +-- Exception (Python standard library)
      +-- PLANTARpcError
      |    +-- ServiceDirectoryError
      |    +-- RpcCommunicationError
      |
      +-- PpmsError
           +-- DatabaseError
           +-- DataTableError
           |    +-- NonexistentDataTable
           |
           +-- DataItemError
           |    +-- DataItemNumberOutOfBounds
           |    +-- ForeignDataItem
           |    +-- NonexistentDataItem
           |
           +-- MtsError
           |    +-- ClosedModuleError
           |    +-- ClosedPanelError
           |    +-- DeletedRecordError
           |        +-- DeletedDataFieldError
           |
           +-- SessionExitForced
           |    +-- MemoryLimitExceeded
           |
           +-- DtpError
           |    +-- DeletedDtpRecordError
           |    +-- DeletedDataItemError
           |
           +-- CustomizingError
                +-- KeyValueTruncationError
                +-- DisabledFeatureError
                +-- ReentrantModuleEvent
                +-- CircularDependencyError

General Functions

Python events

• code examples

Generic functions

Global DTP functions

Global DTP example

Given following fictious customer data structure is defined:

• DT700 Book
  • DI010000 / L123_isbn_13 / ISBN-13 (Primary key)
  • DI010001 / L123_title / Title
  • DI010002 / L123_author_id / Author ID
  • DI010003 / L123_publisher_id / Publisher ID
  • DI010004 / L123_year / Release year

from ppms import ppms
...

# Create a new book in the database
di_dict = {
    'L123_isbn_13': '978-3-8362-1412-4',
    'L123_title': 'Python 3',
    'L123_author_id': author_id,       # previously determined
    'L123_publisher_id': publisher_id,   # ditto
    'L123_year': 2009
}
ppms.create_record(700, di_dict)
...

# Get title of the book identified by ISBN-13 number "978-3-8362-1412-4"
book_title_rec = ppms.search_record(
    700,
    ['978-3-8362-1412-4'],
    [10001],
    dblookup = True)

if book_title_rec is not None:
    book_title = book_title_rec.L123_title.get_value()
    ...

# Get full record of the same book
book_rec = ppms.search_record(
    700,
    ['978-3-8362-1412-4'],
    [],
    dblookup = True)

if book_rec is not None:
    book_year = book_rec.L123_year.get_value()
    ...

User interface

• list of functions:

Example of ui_message_box()

buttons = ['OK','Cancel']
ppms.ui_message_box('Test','Extended message box.', 1, '000207', buttons, 3)

msg = ppms.msg_pop()
ppms.ui_message_box('Replied', buttons[msg.get_reply()-1])
ppms.ui_message_box('Input', msg.get_input())

Enabling/Disabling the user interface

• The PLANTA Server has two context levels that control what is shown to the client.
  • echo - Controls all messages sent from the server to the client. This includes modules opening, filtering, closing, dialog messages etc.
  • message - Controls all dialog related messages sent from the Server to the Client. This includes messages opened by ppms.ui_message_box, ppms.ui_message_id and ppms.ui_statusbar_set.
• Disabling or enabling them can easily be achieved via the Python API:

Controlling the echo state

from ppms import ppms
from ppms.constants import MENU_CLOSE

mod_obj = ppms.get_macro_module()

# We approach this with the echo state enabled
with ppms.echo_disabled():  # This turns off the echo state and remembers that it was turned on before
    new_mod_obj = mod_obj.open_module('009327')  # Since echo is disabled we do not see this on the Client

    with ppms.echo_enabled():  # This turns on the echo state and remembers that it was turned off before
        ppms.ui_message_box('This message appears! The module does not')
    # We left the context where the echo state was enabled and restore the previous state, which was disabled

    new_mod_obj.menu(MENU_CLOSE)
# We left the context where the echo state was disabled and restore the previous state, which was enabled

Controlling the message state

from ppms import ppms

# We approach this with the message state enabled
with ppms.messages_disabled():  # This turns off the message state and remembers that it was turned on before
    ppms.ui_message_box('This message should not appear')  # Message state is disabled, so this message is not shown to the client and lands on the stack

    with ppms.messages_enabled():  # This turns on the message state and remembers that it was turned off before
        ppms.ui_message_box('This message should appear')  # Message state is enabled, so this message is shown to the client and (!) lands on the stack
    # We left the context where the message state was enabled and restore the previous state, which was disabled

    ppms.ui_message_box('This message should not appear')  # Message state is disabled, so this message is not shown to the client and lands on the stack
# We left the context where the message state was disabled and restore the previous state, which was enabled

• When the message or echo context is disabled, messages that would normally be shown to the client are hidden and replied to using their default reply as configured in the Default-Button field.
• To answer messages with a different reply you can use the ppms.autoreply_to_message function.

from ppms import ppms
from ppms.constants import MSG_REPLY_YES, MSG_REPLY_NO, MSG_REPLY_BACK

EXAMPLE_MESSAGE_ID = '0009'  # This dialog offers you "YES", "NO" and "BACK"

with ppms.messages_disabled():
    with ppms.autoreply_to_message(message_id=EXAMPLE_MESSAGE_ID, reply=MSG_REPLY_BACK):
        ppms.ui_message_id(EXAMPLE_MESSAGE_ID)  
        
        with ppms.autoreply_to_message(message_id=EXAMPLE_MESSAGE_ID, reply=MSG_REPLY_NO):
            ppms.ui_message_id(EXAMPLE_MESSAGE_ID) 
            
        ppms.ui_message_id(EXAMPLE_MESSAGE_ID)  
        
msg = ppms.msg_pop()
replies = []
while msg is not None:
    replies.append(msg.get_reply())
    msg = ppms.msg_pop()
    
ppms.ui_message_box(replies)  # [3, 2, 3]

Session export

Used to start and export the logfile information of the current session. Can be used for monitoring or testing purpose for example.

Note:

• The file is encoded in UTF-8. It can be opened in Python with the correct encoding:
• Example:

with open(filename, encoding='utf-8') as log: log_txt = log.read()

Server execute script

Service functions

Note:

• Function has to be defined independently of the module it is called from - since it is called independently.
• All used modules have to be imported in the body of the function, other elements (functions, classes, attributes) of the current module are not implicitly available.
• If a service function stops, make sure stop_service() is the last instruction executed.

Warning:

• Service functions are not reliably executed in the configured time interval
• Execution can only be triggered when the session is polling for messages from a client
• Whenever an action like loading a module or executing python code is executed, service function execution periods are ignored
• Service function execution is now only takes place during the main event loop ; service functions are not called while waiting for a message box response or other specific events

User variables

Timer functions

The collected information is stored in the session table: DT324Statistik.

Record limiting

Information

• These functions control when and how queries that would return a very large number of records are interrupted (because this would slow down the system).
• The limits are defined by the global variables @G80109 (soft limit) and @G80110 (hard limit). If queries return more records than the soft limit, a message box will be displayed via which the user can cancel this query. If queries return more records than the hard limit, they are ALWAYS canceled, and the user sees a message box which informs him/her about this (the message box is not blocking; it does not halt other session processes).
• During loading of modules or filtering, the results of various queries are summed up to count against soft/hard limit.  Otherwise, only the result set of one query is taken into account (for hard limits).
• The query whether soft queries should be canceled is only displayed during module loading/filtering. Otherwise, violations of soft limits are ignored. Violation of hard limits, however, are always taken into account.

DB interface

Information

• Notice that Python API uses the same DB connection as the server program itself, which means that for instance the db_commit() call will have an effect on all pending operations, even on those that were not issued by Python API.
• Starting with Release 39.4, autocommit is disabled throughout the application by default, though emulated for backwards compatibility with existing Python code relying on this setting to be enabled.
• New code should disable autocommit at the beginning, perform DB operations as seen fit, and finish with either commit or rollback when done, in order to deliver the best performance possible.

Commit/Transactional Behavior

• In the default behavior, every db operation via the python API is automatically stored (equivalent to auto commit).
  • This comprises all changes made, e.g. by using db_modify(), the HQL API, or by saving a DTP record.
• This can be switched off using autocommit_disabled(), which implicitly opens a transaction
• Every db operation that is executed afterwards just manipulates the data in the implicitly opened transaction.
• Only during the following statements/events, the changes are commited to the database:

1. when calling db_commit()
2. when leaving the autocommit_disabled() context from a state where auto commit was enabled
3. when leaving a macro context that initially switched off autocommit (as the auto_commit behavior of "parent macros" is implicitly restored)

• If a user has customizing permission, a warning message "IE: auto commit behavior was changed when running <context>, reset is forced!" is displayed when the auto commit behavior is not explicitly reset before leaving a context.
  • This can only occur when using the deprecated function db_set_auto_commit() instead of the context managers autocommit_disabled() or autocommit_enabled()

Working with the auto commit state

from ppms import ppms

# We approach this with the auto commit enabled
with ppms.autocommit_disabled():  # This turns off the auto commit and remembers that it was turned on before
    ppms.db_modify("UPDATE ...")  # We execute a statement on the database that is not committed 

    with ppms.autocommit_enabled():  # This turns on the auto commit and remembers that it was turned off before
                                     # This will commit the previous statement
        ppms.db_modify("UPDATE ...")  # We execute a statement on the database that is committed
        
    # We left the context where the auto commit was enabled and restore the previous state, which was disabled

    ppms.db_modify("UPDATE ...")  # We execute a statement on the database that is not committed 
    
# We leave the context where auto commit is disabled and go back to the previous state which was enabled
    
ppms.db_modify("UPDATE ...")  # We execute a statement on the database that is committed

Validating records

Information

• Hibernate validates all entities that are saved into the database for completion.
• In some cases (migration scripts), we want to deactivate this functionality for one or for all entities
• An 'entity' is the name of a java class for a DT, defined by the column Entity-name in DT415

Modifying the validation

from ppms import ppms

# We approach this with the validation enabled
with ppms.validation_disabled():  # This turns off the validation globally, remembering the old state
    # ...
    
    with ppms.validation_enabled(entity_name='Module'):  # This turns on the validation for the Module entity
        # ...
        
    # We left the context, so validation for the Module entity is disabled again

    # ...

# We left the context where the validation was disabled and we restore the old state - which was enabled

Session monitoring

Information

• These functions allow the monitoring and manipulation of all sessions (both active and terminated threads) since the last server startup.

Protocol version

• enables checking for support of a specific feature; this is relevant for supporting different client versions in python customizing

MTS data

General functions

Panel class

Module class

(module instance) Attributes: Sub-DAs can be directly accessed via their customizing name (same thing as using get_da(string cust-name)) A clarification on invoker data field vs. invocation data field customizing, resp.:

• Invoker DF is the DataField in which the link was clicked / button was pressed / context menu was opened in order to invoke the macro.
• Invocation DFC is the DataFieldCustomizing which defines the macro to be invoked, and perhaps additional parameters for the code to be reused.
• In case of links and buttons, the invocation DFC is the same as the invoker DF's customizing.
• In case of context menu items however, the invocation DFC will differ from the invoker DF's customizing. In this situation, the invocation customizing had been unavailable to the macro invoked (prior to 39.5.3).
• In order to improve code reuse it is advised to treat both of them separately in all cases. The invoker refers to the context in terms of actual data, whereas the invocation context is mainly required for the inner proceedings of the macro handling the invocation itself, so a clear distinction between the two needs to be understood. The fact that the invoker is returned as data field whereas the invocation is returned as a DF customizing should facilitate this distinction.
• As of 39.5.3, the new method Module.get_invocation_customizing will provide the proper DFC in all the situations outlined above.

Using a Module instance as context manager

• Module instances can now be used as a context manager
• When the context is left and the module is still open it will be attempted to close it
  • If this causes a message like the save confirmation to pop up the module is not closed

Using a module as context manager

from ppms import ppms
from ppms.constants import MENU_FILTER

mod_obj = ppms.get_macro_module()

with mod_obj.open_module('009327') as example_module:
    example_module.menu(MENU_FILTER)
    
    # Do whatever you want to do with the module here
    
# The module will be closed when the context is left
ppms.ui_message_box('Module is closed!')

Why is this useful?

• You can use this functionality for technical modules that you need to open to perform some kind of business functionality but should be closed afterwards
• When an error occurs within the context the module is still closed!

from ppms import ppms

mod_obj = ppms.get_macro_module()

with mod_obj.open_module('009327') as example_module:
    int('Hello!')  # raises a ValueError
    
# The module will still be closed!

Root class

Information

• A module can have up to 5 different root areas:
  • main
  • fixed header
  • fixed footer
  • print header
  • print footer

DataArea class

MtsRecord class

(display record, a wrapper for mts_disp_rec data structure) Attributes: Sub-DFs can be directly accessed via their customizing name (same thing as using get_df(string cust-name))

DataField class

(display DF, a wrapper for mts_disp_df data structure)

MessageStackItem class

Attributes: id, text, reply and input (the same attributes the getter-functions are defined for)

Note: To make sure that python triggered messages lay on the stack set blocking to TRUE.

MTS customizing

ModuleCustomizing Class

Attributes: DACs can be directly accessed via their customizing name (same thing as using get_dac(string cust-name))

RootCustomizing Class

DataAreaCustomizing Class

Attributes: DFCs can be directly accessed via their customizing name (same thing as using get_dfc(string cust-name))

DataFieldCustomizing Class

ModuleVariant Class

DTP

DtpPool Class

DtpRecord Class

Attributes: Sub-DIs can be directly accessed via their customizing name (same thing as using get_di(string cust-name))

DataItem Class

Hyperlink Class

Attributes: This class defines the constants

• CLIENT_BASED
• SERVER_BASED
• UNSTRUCTURED
• NO_HYPERLINK

to identify the type of a Hyperlink. See the method get_hyperlink_type of class DataItem for how to use this functionality.

Server Python modules

Information

• Included with the installation of PLANTA are several Python modules that aren't automatically imported in a PLANTA module.
• These Python modules provide further functionality to enhance the base functions provided by ppms.py

What is a Python module?

• A Python module is a *.py file that contains code
• This code can be reused by another module by importing the original module to the new script
• This makes all classes, functions and variables of the imported module available to the new script
• For a basic introduction to Python modules see the corresponding chapter in A Byte of Python

• Important modules:

Example

Goal

• Importing global_setting to access the get_global_setting_value() function to read the content of DI051828 Alpha (120) with the Python-ID "startup_module_persons_users_roles" in module Globale Einstellungen and then opening the module

Example

from ppms import global_setting

def on_load():
    mod_id = global_setting.get_global_setting_value('startup_module_persons_users_roles', 'alpha120')
    ppms.get_macro_module().open_module(mod_id)

Value Ranges

Further methods for Python value ranges

Data Dictionary Access

Information

• This functionality serves mainly as a basis for migration packages and test automation.

Goal

• The data dictionary is already prepared in the server. Information and interconnections therein are frequently required. In order to not implement and maintain the entire logic several times, a simple read-only access to pre-existing information was conceived.

Details

• The data dictionary passed to Python is a static snapshot of the current in-memory state, i.e. the very data dictionary on top of which the code is operating. Modification of the Python objects has no effect on the application's functionality.
• The Python module ppms.data_dictionary defines the object classes used for export and extends them with a few helper methods.
• The global method finalize() will be called from inside ppms.get_data_dictionary() and is mandatory - the same functionality implemented in C would be very unwieldy and complex.

Possible issues with Python Formulae

• The exported data dictionary contains DI dependencies. In order to calculate these for Python formulae, their code needs to be compiled. Hence formulae which do not run in a global context, i.e. have some user session or module dependencies on file scope, will break data dictionary python export! Any instruction depending on more than just the most basic data dictionary components has to be moved into the method using its result, otherwise the formula cannot be compiled outside its intended runtime scope.

Example

from ppms import ppms, data_dictionary

ddict = ppms.get_data_dictionary()

DataDictionary class

DbSchema class

DataTable class

DataItem class

Relation class

DiStructure class