Supporting data exchanges between the whiteboard and InDesign® Server.

Supporting data exchanges between the whiteboard and InDesign® Server. The functions of this module are made to export several content of an InDesign® document into appropriate XML trees.

You may use the xmlquery methods to work this the resulting XML structures. Use xmlquery::serialize to convert it to a string and xmlquery::write to export an XML tree into a file.

static XMLTree get_spreads(
  ItemRef docRef,
  int scope,
  int parentID,
  char* options = 0)

Export document data to XML. An XMLTree is generated. You may handle this tree using the xmlquery methods. Don't forget to close the tree at the end (xmlquery::close)!

The function collects information about the document pages and spreads.

Name Type Default Description
Return XMLTree   Newly created XML tree containing the exported data.
docRef ItemRef - Valid document reference
scope, parentID int, int - Source scope in the document

kScopeDocument : parentID is ignored

kScopeSpread : parentID is the 1-based spread index

kScopePage : parentID is the 1-based page index

kScopeCometGroup : parentID is the comet group ID (see frame::get_cometgroup)

kScopeElement : parentID is the UID of the frame. You can get this number using item::getint on an ItemRef.
options String or char* "" Options specifying the scope and format of the exported data, see server-options
#include "internal/types.h"

Export the placeholders of page 2 of the document. 

#include "internal/types.h"

int main ()
{
    XMLTree tree = server::get_placeholders (0, kScopePage, 2, "xmlindent:1;content:plain,tagged;");

    if (tree)
    {
        xmlquery::write (tree, "$DESKTOP/placeholders.xml");
        xmlquery::close (tree);
    }
    else	showmessage ("Error while fetching data.");

    return 0;
}

Version 3.1 R1760, 26. Feb. 2010

priint:comet InDesign® Plug-Ins

frame::get_cometgroup
item::getint

static XMLTree get_cometgroups(
  ItemRef docRef,
  int scope,
  int parentID,
  char* options = 0)

The function collects information about a Comet group. A description about the parameters you find here..

More functions to support Comet groups are the following :

An example on how to set the parameters and exporting an XML tree to a file ... 

you find here..

Version 3.1 R1760, 26. Feb. 2010

priint:comet InDesign® Plug-Ins

static XMLTree get_elements(
  ItemRef docRef,
  int scope,
  int parentID,
  char* options = 0)

The function collects information about the elements of the document. A description about the parameters you find here..

An example on how to set the parameters and exporting an XML tree to a file ... 

you find here..

Version 3.1 R1760, 26. Feb. 2010

priint:comet InDesign® Plug-Ins

static XMLTree get_placeholders(
  ItemRef docRef,
  int scope,
  int parentID,
  char* options = 0)

The function collects information about placeholders in the document. A description about the parameters you find here..

An example on how to set the parameters and exporting an XML tree to a file ... 

you find here...

Version 3.1 R1760, 26. Feb. 2010

priint:comet InDesign® Plug-Ins

static XMLTree get_notes(
  ItemRef docRef,
  int scope,
  int parentID,
  char* options = 0)

The function collects information about Comet notes in the document. A description about the parameters you find here..

The folloing functions are designed to support Comet notes via cscript:

An example on how to set the parameters and exporting an XML tree to a file ... 

you find here...

Version 3.1 R1760, 26. Feb. 2010

priint:comet InDesign® Plug-Ins

static int load_placeholder(
  char* buffer,
  int maxLen,
  ...)

DEPRECATED! Please use the function load_placeholder_str instead.

Name Type Default Description
Return int   0 or ErrorCode
buffer char* - allocated char* string for the result
maxLen int 0 Length of allocated char* string incl. closing 0 in bytes (not in letters!). If the result is longer than or equal maxLen, the result is filled by maxLen-1 bytes and the function will return the error code allocatedStringTooShortErr (=1288). Using serror (0, &neededBytes) you can ask for the number of needed bytes and execute the function again with a bigger buffer.

Attention : Zu small result strings may lead to wrong tagged text or malformed UTF-8 letters and may cause InDesign® to crash!

