Python API Reference

From S 39.5.4

info Information
  • In PLANTA Project, Python 3.3.2 is used.
  • 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.

Up to S 39.5.4

info Information
  • In PLANTA Project, Python 3.2.4 is used.
  • In case a result of a method or function call could not be retrieved or did not exist, Python's "None" will usually be returned.
  • Empty alpha numeric fields returns an empty string.
  • For detailed information about coding conventions see: http://www.python.org/dev/peps/pep-0008/
  • String values being stored into DIs via Python API will be trimmed to fit into the maximum length specified by respective DI's DB length if necessary.

Macro example

mod_obj = ppms.get_target_module()

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

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

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

def on_reset():
    mod_obj.menu(12)

Custom exceptions

info 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

From S 39.5.14

Exception class Description Raised by
NEW PlantaRpcError defined in module csrpc.core.exceptions; base class for RPC related errors (same exists in client code) all code using csrpc
  • NEW ServiceDirectoryError
defined in module csrpc.core.exceptions; service directory related errors (service lookup failed, service already exists) csrpc service lookups or registration
  • NEW 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()
MtsError Base 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  
CustomizingError Base class for errors caused by faulty customizing  
  • KeyValueTruncationError
Raised whenever a primary key value does not fit into the corresponding DI or column search_record()
  • NEW DisabledFeatureError
Customizing tries to use a feature which was disabled by configuration e.g. client_exec()
  • NEW ReentrantModuleEvent
Module event handler calls itself, leading to stack overflow; call is intercepted  
  • NEW CircularDependencyError
Circular Data Item dependency calculation detected - python formula compilation performs an action which in turn causes dependency calculation of said Data Item again formula with a call to ppms.get_data_dictionary(), or a (nested) import containing the same, each on file scope
SessionExitForced Raised whenever an internal error forces a session to exit  
MemoryLimitExceeded Raised whenever a violation of set memory limits forces a session to exit  

From S 39.5.13

Exception class Description Raised by
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 datatable 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()
MtsError Base 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  
NEW DtpError Base class for errors within the scope of DTP related objects  
  • NEW DeletedDtpRecordError
raised whenever a DtpRecord reference is used which has already been deleted, most likely along with the corresponding DB entry  
  • NEW DeletedDataItemError
raised whenever a DataItem reference is used which has already been deleted, perhaps along with the corresponding DTP record and DB entry  
CustomizingError Base class for errors caused by faulty customizing  
  • NEW KeyValueTruncationError
Raised whenever a primary key value does not fit into the corresponding DI or column search_record()
SessionExitForced Raised whenever an internal error forces a session to exit  
MemoryLimitExceeded Raised whenever a violation of set memory limits forces a session to exit  

From S 39.5.11

Exception class Description Raised by
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 datatable 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()
MtsError Base 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  
CustomizingError Base class for errors caused by faulty customizing  
NEW SessionExitForced Raised whenever an internal error forces a session to exit  
NEW MemoryLimitExceeded Raised whenever a violation of set memory limits forces a session to exit  

From S 39.5.2

Exception class Description Raised by
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 datatable 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()
MtsError Base 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  
  • NEW DeletedRecordError
raised whenever an MtsRecord reference is used which has already been deleted, most likely along with the corresponding DTP record and DB entry  
  • NEW 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  
CustomizingError Base class for errors caused by faulty customizing  

From S 39.5.0

Exception class Description Raised by
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.
NEW DataTableError Base class for errors related to datatable objects  
  • NonexistentDataTable
whenever a nonexistent data table is passed search_record(), create_record(), DtpPool(), get_di_by_id()
NEW 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()
NEW MtsError Base 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  
NEW CustomizingError Base class for errors caused by faulty customizing  

note Class Hierarchy

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

General Functions

Python events

Function Execution 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
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

Generic functions

From S 39.5.20

Method Parameter(s) Return Value Comment
get_target_module()   returns a target module (the one which receives any module-related commands) of the running macro (returns a Module instance) warning 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) warning can't be used in value ranges
get_panels()   returns a Python list containing Panel instances of all currently opened panels warning 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

