For MicroStation V8, the DGN file format has been expanded to include essentially all of the graphic entities, objects, and other concepts of AutoCAD's DWG files. When a DWG file is opened in MicroStation, the DWG entities are converted to equivalent DGN elements. Because the DGN format is a superset of DWG, there are no losses resulting from concept misalignment and this process can be thought of as more of a reformatting than a translation.
As applications continue to see the DGN representation of the DWG data, applications developed to run with on MicroStation with DGN files will for the most part work without change when DWG files are being used. Tools that are developed to edit, query or create DGN geometry will continue to function, and MicroStation largely handles the conversion to DWG automatically and seamlessly.
This chapter covers two essential areas that developers may want to take advantage of when writing MDL applications that read and write data as DWG entities.
There are two primary methods for adding application data to DWG files. Both of these techniques have analogues within the DGN format. Extended Data (xdata) can be added to any entity in a manner very similar to element linkages. Extended Records (Xrecords) are non-graphic objects that can store arbitrary application data in a manner that is somewhat analogous to MicroStation's (Type 66, Level 20) application elements.
When designing applications that are to store data in DWG files there are essentially two approaches to take. The MicroStation oriented approach is appropriate for most applications and simply involves using the existing MicroStation API to create element linkages and application elements just as you would with a DGN file and leaving the conversion of this data to and from DWG to MicroStation. A second, more AutoCAD oriented approach is appropriate for applications that must deal with existing AutoCAD application data or applications where accessing application data within AutoCAD is required.
If the configuration variable MS_DWGSAVEAPPLICATIONDATA is set then application data created by a MicroStation application using conventional methods is preserved in a manner that is essentially transparent to the applications that create or access the data. This is accomplished by automatically converting element linkages and application elements to their equivalent AutoCAD analogues when a DGN file is saved to DWG or new data is added while editing a DWG file. When the DWG file is reopened, the application data is then extracted and restored to element linkages and application elements that exactly match the original data.
An important limitation to the DWG file format is that the concept of normal (unshared) cells does not exist. Typically this means that when a cell is saved to DWG it is converted to a shared cell instance and a definition. As cells are important building blocks for many MicroStation applications, MicroStation will automatically preserve and restore any cell with an application linkage when they are saved with the MS_DWGSAVEAPPLICATIONDATA variable set. The application will continue to see the normal cell and is not required to deal with shared cell instances.
For many simple applications, simply setting MS_DWGSAVEAPPLICATION data will allow the application to run without change on DWG files. For example, many of the MDL examples such as the "Circuit" application work equally well in DWG or DGN files.
Implementation Details
When DGN application data is saved to DWG with MS_DWGSAVEAPPLICATION set, the element linkages are converted to binary extended data and stored under the application name "Mstation". In general, this is completely transparent to the application. The extended data can be viewed in AutoCAD, although since it is binary it not particularly useful. In DXF format, one of these linkages would appear as follows:
. . 1001 MStation 1000 Lnkg 1002 { 1004 1310840301000000010000009A999999999928403333333333333740010000000900000 000000000 1002 }
In a similar manner, application elements (Type 66, Level 20) are converted to xrecords These records could be located within AutoCAD by first finding the "MicroStation" Extended Dictionary entity and then traversing the "Application Element" records of that dictionary. Again, the information is simply a binary representation of the type 66 contents.
In many instances, it may be necessary to access application data that is either generated by AutoCAD applications or to generate or manipulate data that must be accessible from AutoCAD applications. In this case the MicroStation-Centric approach described above is not suitable as the data is encapsulated within binary blobs that are not readily visible outside of the MicroStation application.
In order to efficiently access DWG application data it is necessary to at least briefly mention a few important DWG concepts. A complete discussion of the AutoCAD application extensions is beyond the scope of this document and the reader is referred to the AutoCAD Developer documentation for more detailed information.
In order for an application to properly add extended data to an entity it must first identify itself by placing an entry in the files registered application table. The application registration process will generate an ElementID that uniquely identifies the application. This Element ID of this table entry is then inserted as the first entry in a series of extended data records and all of the records that follow are implicitly owned by that application. Unlike MicroStation's linkage Ids where an application requests a single ID value that will uniquely identify their linkage in any design file, the registered application ID will be different for each file. The mdlRegApp_idFromName function can be used to either find an ID from a previously registered application or to register a new application and obtain a new ID. The mdlRegApp_nameFromId function is used to extract the name for an existing application ID.
Extended data (xdata) is the functional equivalent of MicroStation's element linkage. Extended data can be attached to any entity and consists of a data entries preceded by "group codes" that denote their type. The order of these group codes implies the application ownership - an application precedes it group data with its application ID and any data following that ID and up to the next application ID belongs to that application. Except for beginning with an application ID, the order and content of the extended data is determined by the application. The group code values are completely described in the AutoCAD documentation, but the more common values are defined in msdefs.h as follows:
#define DWGXDATA_String 1000 #define DWGXDATA_Application_Name 1001 #define DWGXDATA_ControlString 1002 #define DWGXDATA_LayerName 1003 #define DWGXDATA_BinaryData 1004 #define DWGXDATA_DatabaseHandle 1005 #define DWGXDATA_Point 1010 #define DWGXDATA_Space_Point 1011 #define DWGXDATA_Disp_Point 1012 #define DWGXDATA_Dir_Point 1013 #define DWGXDATA_Real 1040 #define DWGXDATA_Dist 1041 #define DWGXDATA_Scale 1042 #define DWGXDATA_Integer 1070 #define DWGXDATA_Long_Integer 1071
An application can add extended data to an element with the mdlLinkage_addXDataGroupCode function as demonstrated in the code fragment below (from the example application dwgappdata)
if (SUCCESS == mdlRegApp_idFromName (®AppID, s_applicationName, dgnFile, TRUE)) { char *pTestString = "Test String"; DPoint3d testPoint = {1.0, 2.0, 3.0}; mdlLinkage_addXDataGroupCode (&pDescr, DWGXDATA_Application_Name, ®AppID, sizeof(regAppID)); mdlLinkage_addXDataGroupCode (&pDescr, DWGXDATA_String, pTestString, strlen (pTestString)); mdlLinkage_addXDataGroupCode (&pDescr, DWGXDATA_ControlString, "{", 1); mdlLinkage_addXDataGroupCode (&pDescr, DWGXDATA_Point, &testPoint, sizeof(&testPoint)); mdlLinkage_addXDataGroupCode (&pDescr, DWGXDATA_ControlString, "}", 1); }
The extended data created by this code fragment would appear in a DWG file as follows:
1001 TEST_APPLICATION 1000 Test String 1002 { 1010 1.0 1020 2.0 1030 3.0 1002 }
Similarly, an application can look for extended data on an element with mdlLinkage_findApplicationXData. If the element contains extended data for the supplied application then the function returns success and the index of that application's extended data.
The extended data can then be read by repeatedly calling mdlLinkage_getXDataGroupCode to extract each the individual group codes and their associated data. See the dwgappdata application for an example of that illustrates the extraction of extended data.
Extended Records (xrecords) are the DWG equivalent of MicroStation's application (type 66, level 20) elements. The are similar to extended data in that they contain a series of data chunks with the data type denoted by a group code.
In order to locate extended records or other objects a DWG file contains a series of "Dictionary Objects". A dictionary contains a series of entries that contain a name and the ID of an element associated with that entry. An application will typically add an extended dictionary to a file that contains entries for each of its extended records. The application's extended dictionary is located by an application supplied, unique name in the file's main dictionary. The mdlDictionary_findDictionary function can be used to find an application dictionary. The mdlDictionary_extractEntry function can then be used to extract the dictionary entries.
Once a dictionary element is located, its data can be extracted by using the mdlXRecord_extractGroupData and mdlXRecord_getGroupCode functions. See the dwgappdata application for an example that demonstrates this process.
Note: Version 8.1 does not currently contain functions for creating extended record entities. These functions are under development and will be provided in a future version.