Appendix B

The Undocumented IntraBuilder

• Disclaimer
• Class DbfIndex
• Class Index
• Class TableDef
• The Credits
• SET PREKEEP=ON
• serverEcho
• allowDupSessions
• DBYSTEM INI Setting
• clear

In this appendix, you will discover some of the undocumented features found in IntraBuilder 1.01, including classes, properties, and configuration settings. You are sure to find some of the undocumented features useful for managing indexes and debugging JavaScript applications.

Disclaimer

The features described in this appendix are undocumented yet functional in IntraBuilder 1.01. As with most new Internet tools, IntraBuilder is going through a period of frequent revisions. As of this writing, there have been two updates since the initial 1.0 release. Version 1.01 added significant client/server features such as the ability to call stored procedures. Version 1.01a provided compatibility with the OEM release of Windows 95b. Be sure to check the IntraBuilder Web site periodically to get the latest release news.

Use of some undocumented features might lead to resource loss and cause IntraBuilder to become unstable.

With each revision, undocumented features may change, become documented, or cease to exist. Do not rely on any undocumented feature in a mission-critical application. Technical support is also unlikely to be available for any of these features.

Class DbfIndex

A class object used to display a current index definition or serve as a parameter to the Database::createIndex() method. This class works with dBASE tables. The DbfIndex class has no methods or events.

Syntax:

[<oRef> =] new DbfIndex([<parent>])

Listing B.1. An example of class DbfIndex: DBFINDEX.JS.

 1: var idx = new DbfIndex() ;

 2: idx.indexName     = 'VDB' ;

 3: idx.expression    = 'UPPER(title)' ;

 4: idx.forExpression = 'PRODUCT="Visual dBASE"' ;

 5: _sys.databases.current.createIndex("title.dbf",idx) ;

 6: 

 7: var q = new Query("select * from 'title.dbf'");

 8: q.rowset.indexName = "VDB" ;

 9: _sys.scriptOut.clear() ;

10: while (! q.rowset.endOfSet )

11: {

12:    _sys.scriptOut.writeln(q.rowset.fields["TITLE"].value) ;

13:    q.rowset.next() ;

14: }

15: q.active = false ;

This script creates a new index on the Title table. Line 3 makes the index case insensitive through the dBASE UPPER() function. The forExpression limits the index to displaying only rows where the expression is true. Lines 7 through 15 display the dBASE titles in the Script Pad's results pane. Using an existing index with a forExpression is the fastest way to filter rows in a dBASE table. Note that the forExpression only hides rows. It does not enforce any integrity or delete rows from a table.

Class Index

A class object used to display a current index definition or serve as a parameter to the Database::createIndex() method. This class works with Paradox and SQL tables. The Index class has no methods or events.

Syntax:

[<oRef> =] new Index([<parent>])

Listing B.2. An example of class Index: INDEX.JS.

1: var idx = new Index() ;

2: idx.indexName = "Location" ;

3: idx.fields    = "Location" ;

4: _sys.databases.current.createIndex("employee.db",idx) ;

The preceding script adds a new index to the Employee table that comes with IntraBuilder. You can find the Employee table in the apps\data folder within the main IntraBuilder folder. The index is ascending, not case sensitive, and it allows duplicate values.

Class TableDef

A class object that represents the structure of a table. You can use the TableDef class to examine the indexes and fields of a table. The field information is the same as you get through a rowset. The index and table type information is unavailable through any other class. To date, the TableDef class has no methods or events.

Syntax:

[<oRef> =] new TableDef([<parent>])

Listing B.3. An example of class TableDef: TABLEDEF.JS.

1: var tDef = new TableDef() ;

2: tDef.tableName = "TITLE.DBF" ;

3: _sys.scriptOut.clear() ;

4: for ( var i = 0 ; i < tDef.indexes.length ; i++ )

5: {

6:    _sys.scriptOut.writeln(tDef.indexes[i].indexName) ;

7: }

