Redirects element creation into a temporary database for creating drawing data.

    GSErrCode ACAPI_Database (
        double*           dScale,
        API_PenType**     api_pens



[in] optional parameter (the default value is 1.0); defines the scaling from paper to model. For example, for 1:100 scaling, pass 100.
[in] optional parameter (the default pen table is coming from the current workspace (layout or model)); defines the pen table to use for this drawing data.
API 11  It should contain exactly 255 API_PenType records, starting from the first (index 0) record.


Return Values

The function has completed with success.
Calls to this function cannot be nested; you have to finish the previous drawing data with APIDb_StopDrawingDataID.

For other common API errors see the API Errors document.



This function opens an internal store for the drawing data (the internal data of a drawing element). Further element creation functions will put the created elements into this store. Only 2D elements (including figures/pictures) are allowed. This drawing data can be passed later in the drawingData member of the API_ElementMemo to ACAPI_Element_Create.

The pens have to be passed upfront in the api_pens parameter, and you cannot modify them later. This restriction is coming from the internal setup of the data store.



// -----------------------------------------------------------------------------
// Wraps importing data into IDF
// -----------------------------------------------------------------------------

class IDFSession {

    bool    inited;

    explicit IDFSession () {
        inited = (ACAPI_Database (APIDb_StartDrawingDataID, nullptr, nullptr) == NoError);

    ~IDFSession () {
        if (inited) {
            GSPtr outIDFData = nullptr;
            if (GetIDFData (&outIDFData, nullptr))
                BMKillPtr (&outIDFData);

    bool GetIDFData (GSPtr *outIDFData, API_Box *bounds) {
        if (!inited || outIDFData == nullptr)
            return false;

        bool ret = (ACAPI_Database (APIDb_StopDrawingDataID, outIDFData, bounds) == NoError);

        inited = false;
        return ret;

GSErrCode Import::Do ()
    IDFSession  idfSession;                                    // 1

    GSErrCode   ret = this->ReadAction::Do ();              // 2

    if (ret == NoError) {
        API_Box bounds  = { 0.0, 0.0, 0.0, 0.0 };
        GSPtr   idfData = nullptr;

        if (idfSession.GetIDFData (&idfData, &bounds)) {    // 3
            PlaceDrawing (idfData, bounds);                   // 4

    return ret;


  1. Initiates an IDF session; it redirects further element creation to the drawing data
  2. Reads the elements from an external file into the drawing data
  3. Stops the IDF session, fetches the drawing data & its bounds (calculated internally)
  4. Places the drawing element into the current database (internally calls ACAPI_Element_Create)



Version: API 10 or later
Header: APIdefs_Database.h


See Also

ACAPI_Element_Create, API_ElementMemo
API Functions