warning 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
hourglass.gif echo_off() This method is deprecated, instead use ppms.echo_disabled()   switch to echo-off-mode (don't send updates, also enables message-off-mode)
hourglass.gif echo_on() This method is deprecated, instead use ppms.echo_enabled()   switch to echo-on-mode (send all updates immediately)
hourglass.gif msg_off() This method is deprecated, instead use ppms.messages_disabled()   switch to message-off-mode (suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
hourglass.gif msg_on() This method is deprecated, instead use ppms.messages_enabled()   switch to message-on-mode (do not suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
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 none get last MessageStackItem from message-stack
hourglass.gif msg_set_assumption(id, reply) id: String

reply: int

  set assumption for message-id that should be used in message-off-mode. Stack is kept, as long as the macro runs. This method is deprecated, instead use ppms.autoreply_to_message()
hourglass.gif msg_get_assumption(id) id: String   get assumption for message-id. This method is deprecated, instead use ppms.autoreply_to_message()
hourglass.gif msg_delete_assumption(id) id: String   remove assumption for message-id. This method is deprecated, instead use ppms.autoreply_to_message()
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 number returns the changeset number of the server program
reload_server()     NEW 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.
warning 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! More information
get_server_dict()   Dictionary The function get_server_dict() actually works like the function get_session_dict().
get_query(id) id: id of a record in DT342 SQL query used 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  

From S 39.5.18

Method Parameter(s) Return Value Comment
get_target_module()   returns a target module (the one which receives any module-related commands) of the running macro (returns a Module instance) warning 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) warning can't be used in value ranges
get_panels()   returns a Python list containing Panel instances of all currently opened panels warning 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

warning 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
hourglass.gif echo_off() This method is deprecated, instead use ppms.echo_disabled()   switch to echo-off-mode (don't send updates, also enables message-off-mode)
hourglass.gif echo_on() This method is deprecated, instead use ppms.echo_enabled()   switch to echo-on-mode (send all updates immediately)
hourglass.gif msg_off() This method is deprecated, instead use ppms.messages_disabled()   switch to message-off-mode (suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
hourglass.gif msg_on() This method is deprecated, instead use ppms.messages_enabled()   switch to message-on-mode (do not suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
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 none get last MessageStackItem from message-stack
hourglass.gif msg_set_assumption(id, reply) id: String

reply: int

  set assumption for message-id that should be used in message-off-mode. Stack is kept, as long as the macro runs. This method is deprecated, instead use ppms.autoreply_to_message()
hourglass.gif msg_get_assumption(id) id: String   get assumption for message-id. This method is deprecated, instead use ppms.autoreply_to_message()
hourglass.gif msg_delete_assumption(id) id: String   remove assumption for message-id. This method is deprecated, instead use ppms.autoreply_to_message()
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 number returns the changeset number of the server program
reload_server()     advise the planta deamon to reload all preloaded server-instances 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.
warning 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! More information
get_server_dict()   Dictionary The function get_server_dict() actually works like the function get_session_dict().
get_query(id) id: id of a record in DT342 SQL query used 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() NEW   the textual contents of the system customizing errors message box  

From S 39.5.16

Method Parameter(s) Return Value Comment
get_target_module()   returns a target module (the one which receives any module-related commands) of the running macro (returns a Module instance) warning 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) warning can't be used in value ranges
get_panels()   returns a Python list containing Panel instances of all currently opened panels warning 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

warning 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
hourglass.gif echo_off() This method is deprecated, instead use ppms.echo_disabled()   switch to echo-off-mode (don't send updates, also enables message-off-mode)
hourglass.gif echo_on() This method is deprecated, instead use ppms.echo_enabled()   switch to echo-on-mode (send all updates immediately)
hourglass.gif msg_off() This method is deprecated, instead use ppms.messages_disabled()   switch to message-off-mode (suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
hourglass.gif msg_on() This method is deprecated, instead use ppms.messages_enabled()   switch to message-on-mode (do not suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
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 none get last MessageStackItem from message-stack
hourglass.gif msg_set_assumption(id, reply) id: String

reply: int

  set assumption for message-id that should be used in message-off-mode. Stack is kept, as long as the macro runs. This method is deprecated, instead use ppms.autoreply_to_message()
hourglass.gif msg_get_assumption(id) id: String   get assumption for message-id. This method is deprecated, instead use ppms.autoreply_to_message()
hourglass.gif msg_delete_assumption(id) id: String   remove assumption for message-id. This method is deprecated, instead use ppms.autoreply_to_message()
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 number returns the changeset number of the server program
reload_server()     advise the planta deamon to reload all preloaded server-instances 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.
warning 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! More information
get_server_dict()   Dictionary NEW The function get_server_dict() actually works like the function get_session_dict().
get_query(id) id: id of a record in DT342 SQL query used to read a query of table DT 343. The result of this function is cached and requires a server restart to be cleared

From S 39.5.12

Method Parameter(s) Return Value Comment
get_target_module()   returns a target module (the one which receives any module-related commands) of the running macro (returns a Module instance) warning 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) warning can't be used in value ranges
get_panels()   returns a Python list containing Panel instances of all currently opened panels warning 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

warning 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
hourglass.gif echo_off() This method is deprecated, instead use ppms.echo_disabled()   switch to echo-off-mode (don't send updates, also enables message-off-mode)
hourglass.gif echo_on() This method is deprecated, instead use ppms.echo_enabled()   switch to echo-on-mode (send all updates immediately)
hourglass.gif msg_off() This method is deprecated, instead use ppms.messages_disabled()   switch to message-off-mode (suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
hourglass.gif msg_on() This method is deprecated, instead use ppms.messages_enabled()   switch to message-on-mode (do not suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
NEW echo_disabled()     Enters a context where echo mode is disabled. Restores the old state when leaving the context. Example usage
NEW echo_enabled()     Enters a context where echo mode is enabled. Restores the old state when leaving the context. Example usage
NEW messages_disabled()     Enters a context where messages are disabled. Restores the old state when leaving the context. Example usage
NEW 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 none get last MessageStackItem from message-stack
hourglass.gif msg_set_assumption(id, reply) id: String

reply: int

  set assumption for message-id that should be used in message-off-mode. Stack is kept, as long as the macro runs. This method is deprecated, instead use ppms.autoreply_to_message()
hourglass.gif msg_get_assumption(id) id: String   get assumption for message-id. This method is deprecated, instead use ppms.autoreply_to_message()
hourglass.gif msg_delete_assumption(id) id: String   remove assumption for message-id. This method is deprecated, instead use ppms.autoreply_to_message()
msg_clear_assumptions()     remove all assumptions
NEW 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 number returns the changeset number of the server program
reload_server()     advise the planta deamon to reload all preloaded server-instances 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.
warning 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! More information
NEW get_server_dict()   Dictionary Global dictionary that is shared across all sessions on the same server
get_query(id) id: id of a record in DT342 SQL query used to read a query of table DT 343. The result of this function is cached and requires a server restart to be cleared

From S 39.5.1

Method Parameter(s) Return Value Comment
get_target_module()   returns a target module (the one which receives any module-related commands) of the running macro (returns a Module instance) warning 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) warning can't be used in value ranges
get_panels()   returns a Python list containing Panel instances of all currently opened panels warning 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

warning 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_off()     switch to echo-off-mode (don't send updates, also enables message-off-mode)
echo_on()     switch to echo-on-mode (send all updates immediately)
msg_off()     switch to message-off-mode (suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
msg_on()     switch to message-on-mode (do not suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
msg_pop()   returns MessageStackItem instance or none get last MessageStackItem from message-stack
msg_set_assumption(message-id, reply) message-id: String

reply: int

  set assumption for message-id that should be used in message-off-mode. Stack is kept, as long as the macro runs
msg_get_assumption(String message-id) message-id: String   get assumption for message-id
msg_delete_assumption(String message-id) message-id: String   remove assumption for message-id
msg_clear_assumptions()     remove all assumptions
changeset_number()   string: changeset number returns the changeset number of the server program
reload_server()     advise the planta deamon to reload all preloaded server-instances 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.
warning 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! More information
NEW get_server_dict()   Dictionary Global dictionary that is shared across all sessions on the same server
get_query(id) id: id of a record in DT342 SQL query used to read a query of table DT 343. The result of this function is cached and requires a server restart to be cleared

Up to S 39.5.1

Method Parameter(s) Return Value Comment
get_target_module()   returns a target module (the one which receives any module-related commands) of the running macro (returns a Module instance) warning 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) warning can't be used in value ranges
get_panels()   returns a Python list containing Panel instances of all currently opened panels warning 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

warning 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_off()     switch to echo-off-mode (don't send updates, also enables message-off-mode)
echo_on()     switch to echo-on-mode (send all updates immediately)
msg_off()     switch to message-off-mode (suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
msg_on()     switch to message-on-mode (do not suppress user-queries). Messages that have no assumption set are confirmed with the default answer.
msg_pop()   returns MessageStackItem instance or none get last MessageStackItem from message-stack
msg_set_assumption(message-id, reply) message-id: String

reply: int

  set assumption for message-id that should be used in message-off-mode. Stack is kept, as long as the macro runs
msg_get_assumption(String message-id) message-id: String   get assumption for message-id
msg_delete_assumption(String message-id) message-id: String   remove assumption for message-id
msg_clear_assumptions()     remove all assumptions
changeset_number()   string: changeset number returns the changeset number of the server program
reload_server()     advise the planta deamon to reload all preloaded server-instances 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.
warning 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! More information
get_query(id) id: id of a record in DT342 SQL query used to read a query of table dt343.

Global DTP functions

From S 39.5.3

Method Parameter(s) Return Value Comment
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 NEW 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

Up to S 39.5.3

Method Parameter(s) Return Value Comment
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)

di_list: int list containing required DI numbers. 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()
    ...

User interface

From S 39.5.27

  • list of functions:
Method Parameter(s) Return Value Comment
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 title returns the current system title.
ui_set_system_title(title: string) title: String   sets the system title. Strings that are longer that NEW 200 characters get truncated.

From S 39.5.12

  • list of functions:
Method Parameter(s) Return Value Comment
ui_statusbar_set(text) text: String  
  • Displays a message in the main statusbar
  • NEW In msg_off case, a MessageStackItem is created with the id "statusbar" and the text text
ui_statusbar_clear()    
  • clear main statusbar
  • NEW 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 title returns the current system title.
ui_set_system_title(title: string) title: String   sets the system title. Strings that are longer that 40 characters get truncated.

From S 39.5.0

  • list of functions:
Method Parameter(s) Return Value Comment
ui_statusbar_set(text) text: String   display a message in the main statusbar
ui_statusbar_clear()     clear main 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.
ui_message_id(id: string) id: String   displays a message for the given message id (DI MSG)
NEW ui_get_system_title()   string: system title returns the current system title.
ui_set_system_title(title: string) title: String   sets the system title. Strings that are longer that 40 characters get truncated.

Up to S 39.5.0

* list of functions:
Method Parameter(s) Return Value Comment
ui_statusbar_set(text) text: String   display a message in the main statusbar
ui_statusbar_clear()     clear main 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.
ui_message_id(id: string) id: String   displays a message for the given message id (DI MSG)
ui_set_system_title(title: string) title: String   sets the system title. Strings that are longer that 40 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())

New from S 39.5.12

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:
more 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

more Controlling the message state

from ppms import ppms

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

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

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

  • When the message or echo context is disabled messages that would normally be shown to the client are hidden and replied to 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]

Session export

Used to start and export the logfile information of the current session. Can be used for monitoring or testing purpose for example.
Method Parameter(s) Return Value Comment
session_export_start(filename) filename: String function returns boolean: True if starting session export succeeded, False otherwise If 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 otherwise no success may indicate that no session was started or e.g. disk full
session_export_is_enabled()   return boolean True if enabled, False otherwise

note Note:

  • The file is encoded in UTF-8. It can be opened in Python with the correct encoding:
  • Example:
with open(filename, encoding='utf-8') as log: log_txt = log.read() 

Server execute script

Method Parameter(s) Return Value Comment
get_current_server_script()   returns the last executed server script (in string format) or None is used in source provider for debugger only

Service functions

From S 39.5.15

Method Parameter(s) Return Value Comment
start_service(function, timeinterval) function: function
timeinterval: Integer
None add into service function list Python function that will be executed periodically on the server in passed timeinterval (milliseconds)  
get_services()   dict Returns a dictionary of function: [interval, last_executed]
stop_service(function) function: function None removes Python function from service function list, so server stops periodical execution

note 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 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
  • NEW 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

Up to S 39.5.15

Method Parameter(s) Return Value Comment
start_service(function, timeinterval) function: function
timeinterval: Integer
None add into service function list Python function that will be executed periodically on the server in passed timeinterval (milliseconds)  
get_services()   dict Returns a dictionary of function: [interval, last_executed]
stop_service(function) function: function None removes Python function from service function list, so server stops periodical execution

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

User variables

Method Parameter(s) Return Value Comment
uvar_get(uvar_id: string) uvar_id: String returns a value of the given variable.

warning 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 otherwise sets value of the given variable (@D, @G or @M )

Timer functions

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

From S 39.5.10

Method Parameter(s) Return Value Comment
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() NEW     Starts performance counting globally: from then, performance data from all active and new sessions is written into the table.
performance_counting_disable() NEW     Stops performance counting globally
performance_counting_is_enabled() NEW   int: 0 for disabled, 1 for enabled Returns whether performance counting is currently enabled

Up to S 39.5.10

Method Parameter(s) Return Value Comment
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)

New from S 39.5.11

Record limiting

info 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.

Method Parameter(s) Return Value Comment
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.
warning 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.
warning 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

info 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.

From S 39.5.20

info 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 NEW
  • 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()

more 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

Method Parameter(s) Return Value Comment
db_get_auto_commit()   returns True if the auto commit is on, False otherwise  
hourglass.gif 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 type This 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 not Writes 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.
warning 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 statements Returns 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 string Intended 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)

From S 39.5.15

info Commit/Transactional Behavior

  • In the default behavior, every change via the python function db_modify() is automatically stored (equivalent to auto commit).
  • This can be switched off using autocommit_disabled().
  • Every statement that is executed afterwards just manipulates the data in an 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)
  • When a transaction is opened (no matter whether from python context or by native code), all statements from the session are executed in this transaction context.
  • This includes the automatic ID generation mechanism; safety against concurrent writes in the automatic id tables is given by locking the changed automatic ID record.
  • If a user has customizing permission, warning messages appear in the following situations:
    • If a transaction is open and calling autocommit_enabled(): "IE: forced commit when switching to auto commit"
    • If auto commit behavior is not reset before leaving a context: "IE: auto commit behavior was changed when running <context>, reset is forced!"

more 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

Method Parameter(s) Return Value Comment
db_get_auto_commit()   returns True if the auto commit is on, False otherwise  
hourglass.gif db_set_auto_commit(state) state: Boolean   This method is deprecated, instead use with ppms.autocommit_disabled() or with ppms.autocommit_enabled()
NEW autocommit_disabled()     Enters a context where auto commit is disabled. Restores the old state when leaving the context.
NEW 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 type This 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 not Writes 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.
warning 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 statements Returns 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 string Intended 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)

From S 39.5.0

info Commit/Transactional Behavior

  • In the default behavior, every change via the python function db_modify() is automatically stored (equivalent to auto commit).
  • This can be switched off using db_set_auto_commit(False).
  • Every statement that is executed afterwards just manipulates the data in an implicitely opened transaction.
  • Only during the following statements/events, the changes are commited to the database:
    1. when calling db_commit()
    2. when calling db_set_auto_commit(True)
    3. when leaving a macro context that initially switched off autocommit (as implicitely the auto_commit behavior of "parent macros" is restored)
  • When a transaction is opened (no matter whether from python context or by native code), all statements from the session are executed in this transaction context.
  • This includes the automatic ID generation mechanism; safety against concurrent writes in the automatic id tables is given by locking the changed automatic ID record.
  • If a user has customizing permission, warning messages appear in the following situations:
    • If a transaction is open and calling db_set_auto_commit(True): "IE: forced commit when switching to auto commit"
    • If auto commit behavior is not reset before leaving a context: "IE: auto commit behavior was changed when running <context>, reset is forced!"

Method Parameter(s) Return Value Comment
db_get_auto_commit()   returns True if the auto commit is on, False otherwise  
db_set_auto_commit(state) state: Boolean   takes boolean argument, enables or disables auto commit
db_commit()     commits the pending DB operations
db_rollback()     rolls back any pending operations
db_get_dbms_name()   Number indicating the database type This 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)
NEW 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 not Writes the current database schema to file system, which can then later be used to generate a similar database
NEW 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.
warning With MSSQL this function can only be used after commiting all former changes, otherwise this can lead to deadlocks.
NEW 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 statements Returns 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
NEW db_get_current_dialect()   Returns the name of current Hibernate dialect as a string Intended 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)

Up to S 39.5.0

Method Parameter(s) Return Value Comment
db_get_auto_commit()   returns True if the auto commit is on, False otherwise  
db_set_auto_commit(state) state: Boolean   takes boolean argument, enables or disables auto commit
db_commit()     commits the pending DB operations
db_rollback()     rolls back any pending operations
db_get_dbms_name()   Number indicating the database type This 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)

Validating records

From S 39.5.15

info 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

Method Parameter(s) Return Value Comment
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()
NEW are_all_entities_validated   returns True if entities are currently validated, False if not Note: 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)
NEW 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 not Note: 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 )
NEW 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
NEW 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

