DesignBais Hacks – Introduction Part 1

One of the neat things about DesignBais is that the product itself is written in DesignBais. This isn’t uncommon in the world today. Java is written in Java, C is C, C# is C#, etc. While we can’t open DesignBais system forms in the Forms Designer, we can manually customize them. We could do this with the editor but I believe that would lead to chaos, so I’m proposing here a coding standard which will allow us to hack specific aspects of forms into something we like, or back into their original form.

Ouch! Can’t we call it something besides "hacking"?

First, I’ll define what I mean by a hack. That term has had a lot of bad press over the years and many people wince at the thought of hackers or hacking code. The Open Source market is all about hacking, which these days simply implies that people are making modifications to some software baseline. Hacking is not a bad thing, it’s the bad "black hat" hackers (these days known as "crackers") that give it a bad name.

Some dictionaries define "hacker" alternately with neutral and negative connotations. These are from Dictionary.com:
– "a computer enthusiast."
– "a microcomputer user who attempts to gain unauthorized access to proprietary computer systems."
– "a person who engages in an activity without talent or skill."

Wikipedia defines a hacker as "someone who creates and modifies computer software and computer hardware". Notice no negative connotations are implied in the definition, probably because the text was written by someone attempting to correct old notions. It continues with "In computer programming, a hacker is a software designer and programmer who builds elegant, beautiful programs and systems". When the person who wrote that gets tired of coding he’ll easily be able to find a job in Marketing. The wiki material goes on to explain the positive and negative aspects of hacking.

Our goal here is to customize our environment, arguably improve upon it, and in the "white hat" positive spirit of hacking to make our utilities available to others so that we can all benefit.

Will this violate my support agreement with DBI?

No. DBI will not deny support when customizations are made to the environment. However, before calling for help I would strongly encourage you to remove all hacks as described in this article, to ensure that your tweaks are not causing problems. If there is a serious question about whether a series of hacks has actually corrupted the production software, DBI may request that you save your DBI account, and restore the original version.

The bottom line on this is that you use these hacks at your own risk and discretion, and while I stand behind the material provided here, I cannot be responsible for errors in implementation or related costs for fixing anything that may go wrong.

Preparing for hacks

To start, let’s use a program to make a backup of the original data. The programs provided here are D3-compatible. Please feel free to modify this code, and return it to me via e-mail for the benefit of others (there are formatting issues with code posted in comments and I’d prefer to keep comments short if possible). I can provide platform-specific versions as a service.

* Account DBI, File DBI, Item BACKUP.DBISYSFORMS
* Run in account DBI.
EXECUTE "CREATE-FILE DBISYSFORMS.413 3 3"
CMD = "COPY DICT DBISYSFORMS"
CMD<2> = "(DICT DBISYSFORMS.413"
EXECUTE CMD
CMD = "COPY DBISYSFORMS"
CMD<2> = "(DBISYSFORMS.413"
EXECUTE CMD

Now we can use that file to fall back to the original forms.

Let’s create a consistent place to store our hacks. Create a program file in any DesignBais-enabled account – I call mine DBHACKS. Create a q-pointer that goes back to account DBI, file DBISYSFORMS.413 so that we can restore when we want.

Finally, before we get started, I’d like to establish some sort of naming convention so that I can easily find the hacks in the DBHACKS file. After a couple initial attempts that proved inadequate I came up with the following verbose but effective system. The ID’s for hacks here will be:
  filename-formfile_formitem-hack00
I used dashes because DesignBais doesn’t. I didn’t use asterisks because that would conflict with OS naming conventions where some environments store code in the OS. I didn’t delimit with periods because some formnames include them. I did use the underscore because DesignBais itself uses them. The ‘hack00’ part will tell us which field is being customized, and we’ll increment the number starting with 01, 02, 03, as we find new ways to customize each field. Of course you can just call all of these hack1, hack2, etc, just to keep it short.

The hacks provided here will work with DesignBais v3.3 and v4.13. Since developers are now migrating to v4 I will not guarantee that future hacks will work with anything other than the current (v4) release. At some point we may need to comment our hacks, and create new "hack00" items for different versions. For now, let’s keep it simple.

Our First Hack

Let’s start with something trivial. I think the width of the File Description field is too small in the File Properties form. Let’s widen it in increments.

DBHACKS   DBISYSFORMS-DBIFILES_D10-FILEDESC01

EQU COLSPANS TO 14
EQU XML TO 41
RESTORE=0 ; * tells code whether to restore to original values
IF INDEX(SENTENCE(),’!RESTORE’,1) THEN RESTORE=1
OPEN ‘DBISYSFORMS’ TO LIVE ELSE STOP 201,’DBISYSFORMS’
OPEN ‘DBISYSFORMS.413’ TO BACKUP ELSE
   STOP 201,’DBISYSFORMS.413′
