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 by the GLB script command and used when a special field in the INI file specified GLB filename.QAX. Although the QAX file is the same, when used in the DTFWIN field a parameter list may be supplied by the database programming. (For example, in a Client database, all invoice records for that Client can be displayed by passing the Client number.) The parameter list may use global variables. See section 38 for a list. If present, the following two options in the GLB file must be set properly: 1) glbrestrictmaxlen must be set to the length of the parameter list, and 2) glbdialog must be set N (because the default is Y) If there is an error, DID GLB file.qax=ERR is returned. If the user selects Cancel, DID GLB file.qax=ESC is returned. Otherwise, DID GLB file.qax=value is returned (that is, the designated value from line the user selects is returned). 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): DO GLB somefile.QAX,,PIZZA X DO GLB somefile.QAX,",PIZZA" DO DTFDATA database somefile.QAX output.TMP DO DTFDATA database somefile.QAX output.TMP "," X DO DTFDATA database somefile.QAX output.TMP NEW YORK, DO DTFDATA database somefile.QAX output.TMP "NEW YORK," DO GV: Global Variables ----------------------- This single command can set multiple keys and retrieves all key values. It can also set and get the title text and can set closebutton messages. Because it does multiple actions at once, it cuts down on the amount of handshaking required using the DTFWIN field, speeding up the application and reducing the undesired "flickering'. This command is very handy when multiple databases communicate via the key fields. One call can set multiple values and retrieve all of them, which simplifies programming and makes everything faster (with less flashing as well). DO GV label, GET KEYnn, If GET before SET, orig val returned. GET TITLE, SET KEYnn=ssssss, SET KEYnn+=ssssss, += appends the value. SET TITLE=sssss, CLOSEBUTTON=message (MUST BE LAST) CLOSEBUTTON=RUN script scriptname,,... (MUST BE LAST) DID GV label=KEYnn=sssss,KEYnn=ssss, Returns any key specified by GET KEY, returns title if GET TITLE specified, and also returns all key values not specified by GET KEY. If GET KEY is specified before SET KEY for the same key, the value returned is the value before being set. Because of this, it is possible to get the original value and then set it to a new value in one operation. If GET KEY is not explicitly specified, the value of the KEY will be returned, but it will be the value set by SET KEY. If GET KEYnn is specified, KEYnn= is returned even if the value is blank, whereas when returning all fields as the default, a key that is blank is omitted. To display a message rather than allowing the CLOSE button to close the record, specify something like this: DO GV XXX,CLOSEBUTTON=You must enter the customer's last name. To cause a script to be run when the button is clicked (perhaps to switch focus to another database), do something like this: DO GV XXX,CLOSEBUTTON=RUN SCRIPT /NOACK CLOSEUP CUSTOMER,KEYxx=xxxxxx Because the RUN SCRIPT can have comma separated parameters, if CLOSEBUTTON=RUN SCRIPT is used, it must be the last GV parameter. DO KEY: Set one of the special key "clipboards" ----------------------------------------------- See DO SET KEY. DO MSG: Windows message boxes ----------------------------- General form: DO MSG label,button,icon,text of message DTFWIN will display standard Windows dialog boxes under Q&A program control. These can be used to ask questions (answerable by clickon on an OK or Cancel button, etc), to provide information, to warn the user of problems, and to alert the user to errors. When button the user clicks on is returned to the program. Commas are used to separate the parameters, but they may also be used within the message itself. These are the values you can assign to the DTFWIN field before doing "goto DTWIN" to generate a message box. The is the general form of the text to be entered into the DTFWIN field... DO MSG label,button,icon,text of message Here's an example of actual code you might use... IF Impeach_the_President = "T" THEN { DTFWIN = "DO MSG IMPEACH,YN,Q,Do you really want to?"; Goto DTFWIN; } This will display a dialog with "Yes" and "No" buttons, an icon with a question mark "?", with "QUESTION" in the title bar, and with the text "Do you really want to do that?". The user can exit from the dialog box by selecting Yes or No. If Yes, the following will be placed in the DTFWIN field: DID MSG IMPEACH=Y If No, the following will be placed in the DTFWIN field: DID MSG IMPEACH=N On-field-exit programming in the DTFWIN field can detect "DID MSG IMPEACH" and do a goto to the proper field to resume your program logic. At that point, you can test for Y or N to see what the user wants to do. The choices for buttons on the dialog are as follows (these are standard Windows dialog boxes): Option Buttons in dialog Values that may be returned ------ --------------------- --------------------------- O OK O YN YES,NO Y,N OC OK,CANCEL O,K YNC YES,NO,CANCEL Y,N,C RC RETRY,CANCEL R,C ARI ABORT,RETRY,IGNORE A,R,I The "O" option is the default and may be omitted. The choices for icons on the dialog and for the text in the title bar are as follows (these are standard Windows dialog boxes): Option Icon in dialog Text in caption line ------ ----------------------- -------------------- none No icon No text I Lower case "i" INFORMATION E Exclamation mark "!" WARNING S Stop sign ERROR Q Question mark "?" QUESTION DO PGMDLG: Puts up dialog with buttons -------------------------------------- DO PGMDLG label/title:title text/xsize:nn/ysize:nn, Button1:text; Button2:text; ... Button9:text; Example: DTFWIN = "PGM:DO PGMDLG ChangeChoice" + "/title:Changes to the Arrangement/xsize:210/ysize:150," + "Button1:Per (currently " + ArrangePer + ");" + "Button2:Fixed/Variable Payments (currently " + FixedOrVariablePmts + ");" + "Button3:Payment Date (currently " + @right(@str(ArrangeNextPmtdate),2) + @mid(@str(ArrangeNextPmtdate) ,5,4) + @left(@str(ArrangeNextPmtdate) ,4) + ")"; Returns ESC or BUTTON1, BUTTON2, or BUTTON3. Default title: SELECTION Default xsize: 100 Default ysize: 75 Rule of thumb for ysize: 35 * 15 for each button. See also Topic 30, which describes a different but somewhat similar command. DO PROMPT: Puts up dialog to prompt for a value ----------------------------------------------- DO PROMPT pgmlabel,titletext,labeltext,boxwidth,maxchars, [defaultval],[instructions] Puts up dialog to prompt for a value. The first parameter (pgmlabel) is the label used to identify the result returned. Eg test DTFWIN for DID PROMPT pgmlabel. The second parameter (titletext) is the text to appear in the title bar of the dialog. The third parameter (labeltext) 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 fourth parameter (boxwidth) 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 fifth parameter (maxchars) is the maximum number of characters the user should enter. If more are entered, they will be truncated. This 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 4. Thus, to enter a 6 digit number, you could specify 604 ( 6 x 100 + 4). An optional sixth parameter (defaultval) 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 seventh parameter (instructions) 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. Example: DTFWIN = "PGM:DO PROMPT GETADDR,Address,Enter the address:,150,50," + Address + ",Enter street number name city state and zip." DID PROMPT label=result DID PROMPT label=ESC The dialog can have a line of text included as instructions. Thus, when asking the user to enter a value, in addition to the label next to the edit box, there can be a line of instructions below the label and the edit box. The line of instructions follows a comma after the (optional) default value. (If there is no default value, you must supply the comma anyway.) Here is an example, wrapped for clarity; it lets DTFWIN compute the box width and it specifies at most 10 characters to be entered, with a width parameter of "4": "PGM:DO PROMPT GETMODEL,Stock search by model,Enter partial model,0,1004,,Either enter a partial model number, or Cancel, enter a code, and try again."; DO 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". DO QASCRIPT does not return DID QASCRIPT because often a script is used to change to another form or field and the returned value would be stuffed into the wrong field. Hence it is advisable to use CLEAR (PGM:CLEAR DO QASCRIPT n) to avoid leaving "Doing" in the DTFWIN field. 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"). DO RUN: Running programs ------------------------ General form: DO RUN program parms The program is run and "DID program parms" or "DID program parms=ERR" is returned. DO RUNWAIT: Running programs with confirmation ---------------------------------------------- General form: DO RUNWAIT question,title,program parms The program is run and a message appears to ask whether the program terminated successfully. The titlebar for the question is "PLEASE WAIT, THEN INDICATE OUTCOME" and the text of the message is the first parameter. The second parameter, title, is the title bar for the program that is run. This is used by DTFWIN to force the program to the top, in front of DTFWIN, the databases, and any messages. Even the PLEASE WAIT message is hidden by the program. "DID program parms" or "DID program parms=ERR" is returned. Example: DTFWIN = "PGM:DO RUNWAIT Was the e-mail sent successfully?,EMAIL,EMAIL.BAT " + EMAILTO; The resulting value will be DID EMAIL.BAT ... =Y or DID EMAIL.BAT ... =ERR. DO SCRIPT: Running DTFWIN (not QAWIN) scripts --------------------------------------------- General form: DO SCRIPT dtfwinscriptname or DO SCRIPT dtfwinscriptname,KEYnn=string,KEYnn=string or DO SCRIPT /NOACK scriptname parameters or DO SCRIPT /WAIT scriptname parameters The DTFWIN (not QAWIN) script is 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. Eg PGM:DO SCRIPT COPY FORM LETTER,KEY12=123456,KEY13=ABC.DOC Normally returns DID SCRIPT dtfwinscriptname (before the script is run) or DID SCRIPT dtfwinscriptname=ERR. (Even when key values are set, does not return DID SET KEYnn.) "PGM:CLEAR DO SCRIPT /NOACK scriptname parameters" will not stuff "DID SCRIPT scriptname" into the DTFWIN field. Frequently used in conjunction with CLEAR, as shown. "PGM:DO SCRIPT /WAIT scriptname parameters" will stuff "DID SCRIPT scriptname" into the DTFWIN field but only after the script has run to completion. DO SENDMAIL ------- Send an e-mail to one or more recipients, with optional attachments. See also the script mode command MERGEMAIL. Set DTFWIN as the following example shows: PGM:DO SENDMAIL To:jtd@pgh.net,Mary Smith Joel Campbell CC:Mary Jane Burpee BCC:theboss@mycompany.com Subject:"The subject must be enclosed in quotes" Attach:FILES\JC932282.DOC Attach:XYZ.DOC Text:The text of the message begins here and can span many lines. Here is some simple programming. Notice the triple quotes to generate quotes around the subject in the final value assigned to DTFWIN. Also, the @replace guarantees that there are no quotes in the subject itself. The maximum length of subject is 55 characters. DTFWIN = "PGM:DO SENDMAIL To:" + ToAddress + " Subject:""" + @replace(Subject,"""","'") + """ Text:" + Message; GOTO DTFWIN; The To, CC, and BCC fields can have more than one recipient. The CC and BCC fields may be omitted completely. BCC may also be specified in the optional [SENDMAIL] section of the CFG file. Recipients are specified either with an e-mail address such as jtd@pgh.net or with a combination name and address, as John Dow. Multiple recipients can be separated by commas or with a hard return (both shown in the "To" field above). The "Attach" field may use the following if the file to be attached is not in the DTFWIN directory: , , , , , , , , , , , and of course . Each "Attach:" field can have multiple attachments, separated by commas or hard returns; each must have the full pathname. There can be multiple Attach fields. Files are attached as binary files (not text files) - this is appropriate for Word documents. The files are sent using a slighly modified version of the Public Domain blat.exe program, a 32-bit windows command line email program (similar to SENDMAIL in Unix). There should be three files in the DTFWIN directory: BLAT.EXE, BLAT.INI, and BLAT.PIF. The BLAT.INI file looks like this (the values shown are examples): SMTP=mailauth.myisp.net Sender=johnsmith@bigcorp.com u=userid@myisp.net pw=mypasswd SMTP is the SMTP server, Sender is a valid e-mail address. If the SMTP server requires authentication, supply the "u" and "pw" parameters. I have slightly modified the standard BLAT program. Be sure you use my version of it, not a version you can download from the Internet. DO SET CLOSE: Set value to be returned when CLOSE button is clicked ------------------------------------------------------------------- General form: DO SET CLOSE=string The DTFWIN field is set to DID SET CLOSE=string=ERR if there is a problem, otherwise =OK if no error. If a NEW button on a GLB was not clicked, this will return ERR but display no message. See Topic 32, "Close Button" for a more complete explanation. DO SET KEY: Set one of the special key "clipboards" --------------------------------------------------- General form: DO SET KEYnn=string Sets one of 20 "clipboards" to the specified string value. "n" must be 1 - 20 and the string must be 1 to 120 characters in length. The DTFWIN field is set to DID SET KEYnn=string=ERR if there is a problem, otherwise =OK if no error. (The old syntax was DO KEYn,string. This may still be used.) DO SET KEYS/nn=string/KEYnn=string/nn=string/DO command ------------------------------------------------------- Sets the keys to the string values specified. The strings may contain global variables (see Topic 38). Keys may be specified with either nn or KEYnn. Any DO command (eg DO GLB) may also be run; in that case. the DO command must be placed after all keys. Although the command is shown with the "/" as a delimiter, any (reasonable) character can be used. DTFWIN sets the field to DID SET KEYS...=OK or ERR However, if the "DO" option is used, the resulting DID is from the DO command, not from the SET KEYS command. For example, DO SET KEYS/KEY10=abc/DO GLB qaxfile.QAX,cde,fgh would first set KEY10=abc, then do the GLB specified by qaxfile.QAX, passing it the parameters cde and fgh. The DTFWIN field would be set to "DOING" until the GLB was done, then it would be set to DID GLB .... SET KEYS supports setting the titlebar as well as keys. Eg DO SET KEYS/T=This is the new titlebar text,KEY05=123456 Use /+nn= to append a value to a key. DO SET TITLEBAR: Changing the titlebar -------------------------------------- General form: DO SET TITLEBAR,text Example: DTFWIN = "PGM:DO SET TITLEBAR, Case:" + CASENO; GOTO DTFWIN; DTFWIN sets the field to "DID SET TITLEBAR". (See also DO SET KEYS/T=) DO TITLEBAR: Changing the titlebar (old form) --------------------------------------------- See DO SET TITLEBAR. General form: DO TITLEBAR,text Example: DTFWIN = "DO TITLEBAR, Case:" + CASENO; GOTO DTFWIN; DTFWIN sets the field to "DID TITLEBAR". DO TLB: Text list boxes ----------------------- General form: DO TLB filename Examples: DO TLB LISTA.TXT DO TLB C:\WINDOWS\TEMP\TLB.TMP DO TLB \TLB.TMP If there is an error, DID TLB path_and_filename=ERR is returned. If the user selects Cancel, DID TLB path_and_filename=ESC is returned. Otherwise, DID TLB path_and_filename=value is returned (that is, the designated value from line the user selects is returned). You should probably avoid specifing more than one column as "+" when displaying a text list box, as the first column would be returned into the DTFWIN field and the second into the next field in the database. If you do want to return values to multiple fields which are read only, this technique can be used. 1) Put PGM:TLB etc in the DTFWIN field to do the TLB. 2) Design the form so that there is a temp field on just to the right of the DTFWIN field. This field cannot be read only. 3) On exit from DTFWIN, test for the ERR and ESC conditions. If found, clear the DTFWIN field and Goto an appropriate field. 4) On exit from DTFWIN, if DID TLB was set but it wasn't an error, then make sure control can go to the temp field to the right of DTFWIN (use an explicit GOTO if desired). 5) On exit from the temp field, test DTFWIN for DID TLB and set the desired two fields on the form, then clear DTFWIN and the temp field and goto an appropriate field. See Topic 29 for a full description of TLB's. The parameter list may include any of the DTFWIN parameter variables (see Topic 38). DO US: Userselect list boxes ---------------------------- A list box appears from which the user can make a selection. This is somewhat similar to a TLB, except that the lines in the list box are generated from within the database programming rather than from an external file. When the list box is opened, the cursor is on the first item. General form: DO US label,semi-colon delimited list of values If the user selects Cancel, DID US label=ESC is returned. Otherwise, DID US label=value is returned. Note that the list of values (and any options, such as /FIXEDFONT) are not part of the string that is returned. For fixed font in the list box, used /FIXEDFONT as shown below. To change the dimensions, specify /XSIZE:nnn and/or /YSIZE:nnn, as shown below. You can not set XSIZE smaller than 100 or YSIZE smaller than 75. These are also the default sizes. The default title is "SELECTION". To change, specify /TITLE:new text, as shown below. DTFWIN programming example (wrapped for clarity): DTFWIN = "PGM:DO US BEARS/FIXEDFONT/XSIZE:75/YSIZE:200/TITLE:Bears, Papa bear;Mama bear;Baby bear"; GOTO DTFWIN; ... IF @INSTR(DTFWIN,"DID US BEARS=") > 0 THEN { DTFWIN = @MID(DTFWIN,@INSTR(DTFWIN,"=")+1,99); IF DTFWIN <> "ESC" THEN { WhichBear = DTFWIN; DTFWIN = ""; // Other programming here, eg @XLOOKUP }; }; Topic 27: Script commands - example ------------------------------------- In this fairly elaborate (but actual) example of the script associated with a menu item, the repeat and several other script statements are shown together. An explanation follows. (The actual menu item text is not shown.) = OPEN "Patient Info" DELETE C:\BILLING\OUTPUT.TXT DELETE C:\BILLING\OUTPUT2.TXT DIALOGCHECK OFF QASCRIPT 1 REPEAT IFWINDOW "Q&A" QUIT IFWINDOW "PRINT TO FILE" BREAK ENDREPEAT STUFF "C:\BILLING\OUTPUT.TXT" WAIT 10 REPEAT IFWINDOW "Q&A" GOTO MAKEBACKUP IFWINDOW "PRINT TO FILE" BREAK ENDREPEAT STUFF "C:\BILLING\OUTPUT2.TXT" APPEND C:\BILLING\OUTPUT2.TXT TO C:\BILLING\OUTPUT.TXT DELETE C:\BILLING\OUTPUT2.TXT :MAKEBACKUP COPY C:\BILLING\OUTPUT.TXT TO C:\BILLING\.TXT Explanation. OPEN "Patient Info". The database is opened. DELETE C:\BILLING\OUTPUT.TXT Deletes the file, if it exists. DELETE C:\BILLING\OUTPUT2.TXT Deletes the file, if it exists. DIALOGCHECK OFF Tells DTFWIN not to automatically respond if Q&A Windows puts up a message (such as seen when a report is run but finds nothing to report). QASCRIPT 1 Tells Q&A Windows to run the script that appears as "1" on the Q&A Windows "Assistant" menu. For this real life application, the script runs two reports, both sending the output to the printer "Generic / Text Only on FILE". Both reports may have no data, or the first may have data while the second does not. REPEAT Begins a loop. IFWINDOW "Q&A" QUIT Says that if a window appears with "Q&A" in the title bar, quit (that is, stop the script). If Q&A Windows finds no data for the report, it will put up a message box with "Q&A" in the title bar and a message saying "No records were found that match the Retrieve Specification". Therefore this statement says to stop everthing if the first report fails to find any records to report. IFWINDOW "PRINT TO FILE" BREAK Will exit from the loop if a dialog appears with "PRINT TO FILE" in the title bar. This will happen if the report finds records to put on the report. ENDREPEAT Sends control back to the REPEAT statement above. Thus, the script will continue checking repeatedly until one of IFWINDOW statements detects its window. STUFF "C:\BILLING\OUTPUT.TXT" Directs Q&A Windows to send the report to the specified file. Note that the "PRINT TO FILE" dialog is visible when DTFWIN exits from the loop by doing a BREAK. WAIT 10 Tells DTFWIN to wait approximately as second while the report is sent to disk and the second report starts. This pause is to make sure the "PRINT TO FILE" dialog goes away before the logic below (which is associated with the second report) looks for the dialog for the second report. REPEAT IFWINDOW "Q&A" GOTO MAKEBACKUP IFWINDOW "PRINT TO FILE" BREAK ENDREPEAT STUFF "C:\BILLING\OUTPUT2.TXT" This is similar to the loop above. In this case, if the "Q&A" dialog appears (meaning no records found), control is passed via a GOTO because things need to be done with the file create by the first report (so it can't simply quit as it did above). If the second report finds data, it is written to a different file (OUTPUT2) than the output from the first report (OUTPUT). APPEND C:\BILLING\OUTPUT2.TXT TO C:\BILLING\OUTPUT.TXT DELETE C:\BILLING\OUTPUT2.TXT Both reports generated output but we want only one file, so this says to append the second report's output file to the first report's output file. The second file is then deleted as it's no longer needed. :MAKEBACKUP This is a label that is the target of the GOTO on the IFWINDOW statement in the second loop. COPY C:\BILLING\OUTPUT.TXT TO C:\BILLING\.TXT The file that has been created is now copied to another file that is assigned a name based on today's date. On today, 04 August 2000, the file would be named "C:\BILLING\000804A.TXT", unless a file with that name already exists, in which case it would be copied to 000804B.TXT, and so on. This script therefore creates a file with a standard name (OUTPUT.TXT) that can be used as part of a subsequent procedure (electronic billing, for example) but it also creates a log of each file created so that files can be resent for billing if necessary. Topic 28: Generic list boxes (GLB) ---------------------------------- A generic list box is created when the special field is GLB followed by a filename, as a result of the script command GLB, by using an F12 button with GLB in the button text, or under database control by setting the DTFWIN field to DO GLB. The contents of the file include the information required by DTFDATA. Additionally, other information must be given to describe the list box (its size, location, title, etc). DTFWIN has the DTFDATA program built into it. This gives it the ability to pop up a list box which has been loaded with information extracted on the fly from any Q&A database in the system. Records are extracted into a temporary file, then loaded into the list box. 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," The information required to extract this information and to implement the list box is partially built into the DTFWIN program. A standard QAX file is also used by DTFWIN to perform the extraction. The "select=" record(s) specify which record(s) to retrieve, and the field names specify which data to extract and in what order across the output records. Be sure to specify "format=r". Any dialog asking the user for selection parameters is coded into DTFWIN, and the information it obtains must match any parameters (such as %1 and %2) in "select=". Before a list box can be loaded with values from a database, a dialog appears that gives the user the ability to enter some initial characters to restrict the records to be retrieved from the database and loaded into the list box. For example, if searching on Client last name, the user might type in "SMI" to find John Smith. These are several parameters in the glb file you use together to control the dialog (if any), to control the appearance of the list box, and to determine the string (if any) used to restrict the data retrieved from the database in order to load the list box. In the explanation below, values such as "3" and "Clients" are examples, while the values "0" and "1" are switches. glbrestrictmaxlen=0 glbdialog=Y glbtitle=Clients glbprompttitle=Client Selection ;For the first field glbrestrictrequired=Y/[N] ;glbpromptlabel="&Last name (1-3 letters):" ;glbprompttext= glbrestrictmaxlen=3 glbtitlerestriction=names beginning with ;For an optional second field ;glbrestrict2required=Y/[N] ;glbpromptlabel2="&First name (1 letter):" ;glbprompttext2= ;glbrestrictmaxlen2= ;glbtitlerestriction2= ;For an optional third field ;glbrestrict3required=Y/[N] ;glbpromptlabel3= ;glbprompttext3= ;glbrestrictmaxlen3= ;glbtitlerestriction3= ;For an optional fourth field ;glbrestrict4required=Y/[N] ;glbpromptlabel4= ;glbprompttext4= ;glbrestrictmaxlen4= ;glbtitlerestriction4= ----------------------------------------------------- A dialog with the heading "Clients" appears to prompt the user for a three character value to be used for retrieval. If the user were to enter "SMI" into the dialog, when the list box appears, it will be identified as "Clients (names beginning with SMI)". The text "SMI" would be passed to the SELECT statement in the glb file as %1. If glbrestrictrequired is N, F, 0, or omitted, the user can leave the first field in the dialog blank, otherwise he is required to enter some text into the dialog. Use ` this option if an unrestricted retrieval would return too many hits. This option pertains to only the first field in the dialog. The default for all fields in the dialog is N. The default title for the prompt dialog is based on the list box title, like this: "Restrict string for " + glbtitle Example: Restrict string for Clients However, you can override the default title like this: glbprompttitle="Client Selection" The default label for the field in the prompt dialog is: "Enter first characters:" You can change the field label like this (the & at the front makes the first letter a hot key): glbpromptlabel="&Last name (1-3 letters):" You can specify up to 4 prompt fields to create more values to be passed to the QAX file for use in the SELECT statement as %2, %3, or %4. Example: glbrestrictrequired=Y glbrestrict2required=N glbtitlerestriction2= and first names beginning with glbrestrictmaxlen2=1 glbpromptlabel2="&First name (1 letter):" The SELECT statement would not be something like this: SELECT=LASTNAME .b. %1 & FIRSTNAME .b. %2 Note that the user must enter a value for the last name but can leave the first name blank. There can be a line of text included in each prompt dialog. Thus, when asking the user to enter a value prior to bringing up the list box, in addition to the label next to the edit box, there can be a line of instructions below the label and the edit box. Specify glbprompttext, glbprompttext2, glbprompttext3, or glbprompttext4 for up to 4 prompts. glbdialog=[Y]/N --------------------- If there is a string after the file name Example: GLB file.QAX,ACTIVE the string ("ACTIVE") is used for retrieval. (Note: Previously it was necessary to set glbrestrictmaxlen but that is no longer necessary as of April 2004.) You can also specify the value of up to four of the clipboards or other global variables (see section 38) Example: GLB file.QAX,,, would cause the value of clipboards "1" and "5" and the user id to be used for retrieval. (If the contents of either clipboard includes a comma, it will be parsed into multiple parameters for the glb.) Examples: GLB NAMES.QAX, GLB USACODES.QAX,,,, If no parameters are specified (e.g. "GLB file.QAX"), the first 5 characters of the current field are used for retrieval. This way of generating a list box is only valid in special fields (i.e. when the user presses F12), not in scripts or via the DTFWIN field using programming. (If you're not in a field, there is no place to get the value from.) Descriptions of the other GLB parameters follow ----------------------------------------------- glbxsize=250 glbysize=100 ------------ These are the x and y sizes of the list box. x is the width, y the height. Experiment until you like the appearance. Typical list box sizes glbxsize glbysize Small 250 100 Max 800 x 600 350 200 Max 1024 x 768 500 330 glbdb=Client -------------- The database from which data is to be retrieved. Use the application name for the database, not the actual DTF file name. See the [DATABASES] section of the INI file. glbextractpos=34 glbextractlen=4 ---------------- These two fields may be used, but usually it would be easier to use GLBHDR= to specify a column heading (because it is not necessary to add up columns widths or to otherwise determine the actual column position of the value to be returned). To specify a column header, ("Stock#" for example), use this syntax: GLBHDR=Stock# When the user selects a row in the list box, DTFWIN extracts 4 characters from that row starting in position 34 (for the example values shown above). Typically the text extracted from the selected row of a list box would be a unique value that can be used for XLOOKUPs. When a list box is generated by pressing F12 in a field, the resulting 4 characters are stuffed into the field and the Enter key is pressed, triggering any field exit programming. If a list box is generated by a script command or via database programming via the DTFWIN field, you might want to return several columns if not the entire line from the list box so that the script or the programming can extract multiple fields. (For example, see the SET KEY and SET TITLE script commands.) glbcompress=Y/[N] ----------------- If this is "Y", any blanks in the extracted text are removed from the beginning and end, and extra spaces are removed from the middle. Thus, you can extract a Client last and first name from fixed columns and compress them before entering them into the field. glbviewonly=Y/[N] ----------------- If this is "Y", there is no "OK" button and the user cannot select a row from the list box. It is for displaying information and not for making selections. glbhelpfile=filename or glbhelpfile=%2 -------------------- If specified, the contents of the file (a plain ascii file) are displayed in the list box below the title bar and above the actual list. You can specify an actual file name, such as LBHELP.TXT. You can also use a parameter, such as %2; in this case, this must be the last parameter value passed. Default is blank, or no help file. glbduplen=10 ------------ Specify the number of characters to be suppressed if they are duplicated from line to line. The test is performed as the list box is loaded, which means that the QAX _must_ return them using an appropriate key so that they are in order. If this option is used, the list box will not be sorted automatically; if it is not used, the list box will be sorted automatically. Default is 0, or no suppression. Incompatible with glbncsuppress. glbddisplaysort=[Y]/N ------------------- The default is to sort the contents of a list box before displaying it. Thus, even if DTFDATA doesn't return records in sorted order, they will be sorted anyway. If you set glbdisplaysort=N you will prevent this sorting. Use the N setting in conjuction with DUPS=DUPS and other options for which the output is not sorted and must not be sorted. Example: blank lines between sets of records must not be sorted because they will rise to the top. glbfixedfont=Y/[N] ------------------ If glbfixedfont=Y, the list box will displayed with a fixed font. You can use with the glbhelpfile option to supply (non-scrolling) column headers for the list box. The default is "N". glbmultiselect=Y/[N] -------------------- If glbmultiselect=Y, you can select more than one line from a list box. Instead of one result being returned, multiple results separated by semicolons are returned. If this is used to select a record, then Q&A will automatically select all records indicated, merely by pressing F10 and F9. glbpersistent=Y/[N] -------------------- If glbpersistent=Y, the list box will not be cleared once a selection is made. Instead, it can be restored later by the user. The term "PLB" meaning "Persistent List Box" automatically appears on the menu to indicate that it may be restored. Clicking on PLB will cause the list box to reappear. To clear a persistent list box, click Cancel or press Esc. If there is no list box available to be restored, the term "PLB" does not appear on the menu. glbpersistent=Y may be used with glbmultiselect=Y. glbshowcount=Y/[N] ------------ If glbshowcount=Y, the count of the number of items in the list box appears in the list box titlebar. glbnew=N glbnew=Y glbnew=Y,formname glbnew=Y, glbnew=Y,formname, ----------------------- If glbnew=Y, a button with the text "NEW" appears on the list box between OK and CANCEL. If clicked, DTFWIN automatically opens the target database (specified by glbdb= in the QAX file) in add mode. With this option in program mode, the DTFWIN field is cleared immediately and the cursor remains in the field; DTFWIN does not stuff "DID GLB". If a formname is specified, then DTFWIN will change to that form in the target database. (Maximum number of characters in the form name is 30.) If is specified, then DTFWIN will play a character after opening the new record (and switching to a form, if specified). The following script is dynamically created and run to implement the "new button" click. "DID SCRIPT" is not stuffed into the current field. OPEN database FORM formname only if specified NEWRECORD STUFF only if specified SETMODE PROGRAM Notice that the form change happens before the new record is created. This is important because creating a new record is likely to trigger programming. By switching forms first, the programming can detect the particular form and can therefore execute form specific logic. When the user closes the target database, focus automatically returns to the current database. It is convenient to put a "CLOSE" button on the form in the target database. Important: any text on this line following the values shown above will be interpreted as part of the formname or will prevent from being recognized. Note that in program mode, the standard "DID GLB xxx" is not entered into the DTFWIN field. Rather, a resulting string will be passed back from the target database. See Topic 32, "Close button" for a complete explanation. List boxes with new buttons can be nested to a depth of 3. For example, in Client you could open a list box into INVOICE and have a NEW button on that list box. Upon clicking that NEW button, a new record in INVOICE would be created. While in INVOICE and before clicking CLOSE, you could have a list box into DETAIL and have a NEW button there as well. That would be a depth of 2. (The formname mentioned in the first paragraph cannot be used with nesting.) glbcustom=nn --------------------------- 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. glball=Y/[N] ------------ If glball=Y, a button with the text "All" appears on the list box between OK and CANCEL. If clicked, DTFWIN selects all items in the list box. For use with multiselect list boxes. Warning: Q&A has a limitation on the number of items that can be selected because only a limited number of characters (approximately 100) can be pasted into a field in the retrieve spec. glbsetkey20=text,value ---------------------- The "text" is displayed on the button. If clicked, it is the same as clicking "OK" except that "value" is copied into KEY20. This might be used by the program or script to change to the desired form, as shown below. For example, "glbsetkey20=Update,Update Sales" would display a button with "Update" on it and if clicked would set KEY20 to "Update Sales". The script below would then change to the form "Update Sales" before retrieving the selected record. If the user clicked "OK", then KEY20 would retain the value "Main" and that's the form that would be changed to instead. SET KEY20=Main GLB Client.QAX SET KEY1,1,6 OPEN Sales FORM RETRIEVEALL RETRIEVE FIELD ID STUFF glbtab1=15 glbtab2=3 glbtab3=8 glbtab4=3 glbtab5=80 glbtab6=4 ---------- These parameters are optional. They specify the widths for the columns in the list box. If these are the same as the field widths below, omit these lines. Include them if you want, for instance, to combine two retrieved column into one display column. The default maximum number of columns in a list box is 20 (this can be customized for your application). These may be needed if the DTFDATA record format TABLE is used. The program generates the correct widths for fields before the =SPLIT= but not after it, so those have to be entered explicitly. Add 1 to each glbtab value as compared to the field widths specified for DTFDATA. glbncsuppress=11 --------------- Use to suppress columns on the left. Eg a date for sorting must be in the for YYYY/MM/DD (the internal format). To display it in a better format, such as MM/DD/YY, set glbncsuppress=11 (1 more than the column width of 10). Use glbtab settings for the remaining columns. Note: a field may appear more than once in the list of fields to be displayed, so the date field can appear in position 1 for sorting and in a later position for display (with a format specified. Example: GLBNCSUPPRESS=11 GLBTAB1=8 ... GLBTABn=6 10 CONTRACTDATE 8 CONTRACTDATE,MM/DD/YY GLBHDR=Date ... 6 ContractNo GLBHDR=Cntrct In this particular case, another (and easier option) is to use to mark one or more invisible columns, like this: 10 CONTRACTDATE GLBHDR= Sort date 8 CONTRACTDATE,MM/DD/YY GLBHDR=Date ... 6 ContractNo GLBHDR=Cntrct Do not use glbncsuppress with GLBHDR=. glbncsuppress is also incompatible with glbduplen. N=0 etc. -------- The remaining lines are standard DTFDATA specifications. Note that the SELECT= line must be of the form shown here because DTFWIN will take the one or so characters from the field and use them to select a subset of records. For example, if the user has SMITH in the field, and 2 characters are to be used for restriction, then this SELECT would be the equivalent of Q&A's "SM..". COLUMN HEADERS: Note that in the list of fields, the specification GLBHDR=colheader can be used to specify column headers to appear in the list box. To specify a column header, ("Stock#" for example), use this syntax: GLBHDR=Stock# To specify which column is to be returned, use this syntax: GLBHDR=Stock# To specify one or more invisible columns, which must be the left-most column(s), use this syntax: GLBHDR= any text here The use of GLBHDR is an alternative to GLBTABxx. Do not use both. Also, do not use GLBHDR= together with the glbncsuppress option. SELECT= lastname .b. %1 TRUNCATE=Y NODUPS=Y FORMAT=RECORD SORT=keylen,maxntosort (Negative means descending, ignored by Unix. maxntosort means maximum # records, for DTFWIN only.) DOUBLESPACE=Y/N/T/F/1/0 WRAPCHAR=c (Default is to wrap at a space) MAXWRAPLINES=n SEPARATOR=n DUPS=All/Unduplicated/Single/Dups/Inconsistent/Consistent/Repeated // Field list 15 lastname GLBHDR=Last name //TEXTWRITER 1 27 firstname GLBHDR=First name //TEXTWRITER 2 8 filename GLBHDR=Filename //TEXTWRITER 3 5 recordno GLBHDR=RecNo Starting with GLBHDR, the rest of the line is a comment as far as the DTFDATA logic is concerned. Anything to the right of GLBHDR that begins with // is a comment as far as the column header logic is concerned. The "lastname" line above has this interpretation: The column is 15 characters wide, the field name is "lastname", the column header is "Last name", and this is field "1" if the TEXTWRITER command is used. The column "recordno" contains the value to be returned when the user makes a selection from a list box. The actual column heading will be blank. If GLBHDR= is specified, it is not necessary to set glbextractpos and glbextractlen. In the example, GLBHDR=RecNo was specified. This will generate "RecNo" as the column header. Topic 29: Text list boxes (TLB) ------------------------------- A text list box is created when the special field is TLB followed by a filename. The contents of the file include header information as well as the actual text to be displayed in the list box. The cursor is automatically placed on the first selection in the list box. Examples: TLB LISTA.TXT TLB C:\WINDOWS\TEMP\TLB.TMP TLB TLB.TMP You can create a file by generating a Q&A report to disk and then editing it as needed with any text editor (if you use a word processor, do not save it as a word processor file). The first line in the file is the text to be displayed as the header for the list box when it pops up. It may also pass parameters in the form of switches (e.g. see /VIEWONLY below). The second line is optional. If it has +'s and -'s, they indicate which columns are to be entered into database fields. A + means that column is to be entered, a - means that column is not to be entered. If the second line does not have +'s and -'s, then the data from all columns are entered into successive fields in the database. Important: if this line is present, the first character must be a +, not a -. The second (or third) line has -------'s to indicate the columns. You can use either hyphens ("-", hex 2D, decimal 45) or a single width line draw character ("Ä", hex C4, decimal 196). Subsequent lines are the information for the list box. This is an example in which the entire line (one column) is entered: Media List ------------ FLYER FRIEND LAWYER OTHER OTHER Client PAPER PREV Client RADIO RELATIVE SIGN TV YEL PG This is an example in which two columns of data are entered. City and State ------------ -- Pittsburgh PA Youngstown OH New York NY In this case, the data from the first column is entered, followed by ENTER, followed by the data for the second column. This is what a file might look like that enters only 1 column. FAVORITE PEOPLE + - - ---- ------------------- ------------------ 0032 SANTA CLAUS NORTH POLE 0999 EASTER BUNNY UNKNOWN 2910 TWEEDLE DUM WONDERLAND In this example, an ID number, a name, and an address will be displayed in the list box, but only the ID number will be entered into the database when a row is selected. The contents of the file are not sorted before being displayed in the list box. To clear each field before entering data, DTFWIN uses before stuffing the selected text.. If the first line of a TLB file ends with "/VIEWONLY", the user will be shown the information and will be able to scroll to see it if necessary, but can only click on "Cancel" to clear the box. No selection is possible. The "/VIEWONLY" will be removed from the first line before it is used for the title of the list box. If the first line of a TLB file ends with "/FIXEDFONT", the contents are displayed in a fixed font. If the first line of a TLB file ends with "/YSIZE=nnn", you can specify a number to control the height of the TLB window. The default value is 100. The value you specify must be 3 digits. Example: "/YSIZE=250". (The width is computed automatically based on the contents you supply.) Topic 30: Multiple choice dialog boxes (DLG) --------------------------------------------- Creates a dialog with buttons that returns button-specific values or automatically triggers other GLB or TLB dialogs. In field mode, you could have multiple searches tied to an F12 button on the database form. Upon clicking the F12 button (or pressing the F12 key), a dialog would appear with buttons for the various search choices. When a selection is made, the specified search (eg a GLB or TLB) is invoked. To use this type of dialog in field mode, specify "F12:DLG filename" on the Q&A Windows button. Example: "F12:DLG NAMESRCH.DLG". Here is a sample file specifying this new type of dialog. There can be as many blank lines and comment lines as you wish. However, the title, xsize, ysize, and button lines must be in this order. // Ask whether to search by first or last name (field mode) title=Name search xsize=120 ysize=70 button=Search by last name,GLB SRCHLAST.QAX button=Search by first name,GLB SRCHFRST.QAX In this example, next to the first button will be the words "Search by last name". Next to the second button will be "Search by first name". This example if for field mode. If either choice is made by the user clicking a button, the specified GLB will be triggered. In program mode, do DO DLG dlgfile.DLG and get back DID DLG dlgfile.DLG=result. The result value to be returned by a button click is specified for each button in the DLG file. (If the user clicks CANCEL or presses the ESC key, the value returned is "ESC".) Here is the same sample file as it might be used in program mode. In this example, if either button is clicked, the value LAST or FIRST would be returned. Eg DID DLG dlgfile.DLG=LAST. // Ask whether to search by first or last name (program mode) title=Name search xsize=120 ysize=70 button=Search by last name,LAST button=Search by first name,FIRST You can have at most 9 buttons. Topic 31: XLOOKUP ----------------- While Q&A itself has XLOOKUP functions, the DTFWIN function described here has certain advantages. First, it does not leave the database file open. Thus, it should be used to extract data from a database to which you are also posting with DTFWIN (without using the POST=SHARE option). Second, it can not only extract records with multiple fields (similar to Q&A's XLOOKUP's ability to get data from multiple fields) but it will also be able to extract multiple records. Having done so, programming in the database could examine the multiple records to derive information, such as the amount a Client owes from all open invoices. The present implementation does not extract multiple records. An XLOOKUP is performed when the special field is XLOOKUP followed by a filename. The contents of the file include the information required by DTFDATA. Additionally, the file must have a line with DB= followed by the database name from which the data is to be retrieved. In addition to defining the special field, database programming on entry to the field has to set it to "XLOOKUP keyvalue", where "keyvalue" is the key value to be used to select the record. Example: "XLOOKUP 1234" to get data for Client 1234. This corresponds to the %1 in the "SELECT=" line in the QAX file pointed to by XLOOKUP in the INI file. If desired, you could pass more than one value, comma delimited, to correspond to %1, %2, etc in the QAX file. Example: "XLOOKUP A,23". After the value is entered into the field by DTFWIN, an "Enter" is pressed causing exit from the field. (If desired, the following field could have on entry programming to do something with the value just entered into the field.) If no data is retrieved, the field is cleared. Topic 32: Buttons (BACK, CANCEL, CLOSE, SAVE, CUSTOM, UNDO) ----------------------------------------------------------- BACK button ----------- If the user clicks any button labeled "BACK" (case insensitive), DTFWIN will go back to the previous form that was identifiable (by having a unique button). Any forms visited in the interim that are not identifiable will be skipped over on the way back to the last identifiable form. DTFWIN intercepts the click on the button, so Q&A Windows never realizes that the user clicked on it. Thus, it makes no difference which script you associate with the button, although you must associate a script to make Q&A happy. CANCEL button ------------- No default action, can be customized. CLOSE button ------------ Closes the current database. It is advisable to associate a dummy script to the button in case it is clicked while in qawin without DTFWIN. With DTFWIN running, the click is intercepted by DTFWIN and no qawin script is actually run. A close button is very useful for lookup databases that are opened using the glbnew option in a list box. That is, the user doesn't find the desired entry, clicks the "New" button at the bottom of the dialog, adds a new record to the lookup database which automatically appears, then clicks the "CLOSE" button, at which point the lookup database goes away and the information from the new record is passed back to the original database. To pass information back to the database doing the lookup, in the lookup target database either set a field to "CLOSE:" followed by the value to be returned, or use "DO SET CLOSE=" followed by the value to be returned. Examples: FIELD1 = "CLOSE:" + RECORDNO; GOTO FIELD1; or DTFWIN = "PGM:DO SET CLOSE=" + RECORDNO; GOTO DTFWIN; In the first case, RECORDNO will be returned and the cursor will remain in field FIELD1 so the user can do data entry into that field. In the second case, the DTFWIN will be reset to DID SET CLOSE=xxxxx=OK (or ERR) and Enter will be played so the cursor will leave the DTFWIN field, triggering the field exit programming. CUSTOM button ------------- See "Topic 10: INI file [DTFWIN] section -- Common initialization" for an explanation of the "BUTTON" setting in the INI file. SAVE button ----------- If a SAVE button is clicked and you are adding or updating a record, DTFWIN will tell Q&A Windows to save the current record to disk. This is important if you are adding a new record into a lookup database and now wish to go to another database and retrieve the record in a list box. If the record is not written to disk, the DTFDATA logic in DTFWIN will not see the new record. (Unless you want to keep the lookup database open, use a CLOSE button instead.) DTFWIN can be customized so that additional actions take place when this button is pressed. For example, if entering an order and the Client is new so he does not appear in a Client list box, DTFWIN can open the Client database in add mode so you can add the Client. Then, upon clicking SAVE, DTFWIN would return to the original order database so the Client number can be entered into the order. In a script, you can do the same thing as the SAVE button by the following: SAVE BUTTON EQUIVALENT STUFF "R" (The is needed in case the current retrieve spec refers to a field not on the current form.) The SAVE button logic for existing records uses CTRL-T followed by ESC. CTRL-T brings up the sort spec (and ESC clears it). It is best not to use sort specs when retrieving records because of possible complications. For example, if a sort spec uses a field that's not on the current form, a message will popup asking whether to change to another form. The SAVE logic doesn't anticipate this message, causing confusion. The SAVE button logic for new records uses CTRL-R followed by ESC. This brings up the retrieve spec, then cancels it. This technique cannot be used for existing records in certain circumstances, such as when there is a sort spec in use. UNDO button ----------- An UNDO button on a form undoes any changes made to the record. It has the same effect as Ctrl-Z or Edit>Undo (from the qawin menu). Topic 33: Special function keys ------------------------------- There are three function keys that can be pressed while in DTFWIN or any of the Q&A Windows that may be up. These keys are to trigger actions associated with special fields and to change the focus between DTFWIN and the databases. Default function key Function -------------------- ---------------------------------- F12 special field action Alt-F11 change focus to DTFWIN F11 change focus to database, cycle through all open databases These keys can be customized to any function keys (with or without Alt) that you wish. The default is to use F11 and F12, because they are not used by Q&A Windows. Alt-F11 is the default to switch to DTFWIN, because if you use the keyboard to switch to DTFWIN, you probably want to have Alt depressed to make a menu choice. Topic 34: What happens if Q&A Windows has a problem ---------------------------------------------------- If DTFWIN tells Q&A Windows to close but it doesn't, DTFWIN will wait patiently. This could happen if Q&A Windows has displayed some error message that the user has to clear before Q&A Windows can terminate. This is not likely to happen, as DTFWIN checks for any dialogs belonging to Q&A Windows -- if there is one, it will refuse to exit. If it does happen, the user has to satisfy Q&A Windows (for example, respond to the message) and then do File -> Exit at Q&A Windows to tell it to exit. Sometimes Q&A Windows seems to be hung up on programming. You can't enter a field, can't exit. The following sequence seems to be effective in clearing this condition: Press Ctrl-B, reply "N", then press "Esc". At this point you can exit from QAWIN. Something to beware of in your database design is a conflict between a "Goto field" in a Q&A script that's associated with a button and a "goto" in the programming in a field. Q&A Windows doesn't seem to handle this situation very well. The solution is to avoid using field exit goto's in fields the cursor is likely to be in when the user clicks on such a button. Topic 35: List of Q&A menu choices for ALLOW and DENY commands -------------------------------------------------------------- These two commands are used to specify which Q&A Windows menu choices are available to the user. Presumably all functions would be controlled by DTFWIN instead of directly through Q&A Windows because the Q&A Windows menu is normally hidden. Therefore it is not necessary to allow or deny commands. For this reason, all commands are by default allowed. However, a script could deny or allow commands even if they appear on the DTFWIN menu. To deny a single menu choice, use DENY, like this: Deny "File->Print" To enable all choices on one menu, use the following format: Allow "Help" You can use both formats together, to allow all menu items and then deny one or more from the set, like this: Allow "Edit" Deny "Edit->Calculate Options" This the complete list of menus: File Edit Select Record Assistant Help Toolbar This the complete list of menu items: File->New *Record->New Record File->Open Record->Duplicate Record File->Close *Record->Delete Record File->Import Record->Revert Record File->Export *Record->Sort File->Copy Database *Record->Retrieve File->Recover Record->Retrieve All File->Preferences Record->Toggle View Mode File->Print Preview Record->Spreadsheet View Font File->Print Record->Save Spreadsheet Layout File->Print Setup Record->Field Help File->Page Setup Record->Field Restrictions File->Q&A Write *Record->First Record File->1 *Record->Previous Record File->2 *Record->Next Record File->3 *Record->Last Record Edit->Undo *Assistant->Intelligent Assistant Edit->Cut Assistant->Scripting Assistant Edit->Copy Assistant->Manage Assistant Menu Edit->Paste Assistant->MENU_1 through MENU_9 Edit->Paste Special Current Date Edit->Paste Special Current Time Edit->Clear Edit->Select All ! Edit->Override Field Mask Edit->Calculate Now Edit->Calculate Options Toolbar->Cancel Toolbar->Formview Toolbar->Tableview Toolbar->Load Input Form Help->Contents Help->Search for Help On Help->How to Use Help Help->Tutorial Help->About Q&A *Select->Add/Edit *Select->Design Input Forms *Select->Design Reports Select->Run Report Select->Database Structure Select->Mass Update Select->Mass Delete Select->Load Input Form Hidden->F3 Clears retrieve spec Notes: 1) "Hidden" commands do not correspond to any menu choice. 2) Items with * appear on the Q&A menu as well as on the toolbar. Use the menu equivalent to allow or deny them. The 4 Toolbar items are similar to menu items but are in fact not the same. 3) Edit->Override Field Mask must be allowed if the RETRIEVE and NEWRECORD script commands are used. If it is not allowed, once either of these commands is used, Q&A no longer responds to buttons. Topic 36: Command line parameters --------------------------------- Put one or more of these on the command line in the shortcut for DTFWIN to turn on features useful when designing the application. @DESIGN Permits you to get into the database to make design changes. Also provides information about field coordinates when you press F12 in a field. @SHOWMENU Keeps Q&A Windows menus visible at all times. To be used for development only. @SIZE Displays the size of databases when you select Help -> Technical. It also permits you to resize them with the mouse. @SHOWQT Shows file name (and parameters) of a QAX file name in the glb title bar or the file name of a tlb file in its title bar. If your system has many QAX and TLB files, this will save time identifying which one is being used and perhaps needs to be modified or tweaked. (Also SHOWQAXTLB.) @TRACE Turns on tracing. Useful when writing scripts. See also the script commands TRACE ON and TRACE OFF. CFGDIR= Specifies the location of the CFG file if it's not in the dtfwin directory. Topic 37: SUMMARY OF COMMANDS ----------------------------- PROGRAM MODE (CONTENTS OF SPECIAL FIELD "DTFWIN") ------------------------------------------------- (Return field values begin with "DID".) DO CUSTOM optional parameters DID CUSTOM DO BEEP DID BEEP DO COPYBIN source TO destination DID COPYBIN source TO destination=OK or ERR DO DLG dialogfile DID DLG dialogfile=result or ERR DO DTFDATA database qaxfile outputfile parms DID DTFDATA database qaxfile outputfile parms=1st record DID DTFDATA database qaxfile outputfile parms=ERR DO FIRSTFIELD DO GET KEYnn DO GET KEYnn/CLEAR KEYnn=value DO GET TITLEBAR DID GET TITLEBAR=value DO GLB file.qax,parameterlist (parameter list is optional) DID GLB file.qax=value DID GLB file.qax=ERR DID GLB file.qax=ESC DO KEYnn=string (See DO SET KEY). DO MSG label,button,icon,text of message DID MSG label,button DO PGMDLG: Puts up dialog with buttons DID PGMDLG DO PROMPT label,titletext,labeltext,boxwidth,maxchars, [defaultval],[instructions] DID PROMPT label=result DO QASCRIPT n DO RUN program parms DO RUNWAIT question,title,program parms DO SCRIPT dtfwinscriptname,[optional key values] DID SCRIPT dtfwinscriptname DID SCRIPT dtfwinscriptname=ERR (if undefined dtfwinscriptname) (Even when key values are set, does not return DID SET KEYnn.) DO SENDMAIL DID SENDMAIL=Y DID SENDMAIL=ERR DO SET CLOSE=string DID SET CLOSE=string=xxx xxx=OK or ERR DO SET KEYnn=string DID SET KEYnn=string=xxx xxx=OK or ERR DO SET KEYnn,string (old syntax) DID SET KEYnn,string=xxx xxx=OK or ERR DO SET TITLEBAR DO TITLEBAR,text DO TLB path_and_filename DID TLB path_and_filename=value DID TLB path_and_filename=ERR DID TLB path_and_filename=ESC DO US label/options,semi-colon delimited list of values DID US label=value DID US label=ESC PROGRAM MODE (CONTENTS OF ANY FIELD) ------------------------------------ (See above for return values.) PGM:CLEAR DO command Clears DTFWIN field, no "Doing" PGM:DO BEEP PGM:DO COPYBIN source TO destination PGM:DO CUSTOM optional parameters PGM:DO DLG PGM:DO DTFDATA database qaxfile outputfile parms PGM:DO FIRSTFIELD PGM:DO GET KEYnn PGM:DO GET KEYnn/CLEAR PGM:DO GET TITLEBAR PGM:DO GLB file.qax,parameterlist (parameter list is optional) PGM:DO MSG label,button,icon,text of message PGM:DO PROMPT label,titletext,labeltext,boxwidth,maxchars, [defaultval],[instructions] PGM:DO QASCRIPT n PGM:DO RUN program parms PGM:DO RUNWAIT question,title,program parms PGM:DO SCRIPT dtfwinscriptname,[optional key values] PGM:DO SENDMAIL PGM:DO SET CLOSE=string PGM:DO SET KEYnn=string PGM:DO TITLEBAR,text PGM:DO TLB path_and_filename PGM:DO US label,semi-colon delimited list of values FIELD MODE (SPECIAL FIELDS, DEFINED IN INI FILE BY COORDINATES) --------------------------------------------------------------- CALCULATOR DLG dlgfile,parms GLB file.QAX MANDATORY RUN program parms %1 parms SCRIPT dtfwinscriptname TLB file.ext XLOOKUP file.QAX FIELD MODE (CONTENTS OF ANY FIELD) ---------------------------------- text FLD:CALCULATOR FLD:DLG dlgfile,parms FLD:GLB file.QAX FLD:MANDATORY FLD:RUN program parms %1 parms FLD:SCRIPT dtfwinscriptname FLD:TLB file.ext FLD:XLOOKUP file.QAX FIELD MODE (BUTTON TEXT) ------------------------ F12:CALCULATOR F12:DLG dlgfile F12:GLB file.QAX F12:RUN program parms %1 parms F12:SCRIPT dtfwinscriptname F12:TLB file.ext F12:XLOOKUP file.QAX SCRIPT MODE ----------- ABOUT ALLOW APPEND file TO file BEEP BREAK CLOSE database CONTINUE COPY file TO file COPYBIN file TO file CUSTOM optional parameters DELETE filename DELETERECORD DENY DIALOGCHECK ON/OFF DTFDATA ENDIFUSER (pseudocommand) ENDREPEAT EXIT FIELD "field name" FIRSTFIELD FIRSTRECORD FORM "form name" GLB filename GOTO label IFANYOPEN (pseudocommand) IFDBEXISTS "dbname" (pseudocommand) IFCLOSED database (pseudocommand) IFOPEN database (pseudocommand) IFFILE "filenameandpath" command IFFILEEXISTS "filename" (pseudocommand) IFNOFILE "filenameandpath" command IFUSER (pseudocommand) IFWINDOW "text" command LASTRECORD MAKEDIR MASSUPDATES MENU MERGEMAIL filename MSG NAVIGATION NEXTRECORD NEWRECORD OPEN database PLEASEWAIT "Title text" "Message text" PLEASEWAIT (Cancels if no parameters) PREVRECORD PROMPT QAMENU ON/OFF/command# QASCRIPT 1 (through SCRIPT 9) QASCRIPTS QAWRITE QUIT RENAME REPEAT REPORT F/C/L "name" A/L REPORTS RETRIEVE RETRIEVE "text to be stuffed into the retrieve spec" RETRIEVEALL REVERT RUN SET KEYnn,pos,len SET KEYnn=string SET TITLEBAR,text,pos1,len1,pos2,len2,pos3,len3,pos4,len4 SETFOCUS database SETMODE PGMMODE or FIELDMODE or SCRIPTMODE SORT STUFF "text to be stuffed" TECHNICAL TLB filename TRACE ON/OFF WAIT n Topic 38: DTFWIN GLOBAL VARIABLES --------------------------------- By including any of these variables in a script or elsewhere as described above, the actual value will be used instead. (current database) (today's date) (today's date)