Python API Reference

• All PPMS-specific modules are stored in the top-level package called "ppms"
  • modules currently available
    • ppms_.ppms
      • contains the core SWIG-generated functions and classes
• 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 returns an empty string.
• For detailed information about coding conventions see: http://www.python.org/dev/peps/pep-0008/
• String values being stored into DIs via Python API will be trimmed to fit into the maximum length specified by 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

• 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 exceptions definitions are part of ppms.i
• with PpmsError class intended to be used as a base class for all other PPMS-related exceptions

DatabaseError

• raised by some of DBIF functions ( db_select(), db_modify(), etc.) when things go wrong during communicaiton with DB
• attributes:
  • parameter: string with a description of the error

General Functions

Python events

• code examples

Generic functions

Global DTP functions

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

Session export

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's 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.

User variables

Timer functions

DB interface

• notice that Python API uses the same DB connection as the server program itself, which means that for instance db_commit() call will have an effect on all pending operations, even those that were not issued from Python API
• starting with Release 394 Earth, 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

MTS data

General functions

Panel class

Module class

Method	Parameters	Return Value	Comment
get_uid()		int: Internal UID of the module
get_id()		string: customizing ID of the module (e.g. 009845)
get_root(position)	position: int (root position, 0..4)	Root instance: root at the given position
get_das()		list: of all data areas in the module (DataArea instances)
get_da (name)	name: string (customizing-name)	DataArea instance: DataArea with specified customizing-name from dg410
get_customizing()		ModuleCustomizing instance: customizing for this module instance
set_statusbar(text)	text: string (text to be displayed)	int: 0 for failure, anything else for success
clear_statusbar()		int:
message_box(caption, text)	caption: string text: string		displays a module-specific modal message box with OK button, specified caption and text message
get_roots()		list: of Root instances from the given module
menu(id)	id: ID of the menu item (command) to activate. See Menüpunkte for a list of possible IDs	bool: False on failure, True on success
set_title_suffix(suffix)	suffix: string (a string to be appended to the module's title)	None:
open_module(id, skip_macro=False, forced_status = 0, dock_to_module = -1, dock_style = -1, dock_proportion = -1.0, foreground = -1, auto_hide = -1, focus = 1, disable_submodules)	id: string (ID of the module to be opened) skip_macro: int/bool (optional argument, the default value is False; when True, modules macro will not be executed) forced_status: int [0,1,2] defines wether stored setting is used(0), module is mainmodule(1) or submodule(2) dock_to_module: int (uid of module to be attached to, -1 dock to panel) dock_style: int (0..4), 0:fill, 1:right, 2:left, 3:bottom, 4:top dock_proportion: double (0..1) foreground: -1 is default, in which case client uses its default value; 0 (or False) and 1 (or True) are also possible auto_hide: -1 is default, in which case client uses its default value; 0 (or False) and 1 (or True) are also possible focus: 1 to focus the module after opening, 0 for otherwise disable_submodules: A list of strings containing the IDs of the submodules of opened module which should not be loaded in this call	Module instance or None if an error occurred during opening of the module	Opens a new module in the context of this module. If a module macro is running, the newly opened module will become a current target module of the macro.
is_stub()		bool: True if the module is a stub module (= it was only loaded as a framework for performance reasons), False if module was loaded completely
get_invoker_module()		Module instance or None if no invoker module is linked
get_panel()		Panel instance: of Module
get_invoker_rec()		MtsRecord instance: returns the record from which module was invoked
get_macro_invoker_dfc()		DataFieldCustomizing: returns the data field which defined thef context menu that invoked the module (or NULL if module was not invoked by context menu)	It is recommended that this function is called for the macro_module, not the target_module, since modules do NOT inherit this attribute to their sub modules or their invoked modules. Therefor, if a menu item calls a macro module, only this macro module knows the df which defined its context menu.
get_new_L_var()		dict:: key is variable number, value is list of strings	returns the modules @L Structure that is used for passing it to an invoked module
get_current_L_var()		dict: key is variable number, value is list of strings	returns the modules @L Structure that was given by the invoking module
set_new_L_var(var_no, values)	var_no: number of @L variable values: a list of values	bool:	Sets the @L variables of the next module that will be called from the current one
set_current_L_var(var_no, values)	var_no: number of @L variable values: a list of values	bool:	Sets the @L variables of the current module
create_mv(title)	title: string	string: id of the newly created MV	creates new MV with give title using current module CU settings
delete_mv_by_id(id)	id: string	bool: succes/failure indication	deletes MV of given name from DB, updates all affected MV comboboxes and resets to base CU those modules that had the MV applied at the time of its deletion
save_mv_by_id(id = None)	id: string, optional	bool: success/failure indicator	stores current CU changes into MV of given id; the MV must already exist; if id is not specified (is None), currently applied MV's id will be used
apply_mv_by_id(id)	id: string	bool: success/failure indicator	applies MV of given ID to module's CU
apply_mv_by_title(title)	title: string	bool: success/failure indicator	applies MV of given title to module's CU (assumes the title is unique across the entire list of module's MVs)
get_applied_mv_id()		string: id of currently applied MV
focus()			Gives the module an input focus on client- as well as on server side. Same effect as if user clicked inside the module to give it a focus.
reset_cu()			Sets the module variants back to base setting
refresh_dts(dt_numbers)	dt_numbers: a tuple containing numbers of affected DTs		reselects records for all DAs in the module that use one of the given DTs as their determining DT; intended to be used after TCalc to refresh contents of those DTs that can get new records during the TCalc process; example use: mod.refresh_dts((472, 888))
has_unsaved_changes()		bool: True if the module was changed and it wasn't saved, False otherwise
enableChangesIndicator()			This method will enable the "asterisk"-mechanism of the current module. An asterisk is shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already not shown it will still be not shown)
disableChangesIndicator()			This method will disable the "asterisk"-mechanism of the current module. An asterisk is no longer shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already shown it will still be shown).
getChangesIndicator()		bool: True if the module's title would include an asterisk * if it had unsaved changes, False otherwise.
get_python_macro()		returns the python module of a customized macro	The returned module object offers access to all functions and names that are customized in the modules macro. This functionality is available from version 39.4.4.1 (Hotfix 10).

