dtscli -transfer Parameter Group—Perform Managed Transfers

dtscli Command—Manage Data Transfers › dtscli -transfer Parameter Group—Perform Managed Transfers

dtscli -transfer Parameter Group—Perform Managed Transfers

The -transfer parameter group creates, deletes, and retrieves the status of the transfer objects in a managed transfer.

Syntax format:

dtscli -transfer [checkpoint=y|n] [commit=y|n] [cskip=nn|prefixtransfer]

[fskip=nn|prefixtransfer] [data1=userdata1] [data2=userdata2] [delimiter_conversion=y|n] [delivery=discreet_delivery_period] [description=description] [direction=s|r] [expiry=discreet_expiry_period] [id=object_id] "ipath=host::path" [ipriority=urgent|default|discreet] [iuser=username::password] [iuuid=uuid] [ruuid=uuid] ["f_filters=filters"] ["p_filters=filters"] [label=label] [method=create|delete|status] ["method_parameters=method_parameters"] [output_mode=a|c|r|s|w] [retry_interval=session_retry_interval] [retry_limit=session_retry_limit] "rpath=host::path" [rpriority=urgent|default|discreet] [ruser=username::password]

Note: The -transfer operand can be abbreviated as -t.

checkpoint=y|n

(Optional) Specifies whether the checkpoint restart feature, which is an error recovery mechanism used by Data Transport Service, is enabled. Valid values are y (yes) and n (no). When checkpoint restart is enabled, if a failure occurs during a transfer, Data Transport Service attempts to restart the transfer from the point of failure. When checkpoint restart is disabled, the transfer is restarted from the beginning if a failure occurs during a transfer.

Default: None

commit=y|n

(Optional) Specifies whether the commit to disk feature is enabled. Valid values are y (yes) and n (no). If enabled, the DTS agent flushes its file output buffers to hard disk after every parcel of data has been received. If commit to disk is not specified (n), the DTS agent relies upon the operating system file I/O to flush buffers when necessary.

Default: None

cskip=nn|prefixtransfer

fskip=nn|prefixtransfer

Note: Applies to Data Transport Service r2 and r3 and Client Automation only.

(Optional) Specifies the skip logic setting, the number of transfers to skip if the transfer completes (cskip=) or fails (fskip=). Skip logic applies only to transfers in sequential transfer jobs. For each individual transfer in a sequential transfer job, skip logic allows you to skip the next n transfers or skip forward to another transfer when this transfer completes of fails.

nn

Specifies the number of transfers to skip, such as 1, 2, 3, or a negative number. Use a negative number to skip all remaining transfers, so that no more transfers in the job are activated.

prefixtransfer

Specifies the prefix (I, L, or N) followed by the ID, label, or name of the next transfer to be activated, as follows:

Itransfer-ID
Indicates the object ID of the next transfer to be activated. For example, I657 specifies the transfer whose object ID is 657.
Ltransfer-label
Indicates the label of the next transfer to be activated. For example, Lrecpt_mon specifies the transfer whose label is recpt_mon.
Ntransfer-name
Indicates that the name of the next transfer to be activated. For example, Ntot251200 specifies the transfer whose name is tot251200.

Default: None (empty)

Note: No logic checking is performed: Whatever values you specify for nn in the cskip=nn and fskip=nn expressions are used for the skip logic values.

data1=user_data1

(Optional) Allows user-defined data to be associated with the transfer.

Default: None

data2=user_data2

(Optional) Allows user-defined data to be associated with the transfer.

Default: None

delimiter_conversion=y|n

(Optional) Specifies whether delimiter conversion is enabled. Valid values are y (yes) and n (no). Use delimiter conversion (y) only for instances when you specify the output file name in the same format as the input file name, even though the receiving computer is running on a different platform from the sending computer. In such cross-platform transfers, delimiter conversion helps to ensure that the output path name for the transferred data is correctly delimited for the receiving platform.

