IDatabase¶
- class IDatabase¶
Bases:
ImpactCOMWrapperBase- Description:
Represents a database connection of the application.
Wraps a COM object or another wrapper instance. Accepts: - A valid impact_object - An existing impact_com_wrapper_base-derived instance
- property accept_auto_task¶
Gets accept_auto_task.
- Description:
Indicates if the current automated task should be accepted.
- Remarks:
During many operations in Impact automated tasks are invoked to perform additional processing. You can inform Impact to abort the current operation and stop any further action. For example when saving a working project the save_project automated task is invoked, setting accept_auto_task to false signals Impact to stop the save operation. It is the responsibility of the automated task to display an error message to the user informing them why the operation has been aborted. This property is only applicable when using an IDatabase object running in Impact. This property is ignored when used from an IServer, and the IServer never invokes automated tasks. This property only applies to the active_database in Impact, attempting to access this property from a secondary database connection will result in an error. You can only change the value of accept_auto_task while the database is connected. To see those automated tasks that support being aborted in this way check their Reject flag in Options > Environment > Database Installation > Automation.
- Returns:
The value of accept_auto_task.
- Return type:
accept_auto_task (bool)
- property application_name¶
Gets application_name.
- Returns:
This application_name is a write-only property. It is Automatically created to support property Setter. It will raise an attribute_error if you try to access it.
- property auto_task_drawing¶
Gets auto_task_drawing.
- Description:
Returns the drawing the currently executing automated task is executing on.
- Remarks:
During the execution of an auto-task, the IDrawing object for the task can be obtained by using this property. In certain situations the IApplication.active_drawing may not be the correct drawng when the auto-task is running.
- Returns:
The value of auto_task_drawing.
- Return type:
- property auto_task_layer¶
Gets auto_task_layer.
- Description:
Returns the layer the currently executing automated task is executing on.
- Remarks:
During the execution of an auto-task, the ILayer object for the task on can be obtained by using this property. In certain situations the IApplication.active_drawing.active_layer may not be the correct layer when the auto-task is running.
- Returns:
The value of auto_task_layer.
- Return type:
- property border_plot_creator¶
Gets border_plot_creator.
- Description:
An IBorderPlotCreator object used for creating border plots.
- Returns:
The value of border_plot_creator.
- Return type:
- property can_search_case_sensitive¶
Gets can_search_case_sensitive.
- Description:
Gets if the database can be searched for with case-sensitivity.
- Returns:
The value of can_search_case_sensitive.
- Return type:
can_search_case_sensitive (bool)
- property connected¶
Gets Connected.
- Description:
Indicates if the database is connected or not.
- Returns:
The value of Connected.
- Return type:
connected (bool)
- property connected_user¶
Gets connected_user.
- Description:
Gets the connected user.
- Remarks:
In a desktop scenario this property represents the interactive user, i.e. the user logged into the application.
- Returns:
The value of connected_user.
- Return type:
- property connection¶
Gets Connection.
- Description:
Creates an IDatabaseConnection object for the specified database.
- Remarks:
introduced in Impact 11.0.0.35
- Returns:
The value of Connection.
- Return type:
- property connection_name¶
Gets connection_name.
- Description:
The connection name of the database.
- Returns:
The value of connection_name.
- Return type:
connection_name (str)
- property customers¶
Gets Customers.
- Description:
An ICustomers collection representing all the customers in the database.
- Returns:
The value of Customers.
- Return type:
- property database_driver¶
Gets database_driver.
- Description:
Information describing the database driver.
- Returns:
The value of database_driver.
- Return type:
- property database_server¶
Gets database_server.
- Description:
Information describing the database server.
- Returns:
The value of database_server.
- Return type:
- property document_context¶
Gets document_context.
- Description:
Provides an IDocumentContext for the IDocuments collection operations.
- Remarks:
Introduced in Impact 9.0.0.83.
- Returns:
The value of document_context.
- Return type:
- property document_search¶
Gets document_search.
- Description:
Provides a new IDocumentSearch object for performing a search of documents within the database.
- Remarks:
Check the IDocumentSettings.supports_searching property to determine if searching is supported. Introduced in Impact 9.0.0.83.
- Returns:
The value of document_search.
- Return type:
- property documents¶
Gets Documents.
- Description:
An IDocuments collection representing all the documents in this document repository.
- Remarks:
This collection represents all documents in the database. The IDocuments collection retrieved from IDatabase does not automatically load any IDocument objects. It can be used to add new documents to the document repository without the overhead of loading any existing documents. If you need to load all documents from the document repository you should use the IDocumentSearch object without any search criteria. You should also check supports_paging before loading all documents as the operation may be very slow for large numbers of documents. To access documents related to individual objects see the IDatabaseItem, ICustomer, ICustomerContact, IUser or ISite objects.
- Returns:
The value of Documents.
- Return type:
- property documents_blobbed¶
Gets documents_blobbed.
- Description:
Indicates if documents are stored as blob streams or not.
- Returns:
The value of documents_blobbed.
- Return type:
documents_blobbed (bool)
- property errors¶
Gets Errors.
- Description:
An IErrorItems object containing errors generated by calls to methods and functions for objects related to this database.
- Remarks:
The error items must be cleared by the client prior to a method call to gain only errors related to a method call.
- Returns:
The value of Errors.
- Return type:
- property execute_auto_tasks¶
Gets execute_auto_tasks.
- Description:
Indicates if automated tasks are executed during other COM function calls.
- Remarks:
During calls to COM functions such as IDrawing.save, IDatabaseItem.open or IDatabaseItem.close_and_release automated tasks are normally invoked. However if you wish to prevent automated tasks from being executed during these calls you can set the execute_auto_tasks property to false. Setting execute_auto_tasks to false does not prevent these automated tasks from being executed when invoked by users in Impact. This property is only applicable when using an IDatabase object running in Impact. This property is ignored when used from an IServer, and the IServer never invokes automated tasks. This property only applies to the active_database in Impact, attempting to access this property from a secondary database connection will result in an error. You can only change the value of execute_auto_tasks while the database is connected. To see those automated tasks that support being suppressed in this way check their Suppress flag in Options > Environment, Database Installation, Automation.
- Returns:
The value of execute_auto_tasks.
- Return type:
execute_auto_tasks (bool)
- property files_blobbed¶
Gets files_blobbed.
- Description:
Indicates if files are stored as blob streams or not.
- Returns:
The value of files_blobbed.
- Return type:
files_blobbed (bool)
- property globals¶
Gets Globals.
- Description:
An IGlobals collection that represents session variables valid for the lifetime of the database connection.
- property ldap_authentication_failure_user_account_status¶
Gets ldap_authentication_failure_user_account_status.
- Description:
Determines a domain users account status when LDAP authentication fails.
- Remarks:
When authenticating an ldap_enabled user the database may be prevented from connecting due to restrictions imposed by the domain. This can include an invalid password, disabled account, locked out account, expired password etc. When this happens a ldap_authentication_failure_user_account_status object may be available so you can examine the domain users account status and take appropriate action. This may include redirecting a user to an administration portal for reseting their own password. Do not assume that the password has been verified when Connect fails and an ldap_authentication_failure_user_account_status object is available. This property is only available when using nServer. Introduced in Impact 8.0.0.94.
- Returns:
The value of ldap_authentication_failure_user_account_status.
- Return type:
ldap_authentication_failure_user_account_status (ILDAPUserAccountStatus)
- property ldap_authorization_security_group¶
Gets ldap_authorization_security_group.
- Description:
Gets or sets the LDAP security group that LDAP users must be a member of to be authorized and connect.
- Remarks:
When using nServer and developing your own application for use in an enterprise environment you may need to offer the ability to configure those domain users that have access to your application. You can set this property to a fully qualified distinguished name (DN) corresponding to the LDAP security group users must be a member of. Introduced in Impact 8.0.0.75.
- Returns:
The value of ldap_authorization_security_group.
- Return type:
- property ldap_previous_user_principal_name¶
Gets ldap_previous_user_principal_name.
- Description:
Determines if the LDAP authenticated user name has changed.
- Remarks:
It is possible that LDAP authenticated domain users may have changed the user principal name since their last Impact connection. This property enables you to determine if the user name has changed and update any external references you may store. Introduced in Impact 8.0.0.75.
- Returns:
The value of ldap_previous_user_principal_name.
- Return type:
- property ldap_settings¶
Gets ldap_settings.
- Description:
An ILDAPSettings object representing configured LDAP settings for the database.
- Remarks:
The configured LDAP settings for a database can be read when either connected or disconnected. Introduced in Impact 8.0.0.75.
- Returns:
The value of ldap_settings.
- Return type:
- property low_speed¶
Gets low_speed.
- Description:
Indicates if the database is operating over a low speed connection.
- Returns:
The value of low_speed.
- Return type:
low_speed (bool)
- property macro_repository_path¶
Gets macro_repository_path.
- Description:
Returns the path to the script and macro repository
- Remarks:
Returns the absolute path, as configured in the user’s database connection. Introduced in Impact 8.0.0.49
- Returns:
The value of macro_repository_path.
- Return type:
macro_repository_path (str)
- property primary¶
Gets Primary.
- Description:
Indicates if this is a primary database or not.
- Returns:
The value of Primary.
- Return type:
primary (bool)
- property project_and_layer_filter_options¶
Gets project_and_layer_filter_options.
- Description:
Sets the filtering options for the current Impact database connection.
- Remarks:
Once set, these options will apply additional filtering to any methods used to count or find projects or layers on the current Impact database connection. Reconnecting to the database will clear the filter options. The filtering can be disabled by calling disable_project_and_layer_filtering, and re-enabled by calling enable_project_and_layer_filtering. Introduced in Impact 6.2.0.6
- Returns:
The value of project_and_layer_filter_options.
- Return type:
project_and_layer_filter_options (IProjectAndLayerFilterOptions)
- property projects¶
Gets Projects.
- Description:
An IFolder object representing the top level folder for projects in the database.
- property secondary¶
Gets Secondary.
- Description:
Indicates if this is a secondary database or not.
- Returns:
The value of Secondary.
- Return type:
secondary (bool)
- property server_licence¶
Gets server_licence.
- Description:
An ILicence object representing a licence allocated during an nServer session.
- Remarks:
When using IServer it is important to request an appropriate licence by calling methods and setting properties of the ILicence object. This must be done prior to calling the IDatabase.connect method.
- Returns:
The value of server_licence.
- Return type:
- property settings¶
Gets Settings.
- Description:
An IDatabaseSettings object representing settings for the database.
- Returns:
The value of Settings.
- Return type:
- property settings_blobbed¶
Gets settings_blobbed.
- Description:
Indicates if settings are stored as blob streams or not.
- Returns:
The value of settings_blobbed.
- Return type:
settings_blobbed (bool)
- property single_connection¶
Gets single_connection.
- Description:
Indicates what type of connection to create.
- Remarks:
This property is only applicable when using an IDatabase object running on an IServer. Attempting to access this property when running in Impact will result in an error. The IDatabase object running on an IServer supports two types of database connections. A normal IDatabase connection respects the single connection model of Impact. This ensures that each user can only be connected from a single workstation at any one time. This type of connection is normally used when writing an application that requires a user to specify a user name and password to connect to a database. A special IDatabase connection that allows the IServer object to connect multiple times as the same user to a database. This type of connection is normally used when writing a server application that processes multiple client requests simultaneously and doesn’t require each user to provide security information. This type of connection is most often used with a web server to respond to client page requests. Setting single_connection to True (the default) will open a normal connection, setting it to False will open a connection that supports multiple simultaneous connections. Connecting as ADMIN forces the connection to be opened with single_connection set to true. You cannot change the value of single_connection while the database is connected.
- Returns:
The value of single_connection.
- Return type:
single_connection (bool)
- property sites¶
Gets Sites.
- Description:
An ISites collection containing all the sites in the database.
- Remarks:
If Settings.db_sites is false, then NULL will be returned.
- property standard_creator¶
Gets standard_creator.
- Description:
An IStandardCreator object used for creating projects from standards in the database.
- Returns:
The value of standard_creator.
- Return type:
- property standard_parts¶
Gets standard_parts.
- Description:
An IFolder object representing the top level folder for standard parts in the database.
- Returns:
The value of standard_parts.
- Return type:
- property standard_settings¶
Gets standard_settings.
- Description:
An IStandardSettings object representing standard settings for the database.
- Returns:
The value of standard_settings.
- Return type:
- property standards¶
Gets Standards.
- Description:
An IFolder object representing the top level folder for standards in the database.
- property symbols¶
Gets Symbols.
- Description:
An IFolder object representing the top level folder for symbols in the database.
- property templates¶
Gets Templates.
- Description:
An IFolder object representing the top level folder for templates in the database.
- property unit_settings¶
Gets unit_settings.
- Description:
Represents the connected user’s unit settings.
- Remarks:
The IDatabase.i_unit_settings is useful for assigning to the IConvertor.unit_settings property, IDatabaseValues.unit_settings property, or IDatabaseTableRow.unit_settings property, to ensure that values are displayed using the user’s preferences. This property returns a copy of the user’s settings, so you can modify these values without affecting the user’s environment settings used in Impact. In an nServer context, IDatabase.i_unit_settings does not return the user’s settings. Instead it can be used to persist user settings for the duration of the session (until IDatabase.disconnect). Introduced in Impact 11.0.0.27
- Returns:
The value of unit_settings.
- Return type:
- property users¶
Gets Users.
- Description:
An IUsers collection representing all the users in the database.
- property users_blobbed¶
Gets users_blobbed.
- Description:
Indicates if users are stored as blob streams or not.
- Returns:
The value of users_blobbed.
- Return type:
users_blobbed (bool)
- property working_documents¶
Gets working_documents.
- Description:
An IDocuments collection representing all the checked out documents in this database.
- Remarks:
The IDocuments collection contains checked out documents for all users in the database. The IUser.working_documents property can be used to access each individual user’s checked out documents. Introduced in Impact 9.0.0.83.
- Returns:
The value of working_documents.
- Return type:
- check_credentials(username, password)¶
- Description:
Checks the user credentials are valid and can be successfully used in the IDatabase.connect method.
- Remarks:
The method will work in Impact only if you are connected to a primary database; in nServer it works whether or not you are connected. WARNING! Used from nServer, calling this method unsuccessully three times for a valid user name will cause the account associated with the specified user name to be disabled for 60 minutes. From nServer 10.2 onwards, these “Password Attempts” and “Locked Account Timeout” values may be configured from the nServer Administrator.
- Parameters:
username (str) – Specifies the user name.
password (str) – Specifies the user’s password.
- connect(username, password)¶
- Description:
Connects to the database using the supplied credentials.
- Remarks:
When the database is configured for LDAP authentication you can pass in an empty Username and Password to connect as the windows authenticated user. You can be connected to only one database at any time. This method will fail if a connection has already been made to this or any other database. You may use the Connected property to detect whether this is the case. You can use Disconnect to close the current connection. If the connection fails the Errors property may be accessed in order to determine why the connection failed. For connections from nServer, see additional information in single_connection and server_licence. WARNING! Used from nServer, calling this method unsuccessully three times for a valid user name will cause the account associated with the specified user name to be disabled for 60 minutes. From nServer 10.2 onwards, these “Password Attempts” and “Locked Account Timeout” values may be configured from the nServer Administrator.
- Parameters:
username (str) – The username to use to connect to the database.
password (str) – The password to use to connect to the database.
- connect_ldap_authorization_only(user_principal_name)¶
- Description:
Connects to the database without performing user authentication.
- Remarks:
This function will only work when the database is configured for LDAP authentication. You should only use this function to connect to a database when you have externally authenticated a user. For example when a website has authenticated a user using Kerboros. For connections from an IServer see additional information in single_connection and server_licence. If the connection fails the Errors property may be accessed in order to determine why the connection failed. Introduced in Impact 8.0.0.75.
- Parameters:
user_principal_name (str) – The user principal name to use to connect to the database.
- connect_to_ldap_service()¶
- Description:
Connects to the configured LDAP Service.
- Remarks:
This function should be used when performing multiple operations against an LDAP Service to improve performance. You should call disconnect_from_ldap_service when finished. Introduced in Impact 8.0.0.75.
- Returns:
Returns true when the connection is successful.
- count_items(options)¶
- Description:
Counts database items as specified in the Options parameter.
- Remarks:
Introduced in Impact 6.1.0.43
- Returns:
The number of matching items.
- Parameters:
options (ICountItemsOptions) – Options that specify what to count, and how.
- count_items_by_query(query)¶
- Description:
Counts the number of items the specified query will return.
- Parameters:
query (str) – Specifies the name of the query.
- count_items_by_query2(query_m_t_s)¶
- Description:
Counts the number of items the specified query will return.
- Remarks:
Introduced in Impact 5.1.3.48.
- Parameters:
query_mts (IMasterSetting) – Specifies the query to use.
- count_items_by_sql(drawing_type, s_q_l)¶
- Description:
Returns the number of items which would be returned by using the specified drawing_type and SQL in the find_items_by_sql and find_items_by_sq_l2 methods.
- Parameters:
drawing_type (ipDrawingType) – Specifies the type of drawing to find.
sql (str) – Specifies the sql to execute to find the drawing.
- count_layers(options)¶
- Description:
Counts database layers as specified in the Options parameter.
- Remarks:
Introduced in Impact 7.0.0.13
- Returns:
The number of matching layers.
- Parameters:
options (ICountItemsOptions) – Options that specify what to count, and how.
- count_total_rows(row_count_options)¶
- Description:
Counts the total number of rows using the Query, sql_conditions or SQL provided in the options.
- Remarks:
Introduced in Impact 9.0.0.42
- Parameters:
row_count_options (IRowCountOptions) – Row count options
- create_item(drawing_type, template_name)¶
- Description:
Create a new item.
- Parameters:
drawing_type (ipDrawingType) – The type of the item to create.
template_name (str) – The name of a template to use to create the item from.
- database_table_row(table, key)¶
- Description:
Allows access to data in a table row for a specified custom table name and key.
- Remarks:
This method can only be used for IDatabaseTable objects whose type is dttCustom. Introduced in Impact 13.0.0.67
- Parameters:
table (str) – Name of custom table.
key (int) – The unique key that identifies the required row.
- database_table_rows(table)¶
- Description:
Allows access to table data from any custom table.
- Remarks:
This method can only be used for IDatabaseTable objects whose Type is dttCustom. This will return an IDatabaseTableRows object that can be used to Add/Change/Delete rows within the custom table. To access related table data for an object it is recommended you use the IDatabaseTableValues retrieved from the object’s IDatabaseValues.related_table_values property rather than accessing the data directly using this method. This is because this object returns table rows for ALL parent objects and it may be very inefficient for large databases. Introduced in Impact 11.0.0.27
- Parameters:
table (str) – Name of custom table.
- disable_project_and_layer_filtering()¶
- Description:
Disables any project and layer filtering already established by setting the project_and_layer_filter_options property.
- Remarks:
Introduced in Impact 6.2.0.6
- disconnect()¶
- Description:
Disconnects from the current database.
- disconnect_from_ldap_service()¶
- Description:
Disconnects from the configured LDAP Service.
- Remarks:
Introduced in Impact 8.0.0.75.
- documents_for_external_type(external_type, object_i_d)¶
- Description:
An IDocuments collection representing all the documents that have a relationship to the external object.
- Remarks:
Introduced in Impact 9.0.0.88.
- Parameters:
external_type (str) – A unique identifier for the type of external object.
object_id (any) – A unique identifier for the external object to match.
- enable_project_and_layer_filtering()¶
- Description:
Enables the project and layer filtering already established by setting the project_and_layer_filter_options property.
- Remarks:
Introduced in Impact 6.2.0.6
- failed_login_i_ds()¶
- Description:
Gets the login ids of the users who are currently locked-out due to too many unsuccessful login attempts.
- Remarks:
Introduced in Impact 11.0.0.34. See also reset_failed_login method. This feature applies only to nServer; so the method always returns null (Empty) when used from Impact.
- Returns:
An array of strings, each being a user login id.
- find_address_by_key(key)¶
- Description:
Finds an address by its key
- Remarks:
introduced in Impact 11.0.0.43
- Parameters:
key (int) – Address key
- find_document_by_id(i_d)¶
- Description:
Finds a document with a specific unique document or series id.
- Remarks:
Each document has a unique document id that can be used to locate a specific document. Each document in a series (related by version) has the same unique series id that can be used to locate the latest document in that series. Introduced in Impact 9.0.0.83.
- Parameters:
id (str) – Specifies the unique document or series id of the document to find.
- find_document_by_key(key)¶
- Description:
Finds a document with a specified key.
- Remarks:
This method has been deprecated. You should consider using find_document_by_id instead.
- Parameters:
key (int) – Specifies the key of the document to find.
- find_folder_by_key(key)¶
- Description:
Finds an IFolder with the specified key.
- Parameters:
key (int) – Specifies the key of the folder to find.
- find_item_by_code(drawing_type, code)¶
- Description:
Find an IDatabaseItem with the specified drawing type and code.
- Parameters:
drawing_type (ipDrawingType) – Specifies the type of drawing to find.
code (str) – Specifies the code of the drawing to find.
- find_item_by_guid_string(drawing_type, g_u_i_d)¶
- Description:
Find an IDatabaseItem with the specified drawing GUID and name.
- Parameters:
drawing_type (ipDrawingType) – Specifies the type of drawing to find.
guid (str) – Specifies the GUID of the drawing to find.
- find_item_by_key(drawing_type, key)¶
- Description:
Find an IDatabaseItem with the specified drawing type and key.
- Parameters:
drawing_type (ipDrawingType) – Specifies the type of drawing to find.
key (int) – Specifies the key of the drawing to find.
- find_item_by_name(drawing_type, name)¶
- Description:
Find an IDatabaseItem with the specified drawing type and name.
- Parameters:
drawing_type (ipDrawingType) – Specifies the type of drawing to find.
name (str) – Specifies the name of the drawing to find.
- find_items(options)¶
- Description:
Finds database items as specified in the Options parameter.
- Remarks:
Introduced in Impact 6.1.0.43
- Returns:
A list containing the database items found.
- Parameters:
options (IFindItemsOptions) – Options that specify what to find, and how.
- find_items_by_query(query)¶
- Description:
Finds an array of IDatabaseItem objects by searching using the specified query by name.
- Remarks:
Deprecated, use find_items_by_query2 instead. Remember arrays are zero based and collections are one based.
- Parameters:
query (str) – Specifies the name of the query to use to find the projects.
- find_items_by_query2(query_m_t_s)¶
- Description:
Finds an array of IDatabaseItem objects by searching using the specified query.
- Remarks:
Remember arrays are zero based and collections are one based.
- Parameters:
query_mts (IMasterSetting) – Specifies the query to use to find the projects.
- find_items_by_query_with_max(query, max_records)¶
- Description:
Finds an array of IDatabaseItem objects by searching using the specified query, only returning the maximum specified items.
- Remarks:
Remember arrays are zero based and collections are one based.
- Parameters:
query (str) – Specifies the name of the query to use to find the projects.
max_records (int) – Specifies the maximum number of items to return.
- find_items_by_query_with_max2(query_m_t_s, max_records)¶
- Description:
Finds an array of IDatabaseItem objects by searching using the specified query, only returning the maximum specified items.
- Remarks:
Introduced in Impact 5.1.3.48.
- Parameters:
query_mts (IMasterSetting) – Specifies the query to use.
max_records (int) – Specifies the maximum number of items to return.
- find_items_by_sql(drawing_type, s_q_l)¶
- Description:
Finds an array of IDatabaseItem objects with the specified drawing type and SQL criteria.
- Remarks:
Remember arrays are zero based and collections are one based.
- Returns:
Returns an array of IDatabaseItem objects.
- Parameters:
drawing_type (ipDrawingType) – Specifies the type of drawing to find.
sql (str) – Specifies the SQL query to find the drawings.
- find_items_by_sql2(drawing_type, s_q_l, max_records)¶
- Description:
Finds an array of IDatabaseItem objects with the specified drawing type and SQL, limiting the results to the specified max number of records.
- Remarks:
Remember arrays are zero based and collections are one based. The items are returned in ascending order of name.
- Parameters:
drawing_type (ipDrawingType) – Specifies the type of drawing to find.
sql (str) – Specifies the SQL to execute to find the drawing.
max_records (int) – Specifies the maximum number of records to return. Specifying a value of zero means that all items will be returned as in the find_items_by_sql method.
- find_items_by_sql3(drawing_type, s_q_l, max_records, order_ascending, order_by)¶
- Description:
Finds a collection of IDatabaseItem objects with the specified drawing type and sql, limiting the results to the specified max number of records. The order direction of the results maybe specified.
- Parameters:
drawing_type (ipDrawingType) – Specifies the type of drawing to find.
sql (str) – Specifies the sql to execute to find the drawing.
max_records (int) – Specifies the maximum number of records to return. Specifying a value of zero means that all items will be returned as in the find_items_by_sql method.
order_ascending (bool) – Specifies if the results are ordered ascending or descending.
order_by (str) – Specifies the columns to order the results by.
- find_layers(options)¶
- Description:
Finds database layers as specified in the Options parameter.
- Remarks:
Introduced in Impact 7.0.0.13
- Returns:
A list containing the database layers found.
- Parameters:
options (IFindItemsOptions) – Options that specify what to find, and how.
- find_master_tool_setting(name, type)¶
- Description:
Find an IMasterSetting with the specified path name and type.
- Remarks:
If the required setting is in a sub folder you must prefix the Name method parameter with the folder name, for example “my_import_export_settings|Customer Independent|Complete Import/Export”. When attempting to find settings of type mstPostProcessor you should always prefix the name of the setting with the name of the associated plot machine setting seperated by a vertical bar. See the examples for clarification. Some of the master tool setting types (for example mstAppearance, mstFillArea, mstDBWindow) are not supported by nServer. Attempting to use them will result in an exception “Value does not fall within the expected range”. If the database is configured to use site-specific master tool settings, it is recommended to use find_master_tool_setting2 rather than find_master_tool_setting so that you can filter out any settings that don’t apply to the user.
- Parameters:
name (str) – Specifies the name of the setting to find, including any folder names (using “|” as the separator).
type (ipMasterSettingType) – Specifies the type of the setting to find.
- find_master_tool_setting2(name, type, site)¶
- Description:
Find an IMasterSetting with the specified path name and type, optionally filtering by site.
- Remarks:
Introduced in Impact 11.1.0.15 and 12.0.0.77
- Parameters:
name (str) – Specifies the name of the setting to find, including any folder names (using “|” as the separator).
type (ipMasterSettingType) – Specifies the type of the setting to find.
site (ISite) – Only return the setting if it is associated with this site (optional).
- find_master_tool_setting_by_key(key)¶
- Description:
Finds a master tool setting with a specified key.
- Remarks:
If the database is configured to use site-specific master tool settings, it is recommended to use find_master_tool_setting_by_key2 rather than find_master_tool_setting_by_key so that you can filter out a setting that doesn’t apply to the user.
- Parameters:
key (int) – The key of the master tool setting to find.
- find_master_tool_setting_by_key2(key, site)¶
- Description:
Finds a master tool setting with a specified key, optionally filtering by site.
- Remarks:
Introduced in Impact 11.1.0.15 and 12.0.0.77
- Parameters:
key (int) – The key of the master tool setting to find.
site (ISite) – Only return a setting if it associated with this site (optional).
- find_master_tool_settings(type)¶
- Description:
Finds a collection of IMasterSetting objects of a specified type.
- Remarks:
Some of the master tool setting types (for example mstAppearance, mstFillArea, mstDBWindow) are not supported by nServer. Attempting to use them will result in an exception “Value does not fall within the expected range”. If the database is configured to use site-specific master tool settings, it is recommended to use find_master_tool_settings3 rather than find_master_tool_settings or find_master_tool_settings2, so that you can filter out any settings that don’t apply to the user.
- Parameters:
type (ipMasterSettingType) – Specifies the type of the setting to find.
- find_master_tool_settings2(type, load_settings)¶
- Description:
Finds a collection of IMasterSetting objects of a specified type with the option of loading each setting.
- Remarks:
Introduced in 7.0.0.63 and 6.4.0.13
- Parameters:
type (ipMasterSettingType) – Specifies the type of settings to find.
load_settings (bool) – Indicates if all the settings should be loaded into memory straight away (which is more efficient than loading them individually as they are used).
- find_master_tool_settings3(type, load_settings, site)¶
- Description:
Finds a collection of IMasterSetting objects of a specified type with the option of loading each setting, optionally filtering by site.
- Remarks:
Introduced in Impact 11.1.0.15 and 12.0.0.77
- Parameters:
type (ipMasterSettingType) – Specifies the type of settings to find.
load_settings (bool) – Indicates if all the settings should be loaded into memory straight away (which is more efficient than loading them individually as they are used).
site (ISite) – Only return settings that are associated with this site (optional).
- find_rowset(rowset_options)¶
- Description:
Find a “rowset” (XML representation of row and column data) based on the specified options.
- Remarks:
Introduced in Impact 9.0.0.42.
- Returns:
A string that contains XML data, structured into row and column elements.
- Parameters:
rowset_options (IRowsetOptions) – Options
- find_user_key_by_login_id(login_i_d)¶
- Description:
Find user key by login_id
- Remarks:
Introduced in Impact 10.0.0.61
- Returns:
The user key for that user (IUser.key)
- Parameters:
login_id (str) – The user login id (IUser.login_id).
- find_user_login_id_by_key(key)¶
- Description:
Find user login_id by key.
- Remarks:
Introduced in Impact 10.0.0.61
- Returns:
The login id for that user (IUser.login_id)
- Parameters:
key (int) – The user key (IUser.key)
- find_users_by_email_address(email)¶
- Description:
Finds users with the specific email address.
- Remarks:
Introduced in Impact 7.0.1.4.
- Returns:
An array of located IUsers.
- Parameters:
email (str) – The email address to locate.
- general_report(params, s_q_l_filter_conditions)¶
- Description:
Generates a report on a specified table from the database.
- Remarks:
Introduced in 8.0.0.51. Use this to create a report on a general table in the database such as CUSTOMER or CONTACTS. For reports on projects and layers, use project_or_layer_report instead.
- Parameters:
params (IDatabaseReportParams) – An object that determines what data the report will depict.
sql_filter_conditions (any) – Conditions by which to filter the report data.
- generate_auto_number(settings)¶
- Description:
Generates an single auto-number code from a specific Auto-Number setting.
- Remarks:
The Auto-Number setting should not use or reference any values from a drawing or any layers (such as database values or variables). To use an Auto-Number setting with a drawing use the IDrawing.generate_auto_number method.
- Parameters:
settings (IMasterSetting) – The Auto-Number settings to use to generate the code.
- get_attribute(name)¶
- Description:
Gets an attribute from the database.
- Remarks:
This is an internal method used by Arden Software only.
- Parameters:
name (str) – The name of the attribute to get.
- get_lookups(table_name, display_column_name, filter_s_q_l)¶
- Description:
Gets an ILookUps collection representing all the lookup values for the specified table name, display column name and optional filter.
- Remarks:
Introduced in Impact 6.3.0.3
- Parameters:
table_name (str) – Specifies the name of the table to read values from.
display_column_name (str) – Specifies the column in the specified table to read values from.
filter_sql (str) – Optionally specifies sql to filter the results, e.g. CS_NAME <> ‘(Default Customer)’.
- get_lookups2(table_name, display_column_name, filter_s_q_l, order_by_s_q_l)¶
- Description:
Gets an ILookUps collection representing all the lookup values for the specified table name, display column name with optional filter and SQL to order the results.
- Remarks:
Introduced in 8.0.0.41. Identical to get_lookups but with the additional option to sort the results.
- Parameters:
table_name (str) – Specifies the name of the table to read values from.
display_column_name (str) – Specifies the column in the specified table to read values from.
filter_sql (str) – Optionally specifies sql to filter the results, e.g. CS_NAME <> ‘(Default Customer)’.
order_by_sql (str) – Optionally specifies how the results should be sorted (the “order by” keywords should not be included in this string).
- get_lookups3(params)¶
- Description:
Gets an ILookUps collection representing all the lookup values for the specified table name, display column name and other critera.
- Remarks:
Introduced in Impact 11.0.0.48.
- Parameters:
params (ILookupParameters) – Object defining the lookup table, column and options.
- import_drawing(file_name, settings, destination_drawing)¶
- Description:
Imports a drawing from a file.
- Remarks:
If the IDatabase is obtained from an IServer object (nServer) and the drawing to be imported is an Impact drawing and it contains some macro objects, these objects will be skipped. If the drawing is then saved, the macro objects will be permanently lost. This is a limitation of the IServer object because it does not support the IML. For versions of Impact prior to 8.0.0.51, if you want a script to import a file into an existing drawing, you must pass a drawing object as the destination_drawing and the master tool settings must have the “Create New Project” option disabled. After this version, the option within the master tool settings is ignored.
- Parameters:
file_name (str) – The full path to the file to import the drawing from.
settings (IMasterSetting) – The settings to use to import the drawing.
destination_drawing (IDrawing) – The drawing to import into. This parameter may be null, if so a new drawing will be created.
- import_drawing_from_stream(stream, file_name, chunk_size, settings, destination_drawing)¶
- Description:
Imports a drawing from a stream.
- Remarks:
If the IDatabase is obtained from an IServer object and the drawing to be imported is an Impact drawing and it contains some macro objects these objects will be skipped. If the drawing is then saved the macro objects will be permanently lost. This is a limitation of the IServer object because it does not support the IML.
- Parameters:
stream (win32com.client.Dispatch) – Specifies the stream to import the drawing from. The IUnknown interface passed here must support the IStream interface.
file_name (str) – Specifies the file name to use for the drawing when it is reconstructed on the server side.
chunk_size (int) – Specifies the number of bytes to read for each sequential access to the specified stream. This value must be between 1K (1024 bytes) and 1MB (1048576 bytes), if a value is specified outside this range then the actual value used will be modified to fit into the range.
settings (IMasterSetting) – The settings to use to import the drawing.
destination_drawing (IDrawing) – The drawing to import into. This parameter may be null, if so a new drawing will be created.
- import_master_tool_settings(type, file_name)¶
- Description:
Imports multiple master tool settings from a file.
- Remarks:
Currently only the mstMaterial type of settings is supported. Introduced in Impact 7.0.0.56.
- Parameters:
type (ipMasterSettingType) – The type of settings to be imported (currently this must be set to mstMaterial).
file_name (str) – A file containing the settings, in comma-separated variable (CSV) format.
- initialise_document_external_access(access_rights_column_name, null_document_access_rights_id, deny_display_keys, deny_open_keys, deny_update_keys, deny_delete_keys)¶
- Description:
Initialise document external access.
- Remarks:
Introduced in Impact 10.0.0.60
- Parameters:
access_rights_column_name (str) – A column in the DOCUMENT table that will hold the key of an external access right object
null_document_access_rights_id (int) – The id of an access right to use in place of DOCUMENT records with no access right defined (that is, null or zero)
deny_display_keys (any) – An array of keys of access rights which allow display.
deny_open_keys (any) – An array of keys of access rights which allow open.
deny_update_keys (any) – An array of keys of access rights which allow update.
deny_delete_keys (any) – An array of keys of access rights which allow delete.
- lookup_project_and_layer_keys_from_value(params)¶
- Description:
Looks up projects or layers as specified in the Params parameter.
- Remarks:
Introduced in Impact 6.1.0.26
- Parameters:
params (ILookupProjectAndLayerKeysFromValueParams) – Parameters that specify what to look for, and how. The result keys are returned in either the project_keys or layer_keys properties, and the result values in matching_values.
- lookup_value_from_project_or_layer_key(table_name, column_name, the_key)¶
- Description:
Looks up a value in the given table/column from the specified key.
- Remarks:
Introduced in Impact 6.1.0.26
- Parameters:
table_name (str) – The name of the table in which the column exists.
column_name (str) – The name of the column that contains the data to look up.
the_key (int) – The key of the project or layer.
- master_setting_full_name_translated(master_setting, language_id)¶
- Description:
The translated name of the setting, including any folder names.
- Remarks:
Please see the notes for the master_setting_name_translated method. Introduced in Impact 8.0.0.52
- Returns:
The translated name of the setting, including any folder names.
- Parameters:
master_setting (IMasterSetting) – The object representing the master tool setting.
language_id (any) – A string or enum representing the language wanted.
- master_setting_name_translated(master_setting, language_id, exact_language_match)¶
- Description:
Retreives the translated name for any master tool setting.
- Remarks:
The language_id value can be a string representing the language - for example “sp” (the Windows culture code for Spanish), “sp-MX” (the Windows culture code for Mexican Spanish), or “Spanish” - or it can be a value from the ipImpactLanguageId enumeration (the list of Impact’s built-in languages). If exact_language_match is False, and no translation exists for the specified language, the method will return the best translation available. For example if “sp-MX” is wanted, and only a “sp” tranlation exists, the latter will be returned. Introduced in Impact 8.0.0.52
- Returns:
The translated name of the setting.
- Parameters:
master_setting (IMasterSetting) – The object representing the master tool setting.
language_id (any) – A string or enum representing the language wanted.
exact_language_match (bool) – Specifies what to do if there is no translation for the specified language.
- master_tool_settings_folder_translations(params)¶
- Description:
Retreives translated names for all master tool setting folders.
- Remarks:
Introduced in Impact 8.0.0.52
- Parameters:
params (IMasterToolSettingsFolderTranslationsParams) – An object specifying the criteria used to retreive the names. The results are returned in the translated_names property of this object.
- perform_value_mapping(value_mapping_m_t_s, drawing, layer)¶
- Description:
Performs a value mapping.
- Remarks:
If you specify a Layer then the value mapping is performed only on that layer. If you do not specify a Layer then the value mapping is performed on the project and all appropriate layers within the project. The IServer supports the running of value mappings.
- Parameters:
value_mapping_mts (IMasterSetting) – Specifies the value mapping to perform.
drawing (IDrawing) – Specifies the drawing on which to perform the value mapping.
layer (ILayer) – Specifies the layer on which to perform the value mapping. (Optional)
- project_or_layer_report(params, s_q_l_filter_conditions)¶
- Description:
Generates a report on project or layer data.
- Remarks:
Introduced in Impact 6.4.0.9 and 7.0.0.58.
- Parameters:
params (IDatabaseReportParams) – An object that determines what data the report will depict.
sql_filter_conditions (any) – Conditions by which to filter the report data.
- refresh()¶
- Description:
Refresh the item information from the database.
- reset_failed_login(login_i_d)¶
- Description:
Resets the account for a user who is currently locked-out due to too many unsuccessful login attempts, allowing them to try again.
- Remarks:
Introduced in Impact 11.0.0.34. See also failed_login_i_ds method. This feature applies only to nServer; so the method has no effect when used from Impact.
- Parameters:
login_id (str) – The login id of a locked-out user.
- server_licences(address)¶
- Description:
Returns an IServerLicences collection representing the licences installed on a specific Licence Server.
- Remarks:
Introduced in Impact 7.0.0.10.
- Parameters:
address (str) – An optional licence server address and port number. The Address can be specified in the format “address[:port]”, i.e. “192.168.0.10”, “192.168.0.10:3000”, “ASLICSRVR” are all valid addresses. If no Address (or port number) is specified and the IDatabase object is connected to an active Licence Server then that address is used. If the IDatabase is not connected to a Licence Server then the configured Licence Server is used. If multiple Licence Servers are configured then the first available Licence Server is used.
- set_attribute(name, value)¶
- Description:
Sets an attribute.
- Remarks:
This is an internal method used by Arden Software only.
- Parameters:
name (str) – The name of the attribute to set.
value (str) – The value of the attribute.