OpenR66-TaskOptions

Please note: All new versions will be located at GitHub under Waarp new project name :

http://waarp.github.com/Waarp/

The project still remains Open Source under GPL V3.

We focus here on the several tasks that are possible to run before a transfer starts (pre action), after a transfer is finished correctly (post action) or after an error occurs (either in pre or post action or during transfer: error action).

Those actions are defined in one rule. Each rule contains 2 parts:

Sender actions: A host is a Sender if it is the requester on a SEND rule or if it is the requested on a RECV rule.
Receiver actions: A host is a Sender if it is the requester on a RECV rule or if it is the requested on a SEND rule.

Each action could be on pre, post or error step, each step can have several actions.

It is defined with a unified form of XML:

<tasks>

<task>

</task>

<task>

</task>

</tasks>

Type is the type of task to execute (see below the supported types)
Path is a fixed argument for the task to execute. On this argument, string replacements are done when the following patterns are found:
- #TRUEFULLPATH# : Current full path of current FILENAME
- #TRUEFILENAME# : Current FILENAME (basename) (change in retrieval part)
- #ORIGINALFULLPATH# : Original full path FILENAME (before changing in retrieval part)
- #ORIGINALFILENAME# : Original FILENAME (basename) (before changing in retrieval part)
- #FILESIZE# : File size if it exists
- #INPATH# : In (Receive) path
- #OUTPATH# : Out (Send) path
- #WORKPATH# : Working (while receiving) path
- #ARCHPATH# : Archive path (for export Log)
- #HOMEPATH# : Home path (to enable for instance relative path commands)
- #RULE# : Rule used during transfer
- #DATE# : Current Date in yyyyMMdd format
- #HOUR# : Current Hour in HHmmss format
- #REMOTEHOST# : Remote host id (if not the initiator of the call)
- #REMOTEHOSTIP# : Remote host IP (if not the initiator of the call)
- #LOCALHOST# : Local host Id
- #LOCALHOSTIP# : Local host IP
- #TRANSFERID# : Transfer Id
- #REQUESTERHOST# : Requester host Id
- #REQUESTEDHOST# : Requested host Id
- #FULLTRANSFERID# : Full Transfer Id as TRANSFERID_REQUESTERHOST_REQUESTEDHOST
- #RANKTRANSFER# : Current or final RANK of block
- #BLOCKSIZE# : Block size used
- #ERRORMSG# : The current error message or NoError if no error occurs until this call
- #ERRORCODE# : The current error code or '-' (Unknown) if no error occurs until this call
- #ERRORSTRCODE# : The current error code message or "Unknown" if no error occurs until this call
- #NOWAIT# : Used by Exec type task to specify that the command will be executed in asynchronous mode, without waiting any result from it
- #LOCALEXEC# : Used by Exec type task to specify that the command will be executed not locally (within the JVM) but outside using a LocalExec Daemon (specified in the global configuration)
Delay is generally the delay (if any) for execution before the execution becomes out of time.
Additionnaly, a task will use also the argument from the transfer itself (Transfer Information).

Each action is of one of the following items:

LOG

This task logs or writes to an external file some info:

if delay is 0, no echo at all will be done

if delay is 1, will echo some information in the normal log

if delay is 2, will echo some information in the file (last deduced argument will be the full path for the file output)

if delay is 3, will echo both in the normal log and in the file (last deduced argument will be the full path for the file output)

MOVE

Move the file to the path designed by Path and Transfer Information arguments without renaming the filename (same basename).

After Path is transformed according to above dynamic replacements, it is then used as a String Format where Transfer Information is used as input (String.format(Path,Info)).

Delay is ignored.

The file is marked as moved.

MOVERENAME

Move the file to the path designed by Path and Transfer Information arguments.

After Path is transformed according to above dynamic replacements, it is then used as a String Format where Transfer Information is used as input (String.format(Path,Info)).

Delay is ignored.