Delimiter conversion is intended for cross-platform transfers when the platforms involved use similar (but not exactly the same) delimiters and file naming conventions. The intended use most commonly includes one-to-many transfers between Windows and UNIX/Linux computers. Other kinds of cross-platform transfers are also supported.

If you specify the input and output path names for your transfer completely and accurately while creating or updating a transfer, do not use delimiter conversion. Use delimiter conversion only if you specify the output file name in the same format as the input file name in a cross-platform transfer.

Note: Use delimiter conversion with caution. It does not function as an error checking or validation mechanism for the file naming or delimiter conventions of the receiving platforms.

Default: None

Example: The following example depicts a fanout transfer to Windows and UNIX systems:

dtscli -t "ipath=c:\input.txt"

"rpath=unixserver1::c:\tmp\output.txt"
iuser=administrator::adminpass
ruser=root::rootpass
delimiter_conversion=y
-t "ipath=c:\input.txt"
"rpath=winserver1::c:\tmp\output.txt"
iuser=administrator::adminpass
ruser=root::rootpass
delimiter_conversion=y

delivery=discreet_delivery_period

(Optional) Specifies the discreet delivery period in minutes. This option is applicable only if you specified a transfer priority of discreet for sending the transfer (using ipriority) or for receiving the transfer (using rpriority), or if you specified both. If you specify discreet mode for both sending and receiving the transfer, the same discreet delivery period applies to both.

The discreet delivery period specifies the amount of time during which the initiating or responding DTS agent tries to send or receive the transfer in discreet mode. If the discreet send or discreet receive is not completed within this period, the transfer priority automatically changes from discreet to urgent. (The transfer priority settings are explained in the ipriority and rpriority operand descriptions.)

The time begins to be counted when the transfer is activated (not created).

The discreet delivery period (delivery) is normally used with the discreet expiry period (expiry). The discreet delivery period must be less than or equal to the discreet expiry period. If you specify one of these options (delivery or expiry) but not the other, the default value is used for the missing option.

Default: -1 (unlimited)

Example: To specify a discreet transfer with a discreet delivery period of 360 minutes (6 hours) and a discreet expiry period (expiry) of 720 minutes (12 hours), enter:

dtscli -a|t "ipath=ukwin4q::c:\winnt\tngdts.ini"

"rpath=philauk::c:\config\ukwinp4q\tngdts.ini"
ipriority=discreet rpriority=discreet
delivery=360 expiry=720

"description=description"

(Optional) Specifies a description for the transfer. If the description includes one or more spaces, enclose the entire expression in quotation marks.

Limits: 1–255 characters

direction=s|r

(Optional) Specifies whether the initiating computer in the transfer will receive or send data. Valid values are as follows:

s

Sends data from the initiator to the responder.

r

Sends data from the responder to the initiator.

Note: When using the direction=r option, remember that the source file is on the responding computer, while the destination file is on the initiating computer. (Typically, the opposite is true.)

Default: s

Example: In the following managed transfer example, the initiating computer (NYC_HQ) receives data from the responder (STORE888):

dtscli -a|t "ipath=NYC_HQ::c:\receipts\store888\010398.rcp"

"rpath=STORE888::PDEV.RRARI09.RECEIPTS" direction=r

expiry=discreet_expiry_period

(Optional) Specifies the discreet expiry period in minutes. This option is applicable only if you specified a transfer priority of discreet for sending the transfer (using ipriority) or for receiving the transfer (using rpriority), or if you specified both. If you specify discreet mode for both sending and receiving the transfer, the same discreet expiry period applies to both.

If the transfer expires, it is deleted, and no further attempts to send it occur. The expiry period (expiry) must be greater than or equal to the discreet delivery period (delivery). If you specify one of these options (expiry or delivery) but not the other, the default value is used for the missing option.

The time begins to be counted when the transfer is activated (not created).

