IParameter

Description:

IParameter represents both an input and output parameter of a job.

The IParameter interface provides methods for accessing the properties of a parameter. These are divided into two groups. The first group is available for all parameter types. The second is only available for binary-type parameters.

The first group includes Name, Type and Value. These represent the simplest access to the parameter object. Name and Type are read-only properties. The Value property can also be set or modified later. Depending on the parameter type, the values passed to this property are handled differently. No verification is performed to check whether the passed value corresponds to the required variant type. Instead, an attempt is made to convert the passed value to this type. This is done via the COM conversion functions of the variant. If the conversion fails, the corresponding COM error is thrown. The target types used are listed for the Value property. When setting the Value property,

The second group includes the remaining methods. These are used for processing the binary data of the parameter. If these methods are called on a non-binary parameter, the error errParameterMethodUnsupported is thrown.

Public Methods:

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]

Documentation of Element Functions:

  • HRESULT AppendChunk ([in] VARIANT Data)

AppendChunk appends additional bytes to the parameter’s stream.

This method is only available for parameters of type ptBinary and ptXML.

After calling this method, the position pointer of the internal stream is positioned at its end.

Parameters:

[in]: Data contains the data to be appended to the stream. The data are converted to VT_ARRA|VT_UI1 via the OLE32 ChangeType method and further processed. If a BSTR is passed, for example, the data are processed as WIDECHAR. Writing 8-bit characters to the stream can be done via methods of the Helper-COM object.

Examples:

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 deletes the data of the stream.

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

GetChunk returns the specified number of bytes from the stream.

This method is only available for parameters of type ptBinary and ptXML.

This method begins reading data from the current position in the stream. If the end of the stream is reached before the desired number of characters is read, only the characters read up to that point are returned. The number of characters read can be determined by the size of the returned buffer (see example).

Parameters:

[in]: Length number of bytes to be returned at most.

[out]: pResult (VB return parameter) contains the read bytes. These are returned as a Variant of type VT_ARRAY|VT_UI1.

Example:

VB

' The following program excerpt is equivalent to:
' Dim var
' var = oParameter.Value
' however, the current stream position is preserved
' Set stream to beginning position for reading
oParameter.ResetStream
Dim abReadData() As Byte
...
' Adjust array to required size
ReDim abReadData(0 To oParameter.ActualSize - 1)
' Read data
abReadData = oParameter.GetChunk(oParameter.ActualSize)
' Determine size of read data based on returned data
Dim nSize As Long
nSize = UBound(abReadData) - LBound(abReadData)

  • HRESULT ResetStream ()

ResetStream resets the data stream to the beginning.

This method is only available for parameters of type ptBinary and ptXML.

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

Stream returns the stream of binary data.

This property is only available for parameters of type ptBinary and ptXML.

The stream contains the binary data of the respective parameter. These must not be encoded or decoded in MIME-BASE-64 by the caller. This is done automatically by the OxSvrSpt library.

Parameters:

[out]: ppStream (VB return parameter) contains the stream as an IStream interface.

Documentation of Properties:

  • long ActualSize [get]

ActualSize returns the size of the data stream in bytes.

This method is only available for parameters of type ptBinary and ptXML.

Parameters:

[out]: pVal (VB return parameter) contains the size of the data stream.

  • BSTR Name [get]

Name returns the name of the parameter.

Parameters:

[out]: pVal (VB return parameter) name of the parameter

  • ParameterTypeEnum Type [get]

Type returns the type of the parameter.

The following types are available:

ptString = 1

ptInteger = 2

ptBoolean = 3

ptDouble = 4

ptDateTime = 5

ptBinary = 6

ptXML = 6

The parameters ptBinary and ptXML map to the server parameter Base64. They differ only in creation possibilities.

Parameters:

[out]: pVal (VB return parameter) type of the parameter

  • VARIANT Value [get, set]

Value returns the value of the parameter for non-Base64 parameters and sets the value of the parameter.

This property is not available for Base64 parameter types. Instead, direct access to the decoded binary data can be made via the Stream and Chunk functions. Additionally, there is the possibility to use the XML property.

For Base64 parameters, it is possible to access the data via the Stream and Chunk functionality.

When setting the property, an attempt is made to convert the passed variant value to the required type. The following target types are used:

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

Parameters:

[in]: newVal new value of the parameter

For Base64 parameters, the binary data are returned as Array in the return variant. The position pointer of the Stream is not changed by calling this property.

The type of the returned variant depends on the parameter type.

The following types are used:

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

Parameters:

[out]: pVal (VB return parameter) contains the value of the parameter

  • BSTR XML [get, set]

XML returns the value of the Base64 parameter as an XML string and sets the value of the Base64 parameter from the passed XML string.

This method is only available for parameters of type ptBinary and ptXML.

The output XML string is read via the XML parser.

If a valid XML string cannot be generated from the data, an error is thrown. The error message depends on the XML parser used for validation (MSXML4).

The position pointer of the Stream is not changed by calling this property.

Parameters:

[out]: pVal (VB return parameter) contains the data decoded as XML string.

Example:

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
' Read data from DOM via MSXML
Dim oDocument, bSuccess
Set oDocument = CreateObject("MSXML.DOMDocument")
bSuccess = oDocument.Load(oByteParameter.Stream)
' Read text of XML from DOM and display
MsgBox oDocument.XML

This property is only available for Base64 parameter types.

In this case, the passed XML string is transferred to the Stream provided by the parameter object. The encoding specified in the XML string is automatically considered.

The old data of the Stream are overwritten by calling this property. After calling this property, the position pointer of the Stream points to the beginning of the same.

The passed data are validated during conversion. If non-XML-conformant data are passed, an error is raised. In this case, the Stream has length 0. The error message depends on the XML parser used for validation (MS-XML4).

Parameters:

[in]: newVal basic string with XML data.

Example:

VB

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