7.4 Defining the file type
Quick Reference
To define a report file, type:
filedef filename[=pathname] report [len=rec_len]
To define a data file, type:
filedef filename[=pathname] data [len=rec_len]
To define a print file, type:
filedef filename[=pathname] print [mpa][mpd][mpe][len=n][norule][noser][$text$]
where mpa, mpd and mpe indicate that multipunches should be printed across the page, down the page, or as an asterisk and then listed below the record.
All files named on write and report statements must be defined by a filedef statement before they are used. This tells Quantum whether the file is a report, print or data file, and defines more specifically how the output should be written. So that you can be sure that all filenames will be recognized, you are advised to place all filedef statement at the beginning of the edit.
For report files, the definition is:
filedef filename[=pathname] report [len=rec_len]
where filename is the name of the report file and report is a mandatory keyword indicating that the file is a report file.
✎
If you are writing out more than 200 characters to a report file, you need to set len= on the filedef statement to more than 200 to ensure that no lines are truncated.Quantum normally creates report files in the main project directory. If you want the report file to be created in a different directory, follow the filename with =pathname. When specifying a pathname, the filename acts as a short-hand reference (tag). This means that you still have to tell Quantum the filename by appending it to the pathname.
For example, to declare a report file called repfile1 that is to be created in the directory /home/ben, you would write:
filedef repfile1=/home/ben/repfile1 report
✎
The maximum length for filename is set at 31 characters.For data files, the file definition statement is:
filedef filename[=pathname] data [len=rec_len]
where filename is the name of the output file and data is a mandatory keyword indicating that the named file is a data file. As with report files you may use the optional =pathname parameter to name the directory in which the data file should be created.
All records written to data files are as long as the record length defined with reclen on the struct statement. If you wish to change this, add the option len=reclen to the filedef statement, thus:
filedef newdat1 data len=80
This example says that records written to the data file newdat1 must be 80 columns long.
The file definition statement for print files is:
filedef filename[=pathname] print options
where filename is the name of the print file with an optional pathname, print is a mandatory keyword indicating that the file is a printout file, and options is a list of optional keywords defining more specifically how the records should be written. Filename lengths are as described above for data files.
The options are:
The default output file is a print file called out2, and the default output style is as described above.
To change the output style for this (for example, to suppress the ruler or print multicodes in a different format), simply use a filedef statement naming this file and giving the appropriate options from the list above:
filedef out2 print norule mpe
len=n Length of output record if different from reclen= on the struct statement.
$text$ Heading text to be printed at the top of each page.
mpa Prints the codes in a multicode across the page enclosed in curly brackets. For example:
000401 635495{134}45111
Here, we have a multicode of ‘134’. The ruler is of little use when multicodes are printed in this manner, so you may prefer to suppress it with the option norule.
mpd Prints the codes in a multicode down the page, thus:
----+----1----+----2 000401 635495145111
3 4
mpe Prints multicodes as an asterisk, but lists the individual codes within each multicode beneath the record. For example:
----+----1----+----2 000401 635495*45111
Column 14 contains codes 134 norule Turns off the ruler.
noser Prevents the messages ‘Record nnn’ and ‘n in File’ from being printed.
7.5 Default print parameters for write statements
Quick Reference
To define default print parameters for write statements, type:
ident[±] [$text$] [,variable_name] [,variable_name, …]
Any number of texts, variable names and fields are allowed. Items are printed in the order they are listed.
To turn off ident defaults and return to the standard write behavior, type:
noident
The ident statement gives you increased control over the content of the print file by allowing you to print more than one field of columns and one text per write statement.
The format of this statement is:
ident[±] [$text$] [,variable_name] [,variable_name, …]
Each ident statement may contain any number of texts, variable names and columns as long as each one is separated from the others by a comma. The order in which you define items with this statement controls the order in which they will be printed. For example, if you type:
ident $bad film code$, c(1,10)
if (films0 .gt. 0) write $check c(1,6)$
and Quantum finds a record which fails this test, it will print the following:
bad film code
Column c(1,10) is |----+----|
040506
check c(1,6)
Notice that the text defined with ident does not replace the text given with write. If you do not define a message on the write statement, Quantum will print the complete statement as it usually does.
In this example there is not much difference between using ident and writing the test as:
if (films0 .gt. 0) write c(1,10) $bad film code - check c(1,6)$
The real power comes when you want to write out more than one field and/or text per write statement, or if you want to write out the values of data, integer or real variables. For example, if you type:
ident t1, t2, t3 write
Quantum will write messages of the form:
t(1) is 10 t(2) is 15 t(3) is 20
in the print file (the values reported will, of course, be the values of the variables as they are in your run).
✎
In ident statements you can refer to a field of adjacent entries in a data variable array by specifying the first and last entries. For example, you can specify c(1,12) to refer to columns 1 through 12 of the C array. However, like most other Quantum statements, you cannot use this syntax for other types of variable, such as integer arrays.So the example above must be specified as:
ident t1, t2, t3 and not as:
ident t(1,3)
You can combine texts, columns and variable names. The statements:
ident $Bad film code$, c(1,10), films0, films1, films2, films3 if (films0 .gt. 0) write
might print:
Bad film code
Column c(1,10) is |----+----|
010209
if (films0 .gt. 0) write films(0) is 1
films(1) is 1 films(2) is 1 films(3) is 0
You could use this type of output for checking records which may be incorrectly coded for use with field and bit statements.
☞
For information about field, see section 8.6, ‘Reading numeric codes into an array’.For information about bit, see section 4.4, ‘Responses with numeric codes: bit’ in the Quantum User’s Guide Volume 2.
When ident writes out data variables, it prints the data according to the specification on the filedef statement for the file to which you are writing the data. If the filedef statement includes the keyword norule to suppress the ruler, the data is written out without a ruler, otherwise the ruler is always printed above the data, as in the previous example.
You can alter this behavior without having to respecify the filedef command by typing a + or − sign at the end of the ident keyword. If filedef normally requests a ruler, type:
ident− data variables
to print the listed variables without a ruler. If filedef normally suppresses the ruler, type:
ident+ data variables
to print the variables with a ruler.
To switch off ident and revert to the standard write behavior, type:
noident
7.6 Writing out data in a user-defined format
Quick Reference
To write data to the standard print file (usually called out2) in a format of your choice, type:
call qfprnt(0, $format$, variables)
where format defines the format in which the data is to be written and the data types of the variables used. variables is a comma-separated list of the variables to be written out. Variables must be listed in the order they are used in the format statement.
The format string consists of optional text interspersed with references to variables in the list:
write and report are both powerful statements for writing out data, but they do have limitations which you may find restrictive in some circumstances. The write statement lets you write data out to a print file, including the standard print file (usually called out2), but it always writes the data in a fixed format that you cannot change. The report statement lets you write out data and text in any format you like, but only to a report file. You cannot write to a print file with report.
The qfprnt function brings together the functionality of write and report by writing text and data to the standard print file in a format of your choice. To use it, type:
call qfprnt(0, $format$, variables)
where format defines the format in which the data is to be written and the data types of the variables used. variables is a comma-separated list of the variables to be written out. Variables must be listed in the order they are used in the format statement.
Here is a simple example to start with:
call qfprnt(0,$Number of products tested is: %2i$,t1)
%num_posi Print an integer variable in the next num_pos positions on the line. If the variable has a negative value the value is printed starting with a minus sign.
%num_pos.dec_plr Print a real variable in the next num_pos positions on the line and with dec_pl decimal places. The number of print positions must allow for the required number of decimal places and a decimal point.
%num_colc Print num_col columns starting with the column whose name or number appears in the variable list. Columns are printed as texts not punch codes;
that is, multicodes are converted to letters where possible.
%numberb Print number blank spaces.
If the respondent tested five products this statement will appear in the standard print file as:
Number of products tests is: _5
The underscore character in front of the 5 represents a space and appears as such in the print file.
We’ll explain why we have printed it here shortly. First, let’s look at the qfprnt statement itself.
The format section of the statement consists of text to be printed exactly as it is written and references to variables whose values are to be substituted in the text at the given points. In this example we are writing out the value of the numeric (integer) variable t1. The variable is named in the variable list section of the statement and is represented by the characters %2i in the format section.
There are three parts to the variable’s reference. The % sign signals to Quantum that it has reached a variable reference: all references start with a % sign. The i says that the variable is an integer variable and the 2 says how many print positions to reserve for printing this variable. In the example two positions are reserved for printing the value of t1, but since the value of t1 is only 5, Quantum prints the value on the right of the reserved space and fills the remaining positions with spaces. In the sample output we have used an underscore to represent this space.
Here is another example using two integer variables:
call qfprnt(0,$Record %4i tested %2i products$,recnum,t1) This produces lines of the form:
Record 1004 tested _5 products
As before, the underscore represents a space used to pad a value to the full field width.
This qfprnt statement produces the correct results because the variables are in the same order as their references in the format section. This is your responsibility. As long as a variable has the same type as the reference in the corresponding position in the format section, Quantum will print its value at that point in the statement. So, if we had written:
call qfprnt(0,$Record %4i tested %2i products$,t1,recnum) Quantum would write out:
Record ___5 tested ** products
As you can see, Quantum does not increase the number of print positions to accommodate the value it needs to print. Instead, it prints asterisks. In this example, the asterisks would alert you to the fact that there is something wrong with the qfprnt specification, but this would not always be so.
More often than not you’ll be printing positive values. If Quantum needs to print a negative
Besides integer variables, you can also print real variables, columns or fields of columns and blank strings. You use a reference similar to the one you’ve seen for integer variables.
To print a real variable, type:
%num_pos.dec_plr
where num_pos is the number of print positions required and dec_pl is the number of decimal places. As an example, the statement:
call qfprnt(0,$%5.2r liters bought$,liters)
prints the value of the real variable called liters in a field 5 positions wide. The value is printed with two decimal places so, allowing for the decimal point, the maximum value that can be printed in 99.99:
15.27 liters bought 9.01 liters bought
Quantum can also print the text values of a column, a field of columns or a data variable. By this we mean that Quantum converts multicodes to letters or other keyboard characters before printing them. Multicodes that do not correspond to letters or characters are printed as asterisks. For example, the multicode ‘&1’ translates into the letter A and would be printed as such; the multicode
‘&123’ is simply as collection of codes and would therefore be printed as an asterisk.
To print single columns, type:
%numberc
in the format section, where number is the number of print positions required, and the name of a single column in the corresponding position in the variable list. Quantum will then print number columns starting at the named column. For example:
call qfprnt(0,$Record %4c tested %2i products$,c1,t1) might produce:
Record 1234 tested 5 products
Now suppose that the data is:
----+---2 9462&5736 5 1 8 9 The statement:
call qfprnt(0,$Columns 11 to 20 are %10c: $,c11) reports the following:
Columns 11 to 20 are: 9*62A5*36 To print strings of blanks, type:
%numberb
where number is the number of blanks you want. You’ll find this useful if you want to indent lines or print values in columns.
This chapter describes how to assign values to variables and the statements emit, delete and priority, all of which may be used to alter the contents of a variable. Emit, delete and priority are used only with columns whereas assignment statements can deal with character, integer and real variables.
When we say that these statements change the contents of a column we mean that they change the contents of that column as it exists during the run: at no time do they change the corresponding column in the data file.