Getting and Checking UCSs

The UCS table object has the has() method for checking a UCS in the table and the getAt() method for getting an existing UCS from the table. The pUCSs variable stores a pointer to the UCS table object. The following example adds three UCSs in the table and deletes one of them:


OdDbUCSTableRecordPtr pUCS;

pUCS = OdDbUCSTableRecord::createObject();
pUCS->setName("UCS_X");
pUCSs->add(pUCS);

pUCS = OdDbUCSTableRecord::createObject();
pUCS->setName("Erased_UCS");
pUCSs->add(pUCS);
pUCS->erase(true);

pUCS = OdDbUCSTableRecord::createObject();
pUCS->setName("UCS_Y");
pUCSs->add(pUCS);

To check whether the UCS exists in the UCS table, use the has() method of the UCS table object that requires either the existing UCS name or the ID associated with the existing UCS record object as an argument of the method. The method returns True if the UCS exists in the table or returns False if the UCS is absent from the table or is erased. For example:


// Check the unerased UCS object by name
odPrintConsoleString(L"\nUCS_X %ls in the table", ((pUCSs->has("UCS_X")) ? L"exists" : L"absents"));

// Check the unerased UCS object by ID
odPrintConsoleString(L"\nUCS_Y %ls in the table", ((pUCSs->has(pUCS->objectId())) ? L"exists" : L"absents"));

// Check the erased UCS object (result is absent)
odPrintConsoleString(L"\nErased UCS %ls in the table", ((pUCSs->has("Erased_UCS")) ? L"exists" : L"absents"));

To get a UCS from the UCS table, use the getAt() method of the UCS table object, which requires either the name or ID of the UCS record object as a parameter for searching. The getAt() method has two implementations.

The first implementation of the getAt() method returns the smart pointer to the existing UCS record object that satisfies the specified parameters and requires three arguments:

The first argument is mandatory and specifies the UCS name as a nonempty OdString value that satisfies the parameters for naming objects.
The second argument is optional and specifies the mode for opening the UCS record object as a value of the OdDb::OpenMode enumerator (kForRead, kForWrite, or kForNotify). The value is OdDb::kForRead by default.
The third argument is optional and specifies the erase status as a Boolean value. Specify True when the UCS table object must open an erased UCS record object, or specify False when the UCS table object must open an unerased UCS record object. The value is False by default.

To get the smart pointer to the UCS record object, declare a variable of the OdDbUCSTableRecordPtr type and use the first implementation of the getAt() method. For example:


// Get the unerased UCS object in the read mode
OdDbUCSTableRecordPtr pUCS1 = pUCSs->getAt("UCS_X");

// Get the unerased UCS object in the write mode
OdDbUCSTableRecordPtr pUCS2 = pUCSs->getAt("UCS_Y", OdDb::kForWrite, false);

// Get the unerased or erased UCS object in the notify mode
OdDbUCSTableRecordPtr pUCS3 = pUCSs->getAt("Erased_UCS", OdDb::kForNotify, true);

The second implementation of the getAt() method returns the OdDbObjectId instance associated with the UCS record object that satisfies the specified name and requires two arguments:

The the first argument is mandatory and specifies the UCS name as a nonempty OdString value.
The second argument is optional and specifies the erase status as a Boolean value. The value is False by default.

To get the ID of the UCS record object, declare a variable of the OdDbObjectId type and use the second implementation of the getAt() method. For example:


// Get the ID of the unerased UCS object
OdDbObjectId idUCS1 = pUCSs->getAt("UCS_X");

// Get the ID of the unerased UCS object
OdDbObjectId idUCS2 = pUCSs->getAt("UCS_Y", false);

// Get the ID of the erased UCS object
OdDbObjectId idUCS3 = pUCSs->getAt("Erased_UCS", true);

To get the smart pointer to a UCS instance using an ID, use the safeOpenObject() method of the OdDbObjectId object which opens the UCS record object associated with the specified ID in the specified mode for the specified erase status, and then returns the smart pointer to it. For example:


// Get the unerased UCS object in the read mode using ID
OdDbUCSTableRecordPtr pUCS1 = idUCS1.safeOpenObject();

// Get the unerased UCS object in the write mode using ID
OdDbUCSTableRecordPtr pUCS2 = idUCS2.safeOpenObject(OdDb::kForWrite, false);

// Get the unerased or erased UCS object in the notify mode using ID
OdDbUCSTableRecordPtr pUCSe3 = idUCS3.safeOpenObject(OdDb::kForNotify, true);

These operations can be combined in one line:


OdDbUCSTableRecordPtr pUCS = pUCSs->getAt("UCS_Y").safeOpenObject(OdDb::kForWrite);

When the erase status is False, the getAt() method gets the UCS record object if and only if it is marked as "unerased". When the erase status is True, the getAt() method gets the UCS record object of any status, that is, marked as "erased" or "unerased".

The getAt() method returns ID = kNull or smart pointer = Null when a UCS with the specified name is absent from the UCS table, is permanently deleted, cannot be opened in the specified mode, or is marked as "erased" when the status argument is False. For example:


// When ID = kNull
OdDbObjectId idUCS = pUCSs->getAt("UCS_N");
if(idUCS.isNull())
  odPrintConsoleString(L"\nThe UCS_N can not be opened\n");

// When Pointer = null
OdDbUCSTableRecordPtr pUCS = pUCSs->getAt("UCS_N", OdDb::kForWrite);
if(pUCS.isNull())
  odPrintConsoleString(L"\nThe UCS_N can not be opened\n");

Before getting a UCS, use the has() method to check whether the UCS with the specified name exists in the UCS table.

See Also