CIB runShell technischer Leitfaden

Lieferumfang

Als ausführbares Konsolenprogramm (EXE)

Im Lieferumfang ist des Weiteren eine Hilfe und Anwendungsbeispiele enthalten.

Für die aktive Nutzung der CIB runshell müssen die zugehörigen CoMod-Dlls im Zugriff sein und lizenziert sein. Zusätzlich wird eine Beispiel-Konfigurationsdatei mit ausgeliefert.

Einführung

Die CIB runshell ist ein komfortables Kommandozeilentool. Darüber können alle CIB office Komponenten, die in Form von DLLs oder shared libraries ausgeliefert werden, angesteuert werden.

Mit der CIB runshell ist es insbesondere möglich alle Aufrufparameter ("Properties") zu setzen, die diese einzelnen CIB office Module zur Verfügung stellen.

Ebenso kann über die CIB runshell mit Hilfe einer Parameterdatei ein größerer Auftrag an mehrere verschiedene CIB office Module abgesetzt werden.

Die vorliegende Dokumentation gibt Ihnen einen schnellen Überblick über die Einsatzmöglichkeiten.

Installation

Windows

Das Konsolenprogramm cibrsh*.exe kann als eigenständiges Programm angewendet werden und wird dazu in das Verzeichnis der CoMod-Dlls kopiert. Die Konfigurationsdatei cibrsh.ini kann alternativ auch ins Windowsverzeichnis kopiert werden.

Zusätzlich besteht die Möglichkeit, mit dem Parameter „–i <Pfad>cibrsh.ini“, die Konfigurationsdatei direkt anzugeben.

Linux und Unix

Das Konsolen-Programm cibrshux kann als eigenständiges Programm verwendet werden, dazu kopiert man es ins Verzeichnis mit den CoMod-Libraries und setzt den Library-Path korrekt. Die Konfigurationsdatei cibrsh.ini kann man auch in dieses Verzeichnis kopieren oder alternativ mit dem Parameter „–i <Pfad>cibrsh.ini“ angeben.

Funktionsumfang

Versionen der CIB office Module (=CoMod) ausgeben

Ohne Aufrufparameter gibt die CIB runshell Informationen über die vorgefundenen CIB office Module auf dem Bildschirm aus. Es werden dann alle CIB office Module (wie zum Beispiel CIB format, CIB view, CIB merge, CIB rec, CIB r2h, CIB dialog, jeweils Dll-Version) gesucht und die gefundenen mit Versionsnummer, Erstellungsdatum, Installationsverzeichnis und Dateigröße ausgegeben.

Wenn in dem aktuellen Verzeichnis manche CIB Module nicht gefunden werden, dann wird alternativ in allen Verzeichnissen die über die (LIB)PATH Systemumgebungsvariablen zugänglich sind, nach vorhandenen CIB Modulen gesucht und diese entsprechend ausgegeben.

In Abbildung sehen Sie einmal den CIB print markiert, durch den Aufruf von cibrsh.exe bekommen Sie nun folgende Informationen: CIB print(= CIB format) ist als Version 5.3.176 installiert und wurde am 03.07.2006 erstellt. Ebenso kann man die Dateigröße mit 8769591 Bytes und das Installationsverzeichnis „D:\Source\COMod\bin\Debug\“ sowie den Dateinamen CibPrt32.dll ablesen.

CIB office Module ansteuern

Mit der CIB runshell kann jede CIB office Komponente gezielt angesteuert werden.

Alle über Kommandozeilenparameter und Konfigurationsdateien ansteuerbaren Funktionalitäten werden unterstützt.

Alle Stringproperties, alle numerischen Properties sowie alle Flags (boolsche Properties) können konfiguriert werden.

Mehrere Kommandos (auch gemischte CoMods) können mit einem einzigen Aufruf angestoßen werden, z.B. Mischen eines Dokuments mit CIB merge, Drucken des Ergebnisses mit CIB format/print sowie Konvertierung mit CIB format/pdf.

Die Parameter- und Kommandoübergabe kann auch über eine Parameterdatei erfolgen.

Besonderheiten

