Less is More – Using User Defined Conversions

We are filing this under “things we thought everyone knew but apparently not!” While engaged in a recent project that had us upgrading an application from OpenInsight 8.0.1 to OpenInsight 9.4.0, we came across a curious technique that allowed end users to see meaningful information in the form but the underlying data was a single letter code. To control the available options, the original developer used a drop down list style combo box control, e.g.:

Now, since the dictionary column was designed to only store codes (e.g., “G”, “S”, and “B”), the developer thought that data-binding this combo box control was impossible. Thus, a hidden control (in this case, a radio button group) was added to the form to help with the translation from a meaningful label to a properly stored code:

To manage this properly, the developer then had to create, or modify, various event handlers to make sure the combo box and radio button group controls were always in sync. Needless to say, when there are several controls like this on a single form (as was this case in this project), this becomes an arduous maintenance chore for the developer and it causes unnecessary overhead for OpenInsight.

There is a much simpler and elegant solution to this: User Defined Conversions (aka UDCs). User Defined Conversions are nothing new to the Revelation world, going back to the days of AREV, but they are perhaps an under appreciated tool in the developer’s utility belt. If you are unfamiliar with the concept, we will leave the reader to review the entry within the Programmer’s Reference Manual and the source code samples that come with OpenInsight (e.g., PHONE_FORMAT, SSN_FORMAT). Simply put, a UDC allows for the display of data in one format while storing this in a different format within the database row.

Using the example scenario above, we proceeded to create a UDC called MEDAL_FORMAT:

Subroutine Medal_Format(Conv, Ans, Branch, ReturnData)

/***********************************************************************************************************************

    This program is proprietary and is not to be used by or disclosed to others, nor is it to be copied without written
    permission from SRP Computer Solutions, Inc.

    Name        :   Medal_Format

    Description :   User-Defined Conversion for Medal Codes

    Notes       :   This UDC allows the developer to use a standard combo box control so a meaningful description can
                    be displayed to the end user although the internal value is really a code.

    Parameters  :
        Conv            [in] -- ICONV or OCONV. The flag set by OI whether an internal conversion, validation, or output
                                conversion is being performed.
        Ans             [in] -- The value entered into control that needs to be validated or converted.
        Branch          [in] -- Not used in this UDC.
        ReturnData     [out] -- The returned value after any conversion, if necessary, has been performed.

    History     :   (Date, Initials, Notes)
        05/08/14    dmb     Original programmer.

***********************************************************************************************************************/

$insert Logical
$insert Msg_Equates

Equ VALID$          to 0    ; // Successful
Equ INVALID_MSG$    to 1    ; // Bad Data       -   Print error message window
Equ INVALID_CONV$   to 2    ; // Bad Conversion -          "         "
Equ INVALID_NOMSG$  to 3    ; // Bad but do not print the error message window

ReturnData  = Ans

Status() = 0

Begin Case
    Case Conv EQ 'ICONV'
        GoSub Iconv

    Case Conv EQ 'OCONV'
        GoSub Oconv
End Case

Return

Iconv:
    Begin Case
        Case Ans _EQC 'Gold'    ; ReturnData    = 'G'
        Case Ans _EQC 'Silver'  ; ReturnData    = 'S'
        Case Ans _EQC 'Bronze'  ; ReturnData    = 'B'
        Case Ans _EQC ''        ; ReturnData    = ''
    End Case
return

Oconv:
    Begin Case
        Case Ans _EQC 'G'       ; ReturnData    = 'Gold'
        Case Ans _EQC 'S'       ; ReturnData    = 'Silver'
        Case Ans _EQC 'B'       ; ReturnData    = 'Bronze'
        Case Ans _EQC ''        ; ReturnData    = ''
    End Case
return

By applying this UDC to the control, or even the dictionary column itself, the combo box control can now safely display meaningful information to the user while properly preserving the internal data. This technique can also be used to provide legacy database conventions a more appropriate visual control. For instance, many systems store a literal “Y” and “N” character rather than “1” and “0” for boolean values. Ordinarily these legacy methods prevent developers from using a natural toggle control, like the check box, to represent the data. With a User Defined Conversion, the best visual control can be employed without having to rework the internal data and all dependent business logic.

In parting, if the reader is able to learn from this post and believes it will be useful, we would encourage you to consider creating a more generic UDC routine that pulls the internal and external data from another resource (like a database table designed to store this kind of information.) This way you can rely on one UDC routine and utilize the Branch argument to reference the appropriate translation data. Then it will be rather easy to add more options in the future.