# Macros

## tecplot.macro

## macro.execute_command()

tecplot.macro.execute_command(command)

  Runs a series of tecplot macro commands.

  Parameters:

    command (`str`) – The macro commands to be run.

  Warning

  Zero-based Indexing

  It is important to know that all indexing in PyTecplot scripts are zero-based. This is a departure from the macro language which is one-based. This is to keep with the expectations when working in the python language. However, PyTecplot does not modify strings that are passed to the Tecplot Engine. This means that one-based indexing should be used when running macro commands from python or when using `execute_equation()`.

  This command splits the input into individual commands and runs them one at a time. See the Tecplot Macro Scripting Guide for details about Tecplot 360’s macro language.

  Warning

  The $!VARSET command is not supported. Tecplot Macro variables should be converted to Python variables.

  Warning

  Intrinsic variables (that is, variables with pipes such as `|DATASETFNAME|`) are not supported. If you need to use an intrinsic variable in the macro command, add the macro command to a text file and call `execute_file`.

  See the Tecplot Macro Scripting Guide for more information about raw data and intrinsic variables.

  The following command will perform the same operations as the Hello, World! example:

      >>> tecplot.macro.execute_command(r'''
      ...   $!ATTACHTEXT
      ...     ANCHORPOS { X = 35 Y = 50 }
      ...     TEXTSHAPE { HEIGHT = 35 }
      ...     TEXT = 'Hello, World!'
      ...   $!EXPORTSETUP EXPORTFNAME = 'hello_world.png'
      ...   $!EXPORT
      ...     EXPORTREGION = CURRENTFRAME
      ... ''')

## macro.execute_extended_command()

tecplot.macro.execute_extended_command(command_processor_id, command, raw_data=None)

  Runs a tecplot macro command defined in an addon.

  Parameters:

    - command_processor_id (`str`) –

      A unique string used to determine the API to call when an extended macro command is processed. API’s are provided by add-ons or applications that extend the Tecplot macro language.

      Typically this will be the name of an add-on or application, followed by a version number. For example: ‘CFDAnalyzer4’.

      Each application or add-on may provide one or more unique command processor ID strings corresponding to different API’s, or different versions of an API.

      For example, a file converter add-on responsible for converting DXF files for Tecplot might provide two versions of an API: “DXFCONVERTTOOL-1.2”, and “DXFCONVERTTOOL-2.0”. In that case either of these strings would be passed in the command_processor_id parameter to indicate the version of the API to use.

    - command (`str`) – The command to run.

    - raw_data (`str`) – Raw data required for the command, if any (default: `None`).

  Warning

  Zero-based Indexing

  It is important to know that all indexing in PyTecplot scripts are zero-based. This is a departure from the macro language which is one-based. This is to keep with the expectations when working in the python language. However, PyTecplot does not modify strings that are passed to the Tecplot Engine. This means that one-based indexing should be used when running macro commands from python or when using `execute_equation()`.

  In general, the command string is formatted prior to being fed into the Tecplot Engine so liberal use of whitespace, including new-lines, are acceptable.

  Example:

      >>> tecplot.macro.execute_extended_command(
      ...     'Multi Frame Manager',
      ...     'TILEFRAMESSQUARE')

## macro.execute_file()

tecplot.macro.execute_file(filename)

  Run a macro file.

  Parameters:

    filename (`str`) – The file to be run. (See note below concerning absolute and relative paths.)

  Warning

  Zero-based Indexing

  It is important to know that all indexing in PyTecplot scripts are zero-based. This is a departure from the macro language which is one-based. This is to keep with the expectations when working in the python language. However, PyTecplot does not modify strings that are passed to the Tecplot Engine. This means that one-based indexing should be used when running macro commands from python or when using `execute_equation()`.

  Note

  Absolute and relative paths with PyTecplot

  Relative paths, when used within the PyTecplot API are always from Python’s current working directory which can be obtained by calling `os.getcwd()`. This is true for batch and `connected` modes. One exception to this is paths within a macro command or file which will be relative to the Tecplot Engine’s home directory, which is typically the Tecplot 360 installation directory. Finally, when connected to a remote (non-local) instance of Tecplot 360, only absolute paths are allowed.

  Note that backslashes must be escaped which is especially important for windows paths such as `"C:\\Users"` or `"\\\\server\\path"` which will resolve to `"C:\Users"` and `"\\server\path"` respectively. Alternatively, one may use Python’s raw strings: `r"C:\Users"` and `r"\\server\path"`

  Example:

      >>> tecplot.macro.execute_file('/path/to/macro_file.mcr')

## macro.execute_function()

tecplot.macro.execute_function(name, parameters=None)

  Runs a macro function.

  Parameters:

    - name – (`str`): Name of the macro function to run. This name is not case sensitive. Must be a non-zero length `str`.

    - parameters – (`str`): Any parameters which the quick macro requires. Pass `None` (default) for macro functions which require no parameters. The parameters are passed as a string which includes the parenthesis. For example, if the macro function takes a string parameter and int parameter, pass ‘(“string_parameter_name”, 2)’ Default: `None`

  Macro functions must be defined before they are used. Typically they are defined in the ‘tecplot.mcr’ configuration file which is read when Tecplot Engine is initialized. Macro functions may also be available in the Quick Macro Panel when the Tecplot 360 GUI is running.

  Note

  See the Tecplot Macro Scripting Guide for more information about macro functions.

  Run the “Tile Frames” macro functions. This macro function is defined in the file “tecplot.mcr”, which is located in the Tecplot 360 installation directory:

      >>> tecplot.macro.execute_function('Tile Frames')

  Run a macro function named “Calculate” which takes no parameters and another macro function called “Display” which takes the name of a layout file and an integer as parameters:

      >>> tp.macro.execute_function('Calculate')
      >>> tp.macro.execute_function('Display', '("contour.lay", 2)')