DBFSCR version 2.0 WHAT IS DBFSCR? DBFSCR is a shareware program designed for programmers to help in the design of data entry screens. It uses a screen painter and template files to generate code to be included within programs. DBFSCR uses the SAY..GET metaphor common in all xBASE languages. The templates are not limited xBASE programs. Any code can be included within the templates. In this way, DBFSCR can be used as a screen painter for any data-entry library for any language. Included with this program are templates for Clipper, dBXL, Code Base 3, SkipJack, dBASE 3, and Topaz. SkipJack and Topaz are Pascal libraries that provides access dbf files. They also include screen io functions/procedures similar to the @..SAY..GET of xBASE. Code Base is a C library that provides access to dbf files and provides screen io functions similar to @..SAY..GET. USING DBFSCR To use DBFSCR, just type DBFSCR at the DOS prompt. You will be provided with a blank screen. There is a one page help screen available by pressing F1. You can use the cursor keys to move the block around the screen. Design your screen using the ALT key combinations described below. At any time, you can save your file by pressing Alt-F. The saved file is a special format used by DBFSCR. When you are ready to create your program file to be included in your programs, press Alt-T (Template). Supply the template filename and the filename for the program code. DBFSCR will produce the code using the template. To use the new code, just include it in your program. To modify the screen, load the saved screen and make your changes. It is a good idea to leave the generated code in its own file, so that when you make changes, you can just overwrite the old file. LIABILITY The author bears no responsibility for any damages or losses caused by the use of this program. The burden of liability is on the user of the program. By using this program, the user relieves the author of all liabilities. ACKNOWLDGMENTS dBASE and Ashton-Tate are registered trademarks of Ashton-Tate Corporation. Clipper and Nantucket are registered trademarks of Nantucket Corporation. dBXL and Quicksilver are registered trademarks of WordTech Corp. Code Base is a C library developed and distributed by Sequiter Software Inc. Skipjack is a Pascal library developed and distributed by Max Software Inc. Topaz is a Pascal library developed and distributed by Software Science Inc. SHAREWARE This program is shareware. You are entitled to use the program for 30 days to see if you have use for it. If you find the program of value, please send $15 to: Steven Feinstein 72 Katherine Drive Hamden, CT 06514 COMMANDS ALT-A CHANGE SCREEN'S COLOR Alt-A will change the background color for the entire screen. The colors selected for objects that have already been created will not be affected. When a program file is created, a command from the template will be used once at the beginning of the program to change the screen's colors. ALT-B CREATE BOX Alt-B will create a box object on the screen. A message will be displayed requesting that you move the cursor to the opposite corner for the box. The cursor will change from a solid box to a solid box with a blinking cursor. You can use all of the cursor movement keys to set the box coordinates. ALT-C CENTER OBJECT Alt-C will center the currently selected object horizontally on the screen. The current object is the one the cursor is on. If no object is located at the cursor location, a message will appear informing you of this. ALT-D DELETE OBJECT Alt-D will delete the currently selected object. The current object is the one the cursor is on. You will be prompted to make sure that you want to delete the object. There is NO undo capability. ALT-E EDIT OBJECT Alt-E will display a data-entry screen (like the one used when creating an object- See Alt-G and Alt-S for a description of the fields). You can change any of the information on this screen which describes the object. This function will not work on box objects. ALT-F SAVE SCREEN Alt-F will save the screen to a data file. This file can only be used by DBFSCR and should not be confused with the converted program files. You will be prompted for a filename. You must enter an extension if you want one. ALT-G CREATE INPUT "GET" OBJECT Alt-G will create a "GET" object. A data-entry screen will be displayed allowing you to enter information about the object. The following is a description of the fields: 1) Field type: B - byte C - character D - date I - integer L - logical N - long integer R - real S - string not all templates support all of these types. If a template does not support one of these types, the GET statement will not be printed. 2) Variable/Fieldname: enter the variable name used in the program. Or, if you are using one of the xBASE dialects and want to enter a file's fieldname, you can do that as well. 3) Picture: If your program supports them, enter the picture string used by the programs. Do NOT enter the quotes around the string. That should be handled by the template. 4) Range: If your program supports them, enter the range clause for your field. Do NOT enter any quotes around the range, this should be handled by the template file. 5) Prefield: If your program supports prefield or when clauses, enter the function to be performed here. Do NOT enter () or @ in this field. They should be handled by the template file. 6) Valid: If your program supports valid clauses enter it here. Do NOT enter () or @ in this field, it should be handled by the template. 7) Display length: Enter the length of the field. Character and logical fields will be limited to 1 character in length. 8) Decimal Places: Enter the number of decimal places for the field. This is only valid for real types. Everything else will have a value of 0. ALT-H CHANGE HOME COORDINATES Alt-H will change where on the screen the home location will be. This function was put in for people who use window libraries. Some libraries are set up so that a row is relative to the window borders. In order to show how a screen will look at a screen location, but still keep the coordinates relative, use this function. If you screen output is not relative to a window, don't use this function, your coordinates will be off. ALT-I CHANGE COLORS FOR NEW OBJECTS Alt-I will set the default colors. Whenever an object is created, the new default colors will be used. The command works the same as Alt-A. This command has no affect on existing objects. ALT-K CHANGE AN OBJECT'S COLORS Alt-K will change the color of the currently selected object. The current object is the one the cursor is on. The command works the same as Alt-A, but will only change the current object. ALT-L LOAD SCREEN Alt-L will load a saved screen file from disk. It will first reinitialize the screen, so any work that has not been saved will be lost. If the file is a version 1 file, you will be notified that you will need to save the file using ALT-X if you want to keep it in version 1 format. If you enter a mask (ie. *.dat) or enter a directory ending with '\' (ie. c:\ or \data\) a popup window will be displayed of files to choose from. If you enter an '*' without an extension .dat will be assumed. To get a popup list of the current direcoty enter an '*' by itself. ALT-M MOVE OBJECT Alt-M will move the currently selected object to a new location. The current object is the one the cursor is on. The cursor will change from a solid block, to a solid block with a blinking cursor inside. You will be prompted to choose a new location. ALT-N NEW SCREEN Alt-N will clear the screen and reinitialize the objects. Any work not saved will be lost. ALT-O REDORDER GETS Alt-O will change the order that GETs are printed in the output file. By default, DBFSCR will print the GETs in the order that they are on screen. The xBASE language determines data-entry order by first come basis in the program. Instead of forcing screen order, this function will allow you to reorder the GETs. To use the new order, choose 'N' when asked if you want to use screen coordinates during template conversions. A popup window will appear with the GETs listed in their current order. The first time, they will be in the order that you have entered them (not screen order). To change the order, hilite the item that you want to move, press enter, move to the item that you want to place the first one after, and press enter. It will take two steps to move a GET to first on the list. Move it after the first item and then move the first item after it. ALT-Q QUIT Alt-Q will quit the program. All worked not saved will be lost. ALT-R COPY OBJECT Alt-R will copy the currently selected object to a new location. The current object is the one the cursor is on. The cursor will change from a solid block, to a solid block with a blinking cursor inside. You will be prompted to choose a new location, and a new variable/fieldname (unless the object is a box or it is a text SAY object). You do not have to change the fieldname. ALT-S CREATE "SAY" OBJECT Alt-S will create a "SAY" object. A data-entry screen will be displayed allowing you to enter information about the object. The following is a description of the fields: 1) (S)tring or (V)araible: decide whether the object is a literal string (S) or a variable or fieldname (V). If the first field is 'S' then: 2) Text: enter the literal text string If the first field is 'V' then: 2) Field type: B - byte C - character D - date I - integer L - logical N - long integer R - real S - string not all templates support all of these types. If a template does not support one of these types, the GET statement will not be printed. 3) Variable/Fieldname: enter the variable name used in the program. Or, if you are using one of the xBASE dialects and want to enter a file's fieldname, you can do that as well. 4) Picture: If your program supports them, enter the picture string used by the programs. Do NOT enter the quotes around the string. That should be handled by the template. 5) Display length: Enter the length of the field. Character and logical fields will be limited to 1 character in length. 6) Decimal Places: Enter the number of decimal places for the field. This is only valid for real types. Everything else will have a value of 0. ALT-T CONVERT USING TEMPLATE Alt-T will convert the current screen to a text file of programming commands. The commands used will depend on the template. See the section on templates to learn more about how they work and how to create your own. This is the command that will generate the source code for your programs. You will be prompted if you want to use screen coordinates. If you answer 'Y' then the GETs will be written based on the order they appear on the screen. If you answer 'N', the GETs will be written based on the order that you set using Alt-O. This will have no affect on SAYs and Boxes. You will then be prompted for a template name. An extension of TEM will be assumed if you don't enter one. You can get a popup list by entering a mask (*.tem), entering a directory ending with a '\' (\data\), or by entering an '*' with or without a directory. In that case TEM will be assumed. If the '*' is by itself, the current directory will be displayed. Next you will be prompted for a filename. No extension will be assumed. ALT-X SAVE SCREEN AS VERSION 1 Alt-X will save the current screen as a version 1 file to be used by the previous version of DBFSCR. In order to have some new functions, the file format had to change. Load Screen will load a version 1 file, but to save it, you will need to use this function. The only use for this function, is if you need to use the version 1 software. None of the new features will be saved in this format, so any changes to the new feautres will be lost. ALT-Z SET NEW START COORDINATES Alt-Z will change the start coordinates. The xBASE language uses 0,0 as the start coordinates. Pascal uses 1,1. This function will allow you to change the coordinates to anything you like. NOTE - Veersion 1 had a default start coordinate of 1,1. Version 2 has been changed to 0,0. This was done to be more compatible with xBASE. Just use this function to change it. F2 VIEW/USE DBF FILE F2 will load a .dbf file for viewing of the structure. You can also use a field in the structure to create a GET. F2 will prompt you for a filename. If you enter a directory ending with a '\' (ie. c:\ or c:\data\) a popup list of dbf files will appear that you can choose from. If you enter an '*' by itself, a list of the current directory will be displayed. You can also enter a file mask (test*.dbf or *.dat) if you want to limit the list or if you have named your database files using a different extension. Once a file is chosen, the structure will appear in a popup window. You can view the structure and press ESC when finished. If you press ENTER, you will be placed in a GET data entry screen. The TYPE, WIDTH, and DEC will be filled in based on the structure. The variable/fieldname will be filled in using xBASE notation and the filename as the prefix (ie. TEST->FIELD1). You can then change any information and a GET will be created. If there is not enought room for the GET, a message will display stating this information. CURSOR KEYS The following is a list of cursor keys and their functions. LEFT ARROW - move 1 space to the left. The cursor will wraparound the screen if you move past the left edge. RIGHT ARROW - move 1 space to the right. The cursor will wraparound the screen if you move past the right edge. UP ARROW - move 1 line up. The cursor will wraparound the screen if you move past the top of the screen. DOWN ARROW - move 1 line down. The cursor will wraparound the screen if you move past the bottom of the screen. HOME - move to the beginning of the line. END - move to the end of the line. PGUP - move to the top of the screen. PGDN - move to the bottom of the screen. TAB - move 10 spaces to the right. The cursor will wraparound the screen if you move past the right edge. BACKTAB (Shift -TAB) - move 10 spaces to the left. The cursor will wraparound the screen if you move past the left edge. TEMPLATES Templates are the key to the program. They are used to determine what commands to write depending upon the object type. Included with DBFSCR are the following templates: clipper5.tem, codebas3.tem, dbase3.tem, dbxl.tem, skipjack.tem, and topaz.tem. The templates are just ASCII files and can be modified to suit your programming needs. You can also create your own. It is recommended that you do not change the template files. You should copy them under another name and make changes to the copies. Each line in the template corresponds to commands for each object. The lines in the templates supplied contain comments so you will know which lines should contain which commands. For example, if the comment states 'SAY DATE', then the command on that line should contain the programming command for displaying the date. It is important to place the commands on the correct lines. DBFSCR does not use the comments to determine which command to use. It uses the line number. The comments are there for your use to see which commands to place on which lines. The following is a list of symbols that can be used in the template: \ - used in front of a command to tell DBFSCR that the following command is the last for a line and a newline/carriage return should be placed after it. | - everything on the line after this symbol is considered a comment. # - a command for this line is not used. Ignore anything that would normally create a command for this line. & - use the alternate picture clause with this command. <> - replace this symbol with the value for the global foreground color. <> - replace this symbol with the value for the global background color. <> - replace this symbol with the value for the foreground color. <> - replace this symbol with the value for the background color. <> - replace this symbol with the value for upper row. <> - replace this symbol with the value for upper column. <> - replace this symbol with the value for lower row. <> - replace this symbol with the value for lower column. <> - replace this symbol with the text for that command. <> - replace this symbol with the width of the variable. <> - replace this value with the decimal of the variable. <> - replace this symbol with the text for that command. Use instead of var if the text needs to be split at a comma (see Range in the template files). <> - replace this symbol with the text for that command. Same as <>, but gets the text after the comma instead of before the comma. The following is a list of the lines that are within the template file. line 1 - color type the type must be P, D, or N. They stand for Pascal (using the crt values like Black, LightGray, etc.), dBASE (using the xBASE commands like N/W etc.), and Number (using the decimal value for colors like 7 for white). This is used internally by DBFSCR. line 2 - CLS color The command used to set the color used by a clear screen command. line 3 - Clear Screen The command to clear the screen using the new colors. line 4 - Box color 1 The first command used to set the box color. Most programs do not require two commands, but the provision is there if it does need two. line 5 - Box color 2 The second command used to set the box color. Since most programs do not have a second command, this line usually will contain a #. line 6 - Draw box The command used to draw a box. line 7 - If Double If the box is a double lined box, then this command will be used to complete the box command. line 8 - If Single If the box is a single lined box, then this command will be used to complete the box command. line 9 - Say color 1 Command used to set the SAY colors. A second one is provided if necessary. line 10 - Say color 2 A second command to set the SAY colors. This one is not usually used, but is provided in case two commands are required. line 11 - Say char Command used to display a variable of type char on the screen. line 12 - Say text Command used to display a text string on the screen. line 13 - Say string Command used to display a variable of type string on the screen. line 14 - Say date Command used to display a variable of type date on the screen. line 15 - Say byte Command used to display a variable of type byte on the screen. line 16 - Say integer Command used to display a variable of type integer on the screen. line 17 - Say long Command used to display a variable of type long integer on the screen. line 18 - Say real Command used to display a variable of type real or double on the screen. line 19 - Say logical Command used to display a variable of type logical or boolean on the screen. line 20 - with Say picture Command to print if the variable has a picture clause. line 21 - without Say picture What to print if there is no picture clause. line 22 - with Say picture Alt Alternate command to use if variable has picture clause. This will be use if the Say command is preceded by an &. line 23 - without Say picture Alt Alternate command to print if there is no picture clause. This will be used if the Say command is preceded by an &. line 24 - Get color 1 Command to print to set the color for the next GET. There are two commands if necessary. line 25 - Get color 2 Second command for setting the GET color. Usually this is not used. line 26 - Get char Command used to display a GET variable of type char and get it ready for a read. line 27 - Get string Command used to display a GET variable of type string and get it ready for a read. line 28 - Get date Command used to display a GET variable of type date and get it ready for a read. line 29 - Get byte Command used to display a GET variable of type byte and get it ready for a read. line 30 - Get integer Command used to display a GET variable of type integer and get it ready for a read. line 31 - Get long Command used to display a GET variable of type long int and get it ready for a read. line 32 - Get real Command used to display a GET variable of type real or double and get it ready for a read. line 33 - Get logical Command used to display a GET variable of type logical or boolean and get it ready for a read. line 34 - with Get picture Command to print if the variable has a picture clause. line 35 - without Get picture Command to print if there is no picture clause. line 36 - with Get picture Alt Alternate command to use if variable has picture clause. This will be use if the Get command is preceded by an &. line 37 - without Get picture Alt Alternate command to print if there is no picture clause. This will be used if the Get command is preceded by an &. line 38 - with Range Command to use if the variable has a range clause. line 39 - without Range Command to use if the variable does not have a range clause. line 40 - with prefield Command to use if the variable has a prefield trigger or a when clause. line 41 - without prefield Command to use if the variable does not have a prefield trigger or a when clause. line 42 - with valid Command to use if the variable has a valid clause. line 43 - without valid Command to use if the variable does not have a valid clause. line 44 - END-OF-FILE Required in file for no reason other than to allow the program to have some kind of check to make sure that this is a template file. Some descriptions examples: You will notice that in most of the lines in a template, the command is preceded by \. If the command for that line is the LAST command possible for the line, it should be preceded by \ otherwise it should not. In Skipjack, sj_ClrScr; is the last command to be printed on a line, so it is preceded by a \. sj_Box(... is not the last command for the line (the designation for double or single box comes after it) so it is NOT preceded by a \. sj_DoubleBox); is preceded by a \ since it is the last command on the line. When the two lines are taken together, the output will look like sj_Box(5, 5, 10, 15, sj_DoubleBox);. And the next command will start on the next line. The previous example shows that not all of a single command may be located on the same template line. That is why the \ is used. Also in Skipjack you will notice on line 13, the say date command looks like: &\sj_SayDate.... instead of like the say string command \sj_SayStr... The reason is that in SkipJack, the Date does not have a picture clause. Because it is not written with the exact same syntax as the SayStr command, the Alt picture clause was used. The template knows this because the line was preceded by &. In the range clause, you will notice that <> and <> are used instead of <>. The reason is because, usually the range is entered as: 1,11. In order to separate the string for Skipjack which prints them as: '1','11' the <> and <> were used. Why not just type in '1','11' during data entry within DBFSCR? Because now I can convert the screen to dbxl or clipper without having to redefine the object's information. Finally in Skipjack, you will notice that most of the Says and Gets have #. This is because Skipjack has a limited number of variable types that can be used. Obviously a function could be used to convert the variable before the Say or Get and then imbed the function in the command. For instance, if I created a function that would convert integers to reals and called it IntToReal, I could write the command for Say Int as: \sj_SayNum(<>, <>, IntToReal(<>), <>, <>,. But IntToReal was not included with SkipJack, so I chose not to create the template that way. In the dbase3 template, you will notice that the Says and Gets have the same commands. Even though the same command is used by the variables, they still must be listed for each variable type. Because it is the line in the file which is used by DBFSCR that determines the command to use. Also in dbase3, you will notice that the command for single box is: \ instead of # (dBASE does not have a SINGLE clause). The reason is that the command to draw the box @..TO was not preceded by a \ (it could not be because of the DOUBLE clause). If single box had a # then the next command printed would be on the same line as the @..To command: @ 2,5 TO 5,10 SET COLOR TO (assuming SET COLOR TO was the next command). By using the \, SET COLOR TO will start on the next line: @ 2,5 TO 5,10 SET COLOR TO ... Clipper users: The template is called Clipper5 because I have included the WHEN clause for GETs (ie. prefield trigger). To make this compatible with earlier versions of Clipper, just put a # on the line for prefield. Code Base 3 users: Code Base 3 does not come with a box command. I wrote a box command using s3 routines and included it in the file CBBOX.C. You can use this file or create your own. If you use your own box routine, change the commands (box, double, single) in the CodeBas3.tem file. If you do not want to use the box commands, replace the respective lines with a #. Code Base 4 users: You can modify the CodeBas3.tem file easily to work with your product. I do not have a list of function names, otherwise I would have done it myself. Code Base 3 and 4 users: One final note is required to explain the prefield in Codebas3. I use Code Base (not Code Base 4). While looking around, I noticed that the GET structure allows for a function to be assigned to a field called prepare, similar to the way a function can be assigned to valid using the g3valid function. In my Code Base library, I wrote a function similar to g3valid called g3prepare. This function assigns a function name to the GET structure under the prepare field. While in a read, Code Base looks for a function in prepare every time it enters a field. If that field has a function assigned, then the function will be called before the user is allowed to enter information. Prepare acts like a valid, but before hand (ie. prefield). This is good for things like help prompts and validation routines to determine if the field should be entered. I tested the function and it worked for me until I tried to nest reads. then I ran out of stack space. I am currently working on this problem. Because your library does not have the prepare function, you should put a # at the beginning of that line. I left the prepare in so that you would be aware of the capability. FINAL NOTES I have tested the software and found no bugs. But like any software, I know that I could not have found them all. Please alert me to any that you find. I will make any fixes as soon as I can and upload the changes. If you have any enhancements that you would like to see in the program, let me know. If I agree with the changes, I will add them as soon as possible. If you have any questions or comments, write to me at the address listed above, or, you can e-mail me on Compuserve. My account number is: 72007,624. I look forward to hearing from you.