Using the Naming Macros

Automator offers a number of naming macros that can be used to name files and tables that are being exported, moved, copied and so on. They can also be used to add information when performing distributions or even when using scripting. The macros can be used individually or in combination with one another.

NOTE: Some of the naming macros may not be valid under certain conditions (for example, some macros are only available when using scripts), so until you are well acquainted with the product, use the Insert Macro icon naming macros.zoom80 to ensure that you select macros that are valid for the situation.

 

The following naming macros are available:

Macro

Symbol

Result

Year (4 digit)

&[yyyy]

4-digit year (for example, 2007)

Year (2 digit)

&[yy]

2-digit year (for example, 07)

Month

&[mm]

Month

Day

&[dd]

Adds the day to the file name as a two digit numeral, for example, 09 for the ninth Day

Hour

&[hh]

Hour

Minute

&[mi]

Minutes

Second

&[ss]

Seconds

Quarter

&[qtr]

1-digit quarter of the calendar year: 1 for dates in January: March, 2 for dates in April: June, 3 for dates in July: September, 4 for dates in October: December.

Day of Year

&[dayofyear]

3-digit day of the year in range 001-366.

Previous Day

&[dd.-1d]

2-digit value in the range of 01-31.

Previous Month

&[mm.-1m]

2-digit value in the range of 01-12.

Previous Year

&[yyyy.-1y]

4-digit year (referring to previous year).

ISO Year

&[isoyear]

4-digit year corresponding to the ISO-8601 week in which the date falls.

ISO Week

&[isoweek]

2-digit week of the year (range 01-53) as defined in ISO-8601. Note that it's possible for a date in late December to actually fall in week 01 of the following year. Likewise, it's possible for a date in early January to fall in the last week (52 or 53) of the previous year.

ISO Day of Week

&[isoday]

1-digit day of the week as defined in ISO-8601, namely, Monday=1, Tuesday=2, Wednesday=3, ... Sunday=7.

Summary Name

&[summary]

Name of current summary. This option becomes available when a summary is selected for export.

For multiway export by tables, if all summaries are selected, the system will apply the summary name for the table name by default. As for multiway export by files, no extra changes are needed because the file name is set to the summary name.

Note: This macro is not available when all or more than one load plan is selected.

Filter Name

&[filter]

Name of current filter. Empty if no filter is current.

Measure Title

&[measure]

Name of current measure. Empty if no measure is current.

Key Value

&[keyvalue]

Value of a key field.

First Value of Field

&[firstvalue.value name]

Name of the first value in the selected field. See the Select a Field Name dialog for more information.

Note: This macro is not available when all or more than one load plan is selected.

Input File Location

&[input]

Full path and filename of an input file. To specify multiple input files use the convention &[input.1] &[input.2] etc. If there are more &[input]s than input files, the extra ones are replaced by empty strings. When importing from a database there are no input files, so all &[input]s are replaced by empty strings.

Input File Name

&[inputname]

Filename of an input file. To specify multiple input files use the convention &[inputname.1] &[inputname.2] etc. If there are more &[inputname]s than input files, the extra ones are replaced by empty strings. When importing from a database there are no input files, so all &[inputname]s are replaced by empty strings.

Output File Location

&[output]

Full path and filename of an export file. To specify multiple output files use the convention &[output.1] &[output.2] etc. If there are more &[output]s than export files, the extra ones are replaced by empty strings.

Distribution Source file path

&[source]

Full path and filename of a file that is being distributed via a distribution action. If multiple files exist, this macro will expand all names and concatenate them using a semicolon.

Distribution Source file path (Advanced)

&[source.option]

The option specifies which part of the path to return, i.e., dir for directory, file for filename with extension, name for filename alone, ext for extension.

Job Number

&[jobid]

Job number

Job Log

&[joblog]

Full path and filename of the Job Log

Process Name

&[process]

Process name

Date Format

&[date.<date increment>.<output format>]

