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 vom Benutzer 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 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 Sendeknoten 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 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). Die Angabe eines Nullzeigers bedeutet, dass der Knoten keine Fehler handhaben wird. Ist eine Eingabe nicht NULL, bedeutet die Ausgabe den Erfolgsstatus des Aufrufs. Jegliche während der Ausführung dieses Aufrufs ausgelösten Ausnahmebedingungen werden beim nächsten übergeordneten Knoten im Fluss erneut ausgelöst. 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 zu serialisierende Syntaxelement (Eingabe). Muss das letzte untergeordnete Element des Nachrichtenstamms sein.
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). Ein Nullzeiger bedeutet, dass dieser Parameter ignoriert wird. Auch wenn der dem Element zugeordnete Parser an diesem Wert nicht interessiert ist (z. B. wenn es ein generischer XML-Parser ist), wird der Parameter 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. Auch wenn der dem Element zugeordnete Parser an diesem Wert nicht interessiert ist (z. B. wenn es ein generischer XML-Parser ist), wird auch der Parameter 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. Auch wenn der dem Element zugeordnete Parser an diesem Wert nicht interessiert ist (z. B. wenn es ein generischer XML-Parser ist), wird der Parameter ignoriert.
encoding
Die Codierung, die beim Schreiben des Bitstroms verwendet werden soll (Eingabe). Dieser Parameter ist verbindlich. 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 verbindlich. Es kann als Wert 0 angegeben werden, um zu anzuzeigen, dass die ID des codierten Zeichensatzes des Warteschlangenmanagers verwendet werden sollte. 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.
  • Falls der vom Aufrufenden zugeordnete Speicher nicht ausreichend war, 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 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. Die zweite enthält eine Kopie der Eingabe RFH2 als Hauptteil einer Nachricht in der BLOB-Domäne. 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, 2006 Letzte Aktualisierung: 23. Aug. 2006
as07885_