3.1.4.22 R_WinsDoScavengingNew (Opnum 21)

The R_WinsDoScavengingNew method requests a specific scavenging operation on the target WINS server.

 DWORD R_WinsDoScavengingNew(
   [in] handle_t ServerHdl,
   [in, ref] PWINSINTF_SCV_REQ_T pScvReq
 );

ServerHdl: An RPC binding over IP address/HostName to the WINS server. RPC uses this binding internally to determine which WINS server the call is directed to.

pScvReq: A pointer to a WINSINTF_SCV_REQ_T structure (section 2.2.2.12) that defines the type of scavenging operation.

Return Values: A 32-bit unsigned integer that indicates the return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation completed successfully. A nonzero return value is a Win32 error code, as specified in [MS-ERREF]. The following Win32 error codes can be returned:

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x00000005

ERROR_ACCESS_DENIED

The caller doesn't have sufficient permissions.

Exceptions Thrown: No exceptions SHOULD be thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

Processing and Response Requirements:

When R_WinsDoScanvengingNew is called, the method returns immediately without waiting for scavenging to start. The server just queues a request for the scavenging operation; the internal state and configuration of the WINS server and the value of the fForce member in the WINSINTF_SCV_REQ_T structure (section 2.2.2.12) determine whether the scavenging occurs. Hence, callers to R_WinsDoScanvengingNew SHOULD NOT treat a return code of ERROR_SUCCESS as indicating a successful scavenging operation. Instead, callers SHOULD rely on WINS event logs to determine whether or not the scavenging operation succeeded. The following table lists the events that indicate the status of scavenging.

Event ID

Event Name

Event Description

Informational events

4143

WINS_EVT_SCV_RECS

WINS scavenged its records in the WINS database. The number of records scavenged is listed in the data section.

4144

WINS_EVT_SCV_RPLTOMB

WINS scavenged replica tombstones in the WINS database. The number of records Scavenged is in the data section.

4247

WINS_EVT_SCV_EXC

The WINS Scavenger thread encountered an error.

4250

WINS_EVT_SCV_ERR

The WINS Scavenger thread could not scavenge a record. This record is ignored and the Scavenger continues to the next available record. Check the application log for the Exchange component, ESENT.

4269

WINS_EVT_UNABLE_TO_CHG_PRIORITY

The Scavenger thread was unable to change its priority level.

4288

WINS_EVT_CLEANUP_OWNADDTBL_EXC

The Scavenger thread encountered an error while cleaning up the owner-address table. It will try again after the Verify interval has elapsed.

4328

WINS_EVT_ADMIN_SCVENGING_INITIATED

Administrator '%1' has initiated a scavenging operation.

4329

WINS_EVT_SCVENGING_STARTED

The WINS server has started a scavenging operation.

4330

WINS_EVT_SCVENGING_COMPLETED

The WINS server has completed the scavenging operation.

5001

WINS_EVT_SCV_RANGE

WINS is scavenging the locally owned records from the database. The version number range that is scavenged is in the data section, in the second to fifth words, in this order: from_version_number (low word, high word) to_version_number (low word, high word).

5002

WINS_EVT_SCV_CHUNK

WINS is scavenging a chunk of N records in the version number range from X to Y. N, X ,and Y (low word, high word for version numbers) are listed in the second to sixth words in the data section.

Warning events

4150

WINS_EVT_ADJ_TIME_INTVL_R

WINS adjusted the scavenging related time interval, %1, so that it is compatible with the replication time intervals. The adjusted value for this scavenging parameter is given in the data section (second DWORD). This value was computed by WINS using an algorithm that MAY use the maximum replication time interval specified. The current value achieves a balance between consistency of databases across the network of WINS servers and the performance of the WINS servers.

4151

WINS_EVT_ADJ_TIME_INTVL

WINS adjusted the scavenging related time interval, %1. The adjusted value for this scavenging parameter is listed in the data section (second DWORD). This value was computed by WINS using an algorithm that tries to achieve a balance between consistency of databases across the network of WINS servers and the performance of the WINS servers.

4153

WINS_EVT_UNABLE_TO_VERIFY

The Scavenger thread found active replicas that needed to be verified with the owner WINS server because they were older than the verify time interval. The table of owner-to-address mappings indicated the WINS was not active.

4164

WINS_EVT_FORCE_SCV_R_T

WINS was forced to scavenge replica tombstones of a WINS. The administrator on the computer forced the scavenging using winscl.exe. WINS does not scavenge replica tombstones unless they have timed out and the WINS has been running for at least three days. This ensures that the tombstones have replicated to other WINSes). In this case, the tombstones were timed out but the WINS had not been up for three days. The replica tombstones were deleted. This deletion does not constitute a problem unless the WINS servers are primary andbackup to clients but not both Push and Pull partners of each other. If there are such WINSes, there is a low probability that this action will result in database inconsistency, but if it does, a consistent state can be achieved by initiating consistency checks using winscl.exe.

The following requirements and recommendations apply to a WINS server that processes a call to R_WinsDoScavengingNew:

  • Callers to R_WinsDoScavengingNew SHOULD have control level access. If an RPC client with a lower access level calls R_WinsDoScavengingNew, the server SHOULD return ERROR_ACCESS_DENIED.

  • The WINS server queues a request on the target WINS server for the scavenging operation, and the method returns immediately with ERROR_SUCCESS as the status code.