more 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

New from S 39.5.14

info 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

Method Parameter(s) Return Value Comment
enable_validation_for_all_entities()     Enables validating of all entities (standard behaviour). This deletes any exceptions defined by disable_validation_for_entity
disable_validation_for_all_entities()     disables validating of all entities (standard behaviour). This deletes any exceptions defined by enable_validation_for_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

New from S 39.5.0

Session monitoring

info Information

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

Method Parameter(s) Return Value Comment
get_current_session_uuid()   returns a unique, system-wide UUID that identifies the current session Current 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 startup This 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/active The 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.
note 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 noteNote that this value is defined as seconds, not milliseconds
noteThe 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)
  noteNote that this value is defined as seconds, not milliseconds.
noteThe 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 originally The 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 terminated The 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.
note 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
noteThe 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  

New from 39.5.15

Protocol version

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

MTS data

General functions

Method Parameter(s) Return Value Comment
get_active_module()   returns a module (Module instance) that was a target of the currently processed event e.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

Method Parameter(s) Return Value Comment
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 Panel includes main module
set_title_suffix(suffix:string) suffix: string (a string to be appended to the panel's title) None Set 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.

From S 39.5.15

Method Parameter(s) Return Value Comment
get_uid()   int: Internal UID of the module  
get_id()   string: customizing ID of the module (e.g. 009845)  
get_root(position) position: int (root position, 0..4) Root instance: root at the given position  
get_das()   list: of all data areas in the module (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 IDs bool: True on success, False on failure You 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 module Opens a new module in the context of this module.

If a module macro is running, the newly opened module will become a current target module of the macro.

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 module Opens 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  
hourglass.gif get_macro_invoker_dfc() This method is deprecated and replaced by get_invocation_customizing.    
NEW 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 strings returns the modules @L Structure that is used for passing it to an invoked module
get_current_L_var()   dict: key is variable number, value is list of strings returns the modules @L Structure that was given by the invoking module  
set_new_L_var(var_no, values) var_no: number of @L variable

values: a list of values

bool: Sets the @L variables of the next module that will be called from the current one
NEW 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: string string: id of the newly created MV creates new MV with give title using current module CU settings
delete_mv_by_id(id) id: string bool: succes/failure indication deletes MV of given name from DB, updates all affected MV comboboxes and resets to base CU those modules that had the MV applied at the time of its deletion
save_mv_by_id(id = None) id: string, optional bool: success/failure indicator stores current CU changes into MV of given id; the MV must already exist; if id is not specified (is None), currently applied MV's id will be used
apply_mv_by_id(id) id: string bool: success/failure indicator applies MV of given ID to module's CU
apply_mv_by_title(title) title: string bool: success/failure indicator applies MV of given title to module's CU (assumes the title is unique across the entire list of module's MVs)
get_applied_mv_id()   string: id of currently applied MV  
focus()     Gives the module an input focus on client- as well as on server side. Same effect as if user clicked inside the module to give it a focus.
reset_cu()     Sets the module variants back to base setting
refresh_dts(dt_numbers) dt_numbers: a tuple containing numbers of affected DTs   reselects records for all DAs in the module that use one of the given DTs as their determining DT; intended to be used after TCalc to refresh contents of those DTs that can get new records during the TCalc process; example use: mod.refresh_dts((472, 888))
has_unsaved_changes()   bool: True if the module was changed and it wasn't saved, False otherwise  
enableChangesIndicator()     This method will enable the "asterisk"-mechanism of the current module. An asterisk is shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already not shown it will still be not shown)
disableChangesIndicator()     This method will disable the "asterisk"-mechanism of the current module. An asterisk is no longer shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already shown it will still be shown).
getChangesIndicator()   bool: True if the module's title would include an asterisk * if it had unsaved changes, False otherwise.  
get_python_macro()   returns the python module of a customized macro offers access to all functions and names that are customized in the modules macro

