Die nachfolgenden Inhalte sind nur in englischer Sprache verfügbar.

Information

  • When installing PLANTA project, you can either select Python 3.4.3 or 3.6.0 or 3.8.5 version.
  • 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)
PY

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 exceptions definitions are part of ppms.i
Exception classDescriptionRaised by
PLANTARpcError defined in module csrpc.core.exceptions; base class for RPC related errors (same exists in client code)all code using csrpc
  • ServiceDirectoryError
defined in module csrpc.core.exceptions; service directory related errors (service lookup failed, service already exists)csrpc service lookups or registration
  • RpcCommunicationError
defined in module csrpc.core.exceptions; general csrpc communication problems (e.g. no csrpc client support)all code using csrpc
PpmsError
Base class for all PLANTA project related exceptions
DatabaseError
Base class for all errors that occur when things go wrong during communication with DB DBIF functions like e.g. db_select() , db_modify() etc.
DataTableError
Base class for errors related to data table objects
  • NonexistentDataTable
whenever a nonexistent data table is passed search_record() , create_record() , DtpPool() , get_di_by_id()
DataItemError
Base class for errors related to data item objects
  • DataItemNumberOutOfBounds
whenever a DI >= 1000000 is requested get_di_by_id()
  • NonexistentDataItem
whenever a nonexistent DI is passed or a DI with given customizing name is not found within the data table get_di() , get_di_by_id() , save()
  • ForeignDataItem
whenever a DI is requested by number which does exist, but in a different data table than the one currently handled search_record()
MtsErrorBase class for errors within the scope of module related objects
  • ClosedModuleError
raised whenever a Module reference is used which had been closed already
  • ClosedPanelError
raised whenever a Panel reference is used which had been closed already, most likely along with its associated main module
  • DeletedRecordError
raised whenever an MtsRecord reference is used which has already been deleted, most likely along with the corresponding DTP record and DB entry
  • DeletedDataFieldError
raised whenever a DataField reference in an MtsRecord is used which has already been deleted, perhaps along with the corresponding DTP record and DB entry
DtpError
Base class for errors within the scope of DTP related objects
  • DeletedDtpRecordError
raised whenever a DtpRecord reference is used which has already been deleted, most likely along with the corresponding DB entry
  • DeletedDataItemError
raised whenever a DataItem reference is used which has already been deleted, perhaps along with the corresponding DTP record and DB entry
CustomizingErrorBase class for errors caused by faulty customizing
  • KeyValueTruncationError
Raised whenever a primary key value does not fit into the corresponding DI or columnsearch_record()
  • DisabledFeatureError
Customizing tries to use a feature which was disabled by configuratione.g. client_exec()
  • ReentrantModuleEvent
Module event handler calls itself, leading to stack overflow; call is intercepted
  • CircularDependencyError
Circular Data Item dependency calculation detected - python formula compilation performs an action which in turn causes dependency calculation of said Data Item againformula with a call to ppms.get_data_dictionary(), or a (nested) import containing the same, each on file scope
SessionExitForcedRaised whenever an internal error forces a session to exit
MemoryLimitExceededRaised whenever a violation of set memory limits forces a session to exit

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
CODE

General Functions

Python events

FunctionExecution time

Python code which is not encapsulated in a specific function will be executed during the module load (default behaviour)
on_load()Code in this function is executed also during the module load
on_initial_focus()Code in this function is executed when module is focused the first time
on_focus()

Code in this function will be executed everytime a module is focused.

Note: This function is not executed if the module already had the focus

on_reset()Code in this function will be executed everytime after a module was reset
on_before_mv_switch(old_mv, new_mv)Code in this function will be executed prior to application of a different MV / takes two arguments - ModuleVariant objects representing "old" and "new" MV
on_after_mv_switch(old_mv, new_mv)Code in this function will be executed after application of a different MV / takes two arguments - ModuleVariant objects representing "old" and "new" MV
on_web_load(Variable dictionary)This function will be executed after module loading, but ONLY if the module-opening has been initiated by openModule, with the transferred Dictionary 
on_tooltip_load(datafield)Code in this function will be executed when a tooltip should be opened, but ONLY if tooltip module is configured for the datafield.

Generic functions

MethodParameter(s)Return ValueCommentFrom
get_target_module()
returns a target module (the one which receives any module-related commands) of the running macro (returns a Module instance)
can't be used in value ranges; when a module is opened from the macro, the opened module will become the target module; when the target module is closed, it's invoker becomes target module.

get_macro_module()
returns the module the Python macro is in, this can be the same as from macro get_target_module() , but in case of pure macro modules, it will be different (returns a Module instance)
can't be used in value ranges

get_panels()
returns a Python list containing Panel instances of all currently opened panels
can't be used in value ranges

get_context_df()
returns the DataField instance from which the macro was called when accessible

if no instance can be found, "None" object is returned

can't be used in value ranges

client_exec(script)

