Using macro variables

Types of macro variables

Macro variables are classified in one of three ways:

• Reserved Macro Variables: Variables that are predefined within the VersaLex product. See the table below.
• Custom Directory Macro Variables: Directory variables that are defined by the VersaLex user. You use directory macro variables to specify host directories. See Specifying default host directories.
• Custom Macro Variables Defined as System Properties: Variables that are defined as name=value pairs using the Java –D Command Line parameters (see Bootstrap configuration for further information) or are specified in the conf/system.properties file. Note that Custom Macro Variables are resolved after Reserved Macro and Custom Directory Macro Variables and therefore cannot be used to override those variables.

Using system.properties Variables

It is possible to add general variables to the conf/system.properties file and use them within the contexts outlined in the table. To add a general variable to conf/system.properties, the syntax is: varName=replacementText. For example, if conf/system.properties has the following: myvar=hello, the usage would be %myvar% in the desired location.

Context Definitions

Macro variables are valid in certain contexts. The following describes the various contexts in which macro variables are valid. Not all macro variables are valid in all contexts.

Source File

Applies to the “source” values of LCOPY, LDELETE, LREPLACE, PUT, and CHECK commands (Cleo Harmony and Cleo VLTrader applications only).  Macros are supported for the “source” values of the GET commands for FTP, SFTP and HTTP(s) protocols only.  Macros are not supported for the “source” values of GET commands for other protocols or the DIR command.

Destination File

Applies to the “destination” values of LCOPY, PUT, GET, and CHECK commands (Cleo Harmony and Cleo VLTrader applications only).  It also applies to default file names, as specified under the host AS2 tab (see AS2 Host: AS2 Tab), the host AS4 tab (see AS4 Host: AS4 Tab), the host ebXML tab (see ebXML Host: ebXML Tab), the host EBICS tab (see EBICS Host: EBICS Tab), and the Local HTTP Users HTTP tab (see Configuring access for HTTP host users). It also applies to the file destination, as specified under the host OFTP tab (see OFTP Host: OFTP Tab).  The Destination File context also applies to macros that can be included within HTTP parameter/header values, as defined under the HTTP tabs for HTTP-based protocols (for example, AS2, ebXML). Also, this context applies to the FileFormat parameter on EBICS GET command. See EBICS Command Reference. The Destination File context macro variables may also be used within the Subject header of the SMTP tab.

SYSTEM Command

Applies to the SYSTEM command that can be run within the host actions (see Using operating system commands in actions).

Default Directories

Applies to the default inbox/outbox/sentbox/receivedbox, as specified under the host General tabs (for an example, see FTP Configuration).  The %host% macro variable is supported, but not %mailbox%.

In addition, the %date% macro is supported, but the %time% macro is not. Be careful using the %date% macro in the default outbox because files in the date-stamped outbox subdirectory will not be sent if the send action occurs after midnight. Likewise, archiving entries in sentbox and receivedbox date-stamped directories will only occur for the current date.

Default Local User Archive Directories

Applies to the sentbox and receivedbox archive directories as specified under the local user host General tabs (for an example, refer to Configuring local FTP users).  Both the %host% and %mailbox% macro variables are supported in this context.

In addition, the %date% macro is supported, but the %time% macro is not. Be advised that archiving entries in sentbox archive and receivedbox archive date-stamped directories will only occur for the current date.

Default Root Directory

Applies to the default root directory, as specified under the local user FTP tab, HTTP tab, and SSH FTP tab (for an example, refer to Configuring local FTP users). It also applies to the user home directory, as specified under the local user mailbox FTP tab, HTTP tab, and SSH FTP tab (for an example, see FTP Mailbox: FTP Tab).

Windows/Unix Folders

Applies to the UNC paths specified when you set up Windows/Unix folder access. See CIFS directories. Macros used in this context should always be UNC paths starting with two backslashes (\\). No other macros are supported within macros used in this context.

Custom Variables

Applies to the values that can be specified under custom directory variables on the General tab under Configure System Options. See Other system options for more information.

Execute-On

Applies to the system commands that can be specified within the Execute On Successful Send/Receive/Copy/Check properties and the Execute On Fail property (system, host, or action level). See Advanced system options for information about the Advanced tab under Configure System Options for definitions of these properties. With regard to Execute On Fail command, when a command is executed as a result of a failed transfer (either on the client or the server), then all applicable macros are supported. When a command is executed as a result of a general system failure, then only %date%, %time% and %status% are supported. 

Post/Pre Command

