§3 Usage Scenario
This scenario is supposed to deliver you an insight of the most frequently used ODX Checker functions and make you familiar with these. You will be guided step-by-step through an exemplary situation which you are encouraged to reproduce.
Before you start you should make a few preparations: First you need two ODX documents, if you don't have any own documents you can use the sample documents located in the help/samples sub-directory of the ODX Checker. Open one of these documents in an XML editor of your choice and add a question mark to the contents of some SHORT-NAME tag. SHORT-NAMEs are not allowed to have any other characters than letters, ciphers [a-z|A-Z|0-9] and underscores [_]. Thus you just hacked an error into your document. Do the same with the other document and save them both. Then start the ODX Checker (leaving the XML editor open for later). We're now ready to start...
After startup the Checkers Application Window is all empty, but before we change this we should check our preferences: Choose Preferences from the Settings menu and enter the correct rule directory in the arising window. Then click OK to confirm your changes. If you specified an invalid directory this will yield a message in the Log Window. If so please go back to the preferences and enter a valid directory. Now click on the Rule Set Tab. You'll see a list of all rules that were found in the specified directory (if any). Each of them has a checkbox which is checked by default, telling that the corresponding rule is activated, i.e. it will be checked during the next checking process. Look for a rule named ASAM_003 and make sure that it is activated. Now we're ready to make our first check:
Click on the speed button 'Open ODX' in the Icon Bar to pop up a file chooser dialog. Browse to the folder where the prepared files are located and open the one we changed. After a short period the file will appear in the File Window. If you get a message (in the Log Window) that errors occurred during parsing, then you should check that the document is well-formed and conforms to the current ODX XML Schema. Maybe you accidentally deleted an angle bracket or a slash... When you fixed these errors you may try to load the document again. Now double click the file and (if it's big) wait for the checking process to be completed. The end of a check can be easily recognized by a message in the Log Window, saying that the document was checked successfully. If the Rule Set Tab is still opened, the Checker will automatically switch back to the Messages Tab after the check. You should now see at least one error in the Messages Tab. Double click on it. A small window will pop up showing you detailed information about this error: The code A003-1 identifies the detected error - A003 means that this error was yielded by the rule ASAM_003 and the number 1 identifies this error among possibly multiple sub-errors in this rule. The selected radio button 'error' tells you that this error is serious and not just a warning. Nevertheless it is not runtime relevant as you can see from the unchecked checkbox to the right. Beneath the 'message type' group you will see a message which tells you about this rule violation in plaintext. At the dialogs bottom an XPath query is shown which unambiguously locates the erroneous tag in the ODX document. Mark this query completly and press Ctrl-C to copy it to the clipboard. Now go back to your XML editor and hand it the XPath query to locate the error. Fix it (i.e. remove the previously added question mark) and go back to the Checker. Close the message details and once again press the 'Open ODX' button. Again you choose the document you just fixed and reload it into the checker. If you didn't change the name of the document it should stay activated in the File Window. Now click the 'Check Rules' button from the Icon Bar to recheck it and notice that no errors were reported. You just fixed a bug.
Now suppose that you have a second ODX document which makes references to the one you just checked. In this case it is not necessary to load both files via 'Open ODX' (which also reloads the currently loaded document and might take some time if documents are big). To add the new file to the ODX Checkers current data storage simply click on 'Add ODX' and choose it from the dialog. The new file is then added to the File Window without reloading the old one. By double-clicking the new document you perform a check on it and get a similar result as when you checked the first one before it was fixed. We now want to save the result of this documents check to an HTML document. To do this choose Report CheckResult from the Run menu. A file chooser dialog will pop up where you specify a name and a location for the report to be saved. The results will then be written to an HTML file containing information about which file has been checked, the date of the check and of course details about every single rule violation that was found.
Hopefully this scenario was easily understandable and could successfully make you familiar with the introduced functions.