From S 39.5.3

Method Parameter(s) Return Value Comment
get_uid()   int: Internal UID of the module  
get_id()   string: customizing ID of the module (e.g. 009845)  
get_root(position) position: int (root position, 0..4) Root instance: root at the given position  
get_das()   list: of all data areas in the module (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) DataArea instance: DataArea with specified customizing name from dg410  
get_customizing()   ModuleCustomizing instance: customizing for this module instance  
set_statusbar(text) text: string (text to be displayed) int: 0 for failure, anything else for success  
clear_statusbar()   int:  
message_box(caption, text) caption: string
text: string
  displays a module-specific modal message box with OK button, specified caption and text message
get_roots()   list: of Root instances from the given module  
menu(id) id: ID of the menu item (command) to activate. See Menüpunkte for a list of possible IDs bool: True on success, False on failure You 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 module Opens a new module in the context of this module.

If a module macro is running, the newly opened module will become a current target module of the macro.

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 module Opens 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  
hourglass.gif get_macro_invoker_dfc() This method is deprecated and replaced by get_invocation_customizing.    
NEW 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 strings returns the modules @L Structure that is used for passing it to an invoked module
get_current_L_var()   dict: key is variable number, value is list of strings returns the modules @L Structure that was given by the invoking module  
set_new_L_var(var_no, values) var_no: number of @L variable

values: a list of values

bool: Sets the @L variables of the next module that will be called from the current one
set_current_L_var(var_no, values) var_no: number of @L variable

values: a list of values

bool: Sets the @L variables of the current module
create_mv(title) title: string string: id of the newly created MV creates new MV with give title using current module CU settings
delete_mv_by_id(id) id: string bool: succes/failure indication deletes MV of given name from DB, updates all affected MV comboboxes and resets to base CU those modules that had the MV applied at the time of its deletion
save_mv_by_id(id = None) id: string, optional bool: success/failure indicator stores current CU changes into MV of given id; the MV must already exist; if id is not specified (is None), currently applied MV's id will be used
apply_mv_by_id(id) id: string bool: success/failure indicator applies MV of given ID to module's CU
apply_mv_by_title(title) title: string bool: success/failure indicator applies MV of given title to module's CU (assumes the title is unique across the entire list of module's MVs)
get_applied_mv_id()   string: id of currently applied MV  
focus()     Gives the module an input focus on client- as well as on server side. Same effect as if user clicked inside the module to give it a focus.
reset_cu()     Sets the module variants back to base setting
refresh_dts(dt_numbers) dt_numbers: a tuple containing numbers of affected DTs   reselects records for all DAs in the module that use one of the given DTs as their determining DT; intended to be used after TCalc to refresh contents of those DTs that can get new records during the TCalc process; example use: mod.refresh_dts((472, 888))
has_unsaved_changes()   bool: True if the module was changed and it wasn't saved, False otherwise  
enableChangesIndicator()     This method will enable the "asterisk"-mechanism of the current module. An asterisk is shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already not shown it will still be not shown)
disableChangesIndicator()     This method will disable the "asterisk"-mechanism of the current module. An asterisk is no longer shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already shown it will still be shown).
getChangesIndicator()   bool: True if the module's title would include an asterisk * if it had unsaved changes, False otherwise.  
get_python_macro()   returns the python module of a customized macro offers access to all functions and names that are customized in the modules macro

From S 39.5.0

Method Parameter(s) Return Value Comment
get_uid()   int: Internal UID of the module  
get_id()   string: customizing ID of the module (e.g. 009845)  
get_root(position) position: int (root position, 0..4) Root instance: root at the given position  
get_das()   list: of all data areas in the module (MtsDataArea instances)  
NEW 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) DataArea instance: DataArea with specified customizing name from dg410  
get_customizing()   ModuleCustomizing instance: customizing for this module instance  
set_statusbar(text) text: string (text to be displayed) int: 0 for failure, anything else for success  
clear_statusbar()   int:  
message_box(caption, text) caption: string
text: string
  displays a module-specific modal message box with OK button, specified caption and text message
get_roots()   list: of Root instances from the given module  
menu(id) id: ID of the menu item (command) to activate. See Menüpunkte for a list of possible IDs bool: True on success, False on failure You 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 module Opens a new module in the context of this module.

If a module macro is running, the newly opened module will become a current target module of the macro.

NEW 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 module Opens 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()   DataFieldCustomizing instance : returns the data field customizing which defined the context menu item that invoked the module (or None if module was not invoked by context menu) It is recommended that this function is called for the macro_module, not the target_module, since modules do NOT inherit this attribute to their sub modules or their invoked modules. Therefore, if a menu item calls a macro module, only this macro module knows the dfc which defined its context menu item.
get_new_L_var()   dict:: key is variable number, value is list of strings returns the modules @L Structure that is used for passing it to an invoked module
get_current_L_var()   dict: key is variable number, value is list of strings returns the modules @L Structure that was given by the invoking module  
set_new_L_var(var_no, values) var_no: number of @L variable

values: a list of values

bool: Sets the @L variables of the next module that will be called from the current one
set_current_L_var(var_no, values) var_no: number of @L variable

values: a list of values

bool: Sets the @L variables of the current module
create_mv(title) title: string string: id of the newly created MV creates new MV with give title using current module CU settings
delete_mv_by_id(id) id: string bool: succes/failure indication deletes MV of given name from DB, updates all affected MV comboboxes and resets to base CU those modules that had the MV applied at the time of its deletion
save_mv_by_id(id = None) id: string, optional bool: success/failure indicator stores current CU changes into MV of given id; the MV must already exist; if id is not specified (is None), currently applied MV's id will be used
apply_mv_by_id(id) id: string bool: success/failure indicator applies MV of given ID to module's CU
apply_mv_by_title(title) title: string bool: success/failure indicator applies MV of given title to module's CU (assumes the title is unique across the entire list of module's MVs)
get_applied_mv_id()   string: id of currently applied MV  
focus()     Gives the module an input focus on client- as well as on server side. Same effect as if user clicked inside the module to give it a focus.
reset_cu()     Sets the module variants back to base setting
refresh_dts(dt_numbers) dt_numbers: a tuple containing numbers of affected DTs   reselects records for all DAs in the module that use one of the given DTs as their determining DT; intended to be used after TCalc to refresh contents of those DTs that can get new records during the TCalc process; example use: mod.refresh_dts((472, 888))
has_unsaved_changes()   bool: True if the module was changed and it wasn't saved, False otherwise  
enableChangesIndicator()     This method will enable the "asterisk"-mechanism of the current module. An asterisk is shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already not shown it will still be not shown)
disableChangesIndicator()     This method will disable the "asterisk"-mechanism of the current module. An asterisk is no longer shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already shown it will still be shown).
getChangesIndicator()   bool: True if the module's title would include an asterisk * if it had unsaved changes, False otherwise.  
get_python_macro() NEW   returns the python module of a customized macro offers access to all functions and names that are customized in the modules macro