0 : ignore length, copy whole result always. Take care to have a result string big enough for all possible results. Too small strings may lead InDesign® to crash!

Very simple placeholder script 

int main () 
{
    char	*	buffer	= alloc (1000);
    int			neededBytes;
    int 		result 	= server::load_placeholder(buffer, 1000);

    if (result == 1288)
    {
        serror (0, &neededBytes);
        if (neededBytes > 0)
        {
            release(buffer);
            buffer = alloc (neededBytes);
            result = server::load_placeholder(buffer, neededBytes);
        }
    }

    if (result == 0) textmodel::replace(buffer);

    release(buffer);
    return result;
}

Please use the function load_placeholder_str instead.

static int load_placeholder_str(String str, ...)

Execute the standard load script of a placeholder in a PublishingServer environment. This function can only be used in the context of the placeholder load script.

The function uses the data type String and not char*. The advantage is that you do not need to know the length of result before calling the function. To get the strings content please use string::get (your_stringvar). However, please pay attention to the following things:

The key/value pairs of the function are a pure text replacement in the placeholder load statement and are replaced before sending the command. So, for example, the couple

"MYTAG", "My value"

replaces the tag <MYTAG> in the statement by My value. Which tags are included in the statement can be seen by looking at the load statement (for example, in the ison). For your convenience we write the original instruction in the log again:

Here's a sample statement before applying the key/value pairs: 

# server::load_placeholder_str statement received from server:

  "call stringlist plugin(globalName='DataProviderManager',methodName='get')[
    <Session.Id>,
    'PackagingUnitFirstPrice',
    <Model.Id>,
    <Entity.Id>,
    'customervariantproducts.eur1Price',
    <Record.Id>,
    <Record.GroupId>,'',
    <xml.assortment>,
    <layer.1>,
    <layer.2>,
    '',
    <xml.publication>,
    '','',
    <xml.documentId>,<Java.ResultClass>]:placeholder#268435830#get"

Most of these tags are automatically replaced by the plugins. A complete list of automatically replaced tags and their values can be found here. Please also note the link at the bottom of the table at PubServer specific variables!

But your key/vaue pairs will applied before autoreplacement. For example, <layer.1> and <layer.2> are commonly used as country and language. To set these tags to customized values, simply add the two key/value pairs to your function call: 

"layer.1", "Disc world",
"layer.2", "Ughh"

Name Type Default Description
Return int   0 or ErrorCode
str String - buffer for the result of the load method
... String or char*,
String or char*		 0 KeyValue pairs to override orset certain input values

Very simple placeholder script 

int main () 
{
    String		str		= string::alloc ();
    int 		result 	= server::load_placeholder_str(str);

    if (result == 0)
    {
        textmodel::replace(string::get (str));
    }
    string::release(str);

    return result;
}

Override certain values 

int main () 
{
    String		str		= string::alloc ();
    int 		result 	= server::load_placeholder_str (str, "Record.Id", "12345");

    if (result == 0)
    {
        textmodel::replace(string::get (str));
    }
    string::release(str);

    return result;
}

Version 4.0.5 R14000, 7. Nov 2016

Available:
Comet-Plug-Ins, comet_pdf, Illustrator

placeholder::load
comet.placeholder.loadServer

static int load_elements(ElementList result, ...)

Execute the standard build script of a multiframe placeholder in a PublishingServer environment. This function can only be used in the context of the placeholder build script.

The function uses the data type ElementList for the result. Typically, you will pass the global variable gElements to the function, which is predefined in build scripts. This variable must not be allocated or release.
If you pass a local variable, this must be allocated before and released at the end of the script.

Please note the hints regarding key/value pairs and replacements documented for server::load_placeholder_str.

Name Type Default Description
Return int   0 or ErrorCode
elements ElementList - list for the result of the build method
... String or char*,
String or char*		 0 KeyValue pairs to override orset certain input values

Very simple placeholder load script 

int main () 
{
    return server::load_elements (gElements);
}