Insbesondere zur Massenverarbeitung großer Multi-RTF-Dateien mit CIB format/print ist die CIB runshell eine komplett fertige und einfach einzusetzende Steuerungsmöglichkeit.

Die CIB runshell unterstützt CIB format/print ab der Version 5.0.x

Java

Ebenso lässt sich die CIB runshell gut aus Java Anwendungen nutzen. Dafür steht Ihnen eine eigene JAVA Klasse zur Verfügung.

Beispiele siehe Kapitel „Schneller Einstieg“.

Kommandos und Parameter

Die nachfolgende Aufstellung zeigt alle verfügbaren Kommandos, die über die CIB runshell ausgeführt werden können.

Zusatzkommando

Die nachfolgende Aufstellung zeigt alle verfügbaren Zusatzkommandos, die über die CIB runshell ausgeführt werden können.

Aufrufsyntax

Allgemein gilt für den Aufruf der CIB runshell folgende Syntax:

cibrsh.exe [<Propertyname>=<Wert>] [-<Zusatzkommando>] [-<Kommando1> <Dateiname>
[<Dateiname>]] [<Propertyname>=<Wert>] [-<Kommando2> <Dateiname> [<Dateiname>]] ...

Ein Aufruf der CIB runshell besteht immer aus Property-Optionen und der Kommandooption (z.B. "–p") sowie keinem, einem oder zwei Dateinamen, je nach Kommando. Die Property-Optionen und die Dateinamen können auch in einer Konfigurationsdatei abgelegt werden. Dann wird die CIB runshell mit der Kommandooption „-i“ und Angabe der Konfigurationsdatei aufgerufen.

Mit der CIB runshell können mehrere Kommandos in einem Aufruf nacheinander ausgeführt werden.

Ruft man die CIB runshell ohne ein Argument auf, führt dies zur Ausgabe der verfügbaren CIB office Module und deren Versionsprüfung.

Konfigurationsdatei

Dateiformat

Die Konfigurationsdatei ist eine Textdatei. Die Informationen werden im INI-Dateiformat abgelegt, d.h. die Datei enthält Überschriften in eckigen Klammern, sogenannte Sektionen (=Sections) zu denen dann Texte unter einem Namen(=Key) und deren Wert(=Value) abgelegt werden.

Abbildung der Property-Typen

Namen von Sections und Keys

Die Namen der Sections in der ini-Datei richten sich nach den CIB office Modulen, deren Properties gesetzt werden sollen. Die Namen der Key sind die Strings, die zur Bezeichnung der Properties in der zugehörigen Headerdatei (.h) definiert sind.

[section]

key = <value> 

Beispiel für Konfigurationsdatei

Das Beispiel legt einen anderen Drucker als den Standarddrucker für CIB format/print fest. Diese Einstellung gilt auch für CIB view, da CIB view die CIB format-Einstellung verwendet. Außerdem werden Lizenzdaten gesetzt.

Datei cibrsh.ini im Windowsverzeichnis: 

[Print]
;Print 51
PrinterName=\\SERVER1\Fiery SI Copier-M v2015.108 QMS
 
; Print 50/16bit
CPRPrinterName=\\SERVER2\HPLASERJET4
 
LicenseCompany=CIB
;Testlizenz
LicenseKey=02450503630
 
[View]
CVWTitleString=CIB software Viewer

Funktionsweise

Folgende Abarbeitung der Aufrufparameter findet durch die CIB runshell statt:

Die CIB runshell setzt zunächst alle für das angegebene Kommando notwendigen Properties(das sind: Eingabedateiname, ggf. Ausgabedateiname und Ausgabeformat sowie weitere).
 Dann werden in der Windowsversion alle in der Registry festgelegten Properties ausgewertet. Dabei werden die Einträge unter „HKEY_CURRENTUSER\Software\CIB software GmbH“ ausgelesen.

Nun werden für alle Betriebssysteme die Properties aus der Konfigurationsdatei(Ini-Datei) und anschließend die in der Kommandozeile festgelegten Properties gesetzt.

Mit diesen Einstellungen wird dann das angegebene Kommando ausgeführt.

