nixnet.database.database

class nixnet.database.database.Database(database_name)

Bases: nixnet.database._database_object.DatabaseObject

Opens a database file.

When an already open database is opened, this class grants access to the same database and increases an internal reference counter. A multiple referenced (open) database must be closed as many times as it has been opened. Until it is completely closed, the access to this database remains granted, and the database uses computer resources (memory and handles). For more information, refer to Database.close.

Parameters:database_name (str) – The database alias or file pathname to open.

close(close_all_refs=False)

Closes the database.

For the case that different threads of an application are using the same database, Database and Database.close maintain a reference counter indicating how many times the database is open. Every thread can open the database, work with it, and close the database independently using close_all_refs set to False. Only the last call to Database.close actually closes access to the database.

Note

Database.__exit__ calls Database.close with close_all_refs set to False. See examples of this in CAN Dynamic Database Creation and LIN Dynamic Database Creation.

Another option is that only one thread executes Database.close once, using close_all_refs set to True, which closes access for all other threads. This may be convenient when, for example, the main program needs to stop all running threads and be sure the database is closed properly, even if some threads could not execute Database.close.

Parameters:close_all_refs (bool) – Indicates that a database open multiple times (refer to Database) should be closed completely (close_all_refs is True), or just the reference counter should be decremented (close_all_refs is False), and the database remains open. When the database is closed completely, all references to objects in this database become invalid.

clusters

Returns a collection of Cluster objects in this database.

A cluster is assigned to a database when the cluster object is created. You cannot change this assignment afterwards.

FIBEX and AUTOSAR files can contain any number of clusters, and each cluster uses a unique name.

For CANdb (.dbc), LDF (.ldf), or NI-CAN (.ncd) files, the file contains only one cluster, and no cluster name is stored in the file. For these database formats, NI-XNET uses the name Cluster for the single cluster.

Type:DbCollection

find(object_class, object_name)

Finds an object in the database.

This function finds a database object relative to this parent object. This object may be a grandparent or great-grandparent.

If this object is a direct parent (for example, Frame for Signal), the object_name to search for can be short, and the search proceeds quickly.

If this object is not a direct parent (for example, Database for Signal), the object_name to search for must be qualified such that it is unique within the scope of this object.

For example, if the class of this object is Cluster, and object_class is Signal, you can specify object_name of mySignal, assuming that signal name is unique to the cluster. If not, you must include the Frame name as a prefix, such as myFrameA.mySignal.

NI-XNET supports the following subclasses of DatabaseObject as arguments for object_class:

• nixnet.database.Cluster
• nixnet.database.Frame
• nixnet.database.Pdu
• nixnet.database.Signal
• nixnet.database.SubFrame
• nixnet.database.Ecu
• nixnet.database.LinSched
• nixnet.database.LinSchedEntry

Parameters:

• object_class (DatabaseObject) – The class of the object to find.
• object_name (str) – The name of the object to find.

Returns:

An instance of the found object.

Raises:

• ValueError – Unsupported value provided for argument object_class.
• XnetError – The object is not found.

save(db_filepath='')

Saves the open database to a FIBEX 3.1.0 file.

The file extension must be .xml. If the target file exists, it is overwritten.

XNET saves to the FIBEX file only features that XNET sessions use to communicate on the network. If the original file was created using non-XNET software, the target file may be missing details from the original file. For example, NI-XNET supports only linear scaling. If the original FIBEX file used a rational equation that cannot be expressed as a linear scaling, XNET converts this to a linear scaling with factor 1.0 and offset 0.0.

If db_filepath is empty, the file is saved to the same FIBEX file specified when opened. If opened as a file path, it uses that file path. If opened as an alias, it uses the file path registered for that alias.

Saving a database is not supported under Real-Time (RT), but you can deploy and use a database saved on Windows on a Real-Time (RT) target (refer to Database.deploy).

Parameters:db_filepath (str) – Contains the pathname to the database file or is empty (saves to the original filepath).

show_invalid_from_open

Show or hide Frame and Signal objects that are invalid.

After opening a database, this property always is set to False, meaning that invalid Cluster, Frame, and Signal objects are not returned in properties that return a DbCollection for the database (for example, Cluster.frames and Frame.mux_static_signals). Invalid Cluster, Frame, and Signal objects are incorrectly defined and therefore cannot be used in the bus communication. The False setting is recommended when you use the database to create XNET sessions.

In case the database was opened to correct invalid configuration (for example, in a database editor), you must set the property to True prior to reading properties that return a DbCollection for the database (for example, Cluster.frames and Frame.mux_static_signals).

For invalid objects, the Cluster.check_config_status, Frame.check_config_status, and Signal.check_config_status methods raise an exception if there is a problem. For valid objects, no error is raised.

Cluster, Frame, and Signal objects that became invalid after the database is opened are still returned from the Database.clusters, Cluster.frames, and Frame.mux_static_signals, even if Database.show_invalid_from_open is False and Configuration Status returns an error code. For example, if you open a Frame with valid properties, then you set Signal.start_bit beyond the Frame.payload_len, Frame.check_config_status raises an exception, but the frame is returned from Cluster.frames.

Type:bool