User Documentation
of the LP_XMLConverter tool

Index

Abstract
File formats of the tool
1. Library Part Files
2. XML Files
Parameters and running
Usage tips

1. Abstract

The LP_XMLCoverter tool compiles XML files of a given format to ARCHICAD® Library Parts and vice versa on Windows and Macintosh platforms. Usage of the tool faciliates the creation process of ARCHICAD Libraries by the benefit of a cross-platform text-based format for the time of development.

2. File formats of the tool

The tool uses and generates XML and library part files. A library part file can be unequivocally transformed to one XML file and vice versa without losing any data (when using a correct codepage for transcoding, special characters may get lost otherwise).

The file names must comply with the codepage set in the Regional Settings of the operating system. For example you won't be able to compile a library with Greek file names on Western Codepage.

2.1 Library Part Files

The generated .gsm files are ARCHICAD library part files.

Library Part Identification

In short, two GUIDs - internally coded long numbers -, in combination with the object file name, identify each object. This identifier is called the Library Part ID and it helps ARCHICAD track the iterations of an object, as it is revised or improved. The ID consists of two parts: the first part is the Main ID and the second represents the Revision ID.

The Main ID is created when the library part is saved for the first time. It is also modified if a new library part is created based on an other 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 the Main ID identifies a library part in its function and the Revision ID helps in distinguishing the revisions of the object.

For more information refer GDL Technical Standards Chapter 2 (part of the Basic Library Documenation).

Encoding

The encoding of the texts is UTF-8 from ARCHICAD 11 on.

2.2 XML Files

The XML files are stored in UTF-8 encoding and the line breaks are UNIX linefeeds. The XML format is defined as XML Document Type Definition (DTD) and as XML Schema Definition (XSD) as well.

All binary sections of the library part - which are not resolved into XML elements - are saved with Windows byte order.

These properties quarantee the full platform independence of the XML format of library parts.

3. Parameters and running

Running LP_XMLConverter without parameters will print the version information.

You can get a quick overlook on the possible command line arguments by typing LP_XMLConverter help on the command line. The documentation provided herein is more detailed.

3.1 Convert files and directory trees

LP_XMLConverter libpart2xml [-l lang] [-img folder] [-cur file [-keepimagepath]] [-revids] [-compatibility ACversion] [-password pwd] source dest

Converts the library part file at location source to an XML at location dest.

LP_XMLConverter l2x         [-l lang] [-img folder] [-cur file [-keepimagepath]] [-revids] [-compatibility ACversion] [-password pwd] source dest

Converts all library parts (.gsm files) in the given (source) directory tree to XML files into the given (dest) directory recursively. Other files will be copied as binary files (images, .txt, .gdl, etc.).

-l lang: Language identifier for text conversion: UTF8, INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR. The default is the system codepage.
-img folder: Location of the image folder to create. The images in each library part will be extracted from the GSM file into subfolders and they will be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict) in the created XML files. See chapter Handling built-in images.
-cur file: Location of the current replacement file. The (binary or XML) file will be read in order to revert the parameter values, which were previously changed by a replacement definition XML, to their original values. See chapter Localization of default values.
-keepimagepath: Keeps the path and the filename of the images defined in section GDLPict and Picture. If you don't use this specifier, the path will be determined by the path of the library part and the ID of the picture.
-revids: Write full UNIDs (main GUID + revision GUID) to the XML files.
-compatibility ACversion: Write the XMLs in a format that is understandable by LP_XMLConverter for ARCHICAD ACversion. This is achieved by e.g. leavig out sections, which were introduced since then. ACversion should be between 10 and the current ARCHICAD version, the default is the current.
-password pwd: Decrypt the GSMs with the given password. If the password does not match, the GSM will not be converted to XML. The password can be at most 16 characters long.
source: In case of libpart2xml the location of the source GSM file. The file must exist.
In case of l2x the source directory of the library parts to convert. The directory must exist.
dest: In case of libpart2xml the location of the destination XML file. The parent directory must exist.
In case of l2x the destination directory for the converted XML files. The parent of the directory must exist.

LP_XMLConverter xml2libpart [-l lang] [-img folder] [-def file [-cur file [-keepimagepath]]] [-toplatform platform] [-setcopyright Author LicT LicV] [-password pwd] source dest

