Difference between revisions of "Running LDDTool and Verifying the Output"

From The SBN Wiki
Jump to navigation Jump to search
(Update Safety Save)
(Update Safety Save)
Line 17: Line 17:
  
 
{| class="wikitable"
 
{| class="wikitable"
| style="width: 15%" align="center"| -l
+
| style="width: 10%" align="center"| -l
| style="width: 10% |'''Required'''  
+
| style="width: 15% |'''Required'''  
 
| This switch must ''always'' be specified if you want to actually process the input file. Omitting it produces an error unless the '''-h''' switch is present.
 
| This switch must ''always'' be specified if you want to actually process the input file. Omitting it produces an error unless the '''-h''' switch is present.
 
|-
 
|-
| style="width: 15%" align="center"| -p
+
| style="width: 10%" align="center"| -p
| style="width: 10% |'''Required'''  
+
| style="width: 15% |'''Required'''  
  
 
| This switch must ''always'' be specified if you want to actually process the input file. Omitting it produces an error unless the '''-h''' switch is present.
 
| This switch must ''always'' be specified if you want to actually process the input file. Omitting it produces an error unless the '''-h''' switch is present.
Line 28: Line 28:
 
| colspan="3" |    
 
| colspan="3" |    
 
|-
 
|-
| style="width: 15%" align="center"| -c
+
| style="width: 10%" align="center"| -c
| style="width: 10% |'''Optional'''  
+
| style="width: 15% |'''Optional'''  
 
| This switch directs ''LDDTool'' to create XML <code>&lt;element&gt;</code> definitions for every ''DD_Class'' declaration in the ''Ingest_LDD'' input, ignoring any <code>&lt;element_flag&gt;</code> attributes you might have included in your ''DD_Class'' definitions.
 
| This switch directs ''LDDTool'' to create XML <code>&lt;element&gt;</code> definitions for every ''DD_Class'' declaration in the ''Ingest_LDD'' input, ignoring any <code>&lt;element_flag&gt;</code> attributes you might have included in your ''DD_Class'' definitions.
 
|-
 
|-
| style="width: 15%" align="center"| -h, --help
+
| style="width: 10%" align="center"| -h, --help
| style="width: 10% |'''Optional'''  
+
| style="width: 15% |'''Optional'''  
 
| This displays the command summary information.  In this case all other switches and arguments are ignored.
 
| This displays the command summary information.  In this case all other switches and arguments are ignored.
 
|-
 
|-
| style="width: 15%" align="center"| -m, --merge
+
| style="width: 10%" align="center"| -m, --merge
| style="width: 10% |'''Optional'''  
+
| style="width: 15% |'''Optional'''  
 
| This switch causes ''LDDTool'' to create an additional output file with the same name as the output schema files and an extension of "<code>.pont</code>". 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.
 
| This switch causes ''LDDTool'' to create an additional output file with the same name as the output schema files and an extension of "<code>.pont</code>". 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.
 
|-
 
|-
| style="width: 15%" align="center"| -M
+
| style="width: 10%" align="center"| -M
| style="width: 10% |'''Optional'''  
+
| style="width: 15% |'''Optional'''  
 
| This switch adds a <code>/mission/</code> 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 output schema files namespace.''
 
| This switch adds a <code>/mission/</code> 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 output schema files namespace.''
 
|-
 
|-
| style="width: 15%" align="center"| -J
+
| style="width: 10%" align="center"| -J
| style="width: 10% |'''Optional'''  
+
| style="width: 15% |'''Optional'''  
 
| This switch causes the creation of an additional output file that contains the dictionary information in JSON (Java Script Open Notation) format.
 
| This switch causes the creation of an additional output file that contains the dictionary information in JSON (Java Script Open Notation) format.
 
|-
 
|-
| style="width: 15%" align="center"| -n
+
| style="width: 10%" align="center"| -s
| style="width: 10% |'''Optional'''  
+
| style="width: 15% |'''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.
 +
|-
 +
| style="width: 10%" align="center"| -n
 +
| style="width: 15% |'''Optional'''  
 
| This switch adds "nuance property maps" to the output schema and, if any, JSON files.  This is an experimental capability 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.
 
| This switch adds "nuance property maps" to the output schema and, if any, JSON files.  This is an experimental capability 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.
 +
|-
 +
| style="width: 10%" align="center"| -1
 +
| style="width: 15% |'''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, 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''.
 
|}
 
|}
  
