3.1.4.3 R_WinsTrigger (Opnum 2)

The R_WinsTrigger method triggers a replication operation between a target WINS server and another WINS server.

 DWORD R_WinsTrigger(
   [in] handle_t ServerHdl,
   [in, ref] PWINSINTF_ADD_T pWinsAdd,
   [in] WINSINTF_TRIG_TYPE_E TrigType_e
 );

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.

pWinsAdd: Address of the WINS server with which the target WINS server performs the replication operation.

TrigType_e: The type of replication operation requested.

Return Values: A 32 bit unsigned integer value that indicates the return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation completed successfully. Any other 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.
0x00000FA0 ERROR_WINS_INTERNAL	An error occurred while processing the RPC call.
0x00000FA6 ERROR_RPL_NOT_ALLOWED	The WINS server requested for the replication operation is requested is not configured as a replication partner for the target WINS server.
0x00000005 ERROR_ACCESS_DENIED	The caller does not have sufficient permissions.

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

Processing and Response Requirements:

When R_WinsTrigger is called, the server returns immediately without waiting for the replication operation to finish. The server just queues a request for the replication operation, and the replication takes place at a time determined by the internal state and configuration of the target WINS server. Hence, applications that call R_WinsTrigger SHOULD NOT treat an ERROR_SUCCESS return value as indicating a successful replication operation. Instead, applications SHOULD rely on WINS event logs to determine whether or not replication is successful. The following table lists the events that indicate the status of replication.

