Get Generated File

Command line:
tlapi ‑cGETNDX [‑psPhase] [‑u] [‑tnType] ‑osOutFile sPart
Library call:
nStatus = TLgetndx (sPart, sPhase, nUpd, nType, 1L, 0L, sOutFile)
Scripting call:
sOutFile = GetGenerated (sType, sLocation)

Function

Retrieve one of the files generated from the input as part of the composition run (table of contents, index or cross-reference). See the User Guide for more information on generated files.

Arguments

sPart

The path of the partition for which the generated file is to retrieved.

sOutFile

The full pathname of a text file to hold the retrieved index or table of contents tags. If the file already exists, it will be replaced by the retrieved data. If the file does not exist, it will be created.

sPhase

The partition phase for which the document is required. The selected phase is one of INITIAL, PUBLISH, UPDATE or CURRENT. Defaults to PUBLISH, so for a non-looseleaf job it is usual to select INITIAL.

nUpd

This parameter specifies the extent of the search for table of contents and index keys. If nUpd is 0, then the entire partition will be scanned, if nUpd is 1, then only those new pages created for the current update will be scanned.

When using the command line, the ‑u flag indicates that only changed pages will be included.

nType

This parameter specifies the index file type required and must be one of:

  • 0 = extract table of contents

  • 1 = extract index

  • 5 = extract cross-reference (XREF) file

If this parameter is not present the table of contents is extracted. The results are undefined if a value other than those listed above is used.

sType

This applies to the scripting call only. It must have one of the values TOC, INDEX or XREF to specify the type of data to be returned. The value will be converted to upper case if necessary.

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.

When a file name is generated, it will have extension “.xml”.

The constant "1" in the library call indicates that XML data is to be generated. Other values are reserved for legacy jobs and must not be used.

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

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.

An empty string is returned if any problems occur when creating the output file.

Output Format

XML file valid against predefined DTD. The DTD can be found in the data\sgml\dtd folder under the TopLeaf installation folder (C:\Program Files\TKS by default).

Examples

Command line:

tlapi ‑cGETNDX ‑pPUBLISH ‑t0 ‑otoc.xml manuals/topix/volume1

Library call:

status = TLgetndx("manuals/topix/volume1", "PUBLISH", 0L, 1L, 1L, 0L, "toc.xml");

Scripting call:

file = topleaf.GetGenerated("index", "C:\\Temp\\index.xml");

Restrictions

The extracted file can be empty if there are no tags defined in the selected partition phase or range. This condition is not reported as an error.