September 20, 2006

SQR Document Sections

A reader sent a question about a problem he was having with BEGIN-DOCUMENT in SQR. Now, I admit that I've never even used document sections before and so decided to take a look at them. In the process I found that they can be useful but a little tricky.

A document section is intended to describe a one-page letter or statement. It's a form that contains text and variables, and the values of the variables are merged into the document before it is printed.

begin-document (1,1)
Dear &name
.b
This is to inform you that...
end-document

In this example, the letter begins at position (1,1) on the page. "Dear" is followed by the value of the &name variable. String and numeric #variables can also be used. The ".b" indicates a blank line. The text is presented exactly as shown. Since ".b" is required to force a blank line, this would seem to imply that short lines would be merged together and long lines would wrap. But the only thing that seems to happen is that blank lines are ignored.

Relative positioning is allowed, so you can begin the document at a position such as (+1,1). However, this can lead to problems. When the page fills up, a new page is not started. It appears that SQR assumes you will be doing one document per page and therefore have coded a NEW-PAGE somewhere. If not, then the document(s) will just overflow the page and an error will result.

Documents can be useful in lining up columns. However, that leads to another type of problem. Consider this:

begin-document
&name
&address
&city, &state  &postal     WRONG
end-document

The problem here is that the positions of the state and postal fields are fixed. The value of &STATE will print in column 8 in this example. This means that the state will overlap the city, and there will be 6 blank spaces after the state before the postal (zip) code prints. SQR provides a way out of this. You can code a document marker and then position to it and execute PRINT statements:

begin-document
&name
&address
@city_state_zip
end-document

position () @city_state_zip
print &city   ()
print ', '    ()
print &state  ()
print '  '    ()
print &postal ()

But it would seem much easier just to create a separate variable and print that in the document.

Until next time...