Directory Services

DSDE Reference

[This documentation is preliminary and subject to change.]

Directory Services Data Exchange (DSDE) is a command-prompt utility. It processes input from either the command line or a DSML request document file. It returns results to the command prompt window or the specified output file.

The DSDE command line syntax is as follows:

dsde [flag1 [flag2 ...]]

The /mode flag is required. If /mode IMPORT is specified, then the /input flag is also required. All other command line flags are optional. If no flags are specified, then DSDE will output the online help to the command prompt window.

The following table lists general arguments that can be used in import and export modes.

General arguments
Flag	Abbr.	Description	Default	Mode
/server name	/srv	Specifies the name or virtual directory of the server. It can be a DC, a domain name, or the complete URL address of a DSML Services for Windows ISAPI Extension module (adssoap.dsmlx).	The current Active Directory domain controller.	import / export
/port number	/p	Specifies the port number that is used to connect to the server.	389 for LDAP, 636 for LDAP using SSL, 80 for DSML, 443 for DSML using SSL.	import / export
/protocol [LDAP\|DSML]	/prot	Specifies the protocol format used to communicate with the server.	LDAP	import / export
/opTimeout seconds	/ot	Specifies the timeout, in seconds, for each DSDE operation. The overall command timeout is computed by DSDE. The total timeout value is the number of individual operations times the specified timeout value.	60	import / export
/conTimeout seconds	/ct	Specifies the timeout, in seconds, for the initial connection. The connection timeout is measured from the point that the initial request sent to the server until the point the server responds to the client for establishing a connection.	300	import / export
/output filespec	/out	Specifies the name of the output file for the results. This is normally used in the Export mode. If used in import mode, it writes the server command responses to the specified file. If /output is omitted, the results can also be redirected to a file with the use of the standard command line redirection operators; that is > or >>.	The output is written to the command prompt window (standard console) in export mode. By default, Server command response output is disabled in import mode.	import / export
/quiet	/q	Specifies quiet mode. By default, both the Import and Export modes are in verbose mode. The quiet mode eliminates most of the extra status messages sent to the standard output.	verbose mode
/logDirectory dirspec	/log	Specifies the name of the log file directory and enables the creation of the dsde.log log file. If omitted, no log file is created.	No log file or directory created.	import / export
/mode [IMPORT\|EXPORT]	/m	Specifies the mode in which DSDE runs.	EXPORT	import / export
/ssl		Enables SSL encryption for all communications with the server.	SSL not enabled.	import / export
/replace fromDN toDN	/repl	Replaces all occurrences of fromDN with toDN. These replacements are performed on the DNs and the attribute values of the objects.		import / export
/referral [ON\|OFF]	/rf	Enables or disables referral chasing when a referral is generated by the server. Referral chasing is restricted to the LDAP protocol.	OFF	import / export
/?		Outputs online help to the standard console.		import / export

The following table lists arguments that can be used only in export mode.

Export-specific arguments
Flag	Abbr.	Description	Default	Mode
/query filter	/qS	Specifies a command line LDAP query.	(objectClass=*)	export
/baseDN dn	/dn	Specifies the root of the LDAP search.	default naming context	export
/scope [BASE\|ONELEVEL\|SUBTREE]	/sc	Specifies the scope of the LDAP query.	SUBTREE	export
/attributes attrList	/attr	Specifies a comma-delimited list of attributes that will be returned in the results set. The list must be entered without extraneous spaces, so any attribute names with embedded spaces must be enclosed inside double-quotes. This flag cannot be used with the /excludedAttributes flag.	All attributes are returned.	export
/excludedAttributes attrList	/Xattr	Specifies a comma-delimited list of attributes that will be excluded in the results set; all other attributes not in the list will be returned. The list must be entered without extraneous spaces, so any attribute names with embedded spaces must be enclosed inside double-quotes. This flag cannot be used with the /attributes flag.	No attributes are excluded.	export
/pageSize count	/page	Specifies the page size used for search operations. If set to 0, paging is disabled.	100	export
/outRequest	/Oreq	Transforms all searchResponse results to request operations before returning the results to the user. This flag is valid only if the mode is set to EXPORT. The result of this flag is to format the results of the DSDE operation into a format that can be used as an input request document for DSML Services for Windows.	No transformation performed.	export