Schneller Einstieg

Aufruf der native CIB runshell aus Java mit Inifile für eine CIB pdf-Konvertierung

package de.cib.sample.comod;

import de.cib.comod.RunshellProcess;

boolean doRunshellProcess() {

	//RunshellProcess mit dem Executable erstellen
	RunshellProcess cibRunShell = new RunshellProcess("cibrsh.exe");
	//Eingabefilename
	String inputFileName = new String("Test.rtf");
	//Ausgabefilename
	String uniqueID = ""+System.currentTimeMillis();
	String outputFile = uniqueID+".pdf";
	//Property für das Arbeitsverzeichnis im CIB-Format
	//(z.B. für IncludePicture-Anweisungen) setzen 
	String sWorkspace = new String("c:\\test\\");
	cibRunShell.addProperty("WorkSpace",     sWorkspace);
	//IniFile mit dem Kommando -i setzen
	cibRunShell.addCommand("-i",  sWorkspace+"cibrsh.ini");
	//Kommando -f für die PDF-Konvertierung und Eingabe- sowie 	//Ausgabefilenamen setzen
	cibRunShell.addCommand(RunshellProcess.COMMAND_PDF,
	inputFileName, outputFile);
	try {
		//PDF-Konvertierung ausführen
		cibRunShell.executeAndWait(new File(sWorkspace));
	}
	catch(Exception ex) {
		System.out.println("Bei der Konvertierung mit CIB format "+
		"ist eine Exception aufgetreten.");
		return false;
	}
	//Fehlerbehandlung der Runshell
	int error = cibRunShell.getExitCode();
	if (error != 0) {
		System.out.println("CIB format-Fehler: " + error + 
		"bei der Ausführung von " + cibRunShell.getCommandLine() + 
		";");
		return false;
	}
	return true;
}

Aufrufbeispiel der CIB runshell aus Java und direkter Druck eines PDF-Dokuments

Um diese Beispiel auszuführen werden zwei weitere Klassen benötigt: RunshellProcess.java und Process.java .

import java.io.*;
import de.cib.comod.RunshellProcess;

public class DirectPrintPdf {
	public static void main(String[] args) {
		//PDF-Datei festlegen z.B. ein Test.pdf
		String inputFileName = new String("..\\Test.pdf");
		// neuen Runshell-Prozess starten
		RunshellProcess cibRunShell = new RunshellProcess("cibrsh.exe");
		//Druckernamen festlegen z.B. HP LaserJet 4100 Series PS
		cibRunShell.addArgument("PrinterName = \\\"" + "HP LaserJet 4100 Series PS" + "\\\"");
		//Ausgabeformat festlegen
		cibRunShell.addProperty("OutputFormat", "FormatPrinter");
		//Eingabedatei festlegen
		cibRunShell.addCommand(RunshellProcess.COMMAND_PDFJOIN, inputFileName);
		try {
			//Pfad zu den Libraries angeben und Prozess starten
			runshell.executeAndWait(new File("."));
		}
		catch(IOException io) {
			io.printStackTrace();
		}
		catch(InterruptedException inter) {
			inter.printStackTrace();
		}
}

CIB runshell-Beispiel: Aufruf der native CIB runshell aus Java für einen CIB merge-Mischlauf

package de.cib.sample.comod;
import de.cib.comod.RunshellProcess;

boolean doMergeRunshellProcess() {

		// neuen Runshell-Prozess starten
		String t_Workspace = new String("\home\user\");
		// cibrshux ist die CIB runshell unter Linux/Unix
		RunshellProcess runshell = new RunshellProcess("./bin/cibrshux");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE+"a./templates");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE+"q./Data");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE+"'l!merge.log'");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE+"iTest.rtf");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE +"'o!output.rtf'");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE+"s");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE+"-old-compare");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE+"dTest.csv");
		runshell.addArgument(RunshellProcess.COMMAND_MERGE+"@1");
		try
		{
			// Pfad zu den Libraries angeben und Prozess starten
			runshell.executeAndWait(new File(t_Workspace));
		}
		catch(IOException io)
		{
			System.out.println("Beim Mischen mit CIB merge "+
			"ist eine Exception aufgetreten.");
			return false;
		}
		catch(InterruptedException inter)
		{
			System.out.println("Beim Mischen mit CIB merge "+
			"ist eine Exception aufgetreten.");
			return false;
		}
	// Fehlerbehandlung der CIB runshell
	int error = cibRunShell.getExitCode();
	if (error != 0) {
		System.out.println("CIB merge-Fehler: " + error + 
		"bei der Ausführung von " + cibRunShell.getCommandLine() + 
		";");
		return false;
	}
	return true;
}

