Java Rendering Library 4.3-R34458 : Executing Scripts

Overview

Scripts are the most powerful way to utilize the capabitlities of the pdf renderer or priint:comet Plug-Ins. Any script implemented in cscript or Python can be executed via the Java Rendering Library.

Execute Scripts

There are 2 methods to execute a cscript in a document context:

• OpenedDocument.execScript
• OpenedDocument.execScriptCode

Execute predefined Actions

// run a script defined in the comet project associated to this document.
// Scripts are referred by their ID, so let's assume there is a suitable
// script with ID=17
int     scriptId = 17;
String   scriptArguments = "";

try (OpenedDocument document = Renderer.openDocument("DSN", new TmpCopyFromString("w2mlString", W2MLDocumentType.class))) {
  String scriptResult = document.execScript(scriptId, scriptArguments);
}
catch (RendererException e) {
  // Exceptions during opening or script execution 
}
catch (Exception e) {
  // Exception during auto-close
}

Script execution specifics are similar to the behavior we already know from InDesign® Server or "classic" PDF Renderer:

• the value provided as scriptArgument is defined in cscript as a global const char * variable named gArgument
• return value can be copied to the global variable char * gOutput. Maximum length is 32767 characters (32M)
• execScript returns the value of gOutput as a Java String
• NEW: scripts should always return a result code. 0 (zero) indicates successful execution of the script, any other value indicates an error and is translated to the appropriate Java Exception. Always.
• NEW: syntax errors in scripts will cause Exceptions such as UndefinedIdentifierException, UnexpectedEndOfFileException etc., which might give a hint, what exactly is going wrong.

Script Arguments

The following example prints the String passed as scriptArgument to stdout:

import com.priint.comet.renderer.Renderer;
import com.priint.comet.renderer.internal.OpenedDocument;
// ...
String scriptCode = "int main() { showmessage(\"%s\", gArgument); return 0; }";
try (OpenedDocument document = ((Renderer) renderer).openDocument("DSN", new TmpCopyFromString("w2mlString", W2MLDocumentType.class))) {
  String scriptResult = document.execScriptCode(scriptCode, "Hello World");
}
catch (RendererException e) {
  // Exceptions during opening or script execution
}
catch (Exception e) {
  // Exception during auto-close
}

Script Result

The result type of execScript / execScriptCode methods is a Java String, which can be set in the target cscript via copying characters to the global variable gOutput. Maximum length is 32767 characters (+ terminating zero).

String scriptCode = "int main() { strcpy(gOutput, gArgument); return 0; }";
try (OpenedDocument document = ((Renderer) renderer).openDocument("DSN", new TmpCopyFromString("w2mlString", W2MLDocumentType.class))) {
  String scriptResult = ((OpenedDocument)document).execScriptCode(scriptCode, "Hello World");
  // scriptResult should be "Hello World"
}
catch (Exception e) {
  // ... 
}

Script Return Code

cscripts are supposed to return a result code:

• 0 (zero) to indicate successful execution
• other values to indicate errors

Each (known) result code is translated to an appropriate Java Exception, see here for a list of known error codes.

String scriptCode = "int main() { return 1219; }";
try (OpenedDocument document = ((Renderer) renderer).openDocument(
                                  "DSN", 
                                  new TmpCopyFromString("w2mlString", W2MLDocumentType.class))) {
  document.execScriptCode(scriptCode, "");
}
catch (PageNotFoundException e) {
  // Error code for PageNotFoundException is 1219.
  // See Plugin documentation or ErrorCode class in 
  // Java Rendering Library for error code reference.
}
catch (RendererException e) {
  // Other exceptions during opening or script execution 
}
catch (Exception e) {
  // Exception during auto-close
}