Python API Reference

Information

• 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

Execution time of macro

• 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

• list of functions:

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

Warning

• The function has to be defined independently of the module it's called from.
• So all used modules have to be imported in the body of the function and it's not allowed to call other functions of the current module from the service function.

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
• in case of Python-powered module macros, any changes made to AUTOCOMMIT state of the DB connection will be reverted back to the state before the macro was executed so that Python macros don't unintentionally change AUTOCOMMIT state for the entire application

MTS data

General functions

Panel class

Module class

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 the Alpha (120) Datafield with the Python-ID "startup_module_persons_users_roles" of the global settings module 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