Subtracted date; <date increment> could be -1d, +1d, -1m, +1m, -1y, +1y, and <output format> could be yyyyMMdd, yyyy-MM-dd, etc. The output format is case-sensitive. For a full list of supported format specifiers, click here.

System-Wide Counter

&[counter]

System counter. Automatically increments with each use A?a??a?? counts across all jobs in all processes.

Load Plan

&[loadplan]

Name of load plan selected.

Item Addressing (Advanced)

&[item.xpath]

A specific element or attribute of a job log input or output item. The XPath following the macro name is an XPath expression describing exactly which node is to be returned. Note that these macros are only available for scripting and distributions. In most cases they will be used in scripting to assist in navigating through the job log. They cannot be used for file or table naming.

Item File Path

&[source]

Full path of an item.

Item File Directory

&[source.dir]

Full path of item directory.

Item File Name

&[source.file]

File name of an item.

Item File Name (no ext.)

&[source.name]

File name of an item with no extension.

Item File Extension

&[source.ext]

Extension of item file.

Item URL

&[source.uri]

URL of an item.

Item Title

&[item.title]

Title of an item.

Item Description

&[item.description]

Description of an item.

Item Addressing Examples

&[item.title]

&[item.description]

&[item.sort]

&[item.filter]

&[item.summary]

&[item.totals/@record_count

Returns the auto-generated item title

Returns the auto generated item description

Returns the sort, if specified

Returns the filter, if specified

Returns the summary, if one exists

Returns the record count

Time Intervals

Calendar Year

&[yyyy]

4-digit calendar year

Calendar Half-year

H&[halfyear]-&[yy]

The calendar half-year in which the date falls, where each half-year is defined as six calendar months.

Calendar Quarter

Q&[qtr]-&[yy]

The calendar quarter in which the date falls, where each quarter is defined as three calendar months

Calendar Month

&[monthname]-&[yy]

The calendar month

Calendar Week

W&[week]-&[yy]

The week number

ISO8601 Year

&[isoyear]

The year corresponding to the ISO week in which the date falls.

ISO8601 Week

&[isoyear]-W&[isoweek]

The ISO week in which the date falls.

Fiscal Year

FY&[fendyear]

The fiscal year expressed as the calendar year of the first day of the fiscal year in which the date falls

Fiscal Half-year

FH&[fhalfyear]-&[fendyy]

The fiscal half-year in which the date falls

Fiscal Quarter

FQ&[fqtr]-&[fendyy]

The fiscal quarter in which the date falls.

Fiscal Period

FP&[fperiod]-&[fendyy]

The fiscal period; either a calendar month or a 4- or 5-week period, depending on the type of fiscal year

Fiscal Week

FW&[fweek]-&[fendyy]

The fiscal week number in which the date falls.

 

The naming macros are available in the following locations:

NOTE: The naming macros can also be used when scripting, for example, when using the Item.ExpandMacros method. See the UserScripting Help file for additional information. To use the naming macros in email body fields and NT Event Log Message fields, right-click and choose Insert.

 

Utilizing naming macros

  1. When viewing a field for which you can select a naming macro, click the adjacent Insert Macro icon naming macros.zoom80  to view the naming macro drop-down list.

  2. Select the desired naming macro from the list.

 

Syntax checking of macros

In the Export Wizard and the Portable Report Settings dialog, if the file name contains a macro (or macros), Automator performs a series of tests to be sure that the macros are well-formed. For example, the following conditions are detected and reported as errors:

  • Unknown macro names, for example, &[fred]. Such macros will not expand at runtime.

  • Parameterized macros having ill-formed parameters, for example, &[yyyy.+1q]. Such macros will expand to empty at runtime.

  • Macro names that are not appropriate in the context of the export in question. For instance, &[filter] makes no sense when publishing a PRF file.

  • Ill-formed macros. For example, a macro prefix (&[) without its matching suffix (]), or a macro embedded within a macro for example, &[fil&[dd]ter].

 

© 2024 Altair Engineering Inc. All Rights Reserved.

Intellectual Property Rights Notice | Technical Support