Default: -1 (unlimited)

Example: This example specifies a discreet transfer with a discreet delivery period (delivery) of 180 minutes (3 hours) and a discreet expiry period of 360 minutes (6 hours):

dtscli -a|t "ipath=ukwin4q::c:\winnt\tngdts.ini"

"rpath=philauk::c:\config\ukwinp4q\tngdts.ini"
ipriority=discreet rpriority=discreet delivery=180 expiry=360

id=object_id

(Optional) Applies a transfer method, transfer job method, or schedule method appropriately to one, more, or all specified transfers, transfer jobs, or schedules.

Note: This operand is for existing transfers only. Do not specify an ID when creating a transfer.

Default: None

Examples:

To apply a method (see method=create|delete|status) to a single transfer, use the following format:
```
dtscli -t method=method id=id
```
The add, insert, and remove methods let you apply a method to multiple transfers, using either the id= operand or the label=label operand. For the id= operand, if you specify two or more transfer object IDs when applying a method, enclose the entire id= expression in quotation marks, as shown here:
```
dtscli -t method=method "id=120 130 140"
```
To apply a method to all transfer objects, specify id=all, as shown here:
```
dtscli -t method=method id=all
```

"ipath=host::path"

Specifies the input file in the transfer enclosed in quotation marks. The host name is followed by two colons and the full path name of the transfer. For example:

Windows

"ipath=mmmww185::c:\receipts\010398.rcp"

UNIX/Linux

"ipath=machj17::/home/receipts/010398.rcp"

HTTP Transfers (Internet Downloads):

"ipath=DTA_host_name::destination_path"

Note: The ipath= operand is required.

host

Specifies the computer's name, IP address, or IPX address. For IP addresses, use periods (.) as separators; for example, 172.24.255.255. For IPX addresses, use either periods or colons (:) as separators; for example 00000005.000000000001 or 00000005:000000000001.

A DTS agent acting as an initiator receives transfer requests from this command line utility, establishes a connection to a target responder or group of responders, and sends the data. The initiator is the computer that is initiating the transfer. If the host name is omitted, the local host is used by default.

path

Specifies the full path name of the input data.

Examples:

To send a managed transfer from a Windows computer named canoes to another Windows computer named tipper, enter the following command:
```
dtscli -a|t "ipath=canoes::C:\My Documents\Monthly Reports\apr2008.doc"
	"rpath=tipper::C:\Monthly Reports\David\apr2006.doc"
```
To send a managed transfer between two UNIX/Linux computers named CHICAGO12 and NEWYORK20, enter the following command at the UNIX/Linux prompt:
```
dtscli -a|t "ipath=CHICAGO12::/home/ptfiles/ptcr1000.txt"
	"rpath=NEWYORK20::/home/ptfiles/ptcr1000.txt"
```
To send a managed transfer from a Windows computer named Miami to a UNIX computer named NEWYORK20, enter the following command:
```
dtscli -a|t "ipath=Miami::C:\outgoing\file.txt"
	"rpath=NEWYORK20::/home/incoming/file.txt"
```
Note: If running the dtscli command on UNIX/Linux, remember that the backslash character is the "escape" character. To specify a Windows path, the backslash characters must appear twice. For example:
```
 dtscli -a|t "ipath=Miami::C:\\outgoing\\file.txt"
	"rpath=NEWYORK20::/home/incoming/file.txt" 
```

ipriority=urgent|default|discreet

(Optional) Specifies the transfer priority on the initiating computer in the transfer: urgent, default, or discreet, as described following. The transfer priority you specify here for the initiating computer works with the transfer priority setting for the responding computer (rpriority) and the agent DiscreetMode settings (normal or discreet) for the initiating and responding computers in the transfer. (The agent DiscreetMode setting is one of the Data Transport Agent parameters, which can also be set using the DSM Explorer.)

