IParameter

Beschreibung:

IParameter repräsentiert sowohl einen Eingangs- als auch einen Ausgangs-Parameter eines Jobs.

Die IParameter -Schnittstelle stellt Methoden für den Zugriff auf die Eigenschaften eines Parameters zur Verfügung. Diese sind in zwei Gruppen unterteilt. Die erste Gruppe steht bei allen Paramtertypen zur Verfügung. Die zweite nur bei Parametern vom Binär-Typ.

Zur ersten gehören Name, Type und Value. Diese repräsentieren den einfachsten Zugriff auf das Parameterobjekt. Name und Type stehen als Nur-Lese-Eigenschaften zur Verfügung. Die ValueEigenschaft kann auch im Nachherein gesetzt bzw. verändert werden. Je nach Parametertyp werden die an diese Eigenschaft übergebenen Werte unterschiedlich behandelt. Dabei erfolgt keine Überprüfung, ob der übergebene Wert dem geforderten Varianttyp entspricht. Anstelle dessen wird versucht, den übergebenen Wert in diesen Typ zu konvertieren. Dies geschieht über die COMKonvertierungsfunktionen des Variants. Schlägt die Konvertierung fehl wird der betreffende COMFehler geworfen. Die verwendeten Zieltypen werden bei der Eigenschaft Value aufgeführt. Beim Setzen der Value-Eigenschaft

Zur zweiten Gruppe gehören die restlichen Methoden. Diese dienen der Verarbeitung der BinärDaten des Parameters. Wird eine dieser Methoden bei einem Nicht-Binär-Parameter aufgerufen wird der Fehler errParameterMethodUnsupported geworfen.

Öffentliche Methoden:

HRESULT Stream ([out, retval] IStream ** ppStream)
HRESULT AppendChunk ([in] VARIANT Data)
HRESULT GetChunk ([in] long Length, [out, retval] VARIANT * pResult)
HRESULT ResetStream ()
HRESULT ClearStream ()

Properties:

VARIANT Value [get, set]
BSTR Name [get]
long ActualSize [get]
BSTR XML [get, set]
ParameterTypeEnum Type [get]

Dokumentation der Elementfunktionen:

  • HRESULT AppendChunk ([in] VARIANT Data)

AppendChunk hängt zusätzliche Bytes an den Stream des Parameters

Diese Methode steht nur bei Parametern vom Typ ptBinary und ptXML zur Verfügung

Nach dem Aufruf dieser Methode steht der Positionszeiger des internen Streams auf dessen Ende.

Parameter:

[in]: Data enthält die Daten, die an den Stream angehängt werden sollen Die Daten werden über die OLE32 ChangeType -Methode nach VT_ARRA|VT_UI1 konvertiert und weiterverarbeitet. Wird z. B. ein BSTR übergeben, werden die Daten als WIDECHAR weiterverarbeitet. Das Schreiben von 8bit-Zeichen in den Stream kann über die Methoden des Helper-COM -Objektes erfolgen.

Beispiele:

VB

Dim abWriteData() As Byte
ReDim abWriteData(0 To 5)
abWriteData(0) = 0
abWriteData(1) = 1
abWriteData(2) = 2
abWriteData(3) = 3
abWriteData(4) = 4
abWriteData(5) = 5
oParameter.AppendChunk abWriteData

  • HRESULT ClearStream ()

ClearStream löscht die Daten des Streams.

  • HRESULT GetChunk ([in] long Length, [out, retval] VARIANT * pResult)

GetChunk liefert die angegebene Anzahl von Bytes aus dem Stream zurück.

Diese Methode steht nur bei Parametern vom Typ ptBinary und ptXML zur Verfügung.

Diese Methode beginnt ab der aktuellen Position im Stream die Daten zu lesen. Wird das Ende des Streams erreicht, bevor die gewünschte Anzahl an Zeichen gelesen wurde, werden nur die bis dahin gelesenen Zeichen zurückgeliefert. Die Anzahl der gelesenen Zeichen kann anhand der Größe des zurückgelieferten Puffers bestimmt werden (siehe Beispiel).

Parameter:

[in]: Length Anzahl der maximal zurückgeliefertten Bytes.

[out]: pResult (VB-Rückgabeparameter) enthält die gelesenen Bytes. Diese werden in einem Variant vom Typ VT_ARRAY|VT_UI1 geliefert.

Beispiel:

VB

' der folgende Programm-Ausschnitt entspricht:
' Dim var
' var = oParameter.Value
' dort bleibt jedoch zusätzlich die aktuelle Position des Streams erhalten
' Stream zum Lesen auf die Anfangsposition setzen
oParameter.ResetStream
Dim abReadData() As Byte
...
' Array auf die benötigte Größe anpassen
ReDim abReadData(0 To oParameter.ActualSize - 1)
' Daten lesen
abReadData = oParameter.GetChunk(oParameter.ActualSize)
' Größe der gelesenen Daten anhand der zurückgegebenen Daten ermitteln
Dim nSize As Long
nSize = UBound(abReadData) - LBound(abReadData)

  • HRESULT ResetStream ()

ResetStream setzt den Datenstream auf den Anfang zurück.

Diese Methode steht nur bei Parametern vom Typ ptBinary und ptXML zur Verfügung.

  • HRESULT Stream ([out, retval] IStream ** ppStream)

Stream liefert den Stream der Binärdaten

Diese Eigenschaft steht nur bei Parametern vom Typ ptBinary und ptXML zur Verfügung

Der Stream enthält die Binärdaten des jeweiligen Parameters. Diese sind durch den Aufrufer nicht MIME-BASE-64 zu kodieren bzw. zu dekodieren. Dies geschieht automatisch durch die OxSvrSpt -Bibliothek.

Parameter:

