Python API Reference

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

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

• list of functions:

• list of functions:

• list of functions:

• list of functions:

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:

from ppms import ppms
from ppms.constants import MENU_CLOSE

mod_obj = ppms.get_macro_module()

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

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

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

Controlling the message state

from ppms import ppms

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

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

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

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

Note:

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

Warning:

• service functions are not reliably executed in the configured timeinterval
• execution can only be triggered when the session is polling for messages from a client
• whenever an action takes place like loading a module or executing python code, service function execution periods are ignored
• 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

Note:

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

Warning:

• service functions are not reliably executed in the configured timeinterval
• execution can only be triggered when the session is polling for messages from a client
• whenever an action takes place like loading a module or executing python code, service function execution periods are ignored

Record limiting

Information

• These functions control when and how queries that would return a very large number of records are interrupted (because this would slow down the system).
• The limits are defined by the global variables @G80109 (soft limit) and @G80110 (hard limit). If queries return more records than the soft limit, the user gets the option to cancel this query by a message box. If queries return more records than the hard limit, they are ALWAYS canceled, and user sees a message box informing them about it (this message box is not blocking; it does not halt further session processes).
• During loading of modules or filtering, the results of various queries are added together to count versus soft/hard limit. At other times, only the result set of one query is taken into account (for hard limits).
• The question if soft queries should be canceled only appears during module loading/filtering. At other times, violations of soft limits are ignored. Violation of hard limits, however, are always taken into account.

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

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

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

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

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

Information

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

Modifying the validation

from ppms import ppms

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

    # ...

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

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

Session monitoring

Information

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

Protocol version

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

Using a Module instance as context manager

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

Using a module as context manager

from ppms import ppms
from ppms.constants import MENU_FILTER

mod_obj = ppms.get_macro_module()

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

Why is this useful?

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

from ppms import ppms

mod_obj = ppms.get_macro_module()

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