Class
names in this API begin with "AcMapOSE". Use it for all new development
that involves Oracle Spatial access, or consider using the
Although the earlier implementation of the Oracle Spatial API remains in place, and existing code that is based on it is still valid, it is deprecated. Class names in the earlier Oracle Spatial API begin with "AcMapOracle". The AcMapOracle classes are described in the AutoCAD Map 3D ObjectARX Reference, but they are not discussed in the Developer's Guide.
Before you can do anything else, you must get the AcMapOSEConnection object.
So long as AutoCAD Map 3D is running, there is always an AcMapOSEConnection object, even if no connection is currently in effect. The object is instantiated automatically when an AutoCAD Map 3D session opens, and is destroyed automatically when the session closes.
Because the AcMapOSEConnection object is unique within a session, there can never be more than one connection in effect at a time. To connect, disconnect, or change the current connection, you modify this unique object. You can modify it (or assess its state) either through the the UI or the API. It's the same object either way.
In addition to functions for modifying or assessing its state, the AcMapOSEConnection object has functions for managing reactors. For example, to monitor and react to connection events, subclass a custom reactor from AcMapOSEConnectionReactor, and then add an instance of it to your application using AcMapOSEConnection::AddConnectionReactor(). Similarly, you can create and add reactors for import and export events.
To add new records to the Oracle database, or to update records that were imported and then edited by adding, changing, or deleting data, use an AcMapOSEExport object. To set export options and specify which features will be exported, use AcMapOSEExport::Init().
Note that an AcMapOSEExport object has two functions for exporting. ExportObjects() exports objects listed in an AcDbObjectIdArray. ExportObjectsAll() exports all objects in the drawing database. Both functions export only features specified in the vFeaturesNames argument of AcMapOSEExport::Init(), and both functions are subject to export options specified by the nOptions argument of AcMapOSEExport::Init(). Option values are defined in the AcMapOSEExport::EExportOptions enumeration.
To monitor and react to export events, use a custom subclass of AcMapOSEExportReactor.
Note that, for the sake of performance, the export operation does not process a set of objects one by one. Rather, it collects the objects with their associated data in a cache and then bulk-processes them. The complement of AcMapOSEExportReactor functions reflects this two-step process.
To import objects from an Oracle database to a project drawing, first use an AcMapOSEQuery object to specify conditions for the objects to import, and then use an AcMapOSEImport object for the import itself.
You can initialize the AcMapOSEQuery object with
- The current import query, as defined in the Import dialog box in the user interface.
- An import query loaded from the Oracle database after saving one there previously.
- An explicit set of conditions.
After initializing the AcMapOSEQuery object, you can convert its query to SQL format for viewing purposes.
To monitor and react to import events, use a custom subclass of AcMapOSEImportReactor.
In Oracle databases, entities have Oracle IDs (OValue). In AutoCAD databases, they have AutoCAD IDs (AcDbObjectId). When drawing objects are imported from an Oracle database to a project drawing (AcMapProject object), AutoCAD Map 3D assigns them AutoCAD IDs, but keeps track their corresponding Oracle IDs. Note however, that this information is discarded without saving when the drawing closes, which means that the entire process of updating a set of Oracle records — importing, editing, exporting — must run from start to finish on a continuously open drawing.
For
information about getting corresponding IDs, click
If you have imported a set of records from an Oracle database, and you need to know explicitly which record is associated with a given drawing object (entity), or which entity with a given record, you can use an AcMapOSEObject object to find out. After intializing such an object with an entity's AutoCAD ID, you can get its Oracle ID, and vice-versa, provided that the drawing has remained open since the entity was imported. If the drawing has not remained open, imported entities lose their imported status, in which case, instead of the AcMapOSEObject object giving you an Oracle ID in exchange for an entity's AutoCAD ID, it gives you 0 (an invalid key value), as it does for any entity that is not an imported one.
For
information about Oracle and AutoCAD IDs, click
You can use AcMapOSEObject functions to get other information about a queried object besides its AutoCAD or Oracle ID. For example, its EditSet status, in or out.
To filter new objects from a set of drawing objects, use AcMapOSEProject::FilterNewObjects(). In addition, you can constrain the result by feature or edit-set status (in or out).
Likewise, to filter queried objects, use AcMapOSEProject::FilterQueriedObjects(). In addition, you can constrain the result by feature or edit-set status (in or out). Queried objects are delivered in three subsets by edit status: erased, modified, and unchanged.
When an AutoCAD Map 3D operation fails, the error message and error code are pushed to the error stack (AcMapErrorStack). In the event of an error, check the stack to discover what went wrong and take appropriate action.
For more information about AutoCAD Map 3D and Oracle Spatial data, refer to
- User Interface Help for the Polygon and Advanced Oracle Extension to AutoCAD Map 3D— In the Autodesk Map application, click the question mark icon in the Polygon And Advanced Oracle Extension toolbar.
To view code samples, click links below.
Connecting to an Oracle Spatial Database
Exporting to an Oracle Spatial Database
Importing from an Oracle Spatial Database
The following topics describe sample ObjectARX projects. The project folders are under Map Samples\Oracle Spatial in your AutoCAD Map 3D ObjectARX installation.
Storing Block Attribute Positions in an Oracle Spatial Database
Storing Block Definitions in an Oracle Spatial Database
Importing From an Oracle Spatial Database
Note The sample projects that are located in Map Samples\Oracle are for the earlier Oracle Spatial implementation, which is still supported, but is now deprecated.