Note: For more information, see the Data Transport Agent Plugin Policy Group topic in the Configuration Policy section of the DSM Explorer Help.

Together, the following transfer priority settings and agent DiscreetMode settings determine which mode (normal or discreet) is used to send the transfer and which mode is used to receive the transfer.

urgent

Sends the transfer in normal mode, even if the agent DiscreetMode setting is Y (yes) on the initiating computer.

default

Sends the transfer in normal mode if the agent DiscreetMode setting is N (no) on the initiating computer. However, if the agent DiscreetMode setting is Y (yes) on the initiating computer, then the transfer is sent in discreet mode.

discreet

Sends the transfer in discreet mode, even if the agent DiscreetMode setting is N (no) on the initiating computer.

Discreet transfers are sent and received in the background, using minimal bandwidth, when the sending and receiving computers are not heavily loaded. Based on the load, the DTS agent determines when to send the transfer and calculates the optimal transfer rate, so that the discreet transfer has a minimal impact on the computer’s performance and the user’s productivity.

Default: default

Example: To send and receive (rpriority) a transfer in discreet mode, enter the following command using the default values for the discreet delivery period (delivery) and the discreet expiry period (expiry):

dtscli -a|t "ipath=ukwin4q::c:\winnt\tngdts.ini"

"rpath=philauk::c:\config\ukwinp4q\tngdts.ini"
ipriority=discreet rpriority=discreet

iuser=username::password

(Optional) Specifies the user name and password for the initiating computer.

Note: This is a required parameter if the security mode is set to "fail" for the DTS agents involved in the transfer.

Default: None

Example: This example specifies the user name and password for both the initiating computer (ipath iuser) and the receiving computer (rpath ruser):

dtscli -a|t "ipath=NYC_HQ::c:\receipts\store888\010398.rcp" iuser=Frank::furter

"rpath=STORE888::PDEV.RRARI09.RECEIPTS" ruser=Molly::pitcher

iuuid=uuid

ruuid=uuid

(Optional) Specifies that the iuuid= and ruuid= parameters be used by the DTS agent on the responding computer in a transfer to ensure that the transfer request (request to initiate a transfer) it received was actually intended for it and not for another computer. Data Transport Service uses Dynamic Host Configuration Protocol (DHCP) more efficiently by checking the values of these parameters against the information stored for each DTS agent in the CA MDB.

Default: None

Important! Use these parameters only at the direction of your Management Database (MDB) administrator or Technical Support.

"f_filters=filters"

"p_filters=filters"

(Optional) Specifies the type of filter for a transfer. File filters (f_filters) process the data being transferred one file at a time. Parcel filters (p_filters) process the data being transferred one parcel at a time. (A parcel is a smaller unit of data within the file.)

Typically, you specify filter parameters for agent-to-agent transfers only, not for managed transfers. The only exception is any encryption filter. For all other filters that require parameters, managed transfers automatically take the values supplied by the Transfer Object Server.

To specify file filters, use the following format:

dtscli -a|t "ipath=ipath" "rpath=rpath" ...

"f_filters=file_filters"

To specify parcel filters, use the following format:

dtscli -a|t "ipath=ipath" "rpath=rpath" ...

"p_filters=parcel_filters"

You can specify a single read or write filter or a matching pair of read and write filters. Enclose the entire "f_filters=file_filters" or "p_filters=parcel_filters" expression in quotation marks. Separate multiple filters with a space.

Each type of filter specification requires a colon (:) in the position as shown here:

To specify a read filter and a matching write filter, enter:

"f|p_filters=read_filter_name[(read_filter_params)]
	:write_filter_name[(write_filter_params)]"

To specify a read filter that has no matching write filter, enter:
```
"f|p_filters=read_filter_name[(read_filter_params)]:"
```
To specify a write filter that has no matching read filter, enter:
```
"f|p_filters=:write_filter_name[(write_filter_params)]"
```

Filters are applied in the following order:

File read filters
Parcel read filters
Parcel write filters
File write filters

Read filters of the same type (file or parcel) are applied in the same order that they are specified on the command line. Write filters of the same type are applied in the reverse order that they are specified on the command line.

Default: Binary read and binary write filters

Example: The following command applies the specified filters in the following order:

Binary read parcel filter
Huffman compression parcel filter
Huffman decompression parcel filter

Binary write parcel filter

dtscli -a "ipath=ukwigp3n::c:\temp\getstart.pdf"

	"rpath=ukwigp3n::c:\temp\getstart2.pdf" 
	"p_filters=BINARY_READ:BINARY_WRITE HUFFMAN_COMPRESS:HUFFMAN_UNCOMPRESS"

In this example, none of the filters have parameters.

Note: Each transfer must have either the text filters or the binary filters attached. If you specify any filters, the binary filters are not applied by default; therefore, you must specify either the text or binary filters explicitly in the same command.

label=label

(Optional) Specifies the label for the transfer you are creating. To assign a label, use the label=label operand and supply a non-numeric value, preferably a logical, simple name. You can specify a label only at object creation time, when you enter the dtscli command that creates the object.

Using a label provides an alias, an alternate means besides the object ID for identifying one or more objects. If desired, you can give two or more objects the same label, so that you can apply the same method to all of those objects in a single command, by specifying a single label value instead of multiple object ID values.

A label used in this way is a two-step process:

Create each object, using the label=label operand to specify the same label for each object. (As a result, each object has a unique object ID but the same label.)
To apply the desired method to all of the objects, specify id=label instead of the "id=id1 id2 id3..." expression.

Default: None

Examples:

This example creates three transfers that have the same label (stats):

dtscli -t "ipath=nnwigp4h::c:\pics\large1.bmp" "rpath=sswigp55::c:\pics\large1.bmp" label=stats
	-t "ipath=nnwigp4h::c:\pics\large2.bmp" "rpath=sswigp55::c:\pics\large2.bmp" label=stats
	-t "ipath=nnwigp4h::c:\pics\large3.bmp" "rpath=sswigp55::c:\pics\large3.bmp" 
		label=stats -mode defer

This example deletes all three transfers:
```
dtscli -t id=stats method=delete
```

Note: This technique of specifying the same label and applying the same method to a group of objects applies to transfers, transfer jobs, and schedules.

method=create|delete|status

(Optional) Specifies the method to be applied to the transfer. The valid values are as follows:

create

Creates a transfer.

delete

Deletes one or more existing transfers. Specify the transfers to be deleted, using the id=object_id operand, in a space-separated list enclosed in quotation marks. Use the following format:

method=delete "id=id1 id2 id3 ... "

status

Displays the status of one or more transfers. Specify the transfers to be checked, using the id=object_id operand, in a space-separated list enclosed in quotation marks. Use the following format:

method=status "id=id1 id2 id3 ... "

The status, or transfer state, of each transfer you specify is returned after the command is executed.

Default: create

Examples:

Delete three transfers whose object IDs are 442, 445, and 554:
```
dtscli -t method=delete "id=442 445 554"
```
Display the status of the same three transfers:
```
dtscli -t method=status "id=442 445 554"
```

"method_parameters=method_parameters"

(Optional) Currently unused. The transfer method parameters are reserved for future use.

Default: None

output_mode=a|c|r|s|w

(Optional) Specifies the output mode. Valid values are as follows:

a: Appends data to an existing file. If the file does not exist, the transfer fails.
c: Creates a new output file. If the file already exists, the transfer fails.
r: Replaces an existing file. If the file does not exist already, the transfer fails.
s: Creates a new output file. If the file already exists, data is added onto the existing file.
w: Creates a new output file. If the file already exists, it is replaced.

Default: w

retry_interval=session_retry_interval

(Optional) Specifies the session retry interval, which is the number of seconds between retries if an attempt to connect to any computer involved in the transfer fails.