Converts the XML file at location source to a library part at location dest. If there was a library part at location dest, it is deleted first.

LP_XMLConverter x2l         [-l lang] [-img folder] [-def file [-cur file [-keepimagepath]]] [-toplatform platform] [-setcopyright Author LicT LicV] [-password pwd] source dest

Converts all XML files in the given (source) directory tree to library parts into the given (dest) directory recursively. Other files will be copied as binary files (images, .txt, .gdl, etc.).

-l lang

Language identifier for text conversion: UTF8, INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR. The default is the system codepage.

-img folder

Location of the image source folder. The images can be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict). The compiled library parts will contain the images in themselves. See chapter Handling built-in images.

-def file

Location of the replacement definition XML file. See chapter Localization of default values.

-cur file

A location where to create the current replacement file. The file will be written in XML format, if its extension is .xml, and in custom binary format otherwise (which is much faster). See chapter Localization of default values.

-keepimagepath

Keeps the path and the filename of the images defined in section GDLPict. See chapter Localization of default values.

-toplatform platform

Defines the target platform. Default is the current.

WIN: Windows
MAC_INTEL: Macintosh Intel
MAC_PPC: Macintosh PowerPC

-setcopyright Author LicenseType LicenseVersion

Sets the Copyright section (Author, License Type and License Version) in every written library part. If the XML contained a Copyright section, in the GSM these fileds will be overridden with the given values. If the XML did not contain a Copyright section, a Copyright section with the given values will be added to the GSM.

-password pwd

Encrypt the written GSMs with the given password. Can be at most 16 characters long. Note: LP_XMLConverter will reject encrypting GSMs that will be written with no Copyright section, or with License Type set to "" or "CC0". What Copyright section will be written depends on the source XML and the -setcopyright override option.

source

In case of xml2libpart the location of the source XML file. The file must exist.
In case of x2l the source directory of the XML files to convert. The directory must exist.

dest

In case of xml2libpart the location of the destination GSM file. The parent directory must exist.
In case of x2l the destination directory for the converted library part files. The parent of the directory must exist.

3.2 Fix the hierarchy of a library

LP_XMLConverter fixhierarchy libraryLocation [additionalLib ...]

Repairs the ancestry information, the version, the macro-call section and the parameter section of each library part file in the libraryLocation directory tree. Every changed library part gets a new Revision ID.

libraryLocation: Location of the (GSM) library to fix.
additionalLib: Locations of zero or more additional binary libraries. These libraries are used in fixing the references between library parts (which is based on library part IDs - see GDL Technical Standards Chapter 2.2 for details).

3.3 Make a full library

These commands are intended to serve in a make system, where libraries are developed. All of them check whether an XML file changed since the last compilation. For this, the IDEntryList.dbe file is used. In this file, the tool stores the ID and the MD5 checksum of all the source files. This data is used for each file as follows:

if the ID of the file is in the list
- if the stored and the actual checksums match up,
  the file will be skipped (since it is unchanged)
- if the stored and the actual checksums differ,
  the file will be compiled and the checksum and the ID will be updated in the list
if the ID of the file is NOT in the list
the file will be compiled and its ID and checksum will be added to the list

Non-XML text files (.gdl and .txt) can be stored in Unicode coding, character coding will be transformed to the givel local codepage. Non-XML binary files will be copied unchanged (images and everything except the XML and the foregoing text files).

LP_XMLConverter convertlibrary [options] source dest [additionalLib ...]

Compiles a directory tree of XML files to a directory tree of library parts.

LP_XMLConverter convchecklibrary [options] source dest [additionalLib ...]

Compiles a directory tree of XML files to a directory tree of library parts and checks the consistency of the whole library (ancestry information and macro-call section).

LP_XMLConverter makelibrary [options] source dest [additionalLib ...]

Compiles a directory tree of XML files to a library with a correct hierarchy. So this variant makes a convertlibrary and a fixhierarchy in succession.

LP_XMLConverter finalizelibrary [options] source dest [additionalLib ...]

Does makelibrary and updates 4 sections of the the XML files. These sections are: Ancestry, CalledMacros, ParamSection, and optionally Copyright (if -setcopyright is given). These sections change by re-saving the file (because of the GUIDs) and fixing the inconsistencies (done by fixhierarchy).

