XFOR Version 1.5 Gene Pizzetta December 1, 1991 XFOR a is ZCPR3 Extended FOR utility for searching and displaying "----" delimited file catalogs, including crunched files. The source DU and filename can be specified on the command line, parsed by the CPR for remote system safety. Alternately, an internally configured default directory and filename can be used. Highlighting and direct cursor addressing is used, if available. The error flag is set on error, or if a matching string is not found. XFOR responds to the "//" help option and can be re- invoked with the GO command. Optionally, a header for Bill Tishey's ZFILES.LST, for Nolan-type FOR files, or a custom header can be displayed. Output can be echoed to the printer. Numerous configuration options can be set with with ZCNFG. USAGE: XFOR {{dir}:{fn.ft}} {/options} {string{|string{|...}}} If no filespec is given, the internally configured drive/user and filename will be used. If a filespec is given on the command line, a colon must be included. If only a DU or DIR is given, the internal filename will be used. If only a filename is given, the internal DU will be used. As distributed, the internal DU is configured to default to the currently logged directory. OPTIONS: A leading slash is required. Options must follow the file specification, if one is given, and precede the search string. H Toggle header display on or off, depending on the configured default. A Use alternate header, the header not configured as the default. S Toggle inserting a blank line between entries, depending on the configured default. P Pause display when screen fills. This option will also suppress the "Do you want screen paging?" question, if XFOR has been configured to "ASK". N Suppress screen page pausing, which also suppresses variable screen page overlap. If a header is being displayed, it will appear only at the beginning of the listing. This option will also suppress the "Do you want screen paging?" question, if XFOR has been configured to "ASK". L Output will be echoed to the printer. If the wheel byte is off, however, printer echo is not available and the option will be ignored. Printer output echoes the matching entries only; no headers or other messages are sent to the printer and no formatting is done. Automatic screen paging is disabled if this option is given, although ^S will still work. V Suppress video highlighting. No highlighting will be used, even if available in the TCAP. STRING SEARCH: Leading spaces in the first search string on the command line are not significant. To make leading spaces significant, precede them with the "|" multiple string delimiter. This method allows looking for " REN" without finding "reference". Likewise, because the slash is used as an option list delimiter, a search string beginning with a slash could be misinterpreted by the parser. Looking for file entries beginning with a slash can be done reliably by preceding the slash with "|" or by a question mark. Search strings may include the following special characters: | separates multiple search strings. The "|" is equal to "OR"; that is, an entry will be found if it contains any of the given search strings. \ matches the beginning of a line. In a typical FOR file the only word at the beginning of a line is a filename, so this option can be used to avoid matching words in the file description. ? matches any single character, allowing primitive wildcard searches. XFOR was intended to allow operation through an alias so only one copy has to be on line, even if you want to be able to use it to search several catalogs. The program error flag is set if XFOR encounters any problems. The flag values correspond to those in Z34ERR.LIB (all values are below 14h), except that if no matching string is found, the flag is set to FFh. XFOR can be aborted at any time with ^C, ^K, ^X, C, K, or X. A header for Bill Tishey's ZFILES.LST can be displayed at the top of each screen page. You can make this header display the default, or you can use the command line options H and A, depending on your configuration. XFOR also provides a data area for a custom alternate header. If your TCAP allows, the header will be printed and maintained at the top of the screen; otherwise, it will be printed at the beginning of every screenful and scrolled up the screen. The header is only printed once if screen paging is disabled. As distributed, the alternate header is set up for "Nolan-type" FOR files. The alternate header can be changed using ZCNFG. Because it might be difficult to type in a long header in answer to ZCNFG's prompt, a patch file, XFHEADER.Z80, is provided to allow the creation of an alternate header to your specifications. After editing the file, assemble it to a HEX file and load it over XFOR using MLOAD or MYLOAD. EXAMPLES OF USE: XFOR A1:ZFILES.LST /H XFOR displays all entries in ZFILES.LST in directory A1, using the ZFILES header. XFOR XFOR displays all entries in the internally configured file in the default directory or in the internally configured directory. XFOR A1:ZFILES.LST /SN \REN XFOR will search ZFILES.LST in A1 for entries with filenames beginning with "REN", inserting a blank line between each entry and scrolling continuously. XFOR :ZFILES.LST REN XFOR will search ZFILES.LST in the default directory or in the internally configured directory for entries with a string containing "REN". The search is not case- sensitive. The colon before the filename is required. XFOR :ZFILES.LST /L REN Same as above, except output will also be echoed to the printer (if the wheel byte is on). If the wheel byte is off, the L option will be ignored. XFOR A1: | REN|\REN XFOR will search the internally configured file in A1 for an entry with a word beginning with "REN" or any filename beginning with "REN". XFOR A?M|M?C XFOR will search the internally configured file in the default or internally configured directory for entries containing "ASM", "AQM", "AZM", "MAC", "MQC", "MZC", etc. XFOR : C0: XFOR will search the internally configured file in the default directory or in the internally configured directory for entries containing "C0:". In this case the single colon is required so that XFOR will not think "C0:" is a DU specification. CONFIGURATION: XFOR has a large number of configuration options that can be changed using ZCNFG and the included XFORnn.CFG file. Do not change the name of the CFG file, so that ZCNFG will always be able to find it, even if you change the name of XFOR.COM. The ZCNFG help screens are an important aid to configuring XFOR to your liking, so read them carefully. VIDEO ATTRIBUTES: XFOR will run as distributed under any type of TCAP. Video attributes highlight the header display, if one is used, and the first line of each displayed file entries. Normally, the TCAP "standout" string will be used to set the attributes for the first line of each entry. If an extended TCAP is in memory, XFOR will attempt to display the header in reverse video. If reverse is not available, or if there is no extended TCAP, the standout string will be used for the header, also. If no attributes are available in the TCAP, XFOR will still work fine; the header will be marked by right and left brackets at each end. The attributes used for display of the header and the first lines of entries are configurable. RAS OPERATION: Sysops who cannot store TCAP information for individual users can eliminate the terminal dependencies of highlighting, reverse video, and clearing the screen by making sure those bytes are null in the generic TCAP, or they can be eliminated through a configuration option. The routines in XFOR will not send the strings if they are not there, so the screen will merely scroll. In fact, by using a null TCAP and changing some options with ZCNFG, XFOR can be made to operate in the same manner as earlier FOR utilities, although that would eliminate some desirable enhancements. If XFOR is called with a filename parameter from an alias or from the command line, the filename is parsed by the CPR, which for safety reasons does not allow access to a directory above the maximum DU or to a drive excluded by the drive vector in the environment. To access a directory outside these limits, configure it into the internal DU specification. If the command line filename parameter begins with a colon, the internal DU specification will be used. If the wheel is off, XFOR will exclude the filespec and options parameters from the usage screen display, under the assumption that either the internally configured filename or an alias will always be used and that the options should not be under the control of the remote user. In addition, a few usage examples will be displayed. The theory for the latter is that experienced users want only a reminder of the syntax, but RAS users may need more information. Printer output is disabled if the wheel byte is reset (off). The other options are still available, even though they are not displayed on the help screen. If options are included in aliases that call XFOR, then options will not be available to remote users from the command line (XFOR will only find the first set of options). If no options are to be included in the alias script, inserting a single slash with no options following it will have the same effect. Sysops will probably want to set the paging option to ASK, so users can request no paging if they are reading the FOR file into their text buffer. Paging for most users is almost mandatory, however. As distributed XFOR does not leave a blank line between entries. Since the first line of each entry is highlighted, the display is readable and many more entries can be displayed. Some people may prefer less clutter, however, so XFOR can be configured to insert a blank line by default. The blank line may be even more desirable if highlighting is not supported. XFOR requires a TPA of about 38 kilobytes in order to uncrunch files. It will operate in a much smaller space, however, if uncrunching is not required. XFOR FILE FORMAT: Most FOR files separate entries with a series of four hyphens ("----"). Actually, any hyphen in the first column is considered an entry separator. Entries can be longer than a screen, but a single entry longer than about 8K will cause XFOR to abort with an "incorrect format" message. HISTORY: This utility is a result of the collective ideas and complaints of the group that hangs around Jay Sage's Newton Centre Z-Node. The idea for an enhanced FOR came from Chris McEwen, who runs the Socrates Z-Node. Bill Tishey reformatted his ZFILES.LST so it could be read by FOR and offered several good ideas. Jay Sage gave valuable advice on command line syntax. Bob Dean was a well-spring of suggestions. They, and Howard Schwartz, offered criticism and support that resulted in a much better utility. Thanks to you all. Version 1.5 -- December 1, 1991 -- Gene Pizzetta One small operational change: Now prints "[searching]" only if a search string is given. Other minor changes: uses ZSLIB GCOMNAM instead of Z3LIB PRTNAME to more reliably obtain program's name, and uses ZSLIB EATSPC and EATNSPC to save a few bytes. Version 1.4 -- November 10, 1991 -- Gene Pizzetta Finally implemented a couple of suggestions made months ago. Bob Dean wanted a "searching" message so the user would know something was happening while XFOR was looking for a match, so it's here. Bill Tishey wanted to be able to search crunched files, so that's here also. Unfortunately, neither KMD nor ZMD can handle crunched files, but this XFOR feature could be useful for extended FOR file listings and for Bill Tishey's ZFILES.LST. About 38 kilobytes of TPA is required for uncrunching. "Nolan" FOR file header now built-in as alternate header. Version 1.3 -- April 7, 1991 -- Gene Pizzetta A problem with previous versions was the mixing of console input and output via BDOS and BIOS. That problem has been solved by Adding a TABIT routine to expand tabs in the FOR file and eliminate the use of the SYSLIB BOUT routine. All console I/O is now via the BIOS. Version 1.2 -- December 23, 1990 -- Gene Pizzetta Changed command line syntax at the request of Jay Sage: Now an option list, preceded by a slash, can be included in the command line, just before the match string. Options are: H=display header; A=use alternate header; S=double-space between entries; L=echo to printer (LST); V=turn off all screen attributes; P=use screen paging; and N=no screen paging. The last two will suppress the paging "ASK" configuration option. The L option will suppress screen paging. Version 1.1 -- December 18, 1990 -- Gene Pizzetta Added CR, LF after paging question. At the suggestion of Al Hawley, now uses BOUT instead of COUT in print loop, so tabs are expanded. Added printer output and "+" command line option (must be last token, preceded by a space). Made video attributes used for header and first line of entry configurable options. Version 1.0 -- December 15, 1990 -- Gene Pizzetta Variable screen overlap and clearing screen before each page are now configurable options. Changed method of making leading spaces significant; now requires "|" at beginning of match string if leading spaces are to be significant. Uses direct cursor addressing and clear-to-end-of-screen string, if available and if header is being displayed. Fixed bug found by Bill Tishey that in some cases caused highlighting not to be properly terminated on his Apple II+ (STNDEND must be called before sending a linefeed on that machine). Fixed bug reported by Bob Dean that sent the program into never- never-land if the Kaypro 4/10 TCAP from Z3TCAP27 was used. (This was actually a bug in the SETATR routine in VLIB versions 42 and 43, but I have compensated for it.) Source filename parameter omitted from syntax message for non- wheels, unless configured to always be omitted. And, finally, documentation. Version 0.2 -- December 8, 1990 -- Gene Pizzetta A second beta release. Name changed to XFOR to avoid conflict with ZMD utilities, as suggested by Jay Sage and Chris McEwen. Can be configured to page or not page output, or to ask the user which he wants. No longer responds to quiet flag, but quiet configuration still works. Highlights first line of each entry if available from TCAP, as suggested by Chris McEwen. Uses reverse video for header line, if available. Sets correct Z34 error codes in program error flag, except no string match is FFh. Configurable to allow blank line between entries or not if you want more entries on screen, per suggestion by Bob Dean and Bill Tishey. Satisfies Bob's suggestion for an additional header type by providing for an additional roll-your-own header. Leading spaces now significant in search string. Adopted Jay Sage's suggested command line syntax: if there's a colon in the first token, it's a filename; otherwise, use the internal filename. In addition, XFOR will use the internal filename if the colon is not followed by one, and will use the internal DU if the colon is not preceded by one. Now properly handles entries more than a screen- length. Entry buffer now handles single entries of up to 8K. Version 0.1 -- December 2, 1990 -- Gene Pizzetta A beta release, based on Carson Wilson's FORZ 1.0 (8/5/87), which was a revised disassembly of Irv Hoff's FOR.COM. Sets the ZCPR program error flag if a matching string is not found. The "end of listing" and "aborted" messages suppressed if ZCPR quiet flag is set or if configured to default to quiet mode. Responds to "//" help option on command line. Re-initializes its data buffers so it can be re-invoked with GO command. Added command line source file specification. If no DU or DIR spec is given, an internally configured default directory is used or, if not configured, the current logged directory. If no command tail is given, defaults to configured internal filename. If reading an improperly formatted file, FORZ kept adding to the OutBuf until it overwrote the system. ZFOR instead aborts with an error message. Configurable with ZCNFG. Please report bugs and suggestions to: Gene Pizzetta 481 Revere St. Revere, MA 02151 Voice: (617) 284-0891 Newton Centre Z-Node: (617) 965-7259 Ladera Z-Node Central: (213) 670-9465