DosLogRegister

From EDM2
Jump to: navigation, search

This is the 16 Bit Error Logging API's for IBM OS/2 Version 2.1 function.

There are two major differences between the OS/2 2.0 version of DosLogRegister and the 1.3 version of the API:

  • DosLogRegister no longer supports dynamic registration of Error Log record I.D.'s. Instead, the API always returns a single "default" value.
  • DosLogRegister no longer supports entry format template registration. While the API still accepts a format template as part of its input data packet, the format template will not be acted upon in any way.

DosLogRegister continues to support the existing alert notification registration function.

The description of the OS/2 2.0 version of the DosLogRegister API follows:

Syntax

DosLogRegister(LogHandle, LogRegList, RequestID)

Parameters

LogHandle (PUSHORT)
The address of the word in which the system will return the handle of a named pipe that will be transparently used in subsequent DosLogRead calls.
LogRegList (PVOID)
The address of the log registry buffer.
RequestID (PUSHORT)
The address of the word that the system will fill in with a "default" Error Log record I.D. (if the 'Error Log record I.D.' field in the log registry buffer is set by the caller to -1)

Return Code

DosLogRegister returns the following values:

  • Success : non-zero
  • Failure.

Possible reasons for failure are:

  • Facility unavailable
  • Record I.D. in use
  • Registration failed (general failure)
  • Invalid I.D.
  • Too many open files
  • Too many semaphores
  • Semaphore not found
  • User semaphore limit reached
  • Request timed out without satisfaction
  • Error Log buffer temporarily full

Remarks

Log Registry Buffer format description:

┌──────────────────────────────────────────────┐
│length of the registration data              2│
├──────────────────────────────────────────────┤
│reserved                                     2│
├──────────────────────────────────────────────┤
│Error Log record I.D.                        2│
├──────────────────────────────────────────────┤
│offset to the format template layout field   2│
├──────────────────────────────────────────────┤
│semaphore name string          variable length│
├──────────────────────────────────────────────┤
│format template layout         variable length│
└──────────────────────────────────────────────┘

Where:

'length of the registration data' 
is the total number of bytes in the current Log Registry Buffer (this length includes the two byte length field itself)
'reserved' 
is a two byte reserved field
'Error Log record I.D.' 
contains the Error Log record I.D. that caller wishes to be registered for. If the field is set to 0xFFFF (-1), then a "default" record I.D. is returned in the word pointed to by the'RequestID' parameter. This field can be used to specify an alert notification record I.D. (that is, the caller wishes to be alerted whenever an Error Log Entry containing this record I.D. is logged).
'offset to the format template layout field' 
is the offset within the Log Registry Buffer to the start of the format template layout area.
'semaphore name string' 
is the name of a system semaphore, created with the nonexclusive option, that will be used to alert the caller's process when an Error Log entry containing the specified 'Error Log record I.D.' is logged. The name string is an ASCIIZ string.
'format template layout' 
is an area within the Log Registry Buffer that contains the formatting structure information that is placed within the 1.3 Error Log file. This area is not used in the OS/2 2.0 version of the DosLogRegister call. However, the 'length of the registration data' field should reflect the size of this area.

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

IMPORTS
DOSLOGREGISTER=DOSCALL1.195