Library part format

File extension

Most GDL Library Objects are saved with the *.gsm extension and they are distinguished by their subtype in ARCHICAD.
There is a special extension, *.gdl (GDL Script Files) for the MASTER_GDL/MASTEREND_GDL files.
ARCHICAD handles any GDL Script File starting with the string “MASTER_GDL…” or “MASTEREND_GDL…” in their file name in a special way.
These files can be used to load attribute definitions, define line types, and materials etc. (more information in The GDL Script Analysis).

Identification

The identifier

http://gdl.graphisoft.com/wp-content/uploads/ac19-gdl/BasicTechStandards_LibpartId.png

The ID consists of two parts, each 32 hexadecimal characters long.
The first 36 characters represent the Main ID and
the last 36 characters represent the Revision ID.

  • The Main ID is created when the library part is saved for the first time.
    It is also modified if the library part is resaved using the “Save as” command.
  • The Revision ID is also created when the library part is saved for the first time but it is modified
    if the library part is resaved using the “Save” command.
    Using the LP_XMLConverter tool a compilation will change the Revision ID and leave the Main ID untouched, of course.

This means that Main ID identifies a library part in its function
and the Revision ID helps in distinguishing the revisions
of the object. Let’s see this in practice.

Library Part Identification

When placing an object in , the program stores the reference by the ID and considers the name only for objects without an ID (library parts saved before ARCHICAD 8 and .gdl files).
In case of Library Parts coming from versions earlier than ARCHICAD 8, there was no such thing as a GUID.
So when such a Library Part is encountered in the file, will fill out its ID with zeros.

When loading a library, uses the following hierarchical criteria for matching loaded library parts to objects already placed in the project:

  • In case the stored ID is valid:

    1. tries to get an exact match of both parts of the ID
    2. Failing that, tries to match the first part of the ID, which is the Main ID.
    3. In case it doesn’t find one matching, it starts to check other elements’ Migration Table values to find a substitute.
    4. Finally, when loading files saved before ARCHICAD 12, tries to match by library part name.
  • In case the stored ID is zero, the identification procedure tries to match by name only.

The same process is executed when looking for macros in a placed element
as every library part contains a lookup table for its called macros’ GUIDs.
Naturally, when saving an object containing macro calls,
this table is collected using a name-based search in the currently loaded library.

How to know what the exact GUID of a Library Object is

For this you have to get to know the Subtype Hierarchy dialog window.
In this dialog you can see the subtype hierarchy of the currently loaded library in a tree view.
The main attributes – name, version, ID, file location,
flags indicating if the object is template or placeable –
of the selected library part are displayed in the bottom of the window.

This dialog appears in 3 contexts:

  • Open Object by Subtype… (in File menu)
  • Select Subtype… (in the Library Part Editor window)
  • Place All Objects (in the Special menu)

Naturally, you can read the ID in the XML format of the library part (location: xpointer (/Symbol/@UNID)).
To get this, use the LP_XMLConverter tool.

Compatibility issues

The most important principle is that the Main ID represents a constant functionality to the users of the library.
This means that if you publish a new library part using a Main ID that is already in use by an old library part,
when loading an old project with the new library, the old placed elements will be replaced by the new object.

This contradicts the users’ expectations, such as there will be no change in the object’s parameters and their functions.
If you want to change the name or the function of old parameters, generate a new Main ID and use migration scripts to
avoid ambiguity and unexpected data loss. Make sure that this new Main ID is unique – not identical with any other ID in the library.

Note, that renaming an object won’t make it incompatible with its past self for as long as their MainIDs remain identical.
Similarly, giving the name of an existing library part to a new one (with a new ID) will not make them compatible.

Compatibility of localized libraries

This issue effects the localization of libraries, too.
If you have string type controlling parameters, the relevant values will differ between national versions.
For example:
if you are unaware of the problem, loading a German plan file with the Danish sibling library
will change the generated elements since some control parameters have meaningless values.

There are two solutions:

  1. The easy way is to declare that the German and Danish libraries have nothing to do with each other and to change the Main IDs in localization consequently.
  2. The second – and more user friendly – solution is to create an integer type control parameter acting as string (see VALUES).

These integer parameters are determinant, the visible string descriptions are just an input method for them (therefore localizations can be different, but the true meaning will stay the same).
When writing a script, the integer parameter values should be used.

The following example code features a detail level integer parameter acting as a string type:

http://gdl.graphisoft.com/wp-content/uploads/ac19-gdl/BasicTechStandards_stringInteger.png
! Master script:
dim stDetlevel3DDesc [3]
stDetlevel3DDesc[1]=`Detailed`
stDetlevel3DDesc[2]=`Simple`
stDetlevel3DDesc[3]=`Off`

! iDetlevel3D constants
DETLEVEL3D_DETAILED = 1
DETLEVEL3D_SIMPLE   = 2
DETLEVEL3D_OFF      = 3

! Parameter script:
values{2} "iDetlevel3D"  DETLEVEL3D_DETAILED, stDetlevel3DDesc[1],
                         DETLEVEL3D_SIMPLE,   stDetlevel3DDesc[2],
                         DETLEVEL3D_OFF,      stDetlevel3DDesc[3]

Migrating Elements

It is possible to maintain a link between the old and the new, updated version (with new Main ID) of a library part by using migration scripts
(the section called “Forward Migration script”, the section called “Backward Migration script”) and the section called “Migration table”.

In these scripts you can define which library part substitutes which (by connecting the old and new Main ID-s),
and how to update the new object’s parameter values based on the old one (or vice versa).
You can set rules for the migration to happen only under certain parametric conditions.
If the subject of the migration meets these, the upgrade or downgrade is possible, otherwise it will not be an option.

Migrating Zones

Generally, it is possible for the subject of the migration to have one or more successors (or ancestors in backward migration) depending on parameter settings.
The case is a little different when migrating Zone Stamps, though.
One type of Zone Stamp can be linked to many Zone Categories. But each category can use only one kind of Zone Stamp.

When migrating a Zone Stamp, the Category stays the same.
If the route of migration diverges (“Zone Old” is upgraded to “Zone New 1”, or to “Zone New 2”, depending on different parameter settings),
it is possible to get a Category with two different Stamps linked.
While this is a valid result regarding the migration process, it is an inconsistent situation for ARCHICAD.
Make sure you only migrate Zone Stamps in a direct way, to avoid this.