A predefined table object provides methods for adding, naming, deleting, and recovering records. A predefined table object does not create or delete its own records. Each named record object creates and deletes itself. In the following examples, the pTable variable stores a pointer to the predefined table object.

Creating a record

To create a new instance of the named record object, declare a smart pointer to the record object and use the pseudo-constructor of the corresponding type of record object. The pseudo-constructor is the static method that creates a new dynamic instance of the named record object and returns the smart pointer to it. For example, to create an instance of the registered application record object:

OdDbSymbolTableRecordPtr pRecord = OdDbRegAppTableRecord::createObject();

Naming a record

The created instance gets an empty name by default. A table cannot identify a record without a name, therefore the new instance must get an unique name. The name is an arbitrary non-empty string that can be up to 255 characters long and can contain letters, digits, blank spaces, underscores, and some special characters, but cannot contain inadmissible letters (see Naming objects).

To name a record object, use the setName() method which requires a non-empty OdString value as a new name and does not return a value. The new name must not coincide with other names of records in the table. For example::

pRecord->setName(L"My_Record");

To get the name, use the getName() method which does not have arguments and returns the record name as an OdString value. For example:

odPrintConsoleString(L"\nRecord name: \"%s\"", pRecod->getName().c_str());

Adding a record

The created instance exists independently from the database. Multiple properties of the record object are invalid and the instance does not get an ID until it is added in the database. The table object cannot manipulate the record instance without the OdDbObjectId instance associated with it. Therefore, after creating, the record instance must be added in the table.

To add an instance of the named record object in the predefined table object of the database, use the add() method; it requires one argument — the pointer to an existing instance of the specific record object of the corresponding type — and returns the OdDbObjectId instance associated with the added record object. The specific record object must be derived from the OdDbSymbolTableRecord class. The predefined table object sets the Owner ID property of the added record object to its own Object ID and becomes the owner for the record object. The record object must be named before adding it. For example:

OdDbObjectId idRecord = pTable->add(pRecord);

Deleting a record

To delete an existing instance of the named record object, get its ID or the smart pointer to it, open it in write mode, call its erase() method, and pass to it a True value as an argument. For example:

OdDbSymbolTableRecordPtr pRecord = pTable->getAt("My_Record", OdDb::kForWrite);
if(!pObj.isNull()) 
  pRecord->erase(true);

Or:

OdDbObjectPtr pObject = idRecord.safeOpenObject(OdDb::kForWrite);
pObject->erase(true);

The erase() method marks the record object as "erased", but it does not delete the record object if the database is performing an undo procedure. If the database is not performing an undo, the erase() method deletes the record object permanently.

Recovering a record

The erase status is used for recovering records in the table. If the named record object exists in the predefined table, but is marked as «erased», the erase() method with a False argument marks it as «unerased». To recover an existing instance of the named record object, get its ID or a smart pointer to it, open it in write mode, call its erase() method, and pass to it a False value as an argument. For example:

OdDbSymbolTableRecordPtr pRecord = pTable->getAt("My_Record", OdDb::kForWrite, true);
if(!pObj.isNull())
  pRecord->erase(false);

Or:

OdDbObjectId idObject = pTable->getAt("My_Record", true);
if(!idObj.isNull())
{
  OdDbObjectPtr pObject = idObject.safeOpenObject(OdDb::kForWrite, true);
  pObject->erase(false);
}

Note: If the record object was permanently deleted, the erase(false) method cannot recover it and generates the exception: "104 - Object was permanently deleted". If the named record object is absent from the predefined table, the getAt() method returns OdDb::kNull instance or a NULL pointer.

See Also

Working with Predefined Tables of Named Records

Getting and Checking Records

Iterating through Records

Example of Using the Record–Table and Dictionary Interfaces for Entering Names