The preceding script lists all the indexes of the Title table to the results pane of the Script Pad. Open the Script Pad before running the script to see what happens. You could use a similar technique to populate the options of a select control with index names.

The Credits

On Easter morning, bright-eyed children look high and low for hidden treats. The children learn that treasures await those who have the patience and persistence to be steadfast in their exploration.

Today, computer-hacking kids of all ages stay up all night seeking hidden treasures in computer software. Many CD-ROM games are full of hidden screens and messages. Commercial software also contains hidden dialog boxes with information such as the programmer's name.

IntraBuilder contains hidden credits. As with most Windows software, the IntraBuilder Easter egg is in the About box. To see a list of the many people who brought you IntraBuilder, follow these steps:

1. From the menu, select Help|About.
2. Press Alt+I. When you hold down the Alt key and press the letter I, the dialog starts scrolling the long list of credits, as shown in Figure B.1.

   Figure B.1 : The credits.

3. You can click the OK button during or after the scroll of the credits. Clicking OK closes the dialog box.

SET PREKEEP=ON

IntraBuilder recognizes one DOS environment variable, PREKEEP. If PREKEEP is equal to ON, IntraBuilder does not delete any temporary files created during compilation.

When IntraBuilder compiles a script, it first processes any compiler directives and creates an intermediate source file. IntraBuilder compiles the temporary source file into an object file. Normally, IntraBuilder deletes the temporary file as the last step of the compilation process. You can use PREKEEP to prevent IntraBuilder from erasing the intermediate source file. This file is extremely useful for debugging preprocessor directives.

1. Close all programs and erase all files from the Windows temporary file folder. The default location is C:\Windows\Temp. You can override the default by setting the TEMP environment variable.
2. Open a DOS window in Windows 95. You can open a DOS window by choosing Run from the Start menu and entering COMMAND.
3. Use the DOS SET command to create the PREKEEP variable. You also use SET to view all current DOS variables. In the DOS window, enter the following:
   SET PREKEEP=ON
4. To make IntraBuilder recognize this variable under Windows 95, you must open IntraBuilder from the DOS window. You must be in the BIN folder before loading IntraBuilder. Enter the following in the Script Pad (as shown in Figure B.2):
   CD "\Program Files\Borland\IntraBuilder\Bin"
   INTRA.EXE

   Figure B.2 : Opening IntraBuilder from a DOS window.

5. When you are in the IntraBuilder Designer, you can verify the existence of PREKEEP with the _sys.env.getEnv() method. Open the IntraBuilder Script Pad and enter the following:
   ? _sys.env.getEnv("PREKEEP") ;
   If you see ON in the results pane, you are ready to compile something. If there is no output, IntraBuilder does not recognize the DOS variable.
6. Compile a script that contains preprocessor directives. You can use the prekeep.js file as follows:
   _sys.script.compile("prekeep.js") ;
7. Use the _sys.os.dir() method to locate temporary files that start with INT. IntraBuilder creates the intermediate source files in the temporary folder and begins the filename with the letters INT. In the Script Pad, enter the following:
   _sys.os.dir("C:\\Windows\\Temp\\INT*.*") ;
8. When you have the filename, you can open it with the Script Editor. Before you can read the file in the Script Editor, you have to open the Script Editor properties dialog and select Interpret Text as DOS Text. Until you do this, the characters appear as vertical bars. Figure B.3 shows the file open in the Script Editor after loading in from the Script Pad.

   Figure B.3 : Checking for an intermediary compiled file.

   The first two characters remain unreadable after setting the DOS Text option. Do not try to modify or run this file. Use it only to help you work with the pre-processor.

Any program you compile in the current session of IntraBuilder will create another INT*.* file. You should close IntraBuilder and restart Windows to avoid creating unwanted temporary files. Likewise, do not place SET PREKEEP=ON in your AUTOEXEC file. Doing so prevents IntraBuilder from properly disposing of temporary files.