The options are: [-l lang] [-s suffix] [-suffix_placeable] [-img folder] [-def file [-cur file [-keepimagepath]]] [-toplatform platform] [-setcopyright Author LicT LicV] [-check level] [-verbose n] [-interface file] [-mastergdl file] [-skip_params file] [-password pwd]

-l lang

Language identifier for text conversion: UTF8, INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR. The default is the system codepage.

-s suffix

Optional suffix for names of all target folder. It can be used to distinguish library versions (e.g. Basic Library 21).

-suffix_placeable

If this switch is present, the suffix will be appended to placeable library parts also.

-img folder

Location of the image library. The images can be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict). See chapter Handling built-in images.

-def file

Location of the replacement definition XML file. See chapter Localization of default values.

-cur file

-keepimagepath

Keeps the path and the filename of the images defined in section GDLPict. See chapter Localization of default values.

-toplatform platform

Defines the target platform. Default is the current.

WIN: Windows
MAC_INTEL: Macintosh Intel
MAC_PPC: Macintosh PowerPC

-setcopyright Author LicenseType LicenseVersion

This argument works differently in the four modes.

convertlibrary: The parameter is ignored.
convchecklibrary: All library parts not in the additional libraries are checked, whether they have the given values (Author, License Type and License Version) in their Copyright sections.
makelibrary: For library parts, which were modified since the last finalizelibrary, and which depend on these, if they contain a Copyright section, the Copyright section (Author, License Type and License Version) is overridden with the given values. If they did not contain a Copyright section, a new Copyright section with the given values is added to them.
finalizelibrary: In addition to makelibrary, the written Copyright sections are copied back to the XML source files.

Note: LP_XMLConverter will reject overriding a library part's Copyright section, if the License Type with which to override is "" or "CC0", and the library part is password protected.

-reportLevel

Level of checking report.

0: No report (deafult)
1: Report GDL Errors
2: Report generic GDL warnings

-interpret

Interpret GDL script.

-checkFiles

Checking .GDL files.

-checkPictures

Checking picture files.

Available in case of reportLevel 2:

-checkInit: Checking uninitialized variables.
-checkPrec: Checking precision warnings.
-checkParams: Checking the unused parameters of a libpart. See chapter Listing of unused parameters
-checkBinSections: Checking unused binary 3D and fragments.
-checkThreadSafety2D: Checking the 2D script compatibility with multithread program running.
-checkThreadSafety3D: Checking the 3D script compatibility with multithread program running.

-checkAll

Turn on all warnings with highest level.

-verbose n

Option for setting the verbosity level of printed messages:

0: Quiet mode
1: Print compile information (default)
2: Print all process information

-interface file

Macro library interface definition XML file. When compiling a library without the interface parameter specified, the tool will report all unused macros in separate warnings. In case of a macro library unused macros are the natural intention of the creator and these warnings would shroud other important problems. Consequently, macro libraries should specify their public interface in an XML file (and pass the file to the tool) to omit unused macro warnings for the published macros. The format of the XML file is specified in the XML Schema for Interface Definition file.

-mastergdl file

Location of the master GDL file to be used. If not set, the LP_XMLConv.gdl in the application path will be used.

-skip_params file

In case of checklevel 9 this exception file defines the parameters not to be listed as unused ones, even if they are unused. See chapter Listing of unused parameters.

-password pwd

For every compiled XML encrypt the GSM with the given password. Can be at most 16 characters long. Note: LP_XMLConverter will reject encrypting GSMs for which the source XML does not have a Copyright section, or the License Type is empty or "CC0".

source

Source directory of the compilation.

dest

Destination directory of the compilation.

additionalLib

Locations of zero or more additional binary libraries. These libraries are used in fixing the references between library parts (which is based on library part IDs - see GDL Technical Standards Chapter 2.2 for details).

3.4 Handle LCF files

A library package can be stored in a Library Container File (LCF). LP_XMLConverter can create and extract such an LCF with the following commands.

LP_XMLConverter createcontainer lcfFile [-compress level] libraryFolder [...]

Creates an LCF on the location lcfFile containing the passed libraries.

