Aborts the transaction. Note that an abort() implicitly closes the transaction. A closed transaction does not allow any future operations and needs to be released.

Retrieves an element from the database. The database searches for the most recent version of the named DB element visible for the current transaction. That version will be returned.

Parameters

name

The name of the element to retrieve.

Returns

The requested element from the database, or NULL if name is invalid, no DB element with that name exists, or the transaction is already closed.

Retrieves an element from the database. The database searches for the most recent version of the named DB element visible for the current transaction. That version will be returned.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid&) on the returned pointer, since the return type already is a const pointer to the type T specified as template parameter.

Parameters

name

The name of the element to retrieve.

Returns

The requested element from the database, or NULL if name is invalid, no DB element with that name exists, the transaction is already closed, or the element is not of type T .

Commits the transaction. Note that a commit() implicitly closes the transaction. A closed transaction does not allow any future operations and needs to be released.

Returns

• 0: Success.
• -1: Unspecified failure.
• -3: The transaction is not open.

Creates a copy of a database element. Note that DB elements of type mi::neuraylib::IModule and mi::neuraylib::IFunction_definition can not be copied.

Parameters

source

The name of the element to be copied.

target

The desired name of the copy.

privacy

The desired privacy level of the copy (in the range from 0 to the privacy level of the scope of this transaction). In addition, the constant LOCAL_SCOPE can be used as a shortcut to indicate the privacy level of the scope of this transaction without supplying the actual value itself.

Returns

• 0: Success.
• -2: Invalid parameters (NULL pointer).
• -3: The transaction is not open.
• -4: There is no DB element named source visible in this transaction.
• -5: Invalid privacy level.
• -6: DB elements of this type cannot be copied.
• -9: There is already an element of name name and overwriting elements of that type is not supported. This applies to elements of type mi::neuraylib::IModule and mi::neuraylib::IFunction_definition. It also applies to elements of type mi::neuraylib::IFunction_call that are used as defaults in an mi::neuraylib::IFunction_definition.

Creates an object of the type type_name. Objects created with this method are typically

Types and Scene elements. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.

This method can not be used to create MDL modules, definitions, or function calls. To create instances of mi::neuraylib::IFunction_call, use the method mi::neuraylib::IFunction_definition::create_function_call().

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Parameters

type_name

The type name of the object to create. See Types for possible type names. In addition, Scene elements can be created by passing the name of the requested interfaces without namespace qualifiers and the leading "I", e.g., "Image" for mi::neuraylib::IImage. Note that you can not create instances of mi::neuraylib::IAttribute_set or mi::neuraylib::IScene_element, only instances of the derived interfaces.

argc

The number of elements in argv. Passed to the constructor of factory of the object to create.

argv

The array of arguments passed to the constructor. Passed to the constructor of factory of the object to create.

Returns

A pointer to the created object, or NULL if type_name is invalid ( NULL pointer) or not a valid type name.

Creates an object of the type type_name. Objects created with this method are typically

Types and Scene elements. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.

This method can not be used to create MDL modules, definitions, or function calls. To create instances of mi::neuraylib::IFunction_call, use the method mi::neuraylib::IFunction_definition::create_function_call().

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Note that there are two versions of this templated member function, one that takes no arguments, and another one that takes one or three arguments (the type name, and two optional arguments passed to the constructor or factory). The version with no arguments can only be used to create a subset of supported types derived from mi::IData: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays, structures, maps, and pointers. The version with one or three arguments can be used to create any type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with no arguments with a template parameter where the type name can not be deduced results in compiler errors.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

type_name

The type name of the object to create. See Types for possible type names. In addition, Scene elements can be created by passing the name of the requested interfaces without namespace qualifiers and the leading "I", e.g., "Image" for mi::neuraylib::IImage. Note that you can not create instances of mi::neuraylib::IAttribute_set or mi::neuraylib::IScene_element, only instances of the derived interfaces.

argc

The number of elements in argv. Passed to the constructor of factory of the object to create.

argv

The array of arguments passed to the constructor. Passed to the constructor of factory of the object to create.

Returns

A pointer to the created object, or NULL if type_name is invalid ( NULL pointer), not a valid type name, or does not create an object of type T .

Creates an object of the type T. Objects created with this method are typically

Types and Scene elements. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.

This method can not be used to create MDL modules, definitions, or function calls. To create instances of mi::neuraylib::IFunction_call, use the method mi::neuraylib::IFunction_definition::create_function_call().

The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.

Note that there are two versions of this templated member function, one that takes no arguments, and another one that takes one or three arguments (the type name, and two optional arguments passed to the constructor or factory). The version with no arguments can only be used to create a subset of supported types derived from mi::IData: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays, structures, maps, and pointers. The version with one or three arguments can be used to create any type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with no arguments with a template parameter where the type name can not be deduced results in compiler errors.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Returns

A pointer to the created object.

Retrieves an element from the database and returns it ready for editing. The database searches for the most recent version of the named DB element visible for the current transaction. It will then make a copy of that version and return the copy. The edited DB element will be committed to the database automatically, when the obtained interface is released. It is neither necessary nor possible to store the edited element manually in the database using the store() method.

Parameters

name

The name of the element to retrieve.

Returns

The requested element from the database, or NULL if name is invalid, no DB element with that name exists, or the transaction is already closed.

Retrieves an element from the database and returns it ready for editing. The database searches for the most recent version of the named database element visible for the current transaction. It will then make a copy of that version and return the copy. The edited DB element will be committed to the database automatically, when the obtained interface is released. It is neither necessary nor possible to store the edited element manually in the database using the store() method.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

name

The name of the element to retrieve.

Returns

The requested element from the database, or NULL if name is invalid, no DB element with that name exists, the transaction is already closed, or the element is not of type T .

