The Events File contains information that allows the editor to
locate, in the source member, any tokens or lines that caused a message to
be issued, and to relate messages that refer to expanded source to the corresponding
position in a given source file. The Events File is meant to provide machine-readable
information useful to certain classes of tools. The processor's listing file,
by contrast, is meant to be read by humans. Since the Events File has a common
format across all processors, tools will not have to write processor-specific
code to obtain the information they need.
The Events File is produced
sequentially. Each processor is simply appending new records to it. When an
important event occurs, a record is written to the Events File.
Currently,
the following record types are defined:
- Timestamp Record
- Processor Record
- File ID Record
- File End Record
- Error Information Record
- Expansion Record
- Program Record
- Map Define Record
- Map Start Record
- Map End Record
- Feedback Code Record
Since different types of records will be included in this one
file, the first word in each record will identify the record type. In the
syntax diagrams, each token should be separated by exactly one blank.
Timestamp Record
This record indicates when the
Events File was created, and allows an application to determine if the Events
File is current (if the timestamp is older than a file indicated in a File
ID record, the Events File may be incorrect for that file). This record is
always the first record in the Events File.
Note: This record is not written
by a processor; it is written by the caller of the first processor. This
allows each processor to append to the Events File without having to determine
if the file exists.
The record is defined as follows:
**––– TIMESTAMP ––– version ––– timestamp ––––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- timestamp
- The date and time the Events File was created in yyyymmddhhmmss format.
Processor Record
This record indicates that a new
processor has been invoked. One will always follow the timestamp record in
the Events File (although there may be more than one).
The processor
record is defined as follows:
**––– PROCESSOR ––– version ––– output-id ––– line-class –––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- output-id
- The file ID of an output file produced by this processor. If the output
of this processor is intended to be used as input to another processor, this
file ID represents that file, and the file ID record of the file will follow
this record. If this is the last processor that will be invoked for which
the editor will be expected to display messages, the file ID is 0.
- line-class
- Method used to number lines. Specify zero if a temporary file or internal
file containing an expanded source representation is being used; the line
number represents the line number in the expanded source. Specify one if the
line number represents the physical line number in the source file indicated
in source file ID field.
Note: If the output of one processor is intended as the input
to another processor, the FILEID record for the output should
contain a name, even if the output is not placed in a real file. This same
name should be used in the input FILEID record of the processor
using the output.
File ID Record
This record contains the full name
of the source file processed and associates an integer with the file name.
There should be one record of this type for each source file processed (the
main source file as well as any included source units (copylib members) and
macros).
Note: If a file is included several times during processing, a
file ID record should be written for each inclusion.
The file ID
record is defined as follows:
**––– FILEID ––– version ––– source-id ––– line ––– length ––––*
*––– filename ––– sourcefile timestamp ––– temp flag ––*|
If
the file ID record exceeds the length allowed by the record length of the
events file (which can occur when compiling IFS files) then the file ID record
is followed by one or more file ID continued records of the following format:
**––– FILEIDCONT ––– version ––– source-id ––– line ––– length ––––*
*––– filename ––– sourcefile timestamp ––– temp flag ––*|
For
example:
FILEID 0 001 000000 383 /home/USER/directory/directory2/directory3/directory4asdfjkaskldjfhakjsdf haslkdjf alksjdfh laksjdf/directory5/dir9 askdjfhaksdjfhkalsjdfhlkajsdfhlajdshflkajshdflkajshdflkjahsdflkjhasdlfkjhaslkdfhalksdjfhalksdhfklashdfkashdflkahsdflkjhasdlkfhalskdfjha
FILEIDCONT 0 001 000000 000 lskfhalskdfhalsdhfalksdjfhlaksfhlasasdkjfhaksdjfhlkasjdfhlkajshdflkajshdfkjashdflkjhasdlkfhsadjkfdfhlakdshflkhs/REM1C01501.RPGLE 20030404130518 0
Length should always be used to determine the file name, as IFS
file names may have spaces in them, as shown in the example above.
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- source-id
- A file identifier expressed as an integer to be used in place of the file
name to correlate an error record with the source file in which it occurred,
without having to use the character based file name. Use zero if the input
file is not known, such as input coming from a user exit.
- line
- Source file line number where a new file is referenced, or zero if the
file was not referenced from a file.
- length
- Length of the file name; the maximum length is 255. In a FILEIDCONT record,
the length is always zero since length is only determined by the file ID record.
- filename
- The name should be the fully-qualified physical file name. If none exists
(for example, getting text from the user) or the name can't be determined,
place a null string here.
The name can include servername.
- sourcefile timestamp
- This is the timestamp on the Source file.
- temp flag
- This field is set to 1 to indicate the source is a temporary
file, otherwise it is set to 0. Temporary source file can
only be opened in browse mode. Currently the temp flag is used to reference
output generated by SQL preprocessor.
File End Record
This record indicates that an included
file is ending. It provides a method to determine the nesting of include files
so a program can navigate back up the include chain. This is useful when the
included file does not contain enough information to determine what caused
the error.
The file end record is defined as follows:
**––– FILEEND ––– version ––– file-id ––– expansion –––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- file-id
- The file ID of this file.
- expansion
- Number of expanded source lines in this file, including any nested includes
and macro expansions.
Note: Every file ID record must have a corresponding file end
record, except for the file ID that follows the processor record to define
the output file.
Error Information Record
A record of this type contains
information required to locate a token or line causing a message in the source
file, as well as enough information to allow the message itself to be displayed.
This information includes location information (such as what file and line
the error occurred on) and information related to the error itself (such as
the number, text, and severity of the message).
The error information
record is defined as follows:
**––– ERROR ––– version ––– file-id ––– annot-class –––*
*––– stmt-line ––– start-err-line ––– token-start ––– end-err-line ––– token-end –––*
*––– msg-id ––– sev-char ––– sev-num ––– length ––– msg –––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- file-id
- The file ID number of the source file containing this error.
- annot-class
- Indicates where in a listing of messages this message should be placed
when the Events File is loaded in the Error List window. The positions are
defined as follows:
- 0
- Top of list. Generally used for very important messages that aren't really
associated with a specific line in a file. The sorting order for multiple
instances of messages of this type is not defined. Because no text generally
corresponds to this type of error, it can't be located in the edit window.
- 1
- Middle of list. Generally used for messages which are associated with
a single line or token. Multiple messages of this type are sorted by line
and column number.
- 2
- Bottom of list. Generally used for less important messages that aren't
really associated with a specific line in a file. The sorting order for multiple
instances of messages of this type is not defined. Because no text generally
corresponds to this type of error, it can't be located in the edit window.
- stmt-line
- Line number (in the source file associated with the above source file
ID number) of the first line of the statement containing the error. This
is required in case the error does not occur on the first line of the statement.
This number is interpreted using the line class field.
- start-err-line
- Line number (in the source file associated with the above source file
ID number) containing the start of the error. This number is interpreted using
the line class field.
- token-start
- Column (or character in the line) of the start of the token in error.
If this information is not available, a zero here will cause the entire line
to be flagged as an error.
- end-err-line
- Line number (in the source file associated with the above source file
ID number) containing the end of the error. This number is interpreted using
the line class field.
- token-end
- Column (or character in the line) of the end of the token in error. If
this information is not available, a zero here will cause the entire line
to be flagged as an error.
- msg-id
- Message ID (for example, AMPX999).
- sev-char
- Severity code letter (I, W, E, S,
or T).
- sev-num
- Severity level number. For some systems, this is the return code associated
with the severity code letter (for example, I=0, W=4, E=8, S=12, T=16).
- length
- The actual length of the message text (the next field). The maximum length
is 1024 bytes.
- msg
- The message text of the error message. Any replacement of fields should
have already been done.
Note: Errors that span files may not be properly flagged, because
the error record only allows one file-id to be specified
Expansion Record
This record contains information about expanded source lines due to a pre-processor (such as the SQL pre-compiler or the RPG pre-processor).
This information would be used to create a mapping between the output of a pre-processor and the original source.
The expansion record is defined as follows:
**––– EXPANSION ––– version ––– input-file-id ––– input-line-start –––*
*––– input-line-end ––– output-file-id ––– output-line-start ––– output-line-end –––*|
- version
- The revision of this record, used for upward compatibility. The current version is "1".
- input-file-id
- ID of the file containing the source that will be expanded. The File IDs have to match the IDs found within the same processor block.
- input-line-start
- The line number where the statement to be expanded starts.
- input-line-end
- The line number where the statement to be expanded ends.
- output-file-id
- ID of the file where the expanded source is being written. The File IDs have to match the IDs found within the same processor block.
- output-line-start
- The line number where the expanded source starts.
- output-line-end
- The line number where the expanded source ends.
Note: In the case of a processor that adds source to the output file instead of expanding existing source (case of the SQLCA where the SQL
pre-compiler adds a Data Structure to the existing code), the Input File Start and End Lines should be set to 0 (and any errors with respect to that
section of code would be inserted at the very top of the original source).
Program Record
This record indicates a new program
in the same source file is being compiled. It is used when multiple programs
are contained in one file. Expanded source line is assumed to start over at
1 when this record is written. It is not needed to indicate the first program
in the file.
Note: All ERROR records for a program must
come after the PROGRAM record for that program and before
any PROGRAM records for other programs.
The program
record is defined as follows:
**––– PROGRAM ––– version ––– line –––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- line
- The position in the file that this program starts.
Map Define Record
This record indicates that a macro
is being defined. It is used to allow errors to be reflected back to a macro
definition instead of the place the macro is used.
The map define record
is defined as follows:
**––– MAPDEFINE ––– version ––– macro-id ––– line ––– length ––– macro-name –––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- macro-id
- Integer representing this macro definition. It should be incremented sequentially
within a specific file.
- line
- Physical line in the current file where the macro definition starts.
- length
- Length of the macro name.
- macro-name
- The name of the macro being defined.
Map Start Record
This record indicates that source
expansion is starting. It is used where any textual replacement is being
done.
The map start record is defined as follows:
**––– MAPSTART ––– version ––– macro-id ––– line –––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- macro-id
- Identifier of a macro specified in a map definition record.
- line
- Physical line in the current file where expansion (for example, macro
invocation) begins.
Map End Record
This record indicates that source
expansion is complete. It is used at the end of a textual replacement to
show how many lines were created.
The map start record is defined as
follows:
**––– MAPEND ––– version ––– macro-id ––– line ––– expansion –––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- macro-id
- Identifier of a macro specified in a map definition record.
- line
- Physical line in the current file where expansion (for example, macro
invocation) begins.
- expansion
- Number of lines resulting from this macro expansion, including any nested
expansions.
Feedback Code Record
This record contains the return
code and reason code at the point where compilation stopped.
The feedback
code record is defined as follows:
**––– FEEDBACK ––– version ––– return-code ––– reason-code –––*|
- version
- The revision of this record, used for upward compatibility. The current
version is "1".
- return-code
- Return code returned by the processor.
- reason-code
- Reason code returned by the processor.