Running LDDTool and Verifying the Output

These pages are being actively updated to the latest (version 7.0.1/0.2.1.0) of LDDTool. A note will be posted when the update is complete.

Running LDDTool

The minimal "Operation" documentation provided with the LDDTool package is apparently unmaintained, is at odds with actual tool behaviour in more than a few cases, and is flat-out wrong in at least one key point. The information output as help text for lddtool is not much better. The information below was compiled by running lddtool with various options and looking at the results produced using LDDTool version 7.0.1 of the release package (version 0.2.1.0 of the tool itself), with the "IngestLDD_Example_Classes.xml" file provided in the SBN example package.

Single-letter switches may be combined and order is not significant, so "-l -p -c" is equivalent to "-clp".

Note that the few errors in command invocation that are actually trapped will send error messages to the command line, but these will always be followed by a dump of usage information, so most people will have to be able to scroll back through screen output to see the actual error message.

Also, note that LDDTool will silently ignore invalid switches, so type carefully.

Command Switches to Use

This switches seems to operate as described below. Some have both a short form and a long form.

-l	Required	This switch must always be specified if you want to actually process the input file. Failing to include results in an output list of errors complaining about things that can't be found and nothing else.
-p	Required	This switch must always be specified if you want to actually process the input file. Omitting results in a a brief error message identifying the missing option followed by a listing of the help text.
-c	Optional	This switch directs LDDTool to create XML <element> definitions for every DD_Class declaration in the Ingest_LDD input, ignoring any <element_flag> attributes you might have included in your DD_Class definitions. This is probably not a good idea. Don't do this unless you really mean it.
-h, --help	Optional	This displays the command summary information. In this case all other switches and arguments are ignored. The long form of the switch is safe to use in this case because the -h option overrides and cancels all other options.
-J	Optional	This switch causes the creation of an additional output file that contains the dictionary information in JSON (Java Script Open Notation) format. It is a dump of the entire Information Model as known to LDDTool after processing your input file - so it includes the entire pds: core namespace, the known discipline name spaces, and the dictionary just created.
-m	Optional	This switch causes LDDTool to create an additional output file with the same name as the output schema files and an extension of ".pont". This file is used to load the ontological data base at Engineering Node that holds all configured PDS4 data dictionaries. You should never have to generate this file in normal operations, but if you can find a use for it, have at it.
-M	Optional	This switch adds a /mission/ level to the namespace identifier defined for you dictionary. If you are working on a mission dictionary, you should use this switch to avoid having to edit the namespace in the output schema files.
-n	Optional	This switch adds "nuance property maps" to the output schema and, if any, JSON files. This is an experimental implementation still working towards proof-of-concept stage, so you should avoid it unless you are directly involved in the testing and development of this capability.
-s	Optional	This switch causes the the version number of the local dictionary to be set equal to the version number of the core namespace used to process the input file, and it also causes the output files to have names of the form PDS4_ns_vvvv, where ns is the namespace abbreviation specified inside the input file, and vvvv is the collapsed, four-digit reference to the PDS core version. Apart from the version number, the output schemas are otherwise unaffected.
-v, --version	Optional	This switch causes lddtool to output its internal version number, which is different from the version number on the delivery package. As of this writing, the latest available download package has a version number of "7.0.1", but the -v option will report a version number of "0.2.1.0". The long options is also safe to use in this case - the -v option overrides all other options except the -h option.
-1	Optional	This switch (it's a number one) causes the output of of the PDS4 Information Model in the same format as the HTML web page on the main PDS site. It includes attribute definitions from the local dictionary processed in Section 26, but not class definitions - even if you include the -c option to create visible class elements, or set the element_flag in your class to true. Neither do the associated links work. On the whole, there's not much point, but the switch does not appear to have any side-effects on the output schemas themselves, so in that sense it is harmless.

Command Switches to Ignore or be Wary of

Don't use these. If you read the help text output by lddtool, you will see these switches listed, but they do not have the advertised effect(s), and frequently have unintended side effects because of a program error in handling long-form options.

-a	This switch has no effect.
--attribute	This switch has no effect. It is defined as a synonym for the -a switch, which has no effect, and it also, coincidentally, has no letters in it that would otherwise be recognized as switches.
--class	This switch is supposed to be an alias for the -c switch. While it does cause element definitions to be written for classes, it also changes the name of the output files as though the -s switch was included as well.
-d	This undocumented switch causes lddtool to insert <xs:annotation> elements into the output XML Schema for every attribute included in each class. These elements contain the human-readable definitions you included in the input file as you defined each attribute. Normally, the output XSD schema file only contains these annotations for the classes. Using this switch causes them to be added for attributes as well. It does not, however, do this in a way that is consistently syntactically valid - so a non-trivial input file is likely to produce an .xsd output file that is riddled with content errors.
-IM Spec	Assuming you are clever enough to figure out how to pass an option with an imbedded blank, this is advertised as a long form of the -1 option. It's not. It does not trigger creation of the HTML file, but it does have the same effect as specifying the -M and -c options.
--JASON	This was supposed to be an alternate way of including the -J switch. It actually does also trigger the creation of the JSON output file, but this is not how you spell "JSON", and one must assume that it is only the happy circumstance that none of its letters correspond to currently existing other switches that prevents this string from having unexpected side effects similar to those listed for other long versions.
--LDD	This is supposed to be an alternate way of including the required -l switch. It's not, and using it throws an error.
--merge	As of this writing, this option has the desired effect of being equivalent to the -m option with no additional side-effects. Given the issues with other long options, though, this must be assumed to be a happy coincidence, and it would be better in the long run to avoid all long options, even the ones that seem to work, until the underlying problem is solved.
--Mission	This was supposed to be an alternate way of including the -M switch. It does produce the desired change in namespace, but also produces the addition effects of the -s and -n switches.
--nuance	This was supposed to be an alternate way of including the -n switch, which you also probably shouldn't use, but in addition to adding the property maps to the output, it also causes the same behaviour as the -c switch, and defines elements for all your classes.
--PDS4	This is supposed to be an alternate way of including the required -p switch. It's not, and using it throws an error.
--sync	This was supposed to be an alternate way of including the -s switch. In fact, it has the total effect of the -s, -n, and -c switches combined.