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

From The SBN Wiki
Jump to navigation Jump to search
(→‎Command Switches to Use: Update for 0.2.0.3)
(Update Safety Save)
Line 40: Line 40:
 
| 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, --Mission
+
| style="width: 15%" align="center"| -M
 
| style="width: 10% |'''Optional'''  
 
| style="width: 10% |'''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% |'''Optional'''
 +
| 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% |'''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.
 
|}
 
|}
  
Line 58: Line 65:
 
|-
 
|-
 
| style="width: 10%" align="center"| --Class
 
| style="width: 10%" align="center"| --Class
| This switch is supposed to be an alias for the '''-c''' switch.  It isn't - it's ignored.
+
| 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 .
 
|-
 
|-
 
| style="width: 10%" align="center"| --LDD
 
| style="width: 10%" align="center"| --LDD
Line 65: Line 72:
 
| style="width: 10%" align="center"| --PDS4
 
| style="width: 10%" align="center"| --PDS4
 
| This is supposed to be an alternate way of including the required '''-p''' switch.  It's not, and using it throws an error.
 
| This is supposed to be an alternate way of including the required '''-p''' switch.  It's not, and using it throws an error.
 +
|-
 +
| style="width: 10%" align="center"| --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.
 +
|-
 +
| 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.
 +
|-
 +
| style="width: 10%" align="center"| --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.
 
|}
 
|}
  

Revision as of 17:43, 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.
-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.

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.
--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.