Wednesday, July 05, 2006

The ExternalApp Entry and Splitting lines in [Additional Properties]

The entries in the Additional Properties section of the .GTM file (or the addprop.ini file) have a limit of 255 characters. This may seem like a large limit (this is what we thought anyway), but there is indeed a common entry that can easily exceed this limit. The ExternalApp entry used by Pocket GTViewer to define external applications has the potential to be lengthy. Also, GT/Field for Pocket GTViewer is treated as an External Application to Pocket GTViewer and uses the ExternalApp entry as part of its integration. GT/Field has pretty quickly brought to light that 255 characters are not nearly enough for the ExternalApp entry.

First, let’s look at what the ExternalApp entry contains and see why it can grow beyond the 255 character limit.

App Name is the name that appears in the Applications list dialog in Pocket GTViewer.

Mode is the mode number specifying how to launch the external app (immediately, when a feature is selected, when a point is selected, with a GPS point, etc.).

External App Path is the path on the device to the external application.

Parameters specify any parameters for the external app. This parameter can be used to specify an eMbedded VB file when vbload.exe is used as the external app.

Filter specifies a list of comma delimited : pairs that can be selected when the Feature selection mode is used. For all other modes, this value should be set to . More on the different filter ranges in the a future posting.

Msg is the Prompt message you see in Pocket GTViewer when a feature, point, line, gps point, etc. is being captured. Once the capture is made, the external app is launched. The Msg value only applies to certain modes. For example, Launch Immediately does not use a prompt. If there is no prompt, the value should be set to .

The App Name is generally not very long and the mode is at most 2 characters. The Path to the external app can be several characters depending on the depth of the path; however, the %mainapppath% and %programpath% tokens can reduce the size some (as well as make the location generic). Parameters is rarely used with the growing popularity of .NET development (and the shrinking popularity of eMbedded VB). That leaves filter and msg.

If your external app deals with broad filters where you can include all filters in a category (like 2:*, 3:*, 999:*), then your filter string does not get very long. However, if you have many categories with many features and your external application needs to filter out specific components of a lengthy list of features, the filter string can easily grow to a size greater than 255 characters. GT/Field is a good example of an External App that can have a very lengthy filter if you use it to edit a large number of existing features (and can’t simply say all filters in a category).

Msg will never be too many characters because if it is too big, it won’t fit on the device’s screen. However, if you user 25 characters for your prompt, that is just fewer characters you can use for a filter.

With version 5.0.x.15+ of Pocket GTViewer, the problem of long ExternalApp entry is solved with a new entry for the Additional Properties section:

Any line in the [Additional Properties] section (as well as the addprop.ini) can now be split. Simply split the line and make a new entry called . The must be following by a pipe () which is not part of the split line.

An entry can be split as many times as you need as long as you do not have blank lines between the main entry and the continuation entries.

No comments: