SetEmpty, SetNull, IsEmpty, IsNull Methods

Empty (VT_EMPTY) and null (VT_NULL) values have some special characteristics and require additional methods to support them, as described in the sections that follow.

Most PDO methods operate only on scalar attributes. A structured attribute usually contains a nested array of other attributes and does not have a scalar value that you can set or get directly. VT_EMPTY and VT_NULL are exceptions to the rule.

A structured attribute can contain the value VT_EMPTY, and this is the default value of all attributes (scalar and structured) when they are first declared. All VT_EMPTY values are mapped to default instances of the corresponding parameter (or user class attribute) in the called 4GL procedure. When VT_EMPTY values are passed through ByRef, the default instances to which they were mapped are marshaled back, including any modifications the 4GL procedure may have made to those default values. The OpenROAD Server does not return any data as VT_EMPTY.

When a structured attribute has a VT_EMPTY value, all attributes nested below it are implicitly VT_EMPTY also. It is legal to set or get any scalar attribute that is nested below a VT_EMPTY structured attribute. If you set a nested attribute, the parent attribute then contains a nested array and is no longer empty.

A structured attribute can contain the value VT_NULL, and this represents a null user class instance (or a null user class array instance). VT_NULL values for structured attributes can be sent to, and returned from, a 4GL procedure.

Note: Although OpenROAD supports the concept of a null array row, a COM automation array cannot express this; therefore, null array rows are not supported by the OpenROAD Server interface. An entire array can be null, and any of the attributes within a row can be null, but a row itself cannot be null.

When a structured attribute has a VT_NULL value, all attributes nested below it are implicitly undefined. It is illegal to set or get any attribute that is nested below a VT_NULL structured attribute.

The SetEmpty, SetNull, IsEmpty, and IsNull methods are provided to allow client code to handle the special cases that arise with empty and null values. This is especially important for languages that cannot manipulate VT_EMPTY or VT_NULL values directly.

HRESULT SetEmpty
    (
        [in] BSTR AttributeName
    );

HRESULT SetNull
    (
        [in] BSTR AttributeName
    );

SetEmpty can also be used to clear all data values in the PDO data tree by passing an empty string as the attribute name.

IsEmpty and IsNull let you safely test a scalar or structured value for those special cases before attempting other GetAttribute operations. The result is returned as an integer, with nonzero meaning TRUE and zero meaning FALSE:

HRESULT IsEmpty
    (
        [in] BSTR AttributeName,
        [out, retval] long * IsEmpty
    );

HRESULT IsNull
    (
        [in] BSTR AttributeName,
        [out, retval] long * IsNull
    );