serverEcho

The serverEcho property and registry setting are debugging tools. You can use them to force an IntraBuilder Agent to draw windows as a designer session. The following steps show how you can use serverEcho to cause an IntraBuilder agent to echo form display within a designer as it also streams HTML to a browser:

1. Open the Windows Registry Editor.
2. Locate the following key:
   HKEY_LOCAL_MACHINE\SOFTWARE\Borland\IntraBuilder
3. Add a new string value by selecting Edit|New|String Value. Name the new key serverEcho, as shown in Figure B.4. Close the Registry Editor when done.

   Figure B.4 : Adding the serverEcho key to the registry.

The second part of serverEcho is the property. This is a hidden form property that defaults to false. If you set it to true before a form opens, the echo happens. The property does nothing when set after the open. To set the serverEcho property, add initialization code into the header as shown in Listing B.4.

Listing B.4. Using the serverEcho property.

 1: var f = new echoForm();

 2: f.serverEcho = true;

 3: f.open();

 4: return null;

 5: 

 6: // {End Header} Do not remove this comment//

 7: // Generated on 02/14/97

 8: //

 9: var f = new echoForm();

10: f.open();

The Form Designer generated lines 9 and 10. Both lines are duplicated in the header as lines 1 and 3. The serverEcho property assignment occurs on line 2, after creating an instance of the form but before opening it. Line 4 contains a return to prevent the form from opening twice.

If you have both the serverEcho registry setting and the serverEcho property set, you can see forms open in the agent and the browser. Figure B.5 shows the form in Netscape Navigator and the echo image in an IntraBuilder agent.

Figure B.5 : Viewing an echoed form.

Never use serverEcho in a production environment. This feature consumes Windows resources that are unnecessary when JavaScript forms are running through a browser. Also never try to work with design tools through an agent. Doing so could lead to undesirable results.

allowDupSessions

The IntraBuilder Server optimizes communications by reusing existing form definitions if a form is repeatedly requested from the same IP address. This is done by using the IP address to take precedence over the session ID. Although this is beneficial in most situations, it might cause undesirable results if you want to run an application through multiple browsers that share a single IP address.

If you are developing a new application, you might want to fire up a few browsers on a single workstation to try out some row locking code. This does not truly emulate multiple workstations using the default IntraBuilder Server settings. You can use the allowDupSessions registry key to force the IntraBuilder Server to treat each session on a single machine as an independent connection. Like the serverEcho key, the allowDupSessions registry key needs to exist only as a string value key. The actual string can be left blank. The IntraBuilder Server looks for this key in the following location:

HKEY_LOCAL_MACHINE\SOFTWARE\Borland\IntraBuilder\1.0\Server

DBYSTEM INI Setting

If you are working with encrypted dBASE tables, the password and encryption keys are stored in a file called DBSYSTEM.DB. Despite the extension, this is not a Paradox table. By default, this file resides in the IntraBuilder BIN folder.

C:\Program Files\Borland\IntraBuilder\Bin

You can change where IntraBuilder looks for the DBSYSTEM.DB file with the INI setting shown in Listing B.5. Add the setting to INTRA.INI for the IntraBuilder Designer and INTRASRV.INI for IntraBuilder agents.

Listing B.5. The DBSYSTEM setting for INTRA.INI and INTRASRV.INI.

1: [CommandSettings]

2: DBSYSTEM=M:\TSHARE

clear

The clear command clears output from the results pane. This is synonymous with the _sys.scriptOut.clear() method. This is one of two Xbase commands that make it easier to work with the Script Pad's results pane. The other command is the question mark, which is documented. You can use the Xbase output commands as shortcut versions of _sys.scriptOut methods. Figure B.6 shows how you can use the commands to quickly evaluate simple expressions.

Figure B.6 : Using Xbase streaming output commands.

Syntax:

clear