Up to S 39.5.0

Method Parameter(s) Return Value Comment
get_uid()   int: Internal UID of the module  
get_id()   string: customizing ID of the module (e.g. 009845)  
get_root(position) position: int (root position, 0..4) Root instance: root at the given position  
get_das()   list: of all data areas in the module (MtsDataArea instances)  
get_da(name) name: string (customizing name) DataArea instance: DataArea with specified customizing name from dg410  
get_customizing()   ModuleCustomizing instance: customizing for this module instance  
set_statusbar(text) text: string (text to be displayed) int: 0 for failure, anything else for success  
clear_statusbar()   int:  
message_box(caption, text) caption: string
text: string
  displays a module-specific modal message box with OK button, specified caption and text message
get_roots()   list: of Root instances from the given module  
menu(id) id: ID of the menu item (command) to activate. See Menüpunkte for a list of possible IDs bool: True on success, False on failure You 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 module Opens a new module in the context of this module.

If a module macro is running, the newly opened module will become a current target module of the macro.

is_stub()   bool: True if the module is a stub module (it was only loaded as a framework for performance reasons), False if module was loaded completely  
get_invoker_module()   Module instance or None if no invoker module is linked  
get_panel()   Panel instance: of Module  
get_invoker_rec()   MtsRecord instance: returns the record from which module was invoked  
get_macro_invoker_dfc()   DataFieldCustomizing instance : returns the data field customizing which defined the context menu item that invoked the module (or None if module was not invoked by context menu) It is recommended that this function is called for the macro_module, not the target_module, since modules do NOT inherit this attribute to their sub modules or their invoked modules. Therefore, if a menu item calls a macro module, only this macro module knows the dfc which defined its context menu item.
get_new_L_var()   dict:: key is variable number, value is list of strings returns the modules @L Structure that is used for passing it to an invoked module
get_current_L_var()   dict: key is variable number, value is list of strings returns the modules @L Structure that was given by the invoking module  
set_new_L_var(var_no, values) var_no: number of @L variable

values: a list of values

bool: Sets the @L variables of the next module that will be called from the current one
set_current_L_var(var_no, values) var_no: number of @L variable

values: a list of values

bool: Sets the @L variables of the current module
create_mv(title) title: string string: id of the newly created MV creates new MV with give title using current module CU settings
delete_mv_by_id(id) id: string bool: succes/failure indication deletes MV of given name from DB, updates all affected MV comboboxes and resets to base CU those modules that had the MV applied at the time of its deletion
save_mv_by_id(id = None) id: string, optional bool: success/failure indicator stores current CU changes into MV of given id; the MV must already exist; if id is not specified (is None), currently applied MV's id will be used
apply_mv_by_id(id) id: string bool: success/failure indicator applies MV of given ID to module's CU
apply_mv_by_title(title) title: string bool: success/failure indicator applies MV of given title to module's CU (assumes the title is unique across the entire list of module's MVs)
get_applied_mv_id()   string: id of currently applied MV  
focus()     Gives the module an input focus on client- as well as on server side. Same effect as if user clicked inside the module to give it a focus.
reset_cu()     Sets the module variants back to base setting
refresh_dts(dt_numbers) dt_numbers: a tuple containing numbers of affected DTs   reselects records for all DAs in the module that use one of the given DTs as their determining DT; intended to be used after TCalc to refresh contents of those DTs that can get new records during the TCalc process; example use: mod.refresh_dts((472, 888))
has_unsaved_changes()   bool: True if the module was changed and it wasn't saved, False otherwise  
enableChangesIndicator()     This method will enable the "asterisk"-mechanism of the current module. An asterisk is shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already not shown it will still be not shown)
disableChangesIndicator()     This method will disable the "asterisk"-mechanism of the current module. An asterisk is no longer shown in the title of the module on further changes. The current state of the asterisk is not changed (If it is already shown it will still be shown).
getChangesIndicator()   bool: True if the module's title would include an asterisk * if it had unsaved changes, False otherwise.  

New from S 39.5.16

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

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

more Why is this useful?

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

from ppms import ppms

mod_obj = ppms.get_macro_module()

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

Root class

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

Method Parameter(s) Return Value Comment
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 warning 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 instance Gets 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 instance Gets 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 failure inserts 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 failure inserts a record into the specified top-level-da

DataArea class

From S 39.5.2

Method Parameter(s) Return Value Comment
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 NULL Only 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  
NEW insert_record()   MtsRecord instance just inserted, None if insertion failed  

Up to S 39.5.2

Method Parameter(s) Return Value Comment
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 NULL Only 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  

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

From S 39.5.0

Method Parameter(s) Return Value Comment
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  
NEW 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  
NEW 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 otherwise This 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 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).
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).
warning 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 failed Inserts a new inner recursive child into given record
insert_before()   MtsRecord instance of the record we inserted, None if insertion failed Inserts a new sibling record before given record
insert_after()   MtsRecord instance of the record we inserted, None if insertion failed Inserts 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  
NEW copy_before(destination) MtsRecord instance before which to copy Boolean, whether the operation was successful Performs the same operation as Drag&Drop copy records when dropping before the destination record, selection sensitive
NEW copy_into(destination) MtsRecord instance into which to copy Boolean, whether the operation was successful Performs the same operation as Drag&Drop copy records when dropping into the destination record, selection sensitive
NEW copy_after(destination) MtsRecord instance after which to copy Boolean, whether the operation was successful Performs the same operation as Drag&Drop copy records when dropping after the destination record, selection sensitive
NEW move_before(destination) MtsRecord instance before which to move Boolean, whether the operation was successful Performs the same operation as Drag&Drop move records when dropping before the destination record, selection sensitive
NEW move_into(destination) MtsRecord instance into which to copy Boolean, whether the operation was successful Performs the same operation as Drag&Drop move records when dropping into the destination record, selection sensitive
NEW move_after(destination) MtsRecord instance after which to copy Boolean, whether the operation was successful Performs the same operation as Drag&Drop move records when dropping after the destination record, selection sensitive

Up to S 39.5.0

Method Parameter(s) Return Value Comment
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 (defined in dt412 or alternatively in dg411) 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  
is_marked()   bool: True if the record is marked, False otherwise This 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 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).
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).
warning 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 failed Inserts a new inner recursive child into given record
insert_before()   MtsRecord instance of the record we inserted, None if insertion failed Inserts a new sibling record before given record
insert_after()   MtsRecord instance of the record we inserted, None if insertion failed Inserts 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  

DataField class

(display DF, a wrapper for mts_disp_df data structure)

From S 39.5.17

Method Parameter(s) Return Value Comment
NEU 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 DI int:
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 user int: 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 False Checks if the DF is an input field
make_output()   bool: Overrides DF's customizing, making it behave as an output field.
stop 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 found customizing 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 set bool: true if the symbol was successfully set  
set_hdg_symbol(symbol_id) symbol_id: id of symbol of DF to be set bool: true if the symbol was successfully set  
copy_field2field(destination) destination: DataField instance Boolean: whether the operation was successful Performs the same operation as Drag&Drop field-to-field
copy_field2column(destination) destination: DataField instance Boolean: whether the operation was successful Performs the same operation as Drag&Drop field-to-column, selection sensitive
copy_column2column(destination) destination: DataField instance Boolean: whether the operation was successful Performs the same operation as Drag&Drop column-to-column, selection sensitive

