Specifying Custom Parameters Using Environment Variables

An administrator can specify custom parameters using environment variables.

Important: Astoria recommends that administrators implement custom parameters using composition profiles rather than environment variables, because they are much easier to manage. This is especially true of AST_ANT_OPTS.

However, if an administrator needs to alter the Java environment, they should define the environment variables in the xdbatch.bat, described below, rather than defining a System Environment Variable.

Compose with DITA-OT batch jobs are used for publishing outputs in various formats, such as PDF, XHTML and EclipseHelp. These batch jobs are processed using an open source program called Ant. Ant is a Java-based program that enables you to write scripts for automating various tasks.

Custom parameters for composition jobs can be set in either the ANT_OPTS or the AST_ANT_OPTS environment variables.

Important: Custom parameters specified in the Compose Output dialog, using either the Custom Parameter field or Set Profile options, override any options specified by environment variables.

ANT_OPTS and AST_ANT_OPTS

Astoria On-Premises administrators can configure Ant through the ANT_OPTS environment variable. ANT_OPTS lets you pass options into the Ant script that calls each module of the DITA-OT composition sequence. ANT_OPTS also lets you configure the Java environment in which the DITA-OT runs.

Defining AST_ANT_OPTS for a Batch File

Here is a simple example. Given the following Ant script:

<echo>A ${race} is ${distance}.</echo>

setting

ANT_OPTS=-Drace=marathon -Ddistance="42195 meters"

produces this output:

A marathon is 42195 meters.

AST_ANT_OPTS has almost the same effect as ANT_OPTS. AST_ANT_OPTS lets you pass options to the Ant task that calls each module of the DITA-OT composition sequence. However, AST_ANT_OPTS does not configure the Java environment that runs the Ant script. For that reason, administrators typically use AST_ANT_OPTS to set configuration parameters for all compose-output jobs while reserving ANT_OPTS for configuring the Java environment that runs DITA-OT.

Note: The DITA-OT runs on an Astoria Communication Server (ACS), so both ANT_OPTS and AST_ANT_OPTS are environment variables on whichever ACS server runs your DITA-OT instance.

Setting ANT_OPTS or AST_ANT_OPTS globally affects the behavior of all Ant processes. System administrators can limit the scope of ANT_OPTS or AST_ANT_OPTS by defining them in specific Astoria batch files. For example, to limit the scope of AST_ANT_OPTS to Astoria's batch-job processing, add an entry to <ACS>\common\bin\xdbatch.bat. For example:

SET AST_ANT_OPTS=-Drace=marathon -Ddistance="42195 meters"

When ANT_OPTS or AST_ANT_OPTS is set in Astoria batch files, system administrators do not need to define ANT_OPTS or AST_ANT_OPTS globally.