Adding and Naming UCSs

To create a new UCS, declare a variable of the OdDbUCSTableRecordPtr type and use the pseudo-constructor of the UCS record object. This pseudo-constructor is a static method that creates a new dynamic UCS instance and returns the smart pointer to it. For example:


OdDbUCSTableRecordPtr pUCS = OdDbUCSTableRecord::createObject();

The created instance is independent from the database. Many properties of the UCS record object are invalid and the UCS instance does not get an ID until the UCS is added in the database. The UCS table object cannot manipulate the new UCS without the OdDbObjectId instance associated with the created UCS record object. The new UCS instance gets an empty name by default. The UCS table object cannot identify a UCS without a name. Therefore, after creation, the program must assign a name to the new UCS, and then must add it to the UCS table of the database. The UCS name is an arbitrary nonempty 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 get the name, use the getName() method of the UCS record object; it does not have arguments and returns the UCS name as an OdString value. For example:


OdString sName = pUCS->getName();
odPrintConsoleString(L"\nUCS has the name: %s", sName.c_str());

To set the name, use the setName() method of the UCS record object; itrequires the name as a non-empty OdString value and does not return a value. For example:


pUCS->setName(L"NewUCS");

If the UCS name contains inadmissible letters, the setName() method generates the exception: «37 - Invalid Symbol Table name». If the UCS name is an empty string, the setName() method generates the exception: «106 - Empty Record name».

To add the UCS in the UCS table, use the add() method of the UCS table object which requires one argument — the pointer to the UCS instance to be added — and returns the OdDbObjectId instance associated with the added UCS record object. The pUCSs variable stores a pointer to the UCS table object. For example:


OdDbObjectId idUCS = pUCSs->add(pUCS);

If the UCS table already contains a UCS whose name coincides with the new name, the add() and setName() methods generate the exception: «104 - Duplicate Record name object [10]». The exception message contains the handle of the duplicate UCS in the square brackets. To check whether the UCS table contains a specified name, use the has() method of the UCS table object.

To catch exceptions, use the try … catch statement when the program adds the UCS record object in the table. The following example demonstrates the procedure:


void NewUCS(OdString sUCSName, OdDbUCSTablePtr pUCSs)
{
  if(sUCSName.isEmpty())

    odPrintConsoleString(L"\nThe UCS name is undefined\n");

  else if(sUCSName.findOneOf("<>/\\\":;?,|=`") != -1)

    odPrintConsoleString(L"\nThe UCS name contains inadmissible letters\n");

  else if(pUCSs->has(sUCSName))

    odPrintConsoleString(L"\nThe UCS with name \"%s\" already exists\n", sUCSName.c_str());

  else
  {
    OdDbUCSTableRecordPtr pUCS = OdDbUCSTableRecord::createObject();

    try {
      pUCS->setName(sUCSName);
      pUCSs->add(pUCS);
    }
    catch(OdError& e)
    {
      odPrintConsoleString(L"\nError: %d - %ls\n", e.code(), e.description());
      pUCS->erase();
    }
  }
}

See Also