cniElementAsBitstream

Ruft die Bitstromdarstellung des angegebenen Elements ab. Der dem Element zugeordnete Parser serialisiert das Element und alle untergeordneten Elemente. Das Ergebnis wird in den vom Aufrufenden zugeordneten Speicher kopiert. In dem besonderen Fall, dass alle angegebenen Optionen mit denen des ursprünglichen Bitstroms übereinstimmen, z. B. bei einem vom MQEmpfangsknoten aus einer WebSphere MQ-Warteschlange gelesenen Bitstrom, und die Nachricht seit dem Empfang des ursprünglichen Bitstroms nicht geändert wurde, wird dieser ursprüngliche Bitstrom in den zugeordneten Speicher kopiert. In diesem Fall wird der Parser nicht zum Analysieren und erneuten Serialisieren der Nachricht benötigt.

Der zum Erstellen des Bitstroms verwendete Algorithmus hängt vom verwendeten Parser und den angegebenen Optionen ab. Alle Parser unterstützen die folgenden Modi:
  • RootBitStream: In diesem Modus wird zur Bitstromgenerierung derselbe Algorithmus wie von einem Sendeknoten verwendet. Ein aussagekräftiges Ergebnis wird in diesem Modus nur erzielt, wenn sich das Element, auf das verwiesen wird, auf der obersten Ebene einer untergeordneten Baumstruktur mit der entsprechenden Struktur befindet.
  • EmbeddedBitStream: In diesem Modus wird zur Bitstromgenerierung nicht nur derselbe Algorithmus wie von einem Sendeknoten verwendet, sondern es werden auch die folgenden Merkmale, wenn nicht explizit angegeben, auf dieselbe Weise wie der Ausgabeknoten festgelegt. Das heißt, sie werden festgelegt, indem die vorhergehenden gleichgeordneten Elemente von element durchsucht werden, wobei vorausgesetzt wird, dass sie Header darstellen:
    • ENCODING
    • ID des codierten Zeichensatzes (CCSID)
    • Nachrichtengruppe
    • Nachrichtentyp
    • Nachrichtenformat

    Auf diese Weise ist der Algorithmus zur Bestimmung dieser Eigenschaften im Wesentlichen mit dem für die ESQL-BITSTREAM-Funktion verwendeten Algorithmus identisch.

Einige Parser unterstützen auch einen anderen Modus, FolderBitStream, in dem ein aussagefähiger Bitstrom für jede Unterverzeichnisstruktur generiert wird, vorausgesetzt das Feld, auf das gezeigt wird, stellt einen Ordner dar.

Syntax

CciSize cniElementAsBitstream(
  int*                       returnCode,
  CciElement*                element,
  const struct CciByteArray* value,
  CciChar*                   messageType,
  CciChar*                   messageSet,
  CciChar*                   messageFormat,
  int                        encoding,
  int                        ccsid,
  int                        options);

Parameter

returnCode
Der Rückkehrcode von der Funktion (Ausgabe). Wenn Sie einen NULL-Zeiger bei der Eingabe angeben, bedeutet der Wert, dass der Knoten keine Fehler behandeln kann. Ist eine Eingabe nicht NULL, bedeutet die Ausgabe den Erfolgsstatus des Aufrufs. Alle Ausnahmebedingungen, die bei der Ausführung dieses Aufrufs ausgegeben werden, werden beim nächsten vorgeschalteten Knoten im Nachrichtenfluss erneut ausgegeben. Rufen Sie cciGetLastExceptionData auf, um weitere Informationen zu der Ausnahmebedingung zu erhalten.
Mögliche Rückkehrcodes sind:
  • CCI_SUCCESS
  • CCI_EXCEPTION
  • CCI_INV_ELEMENT_OBJECT
  • CCI_INV_DATA_POINTER
  • CCI_INV_DATA_BUFLEN
  • CCI_INV_BUFFER_TOO_SMALL
