DECLARE-LAYOUT

Syntax

DECLARE-LAYOUT layout_name [PAPER-SIZE=({paper_width_num_lit[uom], paper_depth_num_lit[uom]}|{paper_name})] [FORMFEED=form_feed_lit] [ORIENTATION=orientation_lit] [LEFT-MARGIN=left_margin_num_lit[uom]] [TOP-MARGIN=top_margin_num_lit[uom]] [RIGHT-MARGIN=right_margin_num_lit[uom] |LINE-WIDTH=line_width_num_lit[uom] |MAX-COLUMNS=columns_int_lit] [BOTTOM-MARGIN=bottom_margin_num_lit[uom] |PAGE-DEPTH=page_depth_num_lit[uom] |MAX-LINES=lines_int_lit] [CHAR-WIDTH=char_width_num_lit[uom]] [LINE-HEIGHT=line_height_num_lit[uom]] END-DECLARE

Description

Defines the attributes for the layout of an output file .

The DECLARE-LAYOUT command describes the characteristics of a layout to be used for an output file. A layout can be shared by more than one report. If no DECLARE-LAYOUT is defined or if a DECLARE-REPORT does not reference a defined layout, a layout named DEFAULT is created with the default attribute values shown in the DECLARE-LAYOUT Command Arguments table. For an example of how DECLARE-LAYOUT relates to DECLARE-REPORT, see the DECLARE-REPORT examples in this document.

You can define as many layouts as are necessary for the requirements of the application. You can override the DEFAULT layout attributes by defining a layout called DEFAULT in your program. Each layout name must be unique.

SQR maps its line and column positions on the page by using a grid determined by the LINE-HEIGHT and CHAR-WIDTH arguments. That is, SQR calculates the number of columns per row by dividing the LINE-WIDTH by the CHAR-WIDTH and calculates the number of lines by dividing the PAGE-DEPTH by the LINE-HEIGHT. Each printed segment of text is placed on the page using this grid. Because the characters in proportional fonts vary in width, a word or string may be wider than the horizontal space you have allotted, especially in words containing uppercase letters or boldfaced characters. To account for this behavior, you can either move the column position in the PRINT or POSITION statements or indicate a larger CHAR-WIDTH in the DECLARE-LAYOUT command.

The DECLARE-LAYOUT command selects the proper fonts. In addition, the parameter interacts with PAPER-SIZE like this:

When you do not specify ORIENTATION=LANDSCAPE or the PAPER-SIZE dimensions, SQR creates a page with the dimensions set to 11 inch by 8.5 inch. This results in a page of 100 columns by 45 lines with 0.5 inch margins.
When you specify PAPER-SIZE=(paper_name), the page orientation is set according to the paper_name specified. If you also specify ORIENTATION and the value differs from the PAPER-SIZE value, the ORIENTATION value overrides the PAPER-SIZE value.
When you specify PAPER-SIZE=(page_width, page_depth), SQR does not swap the page width and page depth if ORIENTATION=LANDSCAPE.

Parameters

Parameter	Description
layout_name	A unique layout name to be used for referencing the layout and its attributes.
uom (unit of measure)	An optional suffix that denotes the unit of measure to apply to the preceding value.
paper_name	An option of PAPER-SIZE. This name is associated with predefined dimensions.

Parameter

Description

layout_name

A unique layout name to be used for referencing the layout and its attributes.

uom

(unit of measure)

An optional suffix that denotes the unit of measure to apply to the preceding value.

paper_name

An option of PAPER-SIZE. This name is associated with predefined dimensions.

This table lists valid unit of measure suffixes:

Suffix	Meaning	Definition
dp	decipoint	0.001388 inch
pt	point	0.01388 inch
mm	millimeter	0.03937 inch
cm	centimeter	0.3937 inch
in	inch	1.0000 inch

This table lists valid paper names for the paper_name parameter.

Name	Width	Depth	Orientation
Letter	8.5 in	11 in	Portrait
Legal	8.5 in	14 in	Portrait
A4	8.27 in	11.69 in	Portrait
Executive	7.25 in	10.5 in	Portrait
B5	7.17 in	10.12 in	Portrait
Com-10	4.125 in	9.5 in	Landscape
Monarch	3.875 in	7.5 in	Landscape
DL	4.33 in	8.66 in	Landscape
C5	6.378 in	9.016 in	Landscape

This table describes the arguments of the DECLARE-LAYOUT command:

