LogAddEntries

LogAddEntries is a 32-bit system Error Logging facility high level API. It is used to allow application processes to add Error Log entries to the internal Error Log buffer that is maintained by the System Logging Service device driver.

The description of the LogAddEntries API call follows:

Syntax

        APIRET APIENTRY LogAddEntries(HFILE hf, ULONG service,
                                      PVOID log_data_address);

Parameters

hf

is the file handle returned by LogOpen()
service
specifies the class of logging facility:

0x0

Reserved
0x1
Error Loggging
0x2 - 0xffff
Reserved
log_data_address
is the address of a buffer that contains a variable length Error Log entry. The first word of the buffer contains the number of packets in the Error Log entry

Returns

Return code.

LogAddEntries return the following values:

• Success

  non-zero

  Failure

  Possible reasons for failure are:

  Invalid log type
  Facility unavailable
  Facility suspended
  Facility not open
  Error Log buffer temporarily full

  Remarks

  Error Log Entry Buffer format description:

  Multiple Error Log packets can be included within a single Error Log entry buffer. If multiple packets are included within a single buffer, each individual packet should be aligned on a double word boundary. In the following diagram, the size of each field is indicated in bytes:

         ┌──────────────────────────────────────────────┐
         │packet revision number                       2│
         ├──────────────────────────────────────────────┤
         │# of Error Log entry packets                 2│
         ├──────────────────────────────────────────────┤
         │length of this Error Log entry packet        2│<──┐
         ├──────────────────────────────────────────────┤   │
         │Error Log record I.D.                        2│   │
         ├──────────────────────────────────────────────┤   │
         │status flags                                 4│   │
         ├──────────────────────────────────────────────┤   │
         │qualifier name                               4│   │  multiple
         ├──────────────────────────────────────────────┤   │  Error
         │reserved                                     4│   │  Log entry
         ├──────────────────────────────────────────────┤   │  packets
         │time of logging                              4│   │  within a
         ├──────────────────────────────────────────────┤   │  single
         │date of logging                              4│   │  Error Log
         ├──────────────────────────────────────────────┤   │  Entry Buffer
         │originator name                       8 or 256│   │
         ├──────────────────────────────────────────────┤   │
         │process name (optional)               0 or 260│   │
         ├──────────────────────────────────────────────┤   │
         │formatting DLL module name (optional)       12│   │
         ├──────────────────────────────────────────────┤   │
         │Error Log entry data                   <= 3400│<──┘
         └──────────────────────────────────────────────┘
  
  
  

  Where

  • packet revision number'
    is an integer value that can be used to distinguish error logging packets that are intended to be handled by different revisions of the LogAddEntries API. For the initial version of the API, this field should be set to a value of 1. This field is included in the packet to support future backward compatibility.
    '# of Error Log entry packets'
    is the number of separate packets contained within the user's buffer.
    'length of this Error Log entry packet'
    is the number of bytes in the current Error Log entry packet within the user's Error Log Entry Buffer (this length includes the length of all the Error Log entry packet control fields and the size of the Error Log entry text). To support efficient logging execution, this length should be a multiple of 4 bytes (i.e. if necessary the user should pad the Error Log entry packet).
    'Error Log record I.D.'
    is the record I.D. for the current Error Log entry (I.D. registration will be statically registered by the OS/2 development organization).
    'status flags'
    is a two byte flag holder that contains three single bit flags:

    (BIT 0) is used to indicate whether the current Error Log entry packet contains space in which the Error Logging facility can place a long process name ("on" indicates YES, "off" indicates NO);

    (BIT 1) is used to indicate whether the current Error Log entry packet contains an 8 byte originator name or a 256 byte originator name ("on" indicates a 256 byte originator name, "off" indicates an 8 byte originator name);

    (BIT 2) is used to indicate that the caller has placed time and date values in the Error Log entry packet and does not wish to have those values modified during the logging process ("on" indicates that the Error Log entry packet already contains time and date values, "off" indicates the packet does not already contain time and date values);

    All the other 29 bits in 'status flags' are considered reserved at this time and will be zeroed by the LogAddEntries API.

    'qualifier name'
    is a secondary name field that is provided by the caller
    'reserved'
    is a four byte reserved field
    'time of logging'
    is filled in by the system Error Logging facility (unless BIT 2 of the 'status flags field is "on", indicating that the caller has preset a time value).
    'date of logging'
    is filled in by the system Error Logging facility (unless BIT 2 of the 'status flags field is "on", indicating that the caller has preset a date value);
    'originator name'
    is a primary name field that is provided by the caller.
    'process name'
    is an optional long process name field that will be filled in by the Error Logging facility if the field is provided by the caller in the Error Log entry packet.
    'formatting DLL module name'
    is the optional name of a DLL module that houses a formatting routine that recognizes this type of Error Log entry and can format it for display by the SYSLOG utility. The name is specified as an ASCIIZ string that can be up to eight characters in length. If no module name is specified in this field, then SYSLOG will display the data portion of the Error Log entry as a hexadecimal dump.
    'Error Log entry data'
    is an optional variable length set of data that can be supplied by the caller (the format of the string is under the control of the caller).

    The format and function of the LogAddEntries API call is very similar to that of the 16-bit DosLogEntry call. There are several functional differences from the DosLogEntry call:

    • The user-supplied error log entry Record I.D. will now be a statically allocated value rather than a dynamically allocated value.

    • The maximum size of the originator name field in the caller's packet has been increased from 8 bytes to 256 bytes. The caller can specify whether the packet contains an 8 byte originator name field or a 256 byte originator name field.

    • The maximum size of the variable length data portion within the caller's packet has been increased from 1024 bytes to 3400 bytes

    • The order of the fields within the Error Log entry has been slightly rearranged to support the creation of smaller internal control messages.

    In order to resolve successfully LogAddEntries function calls in your program, the following lines must be added to the Linker Definition (DEF) file:

    IMPORTS
    LogAddEntries=DOSCALL1.432
    
    
    

    ---

    [Back: LogClose]
    [Next: 32-Bit Error Log Entry Formatting DLL Routines]