element
Das Syntaxelement, das serialisiert werden soll (Eingabe).
value
Ein Zeiger zu einem CciByteArray-Struct, das einen Zeiger zu einem Speicherbereich enthält, der vom Aufrufenden zugeordnet wurde, sowie die Größe in CciBytes dieses Speichers (Ausgabe).
messageType
Die Nachrichtentypdefinition, die für die Erstellung des Bitstroms aus der Elementstruktur verwendet wird (Eingabe). Wenn Sie einen NULL-Zeiger angeben, wird der Parameter ignoriert. Der Parameter wird auch ignoriert, wenn der dem Element zugeordnete Parser diesen Wert nicht benötigt, beispielsweise wenn es sich um einen generischen XML-Parser handelt.
messageSet
Die Nachrichtengruppendefinition, die für die Erstellung des Bitstroms aus der Elementstruktur verwendet wird (Eingabe). Wenn Sie einen NULL-Zeiger angeben, wird der Parameter ignoriert. Der Parameter wird auch ignoriert, wenn der dem Element zugeordnete Parser diesen Wert nicht benötigt, beispielsweise wenn es sich um einen generischen XML-Parser handelt.
messageFormat
Das Format, das für die Erstellung des Bitstroms aus der Elementstruktur verwendet wird (Eingabe). Wenn Sie einen NULL-Zeiger angeben, wird der Parameter ignoriert. Der Parameter wird auch ignoriert, wenn der dem Element zugeordnete Parser diesen Wert nicht benötigt, beispielsweise wenn es sich um einen generischen XML-Parser handelt.
encoding
Die Codierung, die beim Schreiben des Bitstroms verwendet werden soll (Eingabe). Dieser Parameter ist obligatorisch. Es kann als Wert 0 angegeben werden, um zu anzuzeigen, dass die Verschlüsselung des Warteschlangenmanagers verwendet werden sollte.
ccsid
Die ID des codierten Zeichensatzes, die beim Schreiben des Bitstroms verwendet werden soll (Eingabe). Dieser Parameter ist obligatorisch. Wenn Sie den Wert 0 angeben, wird die ID des codierten Zeichensatzes (ccsid) des Warteschlangenmanagers verwendet. Wenn als ID des codierten Zeichensatzes -1 angegeben wird, bedeutet dies, dass der Bitstrom mithilfe der Informationen zur ID des codierten Zeichensatzes generiert werden soll, die in der untergeordneten Baumstruktur enthalten sind, die aus dem Feld besteht, auf das das Element sowie seine untergeordneten Elemente verweisen. Derzeit unterstützt keiner der bereitgestellten Parser diese Option.
options
Ganzzahliger Wert, der angibt, welcher Bitstromgenerierungsmodus verwendet werden soll. Legen Sie einen der folgenden Werte fest:
  • CCI_BITSTREAM_OPTIONS_ROOT
  • CCI_BITSTREAM_OPTIONS_EMBEDDED
  • CCI_BITSTREAM_OPTIONS_FOLDER

Rückgabewerte

  • Bei erfolgreicher Ausführung wird die korrekte Größe des für den Bitstrom erforderlichen Speichers zurückgegeben.
  • Wenn vom Aufrufenden nicht genügend Speicher zugeordnet wurde, wird returnCode auf CCI_BUFFER_TOO_SMALL gesetzt.
  • Wenn während der Ausführung eine Ausnahmebedingung auftritt, wird returnCode auf CCI_EXCEPTION gesetzt.

Beispiel

Im folgenden Beispiel wird dargestellt, wie die Optionsparameter verwendet werden können, um den Bitstrom für verschiedene Teile der Nachrichtenbaumstruktur zu erstellen.