lcfFile: Location of the LCF file to create.
-compress level: Compression level setting. The level must be in the 0 - 9 range. 0 means no compression, 1 is best speed, 9 is best compression. The default is 0.
libraryFolder: Location of one or more library folders which are to be included in the LCF file.

LP_XMLConverter extractcontainer lcfFile libraryFolder

Extracts the LCF at location lcfFile to the libraryFolder folder.

lcfFile: Location of the LCF file to exract.
libraryFolder: A destination folder, where the contents of the LCF will be extracted.

3.5 Make subset library

The LP_XMLConverter can create a subset library with the following parametrization. A subset library is the one-sided difference set based on an earlier and a new version of the same library.

Let's take AC20Lib and AC21Lib for example. Their subset will contain all library parts from AC20Lib which don't have a compatible equivalent in AC21Lib. These can be:

Elements, which are not supported anymore and got deleted.
Elements, which were changed in an incompatible way and got a new Main ID.

LP_XMLConverter makesubsetlibrary previous current subset

previous: Source location of the previous library in XML. The folder must exist.
current: Source location of the current library in XML. The folder must exist.
subset: Target location of the subset library to be created in XML. The specified folder will be created.

3.6 Passing Unicode parameter values

You can pass non-ASCII parameters to LP_XMLConverter, e.g. folder or file paths, that contain non-ASCII characters. You can pass such arguments directly on the command line, or in a parameter file, as described below.

-f paramFile: Param_file is an UTF-8 encoded file, which contains one LP_XMLConverter argument in each line, e.g. -img and the location of the image folder should be placed in two separate lines. Empty lines are treated as empty string arguments. Any type of newline character (Windows, Mac, UNIX) is accepted. The arguments in the file will be inserted to the command line replacing the -f paramFile. The parameter file and the direct parametrization can be combined. The -f argument can occur multiple times on the command line.

LP_XMLConverter can handle only characters which fall into the Basic Multilingual Plane (U+0000 – U+FFFF) both on the command line, and in the parameter file. The Unicode codespace is divided into 17 planes, and first plane is the Basic Multilingual Plane.

4. Usage tips

4.1 Compilation for two platforms

Note, that XML files are cross-platform, GSM files are not. (But ARCHICAD can use GSM files from both platforms)

The tool compiles the XML files to a GSM-library for the platform, on whitch it was started. We want to avoid the variance of Revision IDs of the same library part on Windows and on Mac. Different Revision IDs slow down the usage of cross-platform project files a bit. Follow these steps to generate correct libraries with fitting ID-s on both platforms:

compile and finalize the library on a platform (finalizelibrary)
copy the - updated - XML files to the other platform
compile the library (convertlibrary if no change is made between platforms or finalizelibrary if successive compilation is guaranteed)

4.2 Handling built-in images

Library parts can contain "built-in" images. LP_XMLConverter eases the access of this feature, too.

The steps of usage are the following:

Create a folder for the image files and place images in it. The images can be of any format known by ARCHICAD.
Refer the images from the XML files using the following syntax:
```
<GDLPict MIME="image/png"
    path="subfoldername/filename.png"
    SubIdent="3"
    platform="Win"
    SectVersion="19"
    SectionFlags="0">
</GDLPict>
```
The path is relative to the main image folder, which is passed to the converter via the -img commandline parameter. SubIdent is the inner identifier of the image. This ID can be used to access the image from the scripts. In case of using -keepimagepath commandline option, these filenames are invariable after the conversion. Otherwise the filenames become subfoldername/GDLPict_X.ext, where X is the inner identifier of the image ('SubIdent').

Use the image in the scripts of the library part containing it. The actual image can be identified by the SubIdent value, as this example shows:

UI_INFIELD "parName", xPos, yPos, width, height,
        1, 3, 5, 1,        ! mind the "3"
        56, 50, 40, 40,
        1, "",
        2, "",
        3, "",
        4, "",
        5, ""

4.3 Hiding script sections

Library Parts provide a way to have the scripts hidden from the end user. This can be done in XML by adding 64 to the SectionFlags attribute of the script to be hidden. This will create a GSM file with the given scripts hidden. Converting a library part with hidden scripts back to XML will create empty script elements, so be sure to keep the original XML files after publishing the library.

4.4 Localization of default values

