Get Live Pages

Command line:
tlapi ‑cGETLIVE [‑psPhase] [‑tnType] [‑isPlist] ‑osOutFile sPart
Library call:
nStatus = TLgetliveEx (sPart, sPhase, nType, sOutFile, sPlist, sLogFile)
Library call:
nStatus = TLgetlive (sPart, sPhase, nType, sOutFile, sPlist)
Scripting call:
sOutFile = GetLive (nType, sLocation, sPlist, sLogFile)
[Note] Note

The TLgetlive library call is deprecated and may not be supported in future versions of the API.

Function

Retrieve a live pages file for one or more TopLeaf partitions. The live pages file has a DTD file located in data\sgml\dtd under the TopLeaf installation folder.

Arguments

sPart

The path or pathname mask of the partition for which the live pages list is to be generated.

A partition pathname mask can include file wildcard characters in the last component of the path.

Examples of partition pathname masks are

book/myfiles/chap01

and

book/myfiles/chap*
sPhase

The partition phase for which the document is required. The selected phase is one of INITIAL, PUBLISH, UPDATE or CURRENT.

nType

This parameter specifies the format of the live pages list file, and must be one of:

  0 default format (SGML)
  1 SGML, live pages, filing instructions (the default)
  2 XML, live pages, filing instructions, with DTD reference
  3 XML, live pages, filing instructions, with no DTD reference
  4 TEXT file (not implemented)
  11 SGML, live pages only
  12 XML, live pages only, with DTD reference
  13 XML, live pages only, no DTD reference
  21 SGML, filing instructions only
  22 XML, filing instructions only, with DTD reference
  23 XML, filing instructions only, no DTD reference
sOutFile

The full pathname of a document file to hold the retrieved live pages file. If the file already exists, it will be replaced by the retrieved data. If the file does not exist, it will be created.

sPlist

The full pathname of a partition name list file. A partition name list file contains the names of one or more TopLeaf partitions to be included in the live pages list. The name list file is a text file and each line in the file declares the name of one TopLeaf partition. Wildcard characters are not permitted within this file.

For the scripting call if this argument is undefined or the empty string the value of the Partition property is used to determine the partition.

sLogFile

The path to the log file for receiving diagnostic messages.

If this is NULL for the library call, no log file is produced.

For the scripting interface no log is produced if this argument is null or an empty string.

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”.

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

Notes

The live pages file contains two main components, a list of all active leaves (specifying recto and verso pages, and the release in which they were created), and a list of filing instructions (how to update the document changes). It is possible to include or exclude either component.

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.

Examples

Command line:

tlapi ‑cGETLIVE ‑pPUBLISH ‑oC:livep.sgm manuals/topix/volume1

Library call:

/* Fetch live pages for all partitions in C:plist.txt */
status = TLgetliveEx(NULL, "PUBLISH", 12L, "C:merge.sgm", "C:plist.txt", NULL);

Scripting call:

file = topleaf.GetLive(2, "C:\\Temp\\pages.xml", "", "");