Applies to the FTP properties Post Get Command, Post Put Command, Pre Get Command, and Pre Put Command, as specified under the FTP Host: Advanced Tab.  This context also applies to the Post Put Command and Pre Put Command properties as defined in the SSH FTP Host: Advanced Tab.

LCOPY Archive

Applies to the archive directory that can be specified with the LCOPY Archive property (system, host, or action level). See Advanced system options for more information.

Accessible through API

Applies to macros that are available through IactionController interface of the API (if the API is licensed).  Refer to the API javadocs for a description of this interface and the method that can be used to obtain a given macro value.

Directories Only

Applies in several places where only the custom directories macros or %inbox%/%outbox% are appropriate.

Banner/Welcome Message

Applies to the banner and/or welcome messages for the HTTP, FTP, SMTP, and SSH FTP servers. See Configuring Local Listener Responses.

Rules Regarding Macro Variable Use

Below are some general rules for macro variable use.  

1. Macros are identified by %c%, where c is one-to-many characters.
2. Macro variables are case insensitive. You can enter them in lowercase or uppercase.
3. You cannot place a % within a macro variable.
4. When a string contains macros to be resolved and a % that is not tied to a macro, you must escape the non-macro % with %%. After all macro substitution takes place, the software strips the extra %, yielding the intended character sequence. For example, LCOPY test.edi %%%date%_%index% is resolved to %20090714_01.
5. The * and ? characters are not allowed within a macro name. Use other special characters with caution.
6. When using the %date% and %time% macros, it is your responsibility to ensure the formats for the date and time do not violate any file system naming conventions, for example, if the macros are being used to build a filename or directory.
7. Macros are not allowed within a source filename that contains a *, ?, or regular expression. For example, in LCOPY inbox/%mailbox%*, %mailbox% is not resolved. However, in LCOPY inbox/%mailbox%/*, %mailbox% is resolved because it is referenced in the source directory path and not the source filename.
8. You can use macros multiple times within the same command. For %date%, %time% and %index%, the same substitution value is used in all references within the same command. However, when you use either of these macros within the destination path of an LCOPY, and multiple files are being copied in one command, the following special rules are enforced:
   1. If these macros are used anywhere within the directory path, they are only resolved once within command.
   2. If these macors are used within the file token, they are resolved for each filename.
9. Macros you use within a system command, either within the SYSTEM Command context or within the Execute-On context, can be used as part of the actual command or as parameters to a batch file.
10. If the absolute path of the any of the files referenced in the macros contain embedded spaces (for example., %file% resolves to Program Files\LexiCom\inbox\testHost\test.edi) it might be necessary to add double quotes to the macro specification(s) in the command in order for the command to be properly processed by the operating system. For example, copy “%file%” “%file%.bad”.
11. Special rules apply to using directory macro variables for example, %inbox%, %outbox%, and custom directory variables.
    • If you use these macros in a source file, destination file, custom directory variable definition, or an LCOPY Archive context, and the path is a non-URI path, they are replaced only at the beginning of the string. For all other contexts (for example, URI source/destination paths, SYSTEM commands), they are replaced anywhere in the string.
    • Although allowed, you should not use directory macros should within a remote destination file context, as they reference local directory paths and are therefore nonsensical in this context.
    • When preceding a path with a directory macro, you should place a file separator character (for example, ‘/’or ‘\’ between the macro and the subsequent path (for example, %inbox%/test.edi).
    • When using directory macros, care should be used so as not to create circular references (for example, host outbox references %CustomVar% and %CustomVar% references %outbox%).
12. All directory macro variables reference their absolute paths.

Reserved Macro Variables

Below is the table of all reserved macro variables.  

Formatting %date% and %time% Macros

The default %date% setting is yyyyMMdd and the default %time% setting is HHmmssSSS.

To specify a different %date% or %time% format, use a pattern string in the 'Macro Date Format' and 'Macro Time Format' setting (system, host, or action level).  See Advanced system options for information about the Advanced tab under Configure System Options for definitions of these properties.  Formats may also be specified as part of the macro definition, e.g., %date,MacroDateFormat=yyyyMMdd% and %time,MacroTimeFormat=HHmmssSSS%

 In the pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text.  For instance, characters like '.', '#' and '@' will appear in the resulting date or time text even if they are not embraced within single quotes.

Examples Using Pattern Strings:

Macro Variable Usage Examples

Destination File Examples:

Source File Examples:

Execute-On Examples:

After successful execution of 'LCOPY test.edi test2.edi':

Default Host Directory Examples:

Assume the system-level inbox is 'myInbox\' and the custom directory variable, '%custom1%', is set to '\\filsvr01\serverInbox\'.