Default: 60

retry_limit=session_retry_limit

(Optional) Specifies the session retry limit, which is the number of retries that will be attempted if an attempt to connect to any computer involved in the transfer fails.

Default: 20

"rpath=host::path"

Specifies the output file in the transfer enclosed in quotation marks. The host name is followed by two colons and the full path name of the transfer. For example:

Windows

"rpath=mmmww188::c:\receipts\store888\010398.rcp"

UNIX/Linux

"rpath=uxmnuu18::/home/receipts/store888/010398.rcp"

HTTP Transfers (Internet Downloads)

"rpath=http_host_name::http_source_file_path_name"

Note: The rpath= operand is required.

host

A DTS agent acting as a responder listens for and responds to incoming connections. These incoming connections (incoming data transfers) are initiated by the DTS agent.

path

Specifies the full path name of the output data used by the responder DTS agent.

Note: When using the dtscli command to transfer data from UNIX/Linux to Windows, you must enter two backslashes to delimit each directory and path if the output path is not enclosed in quotation marks.

Examples:

This UNIX/Linux to Windows example encloses the rpath in quotation marks so only a single backslash delimiter is required:
```
dtscli -a|t "ipath=uxmnjj17::/home/receipts/010398.rcp" 
	"rpath=mmmww188::c:\receipts\store888\010398.rcp"
```
This example does not use quotation marks to enclose each input and output path expression, so the double backlashes are required.
```
dtscli -a|t ipath=iuxmnjj17::/home/receipts/010398.rcp 
	rpath=mmmww188::c:\\receipts\\store888\\010398.rcp
```
Note: The requirement for double backslashes to delimit each directory and path applies only to the output path for transfers from UNIX/Linux to Windows.

rpriority=urgent|default|discreet

(Optional) Specifies the transfer priority on the responding computer in the transfer: urgent, default, or discreet, as described following. The transfer priority you specify here works with the transfer priority setting for the initiating computer (ipriority) and the agent DiscreetMode settings (normal or discreet) for the initiating and responding computers in the transfer. (The agent DiscreetMode setting is one of the Data Transport Agent parameters, which can also be set using the DSM Explorer.)

Note: For more information, see the Data Transport Agent Plugin Policy Group topic in the Configuration Policy section of the DSM Explorer Help.

urgent

Receives the transfer in normal mode, even if the agent DiscreetMode setting is Y (for yes) on the responding computer.

default

Receives the transfer in normal mode if the agent DiscreetMode setting is N (for no) on the responding computer. However, if the agent DiscreetMode setting is Y on the responding computer, then the transfer is received in discreet mode.

discreet

Receives the transfer in discreet mode, even if the agent DiscreetMode setting is N on the responding computer.

Default: default

Example: To send (ipriority) and receive a transfer in discreet mode, enter the following command using the default values for the discreet delivery period (delivery) and the discreet expiry period (expiry):

dtscli -a|t "ipath=ukwin4q::c:\winnt\tngdts.ini"

"rpath=philauk::c:\config\ukwinp4q\tngdts.ini"
ipriority=discreet rpriority=discreet

ruser=username::password

(Optional) Specifies the user name and password for the responding computer.

Note: This is a required parameter if the security mode is set to "fail" for the DTS agents involved in the transfer.

Default: None

Example: In the following example, the user specifies the user name and password for both the initiating computer (ipath) and the receiving computer (rpath):

dtacli -a|t "ipath=NYC_HQ::c:\receipts\store888\010398.rcp" iuser=polly::nomial \

"rpath=STORE888::PDEV.RRARI09.RECEIPTS" ruser=redbird::bdfeeder ... \

More information:

dtscli Command—Apply Filters

dtscli Command—Create Transfers

dtscli Command—Use Skip Logic

Transfer States

Agent DiscreetMode and Transfer Priority Settings