Get Transformed Output

Command line:
tlapi ‑cGETTRN [‑psPhase] [‑isPartList] [‑TsParams] ‑fsOutFormat ‑osOutFile sPart
Library call:
nStatus = TLcvt2out (sPart, sPhase, sOutFormat, sOutFile, sLogFile, nLogSize, sParams, nShow)
Library call:
nStatus = TLcvtmult (sPart, sPhase, sPartList, sOutFormat, sOutFile, sLogFile, nLogSize, sParams, nShow)
Scripting call:
sOutFile = GetTransform (sOutFormat, sLocation)

Function

Get a transformed version of the data in a partition. The partition must have been composed (for example, by calling Compose).

Arguments

sPart

The path of the partition from which to generate the PDF. The scripting call uses the Partition property to determine the partition to use.

sPartList

The path to a text file containing a list of partitions to include in the output. Each partition name must be on a line by itself. See below for more information.

sPhase

The partition phase from which to take the data. One of INITIAL, PUBLISH, UPDATE or CURRENT. Defaults to PUBLISH, so for a non-looseleaf job it is usual to select INITIAL.

The scripting call uses the Phase property to determine the phase to use.

sOutFormat

A string identifying the type of transformation required. For example, html or rtf.

sOutFile

The path to the output file.

sLogFile

The path to the log file for receiving diagnostic messages.

If this is NULL, no log file is produced.

If this points to an empty string, the location of the “standard” log file is returned here. In this case nLogSize must be set to the maximum size of the buffer pointed to by sLogFile.

nLogSize

The maximum size of the buffer pointed to by sLogFile. Only used if sLogFile points to an empty string on input.

sParams

A string containing parameters for the transformation. The string can contain a number of assignments of the form

name="value"

separated by spaces. See Set Transform Property for descriptions of the available properties.

The special value {part-default} sets the properties to the default values defined for the partition. See the User Guide for information on how to set the default properties for a partition.

The command line call uses the partition default properties unless the ‑T argument is present.

Default property values can also be set by using metadata variables.

nShow

The Windows showmode for the progress display.

The only useful values are SW_NORMAL (1) and SW_MINIMIZE (6). The latter causes the progress window to run minimised. There is no way to prevent the creation of a window.

This parameter is ignored on Unix.

sLocation

This applies to the scripting interface only. This determines where the output file is created:

  • If null or the empty string, the file is created in a directory designated for temporary files.

  • If it is the path to an existing directory, the file is created in this directory.

  • Otherwise, the file is created using sLocation as a path. Any existing file with this path will be overwritten.

For additional command line arguments see “Common Flag Arguments”.

Using Multiple Partitions

When a list of partitions is supplied, the data from each one is used in turn and included in the output.

The partition named in the sPart argument is used to find the mappings which determine the output style. If this partition does not appear in the list its data is not included in the output.

All of the partitions should belong to the same publication. Using partitions composed with different stylesheets may lead to unpredictable results.

The same phase is used for all of the partitions in the list.

Scripting Call Return

The return value is a string containing the path to the output file. This is always an absolute path. It is also available as the value of the OutputFile property.

If the output file cannot be generated, an empty string is returned.

Examples

Command line:

tlapi ‑cGETTRN ‑pINITIAL ‑fhtml ‑oC:\Temp\out.htm manuals/topix/vol1

Library call:

status = TLcvt2out("manuals/topix/vol1", "INITIAL", "html", "C:\\out.htm", NULL, 0, NULL, SW_HIDE);

Scripting call:

topleaf.SetTransformProperty("html", "maketoc", "true");
html = topleaf.GetTransform("html", "C:\\Temp");

Output transform diagnostic log file

If a request to get a transformed version of the partition content fails, you can retrieve a diagnostic log file that may help resolve the problem. The diagnostic log can be retrieved directly using the TLcvt2out library call. Alternatively, if you use the command line interface to run a secondary transform, and the transform fails, you can call the GETSTAT function to retrieve the diagnostic log:

tlapi ‑cGETTRN  ‑pINITIAL ‑fhtml ‑oC:\Temp\out.htm manuals/topix/vol1
tlapi ‑cGETSTAT ‑pINITIAL ‑t5 ‑oC:\Temp\out.log manuals/topix/vol1