The file is marked as moved.

COPY

Copy the file to the path designed by Path argument without renaming the filename (same basename).

Delay and Transfer Information are ignored.

The file is not marked as moved.

COPYRENAME

Copy the file to the path designed by Path and Transfer Information arguments.

After Path is transformed according to above dynamic replacements, it is then used as a String Format where Transfer Information is used as input (String.format(Path,Info)).

Delay is ignored.

The file is not marked as moved.

EXEC

Execute an external command given by Path and Transfer Information arguments.

The Delay is the maximum amount of time in milliseconds before the task should be considered as over time and so in error.

The command path is obtained from Path transformed according to above dynamic replacements, and after a String Format where Transfer Information is used as input (String.format(Path,Info)).

The file is not marked as moved.

The external command is supposed to behave as the following for its exiting value:

exit 0, for a correct execution

exit 1, for a warned execution (but however correct)

other exit values for a failed execution

EXECMOVE

Execute an external command given by Path and Transfer Information arguments.

The Delay is the maximum amount of time in milliseconds before the task should be considered as over time and so in error.

The command path is obtained from Path transformed according to above dynamic replacements, and after a String Format where Transfer Information is used as input (String.format(Path,Info)).

The last line returned by the external command is interpreted as the new full file path. The external command is responsible to really move the previous file to the new one.

The file is marked as moved.

The external command is supposed to to behave as the following for its exiting value:

exit 0, for a correct execution

exit 1, for a warned execution (but however correct)

other exit values for a failed execution

EXECOUTPUT

Execute an external command given by Path and Transfer Information arguments.

The Delay is the maximum amount of time in milliseconds before the task should be considered as over time and so in error.

The command path is obtained from Path transformed according to above dynamic replacements, and after a String Format where Transfer Information is used as input (String.format(Path,Info)).

All lines returned by the external command (normal output) is interpreted as the possible error message in case of error.

The file is not marked as moved.

The external command is supposed to to behave as the following for its exiting value:

exit 0, for a correct execution

exit 1, for a warned execution (but however correct)

other exit values for a failed execution, for which the output (stdout) lines are used as error message, bring back to the remote host as #ERRORMSG# and #ERRORCODE# / #ERRORSTRCODE#

EXECJAVA

Execute an external Java class given by Path and Transfer Information arguments.

The Delay is the maximum amount of time in milliseconds before the task should be considered as over time and so in error.

The class name (which must implement R66Runnable) is obtained from Path transformed according to above dynamic replacements, and after a String Format where Transfer Information is used as input (String.format(Path,Info)). The first argument is this full classname. The allocation must be of the form new MyClass(), so an empty constructor.

The file is not marked as moved.

TRANSFER

Submit a new transfer based on the Path and Transfer Information arguments.

The transfer arguments are obtained from Path transformed according to above dynamic replacements, it is then used as a String Format where Transfer Information is used as input (String.format(Path,Info)).

The result should be as r66send command except "-info" must be the last field:

"-file filepath -to requestedHost -rule rule [-md5] [-start yyyyMMddHHmmss or -delay (delay or +delay)] -info transferInformation"

where each field is separated by blank character. Last field (transferInformation) may contain however blank character.

Delay is ignored.

The file is not marked as moved.

VALIDFILEPATH

Test if the current file is under one of the paths based on the Path and Transfer Information arguments.

The paths arguments are obtained from Path transformed according to above dynamic replacements, it is then used as a String Format where Transfer Information is used as input (String.format(Path,Info)).

The result should be as: "path1 path2 ..." where each path is separated by blank character.

If Delay is not 0, a log is printed out.

The file is not marked as moved.

DELETE

This task deletes the current file.

The current file is no more valid.

No arguments are taken into account.

LINKRENAME

Create a link of the current file and make the file pointing to it.

The link first tries to be a hard link, then a soft link, and if it is really not possible (not supported by the filesystem), it does a copy and rename task.

