CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / jsage / zsus / z3help / x.lbr / XFOR.HZP / XFOR.HLP

Wrap

Text File | 1991-11-18 | 18.1 KB | 351 lines

; XFOR.COM Size (recs) CRC Version Author/Latest Issue Disk 6k (41) 4C28 1.40 Gene Pizzetta 11/91 Z3COM27 1- Usage 2- Config 3- RAS Opn 4- File Format 5- Notes 6- Examples XFOR is a 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, XFOR can display a header for Bill Tishey's ZFILES.LST, or a custom header can be displayed. Output can be echoed to the printer. Numer- ous configuration options can be set with with ZCNFG. :1 Syntax 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 for the currently logged directory. Options A leading slash is required. Options must follow the file specification, if one is given, and preced 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". Options - 2/2 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 format- ting 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 - 1/3 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. String Search 2/3 ? 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. String Search - 3/3 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. A patch file, XFHEADER.Z80 is provided to allow the creation of the alternate header, which is then assembled to a HEX file and loaded over the COM file using MLOAD or MYLOAD. If the 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 diffi- cult 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. :2 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 your 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. :3 RAS Operation - 1/3 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. RAS Operation - 2/3 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 informa- tion. 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 merely reading the FOR file into their text buffer. Paging for many users is almost mandatory, however. RAS Operation - 3/3 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. :4 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. :5 XFOR Notes - 1/5 a. 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. b. Vs 1.4 updates (11/10/91, 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. XFOR Notes - 2/5 b. Vs 1.3 updates (4/7/91, 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. c. Vs 1.2 updates (12/23/90, 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 alter- nate 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" configura- tion option. The L option will suppress screen paging. d. Vs 1.1 updates (12/18/90, Gene Pizzetta): - Added CR, LF after paging question. - 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). XFOR Notes - 3/5 - Made video attributes used for header and first line of entry config- urable options. e. Vs 1.0 updates (12/15/90, 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 that in some cases caused highlighting not to be properly terminated on an Apple II+ (STNDEND must be called before sending a linefeed on that machine). - Fixed bug 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. XFOR Notes - 4/5 f. Vs 0.2 updates (12/8/90, Gene Pizzetta): - A second beta release. Name changed to XFOR to avoid conflict with ZMD utilities. - 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. - 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. - 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 file- name. 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. XFOR Notes - 5/5 - Now properly handles entries more than a screen-length. - Entry buffer now handles single entries of up to 8K. g. Vs 0.1 updates (12/2/90, 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 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. :6 Examples of Use - 1/3 a. XFOR A1:ZFILES.LST /H XFOR displays all entries in ZFILES.LST in A1, using the ZFILES header. b. XFOR XFOR displays all entries in the internally configured file in the default directory or in the internally configured directory. c. 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. d. 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. Examples of Use - 2/3 e. 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. f. 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". g. XFOR A?M|M?C XFOR will search the internally configured file in the default directory or in the internally configured directory for entries containing "ASM", "AQM", "AZM", "MAC", "MQC", "MZC", etc. Examples of Use - 3/3 h. 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.