32-Bit Error Log Entry Formatting DLL Routines

Each Error Log record within an Error Log file can contain the name of a formatting DLL module. A formatting DLL module ise invoked by the SYSLOG utility when SYSLOG encounters an Error Log record that contains the name of the DLL module.

Each formatting module contains a single formatting routine that can be identified by an ordinal value of 1. The formatting routine can be designed to handle a single type of Error Log entry or to handle multiple types of Error Log entries. When SYSLOG passes control to a formatting routine, it passes the entire Error Log record (both header portion and data portion) to the formatting routine. The formatting routine has the complete flexibility to format an Error Log entry as it deems appropriate.

SYSLOG uses the DosLoadModule API to create a run-time link to the specified formatting DLL module. It also uses the DosFreeModule API to free the DLL module after it receives its response from the formatting routine.

There are no specific rules that govern the naming of a formatting DLL module. However, since it is desirable to reduce the possibility of "colliding" with another DLL module of the same name, it is suggested that a formatting DLL module be labeled with a name that adheres to the following standard form: 

        ELGxxxxx.DLL    (where "xxxxx" corresponds to the Error
                           Log record I.D. (in ecimal) of any one
                           of the types of records that the formatting
                           routine is designed to handle)


        e.g. "ELG00127.DLL" is a standardized name for a formatting
                DDL module that recognizes (among other things) Error
                Log records with I.D. of 127 (decimal)

This standard naming convention is suggested because it is assumed that the Error Log records of any one I.D. will only be recognized by a single formatting routine. Therefore the use of the "xxxxx" suffix (based on record I.D.) should assure uniqueness for the formatting module name.

The static Error Log record I.D. registration mechanism that is enforced by the OS/2 RAS development group will attempt to keep a list not only of the Error Log record I.D.'s in use, but also the names of the formatting DLL modules that correspond to each record I.D.. This may also help to reduce the possibility of formatting DLL module names "colliding".

In addition to its single formatting routine, each formatting DLL module must contain a global variable named "ELOG_FORMAT". This exported global variable must be set to a value of 1. When SYSLOG loads a prospective formatting DLL module it will attempt to access this global variable and check whether it has the expected value of 1. If the global variable check fails, then SYSLOG can conclude that it has accidentally loaded another DLL module with the same name as the formatting module that is mentioned in the Error Log entry. This check is intended as a form of protective validation for SYSLOG. The variable may in future releases be used a sort of revision level for the SYSLOG/formatting DLL module interface specification. That is why it will initially be forced to a value of 1.

When a user constructs a Error Log entry formatting DLL module, care should be taken not to export the names of its constituent formatting routine (though the required ELOG_FORMAT global variable must be exported). Not exporting the module name will save storage space within the OS/2 kernel.

Error Log record formatting DLL routines must be written as 32-bit procedures. A typical Error Log record formatting DLL routine will have to accept the parameters: 

        APIRET APIENTRY ELGxxxxx(PVOID Log_Record,
                                 PVOID String_Buffer,
                                 ULONG Buffer_Length,
                                 PULONG String_Length);

Parameters