From S 39.5.7

Method Parameter(s) Return Value Comment
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  
NEW set_raw_value(value) value: data type must match the one that is used by the DF's underlying DI int:
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
NEW set_text_value(value) value: string representation of the value, is treated the same way as the text value filled in by the user int: 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 False Checks if the DF is an input field
make_output()   bool: Overrides DF's customizing, making it behave as an output field
stop 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 found customizing 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 set bool: true if the symbol was successfully set  
set_hdg_symbol(symbol_id) symbol_id: id of symbol of DF to be set bool: true if the symbol was successfully set  
copy_field2field(destination) destination: DataField instance Boolean: whether the operation was successful Performs the same operation as Drag&Drop field-to-field
copy_field2column(destination) destination: DataField instance Boolean: whether the operation was successful Performs the same operation as Drag&Drop field-to-column, selection sensitive
copy_column2column(destination) destination: DataField instance Boolean: whether the operation was successful Performs the same operation as Drag&Drop column-to-column, selection sensitive

Up to S 39.5.7

Method Parameter(s) Return Value Comment
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 DI bool: for Python value ranges, only processInput is executed, checkInput is ignored.
set_text_value(value) value: string representation of the value, is treated the same way as the text value filled in by the user bool: 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 False Checks if the DF is an input field
make_output()   bool: Overrides DF's customizing, making it behave as an output field
stop 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 found customizing 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 set bool: true if the symbol was successfully set  
set_hdg_symboll(symbol_id) symbol_id: id of symbol of DF to be set bool: true if the symbol was successfully set  
copy_field2field(destination) destination: DataField instance Boolean: whether the operation was successful Performs the same operation as Drag&Drop field-to-field
copy_field2column(destination) destination: DataField instance Boolean: whether the operation was successful Performs the same operation as Drag&Drop field-to-column, selection sensitive
copy_column2column(destination) destination: DataField instance Boolean: whether the operation was successful Performs 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)
Method Parameter(s) Return Value Comment
get_id()   String: returns message-id  
get_text()   String: returns message-text  
get_reply()   Int: returns button-id 0 = 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 strings for 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

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

Method Parameter(s) Return Value Comment
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 DA  

RootCustomizing Class

Method Parameter(s) Return Value Comment
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))

From S 39.5.0

Method Parameter(s) Return Value Comment
get_id()   string: customizing ID of the DA
*can raise DataItemError*
 
