The NetAuditRead API reads from the audit log on a server.

The NetAuditRead API replaces the NetAuditOpen API, which is now obsolete.

To read an entire audit log, an application must call NetAuditRead repeatedly until the API indicates that there is no more data to be read. Each call to NetAuditRead returns a handle that must be provided to any subsequent call to NetAuditRead. This handle changes with each subsequent call; it is not a system file handle and never should be treated as such.

Note: The audit log can contain more than 64KB of data. If pusBytesReturned is 0 and pusBytesAvail is not 0, usBuflen is too small to hold all the records in the file, and the application should continue to reiterate calls to this API until pusBytesReturned is returned as 0.

The value of pusBytesAvail can be 0xFFFF. This value means there can be 0xFFFF or more bytes of data available, which possibly is even more than 64KB (the maximum buffer size). In order to receive all the data available from this API, an application must reiterate the call until pusBytesReturned and pusBytesAvail both are returned as 0.

pusBytesReturned applies to the last complete record in the buffer. However, a partial record may be left at the end of the buffer. You may not know whether the area following the last entry is null unless you check.

This API can be called from DLS and OS/2 workstations, but DLS workstations can issue this call only to a remote LAN Server workstation. Administrator authority is required to call this API.

#include <netcons.h>
#include <audit.h>
 
NetAuditRead(pszServername, reserved1, pLogHandle, offset,
             reserved2, reserved3, flags, buf,
             usBuflen, pusBytesReturned, pusBytesAvail);     /* 16 bit */
 
Net32AuditRead(pszServername, reserved1, pLogHandle, offset,
             reserved2, reserved3, flags, buf,
             ulBuflen, pulBytesReturned, pulBytesAvail);     /* 32 bit */

See Common Parameter Definitions for descriptions of parameters not defined here.

reserved1

(const unsigned char LSFAR *) must be NULL.
pLogHandle
(HLOG LSFAR *) is the pointer to the returned log handle.

An application calling NetAuditRead for the first time must initialize the 128-bit log handle as follows: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ BITS ³ VALUE ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ 127(MSB)-64 ³ 0 ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ 63-0(LSB) ³ 1 ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ


The most significant bit (MSB) is the leftmost bit, and the least significant (LSB) is the rightmost bit. To initialize, use the fields in the log-handle structure, which is defined in the AUDIT.H header file. The structure definition is:

 typedef struct loghandle {
       unsigned long   time;
       unsigned long   last_flags;
       unsigned long   offset;
       unsigned long   rec_offset;
    } HLOG;

Using the log-handle structure, you can initialize the bits in the following manner:

  ploghndl.time = 0L;
  ploghndl.last_flags = 0L;
  ploghndl.offset = 0xFFFFFFFF;
  ploghndl.rec_offset = 0xFFFFFFFF;

Thereafter, each call to NetAuditRead must be given the value for the log handle that was returned by the previous call to NetAuditRead.

offset
(unsigned long) is the offset of the record to begin the read. This parameter is ignored unless the flags bit 1 is set. If the flags bit 1 is set, offset is taken as a zero-based offset based on the record number, not bytes, at which the data returned should begin. The offset parameter is dependent on which direction a file is read. If the file is being read backward, record 0 is the last record in the file. If the file is being read forward, record 0 is the first record in the file.
reserved2
(16-bit unsigned short LSFAR * or 32-bit unsigned long LSFAR *) must be NULL.
reserved3
(unsigned long) must be 0.
flags
(unsigned long) is a bit mask, mapped as follows: ÚÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ BITS ³ MEANING ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ 0 ³ If 0, the file is read normally. If 1, the file is read backward ³
³ ³ and records are returned in the buffer in reverse chronology (newest ³
³ ³ records first). ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ 1 ³ If 0, read proceeds normally and sequentially. If 1, read proceeds ³
³ ³ from the nth record from the start of the file, where n is the ³
³ ³ offset parameter. ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ 2-31 ³ Reserved; must be 0. ³
ÀÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

buf
(unsigned char LSFAR *) points to the local memory address where the audit log file entries are to be placed.
usBuflen
(16-bit unsigned short or 32-bit unsigned long) specifies the amount of local memory (in bytes) allocated to receive data from this API.

The following table lists the return codes most significant to this API. (See API Return Codes for a complete list of return codes.) ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿³SYMBOLICCONSTANT ³VALUE³MEANING ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_Success ³ 0 ³ No errors were encountered. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ ERROR_ACCESS_DENIED ³ 5 ³ Administrator privilege is required. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ ERROR_SHARING_VIOLATION ³ 32 ³ A sharing violation occurred. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ ERROR_BAD_NETPATH ³ 53 ³ The network path cannot be found. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ ERROR_NETWORK_ACCESS_DENIED ³ 65 ³ Network access is denied. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ ERROR_INVALID_PARAMETER ³ 87 ³ At least one parameter value is not ³
³ ³ ³ valid. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ ERROR_NET_WRITE_FAULT ³ 88 ³ A network data fault has occurred. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_NetNotStarted ³ 2102 ³ The redirector NETWKSTA.200 has not ³
³ ³ ³ been started. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_RemoteOnly ³ 2106 ³ This operation is not supported on ³
³ ³ ³ workstations. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_BufTooSmall ³ 2123 ³ The buffer is too small for fixed- ³
³ ³ ³ length data. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_WkstaNotStarted ³ 2138 ³ The Requester service has not been ³
³ ³ ³ started. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_InternalError ³ 2140 ³ An internal error has occurred. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_BadTransactConfig ³ 2141 ³ The server is not configured for ³
³ ³ ³ transactions. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_InvalidAPI ³ 2142 ³ The requested API is not supported on ³
³ ³ ³ the remote server. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_InvalidComputer ³ 2351 ³ The specified computer name is not ³
³ ³ ³ valid. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_LogFileChanged ³ 2378 ³ This log file has changed between ³
³ ³ ³ reads. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_LogFileCorrupt ³ 2379 ³ This log file is damaged. ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ NERR_InvalidLogSeek ³ 2440 ³ The log file does not contain the ³
³ ³ ³ requested record number. ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ


Other codes could be returned from the following functions:

• DosChgFilePtr
  
• DosClose
  
• DosFsCtl
  
• DosGetShrSeg
  
• DosOpen
  
• DosRead

For information about:

• Clearing an audit log file, see Auditing - NetAuditClear. 
  Closing an audit log file, see DosClose in the OS/2 Technical Library, Programming Guide Volume 1.
  
  Reading an audit log file, see DosRead in the OS/2 Technical Library, Programming Guide Volume 1.
  
  Writing an entry to the audit log file, see Auditing - NetAuditWrite.

  ---

  [Back] [Next]