Replication Distribution Agent Utility
The Replication Distribution Agent utility configures and begins a replication Distribution Agent, which moves transactions and snapshot jobs held in the distribution database tables to Subscribers. This syntax is used at the command prompt, and the executable file can be found in the \Mssql7\Binn directory.
Syntax
distrib [-?]
-Publisher publisher
-PublisherDB publisher_database
-Subscriber subscriber
[-BcpBatchSize bcp_batch_size]
[-Buffers number_of_buffers]
[-CommitBatchSize commit_batch_size]
[-CommitBatchThreshold commit_batch_threshold]
[-Continuous]
[-DefinitionFile def_path_and_file_name]
[-Distributor distributor]
[-DistributorAddress distributor_address]
[-DistributorLogin distributor_login]
[-DistributorNetwork distributor_network]
[-DistributorPassword distributor_password]
[-DistributorSecurityMode [0|1]]
[-ErrorFile error_path_and_file_name]
[-FileTransferType [0|1]]
[-FtpAddress ftp_address]
[-FtpPassword ftp_password]
[-FtpPort ftp_port]
[-FtpUserName ftp_user_name]
[-HistoryVerboseLevel [0|1|2|3]]
[-LoginTimeOut login_time_out_seconds]
[-MaxBcpThreads]
[-MaxDeliveredTransactions number_of_transactions]
[-MessageInterval message_interval]
[-NoTextInitOnSync]
[-Output output_path_and_file_name]
[-OutputVerboseLevel [0|1|2]]
[-PacketSize packet_size]
[-PollingInterval polling_interval]
[-ProfileName profile_name]
[-Publication publication]
[-QueryTimeOut query_time_out_seconds]
[-QuotedIdentifier quoted_identifier]
[-SubscriberDatabasePath subscriber_path]
[-SubscriberDB subscriber_database]
[-SubscriberLogin subscriber_login]
[-SubscriberPassword subscriber_password]
[-SubscriberSecurityMode [0|1]]
[-SubscriberType [0|1|2|3]]
[-SubscriptionTableName subscription_table]
[-SubscriptionType [0|1|2]]
[-TransactionsPerHistory [0|1|...10000]]
Note Parameters can be specified in any order. When optional parameters are not specified, values from predefined registry settings on the local computer are used.
Arguments
- -?
- Prints all available parameters.
- -Publisher publisher
- Is the name of the Publisher.
- -PublisherDB publisher_database
- Is the name of the Publisher database.
- -Subscriber subscriber
- Is the name of the Subscriber.
- -BcpBatchSize bcp_batch_size
- Is the number of rows to send in a bulk copy operation. When performing a bcp in operation, the batch size is the number of rows to send to the server as one transaction, and also the number of rows that must be sent before the Distribution Agent logs a bcp progress message. When performing a bcp out operation, a fixed batch size of 1000 is used. A value of 0 indicates no message logging.
- -Buffers number_of_buffers
- Is the number of buffers available for asynchronous transactions. The default is 2. Increasing the number of buffers can increase performance because doing so reduces memory paging; however, a larger number of buffers also increases the amount of memory reserved for paging. Performance can be evaluated by seeing how a change in buffer values affects the speed of the connections between Subscriber and Distributor.
- -CommitBatchSize commit_batch_size
- Is the number of transactions to be issued to the Subscriber before a COMMIT statement is issued. The default is 100.
- -CommitBatchThreshold commit_batch_threshold
- Is the number of replication commands to be issued to the Subscriber before a COMMIT statement is issued. The default is 1000.
- -Continuous
- Specifies whether the agent attempts to poll replicated transactions continually. If specified, the agent polls replicated transactions from the source at polling intervals, even if there are no transactions pending.
- -DefinitionFile def_path_and_file_name
- Is the path of the agent definition file. An agent definition file contains command prompt arguments for the agent. The content of the file is parsed as an executable file. Double quotation marks (“) can be used to specify argument values containing arbitrary characters.
- -Distributor distributor
- Is the Distributor name. For Distributor (push) distribution, the name defaults to the name of the local Distributor.
- -DistributorAddress distributor_address
- Is the network connection string for the Net-Library defined in the DistributorNetwork option. If the DistributorNetwork option is the TCP/IP Sockets Net-Library, then the connection string is in the form of
'address,socket'
For more information about the format, see Network Protocols. This option is useful for configuring connections over the Internet.
- -DistributorLogin distributor_login
- Is the Distributor’s login name.
- -DistributorNetwork distributor_network
- Is the Net-Library to use when connecting to the Distributor. This option is useful when configuring the Distribution Agent to connect to a Distributor over the Internet.
- -DistributorPassword distributor_password
- Is the Distributor’s password.
- -DistributorSecurityMode [0|1]
- Specifies the Distributor’s security mode. A value of 0 indicates SQL Server Authentication Mode (default), and a value of 1 indicates Windows NT Authentication Mode.
- -ErrorFile error_path_and_file_name
- Is the path and file name of the error file generated by the Distribution Agent. This file is generated at any point where failure occurred while applying replication transactions at the Subscriber. This file contains the failed replication transactions and associated error messages. When not specified, the error file is generated in the current directory of the Distribution Agent. The error file name is the name of the Distribution Agent with an .err extension. If the specified file name exists, error messages are appended to the file.
- -FileTransferType [0|1]
- Specifies the file transfer type. A value of 0 indicates UNC (universal naming convention), and a value of 1 indicates FTP (file transfer protocol).
- -FtpAddress ftp_address
- Is the network address of the FTP service for the Distributor. When not specified, DistributorAddress is used. If DistributorAddress is not specified, Distributor is used.
- -FtpPassword ftp_password
- Is the user password used to connect to the FTP service.
- -FtpPort ftp_port
- Is the port number of the FTP service for the Distributor. When not specified, the default port number for FTP service (21) is used.
- -FtpUserName ftp_user_name
- Is the username used to connect to the FTP service. When not specified, anonymous is used.
- -HistoryVerboseLevel [0|1|2|3]
- Specifies the amount of history logged during a distribution operation. You can minimize the performance affect of history logging by selecting 1.
HistoryVerboseLevel value |
Description |
1 |
Always update a previous history message of the same status (startup, progress, success, and so forth). If no previous record with the same status exists, insert a new record. |
2 |
Default. Insert new history records unless the record is for such things as idle messages or long-running job messages, in which case update the previous records. |
3 |
Always insert new records, unless it is for idle messages. |
- -LoginTimeOut login_time_out_seconds
- Is the number of seconds before the login times out. The default is 15 seconds.
- -MaxBcpThreads
- Specifies the number of bulk copy operations that can be performed in parallel. The maximum number of threads and ODBC connections that exist simultaneously is the lesser of MaxBcpThreads or the number of bulk copy requests that appear in the synchronization transaction in the distribution database. MaxBcpThreads must have a value greater than zero, and has no hard-coded upper limit. The default is 1.
- -MaxDeliveredTransactions number_of_transactions
- Is the maximum number of push or pull transactions applied to Subscribers in one synchronization. A value of 0 indicates that the maximum is an infinite number of transactions. Other values can be used by Subscribers to shorten the duration of a synchronization being pulled from a Publisher.
- -MessageInterval message_interval
- Is the time interval used for history logging. A history event is logged if either:
- The TransactionsPerHistory value is reached after the last history event is logged.
Or
- The MessageInterval value is reached after the last history event is logged.
If there is no replicated transaction available at the source, the agent reports a no-transaction message to the Distributor. This option specifies how long the agent waits before reporting another no-transaction message. Agents always report a no-transaction message when they detect that there are no transactions available at the source after previously processing replicated transactions. The default is 3600 (seconds).
- -NoTextInitOnSync
- Specifies that applications modifying text or image columns in the published table initialize pointers with some value other than NULL in the UPDATE statement.
- -Output output_path_and_file_name
- Is the path of the agent output file. If the file name is not provided, the output is sent to the console. If the specified file name exists, the output is appended to the file.
- -OutputVerboseLevel [0|1|2]
- Specifies whether the output should be verbose. If the verbose level is 0, only error messages are printed. If the verbose level is 1, all the progress report messages are printed. If the verbose level is 2 (default), all error messages and progress report messages are printed, which is useful for debugging.
- -PacketSize packet_size
- Is the packet size, in bytes. The default is 4096 (bytes).
- -PollingInterval polling_interval
- Is how often, in seconds, the distribution database is queried for replicated transactions. The default is 3 seconds.
- -ProfileName profile_name
- Specifies an agent profile to use for agent parameters. If ProfileName is NULL, the agent profile is disabled. If ProfileName is not specified, the default profile for the agent type is used.
- -Publication publication
- Is the name of the publication. For both types of distribution, this parameter is valid only for immediate_sync publications. If this parameter is not specified, then the Distributor processes all the nonimmediate_sync publications in the Publisher database.
- -QueryTimeOut query_time_out_seconds
- Is the number of seconds before the query times out. The default is 300 seconds.
- -QuotedIdentifier quoted_identifier
- Specifies the quoted identifier character to use. The first character of the value indicates the value the Distribution Agent uses. If QuotedIdentifier is used with no value, the Distribution Agent uses a space. If QuotedIdentifier is not used, the Distribution Agent uses whatever quoted identifier the Subscriber supports.
- -SubscriberDatabasePath subscriber_database_path
- Is the path to the Jet database (.mdb file) if SubscriberType is 2 (allows a connection to a Jet database without an ODBC DSN).
- -SubscriberDB subscriber_database
- Is the name of the Subscriber database.
- -SubscriberLogin subscriber_login
- Is the Subscriber’s login name. If SubscriberSecurityMode is 0 (for Mixed Mode), then this parameter must be specified.
- -SubscriberPassword subscriber_password
- Is the Subscriber’s password. If SubscriberSecurityMode is 0 (for Mixed Mode), then this parameter must be specified.
- -SubscriberSecurityMode [0|1]
- Specifies the Subscriber’s security mode. A value of 0 indicates Mixed Mode (default), and a value of 1 indicates Windows NT Authentication Mode.
- -SubscriberType [0|1|2]
- Specifies the type of Subscriber connection used by the Distribution Agent.
SubscriberType value |
Description |
0 |
Microsoft® SQL Server™ |
1 |
ODBC data source |
2 |
Jet database (direct connection) |
3 |
OLE DB data source |
- -SubscriptionTableName subscription_table
- Is the name of the subscription table generated or used at the given Subscriber. When not specified, the MSreplication_subscription table is used. Use this option for database management systems (DBMS) that do not support long file names.
- -SubscriptionType [0|1|2]
- Specifies the subscription type for distribution. A value of 0 indicates a push subscription, a value of 1 indicates a pull subscription, and a value of 2 indicates an anonymous subscription.
- -TransactionsPerHistory [0|1|...10000]
- Specifies the transaction interval for history logging. If the number of committed transactions after the last instance of history logging is greater than this option, then a history message is logged. The default is 100. A value of 0 indicates infinite TransactionsPerHistory. See MessageInterval.
Important If you installed SQL Server Agent to run under a local system account rather than under a domain user account (the default), the service can only access the local computer. If the Distribution Agent that runs under SQL Server Agent is configured to use Windows NT Authentication Mode when it logs in to SQL Server, the Distribution Agent fails. The default setting is Mixed Mode.
See Also
(c) 1988-98 Microsoft Corporation. All Rights Reserved.