Dieser Code kann in die Funktion _evaluate des Musterumwandlungsknotens kopiert werden. Für eine Eingabenachricht wie die folgende gilt:
MQMD
MQRFH2
<test><data><foo>text</foo></data></test>
der Knoten gibt drei Nachrichten weiter; eine mit einer Kopie der Eingabenachricht in der BLOB-Domäne, eine mit einer Kopie des Eingabe-MQRFH2 als Nachrichtenhauptteil in der BLOB-Domäne und eine mit dem Ordner <data></data> als Nachrichtenhauptteil in der BLOB-Domäne.
CciMessage*          outMsg[3];
  CciTerminal* terminalObject;
  CciElement*          bodyChild;
  CciElement*          inRootElement;
  CciElement*          inSourceElement[3];
  CciElement*          outRootElement;
  CciElement*          outBlobElement;
  CciElement*          outBody;
  struct CciByteArray  bitstream[3];
  int                  bitstreamOptions[3];
  int                  retvalue;
  int rc = 0;
  int                  loopCount;
  CCI_EXCEPTION_ST     exception_st = {CCI_EXCEPTION_ST_DEFAULT};
  const CciChar*       constBLOBParserName  =
                 cciString("NONE",BIP_DEF_COMP_CCSID);
  const CciChar*       constBLOBElementName = 
                 cciString("BLOB",BIP_DEF_COMP_CCSID);
  const CciChar*       constEmptyString     =                     
                 cciString("",BIP_DEF_COMP_CCSID);

  /*erstellt drei Ausgabenachrichten und gibt sie weiter*/
  /*erste Nachricht besitzt einen Bitstrom für den Hauptteil der Eingabenachricht*/
  /*zweite Nachricht besitzt einen Bitstrom für die Eingabe MQRFH2*/
  /*dritte Nachricht besitzt einen Bitstrom für das untergeordnete Element der Eingabenachricht*/

  /* Das Stammelement der Eingabenachricht abrufen */
  inRootElement=cniRootElement(&rc, message);
  /*CCI_CHECK_RC();*/
  checkRC(rc);

  /*den Bereich der Quellenelemente und Bitstromoptionen definieren*/

  /*Hauptteil einer Nachricht*/
  inSourceElement[0] =  cniLastChild(&rc,inRootElement);
  checkRC(rc);

  /*Dies ist das Stammverzeichnis des Hauptteils der Nachricht, deshalb wird der Modus 'RootBitStream' verwendet*/
  bitstreamOptions[0] = CCI_BITSTREAM_OPTIONS_ROOT;

  
  /*letzter Header*/
  inSourceElement[1] = cniPreviousSibling(&rc,inSourceElement[0]);
  checkRC(rc);

  /*Dies ist das Stammverzeichnis von MQRFH2, deshalb wird der Modus 'RootBitStream' verwendet*/
  bitstreamOptions[1] = CCI_BITSTREAM_OPTIONS_ROOT;

  
  /*body.FIRST(erstes untergeordnetes Element des Hauptteils der Nachricht) */
  inSourceElement[2] = cniFirstChild(&rc,inSourceElement[0]);
  checkRC(rc);
  
  /*body.FIRST.FIRST */
  inSourceElement[2] = cniFirstChild(&rc,inSourceElement[2]);
  checkRC(rc);

  /*Dies ist eine untergeordnete Baumstruktur innerhalb des Hauptteils der Nachricht, deshalb wird der Modus 'FolderBitStream' verwendet*/
  bitstreamOptions[2] = CCI_BITSTREAM_OPTIONS_FOLDER;

  
  for (loopCount=0;loopCount<3;loopCount++) {
    int bufLength;

    /* Neue Nachricht für Ausgabe erstellen */
    outMsg[loopCount] = cniCreateMessage(&rc, cniGetMessageContext(&rc, message));
    checkRC(rc);

    /* Stammelement der Ausgabenachricht abrufen */
    outRootElement = cniRootElement(&rc, outMsg[loopCount]);
    checkRC(rc);

    /* Inhalt der Eingabenachricht in die Ausgabenachricht kopieren */
    cniCopyElementTree(&rc, inRootElement, outRootElement);
    checkRC(rc);

    /* Untergeordnetes Element des Stammverzeichnisses abrufen (d. h. den Hauptteil)  */
    bodyChild = cniLastChild(&rc, outRootElement);
    checkRC(rc);

    /*Hauptteil der Nachricht, der von der Eingabenachricht kopiert wurde, auslösen*/
    cniDetach(&rc,
              bodyChild);
    checkRC(rc);

    /*Neuen Hauptteil der Ausgabenachricht in der BLOB-Domäne erstellen*/
    outBody = cniCreateElementAsLastChildUsingParser(&rc,
                                           outRootElement,
                                           constBLOBParserName);
    checkRC(rc);

    /*BLOB-Element erstellen*/
    outBlobElement = cniCreateElementAsLastChild(&rc,
                                outBody);
    checkRC(rc);

    cniSetElementName(&rc,
                      outBlobElement,
                      constBLOBElementName);
    checkRC(rc);
    
    /*Wert des BLOB-Elements durch den Empfang des Bitstroms für das Element
    festlegen */
    bitstream[loopCount].size=512;
    bitstream[loopCount].pointer=(CciByte*)malloc(sizeof(CciByte) * 512);
    
    bufLength = cniElementAsBitstream(&rc,
                          inSourceElement[loopCount],
                          &bitstream[loopCount],
                          constEmptyString,/*angenommene XML-Nachricht, also ohne Bedeutung*/
                          constEmptyString,/*Typ, Gruppe oder Format*/
                          constEmptyString,
                          0,/*WS-Manager-CCSID & Codierung verwenden*/
                          0,
                          bitstreamOptions[loopCount]);
    

    if (rc==CCI_BUFFER_TOO_SMALL) {
        free(bitstream[loopCount].pointer);
        bitstream[loopCount].size=bufLength;
        bitstream[loopCount].pointer=(CciByte*)malloc(sizeof(CciByte) * bitstream[loopCount].size);

        bufLength = cniElementAsBitstream(&rc,
                          inSourceElement[loopCount],
                          &bitstream[loopCount],
                          constEmptyString,/*angenommene XML-Nachricht, also ohne Bedeutung*/
                          constEmptyString,/*Typ, Gruppe oder Format*/
                          constEmptyString,
                          0,/*WS-Manager-CCSID & Codierung verwenden*/
                          0,
                          bitstreamOptions[loopCount]);      
    }
    checkRC(rc);
    bitstream[loopCount].size=bufLength;
    
    cniSetElementByteArrayValue(&rc,
                                outBlobElement,
                                &bitstream[loopCount]);
    checkRC(rc);
  }

  /* Kennung vom Ausgabeterminal abrufen */
  terminalObject = getOutputTerminalHandle( (NODE_CONTEXT_ST *)context,
                                            (CciChar*)constOut);

  /* Wenn das Terminal vorhanden und angeschlossen ist, leiten Sie die Daten dorthin weiter */
  if (terminalObject) {
    if (cniIsTerminalAttached(&rc, terminalObject)) {
      /* Da dies eine neue, veränderte Nachricht ist, sollte sie abgeschlossen werden... */
      cniFinalize(&rc, outMsg[0], CCI_FINALIZE_NONE);
      cniFinalize(&rc, outMsg[1], CCI_FINALIZE_NONE);
      cniFinalize(&rc, outMsg[2], CCI_FINALIZE_NONE);
      retvalue = cniPropagate(&rc, terminalObject, localEnvironment, exceptionList, outMsg[0]);
      retvalue = cniPropagate(&rc, terminalObject, localEnvironment, exceptionList, outMsg[1]);
      retvalue = cniPropagate(&rc, terminalObject, localEnvironment, exceptionList, outMsg[2]);
      if (retvalue == CCI_FAILURE) {
        if (rc == CCI_EXCEPTION) {
          /* Details der Ausnahmebedingung abrufen */
          memset(&exception_st, 0, sizeof(exception_st));
          cciGetLastExceptionData(&rc, &exception_st);

          /* Jede lokale Fehlerbehandlung kann hier eingesetzt werden */

          /* Sicherstellen, dass die Nachricht vor Return/Throw gelöscht wird */
          cniDeleteMessage(0, outMsg[0]);
          cniDeleteMessage(0, outMsg[1]);
          cniDeleteMessage(0, outMsg[2]);

          /* Die Ausnahmebedingung muss erneut ausgegeben werden; beachten Sie, dass diese nicht zurückgegeben wird */
          cciRethrowLastException(&rc);
        }
        else {

          /* Anderer Fehler... Das Plug-in protokolliert diesen unter Umständen mithilfe von 'CciLog()' */
          /* Dienstprogrammfunktion                                                        */

        }
      }
      else {
      }
    }
  }
  else {
    /* Terminal war nicht vorhanden... schwerwiegender interner Fehler. Die Plug-in versucht möglicherweise, */
    /* hier einen Fehler zu protokollieren, indem die Dienstprogrammfunktion 'cciLog()' verwendet wird.                 */
  }

  /* Nachrichten löschen nachdem sie beendet wurde */
  cniDeleteMessage(0, outMsg[0]);
  cniDeleteMessage(0, outMsg[1]);
  cniDeleteMessage(0, outMsg[2]);

  free((void*) constBLOBParserName);
  free((void*) constBLOBElementName);
  free((void*) constEmptyString);
  return;
Bemerkungen | Marken | Downloads | Bibliothek | Unterstützung | Feedback

Copyright IBM Corporation 1999, 2009Copyright IBM Corporation 1999, 2009.
Letzte Aktualisierung : 2009-02-17 15:29:57

as07885_