Event ID	Event Name	Event Description
Informational events
4102	WINS_EVT_CONN_ABORTED	The connection was aborted by the remote WINS. It is possible that Remote WINS is not configured to replicate with the server.
4108	WINS_EVT_CANT_GET_INITRPL_VAL	WINS could not read the InitTimeReplication field of the pull/push key.
4115	WINS_EVT_CANT_GET_CC_MAX_RECS_AAT_VAL	WINS could not read the MaxRecsAtATime value (type DWORD) in the Wins\Parameters\ConsistencyCheck subkey of the registry. Set this value so that  WINS does not replicate more than a set number of records in one cycle while doing periodic consistency checks of the WINS database. When doing a consistency check, WINS replicates all records of an owner WINS by either going to that WINS or to a replication partner. At the end of a consistency check for an owner's records, WINS checks to see if it has replicated more than the specified values in the current consistency check cycle. If the value has been exceeded, the consistency check stops; otherwise it continues. In the next cycle, it starts from where it left off and returns to the first owner if required.
4116	WINS_EVT_CANT_GET_CC_USE_RPL_PNRS_VAL	WINS could not read the UseRplPnrs value of the Wins\Parameters\ConsistencyCheck key. If this value is set to a nonzero (DWORD) value, WINS will do a consistency check of the owners in its database by going to one or more of its replication partners. If the owner of the records happens to be a replication partner, WINS will go to it; otherwise it will pick a partner at random. Set this value if there is a large number of WINSs in the configuration and/or if the local WINS SHOULD NOT to go to any WINS that is not a replication partner.
4121	WINS_EVT_NO_RPL_RECS_RETRIEVED	The WINS Replicator could not find any records in the WINS database. This means there are no active or tombstone records in the database. It could be that the records being requested by a remote WINS server have either been released or do not exist.
4124	WINS_EVT_UPD_NTF_NOT_ACCEPTED	The WINS server received an update notification from the non-configured WINS server at the address, %1. The WINS server rejected it. This means the remote WINS server is not in the list of Push partners (WINS servers under the Pull key) and the administrator has prohibited (by using the registry) replication with non-configured WINS servers. To have  this WINS server to accept update notifications from non-configured WINS servers then set the Wins\Parameters\RplOnlyWCnfPnrs value in the registry to 0.
4126	WINS_EVT_ADD_VERS_MAP_REQ_NOT_ACCEPTED	The WINS server received a pull request from the non-configured WINS server with the address, %1. The WINS server rejected it since the remote WINS server is not in the list of Pull partners (WINS servers under the Pull key) and the administrator has prohibited (by using the registry) replication with non-configured partners. To have this WINS server to accept update notifications from WINS servers not in the "pull partner" list, then set the "replication only with configured partners" value in the registry to 0.
4134	WINS_EVT_INF_REM_WINS	The local WINS is informing a remote WINS to update the version number of a record. This is because the local WINS encountered a conflict between an active owned name and an active replica that it pulled from a replication partner.
4135	WINS_EVT_REM_WINS_INF	The local WINS has been informed by a remote WINS with the address %1, to update the version number of a record. This is because the remote WINS encountered a conflict between an active owned name and an active replica that it pulled from a replication partner.
4137	WINS_EVT_NAME_MISMATCH	A name mismatch was reported while verifying the validity of old replicas. The local record has the name %1 while the replica pulled in from the WINS that owns this record has the name %2. This could mean that the remote WINS was stopped and then restarted but its version counter value was not set to its previous value before termination.
4139	WINS_EVT_CNF_CHANGE	The WINS replication request is being ignored because WINS found that the Wins\Partners key information has changed (due to a notification from the registry) which makes the current partner request out-of-date.
4227	WINS_EVT_CANT_FIND_ANY_REC_IN_RANGE	The Push Thread was requested for a range of records but could not find any records in the range. The replication time intervals MUST be set properly. If the tombstone interval and timeout intervals are not correct (that is, much less than the replication interval), the preceding condition is possible. This is because the records might get changed into tombstones and then deleted before the remote WINS can pull them. Similarly, if the refresh interval is set to be much less than the replication interval, then the records could get released before a WINS can pull them (a released record is not sent).
4251	WINS_EVT_CONN_RETRIES_FAILED	The WINS Replication Pull Handler could not connect to a WINS server. All retries failed. WINS will try again after a set number of replication time intervals have elapsed.
4260	WINS_EVT_RPL_REG_ERR	WINS received an error while registering replicas. It will not register any additional replicas of this WINS at this time (the address is in the data section fourth through eighth byte). A previous log entry will specify the reason for this. If the same error occurs during subsequent replication with the preceding partner WINS, restore the WINS database from the backup.
4261	WINS_EVT_RPL_REG_GRP_MEM_ERR	WINS received an error while trying to register a group's replica with name %1. The replica is owned by the WINS with the address given in the data section.
4262	WINS_EVT_RPL_REG_UNIQUE_ERR	WINS received an error while trying to register a unique replica with name %1. The replica is owned by WINS with the address in the data section.
4268	WINS_EVT_RPL_STATE_ERR	WINS received a replica whose state is incorrect. For example, the state might be RELEASED or the replica might be an Internet group that does not have any members but the state is not TOMBSTONE.
4289	WINS_EVT_RECORD_NOT_OWNED	WINS is trying to update the version number of a database record that it does not own. This is a serious error if the WINS server is updating the record after a conflict. It is not a serious error if the WINS server is updating the record as a result of a request to do so from a remote WINS server. When a remote WINS server notices a conflict between an active owned entry and a replica, it requests the replica owner to update the version number of the record. It is possible that the replica is no longer owned by the remote WINS.
4295	WINS_EVT_ADJ_VERS_NO	When WINS replicated with its partners, one of the partners showed there was more data that actually existed. WINS adjusted its counter so that new registrations and updates are seen by its partners. This means that recovery did not work properly. Check which of the partners has the highest version number corresponding to the local WINS. This can be accomplished by shutting down WINS and restarting after specifying this number in the registry.
4307	WINS_EVT_RPLPULL_EXC	The WINS replicator Pull thread encountered an error while processing a request. Log entries will specify what went wrong.
4312	WINS_EVT_TERM_DUE_TIME_LMT	WINS has exceeded the wait time for all threads to terminate. The number of threads still active is given in the second DWORD of the data section. The thread that could be stuck is the replicator thread, which could be stuck because the other WINS is slow in sending data or reading data. The latter can contribute to pressure on the TCP connection on which it is trying to replicate.
Warning events
4153	WINS_EVT_UNABLE_TO_VERIFY	The Scavenger thread found active replicas that are required 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.
4155	WINS_EVT_REPLICA_CLASH_W_STATIC	A replica clashed with the static record, %1, in the WINS database. The replica was rejected.
4161	WINS_EVT_PARTIAL_RPL_TYPE	A nonzero replication type applies for this partner, which means only a subset of records will be replicated between the local WINS and this partner. To get records that did not replicate, either pull them by using the winscl.exe in the Windows 2000 Resource Kit, (as described in [MSFT-ResourceKits]) or delete all owners acquired only through this partner and initiate replication after that to reacquire all their records. The partner's address is given in the second DWORD of the data section.
4162	WINS_EVT_PNR_PARTIAL_RPL_TYPE	A partner has requested only a subset of records. This means that all the records in the range requested will not be replicated. Check the partner's registry to see what replication type applies to it. The partner's address is given in the second DWORD of the data section.
4163	WINS_EVT_ADJ_MAX_RECS_AAT	WINS adjusted the Maximum Records at a time parameter of the ConsistencyCheck key. The value specified, %2, was changed to the minimum value, %1. This represents the maximum number of records that will be replicated at any one time for a consistency check.
4164	WINS_EVT_FORCE_SCV_R_T	WINS was forced to scavenge replica tombstones of a WINS. The administrator forced the scavenging by 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 is to ensure that the tombstones have replicated to other WINSes. In this case, the tombstones were timed out but the WINS had not been running for three days. The replica tombstones were deleted. This deletion does not constitute a problem unless there are WINS servers that are primary and backup to clients but not both Push and Pull partners of each other. If this type of WINS exists, 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 by using winscl.exe.
Error events
4166	WINS_EVT_RPLPULL_ABNORMAL_SHUTDOWN	The replication Pull thread is shutting down due to an error. Restart WINS.
4167	WINS_EVT_RPLPUSH_ABNORMAL_SHUTDOWN	The replication Push thread is shutting down due to an error. Restart WINS.
4197	WINS_EVT_WINSOCK_BIND_ERR	An address could not bind to a socket. Make sure the TCP/IP stack is installed and running properly. This event might mean that the 'nameserver' port (specified in the services file) which is used as the default by WINS for replication and discovering other WINSes has been taken by another process or service running on this computer. There are two options: either end the other process or service, or direct WINS to use another port. If you choose the second option, set the value 'PortNo' (REG_DWORD) under the Wins\Parameters subkey in the registry to 1512. Note Changing the port number this way will prevent this WINS from replicating or discovering other WINSes unless they too are directed to use the same port number as this WINS.

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