Version 4.3.0 R33300, 21. Jul 2023

Available:
Comet-Plug-Ins, comet_pdf, Illustrator

placeholder::load
comet.placeholder.loadServer

static int load_table_ids(
  IDTypeList products,
  StringList moreGroups,
  ...)

Execute a TableInsert method. This function can only be used in a table load context!

Name Type Default Description
Return int   0 or ErrorCode
products IDTypeList - result list for product IDs to use for table generation. Usually just gProducts
moreGroups StringList - StringList for additional group information. Usually just gMoreGroups.
... String or char* 0 KeyValue pairs for overriding default replacements, see example.

Very simple Table script 

int main ()
{
    return server::load_table_ids(gProducts, gMoreGroups);
}

Override certain input values 

int main ()
{
    return server::load_table_ids(gProducts, gMoreGroups, "TableRecord.Id", "12345");
}

Version 4.0 R5804, 23. Sep 2014

Available:
Comet-Plug-Ins, comet_pdf

static int dataprovider_load(
  StringList resultBuffer,
  char* dataProviderId,
  char* resultEntityId,
  char* search,
  ...)

Load data from a dataprovider

Please note:
In most cases you should prefer one of the following solutions rather than using server::dataprovider_load:

For backward compatibility, the server::dataprovider_load function will still work in future versions, however usage may be deprecated and therefore no longer supported in the future.

Please also note the descriptions for the cScript / Java Bridge. Perhaps the task you want to solve is more convenient and easier to solve this way!

