Current SOAP/PubServer connection and execution of available services.

Version :
13.11.2023, 10:13 Uhr

Current SOAP/PubServer connection and execution of available services. The call requires the installation of the CoreService or CoreService-Internet plugins.

Usage of soap calls requires the installation of the CoreService or CoreService[Internet] plug-ins. Information about the Configuration of the data connection can be found here.

Connections to SOAP/PubServer services are done by SOAP. We are using gSOAP by Robert A. van Engelen for our implemtation. See here for the gSOAP User Guide.

[since v4.0.5 R17778] Plugins and comet_pdf can log the traffic the traffic from and to the service. The following file are written to your desktop:

Please note : Logfiles may become very huge! Do not use SOAP logs only for test cases with a small amount of tasks!

How to activate SOAP logs:

This is a feature! We implement it in the hope, that it helps you to check your SOAP connections. WERK II and partners however, do not see themselves in the obligation to evaluate this data!

static SOAP connection()

Get the current SOAP/PubServer connection. The connection should never be deleted using a script command.

Name Type Default Description
Return SOAP   Current SOAP/PubServer connection of InDesign® or 0


priint:comet InDesign® Plug-Ins, comet_pdf

static SOAP login(
  char* service = 0,
  char* user = 0,
  char* passwd = 0,
  char* lang = 0,
  char* mandant = 0)

Create a connection to a Soap service. If one of the arguments is 0 (not ""!), the login dialog will be opened. The result should be checked for 0 in any case. The pointer returned must be deleted again using soap::logout.

Name Type Default Description
Return SOAP   Pointer to the current SOAP/PubServer connection with successful or 0 otherwise. The pointer must be deleted again using soap::logout!
service String or char* 0 Service name
user String or char* 0 User name
passwd String or char* 0 Password
lan String or char* 0 Language
mandant String or char* 0 Client

After the set up of the SOAP/PubServer connection the current XML files will be uploaded to the service. 

int main ()
{
    SOAP      	soap 	= soap::login (
     					"http://212.100.45.45:8080/cats-comet/cats/comet",
     					"admin",
     					0,
     					0,
     					"Erich Mühsam");
    char					xmlpath[4096];
    int 		res;

    if (!soap) return 0;
    xmlquery::app_path (xmlpath);

    res = soap::upload_metadata (soap, xmlpath);
    if (res) showmessage (
     	"Uploading metadata failed : %s.", 
     	serror (res));

    soap::upload_pageitems (soap, xmlpath);
    if (res) showmessage (
     	"Uploading pageitems failed : %s.",
     	serror (res));

    soap::logout (soap);

    return 0;
}