script: string, when dealing with line breaks, the string must be encapsulated in """, e.g. """import os import sys""", otherwise you get an error like "EOL while scanning single-quoted string"


ge_set_auto_layout_gap(gapwidth: i2_t)gapwidth: int
sets the value of the graphic-editor-setting auto-layout-gap to gapwidth and sends it to the Client

echo_disabled()



Enters a context where echo mode is disabled. Restores the old state when leaving the context. Example usage
echo_enabled()


Enters a context where echo mode is enabled. Restores the old state when leaving the context. Example usage
messages_disabled()


Enters a context where messages are disabled. Restores the old state when leaving the context. Example usage
messages_enabled()


Enters a context where messages are enabled. Restores the old state when leaving the context. Example usage
msg_pop()
returns MessageStackItem instance or noneget last MessageStackItem from message-stack
msg_clear_assumptions()

remove all assumptions
autoreply_to_message(message_id, reply)message_id: String

reply: int


Enters a context where the message is replied to automatically with the given reply. This only works when messages are not shown in the client (echo or message context need to be turned off). Example usage
changeset_number()
string: changeset numberreturns the changeset number of the server program
reload_server()

restart the server, stopping all currently active sessions to let data-dictionary-changes take effect
change_password(username, password)username: string,
password: string

set password of the given user to the new one
distribute_effort_for_list(records)records: list of MtsRecord instances
used internally by effort distribution functionality provided via Schedule Module subclass, not to be used directly
get_session_dict()

Dictionary

Session-specific dictionary used to read and write data. This dictionary can be used to hold global variables that are accessible in all modules of this Client session, but NOT in other Client sessions.
Replace all references to builtins in your Python modules with ppms.get_session_dict(). builtins (as well as other globals in Python) are NOT thread-safe!


get_server_dict()

DictionaryThe function get_server_dict() actually works like the function get_session_dict().
get_query(id)id: id of a record in DT342SQL queryused to read a query of table DT 343. The result of this function is cached and requires a server restart to be cleared
get_system_customizing_errors()



the textual contents of the system customizing errors message box

get_auto_id()

di_id: The id of a DI as string (e.g. "001400")The next auto-number for this DI (with current license)Returns the next auto-number for this DI, or None if di_id does not denote a di using auto-numbers

get_client_type()


Integer which corresponds to a constant of the "ClientType" python class

Return value specifies how a client session was started: via native, headless or web interface

navigate_to(url, target)

url: string

target: string 


used for the F1/F2 functionality (help websites) in Jython/Web clients

db_export_data()

filename: string


starts the database export S 39.5.32

get_client_version()

string

Returns the client version as a string
S 39.5.32

activate_protocol_action(parameter, protocol_name=None)

parameter: string

protocol_name: string


Invokes Application Link

If no protocol name is passed, the configured name will be read from the global setting

S 39.5.33

query_server_configuration

parameter_list: string

Returns the parameterlist as Dictionary

used to read configuration parameters or groups of parameter

S 39.5.34

query_server_parameter

parameter: string

Returns the parameter as a string

reads a single parameter

S 39.5.34

Events and Exits Control

Information

  • With the following functions, you can temporarily disable (& re-enable) any Exit or Data Event in the running server.
  • This only applies to the current session. In other sessions, these exits & events are still enabled.
  • It's intended that these functions are used with 'with' macros, like e.g. messages_enabled / messages_disabled.


Note

  • This does NOT change the (permanent) enabled-property in the Event Data table. For an event to be executed, this field must be enabled (=1), AND the event must not be disabled by one of the following functions.
  • This affects all Data Events (excluding Timed Events), with the exception of some hard coded events for license checking, which are always active.
FunctionParameter(s)Return ValueComment

disable_all_events



Temporarily disables every Data Event

enable_all_events



Re-enables every Data Event that has been temporarily disabled by any function

disable_events_of_table

dt_num: int for data table number


Temporarily disables every Data Event that is assigned to the given table

enable_events_of_table

dt_num: int for data table number


Only re-enables those events that have been temporarily disabled for this table

disable_event

event_uuid: UUID: A unique, system-wide UUID that identifies an event


Temporarily disables the event identified by event_uuid

enable_event

event_uuid: UUID: A unique, system-wide UUID that identifies an event


Re-enables the event identified by event_uuid

is_event_enabled

event_uuid: UUID: A unique, system-wide UUID that identifies an event

returns boolean

Returns False if this Event has been temporarily disabled in any way, OR, if it is permanently disabled (when the enabled field in the Regtest table is set to 0)

Basically the same functionality, but for old Native-Code-Exits, not for events

FunctionParameter(s)Return ValueComment

disable_all_exits



Temporarily disables every Exit

enable_all_exits



Re-enables every Exit that has been temporarily disabled by any function

disable_exit

exit_id: int


Temporarily disables the Exit identified by exit_id

enable_exit

exit_id: int


Re-enables the Exits identified by exit_id

is_exit_enabled

exit_id: int

returns boolean

Returns False if this Exit has been disabled (either by disable_exit or disable_all_exits),
True otherwise

Clientless Sessions

Information

  • With the following functions, you can control Clientless Sessions by Python-code
  • Their handling is essentially identical to their corresponding Jython-functions, and, indeed, they call exactly the same Server-Code


Function

Parameter(s)

Return Value

Comment

open_clientless_session

user: String, name of the user which starts this session (e.g. P20)

Unique ID of the new clientless session


can raise

ppms.UserNotFoundException

Starts the session.

The session stays open until close_clientless_session is called.

open_module_by_clientless_id

clientless_session_id: Int. The return value of open_clientless_session, to identify the session in question.
module: String, ID of the module to open
dictionary: Hashmap<String, Object>, a dictionary containing variables for the module

Returns boolean indicating if the module could be found and prepared


can raise

ppms.ClientlessSessionNotFoundException ppms.ModuleNotFoundException
ppms.ModuleDictionaryException

Prepares the module identified by module-ID to be opened in the clientless session identified by clientless_sesion_id (if existing).
Note: This is an asynchronous call, which means the openModule will finish before the module is actually opened. That's why the return value does not indicate whether opening of the module was successful, just whether a module & a clientless session woith their requested IDs exist
After the module is opened, the new Python-callback-function on_web_load(Dictionary) is called with the parameters given to open_module.
The parameter-dictionary supports parameters of type Boolean, String, Integer, Float, or lists thereof

get_return_value_for_module_by_clientlessId

clientless_session_id: Int. The return value of openClientlessSession, to identify the session in question.
module: String, ID of the module to open

Dictionary: The return value of on_web_load of the module which was called in this thread


can raise

ppms.SessionNotFoundException,
ppms.ModuleDictionaryException

The return value is a dictionary of the same type as the dictionary of open_module_by_clientless_id.
If the module has not been run yet, None is returned
If the module has no method called on_web_load, or on_web_load does not return a value, an empty Dictionary is returned


close_clientless_session

clientless_session_id: Int. The ireturn value of open_clientless_session, to identify the session in question.

void


can raise

ppms.ClientlessSessionNotFoundException

Closes the clientless session

open_clientless_session_with_module

user: String, name oft he user which starts this clientless session (e.g. P20),

module: String, ID of the module to open
dictionary: Hashmap<String, Object>, a dictionary containing variables for the module

Unique ID of the new clientless session


can raise

ppms.UserNotFoundException
ppms.ClientlessSessionNotFoundException ppms.ModuleNotFoundException
ppms.ModuleDictionaryException

Opens a new clientless session and executes a module in it.
Basically a convencience function, as calling it is is identical to

new_id = open_clientless_session(user)
open_module_by_clientless_id(new_id, module_id, some_dictionary)

get_thread_id_of_clientless_session

int: Clientless Session-Id

Long: ThreadID

can raise

ppms.ClientlessSessionNotFoundException

The input Parameter is the ID of a Clientless session (the value that is returned by open_clientless_session and is used as the first parameter by the functions which handle clientless Sessions).

Returns the threadID (Long-value) of this Clientless Session

Global DTP functions

MethodParameter(s)Return ValueComment

search_record(dt_num, key_list, di_list, dblookup = True) 

dt_num: int for data table number

key_list: list containing primary key values for the searched record (values in appropriate type of the key DIs: string for textual keys DIs, int for N2 or N4 key DIs. Note that the format of the key must match the customizing in the data dictionary, f.e. if a uppercase key is expected a uppercase key must be supplied)

di_list: int list containing required DI numbers or/and CU names. If empty all DIs are fetched

dblookup: boolean, telling whether DB-query may be sent if required DIs are missing
returns a DtpRecord instance or None when no record was found or any of the required DIs is missing
can raise DataTableError exception
currently, the dblookup parameter has no effect; search_record() queries the database whenever a record or requested DIs cannot be found in memory
create_record(dt_num, di_dict)
dt_num: int for data table number

di_dict: dictionary with elements in form [DI python name]:[value]
DtpRecord instance on success, None on failure (e.g. no validation possible)
can raise DataItemError and DataTableError exceptions
Dictionary must be populated with all primary key dis and their values except autoid dis.
  • create_record() returns an existing record if there is one
  • use the DtpRecord.state() method to check whether it is a duplicate
  • function awaits that all values fit with db column type and returns none otherwise

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

User interface

  • list of functions:
MethodParameter(s)Return ValueComment
ui_statusbar_set(text)text: String
  • Displays a message in the main statusbar
  • In msg_off case, a MessageStackItem is created with the id "statusbar" and the text text
ui_statusbar_clear()

  • clear main statusbar
  • In msg_off case, a MessageStackItem is created with the id "statusbar"

ui_message_box(caption, text, blocking = 1, ole_id = None, button_list = ['OK'], number_of_input = 0)

caption: String

text: String
blocking: Boolean (stop processing macro until user-reply is available)

ole_id: String (id of message icon)

button_list: list of String (list of names of buttons of message)

number_of_input: Int (number of text fields of message)

displays a global modal message box with with specified parameters. First 2 parameters are mandatory. See example below and MessageStackItem class description. ID for the MessageStackItem is "message_box"

ui_message_id(id: string)

id: String
displays a message for the given message id (DI MSG ). ID for the MessageStackItem is id.

ui_get_system_title()


string: system titlereturns the current system title.
ui_set_system_title(title: string)title: String
sets the system title. Strings that are longer that 200 characters get truncated.

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

Enabling/Disabling the user interface

  • The PLANTA Server has two context levels that control what gets 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
PY

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
PY
  • When the message or echo context is disabled messages that would normally be shown to the client are hidden and replied to with their default reply as configured in Default-Button field.
  • To answer messages with a different reply you can use the function ppms.autoreply_to_message.
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]
PY

Session export

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

MethodParameter(s)Return ValueComment
session_export_start(filename)filename: Stringfunction returns boolean: True if starting session export succeeded, False otherwiseIf a file with this name already exists, it will be discarded, not appended
May not succeed when another session export is started or file could not be opened
session_export_stop()
returns the filename as string if export succeeded, None otherwiseno success may indicate that no session was started or e.g. disk full
session_export_is_enabled()
returns booleanTrue if enabled, False otherwise

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

Server execute script

MethodParameter(s)Return ValueComment
get_current_server_script()
returns the last executed server script (in string format) or Noneis used in source provider for debugger only

Service functions

MethodParameter(s)Return ValueComment
start_service(function, timeinterval)function: function
timeinterval: Integer
Noneadd into service function list Python function that will be executed periodically on the server in passed timeinterval (milliseconds)
get_services()
dictReturns a dictionary of function: [interval, last_executed]
stop_service(function)function: functionNoneremoves Python function from service function list, so server stops periodical execution

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.
  • If a service function stops itself, make sure stop_service() is the last instruction executed.

Warning:

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

User variables

MethodParameter(s)Return ValueComment

uvar_get(uvar_id: string)

uvar_id: String
returns a value of the given variable.

Note: When there's more than one value, this values are unsorted.

uvar_id is a variable name (e.g. "@15", "@G191", "@M4")

 uvar_set(uvar_id: string, value: respective data type)

uvar_id: String

value: respective data type

boolean: true when setting the variable successfully, false otherwisesets value of the given variable (@D, @G or @M )

Timer functions

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

MethodParameter(s)Return ValueComment

start_timer(timer_name: string)

timer_name: String, name of timer under which the statistics are saved
Starts to measure statistics about execution of code after calling this function (if performance counting has been enabled)
stop_timer()



Ends the measuring of statistics and inserts the new record into DT324 with collected information (if performance counting has been enabled)
performance_counting_enable()


Starts performance counting globally: from then, performance data from all active and new sessions is written into the table.
performance_counting_disable()


Stops performance counting globally
performance_counting_is_enabled()

int: 0 for disabled, 1 for enabledReturns whether performance counting is currently enabled

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, the user gets the option to cancel this query by a message box. If queries return more records than the hard limit, they are ALWAYS canceled, and user sees a message box informing them about it (this message box is not blocking; it does not halt further session processes).
  • During loading of modules or filtering, the results of various queries are added together to count versus soft/hard limit. At other times, only the result set of one query is taken into account (for hard limits).
  • The question if soft queries should be canceled only appears during module loading/filtering. At other times, violations of soft limits are ignored. Violation of hard limits, however, are always taken into account.
MethodParameter(s)Return ValueComment
activate_record_limits()


Activates canceling of very large queries. This is the standard behaviour
deactivate_record_limits()

Deactivates canceling of very large queries (both soft and hard limit are ignored until activate_record_limits() is called)
get_soft_record_limit()

returns the current soft breaking limit
get_hard_record_limit()

returns the current hard breaking limit
set_soft_record_limit()
value: String: new soft limit in records
A message asking the user if query should be canceled is displayed if this number of records is returned by queries.
This only sets the limit for this session. It is not not saved into database. If you want to change the soft limit globally, change the value of the global variable G80109 in Customizer → Master Data → Variables
set_hard_record_limit()
value: String: new hard limit in records
Queries are forcibly canceled if they return this number of records.
This only sets the limit for this session. It is not saved into database. If you want to change the soft limit globally, change the value of the global variable G80110 in Customizer → Master Data → Variables

DB interface

Information

  • 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 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. using db_modify(), the HQL API, or by saving a DTP record.
  • This can be switched off using autocommit_disabled(), which implicitely opens a transaction
  • Every db operation that is executed afterwards just manipulates the data in the implicitely 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 implicitely the auto_commit behavior of "parent macros" is restored)
  • If a user has customizing permission, a warning message "IE: auto commit behavior was changed when running <context>, reset is forced!" appears when the auto commit behavior is not explicitely reset before leaving a context
    • This can only occur when using the deprecated function db_set_auto_commit() instead od 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
PY
MethodParameter(s)Return ValueComment
db_get_auto_commit()

returns True if the auto commit is on, False otherwise

db_set_auto_commit(state)

state: Boolean
This method is deprecated, instead use with ppms.autocommit_disabled() or with ppms.autocommit_enabled()
autocommit_disabled()


Enters a context where auto commit is disabled. Restores the old state when leaving the context.
autocommit_enabled()


Enters a context where auto commit is enabled. Restores the old state when leaving the context.
db_commit()


commits the pending DB operations
db_rollback()

rolls back any pending operations
db_get_dbms_name()
Number indicating the database typeThis corresponds to the config parameter Q1TYPE in planta_server.conf (e.g. return value "000002" = Oracle database; return value "000004" = MSSQL database)
db_modify(query)
query: String, takes SQL query string (without a trailing semicolon) as the only argument.returns a number of affected records
can raise DatabaseError exception
intended for INSERT/UPDATE/DELETE statements or other "non-selects" like ALTER SESSION
db_select(query)
query: String, takes SQL query string (without a trailing semicolon) as the only argument.returns the result of the query in the form of a list of sublists (each sublist will contain a list of column values for the specific DB record)
can raise DatabaseError exception
intended for SELECT statements conversion of numeric data (column) types from Oracle to PPMS (C)
NUMBER (any configuration thereof) will always be represented as double (r8_t) in PPMS, and as float in Python (due to the current PPMS DB interface implementation)

db_schema_create(dialect, output_path, dts_to_export = None)

dialect: string: The name of the dialect Hibernate uses for generating data. Must be the name of an existing Hibernate dialect, e.g. de.planta.server.hibernate.dialect.Oracle10gDialect or de.planta.server.hibernate.dialect.SQLServerDialect (also in hibernate.cfg.xml)
output_path: string: The directory the exported schema data is written to
dts_to_export: list of strings: A list of the names (not the numerical IDs!) for the tables that should be exported. If this parameter is not specified, or it is 'None', all tables will be exported.
returns an empty string if write was successful, or a string containing error message(s) if notWrites the current database schema to file system, which can then later be used to generate a similar database
db_custom_schema_create(dialect, dts_to_export, get_create_strings, get_table_strings, get_constraint_strings)
dialect: string: The name of the dialect Hibernate uses for generating data. Must be the name of an existing Hibernate dialect, e.g. de.planta.server.hibernate.dialect.Oracle10gDialect or de.planta.server.hibernate.dialect.SQLServerDialect (also in hibernate.cfg.xml)
dts_to_export: list of strings: A list of the names (not the numerical IDs!) for the tables that should be exported. If this parameter is not specified, or it is 'None', all tables will be exported.
get_create_strings: bool: True: Return create-statements; False: return drop-statements
get_table_strings: bool: If True, return list will include statements for actual tables
get_constraint_strings: bool: If True, return list will include statements for constraints
returns a list of strings that are sql statements
Returns a list of strings that contain sql statements for creation/deletion of a specific set of tables, specified by the arguments of this method.
For MSSQL, this function can only be used after commiting all former changes, otherwise this can lead to deadlocks.
db_custom_lines_create(dialect, dis_to_export, get_create_strings)
dialect: string: The name of the dialect Hibernate uses for generating data. Must be the name of an existing Hibernate dialect, e.g. de.planta.server.hibernate.dialect.Oracle10gDialect or de.planta.server.hibernate.dialect.SQLServerDialect (also in hibernate.cfg.xml)
dis_to_export: list of integers: A list of numerical ids (not their actual column names!) for the data items that should be exported. If this parameter is 'None', return value will be an empty array.
get_create_strings: bool: True: Return create-statements; False: return drop-statements
returns a list of strings that are sql statementsReturns a list of strings that contain sql statements for creation/deletion of a specific set of data items, specified by the arguments of this method
db_get_current_dialect()

Returns the name of current Hibernate dialect as a stringIntended to be used in conjunction with db_schema_create, db_custom_schema_create and db_custom_lines_create as the first parameter (if you only want to export your current database dialect)

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
MethodParameter(s)Return ValueComment
enable_validation_for_all_entities()

Enables validating of all entities (standard behaviour). This deletes any exceptions defined by disable_validation_for_entity (entity)
disable_validation_for_all_entities()

disables validating of all entities (standard behaviour). This deletes any exceptions defined by enable_validation_for_entity (entity)
enable_validation_for_entity (entity)entity: String: The name of the entity that should be enabled for validation (e.g. Module)
Enables validation for this one entity, even if entity validation has been disabled by disable_validation_for_all_entities()
disable_validation_for_entity (entity)entity: String: The name of the entity that should be disabled for validation (e.g. Module)
Disables validation for this one entity, even if entity validation has been enabled by enable_validation_for_all_entities()
are_all_entities_validated
returns True if entities are currently validated, False if notNote: The return value handles the general case, a single entity can still overwrite this behaviour by enable_validation_for_entity (entity) / disable_validation_for_entity (entity)
is_entity_validated(entity)entity: String: The name of the entity that should be disabled for validation (e.g. Module)returns True if this entity is currently validated, False if notNote: If there is no special rule for this particular entity (by enable_validation_for_entity (entity) / disable_validation_for_entity (entity), this returns the general behaviour (identical to calling are_all_entities_validated )
validation_enabled(entity_name)entity_name: String: The name of the entity that should be disabled for validation (e.g. Module).
If you don't pass this parameter validation will be enabled globally.

Note: This is intended to be used as a context manager
validation_disabled(entity_name)entity_name: String: The name of the entity that should be disabled for validation (e.g. Module).
If you don't pass this parameter validation will be disabled globally.

Note: This is intended to be used as a context manager

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
PY

Session monitoring

Information

  • These functions allow the monitoring and manipulation of all sessions (both active and terminated threads) since the last server startup.
MethodParameter(s)Return ValueComment
get_current_session_uuid()
returns a unique, system-wide UUID that identifies the current sessionCurrent session means: The session that is calling this function
get_all_session_uuids()
returns an array of unique, system-wide UUIDs for all sessions that have run since last server startupThis list includes UUIDs both for currently active and already terminated sessions
get_active_session_uuids()
returns an array of unique, system-wide UUIDs for all currently running sessions
get_terminated_session_uuids()
returns an array of unique, system-wide UUIDs for all sessions that have terminated since last server startup
get_last_reported_session_time(uuid)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)returns the time when this session was last reported as alive/activeThe time is returned as milliseconds since the start of 1970.
set_last_reported_session_time(uuid, time)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)
time: long: A time specified as milliseconds since the start of 1970

This defines the specified time as the time this session has reported itself as alive/active as the last time.
Currently, the only time this happens is when a new session is started. In future releases, any session will report themselves as alive at regular time intervals. If it fails to do so, server will assume this session as locked and terminate it.
get_session_timeout(uuid)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)returns the time (in seconds) that server will wait until it will terminate this session
Note that this value is defined as seconds, not milliseconds
The termination of old sessions by server is not implemented yet -> This value has no practical consequence yet
set_session_timeout(uuid, timeout)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)
timeout: int: time the server waits until it will terminate this session (in seconds)

Note that this value is defined as seconds, not milliseconds.
The termination of old sessions by server is not implemented yet -> Setting this value has no practical consequence yet
get_session_start_time(uuid)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)returns the time when this session was started originallyThe time is returned as milliseconds since the start of 1970.
get_session_end_time(uuid)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)returns the time when this session has been terminatedThe time is returned as milliseconds since the start of 1970.
If this session is still running, the returned value will be 0.
get_session_user(uuid)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)returns the user that started this session (as string)
get_session_reason(uuid)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)returns the reason why this session has terminated (as string)This might help to decide if the session terminated successfully (because it was closed) or if it terminated because of some error
If the session is still running, an empty string is returned
is_session_interruptable(uuid)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)interruptable: boolean: True if this session may be interrupted by server (future functionality; the normal behaviour), False if not
set_session_interruptable(uuid, interruptable)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)
interruptable: boolean: Defines this session as interruptable (True) or not interruptable (False)

This is useful for very long running sessions. Setting them as not interruptable means the server will never attempt to terminate/interrupt this session, no matter how long it ran and what the last reported time and timeout is.
If a non-interruptable session is changed to become interruptable, server will automatically set the current time as its last reported time, to prevent the session from being interrupted/terminated immediately if it has run for a long time
The termination of old sessions by server is not implemented yet -> Setting this value has no practical consequence yet
has_session_terminated(uuid)uuid: UUID: A unique, system-wide UUID that identifies a specific session (active or terminated)terminated: boolean: True if this session has been terminated, False if this session is still running

Protocol version

  • enables checking for support of a specific feature; this is relevant for supporting different client versions in python customizing
MethodParameter(s)Return ValueComment
protocol_version_in_boundaries(from_version, to_version)protocol version specifiers - see enum ProtocolVersion in ppms.constants.pyboolean; True if the boundaries are matched, False otherwiseProtocolVersion.UNDEFINED for unspecified version, e.g. if there is no boundary for to_version

MTS data

General functions

MethodParameter(s)Return ValueComment
get_active_module()

returns a module (Module instance) that was a target of the currently processed evente.g. during processing of "modify DF value" or "activate DF" event, this will be the module that contains the modified DF. If the event targets a listbox module, the module that contains the listbox is returned instead.
get_focused_module()
returns latest client side-focused module (Module instance)None might be returned e.g. when the currently focused module is closed (as no new focus events are processed during event processing)

Panel class

MethodParameter(s)Return ValueComment
get_uid()
int: Internal UID of the module
get_main_module()
Module instance: the main module in panel
get_modules()
Python list of modules in Panelincludes main module
set_title_suffix(suffix:string)suffix: string (a string to be appended to the panel's title)NoneSet suffix to panel title

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.
Method Parameter(s)Return ValueComment
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 (MtsDataArea instances)
get_da_by_id(id)
id:string (ID of the DA to get)DataArea instance: DataArea with specified ID
get_da(name)name: string (customizing name of the DA to get)DataArea instance: DataArea with specified customizing name
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 IDsbool: True on success, False on failureYou should always check the return value, especially when saving. A return value of False when saving can indicate, that mandatory fields were not filled or that the module still contains invalid records.
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 whether

  • 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 moduleOpens 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.

open_dialog_module(id, skip_macro = False, show_title = -1, is_closable = -1, is_movable = -1, position = -1, close_button = -1)

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)

show_title: bool: If true, the dialog module will have a title bar displayed


is_closable: bool; if True, module will close if user clicks outside of dialog module


is_movable: bool; if True, module can be moved around by the mouse (functionality only available if show_title is True)

position: int (1..9), where to display dialog module:

  • 1: upper left,
  • 2:upper centre,
  • 3:upper right,
  • 4:left,
  • 5:centre
  • 6:right
  • 7:lower left
  • 8:bottom
  • 9:lower right


close_button: bool; if True, dialog module will have an X-like button in its title to close it (functionality only available if show_title is True)

Module instance or None if an error occurred during opening of the moduleOpens a module as a dialog module. If the dialog-specific parameters are not set, or they are set to an invalid value (-1), this means that these properties for the module will be loaded from the database
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()

This method is deprecated and replaced by get_invocation_customizing .

get_invocation_customizing()

DataFieldCustomizing instance : returns the data field customizing which defined the button, link, or context menu item responsible for the macro invocation.This method needs to be called for the macro_module, not the target_module, since modules do NOT inherit this attribute to their sub modules or their invoked modules. Therefore, if a macro module is invoked by DF action or context menu, only the macro module itself knows the dfc which defined its invocation.
get_new_L_var()
dict:: key is variable number, value is list of stringsreturns 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 stringsreturns 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_temporary_new_L_var(var_no, values)var_no: number of @L variable

values: a list of values

Context Manager:Sets the @L variables of the next module that will be called from the current one when entering the context and restores the old l-vars when the context is left again
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: stringstring: id of the newly created MVcreates new MV with give title using current module CU settings
delete_mv_by_id(id)id: stringbool: succes/failure indicationdeletes 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, optionalbool: success/failure indicatorstores 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: stringbool: success/failure indicatorapplies MV of given ID to module's CU
apply_mv_by_title(title)title: stringbool: success/failure indicatorapplies 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,
Note: This willcall the on_focus function of this module (if it has one) if the module didn't already have the 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 macrooffers access to all functions and names that are customized in the modules macro

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!')
PY

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!
PY

Root class

Information

  • A module can have up to 5 different root areas:
    • main
    • fixed header
    • fixed footer
    • print header
    • print footer
MethodParameter(s)Return ValueComment
get_uid()
int: Internal UID of the root
get_module()
Module instance: in which Record is
get_das()
list: of all top-level DataAreas in the root
get_da_by_id(cust_id)cust_id: string (ID of the DA)DataArea instance
Currently, you get None if you carry out this method. The method only seems to work on data areas on level 0.
get_da(cust_name)cust_name: string (customizing name of the DA to get)DataArea instance
count_records_by_dac_id(dac_id)dac_id: string (ID of the DA to count records in)int: Number of records in the Root from the given DA
count_records(dac_name)dac_name: string (customizing name of the DA to count records in)int: Number of records in the Root from the given DA
get_record_by_dac_id(dac_id, position)

dac_id: string (ID of the DA)

position: position of the record in the DA

MtsRecord instanceGets top-level record from the given DA at the given position
get_record(dac_name, position)

dac_name: string (customizing name of the DA)

position: position of the record in the DA

MtsRecord instanceGets top-level record from the given DA at the given position
get_records_by_dac_id(dac_id)dac_id: string (ID of the DA)list: sorted list of records (as they are sorted in the DA) from the given DA that lies directly in the root.
get_records(dac_name)dac_name: string (customizing name of the DA)list: sorted list of records (as they are sorted in the DA) from the given DA that lies directly in the root.
get_customizing()
RootCustomizing instance: for this Root
insert_record_into_da(dac_name)dac_name: string (customizing name of the DA)MtsRecord instance : of the inserted record, None on failureinserts a record into the specified top-level-da
insert_record_into_da_by_id(dac_uid)dac_uid: string (customizing uid of the da)MtsRecord instance of the inserted record, None on failureinserts a record into the specified top-level-da

DataArea class

MethodParameter(s)Return ValueComment
get_uid()
int: Internal UID of the DA
get_id()
string: customizing ID of the DA
get_root()
Root instance: root of this DA, or NULLOnly top level DAs know their root, all other DAs return NULL
get_customizing()
DataAreaCustomizing instance: for this DA
count_records()
int: Number of records in the entire DA
get_marked_records()
list: sorted list (alphabetically) of all marked records in the DA (list of MtsRecord instances)This works only inside the currently active module. Calling get_marked_records on a data area of another module (e.g. invoker module) always returns None, no matter if it is marked or not.
get_records()
list: unsorted list of all MtsRecord instances in DA
insert_record()

MtsRecord instance just inserted, None if insertion failed

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

MethodParameter(s)Return ValueComment
get_uid()
int: Internal UID of the record
count_dfs()
int: number of DFs in the record
get_df_by_id(cust_id)cust_id: string (customizing ID of the DF to get)DataField instance: for the given DF customizing ID
get_df_by_position(position)position: int (position of the DF in the DA, starting with 0)DataField instance
get_df(cust_name)cust_name: string (customizing name of the df to get)DataField instance
get_dtp_record()
DtpRecord instance: for this MtsRecord instance
count_dfs_in_window(window)window: int (the number of the window in question)int: number of DFs in the given window
get_df_in_window_by_position(window, position)window: int (window number)

position: position of the DF in the given window)
DataField instance: for the DF at the given position in the given window
mark()
bool:Also marks on the Client side.
unmark()
bool:Also unmarks on the Client side.
scroll_to()
bool:Advice Client to scroll to this display_record
expand()

bool: True if nodes could be collapsed, False if not (e.g. because it was a top level node, or the associated dac was invisible)Expands the node this record belongs to, along with all other nodes that belong to the same parent and the same data area
collapse()

bool: True if nodes could be collapsed, False if not (e.g. because it was a top level node, or the associated dac was invisible)Collapses the node this record belongs to, along with all other nodes that belong to the same parent and the same data area
is_marked()
bool: True if the record is marked, False otherwiseThis works only inside the currently active module. Calling is_marked on a record of another module (e.g. invoker module) always returns False, no matter if it is marked or not.
count_children_by_dac_id(child_dac_id)child_dac_id: string (customizing ID of the child DA in which we are counting the child records)int: Number of child records from given DA.
count_children(child_dac_name)child_dac_name: string (customizing name of the child DA in which we are counting the child records)int: Number of child records from given DA or from all child DAs.if argument is left blank or NULL the total number of child records from all child DAs is returned
get_children_by_dac_id(child_dac_id)child_dac_id: string (customizing ID of the child DA to get the records from)list: sorted list of child records from the given DA
get_children(child_dac_name)
child_dac_name: string (customizing name of the child DA to get the records from)list: sorted list of child records from the given DA
get_da()
DataArea instance: for DA this record belongs to
insert_child_by_dac_id(child_dac_id)child_dac_id: string (customizing ID of the child DA in which we want to insert)MtsRecord instance of the record we inserted, None if insertion failedInserts a new child record below the given parent record to the given child DA. The child DA must exist for the given parent record. If DA that is to be inserted to is identical with parent record's DA, the new record will be inserted next to the parent record (after it).
insert_child(name)name: string (customizing name of the child DA in which we want to insert)MtsRecord instance of the record we inserted, None if insertion failed
Inserts a new child record below the given parent record to the given child DA. The child DA must exist for the given parent record. If DA that is to be inserted to is identical with parent record's DA, the new record will be inserted next to the parent record (after it).
In python macros, please use insert_child instead of mod_obj.menu(91)
insert_recursive_child()
MtsRecord instance of the record we inserted, None if insertion failedInserts a new inner recursive child into given record
insert_before()
MtsRecord instance of the record we inserted, None if insertion failedInserts a new sibling record before given record
insert_after()
MtsRecord instance of the record we inserted, None if insertion failedInserts a new sibling record after given record
get_parent()
MtsRecord instance of parent, None if no parent exists
get_module()
Module instance: in which Record is
copy_before(destination)
MtsRecord instance before which to copyBoolean, whether the operation was successfulPerforms the same operation as Drag&Drop copy records when dropping before the destination record, selection sensitive
copy_into(destination)MtsRecord instance into which to copyBoolean, whether the operation was successfulPerforms the same operation as Drag&Drop copy records when dropping into the destination record, selection sensitive
copy_after(destination)MtsRecord instance after which to copyBoolean, whether the operation was successfulPerforms the same operation as Drag&Drop copy records when dropping after the destination record, selection sensitive
move_before(destination)MtsRecord instance before which to moveBoolean, whether the operation was successfulPerforms the same operation as Drag&Drop move records when dropping before the destination record, selection sensitive
move_into(destination)MtsRecord instance into which to copyBoolean, whether the operation was successfulPerforms the same operation as Drag&Drop move records when dropping into the destination record, selection sensitive
move_after(destination)MtsRecord instance after which to copyBoolean, whether the operation was successfulPerforms the same operation as Drag&Drop move records when dropping after the destination record, selection sensitive

DataField class

(display DF, a wrapper for mts_disp_df data structure)

MethodParameter(s)Return ValueComment
activate()

Performs the same action as a link click or button push on such data fields
get_uid()
int: Internal UID of this DF
get_id()
int: customizing ID of this DF
get_raw_value()
String: various data types: the value of the DI which is associated with the DF, data type differs based on the DIs DB type
get_text_value()
String:The value of the DF as it is displayed in the client
set_raw_value(value)
value: data type must match the one that is used by the DF's underlying DIint:
DF_VALUE_SETTER_FAILURE = 0
DF_VALUE_SETTER_SUCCESS = 1
DF_VALUE_SETTER_UNCHANGED = 2
for Python value ranges, only processInput is executed, checkInput is ignored.
DF_VALUE_SETTER_UNCHANGED: the same value already is stored in the DI
set_text_value(value)
value: string representation of the value, is treated the same way as the text value filled in by the userint: see set_raw_value()for Python value ranges, only processInput is executed, checkInput is ignored.
focus()
bool:Sets input focus to this DataField. The module which contains the data field needs to be focussed before
scroll_to()
bool:Advice Client to scroll to this display-df. The module which contains the data field needs to be focussed before
get_di()
DataItem instance: underlying DI
is_input()
bool: True or FalseChecks if the DF is an input field
make_output()

bool:
Overrides DF's customizing, making it behave as an output field.
Warning: It's not allowed to use this method on bar fields (fields with DF behavior = "ba").
make_input()
bool:Overrides DF's customizing, making it behave as an input field
get_record()
MtsRecord instance: in which Datafield is
get_customizing_name()
string, None if no customizing id foundcustomizing name from DF customizing with fallback to DI customizing name
get_df_config()
string:Created by Python wrapper. Returns value of DI040968
get_customizing()
DataFieldCustomizing instance
set_df_symbol(symbol_id)symbol_id: id of symbol of DF to be setbool: true if the symbol was successfully set
set_hdg_symbol(symbol_id)symbol_id: id of symbol of DF to be setbool: true if the symbol was successfully set
copy_field2field(destination)destination: DataField instanceBoolean: whether the operation was successfulPerforms the same operation as Drag&Drop field-to-field
copy_field2column(destination)destination: DataField instanceBoolean: whether the operation was successfulPerforms the same operation as Drag&Drop field-to-column, selection sensitive
copy_column2column(destination)destination: DataField instanceBoolean: whether the operation was successfulPerforms the same operation as Drag&Drop column-to-column, selection sensitive

MessageStackItem class

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

MethodParameter(s)Return ValueComment
get_id()
String: returns message-id
get_text()
String: returns message-text
get_reply()
Int: returns button-id0  = ERROR, 1 = OK, YES / 2 = NO / 3 = CANCEL OR order (1...number_of_buttons) of pushed button when you are using ui_message_box method
get_input()
PyTuple: returns tuple of stringsfor msg boxes created by using ppms.ui_message_box constructor: returns tuple of values from input boxes or None if there are no input boxes

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

MethodParameter(s)Return ValueComment
get_dac_by_id(cust_id)cust_id: string (customizing ID of the DA to get)DataAreaCustomizing instance: customizing for the DA with given ID
get_dac(name)name: string (customizing name of DA to get)DataAreaCustomizing instance: customizing for the DA with given customizing name of DADA Python ID

RootCustomizing Class

MethodParameter(s)Return ValueComment
get_root()
Root instance: For this RC
get_dacs()
list: of DataAreaCustomizing instances: (the top-level DAs from the given root)

DataAreaCustomizing Class

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

MethodParameter(s)Return ValueComment
get_id()
string: customizing ID of the DA
can raise DataItemError

get_name()
string: customizing name of the DAReturns ID if customizing name not exists
get_children()

list: of child DataAreaCustomizing instances of this DAC
can raise DataTableError
All columns of the child records are loaded from the data base. This includes also all existing sub select of this DT (example: computeSQLvaluerange). This can result in bad performance.
get_parent()

DataAreaCustomizing instance of this DAC's parentThis is the first ordinary parent of this DAC, or None if this DAC has no ordinary parents
get_root()
RootCustomizing instance: for this DAC
count_dfcs()
int: number of DFs in this DA
get_dfc_by_id(dfc_id)dfc_id: int (ID of the DF, same ID as the one returned by get_id() method of DataFieldCustomizing)DataFieldCustomizing instance: customizing of the DF with given ID
get_dfc_by_position(position)
DataFieldCustomizing instance: customizing of the DF that is currently sitting at the given position in the DA
get_dfc(name)name: string (customizing name of the dfc to get)DataFieldCustomizing instance: customizing of the DF with given customizing nameDF Python ID
set_sym_area_sep_w1(symbol_id)symbol_id: string (ID of the symbol)None:DI041604
get_sym_area_sep_w1()
string: ID of the symbolDI041604
set_sym_area_sep_w2(symbol_id)symbol_id: string (ID of the symbol)None:DI041605
get_sym_area_sep_w2()
string: ID of the symbolDI041605
set_sym_area_sep_w3(symbol_id)symbol_id: string (ID of the symbol)None:DI041606
get_sym_area_sep_w3()
string: ID of the symbolDI041606
set_sym_frame_w1(symbol_id)symbol_id: string (ID of the symbol)None:DI001950
get_sym_frame_w1()
string: ID of the symbolDI001950
set_sym_frame_w2(symbol_id)symbol_id: string (ID of the symbol)None:DI010586
get_sym_frame_w2()
string: ID of the symbolDI010586
set_sym_frame_w3(symbol_id)symbol_id: string (ID of the symbol)None:DI010587
get_sym_frame_w3()
string: ID of the symbolDI010587
disable_satisfaction()NoneNoneDI001582
enable_satisfaction()NoneNoneDI001582
only works when satisfaction rule is not empty
has_satisfaction()Nonesatisfaction enabled ? true : falseDI001582
get_satisfaction()Nonestring: satisfaction ruleDI024599
set_satisfaction(rule)rule: string (satisfaction rule)NoneDI024599
set_to_output()NoneNoneDI000157
set_to_input()NoneNoneDI000157
is_readonly()Noneis output ? true : falseDI000157
set_never_display()
NoneNoneDI001587
unset_never_display()NoneNoneDI001587
is_never_display()Noneis never display ? true : falseDI001587
expand()
bool: True if nodes could be collapsed, False if not (e.g. because dac was a top level node or inivsible)Expands all nodes whose records belong to this dac, no matter where in parent-child tree
collapse()
bool: True if nodes could be collapsed, False if not (e.g. because dac was a top level node or inivsible)Collapses all nodes whose records belong to this dac, no matter where in parent-child tree
set_display_behavior(d-behavior)d.-behavior: in [0..3]NoneDI028202
get_display_behavior()Nonedisplay-behavior in {0, 1, 2, 3}DI028202
set_permission_create()NoneNoneDI001581
unset_permission_create()NoneNoneDI001581
has_permission_create()Nonehas permission create ? true : falseDI001581
set_permission_insert()NoneNoneDI059051
unset_permission_insert()NoneNoneDI059051
has_permission_insert()Nonehas permission insert ? true : falseDI059051
set_permission_move()NoneNoneDI009341
unset_permission_move()NoneNoneDI009341
has_permission_move()Nonehas permission move ? true : falseDI009341
set_permission_delete()NoneNoneDI000798
unset_permission_delete()NoneNoneDI000798
has_permission_delete()Nonehas permission delete ? true : falseDI000798

DataFieldCustomizing Class

MethodParameter(s)Return ValueComment
get_id()
int: customizing ID of the DF DI000307
get_window()
int: Number of the window this DF sits in
set_window(window)window: int (number of window where DF should be placed)

get_position()
int: Current position of the DF in the DAStarts at 1 for the leftmost Datafield in a Dataarea
set_position(position)position: int (position where the DF will be placed in its window)
To put a Datafield at the first position in a Dataarea use "0", to put it as the second last use "-1"
get_dac()
DataAreaCustomizing instance: DAC for this DFC
get_df_config()
stringCreated by Python wrapper. Returns value of DI040968. Useful for the configuration of Python macros.
get_heading()
string: Heading of the DF
set_heading(heading)heading: string (heading of DF value to be set)

get_default_value()
string: Default Value of DF
set_default_value(dv)dv: string (default value to be set)

get_regex_criteria()
string: regex search criteria
set_regex_criteria(criteria)criteria: string (regex search criteria to set)None:
get_search_criteria()
tuple: of two string values (from and to)
set_search_criteria(sc_from, sc_to)from, to: string (values of from and to components)None:
is_mandatory()
bool: True or False
set_mandatory(mandatory)mandatory: int/boolNone:
set_symbol(symbol_id)symbol_id: string (ID of the symbol)None:
get_symbol()
string: ID of the symbol
set_heading_symbol(symbol_id)symbol_id: string (ID of the symbol)None:
get_heading_symbol()
string: ID of the symbol
show(window)window: int window where the field should show upNone:Show this DF column
hide()
None:Hide this DF column
set_position (position)

to define the data field order in modules with table layout

ModuleVariant Class

MethodParameter(s)Return ValueComment
get_id()
string: customizing id of the MV
get_title()
string: title of the MV
get_description()
string: description of the MV
get_type()
string: type of the MVpossible values:"base" (indicates base CU), "standard" (MV created by customizers, not by regular users),"user" (MV created by current user)
is_favorite()
boolean: True if the MV is current user's favorite, False otherwise

DTP

DtpPool Class

MethodParameter(s)Return ValueComment
DtpPool(number)
number : int (number of the DT)Iterator for DataRecords within the DTP for the DT with the given number
can raise DataTableError exception
example: "for record in DtpPool(461) ..."

DtpRecord Class

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

MethodParameter(s)Return ValueCommentAvailable from
get_di_by_id(number)
number : int (ID of the DI)DataItem instance from the DataRecord with the given number
can raise DataItemError


get_di(name)
name: string (customizing name of the DI)DataItem instance from the DataRecord with the given cust-name from dt412
can raise DataItemError


get_dis()
Returns a list of all the DataItems in this record

get_changed_dis()
Returns a list of the DataItems in this record which have been changed (but not saved yet)This is equal to the list of all DataItems where has_been_updated() returns True
append_dis()di_list: A list containing required DI numbers or/and CU names. If empty, none are fetched

Appends the record with the given DIs.
If the record has been inserted, but not yet saved, these are empty DIs (with standard values).

If the record already exists on database, they are loaded with current values

S 39.5.35

get_children(dt, di_list = None, structure = False)

dt: int, data table number
di_list: list, data items to query for
structure boolean, consider inner structure of child DT
returns list of direct children of current record which are from passed data tabledi_list may contain DI CU names as well as DI numbers
save(dis)
dis: (optional) a tuple containing CU names of DIs that are to be saved (any modified DIs that are not mentioned in this list will not be saved);
this list can be applied only to UPDATE operation, not to INSERT operation (new record stored into DB using save() method will store all DIs, regardless of the "dis" list (this is a limitation caused by current server-side implementation of storage of DTP records into DB)
bool: Operation success/failure indicator
can raise DataItemError
stores (INSERT or UPDATE) all pending changes in the given DTP record into DB

Example

  • for one DI: save(("python_id",))
  • for more than one DI: save(("python_id1","python_id2","python_id3"))

delete()

bool: Operation success/failure indicator
deletes a record and all children, failure when the deletion could not be done or if try to delete a project with tasks (e.g. when children can not be deleted)

Caution: After this, this DtpRecord must not be used anymore in any way. Any calls on this DtpRecord could result in program instabilites and/or crashes!


state()

int: the state of a recordMeaning of the return value:
  • 0 = DtpRecord.NONEXISTENT: the record does not exist on server (NULL)
  • 1 = DtpRecord.INVALID: the primary key or relations are not valid
  • 2 = DtpRecord.NEW: the record is valid, but not stored in database
  • 3 = DtpRecord.STORED: the record is stored in database

DataItem Class

MethodParameter(s)Return ValueComment
get_value()
Value of the DI, data type differs based on the DIs DB type
get_tech_value()
"Technical" value of the DI, data type differs based on the DIs DB typeIs different from the ordinary DI's value for I-TEXT type for instance, in which case the ID of an I-TEXT will be returned instead of the I-TEXT itself
has_been_updated()
bool: True if DI has changed its value, but not been saved yet, false otherwiseCalling set_value or set_string_value sets this boolean to true. Saving the record of this DI sets this boolean to false
get_original_value()
Original value of the DI (from database, before it was changed), data type differs based on the DIs DB typeSee the description for get_original_value above for when the original value is being set.

If the DI has not been changed, the return value will be identical to get_value()

Changing the value of DI which has already been updated again will not change the result of this function. It will always return the value before the first change-operation.

get_original_tech_value()
Original "technical" value of the DI (from database, before it was changed), data type differs based on the DIs DB typeIs different from the ordinary DI's original value for I-TEXT type for instance, in which case the ID of an I-TEXT will be returned instead of the I-TEXT itself

See the description for get_original_value above for when the original value is being set.

If the DI has not been changed, the return value will be identical to get_technical_value()

Changing the value of DI which has already been updated again will not change the result of this function. It will always return the value before the first change-operation.

get_dtp_record()
DtpRecord instance: for this DataItem
get_dfs()
list: of DataField instances which contain DataItem
set_string_value(value)
value: string (ATTENTION: value will first be converted to actual data type using standard procedures, i.e. the same process as when user inserts a value into a DF for instance)int: some Errorcode:
DI_VALUE_SETTER_SUCCESS = 0
DI_VALUE_SETTER_FAILURE = 1
DI_VALUE_SETTER_WRONG_FMT = 2
DI_VALUE_SETTER_KEY = 3
DI_VALUE_SETTER_UNCHANGED = 4
Validation does not happen after filling some DI with values (happens on MTS level). So the method refuses to set a value on DI that is part of primary key (DI_VALUE_SETTER_KEY).
In cases where the same value already is stored in the DI, DI_VALUE_SETTER_UNCHANGED is returned.
set_value(value)
value: data type of the value must match that of the DI; supported Python data types and their respective PPMS data type counterparts: int (N2, N4, N8), float (N8), string (X)see set_string_value() Same as with set_string_value()

After a value has been set to a DI, the related DTP record has to be saved if the DI's behaviour is set to output. Saving the module will involve input DIs only.

get_id()
stringCustomizing id of the DI (value of DI)
get_customizing_name()
string: None if no customizing id foundCustomizing name from DI
is_hyperlink()
bool: True if this Data Item connects to a hyperlink
get_hyperlink_type()
enum: Identifies the type of Hyperlink this Data Item connects to. Possible values are

UNSTRUCTURED: A primitive Hyperlink without structures

CLIENT_BASED: A Client-based Hyperlink without a binary object

SERVER_BASED: A Server-based Hyperlink with a binary object

NO_HYPERLINK: This Data item is not a Hyperlink at all

These values are stored in the Hyperlink class. So, to check if a DI is e.g. a server-based Hyperlink, you would use this call:
if (di.get_hyperlink_type() ! ppms.Hyperlink.SERVER_BASED)
get_hyperlink()
Hyperlink instance:The Hyperlink this data item connects to, or None if this di does not have a hyperlink.If this Data Item connects to a Hyperlink, this Hyperlink object is returned. Else, None is returned
insert_hyperlink()
Hyperlink instance:A new (empty) hyperlink object for this Data Item, or None if this di is not a hyperlink di.
If this di did not have a hyperlink before, a new record for this Hyperlink is now inserted. If it did already have a hyperlink object, this object is returned without any changes.

Note that the hyperlink data structures are only created, they are not yet written into database. To do this, save this di's record (preferably after updating the Hyperlink object by using the Hyperlink's set_value method)

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.

MethodParameter(s)Return ValueComment
get_id()
int: The internal ID used to identify this hyperlinkTogether 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_uid()
string: Unique, system-wide id that identifies this hyperlinkhl.get_uid() is actually identical to hl.get_schema() + "_" + str(hl.get_id())

It may be used as return value of an OLE with a WB to mask any server-based hyperlink as an OLE object.

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 nowMay 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 tableShould 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 instance: The data item that links to this Hyperlink object
get_record()
DtpRecord instance: The record that contains this hyperlink's attributesEvery 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 standard Python binary file methods

set_value(binary=None, url=None, is_folder=False, is_weblink=False)

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"

is_folder: Boolean: True if this hyperlink links to a local folder, False if not

is_weblink: Boolean: True if this hyperlink links to a link on the Internet, False if not

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.

set_title(title)
title: string (title that is shown in the data field)bool: True if changing the title was successful, False otherwise
delete_blob()
bool: True if deleting was successful, False otherwiseRemoves 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()
bool: 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

Caution: This means that the Hyperlink object can no longer be used after this method was called!

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:
Python moduleUsage
constants.pyProvides access to several constants
global_setting.pyProvides access to global settings
sql.pyProvides access to SQL utilities
text_constant.pyProvides access to text constants
user_interface/dialog.pyProvides access to dialog message handling

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

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

DataDictionary class

Attribute TypeContentsComment
db_schemasdictionaryppms.data_dictionary.DbSchemaordered by id
data_tablesdictionaryppms.data_dictionary.DataTableordered by id
data_itemsdictionaryppms.data_dictionary.DataItemordered by id
relationsdictionaryppms.data_dictionary.Relationordered by id
di_structuresdictionaryppms.data_dictionary.DiStructureordered by id

DbSchema class

Attribute TypeContents / Return ValueComment
idstring

data_tableslistppms.data_dictionary.DataTable instancesall tables belonging to the schema
itext_table()methodppms.data_dictionary.DataTable instancethe data table storing I-TEXTs for the schema
itext_inum_di()methodppms.data_dictionary.DataItem instancethe data item storing the number, as of the I-TEXT table, not the I-NUM table
itext_lang_di()methodppms.data_dictionary.DataItem instancethe data item storing the language
itext_text_di()methodppms.data_dictionary.DataItem instancethe data item storing the actual text value
itext_ref_dt()methodppms.data_dictionary.DataItem instancethe data item storing the data table to which the I-TEXT belongs
itext_ref_di()methodppms.data_dictionary.DataItem instancethe data item storing the data item to which the I-TEXT belongs
itext_ref_pk()methodppms.data_dictionary.DataItem instancethe data item storing the primary key values of the record to which the I-TEXT belongs
hlink_table()methodppms.data_dictionary.DataTable instancethe data table storing HLINKs for the schema
hlink_hnum_di()methodppms.data_dictionary.DataItem instancethe data item storing the number (ID)
hlink_storage()methodppms.data_dictionary.DataItem instancethe data item storing the storage type
hlink_mdate()methodppms.data_dictionary.DataItem instancethe data item storing the modification date
hlink_size()methodppms.data_dictionary.DataItem instancethe data item storing the size of actual BLOBs
hlink_ctime()methodppms.data_dictionary.DataItem instancethe data item storing the creation time
hlink_mtime()methodppms.data_dictionary.DataItem instancethe data item storing the modification time
hlink_title()methodppms.data_dictionary.DataItem instancethe data item storing the HLINK title
hlink_url()methodppms.data_dictionary.DataItem instancethe data item storing the HLINK URL
hlink_pos()methodppms.data_dictionary.DataItem instancethe data item storing the position of multi-line HLINK (functionality obsolete, provided for sanity checks)
hlink_ref_di()methodppms.data_dictionary.DataItem instancethe data item storing the data item to which the HLINK belongs
hlink_crc()methodppms.data_dictionary.DataItem instancethe data item storing the CRC checksum for the actual BLOB's data

DataTable class

Attribute TypeContentsComment
idint

schemappms.data_dictionary.DbSchema
the schema to which the table belongs
uuid_dippms.data_dictionary.DataItem
the UUID DI with object ID relevance of the table
sql_namestring
the SQL name of the associated table in the DB
has_dummiesboolean
whether this DT allows empty references in foreign keys referring to it
has_dtp_cacheboolean
whether this DT allows DTP cache (unless CU mode is enabled)
data_itemslistppms.data_dictionary.DataItem instancesall DIs belonging to the table
relationslistppms.data_dictionary.Relation instancesall relations, primary and foreign keys, belonging to the table
acr_dislistppms.data_dictionary.DataItem instancesdata items containing the ACR info for the data table

DataItem class

Attribute TypeContentsComment
idint

tableppms.data_dictionary.DataTable
the table to which the DI belongs
python_idstring

sql_namestring
the SQL name of the associated column in the DB
not_nullboolean
whether the corresponding column in DB has a NOT NULL constraint
db_typestring
which data type the DI has in DB
planta_typestring
which data type the DI has in PLANTA
df_typestring
which default data type any DF using this DI will have
di_classint

used_in_pkboolean
whether the corresponding DI is used in the primary key
used_in_fkboolean
whether the corresponding DI is used in a foreign key
formula_typestring

formulastring

Relation class

Attribute TypeContentsComment
idppms.data_dictionary.RelationId
synthetic type to represent the uniqueness criteria of Relation instances
tableppms.data_dictionary.DataTable
the table to which the relation belongs
foreign_tableppms.data_dictionary.DataTable
the table to which the relation refers
start_dippms.data_dictionary.DataItem
the first DI in the relation
end_dippms.data_dictionary.DataItem
the last DI in the relation
relation_typestring1:1, N:1, 1:N
recursion_typestringordinary, recursive, inner
namestring

DiStructure class

Attribute TypeContentsComment
idint

parent_dippms.data_dictionary.DataItem
the DI to be used in DFs
child_dippms.data_dictionary.DataItem
the DI to be used by the parent DI
functionstring