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.

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® CC 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

"-cometconfig"
"-cometlog"
"-cometlic"
"-cometcache"
"-cometapilog"
"-cometport"
"-cometaccepttimeout"
"-cometreceivetimeout"
"-cometsendtimeout"
"-cometyield"
"-cometlogrotate"
"-cometthreshold"
"-cometprogress"
"-cometdrawidle"
"-cometparanoidredraw"
"-cometidmlcache"
"-cometxmlparser" - "1" classic, "2" optimized, "3" fast
"-playback" - "0" off, "1" record, "2" playback
"-playbackpath"
"-soaplog"

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