Version 1.2 (15 June 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

logout

static int logout(SOAP dbc)

End the connection to SOAP/PubServer service.

Name Type Default Description
Return int   0 or ErrorCode
dbc SOAP - Pointer to a SOAP/PubServer connection created with login. The command may not delete the SOAP/PubServer connection of InDesign® (soap::connection)!


priint:comet InDesign® Plug-Ins, comet_pdf

static char* server(SOAP dbc, char* str)

Ascertain the server name of a SOAP/PubServer connection.

Name Type Default Description
Return String or char*   (Depends on parameter str) Name of the server using the specified SOAP/PubServer connection. The return value is identical with the call parameter str.
dbc SOAP - Valid SOAP/PubServer connection
str String or char* - Reserved memory for the server name. When using char*, the memory should be at least 256 bytes in size. 
char		s[256];

showmessage ("%s", soap::server (soap::connection (), s));

Version 1.1.9 (2 May 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CSOAP.getServer

static char* user(SOAP dbc, char* str)

Acertain the user name with which a SOAP/PubServer connection is to be created.

Name Type Default Description
Return String or char*   (Depends on parameter str) User name for the specified SOAP/PubServer connection. The return value is identical with the call parameter str.
dbc SOAP - Vallid SOAP/PubServer connection
str String or char* - Reserved memory for the user name. When using char*, the memory should be at least 256 bytes in size. 
char		s[256];

showmessage ("%s", soap::user (soap::connection (), s));

Version 1.1.9 (2 May 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CSOAP.getUser

static char* language(SOAP dbc, char* str)

Name Type Default Description
Return String or char*   (Depends on parameter str) Database name/schema for the specified SOAP/PubServer connection. The return value is identical with the call parameter str.
dbc SOAP - Valid SOAP/PubServer connection
str String or char* - Reserved memory for the server name. When using char*, the memory should be at least 256 bytes in size. 
char		s[256];

showmessage ("%s", soap::language (soap::connection (), s));

Version 1.1.9 (2. Mai 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CSOAP.getLanguage

static char* client(SOAP dbc, char* str)

Ascertain the name of the client with which a SOAP/PubServer connection is set up.

Name Type Default Description
Return String or char*   (Depends on parameter str) Client for the specified SOAP/PubServer connection. The return value is identical with the call parameter str.
dbc SOAP - Valid SOAP/PubServer connection
str String or char* - Reserved memory for the client name. When using char*, the memory should be at least 256 bytes in size. 
char		s[256];

showmessage ("%s", soap::client (soap::connection (), s));

VVersion 1.1.9 (2. Mai 2005)

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CSOAP.getClient

static int charset(SOAP dbc)

Characterset of database connection.

Name Type Default Description
Return int   -1 : Error
0 : System characterset
1 : UTF8
2 : Unicode 16 Bit
3 : Unicode 32 Bit
dbc SOAP - database connection

v4.0.5 R14333, 4. Jan. 2017

priint:comet InDesign® Plug-Ins, comet_pdf

comet.CSOAP.getCharset

static int upload(
  SOAP soap,
  char* data,
  int datalen,
  char* id,
  char* fname = "",
  char* mimetype = "",
  char* description = "")

Send a file or a text to an SOAP/PubServer service

Name Type Default Description
Return int   0 or ErrorCode
soap SOAP - Valid SOAP/PubServer connection
data String or char* - Data to be uploaded. The data needs to be text or a complete file path.
datalen int - Length of the data
-1 : data is a file path
0 : data contains text data the length of which is to be automatically calculated
otherwise : data contains text data of this length
id String or char* - Identifier under which the data is to be stored. Identifiers must be unique. If an upload exists with the specified ID, the data here will be changed. The ID will be used in download in order to retrieve the data.
fname String or char* "" Internal data name inside the SOAP/PubServer service. For files this parameter will be ignored, for data this must have a value.
mimetype String or char* "" Type description of the data e.g. text/plain. If this specification is empty, text data will be stored with the text/plain Mime type. For files an attempt will be made to ascertain the Mimetype from the file extension or from the file type (only Macintosh).
description String or char* "" user-defined description of the data

Load the file colors.html of the curent XML files folder (Menu; Plug Ins -> Data folder ...) on the server. The file will be stored with the Id colors.xml. 

SOAP		gSoap		= soap::connection ();

int doUpload (char * path, char * name)
{
    char		src[4096];
    int			err;

    strcpy (src, path);
    strcat (src, "/");
    strcat (src, name);

    err = soap::upload (gSoap, src, -1, name);
    return err;
}

int main ()
{
    char		xmlpath[4069];

    xmlquery::app_path (xmlpath);

    gSoap = soap::connection ();
    if (!gSoap)
    {
        showmessage ("No connection to the SOAP/PubServer service");
        return 0;
    }

    doUpload (xmlpath, "colors.xml");
}

Store a text on the server. The difference to the above example is that soap::upload has a value in the third parameter >= 0. 

SOAP		gSoap		= soap::connection ();

int doUpload (char * id, char * content)
{
    int		err;

    err = soap::upload (gSoap, content, 0, id, id);
    return err;
}

int main ()
{
    char		xmlpath[4069];

    xmlquery::app_path (xmlpath);

    gSoap = soap::connection ();
    if (!gSoap)
    {
        showmessage ("No connection to the SOAP/PubServer service");
        return 0;
    }

    doUpload ("test_1.txt", "That is a test text.");

    return 0;
}


priint:comet InDesign® Plug-Ins, comet_pdf

comet.CSOAP.uploadFile

static char* download(
  SOAP soap,
  char* id,
  int* len,
  int* si_string)

Get the data of a SOAP/PubServer service. The data is identified using the ID under which it is recorded using upload. The call automatically reserves the required memory for the result. This memory must be deleted with release.

    #include "internal/types.h"
    :
    data_ptr = soap::download (gSoap, id, &result_len, &is_string);
    release (data_ptr);

Name Type Default Description
Return char*   Pointer to received data. The data must be deleted again using release.
soap SOAP - Valid connection to server
id String or char* - Data key under which the data is stored with the upload.
len int* - Output : Length of the data in bytes.
is_string int* - Output : Did we get binary data or a string?

0 : binary data. Do not use binary data in string functions like strcpy!

1 : char* data. The string a null terminated already.

Get the text stored above again from the server. Do not forget to test the fetched contents, to see if it is a string. And do not forget to delete the fetched contents again from the memory using release. 

#include "internal/types.h"

SOAP		gSoap		= soap::connection ();

int doDownload (char * id, char ** content)
{
    char	*	result;
    int			result_len;
    int			is_string;

    *content = 0;
    result = soap::download (gSoap, id, &result_len, &is_string);
    if (result)
    {
        if (is_string) *content = result;
        else release (result);
    }

    return 1;
}


int main ()
{
    char	*	string_content;

    gSoap = soap::connection ();
    if (!gSoap)
    {
        showmessage ("No connection to server.");
        return 0;
    }

    doDownload ("test_1.txt", &string_content);
    if (!string_content)
    {
        showmessage ("No data found");
        return 0;
    }

    showmessage ("<%s>", string_content);
    release (string_content);

    return 0;
}


priint:comet InDesign® Plug-Ins, comet_pdf

comet.CSOAP.download

static int download_config(
  char* folder = 0,
  int showFolder = 0,
  int showError = 0)

Download all config files of the current SOAP/PubServer connection to an XML offline folder.

A priint:comet Developer license is needed to download SOAP/PubServer configurations.

An active SOAP/PubServer connection is required for the export! In comet_pdf and Illustrator the command is available, but always returns the error -1199.

[since v4.2 R33233] The function automatically checks all loaded actions and recursively loads all used Includes of the types [soap], [<soap>], [.soap_] and [pubserver] to the subfolder scripts/soap. The includes in the scripts are modified accordingly.

#include "[soap]/actions/0.crpt" becomes:

#include "[xml]/scripts/soap/actions/0.crpt"

Attention I : Some installations use the styleID attribute of the placeholder definitions differently from the default. Actually, this attribute is used as follows:

Of course, it is not a good idea at all to use the attribute contrary to this definition. Unfortunately, it is done anyway. The test case contained 15,000 (sic!) placeholders, each with different styleIDs. None of these IDs actually had an action defined (maybe better that way!). But that a script is empty, of course, we have to test first. These tests are fast, but 15,000 * 1/10 second is still more than half an hour. To avoid this, we do not export the actions used in the styleID of text placeholders! If you use string comparison scripts, please declare them correctly in actions.xml!

Attention II :Includes with the extenstion .c are also imported as described above. However, these scripts usually contain cScript code for calling Java methods of a PubServer Java plugin directly from from this script. This is of course not executable in XML-Offline!

Name Type Default Description
Return int   0 or Error Code



1268 : No priint:comet Developer license
path String oder char* 0 Destination folder for data export.

0 or "" : The destination folder is requested via folder dialog.

Otherwise : Valid and complete path of the destination folder. If the folder does not exist it will be created automatically.
showFolder int 0 Should the destination folder be shown automatically in Finder/Windows Explorer after export?

0 : No
1 : Yes
showError int 0 Should an error message be shown automatically in case of any export error?s

0 : No
1 : Yes

v4.2 R33140, 28. Jun 2023

priint:comet InDesign® Plug-Ins

static int download_tofile(
  SOAP soap,
  char* id,
  char* path,
  char* name = 0,
  char* type = 0,
  char* creator = 0)

Get data from the SOAP/PubServer service. The data are identified by means of the ID under which they were booked with upload, and stored as files.

Name Type Default Description
Return int   0 or ErrorCode
soap SOAP - Valid SOAP/PubServer connection
id String or char* - Data key under which the data was stored with upload.
path String or char* - Target path for the file. If the folder does not exist, it will be automatically created.
name String or char* 0 Name of the file. If the specification is absent, the data name stored in the SOAP/PubServer service (id) will be used.
type String or char* 0 File type (Macintosh). If a string is specified, it must be exactly 4 characters long. If the specifications for type and creator are missing, they will be ascertained from the suffix of the file.
creator String or char* 0 File Creator (Macintosh). If a string is specified, it must be exactly 4 characters long. If the specifications for type and creator are missing, they will be ascertained from the suffix of the file.

Get the file stored under ID colors.xml from the server 

SOAP		gSoap		= soap::connection ();

int doDownload (char * id, char * path)
{
    int		err;
    err = soap::download_tofile (gSoap, id, path);
    return err;
}

int main ()
{
    gSoap = soap::connection ();
    if (!gSoap)
    {
        showmessage ("No connection to the SOAP/PubServer service");
        return 0;
    }

    doDownload ("colors.xml", "/Users/paul/Desktop/aaaa/bbb");

    return 0;
}


priint:comet InDesign® Plug-Ins, comet_pdf

static int upload_metadata(SOAP soap, char* path)

Filing of all the description data for placeholders, scripts , ... .for the Werk II plugins

Name Type Default Description
Return int   0 or ErrorCode
soap SOAP - Vallid SOAP/PubServer connection
path String or char* - Path of the description data

The example uploads all required files of the current data folder (Menu Plug Ins -> Data folder ...) to the server. Pageitems are not stored (for more see upload_pageitems). 

#include "internal/types.h"

SOAP		gSoap		= soap::connection ();

int main ()
{
    char	xmlpath [4096];
    int		res;

    gSoap = soap::connection ();
    if (!gSoap)
    {
        showmessage ("No connection to the SOAP/PubServer service");
        return 0;
    }

    xmlquery::app_path (xmlpath);
    res = soap::upload_metadata (gSoap, xmlpath);
    if (res) showmessage (serror (res));

    return 0;
}


priint:comet InDesign® Plug-Ins, comet_pdf

upload_pageitems
comet.CSOAP.uploadData
comet.CSOAP.uploadFile

static int upload_pageitems(SOAP soap, char* path)

Upload all pageitems to the server.

Name Type Default Description
Return int   0 or ErrorCode
soap SOAP - Valid SOAP/PubServer connection
path String or char* - Path of the description data

The example uploads all required files of the current data folder (Menu Plug Ins -> data folder ...) to the server. 

#include "internal/types.h"

SOAP		gSoap		= soap::connection ();

int main ()
{
    char	xmlpath [4096];
    int		res;

    gSoap = soap::connection ();
    if (!gSoap)
    {
        showmessage ("No connection to the SOAP/PubServer service");
        return 0;
    }

    xmlquery::app_path (xmlpath);
    res = soap::upload_pageitems (gSoap, xmlpath);
    if (res) showmessage (serror (res));

    return 0;
}


priint:comet InDesign® Plug-Ins, comet_pdf

upload_metadata
comet.CSOAP.uploadData
comet.CSOAP.uploadFile

static int upload_folder(
  SOAP soap,
  char* path,
  char* idbase)

All files of the specified folder and all its sub-folders are uploaded to the server.

Name Type Default Description
Return int   0 or ErrorCode
soap SOAP - Valid SOAP/PubServer connection
basepath String or char* - Complete system path to the folder
idbase String or char* "" Base for the ID of the SOAP record. If the string is not empty, a "/" will be automatically appended.


priint:comet InDesign® Plug-Ins, comet_pdf

comet.CSOAP.uploadFolder

static Query call(SOAP soap, char* method)

Create a new transaction query for calls to the generic SOAP operation "call".

The result consists of exactly one char* row.

Name Type Default Description
Return Query   new query
soap SOAP - current SOAP connection
method String or char* - method/statement to execute

See getlist


priint:comet InDesign® Plug-Ins, comet_pdf

static Query getlist(SOAP soap, char* method)

Create a transaction for the SOAP operation getList.

Calling soap::getlist is the same like sql::new_query followed by query::send (qu, "getlist Methodenname");
On other connection types it compares to a call to soap::call sql::new_query.
See examples below. Take care of the following :

The methods returns exactly the rows needed to load the product pool panel. For more information see here..

Name Type Default Description
Return Query   new query Check the result against 0 in all cases!
soap SOAP - Valid database connection
method String or char* - SOAP method to execute

Example 1: soap::call and soap::getlist with SOAP as SQL Proxy 

  Query qu;
//  a)
  qu = sql::new_query ();
  query::send (qu, "DELETE FROM actions WHERE id = ?");
//  ... conform to
  qu = soap::call ("sql.dml");
  query::send (qu, "DELETE FROM actions WHERE id = ?");
//  ... or
  qu = sql::new_query ();
  query::send ("call sql.dml DELETE FROM actions WHERE id = ?");
// (Statements beginning with UPDATE, INSERT, COMMIT,
// EXECUTE,DROP or ALTER are too, of course


//  b)
  qu = sql::new_query ();
  query::send (qu, "SELECT COUNT(id) FROM actions");
//  ... conform to
  qu = soap::getlist ("sql");
  query::send ("SELECT COUNT (id) FROM actions");
//  ... or
  qu = sql::new_query ();
  query::send ("getlist sql SELECT COUNT (id) FROM actions");

Beispiel 2: soap::call and soap::getlist on generic calls 

//  a)				
  qu = sql::new_query ();
  query::send ("call MyMethod some arguments");
//  ... conform to
  qu = soap::call ("MyMethod");
  query::send (qu, "some arguments");
// b)
  qu = sql::new_query ();
  query::send ("getlist MyMethod some arguments");
//  is the same like:
  qu = soap::getlist ("MyMethod");
  query::send (qu, "some arguments");

Beispiel 3: Calling of other SOAP methods 

//  Calling getProductList				
  qu = sql::new_query ();
  query::send ("getProductList i = ? AND j = ? etc.");
// This conforms to the following calls too : 
//   getSubProductList, getElementList, autoCometGetNextJob,
//   autocometSetStart, autocometSetDone, autocometSetStatus and
//   autocometGetNextHotfolder
// Take care to bind the appropriate result columns against the calls!


priint:comet InDesign® Plug-Ins, comet_pdf

static int setlanguage(SOAP soap, char* language)

Set the connection language.

Name Type Default Description
Return int   Errorcode oder 0
soap SOAP - Valid SOAP/PubServer connection
language String or char* - the language

set the connection language 

#include "internal/types.h"

SOAP		gSoap		= soap::connection ();

int main ()
{
    int		res;
    gSoap = soap::connection ();
    if (!gSoap)
    {
        showmessage ("No connection to SOAP/PubServer service");
        return 0;
    }

    res = soap::setlanguage (gSoap, "enEN");
    return res;
}

Plugin Version 3.1 R2212

priint:comet InDesign® Plug-Ins, comet_pdf

static char* getmessage(SOAP soap, int resultCode)

Get description for a result or errorcode.

Name Type Default Description
Return char*   pointer to result string

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.
soap SOAP - Valid SOAP/PubServer connection
resultcode int - error or result code

get description of result code "17" 

#include "internal/types.h"

SOAP		gSoap		= soap::connection ();

int main ()
{
    int		res = 0;
    char*	msg;

    gSoap = soap::connection ();
    if (!gSoap)
    {
        showmessage ("no connection to SOAP/PubServer service");
        return 0;
    }

    msg = soap::getmessage (gSoap, 17);
    if (msg != 0) showmessage ("description for result code 17: '%s'", msg);

    return res;
}

Plugin Version 3.1 R2212

priint:comet InDesign® Plug-Ins, comet_pdf

Author
Paul Seidel
Version
13.11.2023, 10:13 Uhr
Since
Plugin Version 1.1.9 (2 May 2005)

Alphabetic index HTML hierarchy of classes or Java