TEXT2DB is a Z-system tool that takes most of the drudgery out of generating MENU and HELP screens in Z80 assembly language programs. TEXT2DB reads bytes from an ASCII text Input File (INFILE) and sends them to an Output File (OUTFILE) reformatted as data statements suitable for input to an assembler. Certain control characters are recognized and replaced in the output file with a symbol. SYNTAX: TEXT2DB [DIR:]INFILE[.TXT] [OUTFILE[.DB]] [/o] Note: OUTFILE is always written to the same DIR: as INFILE. OPTIONS: Saaa - Set 3 character alpha prefix for synthetic labels. Snnn - Set starting label number [0..255] Saaannn - Set both alpha prefix and starting label number. TEXT2DB is a 'filter' type program which reads text from an input file, modifies it, and writes it to an output file. The modification in this case is replacement of control characters with appropriate mnemonics and insertion of punctuation and assembly mnemonics to create lines of assembly code. For example, the input lines This is line one, and this is line two. would be converted to: db tab,'This is line one,',CR,LF db tab,'and this is line two.',CR,LF Why would one want to do something so simple? The answer, of course, is that you wouldn't bother with a special program for a case this simple. But suppose you wish to make a series of formatted HELP screens (or even one!). You will spend hours getting the spacing and line lengths right by re-doing (and reassembling) the DB statements. With TEXT2DB, you just use your text editor (Document mode if it's WordStar) to make the screen. When it meets your requirements, just run TEXT2DB on it. The resulting file of DB statements can then be edited into the assembly source file (or included with an INCLUDE statement, depending on your assembler). That is a simple case. More tedious yet is the preparation of a MENU screen which includes fields that get changed while the program is running. In this case, you will need a label at each appropriate place in the list of DB statements. In addition, the labeled DB statement must contain as its first data the field to be changed. Again, you can do this manually. All you have to do is re-edit the file of DB statements. For example, db tab,'This is line ' label1: db 'one,',CR,LF db tab,'and this is line ' label2: db 'two.',CR,LF is equivalent to the original example. Now, however, the program can change the contents of the data fields 'one,' and 'two.' by using the labels to reference them. TEXT2DB can also handle this labeling chore! The menus used with ZCNFG to alter TEXT2DB use this strategy; the screen data for them was generated with TEXT2DB. TEXT2DB must have some way of knowing where to put the labels, and how to generate them so that they will not conflict with other labels in the final assembly source file you are working on. The location of labels is indicated in the input text file by a 'trigger' character which YOU include in the text. The default character used is the accent character, "`" (60H). The original example, marked this way to indicate the location of labels is: This is line `one, and this is line `two. The character used as a trigger is configurable, using ZCNFG. If the ` is not suitable, you may select another character that is unlikely to be a part of the input text. If the character MUST be included in the text (and not treated as a trigger), simply type it twice. `` will be recognized as a ` to be included in the output without causing a label to be generated. i.e. the trigger character acts as its own 'escape' character. The labels inserted in the output file are called Synthetic Labels, and are generated by TEXT2DB from an initial 6 character template. The label is initially Aaannn, where the 'A' stands for an Alphabetic character, and the 'aa' stands for 2 alpha-numeric characters and the 'nnn' stands for 3 decimal digits. Each time a label is used, the 'nnn' part is incremented so that the next label will be (systematically) unique. The default first label is SCR000:. You may, with ZCNFG, change this default as you wish within the above guidelines. There is currently one command line option - /SAaannn . The option letter (S) is required but is not part of the first label specification. Both parts are optional; /SAaa and /Snnn are quite acceptable and assign the Alpha and numeric portions of the first label. 'A' may be a space, but will be changed to a period (.) since assemblers do not like spaces in labels. The numeric portion is terminated by a space; 'n' or 'nn' are quite acceptable and will be filled with leading zeros in the synthetic label. The length of the DB statements in the output file is controlled by three considerations: 1) Human readability - will it fit on your screen or printer page, and don't fold lines in the middle of a word(!). 2) Assembler limitations - there is usually some limit to the length of an input line for the assembler. 3) Synthetic labels - clearly, assembler syntax requires that a label be on a new line. Thus, a break in the text must occur where indicated by the trigger character. The Nominal line length (default is 50 characters) and the Maximum line length apply to the first two considerations. Both are configurable with ZCNFG. The line is folded (terminated, and a new line started) on the first space encountered beyond the nominal line length value. If no spaces occur, then the line is unconditionally folded when it reaches the Maximum length. The Maximum line length is usually set to a larger value than the Nominal line length. Its default value is 128 characters, consistent with wide carriage printers and most assemblers. One of the configuration options is a choice between folding the output line Before/After the next space. This is a format option that is up to you. If After is chosen, then the space will be at the END of the folded line; if Before then the space will be the first character in the next line of data. Before closing the output file, one final DB statement is added to it by TEXT2DB - a statement whose data is a string terminator: DB 0 The default argument is, as shown, binary zero. This assumes your program is written to process null-terminated strings. This argument is configurable with ZCNFG; a popular alternate (used with BDOS function 9) is '$'. Note that the enclosing quotes must be included when using ZCNFG to specify this value. The configuration value you supply becomes the literal argument to the DB statement and must follow the syntax rules of your assembler. CONFIGURATION OF TEXT2DB You will probably try TEXT2DB without bothering with configuration. OK, but THEN go through the configuration! You don't have to change anything unless you want to, but the configuration will introduce you to all the things you CAN change easily; and the help screens associated with each menu give further insight into what these parameters can do for you. It's the next best thing to a formal ZCPR3 style HELP file. Put the following files in the same directory. TEXT2DB.COM (or whatever you renamed it to) TEXT2DB.CFG (DON'T change the name of this one!) ZCNFG.COM Then start the configuration session with: ZCNFG TEXT2DB (or whatever you renamed it to) Obviously, ZCNFG need only be on your ZCPR search path. The CFG file may also be in a remote directory; just add the argument DIR:TEXT2DB to the last command line and let ZCNFG find it. The full syntax of a ZCNFG command line is given in ZCNFG's help screen and documentation.