cniElementAsBitstream

Diese Funktion ruft die Darstellung des Bitstroms des angegebenen Elements ab. Der dem Element zugeordnete Parser serialisiert das Element und alle untergeordneten Elemente. Das Ergebnis wird in den Speicher kopiert, der vom Aufrufenden zugeordnet wurde. 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 vom Benutzer zugeordneten Speicher kopiert. In diesem Fall muss der Parser die Nachricht nicht syntaktisch analysieren und erneut serialisieren.

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 Generierung des Bitstroms der Algorithmus des Sendeknotens 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. Dies bedeutet, dass sie durch die Suche nach vorherigen gleichgeordneten Elementen in der Annahme festgelegt werden, dass diese 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 den Modus 'FolderBitStream', der für eine beliebige untergeordnete Baumstruktur einen aussagekräftigen Bitstrom generiert, vorausgesetzt, das Feld, auf das verwiesen 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 aus der Funktion (Ausgabe). Wenn ein Nullzeiger angegeben wird, bedeutet dies, dass der Knoten nicht für Fehler zuständig ist. Wenn die Eingabe nicht NULL ist, gibt die Ausgabe den Erfolgsstatus des Aufrufs an. 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).
Das Syntaxelement, das serialisiert werden soll (Eingabe). Dies muss das letzte untergeordnete Element des Nachrichtenstamms sein.
value
Ein Zeiger auf eine 'CciByteArray'-Struktur, die einen Zeiger auf einen Speicherbereich enthält, der vom Aufrufenden zugeordnet wurde, sowie die Größe dieses Speichers in Byte (CciBytes) (Ausgabe).
messageType
Die Nachrichtentypdefinition, die für die Erstellung des Bitstroms aus der Elementstruktur verwendet wird (Eingabe). Ein Nullzeiger bedeutet, dass dieser Parameter ignoriert wird. Wenn der dem Element zugeordnete Parser diesen Wert nicht benötigt, z. B. wenn es sich um einen generischen XML-Parser handelt, wird der Parameter ebenfalls ignoriert.
messageSet
Die Nachrichtengruppendefinition, die für die Erstellung des Bitstroms aus der Elementstruktur verwendet wird (Eingabe). Ein Nullzeiger bedeutet, dass dieser Parameter ignoriert wird. Wenn der dem Element zugeordnete Parser diesen Wert nicht benötigt, z. B. wenn es sich um einen generischen XML-Parser handelt, wird der Parameter ebenfalls ignoriert.
messageFormat
Das Format, das für die Erstellung des Bitstroms aus der Elementstruktur verwendet wird (Eingabe). Ein Nullzeiger bedeutet, dass dieser Parameter ignoriert wird. Wenn der dem Element zugeordnete Parser diesen Wert nicht benötigt, z. B. wenn es sich um einen generischen XML-Parser handelt, wird der Parameter ebenfalls ignoriert.
encoding
Die Codierung, die beim Schreiben des Bitstroms verwendet werden soll (Eingabe). Dieser Parameter ist obligatorisch. Sie können den Wert 0 angeben, wenn die Codierung des Warteschlangenmanagers verwendet werden soll.
ccsid
Die ID des codierten Zeichensatzes, die beim Schreiben des Bitstroms verwendet werden soll (Eingabe). Dieser Parameter ist obligatorisch. Sie können den Wert 0 angeben, wenn die ID des codierten Zeichensatzes des Warteschlangenmanagers verwendet werden soll. Wenn als ID des codierten Zeichensatzes -1 angegeben wird, bedeutet dies, dass der Bitstrom mit Hilfe 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 kein Parser diese Option.
options
Ganzzahliger Wert, der angibt, welcher Bitstromgenerierungsmodus verwendet werden soll. Er nimmt einen der folgenden Werte an:
  • 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 als Wert für returnCode CCI_BUFFER_TOO_SMALL festgelegt.
  • Wenn bei der Ausführung eine Ausnahmebedingung auftritt, wird als Wert für returnCode CCI_EXCEPTION festgelegt.

Beispiel

Im folgenden Beispiel wird dargestellt, wie die Optionsparameter verwendet werden sollten, 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
RFH2
<test><data><stuff>things</stuff></data></test>
Der Knoten gibt drei Nachrichten weiter. Eine enthält eine Kopie der Eingabenachricht in der BLOB-Domäne, eine enthält eine Kopie der Eingabe RFH2, und die dritte enthält den Ordner <data></data> als Hauptteil einer Nachricht 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 RFH2*/
  /*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 RFH2, 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, destinationList, exceptionList, outMsg[0]);
      retvalue = cniPropagate(&rc, terminalObject, destinationList, exceptionList, outMsg[1]);
      retvalue = cniPropagate(&rc, terminalObject, destinationList, 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 mit Hilfe 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 | Rückmeldung
Copyright IBM Corporation 1999, 2005 Letzte Aktualisierung: Nov 17, 2005
as07885_