Root class

• 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

MessageStackItem class

Note: To make sure that Python-triggered Messages lay on the stack set blocking to TRUE.

MTS customizing

ModuleCustomizing

RootCustomizing

DataAreaCustomizing

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

DataFieldCustomizing

ModuleVariant

DTP

DtpPool

DtpRecord

DataItem

Hyperlink

Method	Parameters	Return value	Comment
get_id()		int: The internal ID used to identify this hyperlink	Together with the schema, this identifies this hyperlink's record in its hyperlink table
get_schema()		string: A short string for the schema of this Hyperlink, e.g. "Q5B"	Together with the id, this identifies this hyperlink's record in its hyperlink table
get_initial_crc()		int: The crc of this Hyperlink's OLE object when it was requested the last time
get_current_crc()		int: The crc of this Hyperlink's OLE object like it is now	May be different from initial_crc if another Client updated this object in your database
get_database_crc()		int: The crc field of this hyperlink in its hyperlink table	Should be identical to get_current_crc
get_title()		string: The title in the data item that connects to this hyperlink
get_url()		string: The destination and name of this hyperlink's data file
get_hyperlink_di()		DataItem The data item that links to this Hyperlink object
get_record()		DtpRecord instance: The record that contains this hyperlink's attributes	Every db schema stores its hyperlinks in its own data table. Note that this record also contains the binary file of this hyperlink (as a blob), but you cannot directly access this Blob object with the usual dtp-record-methods. Use the Hyperlink's methods get_blob and set_value to do this.
get_blob()		ByteArray: The binary object of this hyperlink (Blob object in the database)	Note that BLob objects are read into Python as ByteArrays. This allows e.g. easy writing of Blob objects into data files with usual Python binary file methods
set_value(binary=None, url=None)	binary: ByteArray: The binary object that defines this hyperlink (if server-based) url String: The destination and name of this hyperlink's file. Important! Since this pathname contains backslashes \, you should use Python’s raw string notation, e.g. r"C:\docs\file.doc" not just "C:\docs\file.doc"	bool: True if any values have been written into the Hyperlink object, False if not (e.g. because no parameters were given or because this Hyperlink's data item type does not support this parameter)	Updates the values of this hyperlink object. Note that the values are only updated, they are not yet written into the database. To do this, save this hyperlink's record. The displayed title of the hyperlink will be the filename of the url (= the part of the url after its last backslash \). Both parameters can be empty (None). If a parameter is empty, this attribute is left unchanged. The method only updates the Hyperlink object if at least one parameter is not empty. Note that an empty string "" is different than None. If this method is called with url = "", the current url will be overwritten by an empty string (= deleted). If this method is called without the parameter url, the url of this hyperlink will be left unchanged. Note that only server-based hyperlinks have their own blob-object. If this Hyperlink belongs to a di that is client-based, only the parameter filename is updated, the parameter binary will be ignored.
delete_blob()		string: True if deleting was successful, False otherwise	Removes the binary object that defines this hyperlink. The hyperlink itself (= the structural representation including title and filename) remains unchanged. Note that the binary is not yet deleted in the database, but it will be once its hyperlink di (or the hyperlink record itself) is saved
delete()		string: True if deleting was successful, False otherwise	Deletes the complete Hyperlink object with all its data, as well as the record of this hyperlink, setting the internal value of the data Item that links to this hyperlink to 0 Attention: This means that the Hyperlink object can no longer be used after this method was called!

Server Python modules

• 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

• Importing ppms_cu to access the Helper.get_global_setting() 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

from ppms import ppms_cu

def on_load():
    mod_id = ppms_cu.Helper.get_global_setting('startup_module_persons_users_roles').alpha120.get_value()
    ppms.get_macro_module().open_module(mod_id)

Value Ranges