Aufrufbeispiel der CIB runshell aus Java und ausführen von IsPadAvailable

Um diese Beispiel auszuführen werden zwei weitere Klassen benötigt: RunshellProcess.java und Process.java .

import java.io.*;
import de.cib.comod.RunshellProcess;

public class PadAvailable {
	public static void main(String[] args) {
		// neuen Runshell-Prozess starten
		RunshellProcess runshell = new RunshellProcess("cibrsh.exe");
		runshell.addCommand("-ua", "");
		try {
			//Pfad zu den Libraries angeben und Prozess starten
			runshell.executeAndWait(new File("."));
		}
		catch(IOException io) {
			io.printStackTrace();
		}
		catch(InterruptedException inter) {
			inter.printStackTrace();
		}
		//Wenn der ExitCode 0 ist wurde ein Pad gefunden
		if (runshell.getExitCode() != 0) {
			System.out.println("no pad available");
			System.out.println("exit with code  " + runshell.getExitCode());
		}
		else {
			System.out.println("pad found");
		}
	}
}

PadAvailable.java

Aufrufbeispiel der CIB runshell über ein Script aus Java

import java.lang.Runtime;
import java.io.*;
import java.lang.*;

public class ScriptExec {

    public static void main(String[] args){
    	System.out.println("start");
    // TODO implement Main.main
    	Runtime t_RunTime = Runtime.getRuntime();
    	if (t_RunTime != null)
    	{
	    	String[] t_cmdarray = new String[2];
		//Angabe das aufzurufenden Scripts
	    	t_cmdarray[0] = new String("./TestScript.sh");
		//Argument fuer das Script mit Leerzeichen
	    	t_cmdarray[1] = new String("DocInfo.Author=CIB support Team");
	    	
	    	try
	    	{
	    		//Script starten	
			Process t_Process = t_RunTime.exec(t_cmdarray);
			int t_Result = t_Process.waitFor();
		}
	    	catch (IOException exec)
	    	{
	    		System.out.println("IOException");
	   		exec.printStackTrace(); 
		}
		catch (InterruptedException interexec)
		{
			System.out.println("InterruptedException");
                        interexec.printStackTrace();	
		}
    	}
    }
}

ScriptExec.java

#/bin/sh
LD_LIBRARY_PATH=. ./cibrshux "$1" -f input.rtf output.pdf

TestScript.sh aus Linux/Unix

Returnwert und Fehlerbehandlung

Returnwert

Der Errorlevel/Exitcode des EXE-Aufrufs entspricht dem Fehlercode des ausgeführten Moduls bzw. dem Fehlercode des Betriebssystems.
Zum Beispiel wenn das notwendige Modul nicht geladen werden konnte oder fehlt, bekommt man unter WIN32 den Rückgabewert 126.
Der Rückgabewert 198 ist für jede Art von unerwarteter Ausnahme reserviert, die während der Ausführung des Befehls auftritt(zum Beispiel ein Absturz in der CIB print-Dll).

Fehlerbehandlung

Aufgetretene Fehler werden mit der Fehlernummer und dem Fehlertext auch in der Konsole ausgegeben.

Ein Fehlercode größer 0 bedeutet, dass ein Problem aufgetreten ist und das Kommando nicht ordentlich zu Ende geführt wurde. Nachfolgende Kommandos werden nicht ausgeführt, wenn bei einem Kommando ein Fehler aufgetreten ist.

Konsultieren Sie zur Fehlerbehebung die entsprechenden Abschnitte der Dokumentation des aufgerufenen Moduls.