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 is 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 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 labelled 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)


        for example, "ELG00127.DLL" is a standardized name for a formatting DDL
                     module that recognizes (among other things)
                     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 development organization 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 will 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". For OS/2 2.0, this exported global variable must be set to a value of 1. When SYSLOG loads a prospective formatting DLL module it attempts 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 will in future releases be used as a revision level for the SYSLOG/formatting DLL module interface specification.

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. The SYSLOG utility will be written to use the "ordinal" version of the DosGetProcAddr API.

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: 


        ULONG ELGxxxxx((PVOID) Log_Record, (PVOID) String_Buffer,
                       (ULONG) Buffer_Length, (PULONG) String_Length)

Parameters