After Path is transformed according to above dynamic replacements, it is then used as a String Format where Transfer Information is used as input (String.format(Path,Info)).

Delay is ignored.

The file is not marked as moved.

RESCHEDULE

Reschedule Transfer task to a time delayed by the specified number of milliseconds, if the error code is one of the specified codes and the optional intervals of date are compatible with the new time schedule

Result of arguments will be as following options (the two first are mandatory):

"-delay ms" where ms is the added number of ms on current time before retry on schedule

"-case errorCode,errorCode,..." where errorCode is one of the following error of the current transfer (either literal or code in 1 character):
ConnectionImpossible(C), ServerOverloaded(l), BadAuthent(A), ExternalOp(E), TransferError(T), MD5Error(M), Disconnection(D), RemoteShutdown(r), FinalOp(F), Unimplemented(U), Shutdown(S), RemoteError(R), Internal(I), StoppedTransfer(H), CanceledTransfer(K), Warning(W), Unknown(-), QueryAlreadyFinished(Q), QueryStillRunning(s), NotKnownHost(N), QueryRemotelyUnknown(u), FileNotFound(f), CommandNotFound(c), PassThroughMode(p)
"-between start;end" and/or "-notbetween start;end" (multiple times are allowed, start or end can be not set) and where start and stop are in the following format:
Yn:Mn:Dn:Hn:mn:Sn where n is a number for each time specification, each specification is optional, as Y=Year, M=Month, D=Day, H=Hour, m=minute, s=second.
Format can be X+n, X-n, X=n or Xn where X+-n means adding/subtracting n to current date value, while X=n or Xn means setting exact value
If one time specification is not set, it is based on the current date.

If "-notbetween" is specified, the planned date must not be in the area.
If "-between" is specified, the planned date must be found in any such specified areas (could be in any of the occurrence). If not specified, it only depends on "-notbetween".
If none is specified, the planned date is always valid.

Note that if a previous called to a reschedule was done for this attempt and was successful, the following calls will be ignored.

In case start > end, end will be +1 day
In case start and end < current planned date, both will have +1 day.

Example:

"-delay 3600000 -case ConnectionImpossible,ServerOverloaded,Shutdown -notbetween H7:m0:S0;H19:m0:S0 -notbetween H1:m0:S0;H=3:m0:S0"
means retry in case of error during initialization of connection in 1 hour if not between 7AM to 7PM and not between 1AM to 3AM.

TAR

Create a TAR from the argument as source and destination or UNTAR files from a TAR file.

After Path is transformed according to above dynamic replacements, it is then used as a String Format where Transfer Information is used as input (String.format(Path,Info)).

Delay of 1 = UNTAR PATH="sourceFile targetDirectory"

Delay of 2 = TAR PATH="targetFile sourceDirectory"

Delay of 3 = TAR PATH="targetFile sourceFile1 sourceFile2..."

The current file is not touched.

ZIP

Create a ZIP from the argument as source and destination or UNZIP files from a ZIP file.

After Path is transformed according to above dynamic replacements, it is then used as a String Format where Transfer Information is used as input (String.format(Path,Info)).

Delay of 1 = UNZIP PATH="sourceFile targetDirectory"

Delay of 2 = ZIP PATH="targetFile sourceDirectory"

Delay of 3 = ZIP PATH="targetFile sourceFile1 sourceFile2..."

The current file is not touched.

Example:

<tasks>

<task>

<path>/pathout/</path>

<comment>move the file to /pathout/#TRUEFILENAME#</comment>

</task>

<task>

<path>#HOMEPATH#/pathexec/monscript #TRUEFULLPATH# #ORIGINALFILENAME# #FILESIZE# #RULE# %s %d #REMOTEHOST#</path>

<comment>information passed by transfer is "a_string_without_blank a_number" and replaced respectively in %s and %d</comment>

<comment>maximum 30 seconds to execute this script</comment>

</task>

</tasks>