# 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:
```cpp
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:
```cpp
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:

: `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
```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:

: `Length` number of bytes to be returned at most.

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

Example:

VB
```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:

: `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:

: `pVal` (VB return parameter) contains the size of the data stream.

* `BSTR Name [get]`

`Name` returns the name of the parameter.

Parameters:

: `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:

: `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:
```text
ptString  - VT_BSTR
ptInteger - VT_I4
ptBoolean - VT_BOOL
ptDouble  - VT_R8
ptDateTime - VT_DATE
ptBase64  - VT_ARRAY | VT_UI1
```
Parameters:

: `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:
```text
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:

: `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:

: `pVal` (VB return parameter) contains the data decoded as XML string.

Example:

VB

`Option Explicit`
```vb
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:

: `newVal` basic string with XML data.

Example:

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