get_name()   string: customizing name of the DA Returns 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 parent This 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 name DI041036
DI-Python-ID
set_sym_area_sep_w1(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Datensatztrennung F1
get_sym_area_sep_w1()   string: ID of the symbol Symbol Datensatztrennung F1
set_sym_area_sep_w2(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Datensatztrennung F2
get_sym_area_sep_w2()   string: ID of the symbol Symbol Datensatztrennung F2
set_sym_area_sep_w3(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Datensatztrennung F3
get_sym_area_sep_w3()   string: ID of the symbol Symbol Datensatztrennung F3
set_sym_frame_w1(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Rahmen F1
get_sym_frame_w1()   string: ID of the symbol Symbol Rahmen F1
set_sym_frame_w2(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Rahmen F2
get_sym_frame_w2()   string: ID of the symbol Symbol Rahmen F2
set_sym_frame_w3(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Rahmen F3
get_sym_frame_w3()   string: ID of the symbol Symbol Rahmen F3
disable_satisfaction() None None Erfüllung
enable_satisfaction() None None Erfüllung
only works when satisfaction rule is not empty
has_satisfaction() None satisfaction enabled ? true : false Erfüllung
get_satisfaction() None string: satisfaction rule Erfüllungsregel
set_satisfaction(rule) rule: string (satisfaction rule) None Erfüllungsregel
set_to_output() None None Ausgabe
set_to_input() None None Ausgabe
is_readonly() None is output ? true : false Ausgabe
set_never_display() None None Nie anzeigen
unset_never_display() None None Nie anzeigen
is_never_display() None is never display ? true : false Nie anzeigen
NEW 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  
NEW 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] None Anzeige
get_display_behavior() None display-behavior in {0, 1, 2, 3} Anzeige
set_permission_create() None None Anlegen
unset_permission_create() None None Anlegen
has_permission_create() None has permission create ? true : false Anlegen
set_permission_insert() None None Einfügen
unset_permission_insert() None None Einfügen
has_permission_insert() None has permission insert ? true : false Einfügen
set_permission_move() None None Verschieben
unset_permission_move() None None Verschieben
has_permission_move() None has permission move ? true : false Verschieben
set_permission_delete() None None Löschen
unset_permission_delete() None None Löschen
has_permission_delete() None has permission delete ? true : false Löschen

Up to S 39.5.0

Method Parameter(s) Return Value Comment
get_id()   string: customizing id of the DA
*can raise DataItemError*
 
get_name()   string: customizing name of the da Returns 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 parent This 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 (cust-name of dfc defined in dg411 or dg412) DataFieldCustomizing instance: customizing of the DF with given cust-name DI041036
DI-Python-ID
set_sym_area_sep_w1(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Datensatztrennung F1
get_sym_area_sep_w1()   string: ID of the symbol Symbol Datensatztrennung F1
set_sym_area_sep_w2(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Datensatztrennung F2
get_sym_area_sep_w2()   string: ID of the symbol Symbol Datensatztrennung F2
set_sym_area_sep_w3(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Datensatztrennung F3
get_sym_area_sep_w3()   string: ID of the symbol Symbol Datensatztrennung F3
set_sym_frame_w1(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Rahmen F1
get_sym_frame_w1()   string: ID of the symbol Symbol Rahmen F1
set_sym_frame_w2(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Rahmen F2
get_sym_frame_w2()   string: ID of the symbol Symbol Rahmen F2
set_sym_frame_w3(symbol_id) symbol_id: string (ID of the symbol) None: Symbol Rahmen F3
get_sym_frame_w3()   string: ID of the symbol Symbol Rahmen F3
disable_satisfaction() None None Erfüllung
enable_satisfaction() None None Erfüllung
only works when satisfaction-rule is not empty
has_satisfaction() None satisfaction enabled ? true : false Erfüllung
get_satisfaction() None string: satisfaction rule Erfüllungsregel
set_satisfaction(rule) satisfaction-rule: string None Erfüllungsregel
set_to_output() None None Ausgabe
set_to_input() None None Ausgabe
is_readonly() None is output ? true : false Ausgabe
set_never_display() None None Nie anzeigen
unset_never_display() None None Nie anzeigen
is_never_display() None is never display ? true : false Nie anzeigen
set_display_behavior(d-behavior) d.-behavior in [0..3] None Anzeige
get_display_behavior() None display-behavior in {0, 1, 2, 3} Anzeige
set_permission_create() None None Anlegen
unset_permission_create() None None Anlegen
has_permission_create() None has permission create ? true : false Anlegen
set_permission_insert() None None Einfügen
unset_permission_insert() None None Einfügen
has_permission_insert() None has permission insert ? true : false Einfügen
set_permission_move() None None Verschieben
unset_permission_move() None None Verschieben
has_permission_move() None has permission move ? true : false Verschieben
set_permission_delete() None None Löschen
unset_permission_delete() None None Löschen
has_permission_delete() None has permission delete ? true : false Löschen

DataFieldCustomizing Class

Method Parameter(s) Return Value Comment
get_id()   int: customizing ID of the DF DF-ID  
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 DA  
get_dac()   DataAreaCustomizing instance: DAC for this DFC  
get_df_config() string Created 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/bool None:  
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 up None: Show this DF column
hide()   None: Hide this DF column

ModuleVariant Class

Method Parameter(s) Return Value Comment
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 MV possible 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

Method Parameter(s) Return Value Comment
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))

From S 39.5.3

Method Parameter(s) Return Value Comment
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_children(dt, NEW di_list=None, NEW 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 table di_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);
warning 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)

stop Attention: 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 record Meaning 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

Up to S 39.5.3

Method Parameter(s) Return Value Comment
get_di_by_id(number) number : int (number of the DI) DataItem instance from the DataRecord with the given number
*can raise DataItemError*
 
get_di(name) name: string (customizing-name) DataItem instance from the DataRecord with the given cust-name from dt412
*can raise DataItemError*
 
get_children(dt) dt: int (data table number) returns list of direct children of current record which are from passed data table  
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);
warning this list can be applied only to UPDATE operation, not to INSERT operation. A 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)

stop Attention: 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 record Meaning 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

From S 39.5.7

Method Parameter(s) Return Value Comment
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 type Is 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
get_dtp_record()   DtpRecord instance: for this DataItem  
get_dfs()   list: of DataField instances which contain DataItem  
NEW 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.
NEW 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()   string Customizing id of the DI (value of DI)
get_customizing_name()   string: None if no customizing id found Customizing 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 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)

Up to S 39.5.7

Method Parameter(s) Return Value Comment
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 type Is 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
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:
  • 0: SUCCESS

  • 1: General FAILURE

  • 2: Wrong Format

  • 3: Refused because DI is used in primary key

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
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)   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()   string Customizing id of the DI (value of DI)
get_customizing_name()   string: None if no customizing id found Customizing 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. If this is not a hyperlink object, but it belongs to a Hyperlink's record in a schema's Hyperlink data table, the Hyperlink for this record 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 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

From S 39.5.12

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.

Method Parameter(s) Return Value Comment
get_id()   int: The internal ID used to identify this hyperlink Together with the schema, this identifies this hyperlink's record in its hyperlink table
get_schema()   string: A short string for the schema of this Hyperlink, e.g. "Q5B" Together with the id, this identifies this hyperlink's record in its hyperlink table
get_uid()   string: Unique, system-wide id that identifies this hyperlink hl.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 now May be different from initial_crc if another Client updated this object in your database
get_database_crc()   int: The crc field of this hyperlink in its hyperlink table Should be identical to get_current_crc()
get_title()   string: The title in the data item that connects to this hyperlink  
get_url()   string: The destination and name of this hyperlink's data file  
get_hyperlink_di()   DataItem instance: The data item that links to this Hyperlink object  
get_record()   DtpRecord instance: The record that contains this hyperlink's attributes Every DB schema stores its hyperlinks in its own data table. Note that this record also contains the binary file of this hyperlink (as a blob), but you cannot directly access this Blob object with the usual dtp-record-methods. Use the Hyperlink's methods get_blob() and set_value to do this.
get_blob()   ByteArray: The binary object of this hyperlink (Blob object in the database) note 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 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 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.

NEW 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 otherwise Removes the binary object that defines this hyperlink. The hyperlink itself (= the structural representation including title and filename) remains unchanged. Note that the binary is not yet deleted in the database, but it will be once its hyperlink di (or the hyperlink record itself) is saved
delete()   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

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

New from S 39.5.0

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.

Method Parameter(s) Return Value Comment
get_id()   int: The internal ID used to identify this hyperlink Together with the schema, this identifies this hyperlink's record in its hyperlink table
get_schema()   string: A short string for the schema of this Hyperlink, e.g. "Q5B" Together with the id, this identifies this hyperlink's record in its hyperlink table
get_uid()   string: Unique, system-wide id that identifies this hyperlink hl.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 now May be different from initial_crc if another Client updated this object in your database
get_database_crc()   int: The crc field of this hyperlink in its hyperlink table Should be identical to get_current_crc()
get_title()   string: The title in the data item that connects to this hyperlink  
get_url()   string: The destination and name of this hyperlink's data file  
get_hyperlink_di()   DataItem instance: The data item that links to this Hyperlink object  
get_record()   DtpRecord instance: The record that contains this hyperlink's attributes Every DB schema stores its hyperlinks in its own data table. Note that this record also contains the binary file of this hyperlink (as a blob), but you cannot directly access this Blob object with the usual dtp-record-methods. Use the Hyperlink's methods get_blob and set_value to do this.
get_blob()   ByteArray: The binary object of this hyperlink (Blob object in the database) note 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 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 Note that only server-based hyperlinks have their own blob-object. If this Hyperlink belongs to a di that is client-based, only the parameter filename is updated, the parameter binary will be ignored.

delete_blob()   bool: True if deleting was successful, False otherwise Removes the binary object that defines this hyperlink. The hyperlink itself (= the structural representation including title and filename) remains unchanged. Note that the binary is not yet deleted in the database, but it will be once its hyperlink di (or the hyperlink record itself) is saved
delete()   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

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

Server Python modules

info 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

info 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 module Usage
constants.py Provides access to several constants
global_setting.py Provides access to global settings
sql.py Provides access to SQL utilities
text_constant.py Provides access to text constants
user_interface/dialog.py Provides access to dialog message handling

Example

target-blue 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
application Example
from ppms import global_setting

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

Value Ranges

info Further methods for Python value ranges

From S 39.5.15

Data Dictionary Access

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

target-blue 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.

note 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.

warning NEW 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.

application Example

from ppms import ppms, data_dictionary

ddict = ppms.get_data_dictionary()

DataDictionary class

Attribute Type Contents Comment
db_schemas dictionary ppms.data_dictionary.DbSchema ordered by id
data_tables dictionary ppms.data_dictionary.DataTable ordered by id
data_items dictionary ppms.data_dictionary.DataItem ordered by id
relations dictionary ppms.data_dictionary.Relation ordered by id
di_structures dictionary ppms.data_dictionary.DiStructure ordered by id

DbSchema class

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

DataTable class

Attribute Type Contents Comment
id int    
schema ppms.data_dictionary.DbSchema   the schema to which the table belongs
uuid_di ppms.data_dictionary.DataItem   the UUID DI with object ID relevance of the table
sql_name string   the SQL name of the associated table in the DB
has_dummies boolean   whether this DT allows empty references in foreign keys referring to it
has_dtp_cache boolean   whether this DT allows DTP cache (unless CU mode is enabled)
data_items list ppms.data_dictionary.DataItem instances all DIs belonging to the table
relations list ppms.data_dictionary.Relation instances all relations, primary and foreign keys, belonging to the table
acr_dis list ppms.data_dictionary.DataItem instances data items containing the ACR info for the data table

DataItem class

Attribute Type Contents Comment
id int    
table ppms.data_dictionary.DataTable   the table to which the DI belongs
python_id string    
sql_name string   the SQL name of the associated column in the DB
not_null boolean   whether the corresponding column in DB has a NOT NULL constraint
db_type string   which data type the DI has in DB
planta_type string   which data type the DI has in PLANTA
df_type string   which default data type any DF using this DI will have
di_class int    
used_in_pk boolean   whether the corresponding DI is used in the primary key
used_in_fk boolean   whether the corresponding DI is used in a foreign key
formula_type string    
formula string    

Relation class

Attribute Type Contents Comment
id ppms.data_dictionary.RelationId   synthetic type to represent the uniqueness criteria of Relation instances
table ppms.data_dictionary.DataTable   the table to which the relation belongs
foreign_table ppms.data_dictionary.DataTable   the table to which the relation refers
start_di ppms.data_dictionary.DataItem   the first DI in the relation
end_di ppms.data_dictionary.DataItem   the last DI in the relation
relation_type string 1:1, N:1, 1:N  
recursion_type string ordinary, recursive, inner  
name string    

DiStructure class

Attribute Type Contents Comment
id int    
parent_di ppms.data_dictionary.DataItem   the DI to be used in DFs
child_di ppms.data_dictionary.DataItem   the DI to be used by the parent DI
function string    

From S 39.5.4

Data Dictionary Access

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

target-blue 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.

note 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.

application Example

from ppms import ppms, data_dictionary

ddict = ppms.get_data_dictionary()

DataDictionary class

Attribute Type Contents Comment
db_schemas dictionary ppms.data_dictionary.DbSchema ordered by id
data_tables dictionary ppms.data_dictionary.DataTable ordered by id
data_items dictionary ppms.data_dictionary.DataItem ordered by id
relations dictionary ppms.data_dictionary.Relation ordered by id
di_structures dictionary ppms.data_dictionary.DiStructure ordered by id

DbSchema class

Attribute Type Contents / Return Value Comment
id string    
data_tables list ppms.data_dictionary.DataTable instances all tables belonging to the schema
NEW itext_table() method ppms.data_dictionary.DataTable instance the data table storing I-TEXTs for the schema
NEW itext_inum_di() method ppms.data_dictionary.DataItem instance the data item storing the number, as of the I-TEXT table, not the I-NUM table
NEW itext_lang_di() method ppms.data_dictionary.DataItem instance the data item storing the language
NEW itext_text_di() method ppms.data_dictionary.DataItem instance the data item storing the actual text value
NEW itext_ref_dt() method ppms.data_dictionary.DataItem instance the data item storing the data table to which the I-TEXT belongs
NEW itext_ref_di() method ppms.data_dictionary.DataItem instance the data item storing the data item to which the I-TEXT belongs
NEW itext_ref_pk() method ppms.data_dictionary.DataItem instance the data item storing the primary key values of the record to which the I-TEXT belongs
NEW hlink_table() method ppms.data_dictionary.DataTable instance the data table storing HLINKs for the schema
NEW hlink_hnum_di() method ppms.data_dictionary.DataItem instance the data item storing the number (ID)
NEW hlink_storage() method ppms.data_dictionary.DataItem instance the data item storing the storage type
NEW hlink_mdate() method ppms.data_dictionary.DataItem instance the data item storing the modification date
NEW hlink_size() method ppms.data_dictionary.DataItem instance the data item storing the size of actual BLOBs
NEW hlink_ctime() method ppms.data_dictionary.DataItem instance the data item storing the creation time
NEW hlink_mtime() method ppms.data_dictionary.DataItem instance the data item storing the modification time
NEW hlink_title() method ppms.data_dictionary.DataItem instance the data item storing the HLINK title
NEW hlink_url() method ppms.data_dictionary.DataItem instance the data item storing the HLINK URL
NEW hlink_pos() method ppms.data_dictionary.DataItem instance the data item storing the position of multi-line HLINK (functionality obsolete, provided for sanity checks)
NEW hlink_ref_di() method ppms.data_dictionary.DataItem instance the data item storing the data item to which the HLINK belongs
NEW hlink_crc() method ppms.data_dictionary.DataItem instance the data item storing the CRC checksum for the actual BLOB's data

DataTable class

Attribute Type Contents Comment
id int    
schema ppms.data_dictionary.DbSchema   the schema to which the table belongs
uuid_di ppms.data_dictionary.DataItem   the UUID DI with object ID relevance of the table
sql_name string   the SQL name of the associated table in the DB
has_dummies boolean   whether this DT allows empty references in foreign keys referring to it
has_dtp_cache boolean   whether this DT allows DTP cache (unless CU mode is enabled)
data_items list ppms.data_dictionary.DataItem instances all DIs belonging to the table
relations list ppms.data_dictionary.Relation instances all relations, primary and foreign keys, belonging to the table
NEW acr_dis list ppms.data_dictionary.DataItem instances data items containing the ACR info for the data table

DataItem class

Attribute Type Contents Comment
id int    
table ppms.data_dictionary.DataTable   the table to which the DI belongs
python_id string    
sql_name string   the SQL name of the associated column in the DB
not_null boolean   whether the corresponding column in DB has a NOT NULL constraint
db_type string   which data type the DI has in DB
planta_type string   which data type the DI has in PLANTA
df_type string   which default data type any DF using this DI will have
di_class int    
used_in_pk boolean   whether the corresponding DI is used in the primary key
used_in_fk boolean   whether the corresponding DI is used in a foreign key
formula_type string    
formula string    

Relation class

Attribute Type Contents Comment
id ppms.data_dictionary.RelationId   synthetic type to represent the uniqueness criteria of Relation instances
table ppms.data_dictionary.DataTable   the table to which the relation belongs
foreign_table ppms.data_dictionary.DataTable   the table to which the relation refers
start_di ppms.data_dictionary.DataItem   the first DI in the relation
end_di ppms.data_dictionary.DataItem   the last DI in the relation
relation_type string 1:1, N:1, 1:N  
recursion_type string ordinary, recursive, inner  
name string    

DiStructure class

Attribute Type Contents Comment
id int    
parent_di ppms.data_dictionary.DataItem   the DI to be used in DFs
child_di ppms.data_dictionary.DataItem   the DI to be used by the parent DI
function string    

New from S 39.5.0

Data Dictionary Access

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

target-blue 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.

note 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.

application Example

from ppms import ppms, data_dictionary

ddict = ppms.get_data_dictionary()

DataDictionary class

Attribute Type Contents Comment
db_schemas dictionary ppms.data_dictionary.DbSchema ordered by id
data_tables dictionary ppms.data_dictionary.DataTable ordered by id
data_items dictionary ppms.data_dictionary.DataItem ordered by id
relations dictionary ppms.data_dictionary.Relation ordered by id
di_structures dictionary ppms.data_dictionary.DiStructure ordered by id

DbSchema class

Attribute Type Contents Comment
id string    
data_tables list ppms.data_dictionary.DataTable instances all tables belonging to the schema

DataTable class

Attribute Type Contents Comment
id int    
schema ppms.data_dictionary.DbSchema   the schema to which the table belongs
uuid_di ppms.data_dictionary.DataItem   the UUID DI with object ID relevance of the table
sql_name string   the SQL name of the associated table in the DB
has_dummies boolean   whether this DT allows empty references in foreign keys referring to it
has_dtp_cache boolean   whether this DT allows DTP cache (unless CU mode is enabled)
data_items list ppms.data_dictionary.DataItem instances all DIs belonging to the table
relations list ppms.data_dictionary.Relation instances all relations, primary and foreign keys, belonging to the table

DataItem class

Attribute Type Contents Comment
id int    
table ppms.data_dictionary.DataTable   the table to which the DI belongs
python_id string    
sql_name string   the SQL name of the associated column in the DB
not_null boolean   whether the corresponding column in DB has a NOT NULL constraint
db_type string   which data type the DI has in DB
planta_type string   which data type the DI has in PLANTA
df_type string   which default data type any DF using this DI will have
di_class int    
used_in_pk boolean   whether the corresponding DI is used in the primary key
used_in_fk boolean   whether the corresponding DI is used in a foreign key
formula_type string    
formula string    

Relation class

Attribute Type Contents Comment
id ppms.data_dictionary.RelationId   synthetic type to represent the uniqueness criteria of Relation instances
table ppms.data_dictionary.DataTable   the table to which the relation belongs
foreign_table ppms.data_dictionary.DataTable   the table to which the relation refers
start_di ppms.data_dictionary.DataItem   the first DI in the relation
end_di ppms.data_dictionary.DataItem   the last DI in the relation
relation_type string 1:1, N:1, 1:N  
recursion_type string ordinary, recursive, inner  
name string    

DiStructure class

Attribute Type Contents Comment
id int    
parent_di ppms.data_dictionary.DataItem   the DI to be used in DFs
child_di ppms.data_dictionary.DataItem   the DI to be used by the parent DI
function string    

Topic revision: r431 - 2019-04-10 - 12:56:26 - IrinaZieger
PPMS39_DE.PythonAPIReference moved from PPMS39_DE.PythonAPIreferences on 2009-08-13 - 14:43 by MarkusSchreyer








 
  • Suche in Topic-Namen

  • Suche in Topic-Inhalten