Mit Release 9.11 wird es ermöglicht, auf die Schriftgut-Variablen (SGPV) von zur Laufzeit bekannten Schriftgut-Instanzen zuzugreifen.

Die Klasse ExposedVariablesSupport enthält eine Liste der in dem jeweiligen Schriftgut bekannten Schriftgut-Variablen.

In dem Abschnitt Von KnowlEdge zu CTV-nativeApi wird das Zusammenspiel zwischen der Definition der SGPV-Nutzung in KnowlEdge und der Bereitstellung als ExposedVariable beschrieben.

Abgeleitet von: ExposedVariablesSupport

Jeweils eigene, von ExposedVariablesSupport abgeleitete Klassen werden in der Basis-Assembly erstellt für
- Schriftstücke: ExposedVariablesForSchriftstueck
- Schriftsätze: ExposedVariablesForSchriftsatz
- Massenlisten: ExposedVariablesForMassenliste
- Bündel: ExposedVariablesForBuendel
- Statische Dokumente: ExposedVariablesForStaticDocument
- Instanzen eines in der Basis-Assembly bekannten Schriftgut-Typs.

Hierin sind die ggf. für dieses Schriftgut definierten und zur Laufzeit relevanten Abweichungen in der Nutzung der Schriftgut-Variablen berücksichtigt.

Für Schriftgut, welches explizit in die Basis-Assembly hineingeneriert wurde, wird jeweils eine eigene Klasse ExposedVariablesFor<T> bereitgestellt, sofern in dem Schriftgut Schriftgut-Variablen abweichend definiert sind. Relevant für Abweichende Definitionen ist hier zur Zeit nur die Angabe ReadonlyAtRuntime.

Diese Typen können z.B. ein einer Switch-Anweisung abgefragt werden, um Schriftgut-Variablen abhängig vom der Art des Schriftguts abzufragen oder zu bestücken:

foreach (var sgut in this.Ctv.Documents) {
  switch (sgut.ExposedVariables) {
  case ExposedVariablesForSzAnfrage varsAnfrage:
    varsAnfrage.Lnr.Value = //...;
    varsAnfrage.AnzDup.Value = //...;
    break;
  case ExposedVariablesForSchriftsatz varsSstz:
    varsSstz.Lnr.Value = //...;
    break;
  case ExposedVariablesForBuendel _:
  case ExposedVariablesForMassenListe _:
  case ExposedVariablesForStaticDocument _:
    break;
  case ExposedVariablesForSchriftstueck varsSstk:
    varsSstk.DokTypK.Value = //...;
    break;
  }
}

Liefert die unter dem Namen bekannte Schriftgut-Variable als Instanz der Klasse ExposedVariable<T>.

ExposedVariable<T> <name> { get; }

Für jede Schriftgut-Variable wird in ExposedVariables<T> eine Instanz entweder der Klasse ExposedVariable<T> oder ExposedVariableReadonly<T> erstellt, abhängig von der Angabe „Änderbar zur Laufzeit“. Über Intellisense® können die Schriftgut-Variablen der Klasse angezeigt werden:

ExposedVariable<T>[] <name> { get; };

Eine Besonderheit gilt für Variablen, die anhand ihrer Namensgebung eine Liste bilden, z.B.
DYN-PLATZHALTER-LNR-1 … DYN-PLATZHALTER-LNR-3,
POST-ANS-ZL, POST-ANS-ZL-2 … POST-ANS-ZL9.

Hier liefert ExposedVariables ein Array, welches mit Index referenziert werden muss.

// Beispiel für indizierte Variablen, genutzt für Original und Kopien:
for (var i = 0; i < sstkVars.CtvSortDatn.Length; i++) {
    var sortdat = sstkVars.CtvSortDatn[i];
    sortdat.Value = //...;
    foreach (var copy in sstkVars.Copy) {
        sortdat = copy.CtvSortDatn[i];
        sortdat.Value = //...;
    }
}

Vergleich mit Definition in KnowlEdge

Falls für das Schriftgut Schriftgut-Variablen definiert sind, die getrennt für Original und Kopien bestückt werden können, enthält die Klasse zusätzlich ein Array „Copy“ der Klasse ExposedVariablesFor<T>Copy.

In der Definition von SGPVs sind diese Variablen daran zu erkennen, dass der Maximalindex > 0 ist. Wenn für eine Variable ein MinIndex > 0 angegeben ist, so ist die Variable nur in den Copy-Instanzen der ExposedVariables zu finden.

ExposedVariableSupport Copy[<index>] { get; }

sstkVars.Copy[0].DokEmpfZusTxt = //...
foreach (var copy in sstkVars.Copy) {
    copy.VsanArtK = //...;
}

Vergleich mit Definition in KnowlEdge

Abgeleitet von: ExposedVariablesFor<T>

Hier die Ansicht CTV-Attribute in KnowlEdge:

Die Angabe „Änderbar zur Laufzeit“ entscheidet darüber, ob eine Variable über die native-Api änderbar ist.

Für jede Schriftgut-Variable wird in ExposedVariables<T> eine Instanz entweder der Klasse ExposedVariable<T> oder ExposedVariableReadonly<T> erstellt, abhängig von der Angabe „Änderbar zur Laufzeit“.

Dadurch kann bereits zur Entwurfszeit über Intellisense® festgestellt werden, ob der Wert der Variablen zur Laufzeit verändert werden darf. Ausnahmen:

• Mehrere Instanzen einer Schriftgut-Variablen
• Wenn „Änderbar zur Laufzeit“ für ein Schriftgut abweichend vom Standard definiert ist, kann dies nur dann zur Entwurfszeit festgestellt werden, wenn das Schriftgut in der Basis-Assembly enthalten ist: Schreibende Zugriffe auf eine in dem betreffenden Schriftgut schreibgeschützte Variable führen zur Laufzeit-Conditions. Umgekehrt wird dann die Bestückung von einer im Schriftgut änderbaren Variablen verhindert.

Es gibt zwei Definitionsarten, um mehrere Instanzen einer Schriftgut-Variablen zu erhalten: Als implizite Liste, oder für Original und Kopien.

Wie in obiger Abbildung gezeigt, können die beiden Definitionen kombiniert werden: Eine implizite Liste kann wiederum Variablen für Original und Kopien enthalten, sodass eine zweidimensionale Struktur entsteht.

Bei Schriftgut-Variablen, die in der mdb mit einem Maximal-Index > 0 definiert sind, ist festgelegt, dass die Instanz mit dem Index 0 für das Original eines Dokuments verwendet wird, die Instanzen mit höheren Indizes für die jeweiligen Kopien.

Die Struktur innerhalb der Klasse ExposedVariables spiegelt dies wieder:

• Direkt in der Klasse ExposedVariables<T> enthalten sind die Schriftgut-Variablen ohne getrennte Definition für Kopien sowie die für das Original.
• Daneben enthält ExposedVariables<T> ein Array der Klasse ExposedVariables<T>Copy, welches die Schriftgut-Variablen enthält, die für die Dokumentkopien gelten. Das Array enthält so viele Einträge wie der höchste in der mdb angegebene Maximalindex.
• Wenn für eine Variable ein Minimalindex > 0 festgelegt ist, so existiert diese Variable nur in der Copy-Klasse.

Da der Index für Copy, wie in C# üblich, nullbasiert ist, ergibt sich der dort um eins geringere Wert als für den Index im Pseudocode, d.h. die Variablen für die 1. Kopie sind in Copy[0] enthalten.

Aufgrund der Definition als Copy-Array sind in Ausnahmefällen fehlerhafte Nutzungen möglich, die allerdings zur Laufzeit überprüft werden und dort ggf. zu Conditions führen:

• Wenn für eine Variable ein geringerer Maximalindex festgelegt ist, als es Copy-Instanzen gibt, führt dies bei Zugriff mit unzulässigem Index zu einer Condition.
• In KnowlEdge ist es möglich, pro Kopie festzulegen, ob eine Variable schreibgeschützt ist oder nicht („Änderbar zur Laufzeit“). Dies kann zur Entwurfszeit nicht überprüft werden. Wenn eine der Kopien der Variablen änderbar ist, werden alle Kopien als ExposedVariable<T> erzeugt; eine unzulässige Bestückung wird in dem Fall erst zur Laufzeit festgestellt.

In der mdb sind diverse SGPVs definiert, die anhand ihrer Namensgebung eine Liste bilden, z.B
BEN-ID-1, BEN-ID-2
CTV-SORT-DATN, CTV-SORT-DATN-2, …, CTV-SORT-DATN-6
LIST-FELD, LIST-FELD-2, …, LIST-FELD-10

Dabei ist es unerheblich, ob das erste Vorkommen die Ziffer 1 beinhaltet; sowohl LIST-FELD als auch BEN-ID-1 werden als 1. Element der jeweiligen Liste erkannt.

Diese Schriftgut-Variablen werden in CTV nativeApi als Array dargestellt. So wird aus

Da der Index wie in C# üblich nullbasiert ist, ergibt sich auch hier bei der Referenz auf ein Listenelement der um eins geringere Wert im Index gegenüber dem Namen der Variablen in der Definition und im Pseudocode, z.B. „LIST-FELD-5“ entspricht „ListFeld[4]“, „BEN-ID-2“ entspricht „BenId[1]“.

Aufgrund der Definition als Array sind in Ausnahmefällen fehlerhafte Nutzungen möglich, die allerdings zur Laufzeit überprüft werden und dort ggf. zu Conditions führen:

• In KnowlEdge ist es möglich, pro SGPV in einer solchen Liste unterschiedliche Eigenschaften festzulegen, u.a. abweichende Angaben für „Änderbar zur Laufzeit“. Dies kann zur Entwurfszeit nicht überprüft werden: Wenn eine der Variablen in der Liste änderbar ist, werden alle Listenelemente als ExposedVariable<T> erzeugt.

Besonders zu beachten ist die unterschiedliche Nutzung des Index beim Zugriff auf Schriftgut-Variable: im Pseudocode gibt der Index einer SGPV die Nummer der Kopie an, hier aber wird mit dem Index der SGPV der Eintrag in einer impliziten Liste ausgewählt, während die Schriftgut-Variablen für Kopien über Copy[<index>].<name> referenziert werden.

Beispiel einfache Abfrage und Bestückung:
Pseudocode:

if ctvSstk.EVALUATED = "N" 
then
    ctvSstk.DDA-IGNORE-KZ = "J"
end if	

CTV nativeAPI:

if (sstk_vars.Evaluated.Value == "N") {
    sstk_vars.DdaIgnoreKz.Value = "J";
}

Beispiel Bestückung Original und 1. Kopie aus SGPV eines Schriftsatzes:
Pseudocode:

if CTVSSTZ.VSAN-SRT-HER != ""
then
    ctvSstk.VSAN-SRT-HER = ctvSstk.VSAN-SRT-HER
    ctvSstk.VSAN-SRT-HER[1] = ctvSstk.VSAN-SRT-HER
end if

CTV nativeAPI:

if (sstz_vars.VsanSrtHer.Value != 0) { // nummerisch, da Wert aus Schlüsseltabelle 
    sstk_vars.VsanSrtHer = sstz_vars.VsanSrtHer;
    sstk_vars.Copy[0].VsanSrtHer = sstz_vars.VsanSrtHer;
}

Beispiel Abfrage einer Variablen als nummerisch:
Pseudocode:

if ctvSstz.ANZ-DUP > 1			// implizite Typkonvertierung 
then
    ctvSstk.VWEG-K[2] = ctvSstk.vweg-k
    ctvSstk.VSAN-ART-K[2] = ctvSstk.VSAN-ART-K
end if

CTV nativeAPI:

if (int.Parse(sstk_vars.AnzDup.Value) > 1) {	// explizite Typkonvertierung
    sstk_vars.Copy[1].VwegK = sstk_vars.VwegK;
    sstk_vars.Copy[1].VsanArtK = sstk_vars.VsanArtK;
}

Bestückung einer impliziten Liste für Original und eine Kopie:
Pseudocode:

// bestücke sgpv-variablen für das orginal
ctvSstk.CTV-SORT-DATN = LCTVSOR.NST-CTV-SORT-DATN
ctvSstk.CTV-SORT-DATN-2 = LCTVSOR.NST-CTV-SORT-DATN-2
ctvSstk.CTV-SORT-DATN-3 = LCTVSOR.NST-CTV-SORT-DATN-3
// ...
// bestücke sgpv-variablen für die erste Kopie
ctvSstk.ctv-sort-datn[1] = lctvsor.nst-ctv-sort-datn
ctvSstk.ctv-sort-datn-2[1] = lctvsor.nst-ctv-sort-datn-2
ctvSstk.ctv-sort-datn-3[1] = lctvsor.nst-ctv-sort-datn-3
// ...

CTV nativeAPI:

