Home > Getting Started Guide > Application Interface > Attributes

Attribute Derivation Macros

This section describes some of the macros used to facilitate the definition of new attribute classes; they are illustrated in examples. These macros are defined in file at_macro.hxx. Because attributes are derived from entities, attribute macros are very similar to the entity macros defined in entity.hxx. For more information, refer to the section on entity derivation macros in the Quick Reference Guide.

User-Defined Attribute Macros

Developers must define the following macros to use the predefined attribute macros.

THIS()
The name of this class being defined
PARENT()
The name of the immediate base class (parent)
THIS_LIB
The name of the module (library) in which this class is implemented
PARENT_LIB
The name of the module (library) in which the immediate base class (parent) is implemented
<class>_NAME
The entitys external identifier (<class> is the class name)

You must define THIS() and PARENT() with empty parentheses and THIS_LIB and PARENT_LIB without parentheses. A string must be provided for <class>_NAME.

Predefined Attribute Macros

The predefined attribute macros perform definitions and tasks common to all derived attribute classes. Each attribute class has many methods. Because most of the methods are common to all attribute classes, macros simplify the definition of these methods.

The following macros are used for constructing an applications master attribute. This is the sentinel level organization attribute class that is constructed entirely by the macros:

MASTER_ATTRIB_DECL
Declares an master (organization) attribute class, which has no data or methods of its own. This macro includes the macros defined by the ATTRIB_FUNCTIONS macro.
MASTER_ATTRIB_DEFN
Generates all the code necessary to define a master (organization) attribute class.

The following attribute macro should be invoked in the header file for declaring a derived specific attribute:

ATTRIB_FUNCTIONS
Declares common utility routines (including ENTITY methods inherited by ATTRIB).

The following attribute macros should be invoked in the implementation file for defining a derived specific attribute. The macros should appear in this order.

ATTRIB_DEF
This is a heading macro that combines four macros (ATTCOPY_DEF, LOSE_DEF, DTOR_DEF, DEBUG_DEF) in sequence, for the common case of attributes that do not need any special action in the destructor or in duplication. If special handling is needed, the individual macros should be invoked instead of ATTRIB_DEF.
SAVE_DEF
Completes the debug_ent method and begins the save_common method. Place actions that write out specific attribute information to the save file and insert any pointers into the list immediately following this macro.
RESTORE_DEF
Completes the save_common method and begins the restore_common method. Place actions that read in specific attribute information from the save file immediately following this macro.
COPY_DEF
Completes the restore_common method and begins the copy_common method. Place actions that copy data items into the new object, using the input list to convert any pointers to indices immediately following this macro call.
SCAN_DEF
Completes the restore_common and begins the copy_scan method, which is used in many places in the system to gather a list of connected entities. The SCAN_TYPE reason may indicate the type of scan being performed. Depending on the reason, your implementation should insert any pointers into the input list immediately following this macro.
FIX_POINTER_DEF
Completes the copy_scan method and begins the fix_common method. The fix_common method is often called during two circumstances:
  • during the final stage of restore, and
  • during the final stage of a copy (like api_copy_entity).
Use this method to map indices from the given array of entities to actual pointer values.
TERMINATE_DEF
Terminates the definitions supplied by the *_DEF macros.

In the case of attributes that need special handling in the destructor or in duplication, the following macros should be used (in this order) instead of ATTRIB_DEF:

ATTCOPY_DEF
Invokes the UTILITY_DEF macro, which provides stock definitions for several required ENTITY functions and static data for the restore function and dynamic virtual functions.
This macro then starts the definition of the fixup_copy method. Immediately following the ATTCOPY_DEF macro, place any special action required to duplicate the attribute for roll back purposes. The attribute itself has been copied member wise, but if there is a subsidiary structure hanging off a simple pointer (a character string hanging off a char pointer, for example) it requires copying or otherwise processing here.
ATTCOPY_DEF is used like ATTRIB_DEF, but must be followed by LOSE_DEF, DTOR_DEF, and DEBUG_DEF (in that order).
LOSE_DEF
Defines this attributes lose method. Place any special actions required to lose any dependent entities immediately following this macro.
DTOR_DEF
Defines the attributes destructor, which is called to permanently release all memory back to the operating system. Place any special actions required during attribute destruction immediately following this macro call. For example, a subsidiary data structure may need to be deleted.
DEBUG_DEF
Calls the debug_ent method, which is used to produce neatly formatted, human readable information about the contents of the entity in the debug file. Place actions that write out useful information from the attribute for debugging purposes immediately following this macro.

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.