Argument	Choice or Default UOM	Default Value	Description
PAPER-SIZE	inches	8.5 in, 11 in	Physical size of the page. The first parameter is the width of the page. The second parameter is the depth or length. It may also be a predefined name. (See the table of valid paper names.) Note that when ORIENTATION= LANDSCAPE, the default values are 11 in, 8.5 in.
FORMFEED	YES, NO	YES	Specifies whether formfeeds are to be written at the end of each page.
ORIENTATION	PORTRAIT, LANDSCAPE	PORTRAIT	Portrait pages are printed vertically. Landscape pages are printed horizontally. Printing in landscape for the printer type HPLASERJET requires landscape fonts.
LEFT-MARGIN	inches	0.5 in	Amount of blank space to leave at the left side of the page.
TOP-MARGIN	inches	0.5 in	Amount of blank space to leave at the top of the page.
RIGHT-MARGIN	inches	0.5 in	Amount of blank space to leave at the right side of the page. If you specify LINE-WIDTH or MAX-COLUMNS, you cannot use this parameter.
LINE-WIDTH	inches	7.5 in	Length of the line. If you specify RIGHT-MARGIN or MAX-COLUMNS, you cannot use this parameter.
MAX-COLUMNS	NA (not applicable)	75	Maximum number of columns in a line. If you specify RIGHT-MARGIN or LINE-WIDTH, you cannot use this parameter.
BOTTOM-MARGIN	inches	0.5 in	Amount of blank space to leave at the bottom of the page. If you specify PAGE-DEPTH or MAX-LINES, you cannot use this parameter.
PAGE-DEPTH	inches	10 in	Depth of the page. If you specify BOTTOM-MARGIN or MAX-LINES, you cannot use this parameter.
MAX-LINES	NA	60	Maximum number of lines printed on the page. If you specify PAGE-DEPTH or BOTTOM-MARGIN, you cannot use this parameter.
LINE-HEIGHT	points	12 pt	Size of each SQR line on the page. An inch has 72 points. If LINE-HEIGHT is not specified, it follows the value for POINT-SIZE, if specified. The default value of 12 points yields 6 lines per inch. For the printer type LINEPRINTER, this value is used only to calculate the TOP-MARGIN and BOTTOM-MARGIN (for example, not in computing the position on the page).
CHAR-WIDTH	points	7.2 pt	Size of each SQR horizontal character column on the page (for example, the distance between the locations (1, 12) and (1, 13)). For the printer type LINEPRINTER, this value is used only to calculate the TOP-MARGIN and BOTTOM-MARGIN (not for computing the position on the page).

Example

This example illustrates the ability to specify these parameters using a different measurement system, such as metric:

!
declare-layout my-layout      ! Results in: 

paper-size=(a4)               !   paper-size=(210mm, 297mm) 

left-margin=12.7 mm           !   top-margin=12.7mm 

right-margin=25.4 mm          !  left-margin=12.7mm
end-declare                   !  right-margin=25.4mm

                              !   bottom-margin=12.7mm

                              !   orientation=portrait

                              !   columns=67

                              !   lines=64

This example changes the page dimensions and also changes the left and right margins to be 1 inch:

!
declare-layout large-paper    ! Results in:

paper-size=(14, 11)           !   paper-size=(14in, 11in)

left-margin=1                 !   top-margin=0.5in 

right-margin=1                !   left-margin=1.0in
end-declare                   !   right-margin=1.0in

                              !   bottom-margin=0.5in

                              !   orientation=portrait

                              !   columns=120

                              !   lines=60

This example retains the default page dimensions and changes the left and right margins to be 1 inch:


declare-layout default        ! Results in:

left-margin=1                 !   paper-size=(8.5in, 11in)

right-margin=1                !   top-margin=0.5in
end-declare                   !   left-margin=1.0in 

                              !   right-margin=1.0in

                              !   bottom-margin=0.5in

                              !   orientation=portrait

                              !   columns=65

                              !   lines=60

This example changes the orientation to landscape; the default page dimensions (8.5in and 11in) are swapped, the columns and rows are recalculated, and all other values remain the same:


declare-layout default         ! Results in:

orientation=landscape          !   paper-size=(11in, 8.5in)
end-declare                    !   top-margin=0.5in

                               !   left-margin=0.5in

                               !   right-margin=0.5in

                               !   bottom-margin=0.5in

                               !   orientation=landscape

                               !   columns=100

                               !   lines=45

This example changes the orientation to landscape; the default page dimensions (8.5in and 11in) are swapped, and the top margin is set to 1 inch:

declare-layout my_landscape     ! Results in:

orientation=landscape           !   paper-size=(11in, 8.5in)

top-margin=1                    !   top-margin=1.0in
end-declare                     !   left-margin=0.5in

                                !   right-margin=0.5in

                                !   bottom-margin=0.5in

                                !   orientation=landscape

                                !   columns=100

                                !   lines=43

This example illustrates how to specify the page dimensions using one of the predefined names (note that the orientation has also changed because this example is an envelope):


declare-layout envelope          ! Results in: 

paper-size=(com-10)              !   paper-size=(4.125in, 9.5in) 
end-declare                      !   top-margin=0.5in 

                                 !   left-margin=0.5in

                                 !   right-margin=0.5in

                                 !   bottom-margin=0.5in

                                 !   orientation=landscape

                                 !   columns=85

                                 !   lines=18

See DECLARE-REPORT