• The R_WinsTrigger caller SHOULD have control level access. If an RPC client with a lower access level calls R_WinsTrigger, the server SHOULD return ERROR_ACCESS_DENIED.

• The WINS service on the target WINS server MUST be in the running or paused state. If the service is in initializing or exiting state, the server SHOULD return ERROR_WINS_INTERNAL for its status.

• When R_WinsTrigger is called with trigger type WINSINTF_E_PUSH, the server queues a push replication. If the target WINS server is configured to replicate only with partners and the address of the requested replication partner is not in the server's list of push replication partners, the server SHOULD return WINSINTF_RPL_NOT_ALLOWED. The server can also return ERROR_WINS_INTERNAL for any other errors occur while it processes the request.

• The trigger type WINSINTF_E_PUSH_PROP works same way as the command WINSINTF_E_PUSH except that the update notifications that are sent as part of push replication have the propagate opcode set (see [MS-WINSRA] section 2.2.8.

• When the R_WinsTrigger method is called with trigger type WINSINTF_E_PULL, the server queues a pull replication as specified by the pWinsAdd parameter. If the target WINS server is configured to replicate only with partners, and the address of the requested replication partner is not in the server's list of pull replication partners, the server SHOULD return WINSINTF_RPL_NOT_ALLOWED. Also, the server SHOULD return ERROR_WINS_INTERNAL for any other errors that occur while it processes the request.