"The Official Guide to Programming with OmniMark"
| HOME | COMPANY | SOFTWARE | DOCUMENTATION | EDUCATION & TRAINING | SALES & SERVICE | |
|
"The Official Guide to Programming with OmniMark" |
|
| International Edition | |
Previous chapter is Chapter 14, "SGML Objects".
Next chapter is Chapter 16, "Processing External Entities".
OmniMark reports three kinds of errors:
These errors arise from a program that does not conform to OmniMark syntax. These errors are detected before OmniMark attempts to run the program. If any such errors are present, the program is not run.
Some programs do conform to OmniMark syntax, but employ questionable practises that may be indicative of a coding error. Those situations are reported by warnings. If there are no syntax errors but there are syntax warnings, the OmniMark program will still be run.
Warnings are only reported if the -warning command-line switch is specified when OmniMark is run.
These errors arise from attempting to perform an operation that is not permitted. They cause the immediate termination of the OmniMark program.
These are errors indicating that the input document does not conform to SGML syntax. When these errors occur in the document instance, OmniMark reports the error, performs the appropriate error recovery, and continues processing.
There can also be SGML warnings. Like OmniMark syntax warnings, they are only reported if the command-line option -warning is specified.
OmniMark provides additional features to allow the OmniMark programmer to provide customized SGML error reporting. This chapter describes the features that are available to aid the programmer in this task.
SGML-ERROR condition?
LOG?
local-declaration*
action*
The SGML-ERROR rule is triggered when an SGML parsing error is found by the SGML parser. The OmniMark program can do a number of things in an SGML-ERROR rule.
If the LOG keyword is specified at the beginning of the rule body, then the conventional error reporting is done in addition to the actions that follow.
If there is more than one SGML-ERROR rule in an OmniMark program, the first SGML-ERROR rule which has no condition, or which has a condition that is TRUE is performed.
If there are no SGML-ERROR rules which can be performed, the conventional error reporting is done.
When the document instance has SGML errors, the programmer can still obtain control in the EPILOG-START rule to determine how to complete the processing. This allows the program to clean up properly while still reporting as many errors as possible before terminating the parsing of the current document.
The parts of the error message produced by the SGML parser are available in the SGML-ERROR rule in the following built-in local variables:
Each SGML error and SGML warning is assigned its own unique error code number. These numbers are fixed for all future releases of OmniMark, although new ones may be added in the future. #ERROR-CODE provides this numeric-code.
The OmniMark error messages and their error codes are listed in Using OmniMark 3 [eum13], the companion manual on running OmniMark.
These error code numbers provide a reliable way of identifying an error or warning, since the text in the message can change as user feedback results in improved error messages.
#CLASS gives a number indicating the class of the error. It is:
#MESSAGE gives the text of the fixed part of the message for this kind of error.
#ADDITIONAL-INFO gives the text of the part of the message that gives information about this particular instance of the error.
#ADDITIONAL-INFO is not always attached. The "IS ATTACHED" test can be used to make sure that it is only used when it is present.
#RECOVERY-INFO gives the text of the part of the message that gives information about how the SGML parser will recover from this error in order to continue processing.
#RECOVERY-INFO is not always attached. The "IS ATTACHED" test can be used to make sure that it is only used when it is present.
#FILE-NAME gives the name of the file in which the error was found. This will either be the name of the main input file, or the name of the file from which an external entity's text is being read.
#LINE-NUMBER gives the number of the line in the SGML file on which the error occurred. This number is the line number as seen by the SGML parser. If up-translation or context-translation is being done, the line number is based on the lines output from FIND, FIND-START and FIND-END rules to the SGML parser.
For example, the following SGML-ERROR rule instructs OmniMark to report an error in the usual fashion and also outputs the fixed and variable parts of the error message, together with the number of the line on which it occurred in a form that can be accessed by other software. If the variable part of the message is not available, it is not written out.
SGML-ERROR
LOG
OUTPUT "\message{%g(#MESSAGE) on line %d(#LINE-NUMBER)"
OUTPUT "%n%g(#ADDITIONAL-INFO)"
WHEN #ADDITIONAL-INFO IS ATTACHED
OUTPUT "}"
Warning (#CLASS = 0) reports are always passed to SGML-ERROR rules, even if the -warnings command-line option has not been used. The OmniMark program can ignore warnings if it wishes by, for example, using the following condition:
SGML-ERROR UNLESS #CLASS = 0
Specifying LOG in an SGML-ERROR rule has no effect on warning reports unless the command-line option -warning is given. However, the actions in the selected SGML-ERROR rule will still be performed.
Many of the built-in local variables in the SGML-ERROR rule are also provided as pattern variables, for compatibility with past releases. Use of these pattern variables is seriously deprecated.
Unlike programmer-defined pattern variables, these pattern variables must always be heralded with the PATTERN keyword in contexts where heralding would normally be optional.
The pattern variables are CLASS, MESSAGE, ADDITIONAL-INFO, RECOVERY-INFO, FILE-NAME, and LINE-NUMBER.
The "IS SPECIFIED" test will always be true for these built-in pattern variables except for ADDITIONAL-INFO and RECOVERY-INFO, which are not present in all messages.
OmniMark also provides built-in counters to report the number of SGML errors and warnings encountered. Although it is simple for a programmer to provide an SGML-ERROR rule that does exactly this, it is likely going to be commonly-required information, and it makes sense for OmniMark to provide it in a consistent way.
The counters which perform error-counting are:
The counters #SGML-ERROR-COUNT and #SGML-WARNING-COUNT are "saved" and reset to zero by a "DO SGML-PARSE" action and the previous values are restored by exiting from the "DO SGML-PARSE" action. Note that these counter values for the (sub-)document are not available immediately following the "DO SGML-PARSE" action: if they are to be communicated to the processing of an enclosing document, they have to be captured by the "DO SGML-PARSE" action.
#SGML-ERROR-COUNT, #SGML-WARNING-COUNT, #SGML-ERROR-TOTAL and #SGML-WARNING-TOTAL are "read-only": the OmniMark programmer cannot set or otherwise change their values.
The values of the built-in counters #SGML-WARNING-COUNT and #SGML-WARNING-TOTAL are always incremented for warnings issued by the SGML parser, whether or not those warnings are reported by OmniMark. This is consistent with the fact that warnings are always "seen" by the SGML-ERROR rule, whether or not -warnings is specified on the command line.
OmniMark automatically performs error recovery after SGML errors in the document instance. However, SGML errors in the document prolog cause OmniMark to abandon the parsing of that document. This means that if the error occurs in the document prolog of:
The PROLOG-IN-ERROR rule is provided to allow the programmer to gain control before parsing of the current document is terminated.
PROLOG-IN-ERROR condition?
local-declaration*
action*
The PROLOG-IN-ERROR rule is performed either at the end of the SGML Declaration or at the end of the document prolog, if any SGML errors have been encountered to that point. This is essentially immediately prior to the point at which OmniMark normally gives up the current parse.
Each PROLOG-IN-ERROR rule that is in an active group (or in no group -- in the #IMPLIED group), and either has no condition or has a condition that succeeds is performed. (There can be more than one.)
The PROLOG-IN-ERROR rule gives the programmer the following choices:
Like other output processor rules, the PROLOG-IN-ERROR rule can have a condition that determines whether it is performed, and only a PROLOG-IN-ERROR rule in an active group will be selected for being performed. Subject to any condition and the currently active groups, any selectable PROLOG-IN-ERROR rule is performed, and they are performed in the order in which they appear in the OmniMark program.
Considerable confusion and difficulty has resulted from the Amendment 1 to the SGML standard change of the minimum literal at the start of the SGML Declaration (i.e. "ISO 8879-1986" changed to "ISO 8879:1986"). Some SGML supporting products require one, some the other, and others allow either.
To alleviate the trouble caused by strict adherence to the standard, OmniMark allows both forms of this minimum literal, but reports a warning (rather than an error) when it encounters the "ISO 8879-1986" form. When warnings are suppressed in an OmniMark run, no indication of this error will be given.
It should be kept in mind that anything other than "ISO 8879:1986" is, strictly speaking, an error, even though, for convenience, the older form is only reported as a warning.
Next chapter is Chapter 16, "Processing External Entities".
Copyright © OmniMark Technologies Corporation, 1988-1997. All rights reserved.
EUM27, release 2, 1997/04/11.
|
|
|
|
|