Returns the ID of this transaction. The transaction ID is of most use when debugging an application as the value returned allows one to correlate log messages and admin HTTP server output with the API actions.

Returns

The ID of the transaction.

Returns the privacy level of the element with the name name.

Parameters

name

The name of the element.

Returns

• >= 0: Success. The privacy level of the element (in the range 0-255).
• -2: Invalid parameters (NULL pointer).
• -3: The transaction is not open.
• -4: There is no DB element named name visible in this transaction.

Returns the scope of this transaction.

Returns the time stamp describing the current "time".

See also:

has_changed_since_time_stamp(), get_time_stamp( const char*)const

Returns the time stamp of the last change of a database element.

See also:

has_changed_since_time_stamp(), get_time_stamp()

Checks whether an element has been stored or changed in the database since a given time stamp.

See also:

get_time_stamp(), get_time_stamp( const char*)const

Parameters

element

The name of the element.

time_stamp

The time stamp obtained from get_time_stamp() or get_time_stamp( const char*)const.

Returns

true if the element has been stored or changed since the time stamp (or if element or time_stamp is invalid, or there is no element with that name), false otherwise.

Indicates whether the transaction is open.

Returns

true if the transaction is still open, or false if the transaction is closed, i.e., it has been committed or aborted.

Returns scene elements of a subgraph originating at a given scene element. The method iterates over all elements of a subgraph originating at the given scene element and returns their names. Optionally, the results can be filtered by a regular expression for the element names and a list for type names.

Note that the runtime of the method depends on the number of elements in the subgraph. It might be expensive to call this method for large subgraphs.

The returned scene elements are in such an order that all elements referenced by a given element are listed before that element ("before" in the sense of "using smaller array indices").

Parameters

root_element

The root of the subgraph to traverse.

name_pattern

An extended regular expression that acts as filter on the names of returned scene elements (see [OGBS7]). The regular expression is matched to any part of the scene element name, not just to the entire scene element name. The value NULL is handled as ".*".

type_names

A list of type names that acts as filter on the names of returned scene elements. Only scene elements with a matching type name pass the filter. The value NULL lets all scene elements pass the filter irrespective of their type name.

Returns

A list of name of scene elements in the subgraph matching the given regular expression and type name filter, or NULL in case of an invalid root element name or an invalid regular expression.

Returns the name of a database element.

Parameters

db_element

The DB element.

Returns

The name of the DB element, or NULL if db_element is invalid ( NULL pointer), the object is not in the database, or the transaction is already closed.

Marks the element with the name name for removal from the database.

Global removals

The purpose of global removals is to mark all versions of a database element for garbage collection. Such a marker has no effect while the element is still referenced (in any scope) by other elements or while the transaction where the removal request was made is still open. When these conditions do no longer apply, the element becomes eligible for garbage collection and must no longer be used in any way. There is no guarantee when the garbage collection will actually remove the element.

This implies that a remove() call might actually remove an element that was stored later under the same name. This can potentially lead to invalid tag accesses. Those cases can be avoided by using mi::neuraylib::IDatabase::garbage_collection() after a transaction was committed and before starting the next one to force garbage collection of all possible elements.

Local removals

The purpose of local removals is to undo the effects of an earlier localization via mi::neuraylib::ITransaction::copy(). A local removal request requires that the element exists in the scope of the transaction, and at least one more version of that element exists in one of the parent scopes. The effect of a local removal request is to immediately hide the version the scope of the transaction (the local copy), and to make the next version in one of the parent scopes accessible from the very same transaction. The hidden local copy will be lazily removed by the garbage collection of the DB. There is no guarantee when this will happen.

Parameters

name

The name of the element in the database to mark for removal.

only_localized

false for global removals (the default) or true for local removals. The flag is ignored in favor of global removals if the transaction belongs to the global scope.

Returns

- 0: Success (including subsequent global removals on elements already marked for global removal).

• -1: For global removals: there is no DB element named name visible in this transaction. For local removals: there is no DB element named name in the scope of this transaction or there is no version of that DB element in one of the parent scopes.
• -2: Invalid parameters (NULL pointer).
• -3: The transaction is not open.

Stores the element db_element in the database under the name name and with the privacy level privacy. After a successful store operation the passed interface pointer must no longer be used, except for releasing it. This is due to the fact that after a store() the database retains ownership of the stored data. You can obtain the stored version from the database using the access() or edit() methods.

registered.

• -9: There is already an element of name name and overwriting elements of that type is not supported. This applies to elements of type mi::neuraylib::IModule and mi::neuraylib::IFunction_definition. It also applies to elements of type mi::neuraylib::IFunction_call that are used as defaults in an mi::neuraylib::IFunction_definition.

Parameters

db_element

The mi::base::IInterface to store.

name

The name under which to store db_element. If there exists already a DB element with that name then it will be overwritten

privacy

The privacy level under which to store db_element (in the range from 0 to the privacy level of the scope of this transaction). In addition, the constant LOCAL_SCOPE can be used as a shortcut to indicate the privacy level of the scope of this transaction without supplying the actual value itself.

Returns

• 0: Success.
• -1: Unspecified failure.
• -2: Invalid parameters (NULL pointer).
• -3: The transaction is not open.
• -4: db_element is not a DB element.
• -5: Invalid privacy level.
• -6: db_element has already been stored previously.
• -7: The element is to be stored in a transaction different from the one that was used to create it.
• -8: The element is a user-defined class that has not been

Symbolic privacy level for the privacy level of the scope of this transaction. This symbolic constant can be passed to store() and copy() to indicate the privacy level of the scope of this transaction. It has the same affect as passing the result of mi::neuraylib::IScope::get_privacy_level(), but is more convenient.