The following table lists arguments that can be used only in import mode.

Import-specific arguments
Flag	Abbr.	Description	Default	Mode
/input filespec	/in	Specifies the name of the input file for the request document.		import
/resume	/rm	Specifies that the server should resume with the next input operation when an error occurs. This flag overrides any onError="exit" command in the DSML v2 input request file.	Error resume is disabled.	import
/bulk [ON\|OFF]	/bk	Enables or disables the LazyCommit behavior of the server.	ON	import

The following table lists credential-handling arguments, which can be used in import and export modes.

Credential-handling arguments

Flag

Abbr.

Description

Default

Mode

/cred username password

/cr

Specifies alternate user credentials. If an asterisk (*) is specified for the password argument, the user will be prompted for a password by the command prompt window. The prompted password is not echoed to the command windows.

default credentials for the current user.

import / export

/authFlag [NEGO|BASIC|ANONYMOUS]

Specifies the authentication method used between the client and server computers.

NEGO: Negotiate. Credentials are not required, and if not specified the credentials default to the current logon user. If authenticating against a DSML Services for Windows server, IIS Windows Integrated Authentication is used.

BASIC: Credentials are required. If authenticating against a DSML Services for Windows server, an HTTP Basic Authentication is performed. If authenticating against an LDAP server, an LDAP simple bind is performed.

BASIC authentication for either LDAP or DSML Services for Window always transmits the username and password credentials as plaintext across the network, unless SSL is used to encrypted the underlying network traffic.

ANONYMOUS: Credentials are not allowed. If authenticating against a DSML Services for Windows server, the IIS Anonymous user account is used. If authenticating against an LDAP server, an anonymous LDAP bind is performed.

NEGO

import / export

Remarks

While DSDE runs, DSDE will echo processing status messages to the command prompt window (standard output) as a way to provide user feedback. Specifying /quiet disable the user feedback output.

The following events will generate echo:

DSDE receives <errorResponse>.
DSDE completes the process. If no <errorResponse> and LDAP Error are reported, it should report as Command completed successfully. If there are one or more errors, DSDE should report as Command completed with error(s).

Character Sets Used in DSDE

DSDE will always produce Unicode files, including all export and log files.

DSDE will probe any input file if the character set is not specified. If the input file appears to be Unicode, then it will be processed as all Unicode. If the input file appears to be ANSI, then it will be processed as all ANSI.

DSDE Referral Chasing Behavior

In the current release, there are three scenarios where chase Referral is applicable:

Protocol is set to DSML and the DSML Services for Windows server produces an HTTP REF URL to DSDE.
Protocol is set to DSML and the DSML Services for Windows server returns an LDAP Referral to DSDE.
The protocol is set to LDAP and the LDAP directory server returns an LDAP referral to DSDE.

DSDE will chase the referral only if the chase referral switch is turned on and the directory server returns an LDAP referral to DSDE. In all other cases DSDE will ignore the referral.

Example Code

The following code examples show DSDE command prompt usage.

The first code example performs an export of all objects under the default naming context using the LDAP protocol. DSDE outputs the search results to the console, which is then redirected to a file named "dit.xml" .

DSDE  /qS (objectClass=*) > dit.xml

The second code example performs an import of the contents of the file "import.xml". It uses the DSML protocol to talk to a server named "myServer" by specifying the complete URL of the server's DSML ISAPI extension module.

DSDE /in  import.xml /protocol dsml /serverName http://myServer/dsml/adssoap.dsmlx /m import

The third code example performs an export using the DSML protocol. It exports all objects with an objectClass of user and an objectCategory of person located under the default naming context and stores the results in a file named "user.xml".

DSDE /query (&(objectClass=user)(objectCategory=person))  /prot dsml /serverName http://myServer/dsml/adssoap.dsmlx /out user.xml