Line 78: Line 86:
 
| style="width: 10%" align="center"| --JASON
 
| style="width: 10%" align="center"| --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 switched that prevents this string from having unexpected side effects similar to those listed for other long versions.
 
| 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 switched that prevents this string from having unexpected side effects similar to those listed for other long versions.
 +
|-
 +
| style="width: 10%" align="center"| --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.
 
|-
 
|-
 
| style="width: 10%" align="center"| --nuance
 
| style="width: 10%" align="center"| --nuance
Line 89: Line 100:
 
{| class="wikitable"
 
{| class="wikitable"
 
| style="width: 10%" align="center"| -d
 
| style="width: 10%" align="center"| -d
 
 
 
| This switch appears to cause ''LDDTool'' to include <code>&lt;annotation&gt;</code> elements in 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 definitions for the classes.  Using this switch causes them to be added for attributes as well.
 
| This switch appears to cause ''LDDTool'' to include <code>&lt;annotation&gt;</code> elements in 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 definitions for the classes.  Using this switch causes them to be added for attributes as well.
 
|-
 
|-
 
 
 
 
 
| style="width: 10%" align="center"| -v
 
| style="width: 10%" align="center"| -v
 
| This switch causes ''LDDTool'' to output its version number.  To get the version number output, '''-v''' must be the only switch used.  Specifically, using '''-h''' at the same time will suppress the output  of the version number.
 
| This switch causes ''LDDTool'' to output its version number.  To get the version number output, '''-v''' must be the only switch used.  Specifically, using '''-h''' at the same time will suppress the output  of the version number.
 
|}
 
|}

Revision as of 18:20, 29 April 2016

Bearing in mind the beta-test status of this software, there are some significant caveats and provisos involved in actually using it in a production environment.

Running LDDTool

The "operations" documentation provided with the LDDTool package is unmaintained and is at odds with actual tool behaviour in more than a few cases. The information below was compiled by running lddtool with various options and looking at the results produced using LDDTool version 0.1.8.9f, with the "IngestLDDTool.xml" file that came in the distribution package.


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

Note that errors in command invocation 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. Omitting it produces an error unless the -h switch is present.
-p Required This switch must always be specified if you want to actually process the input file. Omitting it produces an error unless the -h switch is present.
 
-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.
-h, --help Optional This displays the command summary information. In this case all other switches and arguments are ignored.
-m, --merge 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 output schema files namespace.
-J Optional This switch causes the creation of an additional output file that contains the dictionary information in JSON (Java Script Open Notation) format.
-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.
-n Optional This switch adds "nuance property maps" to the output schema and, if any, JSON files. This is an experimental capability 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.
-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, 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.

Command Switches to Ignore

Don't use these.

-a This switch has no effect.
--Attribute This switch has no effect. It is defined as a synonym for the -a switch.
--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 .
--LDD This is supposed to be an alternate way of including the required -l switch. It's not, and using it throws an error.
--PDS4 This is supposed to be an alternate way of including the required -p switch. It's not, and using it throws an error.
--Mission This was supposed to be an alternate way of including the -M switch. It does not product the desired change in namespace, but neither does it throw an error to warn you something is wrong.
--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 switched that prevents this string from having unexpected side effects similar to those listed for other long versions.
--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.
--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.

Undocumented Switches

These switches were discovered by accident during testing. Their behaviour is inferred from output. Use at your own peril...

-d This switch appears to cause LDDTool to include <annotation> elements in 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 definitions for the classes. Using this switch causes them to be added for attributes as well.
-v This switch causes LDDTool to output its version number. To get the version number output, -v must be the only switch used. Specifically, using -h at the same time will suppress the output of the version number.