Notes for resultBuffer:
  1. the result type of the DataProvider is determined by the type of the resultBuffer provided as parameter. At the time, the following types can be processed:
    • String or char*: the result is a single string (the first value fetched from the DastaProvider).
    • StringList: result is a list of strings
    • IDTypeList: result is a list of IDs of the type idtype
    • ProductList: result is a list of Products
    The content of resultBuffer doesn't necessarily make sense, so you should know the requested DataProvider and use one of the following combinations:
    • String or char*: for DataProviders with result type String or List<String>
    • StringList: for DataProcviders with result type String or List<String>
    • IDTypeList: for DataProviders with result type List<RecordId>
    • ProductList: for DataProviders with result type List<Product>
  2. the parameter provided as resultBuffer must be allocated in the script (it's really important), otherwise the result type cannot be detected
  3. the list must be released in the script. If you need the list values outside of the script, they must be copied (e.g. in a global list)

Name Type Default Description
Return int   0 or ErrorCode
resultBuffer int - result pointer of type String or char*, ProductList, IDTypeList or StringList. This list or string must be allocated within the script!
dataProviderId String or char* - identifier of the DataProvider
resultEntityId String or char* 0 The content replaces the tag <Entity.ResultId> in the statement of dataProviderId.
search String or char* 0 The content replaces the tag <Record.SearchStr> in the statement of dataProviderId.
{key, value} String or char*, String or char* 0 Any number of Key/Value pairs for further replacings. Every pair must consist of two string.

Replacing the keys by the values is a simple search/replace in the statement of dataProviderId only: All occurances of <key> are replaced by 'value'. Single quotas in values are escaped automatically.

To replace all the tags used in the statement, you must know the statement, of course. Therefor the original statement of the DataProvider is written into the logfile with the introduction # DataProvider Statement received from server. The result of the replacements are also found in the logfile with the introduction # Preprocessed data provider statement.

Which value is expected for which key, you may need to ask the whom who wrote the DataProvider method at least. Values for replacing the common PublishingServer-specific tags can be found here. Further values of common keys can be found here.

Example: fill a idtype list. 

int main ()
{
    IDTypeList 	ids 	= idtypelist::alloc();
    int 		result 	= 0;
    int 		index  	= 0;

    result = server::dataprovider_load(ids, "ChildBuckets", 0, 0, "Record.Id", gPSRecordId, "Entity.Id", gPSEntityId);
    if (result == 0) {
        // copy ids to the global IDTypeList gProducts (will only work this way, if executed as a TableInsert method)
        for (index = 0; index < idtypelist::length(ids); ++index) {
            idtypelist::insert(gProducts, -1, idtypelist::get(ids, index));
        }
    }

    // clear list, but do not clear entries
    idtypelist::clear(ids, 0);
    return result;
}

Example: get a simple String. 

int main ()
{
    char 	* 	value 	= alloc(32768);
    int 		result 	= 0;

    result = server::dataprovider_load(value, "FirstText", 0, 0, "Record.Id", gPSRecordId, "Entity.ContextLanguage", "deu");
    if (result == 0)
    {
        textmodel::replace(value);
    }

    release(value);
    return result;
}

use load_placeholder_str instead or a custom Java method like described here.
Version 4.0 R5804, 23. Sep 2014

Available:
Comet-Plug-Ins, comet_pdf

comet.placeholder.loadDataProvider

static int individualization(ItemRef docRef, char* dataFilePath)

Serialize a document, see here for more information about serializations.

Name Type Default Description
Return int   0 or ErrorCode
docRef ItemRef - Document to serialize, see hier

0 : current front document
dataFilePath char* oder String - Complete path to serialization data file see here

Version v4.1, 1. Oct 2018

priint:comet InDesign® Plug-Ins, comet_pdf

static char* get_session_arg(char* option)

Determine the value of an program option or an value of the environment configuration.

The call only returns meaningful values in InDesign® Server. In InDesign® Desktop and comet_pdf the result is always empty.

Die folgenden Tabelle enthält alle von den priint_comet Plugins definierten Zusatzparameter für InDesign® Server:

Option Beschreibung Werte
-cometconfig

[Deprecated] Path to the Autocomet configuration file (batch mode).

<config.xml path>

-cometlog

Enable common logging and write logs to <comet log file path>. You should enable logging on development systems and to trace errors on productive systems. The destination folder must exist, otherwise logging will fail.

If set, the cometlog option must be unique for each InDesign Server instance running on the same machine.

<comet log file path>

-cometlic

Read license from <license file path> rather than from the standard locations for license files.

<license file path>

-cometcache

Set the comet cache path.

The cache path must be unique for each InDesignServer instance running on the same machine, so it’s highly recommended using this option. The default is ~/Documents/XCache, which might not be useful in a server environment.

<cache folder path>

-cometapilog

Enable API logging and write logs to <api log file path>. This will trace the complete communication between priint:cometserver and InDesignServer. The destination folder must exist, otherwise logging will fail.

If set, the cometapilog option must be unique for each InDesignServer instance running on the same machine.

<api log file path>

-cometaccepttimeout

Default: 1 (= 1 ms)

<accept timeout in ms>

-cometreceivetimeout

Default: 60000 (=60s)

<receive timeout in ms>

-cometsendtimeout

Default: 60000 (=60s)

<send timeout in ms>

-cometyield

Milliseconds to yield between listen attempts, currently unused.

<yield ms>

-cometlogrotate

Rotate comet logs, if the log file exceeds the size of <# bytes> bytes. Default is 2097152 (2 MB), -1 will disable log rotate at all (not recommended). This setting applies to all log files.

<# bytes>

-cometthreshold

Threshold in bytes before writing script results (like XML strings) in tmp files rather than returning the string. This setting is relevant for the Corba connection only, the default value is 32768. Higher values may improve performance, on the other hand large result strings (> 512k) sometimes cause failures in the Corba connection.

The argument is not relevant for SOAP/PubServer communications.

<# bytes>

-cometparanoidlog

Unused

-cometdrawidle

Enable / disable draw idle features. If turned on (default), InDesignServer will prepare previews whenever “idle”. You should not turn it off, except you notice problems with previews.

true | false

-cometparanoidredraw

With paranoidredraw turned on, every spread is forced to be rendered in kPrinting mode before the first preview request, even if the spread has not been changed after the document has been openend.

Customers reported, that they had occasional problems with text placeholders, which appeared to be empty in previews. This is a known problem for placeholders, that have just been loaded or updated, but not yet rendered in kPrinting mode; it is not a known problem for placeholders in documents just opened. However, since it seems to be a potential problem, the potential solution would be to turn cometparanoidredraw on.

true | false

-cometidmlcache

Turn IDML cache on (default is off). With IDML cache turned on, all templates will be resaved as IDML and then opened from the IDML file. This will slow down the first builds a little bit, but can help to speed up subsequent builds, reduce size of generated documents and solve problems caused by sorrupted or outdated templates.

You can skip this option, unless you encounter frequent performance or stability issues when generating pages.

on | off

-legalnotes

After starting the InDesignServer, the Legal Notes of the priint:comet plug-ins are shown in the standard browser.

-

-iorfile

[Deprecated] This is the communication endpoint for Corba connections. You must provide a file name, the destination folder must exist and must be writeable for the InDesignServer user. If the file provided already exists, this file must be writeable for the InDesignServer user.

<path to iorfile>

-shutdowntrigger

Shutdown the InDesignServer instance after (every) n days / hours / minutes / seconds uptime, after n documents or n jobs have been processed, when memory is low, at a certain time or when no more n GB memory can be allocated. See Section 10 Troubleshooting for more information.

The following criteria are supported:

  • uptime=nd | nh | nm | ns documents=n
  • jobs=n
  • memory[=low]
  • time=hh:mm:ss
  • headroom=nG | nM | nK

One of the criteria described.

-purgetrigger

[Deprecated] Purge memory after (every) n days / hours / minutes / seconds uptime, after n documents or n jobs have been processed, when memory is low, at a certain time or when no more n GB memory can be allocated. See Section 10 Troubleshooting for more information.

The following criteria are supported:

  • uptime=nd | nh | nm | ns documents=n
  • jobs=n
  • memory[=low]
  • time=hh:mm:ss
  • headroom=nG | nM | nK

One of the criteria described.

-cometxmlparser

Which XML parser to use. You should skip this option or set it to fast.

  • classic
  • optimized
  • fast

-playback

Use of recorded data in $XCACHE.

priint:comet plugins can record received data from external data sources. Recorded data can used in playback. See here for more information about recording data. mode.

WERK II reserves the right to turn off this feature at any time – please contact WERK II if you plan to use recoreded data.

-playbackpath

Complete path to record(ed) data. URL[See here for more information about recording data.]{../InDesign/Plugins/w2plugins.html#Playback-Modus}

<playback data path>

-soaplog

Turn on logging the the complete SOAP traffic. The SOAP traffic is looeg to these files:

  • $DESKTOP/_soapTEST.log
  • $DESKTOP/_soapSENT.log
  • $DESKTOP/_soapRECV.log
See here for more information.

-

-debugpy

Activate the Python debugger at the specified port.

If set, the debugpy option must be unique for each InDesignServer instance running on the same machine. In addition, if debugpy and debugscript are used both, they must be unique too.

The following values are supported:

  • 0 : Do not use the Python Debugger
  • -1 : Default port 5678
  • > 0 : <port number>

<port-number>

-debugscript

Activate the cScript Tracer at the specified port.

If set, the debugscript option must be unique for each InDesignServer instance running on the same machine. In addition, if debugpy and debugscript are used both, they must be unique too.

The following values are supported:

  • 0 : Do not use the cScript Tracer
  • -1 : Default port 5678
  • > 0 : <port number>

<port-number>

Name Type Default Description
Return char*   Value of programm option resp. environment configuration. Please note that int and bool values are also returned as strings!
"" : In case of an error

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.
option char* oder String - Valid program option or environment configuration. The following specifications are supported:

InDesign® Server programm options. A description of the options can be found in Documentation/English/Intro to InDesign® Server NNN.pdf in the folder of InDesign® Server.
    "-adminport"
    "-configuration"
    "-console" | "-noconsole" - result "0" or "1"
    "-errorlist" | "-noerrorlist" - result "0" or "1"
    "-heartbeatupdateinterval"
    "+home"
    "-host"
    "-iorfile"
    "-LogToApplicationEventLog" - result "0" or "1"
    "-maxerrors"
    "-maxwaitss"
    "-noblockss" - result "0" or "1"
    "-onmainthread" - result "0" or "1"
    "-pluginpath"
    "-port"
    "-previews" | "-nopreviews" - result "0" or "1"
    "-rxidletimeout"
    "-seh" - result "0" or "1"
    "-sendcrashlogs" | "-nosendcrashlogs" - result "0" or "1"

priint:comet option extensions for InDesign® Server, see here
Environment settings by app.comet.setEnvironment

    "endpoint"
    "getEnvironment"
    "instanceID"
    "isConnected"
    "isPubserverConnection"
    "scriptIO"
    "upTime" 
int main ()
{
    int 	i;
    int 	n = server::count_session_args ();

    showmessage ("log ---%s---\n", 				server::get_session_arg ("-cometlog"));
    showmessage ("treshold ---%s---\n",			server::get_session_arg ("-cometthreshold"));
    showmessage ("confi ---%s---\n",			server::get_session_arg ("-configuration"));
    showmessage ("rxidletimeout ---%s---\n",	server::get_session_arg ("-rxidletimeout"));
    showmessage ("port ---%s---\n",				server::get_session_arg ("-port"));

    for (i = 0; i < n; i++)
    {
        showmessage ("%d   : '%s'\n", i, server::get_nth_session_arg (i));
    }
}

Version v4.1, 18. Feb 2019 (Vietnam)

priint:comet InDesign® Plug-Ins, comet_pdf

count_session_args
get_nth_session_arg

static int count_session_args()

With how many additional arguments was the program called? The result is also correct for InDesign® Desktop, if it was called directly from the Terminal.

Name Type Default Description
Return int   Number of program arguments at the start of the program. The program name is counted as argument 0. 
int main ()
{
    int 	i;
    int 	n = server::count_session_args ();

    showmessage ("log ---%s---\n", 				server::get_session_arg ("-cometlog"));
    showmessage ("treshold ---%s---\n",			server::get_session_arg ("-cometthreshold"));
    showmessage ("confi ---%s---\n",			server::get_session_arg ("-configuration"));
    showmessage ("rxidletimeout ---%s---\n",	server::get_session_arg ("-rxidletimeout"));
    showmessage ("port ---%s---\n",				server::get_session_arg ("-port"));

    for (i = 0; i < n; i++)
    {
        showmessage ("%d   : '%s'\n", i, server::get_nth_session_arg (i));
    }
}

Version v4.1, 18. Feb 2019 (Vietnam)

priint:comet InDesign® Plug-Ins, comet_pdf

get_session_arg
get_nth_session_arg

static char* get_nth_session_arg(int nth)

Value of the nth program argument. The program name itself is argument 0.

Name Type Default Description
Return char*   Value of the nth program argument. Please note that the option names like -port etc. also count as arguments!
"" : In case of an error

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.
nth int - 0-based index of the argument. 
int main ()
{
    int 	i;
    int 	n = server::count_session_args ();

    showmessage ("log ---%s---\n", 				server::get_session_arg ("-cometlog"));
    showmessage ("treshold ---%s---\n",			server::get_session_arg ("-cometthreshold"));
    showmessage ("confi ---%s---\n",			server::get_session_arg ("-configuration"));
    showmessage ("rxidletimeout ---%s---\n",	server::get_session_arg ("-rxidletimeout"));
    showmessage ("port ---%s---\n",				server::get_session_arg ("-port"));

    for (i = 0; i < n; i++)
    {
        showmessage ("%d   : '%s'\n", i, server::get_nth_session_arg (i));
    }
}

Version v4.1, 18. Feb 2019 (Vietnam)

priint:comet InDesign® Plug-Ins, comet_pdf

get_session_arg
count_session_args

Since
Version 3.1, R1760, 26. Feb. 2010

Available
priint:comet InDesign® Plug-Ins

Alphabetic index HTML hierarchy of classes or Java