Some published libraries should work with different default attribute sets - consequently they must come with different default parameters to different users. Since ARCHICAD 11, LP_XMLConverter provides a way to compile differently parametrized libraries from the same source XMLs. The technology is based on the concept of meanings.

Meanings give you the possibility to assign architectural notion to a given parameter. See the following example from the International ARCHICAD Library's Armchair 01.xml where we assert that the value of 4 in the gs_cont_pen parameter is just an instance of the notion of Furnishing_ContPen (which is meaningful architectural thing in contrast to '4').

<PenColor Name="gs_cont_pen">
    <Description><![CDATA["Contour Pen"]]></Description>
    <Fix/>
    <Flags>
        <ParFlg_Child/>
    </Flags>
    <Value Meaning="Furnishing_ContPen">4</Value>
</PenColor>

Having this asserted, you can define the default values for all meanings you specified. This can be done in the replacement definition XML file, which can be passed to LP_XMLConverter with the -def parameter. Here is a snipplet from it which tells the converter tool to substitute all furnishing contour pens with 7 in the current compliation.

<ReplacementDef>
    <ReplacementItem meaning="Furnishing_ContPen" value="7"/>
    ...
</ReplacementDef>

Unfortunately, the GSM library part format cannot hold these extra meaning hints, consequently an extra file beside the binary library must be created in this substituting scenario. This extra file is the current replacement file and it is used when you convert the binary GSM-s back to XML - to restore the original values and meanings.

The current replacement file can be passed to the converter tool using the -cur parameter.

The paths of built-in image files get stored in this file, too, in case you add the -keepimagepath specifier. See chapter Handling built-in images for further info.

4.5 Listing of unused parameters

With checkParams, LP_XMLConverter is used to list the unused parameters of a library part file. In general, a parameter is used, when its value is used for something, or a value is assigned to this parameter.

Not all of the GDL script files are under the scope of unused parameters check. Only non-template library parts, whom subtype is not Property, can be checked for unused parameters. Other files: .gdl files, template libpart files, and Property library parts are out of scope for the unused parameters check.

Not all of the unused parameters should be listed as unused. Rules:

If the value of a parameter is used, or a value is assigned to a parameter, with or without the 'PARAMETERS' command, the parameter is used.
A hidden parameter, which is inherited from a subtype, is not listed as unused.
Macros: if a libpart file contains a macro call with 'PARAMETERS ALL', then only those parameters of the libpart can be assumed to be unused, which parameters are not among the called macros' parameters.
Separators and titles can never be unused.
If a title is from template, and is hidden, then the children parameters of this title are also hidden, and not listed as unused.
If the parameter begins with 'AC_' or 'ROOM_' prefix, it won't be listed as unused.
If the parameter is listed in the Unused Parameters to Skip XML file, it won't be listed as unused.

Format of the Unused Parameters to Skip XML file:

<?xml version="1.0" encoding="UTF-8"?>
<UnusedParsToSkip>
    <Common>
        <Param>GS_LIST</Param>
        <Param>FM_TYPE</Param>
    </Common>
    <LibPart>
        <Name>MEP_m_Connections.gsm</Name>
        <Param>MEP_VERSION</Param>
        <Param>GS_DETLEVEL_3D</Param>
    </LibPart>
    <LibPart>
        <MainGUID>0585F813-1620-476A-A6B4-9EAD75FC9F17</MainGUID>
         <Param>GS_DRNOEDIT</Param>
    </LibPart>
</UnusedParsToSkip>

The 'Common' section affects all library parts under checking.
The 'LibPart' section affects only the library part identified by the 'Name' or by the 'MainGUID'.

How to get rid of unused parameters:

If a parameter is unused, deletion of this is the mostly preferred option. But, with deletion, be very careful:
- Only those parameters can be deleted which are not necessary for ARCHICAD. Other parameters must be written into Unused Parameters to Skip File.
- If the libpart is a built-in macro, then parameter deletion is forbidden! Instead of this, the parameter should be assigned to a dummy variable, after a RETURN or an END command.
- If the libpart is a macro, but is not built-in, then, after deletion, the macro file should get a new Main GUID.
An unused parameter, inherited from the library part's subtype, should be hidden. Or, sometimes, the parameter should be deleted from the subtype itself. NOTE: be careful with deletion as written above!

User Documentationof the LP_XMLConverter tool