Retrieves an attribute from the database.

    GSErrCode  ACAPI_Attribute_Get (
        API_Attribute*     attribute



[in/out] Parameters of the attribute. The type and the index or the name of the attribute must be passed in the typeID and index, or in the typeID and name fields in the attribute header. The data of the attribute is returned in the appropriate fields of the API_Attribute structure.


Return Values

The function has completed with success.
The passed parameter (attribute) is nullptr
The attribute type is invalid
The attribute index is invalid; if referenced by index
The attribute with the given name doesn’t exist; if referenced by name
The attribute doesn’t exist in the database.

For other common API errors see the API Errors document.



This function is used to retrieve one attribute’s data from the database. Beside the typeID, you should specify either the index or the name field of the header. In the latter case, the index field should be set to zero, and the attribute database is searched by name.

You may optionally call ACAPI_Attribute_GetDef to get extended information for certain attribute types.

The index range is not always continuous; deleted attributes are not purged immediately from the database.

Note: The received attributes can have dynamically allocated members depending on the typeID. They should be disposed when they are no more needed.

  • API_MaterialID: attribute.material.texture.fileLoc
  • API_ModelViewOptionsID: attribute.modelViewOpt.modelViewOpt.gdlOptions

Note: Special pen IDs can be used:

  • 1000: returns the color of the grid line
  • 1001: returns the color of the zone stamp
  • 1002: returns the color of the ghost story



/* Example I -- get an attribute */
API_Attribute     attrib;
GSErrCode         err;

BNZeroMemory (&attrib, sizeof (API_Attribute));

/* get the "Wave" line type */
attrib.header.typeID = API_LinetypeID;
CHCopyC ("Wave",;

err = ACAPI_Attribute_Get (&attrib);

/* Example II -- loop through all attributes of a kind */
API_Attribute  attrib;
short          nLin, i;
GSErrCode      err;

BNZeroMemory (&attrib, sizeof (API_Attribute));
attrib.header.typeID = API_LinetypeID;
err = ACAPI_Attribute_GetNum (API_LinetypeID, &nLin);
for (i = 1; i <= nLin && err == NoError; i++) {
    attrib.header.index = i;
    err = ACAPI_Attribute_Get (&attrib);
    if (err == NoError) {
        /* do what you want */
    if (err == APIERR_DELETED)
        err = NoError;



Version: API 1.3 or later
Header: ACAPinc.h


See Also

Attribute Manager, API Functions