DEVELOPER'S GUIDE TO DTFWIN July 31, 2005 John T. Dow info@johntdow.com This document describes DTFWIN from the developer's perspective. The developer is person who is responsible for the customized application created using the DTFWIN Software Development Kit. Read DTFWIN.NEW (the what's new file) to learn what has changed since this file has been updated or to learn what's been changed since you last studied it thoroughly. Read FEATURES.TXT for a description of what DTFWIN can do. The README_W.TXT file gives a brief description of how to install DTFWIN, including preparation of Windows and Q&A for Windows on your workstations. It also tells you how to use the CFG file to configure certain options differently for each workstation on which you are running DTFWIN. You can have a single CFG file or one or more workstations can have their own CFG file to override your standard settings. The CFG file is partially described in the READ_W.TXT file, but most of the settings are described below in Topic 5, Topic 6, and Topic 7. Contents -------- To go directly to a topic when viewing this file, search for the word "Topic" and the topic number. Topic 1: Overview of important concepts Topic 2: Overview of modes (Script, Field, Program) Topic 3: Automatic changes to Q&A Windows appearance and behavior Topic 4: Initialization, configuration, and message files Topic 5: CFG file [DIRECTORIES] section Topic 6: CFG file [SENDMAIL] section Topic 7: CFG file [SPECIAL] section Topic 8: CFG file [INTERNATIONAL] section Topic 9: INI file [MAP] section -- Application specific initialization Topic 10: INI file [DTFWIN] section -- Common initialization Topic 11: INI file [DATABASES] section -- Database definitions Topic 12: INI file [UNIQUE BUTTONS] section -- Form identification Topic 13: INI file [SPECIAL FIELDS] section -- Field mode by coordinates Topic 14: INI file [AUTOMATIC FORM SELECTION] section Topic 15: INI file [NAVIGATION] section Topic 16: INI file [MENU:MAIN] section -- script mode Topic 17: INI file [SCRIPTS] section -- script mode Topic 18: Script mode normal use (menu items) Topic 19: Field mode normal use (F12:command) Topic 20: Program mode (DTFWIN and other fields) Topic 21: Script mode other uses (AUTOSTART etc) Topic 22: Field mode other uses ([SPECIAL FIELDS], FLD:command) Topic 23: CUSTOM programming and buttons Topic 24: Script commands - alphabetical listing Topic 25: Field mode: Alphabetical list of actions Topic 26: Program mode: Alphabetical list of actions Topic 27: Script commands - example Topic 28: Generic list boxes (GLB) Topic 29: Text list boxes (TLB) Topic 30: Multiple choice dialog boxes (DLG) Topic 31: XLOOKUP Topic 32: Buttons (BACK, CANCEL, CLOSE, SAVE, CUSTOM, UNDO) Topic 33: Special function keys Topic 34: What happens if Q&A Windows has a problem Topic 35: List of Q&A menu choices for ALLOW and DENY commands Topic 36: Command line parameters Topic 37: SUMMARY OF COMMANDS Topic 38: DTFWIN GLOBAL VARIABLES Topic 1: Overview of important concepts --------------------------------------- DTFWIN enhances Q&A Windows by providing a customized menu, a script language, management of multiple databases open at once, and a number of new features (such as the ability to post, to run external programs, to put up dialogs and to do list boxes). You tell DTFWIN how to do these things by a combination of an INI file, various supporting files (to be described in detail below), and by making various changes to your database. DTFWIN presents the illusion that only one program is running, when in fact you may have DTFWIN and two or three databases open simultaneously. In fact, the user does not start Q&A Windows, does not tell it to open or close a database, and does not tell it to exit; all of these things are done by DTFWIN instead. Q&A Windows databases do not appear to be separate programs because they have no menus and because their title bar changes to reflect the application name and the databases application name (which may be more descriptive than the actual file name for the DTF and IDX files). Furthermore, DTFWIN controls the location on the monitor of the databases relative to DTFWIN -- that is, the user cannot drag one away and lose it. The user cannot change the size of DTFWIN or of any of the databases; you control this in the INI file. If another program happens to cover up one or more of DTFWIN, the databases, and any dialogs that may be visible, clicking on any of them will immediately bring all of them to the fore. Minimizing DTFWIN will also minimize all databases, and restoring DTFWIN from the task bar will also restore all databases. DTFWIN and Q&A Windows (that is, your database) must work together, and to work together they have to exchange information. The exchange of information takes place through buttons and fields. The DTFWIN program can read the text on buttons and can "spy" on and change the content of the current field. Thus, from within the database you can control DTFWIN by clicking on buttons and by putting certain values into certain fields. Likewise, the database can learn the result of an action by testing to see how a field has been set. There are three modes in which actions in the DTFWIN program can take place: script, field, and program. Typical script mode : a menu choice runs a script Typical field mode : clicking a button closes a database Typical program mode: programming posts to another database These modes are desribed in more detail in the next section. Many features can be invoked in two or three of these modes. However, sometimes there are small differences in the syntax and capabilities. For example, in field mode, a list box returns a key value into the field and presses ENTER to trigger field exit programming. In program mode, the value is returned into the DTFWIN field (which serves many purposes, see below), so DTFWIN can't return just the value selected by the user but must also return information so the database programming can determine what's going on with a series of IF statements. In script mode, the information selected by the user is left in the "result clipboard" (see below). In the program mode, there is one particular field that is often used as a portal between the database and the DTFWIN program. That by custom is called the "DTFWIN field". Other fields can also be used in program mode by assigning values with the "PGM:" prefix. In the field mode, any field can also be used to exchange information with the DTFWIN program. This mode is generally used for list boxes, image viewers, phone dialers, and other actions that are closely tied to specific fields. Some actions result in text that remains in a "clipboard". For example, if a script has generated a list box (using the GLB command), the result of a user making a selection is placed into the "result clipboard". You can access this clipboard using various commands, such as SET KEY or SET TITLEBAR. The SET KEY command sets one of nine other clipboards which are typically used for key values (to enable DTFWIN to coordinate multiple databases). Topic 2: Overview of modes (Script, Field, Program) --------------------------------------------------- There are three modes for commands: Script, field, and program. This section briefly lists how these modes can be used. This is a reference section -- much of this will not make sense until other parts of this document have been read. (Names in square brackets are sections in the INI file.) Typical or normal use --------------------- Script mode : Menu selections in [MENU:MAIN] Field mode : "F12:command" on button next to a field Program mode:"DO command" assigned to DTFWIN field in database Other uses ---------- Script mode ----------- 1) "AUTOSTART" script in [SCRIPTS] 2) Auto_Retrieve_Script in [DATABASES] 3) "F12:SCRIPT dtfwinscriptname" on button next to a field. 4) "F12" on button, "SCRIPT dtfwinscriptname" in [SPECIAL FIELDS] 5) "DO SCRIPT dtfwinscriptname" assigned to DTFWIN field. Field mode ---------- 1) "F12" on button, command in [SPECIAL FIELDS] 2) "FLD:command" assigned to any field in database. Program mode ------------ "PGM:DO command" assigned to any field in database. If this option is used witht the DTFWIN field, it is not necessary to identify it using coordinates. For field mode commands, DTFWIN can identify the active field using either of two techniques. 1) BUTTON: There is an "F12" field immediately to the left of the field, and the text on the button specifies an action. Example of text on a button: F12:TLB CITYST.TXT This would invoke the TLB dialog using the CITYST.TXT file. (See Topic 29 for a full description of TLB's.) This technique is employed when the user presses the F12 key when in the field or if the user clicks on the button and there is a Q&A Windows script associated with the button that tells Q&A to go to that field. This is described in detail in "Topic 18: Field mode normal use (F12:command)." 2) COORDINATES: There is an entry in the [SPECIAL FIELDS] section of the INI file that identifies this field by its coordinates. This is described in detail in "Topic 12: INI file [SPECIAL FIELDS] section -- Field mode by coordinates." The button technique is easier to set up and maintain because you don't have to determine coordinates and if you redesign the form a little, as long as you keep the button next to the field, it won't break (whereas if you're using coordinates and move a field, you have to get the new coordinate values and edit the INI file to reflect the new values). The coordinate technique may be used with the DTFWIN field, but the various popup list boxes and other features activated by F12 buttons can best be designed using the button technique. You can also use the "PGM:" prefix to DTFWIN commands; this allows the DTFWIN field, or any other field, to be used without worrying about coordinates. Topic 3: Automatic changes to Q&A Windows appearance and behavior ------------------------------------------------------------------ DTFWIN automatically modifies the appearance and behavior of Q&A Windows to improve Q&A's functionality and to make it fit more seamless into an application that consists of DTFWIN and one or more databases. DTFWIN removes the menu from Q&A Windows, so that only the application's menu (defined in the INI file) is visible. DTFWIN removes the system menu and the little icon at the left side of the title bar. It removes the minimize and maximize buttons from the Q&A Windows title bar and does not remove but greys out the "X" at the right side of the title bar. These changes prevent the user from separately controlling the database. For example, if the user minimizes or moves DTFWIN, the Q&A Windows databases will also be minimized or moved automatically by DTFWIN. The user cannot move a database separately from the entire application. If another program partially covers DTFWIN and one or more of the databases, just clicking on DTFWIN or on any of the databases will make them all come in from of the program. DTFWIN changes the text on the title bar so that it does not read "Q&A" followed by the file name of the database but instead reads something like this: <> (2) DTFWIN removes the "thick borders" from databases so that the user cannot resize them. The size of databases is controlled by the INI file. Pressing F1 in a field causes Q&A Windows to display generic help. Normally, if the user wants to see the field help, he must first select "Records", then "Field Help". DTFWIN changes Q&A Windows so that pressing F1 in a field will display the field help, not the Q&A Windows help file. To restore standard Q&A Windows behavior, put FIELDHELP=N in the [DTFWIN] section of the INI file. (If you really want to provide the user access to the standard Q&A Windows help file, you could run Winhelp.exe from a menu choice.) If a dialog appears with "This field requires a value." or "Do you want to discard the changes" then DTFWIN stuffs ENTER automatically. If the database programming sets a field value to "", DTFWIN will erase the and press the Down Arrow key. If the field has a restrict spec, this will cause Q&A to popup the list of allowable choices for the field. If you set a field to some text followed by "", DTFWIN will delete the "" and press the Enter key. This is useful when a Q&A Windows is used to give a field a value and then go to the field. DTFWIN will press Enter to trigger the field exit programming. Topic 4: Initialization, configuration, and message files --------------------------------------------------------- In discussing the INI and CFG files, let's assume that your application is "Mother's Apple Pie", or MAP. The program name you have chosen for DTFWIN is MAP.EXE. DTFWIN is passed certain information about the databases in a pair of initialization files (eg MAP.CFG and MAP.INI) that use a structure similar to Windows INI files. The CFG file is optional (everything specified in it has a reasonable default); the INI file, which defines the heart and soul of the application, is required. IMPORTANT: Do not use an editor that puts tab characters or terminating characters into either of these files. The Windows program NOTEPAD and the DOS program EDIT are suitable, Q&A's word processor is not. The purpose of the CFG (configuration) file is to specify information that may vary from workstation to workstation. For example, you may want to point to different QAWIN directories for each workstation. The CFG file is described in detail in the README_W.TXT file. The purpose of the INI file is to define the application, which involves specifying information common to all workstations. Therefore, in a multiuser environment, it should be placed on a network volume and shared by all users. The information in these files is divided into several sections, with section names enclosed in square brackets like this: [SECTION NAME] The CFG and INI files have sections listed here. Some are optional. They must be in this order: CFG [MAP] Optional, app specific [DIRECTORIES] Mandatory [SENDMAIL] Optional [SPECIAL] Optional [INTERNATIONAL] Optional INI [MAP] Optional, app specific [DTFWIN] Mandatory [DATABASES] Mandatory [UNIQUE BUTTONS] Optional [SPECIAL FIELDS] Optional [AUTOMATIC FORM SELECTION] Optional [NAVIGATION] Optional [MENU:MAIN] Mandatory [MENU:other] Optional [MENU:UPDATE dbname] Mandatory if updating [MENU:CONFIRM] Mandatory if updating [SCRIPTS] Optional Sometimes the information in each section is in fixed format records, so when adding new records be sure to copy the exact format of the template record provided in each section. (More on this below.) Any record beginning with a semicolon is a comment. Comments may also be added on the right of some information records, in the "Remark" column identified by the template records. Make sure that all unique button text, form names, and special field names are unique across all databases. The INI file has several sections. The INI file has an application specific section (eg [MAP]) and a [DTFWIN] section that are both read and processed before the user logs on. The other sections of the INI file are read and processed after the user logs on. MESSAGES AND FORCED LOGOFF A message can be broadcast to all users and all users can be forced to logoff from DTFWIN (although one or more can be exempted from the forced logoff). To activate, create the text file MESSAGE.TXT in the DTFWIN directory. This can be done using an editor such as notepad. For a simple message (eg "Early dismissal at 3PM"), you can also type ECHO Early dismissal at 3PM > MESSAGE.TXT while at a DOS prompt in the DTFWIN directory. The message can be one or more lines. Total number of characters is 1000. Forced logoff is caused by putting USERLOCK in the first line, like this: USERLOCK MARY BILL All users must logoff now for routine maintenance. In this case, the first line will not be displayed as part of the message. The words MARY and BILL that appear after USERLOCK on the first line of the file are user id's (the userauth feature must be set in the INI file). Those users will receive the message but will not be forced to logoff. Presumably MARY and BILL need access to perform the routine maintenance. If no user id's appear after USERLOCK, all users will be forced off. For example, a BAT file that is scheduled to run at 3AM every day could do ECHO USERLOCK > MESSAGE.TXT, thus causing everyone to be logged off. It is not necessary to have a message on the second (and possibly additional lines) when USERLOCK is used. If there is no message, the users will be forced to logoff without notice. Topic 5: CFG file [DIRECTORIES] section --------------------------------------- The CFG file allows you to configure certain options differently for each workstation on which you are running DTFWIN. The CFG file has a [DIRECTORIES] section that is read and processed prior to the user logging on. Here is an example of a CFG file's directories section with the default values shown: Possible settings Defaults --------------------------------- -------------------- TEMPDIR=C:\TEMP C:\WINDOWS\TEMP QAWINDIR=C:\QAWIN C:\QAWIN DATADIR=F:\MAPDATA NAVIGATION=F:\MAPDATA\NAV.TXT None These directory specifications allow you to control where DTFWIN on each work station locates the following: 1) DTFWINDIR the directory where the DTFWIN executable exists (Cannot be changed in the CFG file.) 2) TEMPDIR the temporary directory The defaults are, in this order: %TEMP% %TMP% C:\WINNT\TEMP\ C:\WINDOWS\TEMP\ It can be set either with a string, as in TEMPDIR=D:\TEMP or with an environment variable, as in TEMPDIR=%DTFWINTMPDIR% 3) QAWINDIR the directory where Q&A Windows is installed, and 4) DATADIR the directory where the databases are located (by default, DATADIR = DTFWINDIR). 5) DATADIR2 another directory where some or all of the databases (or other files) may be located. 6) NAVIGATION allows you to have a navigation section external to the INI file. (Note that it doesn't specify a directory but a file.) Topic 6: CFG file [SENDMAIL] section ------------------------------------ The optional [SENDMAIL] section in the CFG file allows specifying BCC, which is used with DO SENDMAIL to automatically send a blind carbon copy of the e-mail to the designed address (even if the user sending the e-mail does not specify this). Example: [SENDMAIL] BCC=fredbaker@bakersbuttons.com BCC may also be explicitly specified with the DO SENDMAIL. Topic 7: CFG file [SPECIAL] section ----------------------------------- The optional [SPECIAL] section in the CFG file allows workstation specific control of vertical size of DTFWIN. Example: [SPECIAL] DTFWINHEIGHT=50 The default DTFWIN heights are: 40 Windows 95/98/NT/2000/XP (See note below) 56 Win 3.1 Note: 40 assumes that Display Properties>Appearance>Scheme is set to Windows Standard. For example, if you have selected Windows Standard (Extra Large) then you should use 50 instead of 40. The optional [SPECIAL] section in the CFG file also allows workstation specific control of the overall size of DTFWIN and the databases if the screen size is reduced due to a horizontal or vertical status bar. Example: [SPECIAL] HBARSIZE=28 VBARSIZE=40 The default bar sizes are 0. With a status bar across the bottom of the screen, setting HBARSIZE=28 (or other appropriate value > 0) would prevent overlap of DTFWIN and the status bar. The DTFWIN program normally wakes up and checks for various things 10 times per second. (For example, has the database placed something of interest into the DTFWIN field.) This interval can be changed. The value is in milliseconds, so TIMER=100 is 1/10 second. [SPECIAL] TIMER=100 Q&A for Windows was developed in the days of 16-bit windows, and multistasking was handled differently then. Perhaps for that reason, when the program should be idle because it is waiting for a user to make a menu selection or to enter a value into a field, the program unfortunately is a cpu hog. It just sits in a loop, consuming CPU cycles until there is something to do. You can see this if you open the task manager on Windows 2000 or XP and look at the process. With multiple Q&A Windows running on a system, this CPU load can have a major adverse effect on other applications. A solution to this problem involves a patched version of Q&A Windows, an additional DLL that is customized to the application, and a 32-bit Windows program (that remains hidden from sight). The total package reduces CPU load from near 100% to less than 3%. Available separately. The following option in the CFG file is required to turn on this option. [SPECIAL] DTFX=Y In some cases, grayed out menu items seem to cause their menus to also be grayed out. This was seen to happen regularly at an Australian site as well as on a Citrix server. The option DISABLED=n allows an override of the default behavior. Disabling menu choices without graying them out seems to be more reliable, if less convenient. Choose one of the following. The default can of course be omitted. Selection 1 works best in difficult situations. Selection 2 is for historical comparison: it was the previous default. [SPECIAL] DISABLED=0 default GRAYED and DISABLED DISABLED=1 DISABLED but not GRAYED DISABLED=2 GRAYED but not DISABLED Topic 8: CFG file [INTERNATIONAL] section ----------------------------------------- In this optional section you can specify which version of Q&A for Windows you are using on this workstation, and which keyboard you are using on this workstation. Here is an example configured for the German version of QAWIN: QAWIN=GERMAN The default version of QAWIN is ENGLISH. You may specify GERMAN, DUTCH, FRENCH, or SWEDISH. This affects DTFWIN's ability to issue commands to QAWIN to open files, run reports, etc. As of 25 February 2002 it does not alter all the messages that DTFWIN displays. Also, text in list boxes is controlled by the files supplied by the user; this text is not built in to DTFWIN. DTFWIN automatically adjusts for the keyboard you are using. Topic 9: INI file [MAP] section -- Application specific initialization ---------------------------------------------------------------------- There may be a section identified by your application name in square brackets, [MAP] in these examples. Here are some examples of entries that might exist in this section: [MAP] VIEWER=C:\WINDOWS\MAGICVEW.EXE D:\IMAGES\FUNNY\%1.GIF WINWORD=C:\WINAPPS\MSOFFICE\WINWORD.EXE F:\DOCS\%1.DOC These are typical of the customized things that are possible. They indicate where a viewer is located and the files to be viewed, and where a word processor is located and where the documents are located. These two entries would be used when the user presses F12 on special fields that are associated with the viewer or word processor. (This is just an example. You can probably use the field mode command "RUN WINWORD.EXE %1.DOC", which doesn't require any customization.) Topic 10: INI file [DTFWIN] section -- Common initialization ------------------------------------------------------------ These are the options available in the [DTFWIN] section of the INI file. These options are common to all DTFWIN applications. Remember in the example shown here that lines beginning with a semicolon (;) are comments. [DTFWIN] ; This section has settings used by all DTFWIN applications. ; This section is read before the user logs on. USERAUTH=APPLEPIE WIDTH=750 HEIGHT=545 ;XPOS=0 ;YPOS=0 ;BUTTON=LETTER ;FIELDHELP=Y ;F12xProximity= ;F12yProximity= ;TIMEOUT= USERAUTH -------- The [DTFWIN] section may include a setting for USERAUTH. This specifies the database to be used for logons (APPLEPIE.DTF in this example). If password protection is not used for databases, omit this. If you specify USERAUTH, when DTFWIN starts it will ask for a user id and password and authenticate the user against this database. (It doesn't actually open the database at this point, rather DTFWIN just uses it as a repository of users and their passwords.) Specify only the actual name of the database, not the "script name" specified in the INI file. Do not provide full path - the database must be in the DATADIR directory. HEIGHT, WIDTH, XPOS, YPOS ------------------------- The [DTFWIN] section of the INI file can also specify the size and position of the MAP.EXE program. If this section is omitted or any of the values omitted, the default is to use the entire screen. The values HEIGHT, WIDTH, XPOS, and YPOS can be specified. WIDTH is the width for the MAP program and is also the default width for the databases. HEIGHT is the combined height of the MAP program and the databases (which by default fit below the menu). By default, the MAP program would fill the entire screen. If the screen is 800 x 600, the default values for width and height would be 800 and 600. Bear in mind that you have to design the QAWIN forms for a particular screen resolution and they won't look right with a different resolution. You should design them for the lowest resolution monitors that will be used to run the application. For example, if most users have 800 x 600 monitors but a few have 1024 x 768, design for 800 x 600. Specify WIDTH=800 and HEIGHT=600 and then things will look right even on the larger resolution monitors. In this case, the program and databases will exactly fill the 800 x 600 monitors and be centered in the 1024 x 768 monitors. Here are approximate sizes for forms for various screen resolutions. Resolution Form size in inches 640 x 480 6 1/2 x 3 1/2 800 x 600 8 1/4 x 5 1/4 1024 x 768 10 1/2 x 7 1600 x 1200 16 1/2 x 10 3/4 You can specify where the MAP program is to be placed. By default, it is centered on the screen. See below for hints on determining values for these parameters. BUTTON ------ The value of BUTTON is the text you put on a custom button. Example, you might want a button labelled "FAX": BUTTON=FAX If the user clicks on the button, your database should execute a Q&A Windows script to send control to the DTFWIN field, at which point the DTFWIN program will enter the following text and press Enter to trigger the field exit programming: BUTTON formname,buttonname "formname" is the form name from the INI file; you might want to use @layout instead. "buttonname" is the text that was on the button that was clicked. At present, DTFWIN only supports one custom button, so this information is redundant. DTFWIN can also be customized if necessary to handle clicks on this button if database programming or running a script is not sufficient. FIELDHELP --------- Pressing F1 in a field causes Q&A Windows to display generic help. If the user wants to see the field help, he must select "Records", then "Field Help". DTFWIN changes Q&A Windows so that pressing F1 in a field will display the field help, not the Q&A Windows help file. To restore standard Q&A Windows behavior, put FIELDHELP=N in the [DTFWIN] section of the INI file. If you really want to provide the user access to the standard Q&A Windows help file, you could run Winhelp.exe from a menu choice. F12xPROXIMITY, F12yPROXIMITY ---------------------------- These two parameters control how close an F12 button has to be to a field for DTFWIN to pair them so that the label on the F12 button will be used as a field mode command for the field. The x distance is measured from the right side of the button to the left side of the field (so the size of the button does not affect proximity). The y distance is from the top of the button to the top of the field. F12xProximity defaults to 10 and F12yProximity defaults to 5. TIMEOUT=nn,logfile ------------------ The log file is optional. Examples: TIMEOUT=30 30 seconds, no log TIMEOUT=1200,c:\temp\timeout.txt 20 minutes, write log The log file is optional. If specified, it appends records like this to the specified file. 02/05/2004 14:51 Fred. DB's open = Customer, Salesmen If you specify TIMEOUT=300 in the [DTFWIN] section of the INI file, a user will time out after 300 seconds of inactivity. The entire application will shut down, and any Q&A databases that are open will be closed. If you set a negative value, such as TIMEOUT=-10, then the timeout interval will be 10 seconds but it won't actually timeout. It will only display a message saying "TIMED OUT". Use this to test the behavior of DTFWIN to learn under what conditions it will time out. The time out doesn't work in all cases. For example, if the user is in a DTFWIN dialog, it won't time out until he exits from it. However, it does time out if he has qawin up and isn't doing anything. Changing a form or tabbing to another field will keep it from timing out. Changing the contents of a field (first 100 characters) will keep it from timing out. By default there is no time out. AUTOENTER=Y ----------- Automatic stuffing of Enter into the "This field requires a value." and "Do you want to discard the changes" dialogs is turned on by putting AUTOENTER=Y in the [DTFWIN] section of the INI file. This option is useful if you have specified a MANDATORY special field or are using the REVERT option and don't want the user to have to reply to the confirmation prompt. The default is OFF. Topic 11: INI file [DATABASES] section -- Database definitions -------------------------------------------------------------- The [DATABASES] section of the INI file defines the databases used by DTFWIN. For each database, provide an application name to be used in the script as well as the actual name (with no path and no extension) of the DTF and IDX files. You may also provide the size and position for the databases, but this is optional. All database files must be in the DATADIR or DATADIR2 directories as specified in the CFG file. (The default directory is the same directory where dtfwin is installed.) Example (the four lines are numbered and split for clarity): [DATABASES] 1 ;AppNameForDB....... Actual name......... Width Height Xpos Ypos 2 Client Client 390 500 0 0 3 Store STORE 360 500 390 0 4 Old Clients Client 1 Height Xpos Ypos Key Auto_Retrieve_Script.......... Lock 2 500 0 0 Y 3 500 390 0 1 RETRIEVE PIC 4 In this example, the first database is actually Client.DTF and Client.IDX. It is referred to in the scripts as "Client". Neither name should have any special characters, although blanks are permitted in the application name. Databases are normally located in the DATADIR that you specify in the CFG file on the DATADIR= line. If you need to, you can refer to a database that is in another location. In the example above, there is a Client database in another directory, perhaps an archive copy. (Perhaps the programming in the regular Client database knows to look in the archive copy of the Client database for old information about existing Clients.) By specifying as shown above, you specify that the database is located in the second data directory, defined by DATADIR2= in the CFG file. (The backslash here is optional, since DTFWIN always provides one automatically at the end of DATADIR and DATADIR2. If you put another one here for readability, it is ignored.) Four fields specify the size of the database (WIDTH and HEIGHT) and the location (Xpos and Ypos). The position is relative to DTFWIN. Notice that DTFWIN was defined above to have a width of 750 and a height of 545. The two databases shown here have a combined width of 750. Both have a Ypos of 0 (so they both fit tightly under DTFWIN). The first has an Xpos of 0 (so it's aligned on the left with DTFWIN) and the second has an Xpos of 390, which is the width of the first, so the left side of the second database exactly buts up against the right side of the first. Thus, these two databases will be opened side-by-side, or tiled. Caution: if you make a database too narrow, the user may not be able to see all of the tool bar. For example, when in retrieve mode, there is an icon with a green check mark (which is equilvalent to pressing F10) and an icon with a red X (which is equivalent to pressing ESC). A minimum width of 600 is suggested. You can leave any or all of these position and size fields blank and DTFWIN will pick reasonable defaults. See OldClients in the example above. To determine the size and location of DTFWIN and for the databases, put "@SIZE" on the command line. This will allow you to grab the corner of Q&A Windows for each database to resize it until it is right for the particular database. You can then grab the window using the title bar and move it to the desired location. Do this for more than one database at time if you want them to fit together in particular fashion. Having done this, use DTFWIN's "Help -> Technical" menu item to see the size and location of each database and of DTFWIN. If you do not specify @SIZE on the command line when starting DTFWIN, you cannot change the size of the databases. The "Key" column and the "Auto_Retrieve_Script" cause DTFWIN to trigger the named script if you switch to or open the database after changing the value of the key clipboard. You can change the value using SET KEY script command or with the program mode command PGM:DO SET KEY=xxxxxxx. A typical use for this would be a primary database, such as Client, and one or more secondary databases, such as ORDER. For each record in Client there can be one or more records in ORDER. If you have selected a Client and set KEY1 to the Client number, then when switching to the ORDER database, DTFWIN will automatically run the script which can do a retrieve for the records for that Client. Specify both a key (1 - 20) and a script. If a script is already running, the Auto_Retrieve_Script will run after the current script exits. Special cases: A) If the key is 999, the script is run unconditionally. B) If the key is 888, the script is run unconditionally except if the database is in the retrieve spec. If the "Lock" column has "Y" in it, the database cannot be closed to free up a qawin. Explanation: whenever you want to open a database, DTFWIN looks for a copy of Q&A Windows that's free and uses it to open the database. (You use QAWINCPY.EXE to make up to 10 copies of QAWIN.) If there isn't a free qawin available, DTFWIN has to close a database so it can open the next one. The lock option allows you to prevent certain databases from being closed by this process. Topic 12: INI file [UNIQUE BUTTONS] section -- Form identification ----------------------------------------------------------------- Most of DTFWIN's capabilities do not require it to know exactly which form is up on the screen because many of these capabilities can be triggered by F12 buttons (see next topic) or under the control of the Q&A programming. However, certain capabilities (such as automatic form selection and the use of the DTFWIN special field) do require DTFWIN to recognize which form is in use. DTFWIN cannot read the form or its name (because it is a bit-mapped image), but it can read the text on the buttons on the form. Therefore, to uniquely identify forms, each must have a button with unique text. DTFWIN does not care what the text is, it simply must be unique. The text for all these unique buttons is passed to DTFWIN via the [UNIQUE BUTTONS] section in the initialization file. The format of this section is as follows. [UNIQUE BUTTONS] ;Unique button text Form name Remarks BASIC ROOM DATA BASIC ROOM DATA ANYTHING HERE INFORMATION ABOUT BEDROOMS BEDROOM INFORMATION ABOUT KITCHENS KITCHEN The columns shown here are not exact. The exact columns are: Button text Col 1 Form name Col 42 Remarks Col 74 When making a new entry in the file, use the line beginning with ";" as a template. This record names the fields and indicates the proper columns to use. The line beginning "Help for Browse" indicates that there a button with the text "INFORMATION ABOUT BEDROOMS" on the "BEDROOM" form. If you don't have a button on a form that is obviously unique, just create a button that's out of sight (put it down farther than the user would ever scroll) and use some standard text on it, such as an "=" followed by the form name. Topic 13: INI file [SPECIAL FIELDS] section -- Field mode by coordinates ----------------------------------------------------------------------- Many of DTFWIN's capabilities are based on field mode commands which are associated with specific data fields. Therefore, DTFWIN must be able to recognize which is the active field at any given time. An active field is open for data entry or editing. (This field looks different and has a blinking cursor in it.) The normal way to identify the active field so these commands can be used is by means of the "button technique," described in "Topic 14: Field mode normal use (F12:command)". The button technique is based on having a button next to the field so that DTFWIN can identify the field. For some situations this is not possible as a way of identifying a field. Therefore it is possible to identify a field by making an appropriate entry in the [SPECIAL FIELDS] section of the INI file, as described here. The is called the "coordinate technique." For the coordinate technique, DTFWIN tries to identify the form (by looking for a unique button) and then looks for the screen coordinates for the field in the [SPECIAL FIELDS] section of the initialization file. This section has the following format. [SPECIAL FIELDS] ;Form name or * or ** -X- -Y- SpclFldId Remarks =Order Form 210 120 GLB PARTS.GLB (The columns shown here are not exact. When making a new entry in the file, use the line beginning with ";" as a template. This record names the fields and indicates the proper columns to use.) When the user presses F12 in a field, DTFWIN tries to find a match based on the form name and the screen coordinates. If it finds a match, it then knows the field mode command you want for that special field. Note that the wildcard * in the form name field matches any form that has a unique button, and ** matches any form even if it doesn't have a unique button. In this cae, there is a button with the text "=Order Form" to uniquely identify the form. In the example shown above, if the field is at 210,120 and on the "Order Form", the field mode command for the special field is "GLB PARTS.GLB". To determine the coordinates for a field, put "@DESIGN" on the command line when running DTFWIN. (If using Windows 95, you can simply type "MAP @DESIGN" in a DOS session for the Mother's Apple Pie application.) Then go to the field in question and press F12. Note: This will not work until you have put a correct entry in the [UNIQUE BUTTONS] section so DTFWIN can identify the form. When @DESIGN is in effect you will also be permitted to design the input form. This is to facilitate adding and positioning fields, particularly the DTFWIN field. (Normally users are prevented from doing anything that would alter the form design.) Topic 14: INI file [AUTOMATIC FORM SELECTION] section ----------------------------------------------------- DTFWIN will automatically change forms based on the contents of special fields listed in the [AUTOMATIC FORM SELECTION] section of the initialization file. This section has the following format. [AUTOMATIC FORM SELECTION] ;SpclFldId Code Value Form to go to Remarks RoomType BEDROOM BEDROOM RoomType KITCHEN KITCHEN (The columns shown here are not exact. When making a new entry in the file, use the line beginning with ";" as a template. This record names the fields and indicates the proper columns to use.) You would also have to identify a field on each form like this: [SPECIAL FIELDS] ;Form name or * or ** -X- -Y- SpclFldId Remarks * 117 98 RoomType In this example, the wildcard can be used for this special field's form name because the "RoomType" field is at the same location on each of the forms on purpose. This automatic form selection only happens when a special field is the active field. In that case, DTFWIN repeatedly checks the value of that field as displayed, even while the user is entering data into the field or editing an existing value. The combination of the name of the special field (such as "RoomType") and the value of the field (such as "BEDROOM") is used to determine which form to change to. If there is no match, DTFWIN will not change the form. The form to change to need not be an identifiable form (ie it does not have to have a unique button). Make sure the name of the form in the initialization file exactly matches the form name in the database. Topic 15: INI file [NAVIGATION] section --------------------------------------- By making entries in the [NAVIGATION] section of the INI file, you can specify the choices to appear on the navigation menu choice. Each choice consists of descriptive text, a database name, a form name, and optionally a field name. Upon selecting one of these choices DTFWIN will switch to the appropriate database, form, and field (if specified). If necessary, DTFWIN will open the appropriate database. You may create a separate INI file that only contains the [NAVIGATION] section. This makes it easy to update the NAVIGATION section independently of the rest of the INI file. To exercise this option, put a line in the [DIRECTORIES] section of the CFG file with NAVIGATION= followed by the file name or a complete path and the file name of the file containing the [NAVIGATION] section. Example: "NAVIGATION=NAV.INI" would specify a file in the DTFWIN directory. You could also specify "NAVIGATION=D:\LOCAL\NAV.TXT". The separate file must have exactly the same structure as the [NAVIGATION] section of the standard INI file. However, the section header ([NAVIGATION]) is optional in the separate INI file. Topic 16: INI file [MENU:MAIN] section -- script mode ----------------------------------------------------- The menu items and their associated scripts to be executed for each menu item are defined in the [MENU:MAIN] section. Topic 17: INI file [SCRIPTS] section -- script mode --------------------------------------------------- Scripts not associated with menu items are in the [SCRIPTS] section. There are several ways that these scripts can be invoked. See the "Script mode other uses (AUTOSTART etc)" topic. Topic 18: Script mode normal use (menu items) --------------------------------------------- Here is an example of a menu structure with associated scripts. [MENU:MAIN] &File = MENU print &Portrait = STUFF TP print &Landscape = STUFF TP ;These two lines are comments. ;The next line generates a horizontal line in the File menu. SEPARATOR e&Xit = EXIT &Client = MENU &Main Menu = OPEN Client FORM "main" &Fancy data = OPEN Client FORM "Fancy Pants" &Windows = MENU &Client = IFOPEN Client SETFOCUS Client &Navigation = NAVIGATION &Help = MENU &Technical = TECHNICAL &About = ABOUT To the left of the "=" is the text that is to appear on the menu. The ampersand "&" precedes the letter that is to be highlighted in the menu. Indentation indicates menus and submenus. Thus, "File" appears on the main menu because it is not indented. "print &Portrait" appears on the File menu because it is indented. "&Client" is on the main menu because it is not indented. You can have several levels of submenus by indenting one more column for each level. The "=" must appear in column 11 or greater. Extra blank spaces can appear between items on the line and are ignored. You may indent as desired to improve readability, as long as there are at least 10 leading spaces on lines that are not new menu items. (Spaces in quoted strings or in the menu text are not ignored.) Blank lines and comments (lines beginning with a semicolon ";" or //) are ignored. A line with "separator" will generate a horizontal line on the menu to separate items above and below it. The column in which "separator" appears is critical, just like other menu items. Separators can be used at any depth. Menu choices can be restricted to certain users. Use this statement to begin a block of INI menu statements that should be restricted or one or more specific users. IFUSER userlist Use this statement to end the block. ENDIFUSER These statements maybe indented for consistency with other statements. The user list consists of more or more logon userid's, separated by commas. Example: IFUSER JOHN,MARY,WILLIAM DSS Signed = PROMPT "CentreLink form signed" "Enter Agent #" 0 7 SET KEY01,1,7 PROMPT "CentreLink form signed" "Enter Date" 0 10 @date SET KEY02,1,10 DTFDATA ARRANGE PSTZR.QAX PSTZR.TMP "," TLB PSTZR.TMP ENDIFUSER Topic 19: Field mode normal use (F12:command) --------------------------------------------- Much of the enhancements DTFWIN provides to Q&A Windows involves the use of "F12" buttons next to special fields. The user clicks on the button or presses F12 when in the field and DTFWIN springs into action, popping up a list box or running an external program to dial a phone number. You can easily associate buttons with the field mode commands for special fields. Thus, the user can be in the field and press F12, or he can click on the button and have the same effect. To set up an F12 button, first create a script that goes to the special field. (You might give the script the same text as the name of the field; eg "Client ID".) Then put a button on the form next to the special field. The button must have the label "F12:" followed by a field mode command. Example: "F12:GLB Client.QAX". You can make a small, square button with no visible label by putting some spaces before the "F12" in the label when you create the button on the form. See WinDemo for an example. If you have a lot of text on the button, you'll need a lot of spaces to make it appear blank. If the total width is too great, it may be truncated and not work. In that case, make the button smaller and you won't need as many spaces in front of the text. Now, when the user clicks on a button and Q&A Windows goes to the field, DTFWIN will automatically act exactly as if F12 was pressed in that field. Topic 20: Program mode (DTFWIN and other fields) ------------------------------------------------ You have a lot of control of DTFWIN using a special field, the "DTFWIN field". This field serves as a "portal" between the database and the DTFWIN program. You may identify this field by putting its coordinates in the [SPECIAL FIELDS] section of the INI file. You cannot identify it by the so-called "button technique" of putting a button next to it. However, by putting "PGM:" before any program mode command, the field can be used without specifying coordinates. In fact, this technique can be used with any field. However, from a programming standpoint, it is good to keep as much programming in one field as possible because it's easier to find that way. Hint: If you have a DTFWIN field on a form but can't locate it because you've cleverly hidden it behind something else, if you run the application with the @DESIGN command line option and then press F12 in any field, a question will appear asking if you want to go to the DTFWIN field. If you select Yes, control will go to the DTFWIN field. The DTFWIN field can be used to display standard Windows dialog boxes to convey information to the user and to ask questions to be answered by standard buttons such as "OK", "Cancel", "Retry", etc. This field should not be used as an actual data field and the user should never enter the field. Instead, database programming should set the field to certain types of values and then goto the field, thus triggering action on the part of DTFWIN. Should the cursor enter the DTFWIN field (e.g. by back tabbing or by using the mouse), if field is blank (and not in the retrieve spec), DTFWIN will enter "EMPTY" and press the Enter key to trigger database programming to allow the program to take control from the user. In addition to these standard uses of this field, customization can use this field for other purposes as well. To tell DTFWIN to do something, the Q&A programming should set the field to a particular value then do "GOTO DTFWIN". This will cause the field to become active. DTFWIN will notice the field, read its value, and do as you told it to. In most cases, when it's done doing whatever you wanted it to do, it places a value into the field to pass back status or other information. You can then have on-field-exit programming that can obtain this information and act accordingly. Call the field "DTFWIN" because it's used to communicate with the DTFWIN program. (The field does not actually need to have that name, but should as a matter of convention.) Put the coordinates for the field in the [SPECIAL FIELDS] section of the INI file and identify the field as "DTFWIN". (See the WINDEMO.INI file for an example.) There should be on-entry navigation so that if the user cursors through the DTFWIN field, control will automatically jump over it. If someone is allowed to enter the field and it's blank, the program will detect this and enter "EMPTY" into the field and then press Enter, triggering the on-field-exit programming. Your on-field-exit programming can then clear the field and transfer control to the field of your choice. The size and placement of the DTFWIN special field is important because your programming and DTFWIN.EXE use it to pass information back and forth and you don't want it to be too visible. Basically, you want it to be in the center of the screen so it gets covered by any messages and list boxes that appear, and it should have some width but does not require any height. The field does not need to have much height. In fact, you can change the font size for the field so that you can make it a very thin sliver, able to be squeezed in between other objects on the form. Q&A will expand it downward when needed. However, you should make the field the same width (or slightly narrower than) the dialog or message box that Windows will display. Position the field under the box's title bar. This way, when your programming places text into the field, the field will be visible only briefly until the box covers it. (See @DESIGN below for tips on setting the location and size.) The field should not be too narrow. If it is, when your programming puts text into the field, Q&A Windows may stretch the field vertically and cause the form to scroll. Scrolling is bad because it changes the coordinates of any special fields on that form, which in turns prevents DTFWIN from recognizing them any more. It also looks bad,. You should set the field's fill and line colors so that it is not normally visible on the form. That is, make them the same color as the background (white by default). There should also be on-field-exit programming to test the result returned by DTFWIN. More about this later. If a) you have @DESIGN in effect, b) the cursor is in a field that isn't a special field, and c) you press F12, you will be asked if you want to go to the DTFWIN field. If you reply "Yes", control will pass to that field (This is useful because the DTFWIN field is often hidden and difficult to find.) If you say "No", it will display the coordinates of the current field. You can use this as follows to design forms with the DTFWIN field. First, put the field on the form near the middle so it is likely to be hidden by any dialogs that appear. Then press F12. Note where the dialog appears, then reply "Yes" and see if the DTFWIN field would have been covered by that dialog. Edit the form as necessary. When you are pleased with the placement and appearance of the DTFWIN field, press F12 to go to the DTFWIN field, then press F12 again and say "No" to copy down the coordinates of the field. To repeat, any program mode command (described above) can be executed from the database programming by setting any field to "PGM:" followed by the command. For example, to put up a message box, you could set a field to "PGM:DO MSG label,button,icon,text of message". With this option, you do not need to have unique buttons and do not need to identify fields by coordinates. Example of use: You can use "PGM:DO SCRIPT scriptname" to popup a list box under program control. Here's an example. The programming sets KEY1 equal to two parameters and calls the script by: #10 = "PGM:DO SCRIPT USADUPSEARCH,KEY1=" + @LEFT(#30,3) + "," + @LEFT(#20,3); This runs the following script, which uses KEY1 to pass the two parameters to the GLB, and then uses KEY2 to stuff the result into the ID field in the retrieve spec (it could also reuse KEY1). USADUPSEARCH = GLB USANAMEX.QAX, SET KEY2,1,80 RETRIEVEALL RETRIEVE FIELD ID STUFF FIELD DTFWIN STUFF "CHECK PRIMARY" Topic 21: Script mode other uses (AUTOSTART etc) ------------------------------------------------ There are several ways that DTFWIN scripts can be used other than the standard way of making a menu choice. "AUTOSTART" script in [SCRIPTS] ------------------------------- If there is a script named "AUTOSTART" in the [SCRIPTS] section, it will be executed as soon as DTFWIN is started. This script could open one or more databases without requiring any action by the user. Here is an example of a [SCRIPT] section with an AUTOSTART script. Notice that the format of this section is exactly the same as [MENU:MAIN] section. The only difference is that the name on the left is a DTFWIN script name, not a menu choice. [SCRIPTS] AUTOSTART = OPEN Client Auto_Retrieve_Script in [DATABASES] ----------------------------------- See the topic "INI file [DATABASES] section -- Database definitions". "F12:SCRIPT dtfwinscriptname" on button next to a field. -------------------------------------------------------- Just put "F12:SCRIPT" and the script name on a button next to a field and either click on the button or press F12 in the field and the script will be invoked. "F12" on button, "SCRIPT dtfwinscriptname" in [SPECIAL FIELDS] ----------------------------------------------------------------- Put "F12" on a button and make an entry for the field it goes to in the [SPECIAL FIELDS] section of the INI file and either click on the button or press F12 in the field and the script will be invoked. The entry in the INI file must specify the form, field coordinates, and the "DO SCRIPT dtfwinscriptname" assigned to DTFWIN field ----------------------------------------------------- To run a script from a field, you can set a field to DO SCRIPT followed by the name of a DTFWIN script you have defined in the INI file and that script will be run. You can also set one or more of the 20 key values at the same time the script is called. This is a way of passing variable information to the script. Values are comma delimited. To include a comma in a value, enclose the value in quotation marks. Quotation marks within quoted values are not supported. Eg PGM:DO SCRIPT COPY FORM LETTER,KEY12=123456,KEY13=ABC.DOC Eg PGM:DO SCRIPT COPY FORM LETTER,KEY01="VCR,2 HEAD MONO," Returns DID SCRIPT dtfwinscriptname or DID SCRIPT dtfwinscriptname=ERR. Even when key values are set, does not return DID SET KEYnn. Topic 22: Field mode other uses ([SPECIAL FIELDS], FLD:command) --------------------------------------------------------------- [SPECIAL FIELDS] ---------------- The normal way to invoke a field mode command when clicking a button is to put the button next to the field and put the command on the button itself, as explained above. However, you can also define a field using the [SPECIAL FIELDS] section of the INI file and specify the command there. In this case, the button should only have "F12" on it, not the colon and not the command. One advantage of this technique is that the button does not need to be located next to the field. Another advantage is that it is easier to have a button appear to be blank if it only has "F12" on it and not the command itself. Disadvantages are that you have to 1) determine the coordinates for the field and 2) maintain the coordinates if you redesign the form. Another disadvantage is that the coordinates change if the form is scrolled, so scrolling is strictly forbidden. FLD:command ----------- Any field mode command (described above) can be executed from the database programming by setting a field to "FLD:" followed by the command. For example, to do a generic list box, you could set a field to "FLD:GLB Client.QAX", then go to that field. Of course, many field mode commands already have equivalent program mode commands, so this use would not be helpful in those cases. Topic 23: CUSTOM programming and buttons ---------------------------------------- There are several ways that the DTFWIN application can be customized. With the exception of the default action for a qawin custom button (item 4 below), all require C++ custom programming of the DTFWIN program. 1) Program mode Set DTFWIN = "DO CUSTOM " followed by optional parameters. 2) Script mode CUSTOM followed by optional parameters. 3) GLB custom processing Put "glbcustom=nn" in the QAX file. When the OK button is clicked, DTFWIN will call a custom routine in the EXE file to manipulate the contents of the list box. Exactly what it does depends on the application, which can detect the value nn to implement different actions for different list boxes. There is no default. 4) QAWIN custom button Put "button=xxx" in the [DTFWIN] section of the INI file, where xxx matches the text on a button on the qawin form. Custom programming can handle the button click. If not, the default action is to stuff BUTTON formname,buttonname into the current field (the assumption being that the button executed a qawin script that passed control to the DTFWIN field). Topic 24: Script commands - alphabetical listing ------------------------------------------------- These are the commands you may use in the scripts. There are about 50 commands. End of line comments in scripts may be indicated with "//". ABOUT ----- Displays About information. John can customize this for your needs. ALLOW ----- Specifies which Q&A Windows commands the user is permitted to access. By default, all commands are allowed because the Q&A Windows menu is hidden. For some strange reason, you must allow EDIT to be able to use the RETRIEVE script command. See topic "List of Q&A menu choices for ALLOW and DENY commands". APPEND file TO file ------------------- Appends one file to another. Example: APPEND C:\WINDOWS\TEMP\RPT.TXT TO C:\WINDOWS\TEMP\RPTS.TXT (This is shown on two lines to accommodate an 80 column display of this file. In the INI file the statement must be on one line.) BEEP ---- Makes a "ding" sound. BREAK ----- Exit from a loop. See Section 24 for an example. CHECK@NUMBER ------------ Checks @NUMBER to make sure that its value matches the highest value in the field where it's used. Here's how it would be used in an AUTOSTART script on the Customer database. XLOOKUP Customer Customer.MAX CHECK@NUMBER Customer The CUSTOMER.MAX file contains this: SELECT=RECORDNO = MAX FORMAT=RECORD 6 RECORDNO The XLOOKUP finds the record with the maximum value for RECORDNO and leaves the resulting 6 characters in temporary clipboard, which is accessed by CHECK@NUMBER. CLOSE database -------------- Closes the databases and hides but does not close the Q&A Windows CONTINUE -------- Return to the top of a loop, skipping any statements that come between this statement and the next ENDREPEAT statement. This might be used in conjunction with IFWINDOW: for example, IFWINDOW "abc" CONTINUE means that as long as the "abc" window is visible, keep going back to the top of the loop. COPY file TO file ----------------- Copies a text file. If the target file exists, it is replaced. The COPY command has the ability to generate a file name based on the date, with a tie breaker terminal letter. Example: COPY C:\TEMP\REPORT.TXT TO C:\HISTORY\.TXT would create a file with a name like 000802A.TXT (or 000802B.TXT if the A file already existed). The two file names may use global variables. See section 38 for a list. COPYBIN file TO file -------------------- Copies a binary file. If the target file exists, it is replaced. Here's an example that copies an empty database (a template) named T-DETAIL to R-DETAIL (so it can be loaded by the script to do a fancy report). COPYBIN T-DETAIL.DTF TO R-DETAIL.DTF COPYBIN T-DETAIL.IDX TO R-DETAIL.IDX The two file names may use global variables. See section 38 for a list. CUSTOM optional parameters -------------------------- Example: CUSTOM OVERVIEW DELETE filename --------------- Deletes the named file. Example: DELETE REPORT.TXT DELETERECORD ------------ Deletes the current record from the current database. DENY ---- See ALLOW. DIALOGCHECK ----------- DTFWIN keeps a lookout for Q&A dialogs to prevent lockup situations (for example, DTFWIN will not try to exit if a Q&A Windows needs an answer to some dialog). This command, DIALOGCHECK OFF, allows an override of the automatic process. You may need to do this in a DTFWIN script to determine what is happening -- example when running a report that finds no records, your script should detect the dialog so it can act accordingly. This option is automatically turned on at the beginning of each script, so each script that needs it to be off must turn it off explicitly. You can turn it on again if desired. DTFDATA ------- The DTFDATA routine can be called from a script. You can pass one of the key values as a parameter. Here is the syntax: DTFDATA database qaxfile outputfile [parameters] Example: DTFDATA PI LISTPI.QAX LISTALL.TMP The qax file is always in the dtfwin directory and the file name must include the extension. Global variables can be used to specify the name (eg .QAX is permitted) but not to change the directory (eg \ABC.QAX is not permitted). The output file is always written to . There is no need to pass user id and password to DTFDATA. The optional parameter list may use global variables. See section 38 for a list. See GLB below for a discussion of differences between DTFDATA and GLB parameter passing. There is a special use of this command to create qax files. DTFDATA /MAKEQAX database qaxfile example DTFDATA /MAKEQAX CONTRACT VIEWFEES.QAX This will use the DTFWIN.TAX file to create a QAX file for the database. See the documentation for DTFDATA for details. DTFWIN will create the qax file and then immediately terminate. ENDREPEAT --------- End of a loop. Cannot be nested. See Section 24Y for an example. EXIT ---- Exists from DTFWIN. Shuts down all Q&A Windows. FIELD "field name" ------------------ Positions at the named field. Use quotes if there is a blank in the field name. Global variables such as can be used, as FIELD FIRSTFIELD ---------- Goes to the first field on the current form. FIRSTRECORD ----------- Goes to the first record (depending on the retrieve spec). FORM "form name" ---------------- Positions at the named form. Use quotes if there is a blank in the form name. Global variables such as can be used, as FORM GLB filename,parameters ----------------------- If there is an error or the user presses ESC, the script is aborted. If the user makes a selection, the "result clipboard" is set to the column extracted based on GLBHDR= (or based on glbextractpos and glbextractlen). The GLB command and the DTFDATA command (qv) have something in common. They both use the built-in DTFDATA program. Usually a GLB gets parameters for the SELECT statement by prompting the user. However, in some cases, parameters are passed to the GLB as they are to DTFDATA. When parameters are passed, there are two differences. 1) For a GLB, the parameter list may not (and in fact need not) be enclosed in quotation marks. However, because DTFDATA has multiple parameters on its "command line", if there are any blank spaces in the parameter list, it must be enclosed in quotes. 2) Also, GLB parameters are preceded by a comma, whereas DTFDATA parameters are preceded by a blank. Examples (those with an X would cause erroneous results): GLB somefile.QAX,,PIZZA X GLB somefile.QAX,",PIZZA" DTFDATA database somefile.QAX output.TMP DTFDATA database somefile.QAX output.TMP "," X DTFDATA database somefile.QAX output.TMP NEW YORK, DTFDATA database somefile.QAX output.TMP "NEW YORK," GOTO label ---------- GOTO (with label). A label, preceded by a colon (:), may appear at the beginning of a statement or on a line by itself. Labels may be "outdented" for readability; just make sure they are indented at least 10 spaces, otherwise they will appear to be a new menu choice. Labels can consist of any reasonable characters except spaces. The statement with the label must appear in the same script. The label name is not case sensitive. Example: &Menu choice = IFWINDOW "Q&A" GOTO MYLABEL (statements here) QUIT :MYLABEL // Indent at least 10 chars STUFF "HELLO" IFANYOPEN (Pseudocommand) -------------------------- If no databases are open, then this menu choice is greyed out. Must be the first statement in the script. See also IFOPEN. IFCLOSED database (Pseudocommand) ---------------------------------- Greys out the menu item if the named database is open. Use for an open menu choice. Must be the first item of the script. IFDBEXISTS database (Pseudocommand) ------------------------------------ Similar to IFOPEN, greys out menu choice if the database doesn't exist. Must be the first item of the script. (Formerly IFEXISTS.) IFFILE "filenameandpath" command -------------------------------- Tests for the presense of a file with the specified path and name. The test is not case sensitive. If the file exists, the specified command is executed. If the file does not exist, the next command is executed instead. Example: IFFILE "ZOLD\Client.IDX" GOTO ABORT IFFILEEXISTS "filepathandname" (Pseudocommand) ----------------------------------------------- Similar to IFOPEN, greys out menu choice if the file doesn't exist. Must be the first item of the script. IFNOFILE "filenameandpath" command ---------------------------------- Tests for the absense of a file with the specified path and name. The test is not case sensitive. If the file does not exist, the specified command is executed. If the file does exist, the next command is executed instead. Example: IFNOFILE "ZOLD\Client.IDX" GOTO ABORT IFOPEN database (Pseudocommand) -------------------------------- Greys out the menu item if the named database is not open. Use for a Windows menu or for a Close menu choice. Must be the first statement in the script. See also IFANYOPEN. IFWINDOW "text" command ----------------------- Tests for a window with the specified text in the title bar. The test is not case sensitive. If the window exists, the specified command is executed. If the window does not exist, the next command is executed instead. See Section 24 for an example. LASTRECORD ---------- Goes to the LAST record (depending on the retrieve spec). MAKEDIR "directory" ------------------- Creates the specified directory. MASSUPDATES ----------- Brings up Mass update menu. The Q&A menu does not need to be visible for this command to work. MENU ---- States that this item is a menu or submenu. MERGEMAIL filename or MERGEMAIL filename SHOWLOG -------------------------- Sends e-mails to multiple recipients. See also the program mode command DO SENDMAIL. Specify the optional SHOWLOG parameter if you want detailed feedback as each e-mail is sent. Without the parameter, you will only receive feedback if an error is detected when sending a message. If there were no problems, after all messages have been sent, you will see a message to that effect. Sample message (From, To, and Subject must be in this order): From:president@whitehouse.gov To:president@whitehouse.gov Subject:Testing MERGEMAIL option We find it necessary on this occasion to blah blah blah. To send attachments, create a subdirectory MMATTACH under the DTFWINDIR directory and place any files to be attached in it. You can attach multiple files. They can be word documents, images, html files, txt files, whatever you wish. Allows sending e-mail to multiple addresses using either the TEXTWRITER command or a Q&A Windows Freeform Report. You can send customized messages to multiple recipients at once, automatically, just by making a single menu selection. The TEXTWRITER command was developed because freeform reports can be finicky when sending output to a text file. Whether you use a Freeform report or TEXTWRITER, begin by putting information such as the from and to e-mail addresses at the top of each page of a report, along with the subject. To send the e-mail messages, you define a menu choice to run that report and send the output to a file. The DTFWIN command MERGEMAIL then reads that file. For each page of the report, it extracts the addresses and subject lines and e-mails the remainder of the report page as the message going to that particular address. Here are the details for setting it up. The first 3 steps and steps 8 - 10 are only relevant if you are using a Freeform report. If using TEXTWRITER, you only need steps 4 - 7 and 10 - 11. Steps 1 - 3 and 8 - 9 are for setting up a generic text only printer and other chores needed to send a freeform report to a file. It is simpler and more reliable to just use the TEXTWRITER command in DTFWIN. 1) If you haven't done so already, add a new printer, selecting "Generic / Text Only". This will allow you to send the report to a file without any font or formatting information, which is appropriate for an e-mail message. 2) While in "Design Reports/Labels", select File -> Print, then click on "Setup" and select "Generic / Text Only on FILE:" as a Specific Printer. This will indicate that the output from this report is to go to a file. 3) Select File -> Page Setup, click on "Source" and choose "Continuous - Page Break". This will put a Form Feed between each "page" of the report (that is, between each message to be e-mailed). 4) In defining the report, put "From:" followed by your e-mail address at the top of each page. If using a freeform report, this can be done in a text box if it doesn't change from message to message. If using TEXTWRITER, it can be typed into the TW file. 5) Put "To:" followed by the destination e-mail address on the next line. (Any blank lines will be ignored.) 6) Put "Subject:" followed by the e-mail subject on the next nonblank line. 7) The remaining lines are the message to be sent. Blank lines from this point on are included in the message. You can run the report and select preview, but you should also run the report manually and send the output to a file, then look at that file using a program like Notepad to make sure it is formatted correctly for e-mail purposes. Be warned, there can be a discrepancy between what it looks like when previewed and the resulting file actually written to disk. 8) Use Assistant -> Scripting Assistant to create a Q&A Windows script to "Print the Freeform Report" you've defined. 9) Use Assistant -> Manage Assistant Menu to add this script to the assistant menu. Let's say it's script 1. You'll see that same number below, following "QASCRIPT". 10) Add a menu choice "Send e-mails" in the DTFWIN INI file. Do something like this to use TEXTWRITER. In this example, records will be selected from the PEOPLE database using the first letter of the last name as well as the year in a registration field (details as to which records are retrieved as well as the fields and how they are formatted into the message are specified in the EMAILDAT.QAX and EMAIL.TW files, not shown). &Send e-mail by name, year = PROMPT "Select by name" "First letter of last name" 150 1 SET KEY1,1,1 PROMPT "Select by year" "2 digit year" 150 2 SET KEY2,1,2 DTFDATA PEOPLE EMAILDAT.QAX EMAILDAT.TMP , TEXTWRITER EMAILDAT.QAX EMAILMSG.TW EMAILDAT.TMP EMAILDAT.TXT MERGEMAIL EMAILDAT.TXT MSG "O,I,The e-mails have all been sent." Do something like this to use a freeform report. Send e-mails = OPEN Client DELETE "C:\WINDOWS\TEMP\MERGEMAIL.RPT" DIALOGCHECK OFF QASCRIPT 1 REPEAT IFWINDOW "Q&A" QUIT IFWINDOW "PRINT TO FILE" BREAK ENDREPEAT STUFF "C:\WINDOWS\TEMP\MERGEMAIL.RPT" MERGEMAIL C:\WINDOWS\TEMP\MERGEMAIL.RPT 11) Connect to the Internet, run DTFWIN, select the menu choice, and watch the e-mails go out. As each message is prepared and sent, a DOS session will open temporarily. If you specify SHOWLOG on the MERGEMAIL line, you will see a brief log for each e-mail message that is sent and will have the option to say it was sent successfully or not. If you say it wasn't, then the process stops immediately. See the SENDMAIL program mode command for comments on the BLAT program, which is used to send the mail messages. MSG --- Displays a message box. Similar to DO MSG used in the DTFWIN special field, but it doesn't return a value and has no label. The syntax is: MSG "button,icon,text of message". NAVIGATION ---------- Generates the navigation popup, based on the [NAVIGATION] section in the INI file or in the NAVIGATION.INI file if it exists. NEXTRECORD ---------- Goes to the next record (depending on the retrieve spec). NEWRECORD --------- Puts Q&A Windows into add mode for the current database. Note: Q&A automatically enters the first field, which triggers any field entry programming for that field. Note: Q&A does something strange in the following circumstance. In this example, the Customer database has a default form "Main" and another form "Spouse". Script "4" on the Assistant menu does "Use form Spouse." OPEN Customer QASCRIPT 4 NEWRECORD In this example, there is programming that tests @layout. This programming is triggered on entry to the first field on the form, You would think that Q&A would change from the default form "Main" to the "Spouse" form before creating the new record and triggering the programming. However, when the programming tests @layout, "Main" is returned, not "Spouse". It seems that Q&A creates the new record before changing the form, even though the DTFWIN script clearly does those operations in the reverse order. The solution is to delete the NEWRECORD statement and to revise the Q&A SCRIPT that is invoked by QASCRIPT 4 to do the following: Use form Spouse. Add a new record. OPEN database ------------- Opens the named database. If the database is already open, focus is switched to it. OPEN database ------------------------ Opens the named database. Here's an example that goes directly to a specific order, given that a Client has been selected. Coming into this code, the clipboard KEY1 has been set with the Client id number. &Find order = IFOPEN Client GLB FINDORDR.QAX, SET KEY2,1,9 OPEN ORDER FORM MAIN RETRIEVE FIELD ClientID STUFF A FIELD ORDERNO STUFF A The database name may be passed in one of the KEY parameters. Eg OPEN PLEASEWAIT ---------- PLEASEWAIT "Title text" "Message text" PLEASEWAIT (with no parameters, cancels the existing message). PREVRECORD ---------- Goes to the previous record (depending on the retrieve spec). PROMPT "title" "text" boxwidth maxchars defaultvalue instructions ----------------------------------------------------------------- Puts up dialog to prompt for a value. The first parameter is the text to appear in the title bar of the dialog. The second parameter is the text to appear in the dialog to describe the field value the user is to enter. It's the actual prompt string. The third parameter is the width of the dialog box. If is "0", DTFWIN will compute it automatically. To set it manually, a reasonable starting value might be 200. (See also glbxsize, which is a similar parameter for glb dialogs.) The fourth parameter is the maximum number of characters the user should enter. If more are entered, they will be truncated. The fourth parameter also determines the width of the edit box the user types the data into. The default assumes that wide, upper case characters will be entered (such as "W"). This default often results in an excessively wide edit box. To make a narrower box, multiply maxchars by 100 and add a number between 4 and 8 to control the width. Narrow characters (such as digits) would be 5. Thus, to enter a 6 digit number, you could specify 605 ( 6 x 100 + 5). For a 10 character date field (mm/dd/yyyy or dd/mm/yyyy), which includes 2 "/" characters, you can specify 1004. Use 8 for capitalized letters to allow for "W" and "M". An optional fifth parameter is the default value. (Use "." if there is no default value but there is a sixth value.) Specify "@date" for today's date in the format yyyy/mm/dd. An optional sixth parameter is a one line of instructional text to appear below the prompt label and edit box. If this is used, there must also be a default value (use "." as a place holder). Do not use commas within the instruction text. In the example shown here, the user is asked to enter a date as year and month (example 2000/12). The next statement assigns this value to the DTFWIN clipboard KEY1. The last statement extracts data, using the passed date as parameter %1 in the QAX file (not shown). PROMPT "Top Down Report" "Report month. YYYY/MM" 150 704 SET KEY01,1,7 DTFDATA ORDERS TOPDOWN.QAX TOPDOWN.TXT QAMENU ON/OFF/command# ---------------------- To run a report or a Q&A Windows script and be able to stuff characters into the dialog that comes up (eg to modify the retrieve spec or the output filename etc), use QAMENU ON, STUFF "R" rather than using the DTFWIN script command REPORTS. For the same reason, to use the scripting assistant, use QAMENU ON, STUFF "S", QAMENU OFF for the scripting assistant (instead of SCRIPTS). Summary: use REPORTS and SCRIPTS to bring up the reports dialog and the scripting assistant dialog for the user to access them, but use QAMENU ON and STUFF if you want to access them in your DTFWIN script. The command # may be decimal or hexadecimal (eg 0x1234). Note: In French, to run reports use "L". QASCRIPT 1 (through SCRIPT 9) --------------------------- QASCRIPT 1 tells Q&A Windows to run the script numbered "1" on the "Assistant menu." (You can put up to 10 scripts on the menu using the "Manage Assistant Menu" option on the "Assistant" menu.) You can run scripts "1" through "9". If it is necessary to regain control after changing forms, use a script with the /WAIT option. Eg "PGM:DO SCRIPT /WAIT xxx", where the script is "QASCRIPT n". Then test for @INSTR(DTFWIN,"DID SCRIPT /WAIT xxx"). QASCRIPTS ------- Brings up the "DAVE the Scripting Assistant" menu, as if the menu choice Assistant -> Scripting Assistant had been made. (This is not "DAVE the Intelligent Assistant".) The Q&A menu does not need to be visible for this command to work. QAWRITE ------- Starts Q&A Write for Windows. DTFWIN will maintain the Q&A Write for Windows in front of itself and any databases unless the Q&A Write for Windows is moved to the side by the user or minimized by the user. QUIT ---- Causes the current script to stop executing. If there is a secondary script, it is executed at this point. RENAME oldname TO newname ------------------------- Renames a file. If a file with the new name already exists, it is an error. The two file names may use global variables. See section 38 for a list. REPEAT ------ Beginning of a loop. Cannot be nested. REPORT F/C/L "name" A/L ----------------------- Tells Q&A to run the specified report. The first parameter selects the type of report. F = FreeForm C = Columnar L = Label The "name" is the name of the report, case insensitive. The last parameter tells Q&A which retrieve to use. A = Attached L = Last run Do STUFF immediately after REPORT if you want the report to be automatically previewed. Following this command, the Q&A Menus have been turned on, as if the QAMENU ON command had been executed. Use QAMENU OFF to turn them off if desired. Here is an example of a report with a user specified retrieve spec. This script runs a (freeform) report that is named "ACCOUNT HISTORY" with the "Last Run" option selected for the retrieve spec. It also does an automatic preview. &Acct History for Client = PROMPT "Title" "Prompt" 150 6 SET KEY11,1,6 OPEN Payment QAMENU ON RETRIEVEALL RETRIEVE QASCRIPT 4 // Goto key field STUFF REPORT F "Account History" L STUFF QAMENU OFF REPORTS ------- As if 10/28/2003, when this is used qawin hangs after a report is selected and run. It is better to use QAMENU ON, STUFF R, QAMENU OFF. Tells Q&A to open its reports menu so the user can select and run a report. The Q&A menu does not need to be visible for this command to work. RETRIEVE -------- Puts Q&A Windows into the retrieve spec for the current database. RETRIEVE "text to be stuffed into the retrieve spec" ---------------------------------------------------- Same as above, but also stuffs the specified text into a field or fields. Use quotes if there is a blank in the retrieve spec. The text may include any of the following, and DTFWIN will substitute the proper values at run time. Clipboards 1 - 9 Today's date Today's date RETRIEVEALL ----------- RETRIEVEALL clears the retrieve spec, so a subsequent retrieve will find all data records. Note that if a script is to put values into certain fields to create a retrieve spec, it is good practice to do RETRIEVEALL first to clear any existing spec. REVERT ------ Causes the data values in the current record to revert. (You should probably put a SETFOCUS to the proper database first.) RUN --- The RUN command can be used in a script. Syntax is: RUN program optional parameters DTFWIN will maintain the program in front of itself and any databases unless the program is moved to the side by the user or minimized by the user. SET @NUMBER dbname,pos,len ------------------------- Sets @NUMBER in the named database to the value returned from XLOOKUP (qv). SET KEYnn,pos,len,delchars ------------------------- Sets the key to the result of an operation that leaves data in the "result clipboard." Examples include list boxes (glb) and prompts. The key can be 1 - 9. Specify the starting column and the number of columns to be extracted from the text returned by the glb. Be aware that the result clipboard after a list box does not contain the entire line in the list box that the user selected, only that column specified by GLBHDR= or by glbextractpos and glbextractlen. The last parameter (delchars) is optional. If present, it is a list of one or more characters (excluding blanks and commas) that should be deleted from the string. For example, if a templated value is returned by DTFDATA, this can be used to remove punctuation characters. Example SET KEY1,1,6,- will set key clipboard "1" to the first six characters after removing any hyphens (-). (If you want to take everything, specify something like 1,99.) If any columns in the QAX file are marked for invisible, remember to exclude them when determining pos and len. For example, if a date field is the first column and appears unformatted in the natural yyyy/mm/dd format for sorting but is marked invisible so another column can display the date with a format such as mm/dd/yy, the first 11 columns will not be present when the text is extracted. That is, the columns specified should match the list box as displayed, not the LISTBOX.TMP file in the temp directory. SET KEYnn=string ---------------- Sets the key to the string value specified. The string may contain global variables (see Topic 38). If the string contains embedded blanks, enclose KEYnn= and the string in quotes, as shown here: SET "KEY05=VCR,2 HEAD MONO,MINTO" SET TITLEBAR,text,pos1,len1,pos2,len2,pos3,len3,pos4,len4 --------------------------------------------------------- Sets the title bar from the result clipboard or one of the 20 keys. Specify pairs of starting column and field width. Examples: SET "TITLEBAR, Client #,22,15,38,10,1,20" SET "TITLEBAR, Client #,,22,15,38,10,1,20" The quotes are required because of the spaces in the parameters. The title bar text will consist of the application name, the text specified in this command, and the data extracted from the result clipboard. The maximum number of extraction pairs is 4. There is a limit to the amount of text that can be displayed in a title bar. If you have too long an application name and try to append too much text, it will be truncated. SETFOCUS database ----------------- Changes focus to the database. If the database is not open, the script is terminated. SETMODE PGMMODE or FIELDMODE or SCRIPTMODE ------------------------------------------ Change mode while in a script. This is used internally by the New button logic, which dynamically creates a script to open the lookup target database. However, it needs to remain in PGMMODE so that a value can be returned when the CLOSE button is clicked. SORT ---- Selects the sort spec. STUFF "text to be stuffed" -------------------------- Acts as though the user were typing the specified text. The most number of characters that can be stuffed at once is 127. Use quotes if there is a blank in the text. In addition to text characters, the following special characters can also be specified: through through 0 through 0 A through Z The following can be stuffed. The actual text stuffed depends on the value defined elsewhere. For example, will stuff the value you specify in the CFG file on the DATADIR= line. would stuff the value in the third key clipboard. Includes final \ Includes final \ ... Includes final \ ... Includes final \ USERAUTH must be set in the INI file. USERAUTH must be set in the INI file. TECHNICAL --------- Displays technical information, such as screen resolution, font size, which version of Windows was detected, and how many Q&A databases can be opened at once. It also will display the values of any keys (see SET KEY etc) and how much of certain resources have been used; useful information to let you know if your application is about to burst at the seams. Technical help displays all Q&A's if at least 1 has a closebutton message. TEXTWRITER ------------ Simple freeformat report writer. Can be used to send e-mail messages or to create a document to be faxed. Output is plain ascii text (no fonts etc) that can be e-mailed, faxed, or copied to a printer to overlay a preprinted form. Q&A's freeform report writer should work for these tasks, but it is tricky to use if the output is formatted for a generic text printer and sent to a disk file. Use TEXTWRITER with MERGEMAIL to send multiple e-mails or faxes at once. It can also be used directly under program control to send a single e-mail or fax. Here's an example of sending a fax from within a database. After the uses clicks on a button that triggers the programming to send a fax, the programming uses the "PGM:DO SET KEY" command to set KEY2 to a unique INV number (so the record whose data is to be faxed can be identified) and KEY3 is set to the fax telephone number. Then the script FAXINV is run. Here's the script: FAXINV = DTFDATA ORDERS INV.QAX INV.DAT TEXTWRITER INV.QAX INV.TW INV.DAT INV.FAX RUN FAXINV.BAT Notice that DTFDATA is used to extract the fields (that are to appear on the invoice) into the INV.DAT file, that TEXTWRITER formats the data in INV.DAT into INV.FAX (the document to be faxed), and FAXINV.BAT calls a command line program to send the document to the telephonenumber . The BAT file for sending faxes looks like this: @ECHO OFF REM FAXINV.BAT REM REM CALL WITH FAX NUMBER REM COPY QFAX.EXE C:\WINDOWS\TEMP COPY QFAX.CFG C:\WINDOWS\TEMP C: CD \WINDOWS\TEMP QFAX INV.FAX %1 QFAX is a shareware program that is easy to use and can send faxes from the command line, as seen here. To send e-mails, use the program mode command DO SENDMAIL or the script mode command MERGEMAIL - both use BLAT, a public domain program that is easy to use and can send e-mails from the command line. Here are details for using TEXTWRITER. TEXTWRITER qaxfile TWfile input output qaxfile is in dtfwindir TWfile is in dtfwindir input is in tempdir output is in tempdir Here is part of a TW file showing how you place fields in the output. The fields are identified as 1, 2, A, B, and C. Notice the "X and "SIGNATURE ON FILE", which are text that should appear on the file just as shown. (If this output is supposed to overlay a preprinted form, the "X" might be designed to fit inside a box on the form.) <1,F > <2,F > X SIGNATURE ON FILE The data to be loaded into these fields is extracted from the database using the built in DTFDATA function. DTFDATA of course requires a QAX file so it knows which fields to extract, in what format, etc. You must include this line in the QAX file: FORMAT=NAMES The QAX file also identifies the fields for TEXTWRITER using the syntax shown in this example: FIRSTNAME //TEXTWRITER B LASTNAME //TEXTWRITER C2 The "B" and "C" correspond to the fields defined in the TWfile. You can use one or two characters to identify fields. The ",F" means that the field is "fixed width" on the output. The ",R" means that the field is "right justified" and "fixed width" on the output. If you do not specify ",F" or ",R", then fields squish together without maintaining the columns. Use ",S" to indicate that an output line should be omitted if all the fields on that line are blank. The fixed width, right justify, and suppress blank line options are mutually exclusive. TLB filename ------------ A TLB can be displayed from a script. Syntax: TLB filename Examples: TLB LISTA.TXT TLB C:\WINDOWS\TEMP\TLB.TMP TLB TLB.TMP See Topic 29 for a full description of TLB's. TRACE ON/OFF ------------ Turns tracing on or off. (Tracing can also be turned on upon start up with the @TRACE command line option.) Tracing is a debugging tool especially helpful when you're writing scripts. WAIT n ------ Causes a wait of approximately n/10 seconds. XLOOKUP dbname qaxfilename [comma_delimited_parameter(s)] --------------------------------------------------------- Uses a QAX file to obtain data, but unlike a GLB, does not display the data in a list box. Data obtained may be accessed using SET KEY or SET @NUMBER. The result of the XLOOKUP operation is written to the file XLOOKUP.TMP Topic 25: Field mode: Alphabetical list of actions -------------------------------------------------- Note that some of these actions (such as GLB, TLB, RUN) can be triggered by an F12 button next to the field, others require that the field be identified using coordinates. Dialog with buttons ------------------- Creates a dialog with buttons. These buttons each cause different text to be stuffed. In field mode, the buttons launch secondary GLB's or TLB's. In program mode, returns DID DLG dlgfile=result See Topic 30 for a detailed explanation. Also note that in program mode there is a DO PGMDLG command, which is different but somewhat similar. Generic list box ---------------- INI file example: GLB Client.QAX Button example: F12:GLB Client.QAX, Put GLB followed by a file name in the column. The file you specify contains information defining the list box as well as how to extract data from a database to load it. See below for details for this file. XLOOKUP --------------- INI file example: XLOOKUP GETNUM.QAX Button example: F12:XLOOKUP GETNUM.QAX Put XLOOKUP followed by a file name in the column. The file you specify contains information defining how to extract data from a database. The first record extracted is loaded into the field. See below for details for this file. Text list box ------------- INI file example: TLB SIZES.TXT Button example: F12:TLB SIZES.TXT Put TLB followed by a file name in the column. The file you specify contains information defining the list box as well as the data to be loaded into it. See Topic 29 for a full description of TLB's. Launch an app ------------- INI file example: RUN EDIT.EXE ABC.TXT %1 XYZ.TXT Button example: F12:RUN EDIT.EXE ABC.TXT %1 XYZ.TXT Put RUN followed by a program name in the column. The program should be in the path. You can pass parameters to the program, including the contents of the current field (as %1). Other than running the application, DTFWIN takes no special action. Note: to run a DOS program, specify the PIF. (This is true for Win 95/98 as well as Win 3.x.) This will cause a new DOS session to be created just to run the program. CALCULATOR ---------- INI file example: CALCULATOR Button example: F12:CALCULATOR Runs the Windows program "CALC.EXE" and returns a calculated value to the field when the user presses F12 in the calculator. DTFWIN will maintain the calculator in front of itself and any databases unless the calculator is moved to the side by the user or minimized by the user. DTFWIN ------ See the description of program mode. MANDATORY --------- INI file example: MANDATORY To be used to provide tight control over data quality control, since Q&A will not allow exit from a record if a mandatory field is blank. This field should not be used as an actual data field and the user should never enter the field. Because the field is MANDATORY, whenever the cursor enters a blank MANDATORY field (e.g. by back tabbing or by using the mouse or if Q&A puts it there because the user is attempting to leave the record while the field is still blank), DTFWIN will enter "EMPTY" and press the Enter key to trigger database programming to allow the program to take control from the user. DTFWIN will not stuff EMPTY into a MANDATORY field if in the retrieve spec. The AUTOENTER option that is set in the [DTFWIN] section of the INI file should be set Y if you have any mandatory fields. This will tell DTFWIN to press Enter to clear any warning message that pops up if the mandatory field is left blank. Run a DTFWIN script ------------------- INI file example: SCRIPT dtfwinscriptname Button example: F12:SCRIPT dtfwinscriptname Customized fields ----------------- INI file example: custom text The exact action taken for a special field is programmed into DTFWIN. Which action it takes is determined by the name of the special field. Topic 26: Program mode - Alphabetical list of commands ------------------------------------- Normally, after DTFWIN reads the DO command from the DTFWIN field, it clears the command and replaces it with "Doing". This way, the Q&A programming can test to see if DTFWIN is not blank and not permit the cursor to leave the field until the command has finished and returned any resulting string value. The field exit programming in DTFWIN can have this test: IF DTFWIN <> "" THEN GOTO DTFWIN. Programming in other fields with a GOTO should do this: IF DTFWIN = "" THEN GOTO xyz; This will lock the cursor in the field until DTFWIN can complete whatever it's doing. CLEAR option ------------ If a command does not return a value or if focus is to be switched away to another database, use "CLEAR DO" to clear the field and not stuff "Doing". Example: PGM:CLEAR DO SCRIPT /NOACK scriptname parameters DO BEEP ------- Makes a "ding" sound. Returns DID BEEP. DO CLOSEBUTTON: Specify script to run user clicks CLOSE ------------------------------------------------------- This option would typically be done on entry to a record. See also the DO GV command, which has a CLOSEBUTTON option with the same features. 1) Disable close button and display the message if the user tries to close by clicking the close button. DO CLOSEBUTTON label message 2) Run a script (which could close the database and change focus to another database). DO CLOSEBUTTON label RUN SCRIPT /NOACK scriptname,,... 3) Reset close button to normal (DTFWIN automatically closes). DO CLOSEBUTTON label Result returned: DID CLOSEBUTTON label [message] Use RUN SCRIPT /NOACK scriptname so that DTFWIN doesn't try to stuff an acknowledgement if there's no record open (eg right after deleting a record). DO COPYBIN: Copy text or binary file ------------------------------------ AS OF 5/29/2002 3:36PM, THIS FEATURE HAS NOT BEEN FULLY IMPLEMENTED OR TESTED General form: DO COPYBIN source TO destination Copies a binary file. If the target file exists, it is replaced. Here's an example that copies an empty database (a template) named T-DETAIL to R-DETAIL (so it can be loaded by the script to do a fancy report). DO COPYBIN T-DETAIL.DTF TO R-DETAIL.DTF DO COPYBIN T-DETAIL.IDX TO R-DETAIL.IDX If the destination path contains a subdirectory that does not exist, it is created. The two file names may use global variables. See section 38 for a list. Returns DID COPYBIN source TO destination=OK or ERR DO CUSTOM optional parameters ----------------------------- Example: PGM:DO CUSTOM SCHEDULE,blah,blah,blah,blah..... The text passed can be an entire field (32K). Returns DID CUSTOM parameters=result DO DLG dlgfile -------------- Creates a dialog with buttons. These buttons each cause different text to be stuffed. In field mode, the buttons launch secondary GLB's or TLB's. Returns DID DLG dlgfile=result See Topic 30. Note that there is also a DO PGMDLG command, which is different but somewhat similar. DO DTFDATA: Extracting from and posting to Q&A databases -------------------------------------------------------- General form: DO DTFDATA database qaxfile outputfile "parms" The internal DTFDATA program is run. See the DTFDATA documentation for details of its parameters and files. If there is an error, DID DTFDATA database qaxfile outputfile parms=ERR is placed into the DTFWIN field. If there is not an error, DID DTFDATA database qaxfile outputfile parms=1st record is returned to the DTFWIN field (truncated to 80 characters max). You can pass one or more of the key values as parameters. Example: DO DTFDATA PI LISTPI.QAX LISTALL.TMP "," The output file is always written to . There is no need to pass user id and password to DTFDATA. See DO GLB below for a discussion of differences between DO DTFDATA and DO GLB parameter passing. Note: DTFDATA when posting checks to see if the record is locked. The quotation marks around the parameters are optional, unless there are embedded blanks. DO FIRSTFIELD ------------- Goes to the first field on the current form. DO GET KEY: Gets the value of one of the special key "clipboards" ----------------------------------------------------------------- General form: DO GET KEYnn Gets the value of one of twenty "clipboards". The resulting value is placed into the current field and enter is pressed to trigger field exit programming. The value is preceded by "KEYnn=". "nn" must be 1 - 20. Example: DO GET KEY2 KEY2=SMITH (DTFWIN simulates pressing ENTER) DO GET KEY2/CLEAR KEY2=SMITH (DTFWIN simulates pressing ENTER, and KEY2 in DTFWIN is cleared) DO GET TITLEBAR: Gets the value of the titlebar ----------------------------------------------- General form: DO GET TITLEBAR Gets the value of the titlebar, as set by the DO TITLEBAR program mode command or the SET TITLEBAR script mode command. The resulting value is placed into the current field and enter is pressed to trigger field exit programming. The value is preceded by "TITLEBAR=". Example: DO GET TITLEBAR TITLEBAR=SMITH (enter pressed) DO GLB: Generic list boxes -------------------------- A list box appears from which the user can make a selection. Unlike a TLB (which gets the contents from a file) or a US (which supplies the contents from the database programming), the contents of a GLB are obtained from a Q&A database using the internal DTFDATA program. Upon opening, the cursor is positioned at the first item (except in the case of persistent list boxes). General form: DO GLB file.qax,parameterlist A QAX file used with the DTFWIN field is the same as a QAX file used