Special Type Mappings
Empty and NULL values are supported for both the scalar and structured mappings.
A VARIANT containing a VT_EMPTY value is accepted as a default input value and is mapped to the default initial value for the corresponding 4GL scalar, user class instance, or array instance. This is a convenient way to initialize ByRef data that is used for output only, and it minimizes the marshaling cost of sending the input.
A VARIANT containing a VT_NULL value is mapped to a NULL value in the corresponding OpenROAD 4GL scalar, user class instance, or array instance. This mapping fails if the 4GL attribute was declared as a non-nullable type. NULL 4GL values are mapped back to VT_NULL when returned using ByRef.
The OpenROAD DATE data type requires several special cases because it is really a combination of the following multiple types:
• Timestamp
• Date-without-time
• Interval
• Blank date
The COM automation DATE data type can only represent timestamps, so special exceptions are made for the other DATE values.
Timestamp
OpenROAD timestamps are converted directly to COM DATE values. These timestamps are always transmitted in Greenwich Mean Time (GMT) form. The client must handle any shifting to a local time zone for display purposes.
This time-zone-shifting behavior is the default behavior for OpenROAD 4GL clients. OpenROAD timestamps are stored internally in GMT but always shifted from the local time zone on display input and shifted to the local time zone for display output.
The COM ParameterData interface does not do any time zone shifting. It only handles timestamps in GMT form. Non-4GL client applications must implement their own time zone shifting if desired.
Date-without-time
OpenROAD date-without-time values are represented in COM DATE values as midnight (GMT) timestamps, but they are not the same as timestamps. Following are some properties of date-without-time values:
• They are not subject to time zone shifting when formatted for display.
• They are transmitted as a GMT timestamp, but with an extra flag to identify them as a date-without-time value.
• They are transparently converted back to a real OpenROAD date-without-time value in an OpenROAD 4GL client, but the COM ParameterData interface returns the value as a GMT midnight timestamp.
• Non-4GL clients must call a helper method (IsDateWithoutTime) to determine if the value represents a normal timestamp or whether it represents a date-without-time.
• Non-4GL clients must never perform zone shifting of date-without-time values.
Interval
OpenROAD DATE interval values are not supported by the OpenROAD Server marshaling protocol. You can use intervals internally within a server application, but interval values cannot be transmitted between client and server within SCP parameters. If you need to communicate intervals between a client and server, those values must be converted to some other type that can be marshaled (such as varchar).
Blank Date
The OpenROAD blank date value is not the same as the NULL value. There is no value in the COM DATE data type that represents this blank value. To communicate this extra value through a COM VARIANT, it must be represented outside of the range of the COM DATE data type, where an empty string is used.
In an OpenROAD 4GL client, this empty string value is automatically converted back to an OpenROAD blank date value. Non-4GL clients must either test for the empty string or call a helper method (IsBlankDate) to determine if the value represents a blank date.