[out]: ppStream (VB-Rückgabeparameter) enthält den Stream als IStream -Schnittstelle.

Dokumentation der Properties:

  • long ActualSize [get]

ActualSize liefert die Größe des Datenstreams in Byte zurück.

Diese Methode steht nur bei Parametern vom Typ ptBinary und ptXML zur Verfügung.

Parameter:

[out]: pVal (VB-Rückgabeparameter) enthält die Größe des Datenstreams.

  • BSTR Name [get]

Name liefert den Namen des Parameters zurück.

Parameter:

[out]: pVal (VB-Rückgabeparameter) Name der Datei

  • ParameterTypeEnum Type [get]

Type liefert den Typ des Parameters zurück.

Folgende Typen stehen zur Verfügung:

ptString = 1

ptInteger = 2

ptBoolean = 3

ptDouble = 4

ptDateTime = 5

ptBinary =6

ptXML = 6

Die Parameter ptBinary und ptXML bilden dabei den Server-Parameter Base64 ab. Sie unterscheien sich lediglich in den Erstellungsmöglichkeiten.

Parameter:

[out]: pVal (VB-Rückgabeparameter) Typ des Parameters

  • VARIANT Value [get, set]

Value liefert den Wert des Parameters für nicht Base64-Parameter und setzt den Wert des Parameters.

Diese Eigenschaft steht nicht bei Parametern des Typs Base64 zur Verfügung. Anstatt dess kann über die Stream - und Chunk -Funktionen direkt auf die dekodierten Binärdaten zugegriffen werden. Weiterhin besteht die Möglichkeit über die XML-Eigenschaft

Bei Parametern des Typs Base64 besteht die Möglichkeit die Daten über die Stream - und Chunk -Funktionalität

Beim Setzen der Eigenschaft wird versucht, den übergebenen Wert des Variants in den benötigten Typ zu konvertieren. Als Zieltypen werden folgende verwendet:

ptString  - VT_BSTR
ptInteger - VT_I4
ptBoolean - VT_BOOL
ptDouble  - VT_R8
ptDateTime - VT_DATE
ptBase64  - VT_ARRAY | VT_UI1

Parameter:

[in]: newVal neuer Wert des Parameters

Bei Parametern vom Typ Base64 werden die Binärdaten als Array im Rückgabe-Variant zurückgeliefert. Der Positionszeiger des Streams wird durch den Aufruf dieser Eigenschaft nicht verändert.

Der Typ des zurückgelieferten Variants ist abhängig vom Typ des Parameters.

folgende Typen werden verwendet:

ptString   - VT_BSTR
ptInteger  - VT_I4
ptBoolean  - VT_BOOL
ptDouble   - VT_R8
ptDateTime - VT_DATE
ptBinary   - VT_ARRAY | VT_UI1
ptXML      - VT_ARRAY | VT_UI1

Parameter:

[out]: pVal (VB-Rückgabeparameter) enthält den Wert des Parameters

  • BSTR XML [get, set]

XML liefert den Wert des Base64-Parameters als XML-String und setzt den Wert des Base64Parameters aus der übergebenen XML-Zeichenkette.

Diese Methode steht nur bei Parametern vom Typ ptBinary und ptXML zur Verfügung.

Die ausgegebene XML-Zeichenkette wird über den XML-Parsers ausgelesen.

Lässt sich aus den Daten keine valide XML-Zeichenkette generieren, wird ein Fehler geworfen. Die Fehlermeldung richtet sich nach dem zur Validierung verwendeten XML-Parsers (MSXML4).

Der Positionszeiger des Streams wird durch den Aufruf dieser Eigenschaft nicht verändert.

Parameter:

[out]: pVal (VB-Rückgabeparameter) enthält die als XML-Zeichenkette dekodierten Daten.

Beispiel:

VB

Option Explicit

Dim oServer, oSession, oJob, oInputParameters, oByteParameter
Set oServer = CreateObject("OxsvrSpt.Server")
Set oSession = oServer.Login()
Set oJob = oSession.NewJob("med.ObservationValues")
Set oInputParameters = oJob.InputParameters
Set oByteParameter = oInputParameters.AddNewByteParameter("Parametername")
oByteParameter.XML = "<?xml version='1.0' encoding='utf-8'?>" & _
    "<med>irgendein Test mit Umlauten äöüß</med>"
oByteParameter.ResetStream
' Daten über MSXML wieder auslesen
Dim oDocument, bSuccess
Set oDocument = CreateObject("MSXML.DOMDocument")
bSuccess = oDocument.Load(oByteParameter.Stream)
' Text des XML aus dem DOM auslesen und ausgeben
MsgBox oDocument.XML

Diese Eigenschaft steht nur bei Parametern des Typs Base64 zur Verfügung.

Dabei wird die übergebene XML-Zeichenkette in den im Parameterobjekt zur Verfügung gestellten Stream übertragen. Es wird automatisch die in der XML-Zeichenkette angegebene Kodierung berücksichtigt.

Die alten Daten des Streams werden durch den Aufruf dieser Eigenschaft überschrieben. Nach dem Aufruf dieser Eigenschaft weist der Positionszeiger des Streams auf den Anfang desselben.

Die übergebenen Daten werden bei der Konvertierung validiert. Werden nicht-XML-konforme Daten übergeben, wird ein Fehler ausgelöst. Der Stream hat in diesem Fall die Länge 0. Die Fehlermeldung richtet sich nach dem zur Validierung verwendeten XML-Parser (MS-XML4).

Parameter:

[in]: newVal Basicstring mit den XML-Daten.

Beispiel:

VB

Dim oParameter As OxSvrSpt.Parameter
...
oParameter.XML = "<?xml version='1.0' encoding='utf-8'?>" & _
    "<med>irgendein Test mit Umlauten äöüß</med>"