sstk_vars.CtvSortDatn[0].Value = lctvSor.NstCtvSortDatn;
sstk_vars.CtvSortDatn[1].Value = lctvSor.NstCtvSortDatn2;
sstk_vars.CtvSortDatn[2].Value = lctvSor.NstCtvSortDatn3;
// ...
sstk_vars.Copy[0].CtvSortDatn[0].Value = lctvSor.NstCtvSortDatn;
sstk_vars.Copy[0].CtvSortDatn[1].Value = lctvSor.NstCtvSortDatn2;
sstk_vars.Copy[0].CtvSortDatn[2].Value = lctvSor.NstCtvSortDatn3;
// ...

Bestückung einer impliziten Liste für Original und Kopien, mit Modulaufruf zur Ermittlung der Werte:
Pseudocode:

do sortierschleife vary copyIndex from 0 by 1 to 3
   if (copyindex = 0)
   then
      ctsosy.VWG-VWEG-K = ctvSstk.VWEG-K
      call efun service ctn-sortier-var-erm in ctv.durchfuehren 
        with ctsosy = ctsosy 
        and  ctvsort = lctvsor
      end call
      ctvSstk.CTV-SORT-DATN   = LCTVSOR.NST-CTV-SORT-DATN
      ctvSstk.CTV-SORT-DATN-2 = LCTVSOR.NST-CTV-SORT-DATN-2
      ctvSstk.CTV-SORT-DATN-3 = LCTVSOR.NST-CTV-SORT-DATN-3
      // ...
   else
       ctsosy.VWG-VWEG-K = ctvSstk.VWEG-K[copyindex]
       call efun service ctn-sortier-var-erm in ctv.durchfuehren 
        with ctsosy = ctsosy 
        and  ctvsort = lctvsor
       end call
      ctvSstk.CTV-SORT-DATN[copyindex]   = LCTVSOR.NST-CTV-SORT-DATN
      ctvSstk.CTV-SORT-DATN-2[copyindex] = LCTVSOR.NST-CTV-SORT-DATN-2
      ctvSstk.CTV-SORT-DATN-3[copyindex] = LCTVSOR.NST-CTV-SORT-DATN-3
    // ...
   end if
end sortierschleife

CTV nativeAPI:

var callCtnSortVarErm = Call.CtnSortierVarErm.Durchfuehren;
callCtnSortVarErm.Ctsosy = ctsosy;
callCtnSortVarErm.Ctvsort = ctsort;
ctsosy.VwgVwegK = sstk_vars.VwegK.Value;
callCtnSortVarErm.Run();
sstk_vars.CtvSortDatn[0].Value = lctvSor.NstCtvSortDatn;
sstk_vars.CtvSortDatn[1].Value = lctvSor.NstCtvSortDatn2;
sstk_vars.CtvSortDatn[2].Value = lctvSor.NstCtvSortDatn3;
// ...
foreach (var copy in sstk_vars.Copy.Where(c => !string.IsNullOrEmpty(c.VwegK.Value))) {
    ctsosy.VwgVwegK = copy.VwegK.Value;
    callCtnSortVarErm.Run();
    copy.CtvSortDatn[0].Value = lctvSor.NstCtvSortDatn;
    copy.CtvSortDatn[1].Value = lctvSor.NstCtvSortDatn2;
    copy.CtvSortDatn[2].Value = lctvSor.NstCtvSortDatn3;
    // ...
}

Zusätzliches Beispiel: Wenn im Objekt ein Occurs eingefügt wird, kann in CTV-nativeApi die gesamte Bestückung in Schleifen abgearbeitet werden, da über die implizite Liste iteriert werden kann:

ctsosy.VwgVwegK = sstk_vars.VwegK.Value;
callCtnSortVarErm.Run();
for (var listindex = 0; listindex < sstk_vars.CtvSortDatn.Length; listindex++) {
    sstk_vars.CtvSortDatn[listindex].Value = lctvSor.NstCtvSortDatnTab[listindex];
}
foreach (var copy in sstk_vars.Copy.Where(c => !string.IsNullOrEmpty(c.VwegK.Value))) {
    ctsosy.VwgVwegK = copy.VwegK.Value;
    callCtnSortVarErm.Run();
    for (var listindex = 0; listindex < copy.CtvSortDatn.Length; listindex++) {
        copy.CtvSortDatn[listindex].Value = lctvSor.NstCtvSortDatnTab[listindex];
    }
}