Specifying a parameter list for a macro

What is a parameter list?

Some macros allow you to specify a parameter list when you play the macro. The parameter list can be required or optional.

A parameter list is a set of values that tell the macro how to perform its work. For example, a macro named FileDownload could expect you to specify a parameter list containing the following two values:

• A remote file name (the name of the file to be downloaded from a remote host), such as NewData.123; and
• A local file name (the name to give to this file after it is downloaded), such as MyData.123.

Depending on the macro, you could specify the parameter list as follows:

  strRemoteFile="NewData.123", strLocalFile="MyData.123"

What parameters should you specify?

Each macro's parameter list is different. Either your system administrator or the author of the macro should provide you with instructions and examples for specifying the parameter list.

You can check the macro's Description field to see if it contains a description of a parameter list. To check the macro's Description field, open the Macro Properties window from one of the following windows:

• The Available macros window ( Properties)
• The Play macro window ( Properties)

The format of a parameter list

This section briefly describes the format of a parameter list. For more detailed information see Format of a parameter list in the Macro Programming Guide (primarily for system administrators and macro writers).

The pattern of a parameter list for a macro is:

  name1="value1", name2="value2", name3="value3", ...

For example,

  strRemoteFile="NewData.123", strLocalFile="MyData.123"

Format rules:

• Parameter list

  A parameter list is a series of name-value pairs. You can specify any number of pairs, so long as each pair refers to an actual variable defined in the macro. Use either a blank space, a comma, or both to separate one name-value pair from the next. In the example above, there are two name-value pairs:

  • strRemoteFile="NewData.123" is the first name-value pair.
  • strLocalFile="MyData.123" is the second name-value pair.
  Also in the example above, a comma and space ( , ) after the first name-value pair separate it from the second name-value pair.

• Name-value pairs

  Each name-value pair consists of:

  • The name of a variable that is already defined in the macro (such as strRemoteFile in the first name-value pair in the example above); followed by
  • An equals sign ( =); followed by
  • An initial value for the variable, enclosed in quotes ( "NewData.123" in the first name-value pair in the example above.)

• Variable name

  Spell the variable name exactly as it is spelled in the macro, for example strRemoteFile. The variable must be a variable belonging to a standard data type (integer, double, string, or boolean). You cannot specify a variable belonging to an imported type.

• Equals sign ( =)

  An equals sign is required between the variable name and the value.

• Variable value

  The variable value must be enclosed in double quotes ( ""), for example "NewData.123". The value must be a simple value, not an expression.

  Rules for string variables:

  • Do not also enclose the string in single quotes. Wrong: "'123 Elm Street'". Right: "123 Elm Street".
  • To specify an empty string use two double quotes with nothing between them ( "" ).
  • Escape sequences:
    • To specify a single quote ( ' ), use \'. Example: "John\'s Business Plan"
    • To specify a backslash ( \ ), use \\. Example: "c:\\Documents and Settings"

  Example with a name-value pair from each standard data type: intLineCount="24", dblLength="1441.25", strName="John Smith", boolComplete="true"

Related topics