END
FID = ‘DBIFILES*D10’
READ FORM FROM LIVE,FID ELSE STOP 202,FID
LOCATE(‘text6’,FORM,XML;VAL) ELSE
  CRT "Cant find field"
  STOP
END
IF RESTORE = 0 THEN
  FORM<COLSPANS,VAL> = INT(FORM<COLSPANS,VAL>*1.20)
END
IF RESTORE = 1 THEN
  READ ORIGFORM FROM BACKUP,FID THEN
    FORM = ORIGFORM
  END ELSE
   STOP 202,FID
  END
END
WRITE FORM ON LIVE,FID
* done

Let’s breakdown the code:

1. Checking the Sentence() for "!restore" allows us to restore the form definitions from the command-line. This can be done for one form, or for all forms that have been modified if they are run in a loop with !restore appended to their command-line.
2. The file name is DBIFILES and the form name is D10, so the item ID for DBSYSFORMS is DBIFILES*D10. How did we know this? When you’re using DesignBais the status bar at the bottom of the form tells us the form name as file_form. They display it to us with an underscore but the form is stored with an asterisk. Note that IE7 has some option to turn off the status bar display – you may need to toggle this. So, just for convenience I assign the file*form to a variable called FID for Form ID.
3. The unique field on the form is identified as ‘text6’. How did we know this? By using a statement at TCL like this (use 132-column mode in terminal or send output to LPTR):
   LIST   DBISYSFORMS     ‘DBIFILES*D10’     DBIF.FIELD.NAME.LIST
     DBIF.ATTR     DBIF.FIELD.XML.LABEL     DBIF.FIELD.PROPERTY
     DBIF.FIELD.COL.LIST     DBIF.FIELD.ROW.LIST
     DBIF.FIELD.LENGTH.LIST     DBIF.FIELD.ALT.LENGTH.LIST    ID-SUPP
   The "Field XML Label" is a unique ID assigned at design time. There are two fields in the Name List called DBIFI.FILE.DESCRIPTION, so that couldn’t be used, but only one of them has the XML ID ‘text6’.
4. If we are not restoring, we change the colspan value for the field, increasing it by 20%. Running it more than once keeps increasing the value. It’s personal preference whether to do this or whether to set it at a fixed value. Since I didn’t know what value I wanted, I just ran the program, clicked File Properties to see the effects, ran it again, checked again, etc.
5. If we are restoring, just reset the whole item back to normal. Might it be better to just reset this one value that we’re changing? Personally I think so, but again, that’s personal preference. To keep this easy I’d say restore the whole item and then re-apply customizations as desired.
6. Whatever action we took, write the resulting item back to the live DBISYSFORMS.

To revert back to the original values, you can run the program from the command prompt like this:
  DBISYSFORMS-DBIFILES_D10-FILEDESC01   !RESTORE

Our Second Hack

Let’s do another one. When I am in developer mode, I like to see my own company logo in the top-left corner, rather than the default DesignBais logo. Rather than hacking a form, we’re going to hack a menu definition which has a different attribute structure. Here’s the code and we’ll dissect it below.

DBHACKS   DBISYSFORMS-MENU_DEVELOP.TOP-TOPLEFT01

EQU TOPLEFT TO 11
RESTORE=0 ; * tells code whether to restore to original values
IF INDEX(SENTENCE(),’!RESTORE’,1) THEN RESTORE=1
OPEN ‘DBISYSFORMS’ TO LIVE ELSE STOP 201,’DBISYSFORMS’
OPEN ‘DBISYSFORMS.413’ TO BACKUP ELSE
   STOP 201,’DBISYSFORMS.413′
END
FID = ‘MENU*DEVELOP.TOP’
READ FORM FROM LIVE,FID ELSE STOP 202,FID
IF RESTORE = 0 THEN
  FORM<TOPLEFT> = ‘nrd/nrdlogodb1.jpg’
END
IF RESTORE = 1 THEN
  READ ORIGFORM FROM BACKUP,FID THEN
    FORM = ORIGFORM
  END ELSE
   STOP 202,FID
  END
END
WRITE FORM ON LIVE,FID
* done

As with the first program, we open DBISYSFORMS and the backup file. We read the item. We check to see if we’re going to restore, and if not we make the change. Then we write back the right item.

Note how much of that code is consistent with the first program. In my next article on this topic (next week) I’ll break these items up to make use of a common Include item. That will allow us to create hacks with (no kidding) as few as two lines of custom code! I’ll also tell you how you actually can customize stock DBI forms using the developer environment. Then we can compare methods so you can decide what suits your needs.

If anyone has comments or suggestions, I’ll try to roll the feedback into enhancements in the next article. Requests for specific hacks are also welcome. I’ve been thinking about posting a little library of hacks here for free consumption, and/or making a number of special hacks available for purchase.

If you’ve hacked your own environment using the information provided here then you are officially a "H4x0r", and you have earned the right to make use of the Google language settings created specifically for you and your kind. Enjoy!