Macros are not really a type of host element, but are instead configuration snippets used in source, destination and next action elements to represent dates, times, filenames and task parameters. For example, a task using a macro of "data[yyyy].log" would run against a value of "data2003.log" instead.
Macros can be used in the following places:
Macro keywords are always found in square brackets ("[","]"). Macro arguments (usually a DateSpec or an integer) follow macro keywords after a colon (":").
In some cases, task or global parameters may contain macros. These are still interpreted as macros. For example, if a global parameter named "Error_Subject" is set with a value of "ERROR in '[TaskName]' at [hh]:[mm]:[ss]", a Next Action subject set to "[Parm:Error_Subject]" would be interpreted as "ERROR in 'Get TPS Reports' at 12:34:56" when the task is run.
| Attribute | Description | Applicable Host Types |
| DestFileName | The filename of the most recent destination file, not including any directory names. For example: "report12.txt". This is used primarily in per-file Next Actions. | All |
| DestFolderPath | The folder path, including all folder components but not the filename, of the most recent destination file. For example: "/pub/reports". This is used primarily in per-file Next Actions. | All |
| ErrorCodeFile | The last error code encountered for the current file, or 0 if no error. See "Next Actions" for an example of how to use this macro to report errors. | All |
| ErrorDescriptionFile | The last error description encountered for the current file, or empty if no error. See "Next Actions" for an example of how to use this macro to report errors. | All |
| ErrorCodeTask | The last error code encountered for this task, or 0 if no error. See "Next Actions" for an example of how to use this macro to report errors. | All |
| ErrorDescriptionTask | The last error description encountered for this task, or empty if no error. See "Next Actions" for an example of how to use this macro to report errors. | All |
| FileDateStamp | The date stamp of the file as recorded by the source, in the form YYYY-MM-DD HH:MM:SS. Not all sources provide date stamps. When using this macro in a destination filename or folder name, you will usually want to combine it with macro string functions. For example, "[LEFT([FileDateStamp],10)]" will yield the "YYYY-MM-DD" date part and "[MID([FileDateStamp],12,2)]" will yield the hour from the original source file's date and time information. | Filesystem, FTP (most), MOVEit, SSH |
| FileSize | The size of the file, in bytes, as recorded by the source. Note: some unusual FTP servers do not provide the file size; in these cases, a size of 0 will be used. | Filesystem, FTP (most), MOVEit, SSH |
| FolderID | Unique number identifying a MOVEit folder. For example: "1236518". | MOVEit |
| FolderName | Name of remote folder. Note that this macro returns only the "last" part of the path. Example: Given a full remote path of "frog\dog\cat", this macro returns "cat". | Filesystem, FTP, MOVEit, SSH |
| FullPath | The full path of the file as it was on the source, including all directories and the filename. | Filesystem, FTP, MOVEit, SSH |
| ID | Unique number identifying a MOVEit file. For example: "251660214". | MOVEit |
| NominalStart | Time this task was "officially" started in "YYYY-MM-DD HH:MM:SS" format (e.g., "2006-07-18 11:33:16"). This value combined with the TaskID will yield a key that uniquely identifies a single task run (e.g., in the "stats" database table). | All |
| OrigComment | The upload comment specified when the file was uploaded. (This is often blank.) | MOVEit |
| OrigName | Original name of this file. Example: "Example.txt" | Filesystem, FTP, MOVEit, SSH |
| OrigUser | The username of the user who uploaded the file | MOVEit |
| OrigUserEmail | The email address of the user who uploaded the file | MOVEit, POP3 |
| OrigUserFull | The full name of the user who uploaded the file | MOVEit |
| OrigUserID | The UserID of the user who uploaded the file, if the MOVEit DMZ host is version 5.5 or later. If the MOVEit DMZ host is an earlier version, this will be the empty string. (The UserID is typically a long string starting with the username; a typical UserID might be "fred9zyupmuxa6dk".) | MOVEit |
| OnlyName | The original filename minus the extension and the period. Example: Given "frog.txt", this macro returns "frog". | Filesystem, FTP, MOVEit, SSH |
| OnlyExt | The original filename extension. Example: Given "frog.txt", this macro returns "txt". | Filesystem, FTP, MOVEit, SSH |
| Parm:ParmName | Returns the task parameter named ParmName. If there is no such parameter, the empty string is returned. | All |
| RelativePath | The pathname of the directory for this file, relative to the originally specified source path. This applies only when Include Subdirectories is selected, and cannot be used for source paths. For instance, if the source path is C:\outgoing and the file in question is C:\outgoing\reports\Fred.txt, then when used in a destination path, [RelativePath] is "reports". | Filesystem, FTP, MOVEit, SSH |
| Rnd | A random decimal number. Use the format [Rnd:len] where len is the desired number of digits. The random number generator is of cryptographic quality. | All |
| SyncReport() | Synchronization tasks offer a special "[SyncReport()]" macro that allows a complete report of all synchronization actions to be sent in a Next Action email notification. Please see the Synchronization - Next Actions documentation for more information. | Next Actions Following Sync Tasks |
| TaskID | The ID of the task that is running. This number is used internally in the configuration files and the database to identify tasks. A typical value would be a nine-digit number such as "618116254". | All |
| TaskName | The name of the task that is running | All |
| TaskStatus | The status of the task that is running. This string will have one of three values: "Success" if the task encountered no errors and processed at least one file or ran at least one script, "Failure" if the task encountered one or more errors, or "No xfers" if the task encountered no errors but did not process any files or run any scripts. | All |
| Date specification (see below) | Current date and time. Example: Given a time of "10:06" and a macro of "[HH][TT]", the macro will return "1006". | Filesystem, FTP, MOVEit, SSH |
| Macro function (see below) |
Returns the results of a string operation | All |
Examples: (Given "January 3, 2002 13:11:01", original filename="myfile.txt")
The Macro Date and Time Syntax allows operators to specify how date and time elements should be represented in their filenames and messages. The different types of date/time elements supported include day-of-week, day-of-month, day-of-year (aka "Julian"), hour, minute, second, month, week-of-year and year.
Operators such as the minus sign normally apply to all times and dates in a macro phrase. To apply operators to only part of a macro phrase, use double-quotes to delimit phrases. For example, if today is currently July 5, 2007, a macro of:
| Attribute | Description |
| A | DAY-OF-WEEK; minimal numeric. Example: "2" (Sunday=0) |
| AAA | DAY-OF-WEEK; three-letter abbreviation. Example: "Tue" |
| AAAA | DAY-OF-WEEK; full. Example: "Tuesday" |
| B | DAY-OF-WEEK; minimal numeric. Example: "2" (Sunday=1) |
| D | DAY-OF-MONTH; minimal representation. Example: "7" |
| DD | DAY-OF-MONTH; two-digit representation. Example: "07" |
| H | HOUR; minimal representation, 24-hour clock. Example: "7" |
| HH | HOUR; two-digit representation, 24-hour clock. Example: "07" |
| HHH | HOUR; minimal representation, 12-hour clock. Example: "7" |
| HHHH | HOUR; two-digit representation, 12-hour clock. Example: "07" |
| II | am/pm; two-digit representation of "am" or "pm" designation. Example: "pm" |
| J | JULIAN DATE; minimal representation. Example: "7" First day of year is 0. |
| JJJ | JULIAN DATE; three-digit representation. Example: "007" First day of year is 0. |
| K | JULIAN DATE; minimal representation. Example: "7" First day of year is 1. |
| KKK | JULIAN DATE; three-digit representation. Example: "007" First day of year is 1. |
| M | MONTH; minimal numeric representation. Example: "7" First month is 1. |
| MM | MONTH; two-digit numeric representation. Example: "07" First month is 1. |
| MMM | MONTH; short representation. Example: "Jan" |
| MMMM | MONTH; full representation. Example: "January" |
| S | SECOND; minimal representation. Example: "7" |
| SS | SECOND; two-digit representation. Example: "07" |
| T | MINUTE; minimal representation. Example: "7" |
| TT | MINUTE; two-digit representation. Example: "07" |
| W | WEEK-OF-YEAR; minimal representation. First week is numbered 0. Example: "2" |
| WW | WEEK-OF-YEAR; two-digit representation. First week is numbered 0. Example: "02" |
| X | WEEK-OF-YEAR; minimal representation. First week is numbered 1. Example: "2" |
| XX | WEEK-OF-YEAR; two-digit representation. First week is numbered 1. Example: "02" |
| YY | YEAR; two-digit representation. Example: "02" |
| YYYY | YEAR; four-digit representation. Example: "2002" |
| + | The "+" symbol following any date designation will increment the current date by one unit of time, namely amount of time implied by the designation. The entire date is affected, with rollover from day-to-day, month-to-month, year-to-year, etc. as required. A + after a day designation increments the date by one day; a + after a month designation increments the date by one month, etc. For instance, on June 30, 2003, "[MMM] [DD], [YYYY]" is rendered "Jun 30, 2003", but "[MMM] [DD+], [YYYY]" is rendered "Jul 1, 2003". |
| - | The "-" symbol following any date designation will decrement the current date by one unit of time, namely the amount of time implied by the designation. The entire date is affected, as with "+". Hence, [MMM-] decrements the date by one month, etc. |
Macro functions are built-in functions that perform string operations on their arguments. These functions are patterned after the identically-named functions in Basic. Macro function references must start with a [, then the name of the function, then a (.
| Function name | Description |
| LEFT(arg, count) | Returns the leftmost "count" characters of "arg". If arg is less than count characters long, the entire string is returned. |
| LEN(arg) | Returns the number of characters in "arg", as a decimal number. |
| MID(arg, start, count) | Returns "count" characters from "arg", starting at position "start" (where 1 is the first character). If ", count" is omitted, then the function returns the characters starting at "start" and going through the end of "arg". For example, if the original filename is ABCDE.TXT, then the value of the macro [MID([OrigName], 2, 3)] is BCD and the value of [MID([OrigName],2)] is BCDE.TXT. |
| RIGHT(arg, count) | Returns the rightmost "count" characters of "arg". If arg is less than count characters long, the entire string is returned. |