Black Box 4

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

/ Black Box 4 / BlackBox.cdr / editors / trw110.arj / REPORTER.DOC < prev next >

Wrap

Text File | 1991-05-28 | 28KB | 510 lines

----------------------------- Program Information ------------------------------ Program : Text Report Writer & DefMaker Utility (ShareWare) Version : v1.1 Release Date : 06/01/91 Registration : $20.00 Latest version and removal of header messages. Author : John Leschak 6625 Dorchester Road, #226 Charleston, South Carolina 29418 803-552-0885 Included Files: REPORTER.EXE Executable program REPORTER.DEF Basic report definition file. REPORTER.DOC Documention SAMPLE.DEF Sample report definition file SAMPLE.DAT Sample test data. SAMPLE.BAT Batch file to run sample report. DEFMAKER.EXE Report definition file generator. ** The file DEFMAKER.EXE has been compressed with PKLite, if there is a problem with this, you may decompress if need be. ------------------------------ Program Description ----------------------------- I wrote this program because I cound not find an easy and flexible utility to assist in converting the layout of fixed length ASCII files and offer simple reporting capabilities. It was also desirable for me that the program use DOS' redirection to allow for maximum control, simplicity and flexibility. Also included is the support of delimited files and BASIC format files. If you work a lot with text files, you should find this utility most useful. I welcome your comments and support with open arms. In my opinion, this program contains great potential for a general utility. You may have the impression that a spreadsheet or good text editor may be more better suited for this type of text manipulation, well..you are correct, you will be able to achieve greater flexibility for sorts and formatting, but the cost is generally high memory overhead. As the the goal here was to make a general purpose utility, you will find that a user interface is virtually non-existent, nor do I have any plans to include one in future releases. I have included a simple utility with a reasonibly good user-interface to create report definition files. Although this utility isn't flawless, it takes a lot of the guesswork out of trying to figure out which field specification go with what field types. --------------------------------- Program Usage -------------------------------- In order to use this program, you should be familiar with DOS' redirection capabilities, as the program is useless without them. For a quick idea of what the program actually does, run the SAMPLE.BAT batch file for a VERY simple demonstration. Installation: The only files required to run the program are REPORTER.EXE and a report definition file (see the example in REPORTER.DEF). Copy these files to your favorite directory, preferable one that is in your DOS path. The report definition files (.DEF) should be located in the directory which contains your data. You may optionally add a line to you AUTOEXEC.BAT file to set the location of the default directory to look for the report definition file. This is generally not a good idea for this application, since data files are usually store in many directories on your hard disk, but nevertheless, it is supported. Example: SET RPT=C:\UTILS Execution: To run the program you must first have some fixed length or delimited file to use as input into the program and you must have also created a report definition file which maps the output fields to that of you input file. Sample Data: Below is a general description of an input file and some possible data it might contain: Description Start Length ----------- ----- ------ NAME 1 20 PHONE 21 7 AGE 28 3 SALARY 31 8 which may look like this internally (kind of hard to read?): LESCHAK, JOHN 552088526 99999.00 DOE, JOHN 123456756 123.21 DOE, JANE 123456755 1233.21 ALBERTSON, MITCH 555121210954000.00 Suppose you had already created a report definition file called SAMPLE.DEF and you wanted to generate a report sent to the screen using the above file called SAMPLE.DAT as input. To do this you would type the following at the DOS prompt: TYPE SAMPLE.DAT | REPORTER SAMPLE.DEF | MORE If you wanted the output to be sent to a file, type the following at the DOS prompt: TYPE SAMPLE.DAT | REPORTER SAMPLE.DEF > SAMPLE.OUT If you wanted the output to be sent to the printer, type the following at the DOS prompt: TYPE SAMPLE.DAT | REPORTER SAMPLE.DEF > PRN Note that if you have not set a path for the report definition file in your AUTOEXEC.BAT, you must specify a full path name or have the report definition file in the current directory. If you have set a path for the report definition file in you AUTOEXEC.BAT, then only a filename can be entered on the command line. If no report definition file is specified, then it will default to REPORTER.DEF. Although at this point, its capabilities seem kind of limited, but as you learn more about DOS' redirection and read the following on writing your own report definition files, you will see that the possibilites are great. For a sample report, run SAMPLE.BAT at the DOS prompt. ----------------------------- Report Defintion File ---------------------------- Report definition files are used to map your output fields to your input. All report definition files are completely ASCII text and can be created with your favorite editor. Total field length for a report cannot exceed 255 characters. A report definition file contains groups or sections: [REPORT] Report definition header with comments following on the lines below. Must be the first line in file. this header group is required. [FORMAT] General page formatting options which include field spacing, page headers, form feeds, page length, and character conversion to uppercase. This group is optional. [FIELD] List of output fields and their mapping to input. Also include field characteristics and output specs. This group is required. [FILTER] List of field selection criteria for output. Allows user to specify range of output for any defined field in the [Field] group. [REPORT] Group The [Report] group is used to identify a report definition file and for the user to enter comments about the report. All comments will be ignored. The [Report] group heading must be the first line in the report definition file, or an error will occur. [FORMAT] Group The [Format] Group is used to set page formatting options. This section is optional and will fall to the default options if omitted. Available formatting options can be entered in any order and in any case. Options are as follows: FIELDSPACE=nn Spacing between fields, where nn must be between 0 and 99. Defaults to 2. PAGELENGTH=nn Number of lines per page, where nn must be between 10 and 256 or else 0. A page length of 0 indicates no page breaking will occur. If headings are not suppressed then headings will appear at the beginning of outpu only. If form feeds are enabled then a form feed character will be sent at the end of each page. Defaults to 0. SENDFF=YES SENDFF=NO Indicates whether or not a form feed character will be sent after each page break. If the page length is set to 0, then a form feed will be sent only at the end of the report. Defaults to NO. UPPERCASE=YES UPPERCASE=NO Indicates whether or not all input characters will be converted to upper case. Headings, field headers and field constants will not be converted. Defaults to NO. REMOVEBLANKS=YES REMOVEBLANKS=NO Indicates whether or not blank input lines should be removed from output. Defaults to YES. REMOVEDUPS=YES REMOVEDUPS=NO Indicates whether or not duplicate field values will be output. If enabled, then only the first output field value for the series of duplicate output field values will be output. Numeric duplicate fields will not be removed, only string type duplicate fields. Defaults to YES. SUPRESSHEADING=YES SUPRESSHEADING=NO Indicates whether or not page and field headings will be suppressed from output. If form feed is enabled, then a form feed will still be sent at the end of each page. Defaults to NO. FILEFORMAT=FIXED FILEFORMAT=BASIC FILEFORMAT=DELIM Indicates the format of the input. Types supported are fixed length files (FIXED), delimited files, and BASIC format files BASIC). BASIC format files are a special type of delimited file, with strings surrounded by double quotes and fields seperated by commas (there is also a header on the first line). When using either BASIC or delimited files, you should replace the <size> field specification in the [Field] group with the logical field number (i.e. 1 = first field, 2 = second field, etc...). Defaults to FIXED. DELIMCHAR=x This is the delimiting character used when the file format type is delimited to indicate field seperation. You may specify only 1 delimiting character. If no delimiting character is entered after DELIMCHAR=, then this will signify that a space (' ') is to be used as the delimiter. Defaults to , (a comma). DELIMQUOTE=x This is the character used when the file format type is delimited to indicate string values. You must specify only 1 delimiting quote character following the DELIMQUOTE=. Defaults to " (a double quote). HEADING= text Single line report heading to appear at the top of all pages if supress headings is disabled. The text to be used for the heading must begin in column 10 and may contain embedded spaces. Defaults to blank. [FIELD] Group The [Field] group is used to map you output fields to you input. There are three types of fields: string, numeric, and constants. Field specifications may be seperated by a space (' '), an equal sign ('=') or a pipe ('|'). Sorting occurs in the order in which the fields occur in the report definition file. Currently there is no support for sorting in ascending order but will be included in future versions. You can create as many fields as you need, you are restricted only by available memory. All fields begin with a field label which is used as a field heading when supress headings is disabled. Field labels do not need to be unique (although future versions may require this) and should not contain embedded spaces. Field labels are limited to 15 characters and are case sensitive. The following is a list of the format used for each field type: STRING field <label> = <start> <length> <size> <just> STRING GROUP <label> Field heading. Required. <start> Starting character position of field in input file. Required. <length> Length of input field. Number of characters to be read beginning from the <start> position. Length must be between 1 and 255. Required. <size> Output field size. If size is less then the size of the <label> then the label will be truncated. Size must be between 1 and 255. For delimited or BASIC format files, the size should be changed to the logical field number (i.e. 1 = first field, 2 = second field, etc.). Required. <just> Field justification, either RIGHT or LEFT. Required. STRING Indicates this is a string type field. Required. GROUP Optional specification, indicates whether or not sub-totals should be output when this value changes. if send form feed is enabled, then a a form feed will be sent after the sub-totals and a new page header will be output. This field is ignored if suppress headings is enabled. NUMERIC field <label> = <start> <length> <size> <just> NUMERIC <places> TOTAL or <label> = <start> <length> <mask> <just> NUMERIC <places> TOTAL <label> Field heading. Required. <start> Starting character position of field in input file. Required. <length> Length of input field. Number of characters to be read beginning from the <start> position. Required. <size> Output field size. If size is less then the size of the <label> then the label will be truncated. <size> may be replaced by the <mask> field specification, but one of them is required. Size must be between 1 and 255. For delimited or BASIC format files, the size should be changed to the logical field number (i.e. 1 = first field, 2 = second field, etc.). <mask> Formatting string to specify layout of output field. The <size> of the field will be the length of the mask. If a mask is entered then <places> is ignored but must be present. <mask> may be replaced by the <size> field, but one of them is required. A mask should not contain embedded spaces and should not exceed 25 characters, valid mask characters are: @ = lead zeros, needed once $ = float dollar sign, needed once * = blank space filler # = digit placement . = decimal point location , = comma seperators - = display minus sign only + = display minus or plus sign} <just> Field justification, either RIGHT or LEFT. Required. NUMERIC Indicates this is a string type field. Required. <places> Number of decimal places to be output. No rounding will occur. This will be ignored if a <mask> was entered. Places must be between 0 and 5 Required. TOTAL Optional specification, if present field will have totals at tail of output. This is ignored if supress headings is enabled. CONSTANT field <label> = 0 <text> <size> <just> NOSPACE <label> Field heading. Required. 0 A zero starting position indicates that this field is a constant field. Required. <text> Value of constant, will be treated as a string. If text is longer then the size of the field, then the text will be truncated. Text should no exceed 25 characters. Required. <size> Output field size. If size is less then the size of the <label> then the label will be truncated. Size must be between 1 and 255. Required. <just> Field justification, either RIGHT or LEFT. Required. NOSPACE Optional specification, if present no field seperators will appear either before or after this constant. [FILTER] Group The [Filter] group is used to restrict output to input records which fall within the specified field ranges. Before a filter can be created for a field, you must have previously defined that field in the [Field] group. This group is optional. You can create a field filter for string type and numeric type fields, but not for constant type fields. For string type filters, the input and filter values are always converted to upper case before comparison. any filter created for a constant field, will be ignored. You can create as many filters as you need, you are limited only by memory. If there are duplicate field labels for fields defined in the [Field] group, then the filter will be assigned to the first occurence of the field label identifier. Each field label can have at most two filters, one to set the lowest allowed value, and one to set the highest allowed value. It is not required that both of these be present, as you are allowed to set only the lowest allowed value or just the highest allowed value. Both string type filters and numeric type filters use the same general format. The following is a list of the format used for field filters: STRING filters <label> = LOWEST <text> <label> = HIGHEST <text> <label> Field label if a previously defined field created in the [Field] group. Labels are case sensitive. Required. LOWEST Indicate that this filter is to be used as the lowest allowed input value for the specified field. Required. HIGHEST Indicates that this filter is to be used as the highest allowed input value for the specified field. Required. <text> Text string to compare input to, no wild cards are currently supported. This specification may contain embedded spaces. This is not required, and will be taken as a blank string if not present. The text can be no longer than 40 characters, leading spaces will be removed. NUMERIC filters <label> = LOWEST <value> <label> = HIGHEST <value> <label> Field label if a previously defined field created in the [Field] group. Labels are case sensitive. Required. LOWEST Indicate that this filter is to be used as the lowest allowed input value for the specified field. Required. HIGHEST Indicates that this filter is to be used as the highest allowed input value for the specified field. Required. <value> Value to be compare input to. If this field is omitted, then the value will default to 0.0. Embedded spaces are not allowed, but you may use a leading dollar sign ('$'), leading or trailing positive or negative sign ('+','-'), embedded commas (',') or leading zeros ('0'). ------------------------------------ DefMaker ---------------------------------- To assist in writing report definition files, I have included a small utility which will generate this file and also a simple batch file which will redirect output to printer PRN. The utility is called DefMaker (for a lack of a better word). The DefMaker utility is very easy to use and needs only minor instruction. When you start the utility, a menu will appear on the top line of the screen with four (4) menu options: Formats, Fields, Filters and Create (very similar to the report definition file structure..hmmm). For descriptions of field meanings, see the documentation above on Report Definition Files for more information. A context sensitive help utility will be included in future releases. To create or modify a report file: 1) First create a new report format by selecting the Format menu option. To add a new report format, press the INSERT key. If this is your first report format added, you will automatically be forwarded to the update screen and are ready to enter in the format options for the new report definition file. If you are modifying an existing report format, use the arrow keys to highlight the desired report format and press the ENTER key. You must complete this step before you will be allowed to enter fields and filters. Although you will have to enter a response for all options, only the applicable option specifications for the indicated file format will be used in the final report definition file. Note that if you change the file name of the report format, you will lose the link to all fields and filters tied to that report format. 2) After you have created the format in step #1, you can move on to create the fields which will appear in your report. Select the Fields menu option and select the report format which you wish to add the fields to. To select a report format, use the arrow keys to move the highlighted bar to the desired report format and press the ENTER key. If this is the first field being added, you will automatically be forwarded to adding a new field. If there are already existing fields for the report format, you may either modify an existing one by pressing ENTER after highlighting the desired field, or you may add a new field by pressing the INSERT key. For the most part, you will be forced to enter valid field specifications for all those which are applicable to the specified field type. If a field specification does not apply to the indicated field type, you may either leave that specification alone or change it (either way it will be ignored when creating the report definition file). To delete and existing report file: 1) Deleting an existing report file is similar to adding one. The only difference is that you must first delete all fields and filters before you delete the report format. To delete fields, filters and formats, you can simply press the DELETE key while the highlighted bar is on the desired field, filter or format (you will be promted to confirm the deletion). To create the report definition file: 1) To create the report definition file, select the Create menu option and select the report format which a report definition file and simple batch file is to be created. While the files are being created, the highlighted bar will disappear and reappear when the files have been created. If you hear a beep while the file is being created, then there was an error creating the report definition file. If this error occurs, it is because a file existing in the current directory with the file name the same as that specified in the report format, (i.e. a file with no extension and file names the same). When a report definition file is created it creates a temporary work file with a name that of that specified in the report format, with no extension, and after the file is generated it copies that file into a .DEF file of the same name and deletes the file with no extension. Well...anyway, general rule is try to assign an extension to all of the files in the report directory and you shouldn't have any problem. --------------------------------- Revision Notes ------------------------------- v1.0 Initial Release. v1.1 Addition of REMOVEDUPS in [Format] group. Addition of GROUP field specification for string types in [Field] group. Addition of sub-totals for numeric fields upon GROUP break. Addition of selection filter and the [Filter] group. Addition of DefMaker utility to create .DEF files.