Contents
COBOL FormPrint Table of Contents

COBOL FormPrint

Windows Form Printing for COBOL

Flexus International Corporation	Fax: 610-588-9475
P.O. Box 640	Voice: 610-588-9400
Bangor  PA  18013-0640	BBS: 610-863-4740
U.S.A.	E-Mail: info@flexus.com

The software described in this document is furnished under a license agreement or non-disclosure agreement.  The software may be used or copied only in accordance with the terms of the agreement.  It is unlawful to copy this software on magnetic tape, disk or any other medium for any purpose other than the purchaser's personal use.

Copyright  1993, 1994, 1995, 1996, 1997, 1998

Interex Software, Incorporated

All rights reserved.

TABLE OF CONTENTS

PART A

Getting Started

CHAPTER A1 - Before You Begin

What is COBOL FormPrint?

The COBOL FormPrint Forms Editor

The Runtime System

A STEP-BY-STEP APPROACH TO USING COBOL FormPrint

WHAT YOU NEED TO USE COBOL FormPrint

WHAT YOUR CUSTOMER NEEDS TO USE COBOL FormPrint

TERMINOLOGY

Form file

Form

Field

Group

Repeat Group

Color

Font

WHAT'S IN THE REST OF THIS GUIDE?

A Summary of PART B

A Summary of PART C

A Summary of PART D

A Summary of PART E

Appendix A

Appendix B

INSTALLATION OF COBOL FormPrint and THE FORMS EDITOR

SYSTEM REQUIREMENTS

GETTING HELP

CHAPTER A2 - An Introduction to the Windows Print Manager

PART B

The COBOL FormPrint Forms Editor

CHAPTER B1 - An Introduction to the COBOL FormPrint Forms Editor

Launch the COBOL FormPrint Forms Editor

Components of the Forms Editor

The Interrelationships between the Four Components

Using the Forms Editor

Accessing the Forms Editor Menu Bar

With the Mouse pointer

With the Keyboard

Accessing the Forms Editor Icon Tool Bar

With the Mouse pointer

With the Keyboard

Pointer Symbols in the Forms Editor Icon Tool Bar

Actions to be Taken After Selection of Specific Icons

Accessing the Forms Editor Field Characteristic Ribbon

With the Mouse pointer

With the Keyboard

Pointer Symbols in the Forms Editor Field Characteristic Ribbon

Accessing the Forms Editor Format Window

With the Mouse Pointer

With the Keyboard

Pointer Symbols Used with the Forms Editor Format Window

CHAPTER B2 - How to Use the COBOL FormPrint Forms Editor

What is a Form File?

Create a New Form File in the Forms Editor

How to Use the Format Window in the Forms Editor

Working with Fields in the Format Window

Creating a Field in the Format Window

Using the Mouse

Using the Keyboard

Selecting a Field in the Format Window

Using the Mouse

Using the Keyboard

De-selecting a Field in the Format Window

Using the Mouse

Using the Keyboard

Changing the Size of a Field or Group in the Format Window

Using the Mouse

Using the Keyboard

Working with Cell Rows and Cell Columns

Moving a Field in the Format Window

Using the Mouse

Using the Keyboard

Deleting a Field in the Format Window

Using the Mouse

Using the Keyboard

Manipulating Multiple Fields and Groups in the Format Window

Selecting an area using the mouse

Selecting an area using the keyboard

Moving the selected area using the mouse

Moving the selected area using the keyboard

Copying the selected area

Deleting the selected area

Deleting and copying the selected area

Copying an area back to the Format Window

Overlaying One Field with Another in the Format Window

Undoing Your Last Change

Aligning Fields

CHAPTER B3 - Working with Bitmaps in the Form Header

Using a Bitmap to Print the Company Logo on a Form

What is a Bitmap?

Add a Bitmap to the Format Window

CHAPTER B4 - Working with Static Text in the Form

What is Static Text?

Create a Line of Static Text in the Form Definition

Using the Keyboard

Important Issues Involving Static Text in COBOL FormPrint

Multiline Text

Move the Line of Static Text in the Form Definition

CHAPTER B5 - Changing the Default Font Size and Type

What is a Font?

Important Issues Involving Fonts in COBOL FormPrint

Add Static Text to the Form

Add a New Font Size and Type

Change the Default Font

CHAPTER B6 - Changing Colors

Establish a Color for a Form Field

CHAPTER B7 - Working with Custom Fields

What is a Custom Field?

Add Several Custom Fields to the Form

Multiline Fields

CHAPTER B8 - Working with Input Types

What is an Input Field Type?

Establish a Numeric Field

Establish the Input Type

CHAPTER B9 - Working with Field Groups

What is a Field Group?

Establish a Field Group

Using the Keyboard

Include All Fields Within the Field Group

Using the Keyboard

Establish a Fill Color for the Field Group

Create Static Text Column Headings in the Form Definition

Using the Keyboard

CHAPTER B10 - Working with Repeat Groups

What is a Repeat Group?

Add a Repeat Group on the Panel

Specify the Total Number of Field Occurrences

CHAPTER B11 - Changing the Field Border

What is the Field Border?

Eliminate the Border for a Field

CHAPTER B12 - Working with Check Boxes?

What is a Check Box?

Add a Check Box to the Form

Assign a Caption to the Check Box

Assign Program Values to the Check Box

CHAPTER B13 - Working with Radio Buttons

What is a Radio Button?

Add a Radio Button to the Form

Assign a Caption to the Radio Button

Assign Program Values to the Radio Button

CHAPTER B14 - Guidelines for Creating Forms

Introduction

Spacing of Items within the Form

Lines and Boxes

Spreadsheets and Grids

Colors and Shading

Fonts

Repeating Fields

Data Field Formatting

Radio Buttons and Check Boxes

Bitmaps

PART C

Programming with FormPrint

CHAPTER C1 - Introduction to Programming

Calling COBOL FormPrint

Function Area

How to Initialize FormPrint and Open a Form File

How to Select a Printer

How to Print a Form

How to Finish Up

CHAPTER C2 - The Generated Program Data Division

Function Codes and Parameter area

Parameter for PRINT-PAGE Function

CHAPTER C3 - The Generated Program Procedure Division

Init FormPrint

Selecting the printer

CHAPTER C4 - Selecting the Printer with COBOL FormPrint

Methods for Selecting the Printer

The First Method for Selecting the Printer

Explanation of the First Method

A Flowchart of the First Method for Selecting the Printer

The Second Method for Selecting the Printer

Explanation of the Second Method for Selecting the Printer

A Flowchart of the Second Method for Selecting the Printer

The Third Method for Selecting the Printer

Explanation of the Third Method for Selecting the Printer

A Flowchart of the Third Method for Selecting the Printer

Setting Additional Printer Attributes

CHAPTER C5 - Miscellaneous Issues

Completing the Printing Job

Checking the Version Number of FormPrint

Creating a Log File

CHAPTER C6 - Dynamically Modifying the Form at Runtime

Changing a Bitmap Image

Changing a Font

Changing a Color

CHAPTER C7 - MultiForm Pages

Defining Forms for Multi-Form Pages

Programming for Multi-Form Pages

CHAPTER C8 - Print Preview Facility

Invoking the Print Preview Facility

Using the Print Preview Facility

PART D

FormPrint Programming Functions

CHAPTER D1 - Introduction to Functions

Primary Functions

Information Functions

Explanation of the Primary Function Area

QPR-INIT

QPR-SELECT-PRINTER

QPR-PRINT-PAGE

QPR-END-PRINT

QPR-SELECT-PRINTER-EX

Parameter Areas

CHAPTER D2 - Primary Functions

QPR-INIT

QPR-SELECT-PRINTER

QPR-PRINT-PAGE

QPR-END-PRINT

QPR-SELECT-PRINTER-EX

CHAPTER D3 - Information Functions

QPR-ABOUT

PART E

FormPrint Data Items

CHAPTER E1 - Introduction to Data Items

CHAPTER E2 - Data Used for Opening a Forms File & Initializing FormPrint

Layout

QPR-QI-RET

QPR-LIBRARY

QPR-METHOD

QPR-FILE

CHAPTER E3 - Data Used for Selecting the Printer

Layout

QPR-RET-CODE

QPR-DIALOG

QPR-DOC-NAME

QPR-ORIENTATION

QPR-COPIES

QPR-STRETCH

QPR-DEVICE-LIST

QPR-DRIVER

QPR-OUTPUT

QPR-PAPER-SIZE

QPR-PAPER-SOURCE

QPR-PREVIEW

CHAPTER E4 - Data Used for Obtaining Version Information

Layout

QPR-QE-RET

QPR-VERSION-INFO

QPR-DISPLAY-BOX

APPENDIX A - Configuring COBOL FormPrint

APPENDIX B - Form File Organization

APPENDIX C - Return Codes

For Help on Help, Press F1


CHAPTER A1 - Before You Begin

What is COBOL FormPrint?

COBOL FormPrint is a tool used by COBOL programmers to develop and maintain contemporary print forms for their programs.  It allows the complexities of such forms to be somewhat isolated from a COBOL program, yet still enables a COBOL programmer to have close control over the form directly from a program using standard COBOL code.

The COBOL FormPrint Forms Editor

COBOL FormPrint provides a Forms Editor for designing and developing your printer form.

The Runtime System

For implementing your print form, COBOL FormPrint provides a powerful runtime system (also used by the Forms Editor itself) accessed through simple call statements.  Sample call statements and a copy file containing interface data items can be generated using the Forms Editors own code generator.

A STEP-BY-STEP APPROACH TO USING COBOL FormPrint

Here is a step-by-step outline of a typical COBOL FormPrint Development session:

1.	Define your form using the COBOL FormPrint Forms Editor

2.	Generate the data area for your form using the Code Generator included with the COBOL FormPrint Forms Editor

3.	Include the generated data area in the printing subroutine within your COBOL application

4.	Modify the logic in your printing subroutine to pass data to the new data area

5.	Call QPR (COBOL FormPrint) for printing each page

WHAT YOU NEED TO USE COBOL FormPrint

1.	The COBOL FormPrint Forms Editor.

2.	QPR.DLL (The COBOL FormPrint Runtime System)

WHAT YOUR CUSTOMER NEEDS TO USE COBOL FormPrint

1.	QPR.DLL  (The COBOL FormPrint Runtime System)

2.	All forms files containing forms used in your application.

3.	All bitmap image files included in the forms used in your application.

4.	If your forms include radio buttons, your customer will need the bitmap image files for selected and unselected radio buttons.  These files are named RON.BMP (selected radio button bitmap image) and ROFF.BMP (unselected radio button bitmap image).

5.	The FONTS.QPR file which contains information about form fonts and color IDs used in your FormPrint forms.

TERMINOLOGY

Here is a formal definition of some of the terms used in the rest of this guide.  Some of these terms have already been mentioned above.

Form file

This is the file in which COBOL FormPrint stores forms.  This file may be manipulated with regular operating system commands.

Form

This is the actual form definition that your program will send to the printer.  Forms are defined using the Forms Editor.

Field

An object defined within a form for the purpose of displaying data on a printed form.  Fields are defined using the Forms Editor.  Static fields are used for forms text which does not generally change, labels for non-static fields and other printed text which generally remains constant.  Non-static fields are used for printing variable data and printing non-static data.

Group

An object used to logically group non-static fields within a form.  Groups are defined using the Forms Editor.

Repeat Group

An object used to allow a non-static field or group of fields to be defined once and used multiple times within a form.  Repeat groups are used to create vertical and horizontal arrays.

Color

The attribute assigned to a field, group or form setting the foreground and background colors of the object.  Colors are defined using the Forms Editor.

Font

The attribute assigned to a field or form controlling the printed output for that object.  Fonts are defined using the Forms Editor.

WHAT'S IN THE REST OF THIS GUIDE?

The COBOL FormPrint User Guide is divided into 5 parts.  Each part has been assigned a letter and represents a major User Guide topic.  The remaining 4 parts are:

Part B, The COBOL FormPrint Forms Editor.

Part C, Programming with COBOL FormPrint.

Part D, FormPrint Programming Functions

Part E, FormPrint Data Items

A Summary of PART B

PART B, The COBOL FormPrint Forms Editor, provides a basic introduction to the Forms Editor and how to use the editor in general.  If you encounter difficulty in creating, deleting, moving or changing the size of fields in the Forms Editor, you should refer to Chapter B2.  This chapter explains the standard procedures to use when working with fields in the form you are creating.

Part B will help significantly reduce your learning curve when using the Forms Editor.

A Summary of PART C

PART C, Programming with COBOL FormPrint, provides an overview of the concepts involved when using COBOL FormPrint.  Part C is helpful when you first start using COBOL FormPrint.

This section of the manual explains in general terms the standard procedures you will use when using COBOL FormPrint.  Topics covered include how to select the printer, pass data to forms, and eventually send forms to printer, close and end your printer session.

A Summary of PART D

PART D, FormPrint Programming Functions, lists the various FormPrint functions used to control the printing from your COBOL program.

A Summary of PART E

PART E, FormPrint Data Items, lists the various FormPrint data variables passed to FormPrint by your COBOL program.  The entries in the various chapters of PART E will list the Data Items as well as the functions needed to set the item in your program.

Appendix A

Appendix A lists the Environment Variables used to configure COBOL FormPrint.

Appendix B

Appendix B provides techniques for organizing forms within your forms files.  It also describes the QPRCHECK utility which is used to compress and update forms files.

INSTALLATION OF COBOL FormPrint and THE FORMS EDITOR

COBOL FormPrint and the Forms Editor are shipped as an executable (.EXE) file.  This allows you to start the installation using the Windows Program Manager or the Windows 95 Start/Run feature to install the package

SYSTEM REQUIREMENTS

COBOL FormPrint requires approximately  2.4 megabytes of hard disk space.

GETTING HELP

The COBOL FormPrint Users Guide should provide answers to most of your questions.  Please study the manual carefully before calling for assistance.  If after reviewing the manual, you are still unsure of the solution to your problem, please call the telephone number on the first page of this book.  You will also find the facsimile number, bulletin board number and e-mail address on the first page if you wish to send your question by fax or modem.

Note:  If your problem is complex or if we are unable to duplicate the problem, you may need to send us a small sample application which will demonstrate the problem.  If so, please remember to send the following:

1.	Only small sample programs (source code in addition to executable files as we must be able to compile the files in our environment. The source files and executables should not contain any file handling)

2.	Your FONTS.QPR file.

3.	The forms file(s) used by the sample program.

4.	The version number of COBOL FormPrint.

Proceed to Chapter A2


CHAPTER A2 - An Introduction to the Windows Print Manager

When you use a printer in the Windows environment, you are actually initiating a complex interaction involving, the printer device library module and the Windows Print Manager program (PRINTMAN.EXE).  When a program wants to begin using a printer, Windows loads the device driver module.  The device driver performs some initializations and then the Windows Print Manager program is  loaded into memory.  The Windows Print Manager program is a print spooler that relieves your application from some of the work involved with printing.

The Print Manager will read and transfer the files created by Windows GDI (Graphical Device Interface) directly to the printer.  During the time the Print Manager is writing the printer output to the output port, other Windows programs can function normally.  If the Print Manager can't be loaded, Windows will attempt to write directly to the parallel or serial port.  Unlike the printing done by the Print Manager this will delay the operation of application programs until printing is completed.

To make sure that the Print Manager is being loaded in your installation of Windows you should inspect the [windows] section of the WIN.INI file.  This file can usually be found in the \WINDOWS directory.  It must contain the following text in order to be loaded properly:

Spooler=yes

If you change the text to:

Spooler=No

The Print Manager will not be loaded.  You may wish to do this if you want to use a different hardware or software spooler that works faster than the Print Manager or if your printer is on a network which has its own spooler.

Proceed to Chapter B1


CHAPTER B1 - An Introduction to the COBOL FormPrint Forms Editor

Launch the COBOL FormPrint Forms Editor

1.	Invoke the forms editor program as you would invoke any program from the operating system/environment in which you are working.  If you invoke COBOL FormPrint from a GUI environment, click on the appropriate icon.

2.	The COBOL FormPrint logo window will display for a few moments.  The FormPrint Forms Editor Tool will then display.

Components of the Forms Editor

As you can see in the previous image, there are four main components of the COBOL FormPrint Forms Editor.  The components are as follows:

•	The Menu Bar

•	The Icon Tool Bar

•	The Field Characteristic Ribbon

•	The Format Window

The Interrelationships between the Four Components

Each of the four components will be addressed individually later.

1.	The Format Window is your work area.  This is the area where you:

a)	specify the location of your form fields,

b)	resize the default form fields to suit your needs and

c)	combine various form fields to complete the appearance of your form.

2.	The Icon Tool Bar is used to select various form fields for placement in the Format Window.  It is also used to initiate the process of specifying form field behavior.  The Icon Tool Bar should significantly speed completion of the user interface design if you prefer to use a mouse.

For example, assume that you would like to place a data field on the proposed form.  The first step to accomplish this task would be to move the mouse pointer to the second icon on the Tool Bar and click once.  You would then move the pointer to the desired location in the Format Window and click again.  A default data field will then appear in the Format Window automatically.

As mentioned previously, you could then easily change the location or size of the default field within the Format Window.

3.	The Field Characteristic Ribbon allows you to specify the characteristics of the form fields once they are placed in the Format Window.  In the example of the data entry field just created, the developer could easily specify:

a)	a COBOL field name, ,,

b)	initial display value for the data entry field,, ,

c)	COBOL picture clause and,

d)	whether the field is an alphanumeric, numeric or date field.

This is all accomplished by typing the appropriate values within the Field Characteristic Ribbon.

There are three entry fields and one combination box on the Field Characteristic Ribbon.

In order to enter or select a Field Characteristic for a specific field or field group, the cursor in the Format Window must be on the field or field group for which you want to establish the characteristic.

4.	The Menu Bar is also available to create form fields and specify field characteristics for fields already in the Format Window.  The Menu Bar also provides access to the same form design tools which are available on the Icon Tool Bar.

For creation of standard form fields, it is suggested that you use the Icon Tool Bar for faster forms design, but if you prefer not to use a mouse when designing the form, the Menu Bar provides you with all of the same form design facilities.

The Menu Bar is also used for accessing forms file management tasks and tools not available on the Icon Tool Bar such as opening forms files, saving your work to disk and modifying the size of the form.

Using the Forms Editor

1.	The Forms Editor may be navigated with the keyboard, the mouse or both the keyboard and the mouse.  Although the keyboard must be used when specifying field captions, field formats and initial values, using the mouse as much as possible will greatly speed the process of form development.

2.	At any point during the development process, you may minimize, maximize, restore or close the Forms Editor using the icons in the upper right corner of the main Forms Editor window.  You may also use the system icon in the upper right to perform these functions.

Accessing the Forms Editor Menu Bar

With the Mouse pointer

Click on the desired menu bar option.  The corresponding pull down menu will appear, allowing you to click on the desired choice.

With the Keyboard

Use the (ALT) or (F10) key to activate the menu bar.  Press the (DOWN ARROW) or (ENTER) key to display the corresponding pull down menu.  Use the (ARROW) keys to move to the desired choice and select the choice using the (ENTER) key.

Accessing the Forms Editor Icon Tool Bar

1.	The Icon Tool Bar is used for several purposes in the Forms Editor.  The Icon Tool Bar can be used to create fields in the Format Window as well as establish rules for field behavior.  Accessing the Icon Tool Bar can be accomplished as follows:

With the Mouse pointer

Position the mouse pointer on the desired icon and click the left mouse button once.  The pointer symbol may change, depending upon the specific icon selected.  See the section on Pointer Symbols in the Forms Editor Icon Tool Bar below for more information on those icons which change the pointer symbol.

With the Keyboard

The Icon Tool Bar must be activated with the mouse.  All tools available on the Icon Tool Bar are also accessible through the Menu Bar, if you prefer to use the keyboard instead of the mouse.

Pointer Symbols in the Forms Editor Icon Tool Bar

1.	The Icon Tool Bar uses two different pointer symbols.  The default pointer symbol, which is a diagonally pointing arrow, is used to initially select the icon.

2.	After the Icon has been selected, the pointer will change to an action pointer for those icons which are used to:

a)  create a field in the Format Window, or

b)  select a field in the Format Window for further definition.

When the pointer symbol changes to the action pointer (vertically pointing arrow or a four-way pointing arrow, depending upon your operating environment), it is an indication that action is needed in the Format Window.  The action to be taken depends on the specific icon selected.

3.	The pointer will remain as a diagonally pointing arrow for those icons which require further definition of field or group characteristics in the Field Characteristic Ribbon.  These characteristics, or rules, are set in the Combination Box located on the Field Characteristic Ribbon.

Actions to be Taken After Selection of Specific Icons

1.	The icons which change to an action pointer when selected and the specific action to be taken include:

Icon	Action to Be Taken
Static Text	Create Static Text in Format Window
Custom Field	Create Custom Field in Format Window
Radio Button	Create Radio Button in Format Window
Check Box	Create Check Box in Format Window
Bitmap	Create Bitmap in Format Window
Group Box	Create Field Group Box in Format Window
Repeat Field	Create Repeat Field Box in Format Window
Delete Field	Delete Field in Format Window
Page Setup	Select Paper Size and Orientation
Print Sample	Print a Sample Copy of the Form
Font	Select Field to Assign a Special Font
Color	Select Field to Assign a Special Color
Accessing the Forms Editor Field Characteristic Ribbon

With the Mouse pointer

Using the mouse, position the pointer on the field in the Format Window for which you want to establish a specific characteristic.  Click the left button once to position the cursor.

Once the field has been selected, move the pointer to the field in the Field Characteristic Ribbon which is to be modified and click once.

With the Keyboard

When the cursor is in the Format Window, you may access the Field Characteristic Ribbon by pressing the (ESC) key once.

If the Menu Bar has been activated and a menu bar option is highlighted, pressing the (ESC) key twice will place the cursor on the Field Characteristic Ribbon.

If a pulldown menu is displayed, the (ESC) key must be pressed three times to access the Field Characteristic Ribbon.  When the cursor jumps to the Field Characteristic Ribbon, it will always be located in the first field on the Ribbon.

To access other fields on the Field Characteristic Ribbon, press the (TAB) or (BACKTAB) key to move the cursor.

The first three fields on the Field Characteristic Ribbon are entry fields.  Field characteristics may be simply typed into these fields.  The Combination Box Field (last field on the Field Characteristic Ribbon) provides a variety of selections for certain types of field behavior.

You may prefer to set the Combination Box selections using the keyboard to select the appropriate icon on the Icon Tool Bar.  Use the (CTRL-LEFT ARROW) and (CTRL-RIGHT ARROW) key combinations while the cursor is in the Combination Box to switch between the various field behavior options.  Once the desired option is displayed, the (UP ARROW) and (DOWN ARROW) keys may be used to scroll through the specific settings.  Press the (ENTER) key to establish the setting for that option.

Pointer Symbols in the Forms Editor Field Characteristic Ribbon

1.	The Field Characteristic Ribbon uses two different pointer symbols.  The default pointer symbol, which is a diagonally pointing arrow, is used to make selections in the Combination Box (fourth field) on the Field Characteristic Ribbon.

2. 	The second pointer symbol, the I-Beam pointer, is used in the first three fields on the Field Characteristic Ribbon.  The I-Beam pointer is used to position the vertical cursor in the text contained in these three fields.

Accessing the Forms Editor Format Window

With the Mouse Pointer

Using the mouse, position the pointer in the desired location within the Format Window.  Click the left mouse button once to position the cursor.  To move the cursor to an area of the Format Window which is not currently visible, click the left button on the horizontal or vertical scroll bar within the Format Window.

You can also scroll the Format Window by clicking and holding the left mouse button while dragging the pointer left, right, up or down.  The Format Window should automatically scroll when the pointer is dragged outside of the Format Window.

With the Keyboard

If the cursor is already within the Format Window, you may locate the cursor by using the (ARROW) keys.  If the cursor is in the Field Characteristic Ribbon, press the (ENTER) key to locate the cursor in the Format Window.

If the Menu Bar has been activated and a menu bar option is highlighted, pressing the (ESC) key twice will place the cursor in the Format Window if the cursor was in the Format Window prior to Menu Bar activation.

If a pulldown menu is displayed, the (ESC) key must be pressed three times to access the Format Window if the cursor was in the Format Window prior to Menu Bar activation.

When the cursor jumps to the Format Window, it will always be located in its prior location in the Format Window.

Pointer Symbols Used with the Forms Editor Format Window

1.	The Format Window uses several different pointer symbols.  The default pointer symbol, which is a diagonally pointing arrow, is used to position the cursor and select fields in the Format Window for moving, resizing or field characteristic modification.

2.	The action pointer is used in the Format Window to locate a field or select a field in the Format Window for further definition.  The action pointer is displayed as a result of clicking the mouse on the Icon Tool Bar.

3.	The pointer will change to a double arrow symbol when:

a)	a field has been selected and is displayed with a reverse video border,

and

b)	the pointer is directly on the reverse video border.

The double arrow symbol indicates that the mouse may be used to change the width and/or height of a field.  There are three general types of double arrow symbols as follows:

Pointer Symbol	Action to be Taken
Horizontal Double Arrow	Change the width of the field
Vertical Double Arrow	Change the height of the field
Diagonal Double Arrow	Change the width and height of the field

Proceed to Chapter B2


CHAPTER B2 - How to Use the COBOL FormPrint Forms Editor

What is a Form File?

The Forms Editor stores forms information in data files called form files.  These form files contain the images of the forms you create as well as all of the information about the fields contained on each form.

The Forms Editor allows you to store one form per form file or many forms in a file.  You can create any number of form files you desire.  The form files may also contain full size forms definitions as well as smaller form definitions.

These form files will eventually be used and loaded into memory by your COBOL application when you make a CALL to the COBOL FormPrint runtime system.  In order to design your form images, it is necessary to first create a form file.  Once the form file is created, it may be opened later so that you may add additional forms or modify existing forms.

Before you begin designing your forms, you must first create a new form file or open an existing form file.

Create a New Form File in the Forms Editor

To create a new form file select the File/New file Menu Bar Option.

The Forms Editor Menu Bar may be accessed with the mouse by positioning the pointer on the desired menu option and clicking the left mouse button.  If you prefer to use the keyboard to access the menu bar, press the (ALT) key or (F10) key to activate the menu bar.  Use the (ARROW) keys to navigate the menu bar and pull down menus.  When you have highlighted the New file pull down option, press the (ENTER) key.

The New File pop-up window will be displayed allowing you to establish the file name and directory in which the file will reside.  There are no restrictions on file naming conventions for your form files other than those limitations imposed by your operating system/environment.

Dont change the default directory in order to create the form file in the directory in which Forms Editor resides.  Press the (ENTER) key or click on the OK Push Button to create the form file.

How to Use the Format Window in the Forms Editor

The following will describe how to access the Format Window in the Forms Editor and arrange fields to help you design your forms.

The Format Window is your work area.  This is the area in which you arrange your fields for a form that will eventually be sent to your printer from your COBOL application.

To scroll the format window, either click on the vertical and horizontal Scroll Bars or use the PGUP/PGDN keys to scroll up/down and the HOME/END keys to scroll left/right.

Working with Fields in the Format Window

Fields are easily created, sized and arranged in the Format Window with your mouse or the keyboard.  When working with fields in the Format Window, avoid overlaying one field with another, unless you are creating a special effect by overlaying a static field with a data field or a bitmap field with a static field.

Creating a Field in the Format Window

Using the Mouse

Choose the data field icon (pictured above) from the Icon Toolbar and select it by positioning the pointer directly on the icon and clicking the left mouse button.  Move the mouse pointer near the top left corner of the Format Window.  This is the location in which the data field is to appear.  Click the left mouse button once more.  A default representation of the selected field will appear in the Format Window.

Using the Keyboard

When creating a field with the keyboard, the cursor should be positioned to the desired location in the Format Window before the field is created.  Otherwise, the field will be automatically created in the current Format Window cursor position.

Once the cursor is properly positioned in the Format Window, press the (ALT) or (F10) key to activate the Menu Bar.  Next, press the "d" mnemonic key or use the (ARROW) keys to display the Field Pull Down Menu.  Position the highlight on the desired field type and press the (ENTER) key to create the field.

Selecting a Field in the Format Window

Using the Mouse

To select a field in the Format Window, double click the left mouse button while the pointer is directly on the field.  The field will then be surrounded  with a reverse video border, indicating that the field has been selected.  If you wish to use the keyboard to select a field, first position the cursor on the field, then press the (ENTER) key to select it.

Using the Keyboard

To select a field in the Format Window with the keyboard, first position the cursor directly on the field.

Once the cursor is located on the field, press the (ENTER) key.  The Forms Editor will then surround the field with a reverse video border indicating that the field has been selected.

De-selecting a Field in the Format Window

Using the Mouse

When using the mouse to de-select a field, click once on the selected field.  You may also move the mouse outside of the Format Window to de-select the field.

Using the Keyboard

A field which has been selected in the Format Window may be de-selected by pressing the (ESC) key.

Changing the Size of a Field or Group in the Format Window

Using the Mouse

Select the data field with the mouse.  This is accomplished by double clicking the left mouse button while the pointer is directly on the field.  The Forms Editor will then surround the field with a reverse video border, indicating that the field has been selected.

Move the mouse pointer to one of the sides or corners of the reverse video border surrounding the data field.  As soon as the pointer changes to a double arrow symbol, you may change the height, width or both the height and width of the field.  To change the width of the data field, position the pointer on the side of the selected data field until the pointer is a horizontal double arrow.  Click and hold down the left mouse button.

Modify the width of the data field by moving the mouse pointer to the left or right while continuing to hold the left mouse button.  When the desired data field width has been achieved, release the left button on the mouse.

Using the Keyboard

If you want to use the keyboard to change the size of fields in the Format Window, first locate the cursor directly on the field you wish to re-size with the (ARROW) keys.

Press the (ENTER) key to select the field.  The field will be surrounded by a reverse video border, indicating that it was selected.

Changing the size of a field with the keyboard is a two step process.  The first step is to press one of the four key combinations below, depending upon which side of the field you wish to change.  When you press the key combination below, the "focus" changes to the appropriate side.  You may then proceed to step two.

Key Combination	Focus is on:

(CTRL-UP ARROW)	Top of Field

(CTRL-DOWN ARROW)	Bottom of Field

(CTRL-RIGHT ARROW)	Right Side of Field

(CTRL-LEFT ARROW)	Left Side of Field

Step two allows you to actually increase or decrease the size of the field depending upon which key combination is pressed.  The following table indicates the result based upon the focus and the key combination pressed.

Focus is on the Top of the Field

(CTRL-UP ARROW)	Increase the Height of the Field

(CTRL-DOWN ARROW)	Decrease the Height of the Field

Focus is on the Bottom of the Field

(CTRL-UP ARROW)	Decrease the Height of the Field

(CTRL-DOWN ARROW)	Increase the Height of the Field

Focus is on the Right Side of the Field

(CTRL-RIGHT ARROW)	Increase the Width of the Field

(CTRL-LEFT ARROW)	Decrease the Width of the Field

Focus is on the Left Side of the Field

(CTRL-RIGHT ARROW)	Decrease the Width of the Field

(CTRL-LEFT ARROW)	Increase the Width of the Field

PLEASE NOTE:  Although it is possible to change the size of virtually every field, it may not be necessary in all cases.  When the default caption for Static Text, Radio Buttons and Check Boxes is increased in size, the field will increase in width automatically.

These fields will automatically increase in width to accommodate changes in the width of the caption or the width of the font used for the caption.  This occurs when the caption exceeds the current field width.  The fields will not automatically increase in height to accommodate a larger font style.  If you wish to use a larger font, you must manually increase the height of the field as appropriate.

In addition, a decrease in the length of the caption will not automatically decrease the width of the field.  In some cases, the appearance of the form is improved if all fields in a field group (such as data fields) are equal in length.  If the field width were automatically decreased, it would be impossible to have equal width fields with variable length captions.

Working with Cell Rows and Cell Columns

The Format Window of the COBOL FormPrint Forms Editor contains a grid to help you change the location fields and change the size of fields appropriately.

Using the top reverse video border to change the size of a forms field may not produce the precise size that you may desire.  After you have selected a field to change the size, you may wish to use the bottom border to change the height of a field.

The reason you may wish to use the bottom of the reverse video border to change the height is because the Forms Editor uses the top of the field to establish the default row position for the field.  When you use the top border to change the size of the field, it will always "snap" itself to the top of the cell row.  By using the bottom border to change the size, you will be able to change the field height more precisely.

Moving a field to a new location on the form is perfectly acceptable, because the top of the field will "snap" to a cell row in the grid.

Moving a Field in the Format Window

Using the Mouse

Select the data field on the Format Window by double clicking the left mouse button while the pointer is directly on the data field.  The Forms Editor will then surround the field with a reverse video border, indicating that the field has been selected.

Move the mouse pointer inside the reverse video border surrounding the field, then press and hold down the left mouse button.  The mouse pointer must be inside the border in order to move the field.  If the pointer is directly on the reverse video border, the field will be re-sized instead of moved.

Change the location of the data field by moving the mouse pointer while continuing to hold the left mouse button.  The reverse video border will follow the pointer as long as the left mouse button is depressed.  When the reverse video border for the field has been moved to the desired location, release the left mouse button.  This process results in "dragging" the field to the desired location.

Using the Keyboard

If you want to use the keyboard to move fields on the screen, first locate the cursor directly on the field you wish to move with the (ARROW) keys.

Press the (ENTER) key to select the field.  The field will be surrounded by a reverse video border, indicating that it was selected.

Move the field to the desired location by pressing the appropriate (ARROW) key.

Deleting a Field in the Format Window

Using the Mouse

Move the mouse pointer to the "Delete" icon on the Icon Toolbar and click the left button once.  The pointer symbol will change to an action pointer.  Move the pointer so that it is directly on the data field and click the left mouse button once more.  The data field will be deleted.

Using the Keyboard

Move the cursor to the field that you want to delete in the Format Window.  Select the Field/Delete Menu Bar Option.  The field will be automatically deleted.  You should use caution when selecting a field to be deleted.  When this method is used, there is no warning given before the field is deleted.

Manipulating Multiple Fields and Groups in the Format Window

You may find it useful to move a whole area within the format window rather than individually moving the fields and/or groups within that area.  You can also copy fields and/or groups within the window to the clipboard and later copy those items back to a different place within the same panel or even to another panel.

Selecting an area using the mouse

An area of the form is selected by holding down the left mouse button and moving the mouse pointer down or to the right.  After the mouse pointer has been moved a few pixels, the selection highlight will appear and will resize itself as the mouse pointer is moved further.  When the required area has been highlighted, release the mouse button.

Selecting an area using the keyboard

Alternatively, you may position the cursor using the arrow keys and then use the CTRL-RIGHT and CTRL-DOWN keys to select an area.

Moving the selected area using the mouse

To move the items included in the selected area, move the mouse pointer into the selected area, hold down the left mouse button, move the selection highlight to a new location and then release the mouse button.

Moving the selected area using the keyboard

Alternatively, you may use the arrow keys to move the selection highlight and then press ENTER.

Copying the selected area

Once an area has been selected, the items within it may be copied to the editor clipboard using the Edit/Copy menu option.

Deleting the selected area

Once an area has been selected, the items within it may be deleted using the Edit/Clear menu option.

Deleting and copying the selected area

Once an area has been selected, the items within it may be copied to the editor clipboard and then deleted in one action using the Edit/Cut menu option.

Copying an area back to the Format Window

Once items have been copied to the editor clipboard using the Edit/Copy or the Edit/Cut menu options, these items may be copied back to the current form or a different form using the Edit/Paste menu option.  To do this position the cursor using the mouse or arrow keys and select the Edit/Paste option.  The items will be copied to the area whose top left corner is defined by the cursor position.  The Paste option will maintain all the IDs of selected items unless those IDs are already being used in the form.  This may occur if items are being moved to another form or copied within the same form. The Paste option will also adjust the size of items if items are being moved to a form with a different cell size.  The contents of the editor clipboard will be maintained (for use in Paste operations) until another Copy or Cut operation is performed or a selected area is moved (see Moving the Selected Area above).

Overlaying One Field with Another in the Format Window

When creating or moving fields in the Format Window, it is possible to overlay one field with another.  When a field is overlaid with another in the Format Window, it may cause the overlaid field to disappear from the Format Window.  To restore the field back to its original state, move the top field.

Undoing Your Last Change

If during editing, you make a change to the form in error or a change that you are not satisfied with, you can undo the change by selecting the Edit/Undo menu option.  Any edit action is considered a change, including adding and deleting fields, moving fields and changing attributes by selecting menu options.  Only the last edit action can be undone.

Aligning Fields

Once an area has been selected, the fields within that area may be aligned using the Edit/Align menu option.  Fields can be aligned with respect to the first field in the selected area either horizontally (left/right/center) or vertically (top).  Fields can also be resized to the first field and spaced horizontally or vertically by a specified amount.

Proceed to Chapter B3


CHAPTER B3 - Working with Bitmaps in the Form Header

The first part of the sample form to be designed will be the header.  The header in the sample form will contain a bitmap for the company logo, a form title and fields for the page number and date that the form is printed.

Using a Bitmap to Print the Company Logo on a Form

1.	Because the Bitmap Field will be established in the top left area of the form, you should scroll the form image up and to the left to view the top left corner of the form.  To scroll up, click the mouse on the upward pointing arrow on the vertical scroll bar.  To scroll left, click the mouse on the left pointing arrow on the horizontal scroll bar.  The form will shift to reveal the top left portion.  If you are not using a mouse to design your forms, please refer to the instructions in Chapter B2, How to Use the COBOL FormPrint Forms Editor for information on scrolling through the form with the keyboard.

What is a Bitmap?

A bitmap is a raster based (pixel) graphical image.  Bitmaps are useful to display graphics on your form.  Because bitmaps are images, the graphic image in your bitmap is only limited by your imagination.  One example of a useful bitmap is your company logo as a  header on your form.  Another example might be a picture of an inventory item or an employee photograph.

Bitmaps should be in DIB (Device Independent Bitmap) format and have the extension ".BMP".

Add a Bitmap to the Format Window

1.	To create a bitmap field, click the left mouse button on the "Bitmap" icon or select the Field/Bitmap Menu Bar Option.

If you are using a mouse, move the pointer near the top and left of the Format Window and click once.  The bitmap you are adding will simply be a logo that will be added to the form in order to improve its appearance.

2.	Select the Auxiliary pull down option from the File menu bar option.  The Open pop-up window will be displayed.

You may now type the file name, "FORMPRNT.BMP" directly into the File Name field or scroll through the list box on the Open pop-up window until you highlight the file name.  If you choose to select the file name with the highlight, press the (ENTER) key when the proper file name has been highlighted.

You will now see that the second field in the Field Characteristics Ribbon contains the file name, "FORMPRNT.BMP,."  If you already know the name of the bitmap file which you want to display on the panel, you may also type it directly into the second field on the Field Characteristics Ribbon.  If you type the file name in directly, it is very important to include a comma before the file name.

You should also notice that the Combination Box on the Field Characteristics Window displays the word, "bitmap."  If you want to print 256 color bitmaps from your COBOL FormPrint form, then you may wish to establish the icon field as a "bitmap exact" in the Combination Box.  This has the effect of printing the exact 256 color palette for the bitmap.  Please bear in mind that each 256 color bitmap may have a unique palette, therefore you may get unpredictable results if you attempt to print multiple 256 color bitmap icons on the panel simultaneously.

3.	The bitmap image that you have added to the form is larger than the default bitmap size, so it is necessary to resize the bitmap field to fit the size of the bitmap.  This is accomplished with the mouse or the keyboard using the same method as resizing any other field in the Format Window.

4.	Change the size of the bitmap by double clicking the left mouse button on the field in the Format Window.  You may also select the bitmap field with the (ENTER) key.

A reverse video border will appear around the graphic.  Move the pointer to the bottom right corner until the pointer changes to a diagonally pointing double arrow.  Click and hold the left mouse button.

Drag the pointer to the right and down to change the size of the field.  Release the left button to establish the size of the field.  If the new size is still too small or too large for the graphic, you may repeat this procedure until the field and bitmap are the same size.

If you are using the keyboard to re-size the bitmap field, use the (CTRL-ARROW) keys to increase or decrease the size of the bitmap field once it has been selected.

PLEASE NOTE:  To view the bitmap as it will be printed, Click on the [image]  icon and set the Combination Box on the Field Characteristics Window display to size image to field

5.	After you have changed the size of the bitmap field, move the bitmap image to the top left corner of the form.  Moving a bitmap field is accomplished in the same manner as moving any field type in COBOL FormPrint.  For instructions on moving a field, please refer to Chapter B2, How to Use the COBOL FormPrint Forms Editor.

Your form in the Forms Editor should now look like this:

Proceed to Chapter B4


CHAPTER B4 - Working with Static Text in the Form

What is Static Text?

In the Forms Editor, static text is generally used to represent a field label.  This is how it will be used in this example.  Static text could also be used anytime you want to add information to the form which normally wouldnt change.

Create a Line of Static Text in the Form Definition

1.	Click the mouse pointer on the "Static Text" Icon.  The pointer will change from a diagonal arrow to a vertical arrow, indicating that the icon has been selected.  Move the pointer to the center of the Format Window and click once to establish the static text.  The default value is "Text."

Using the Keyboard

You may also select the Field/Static text Menu Bar Option to create Static Text in the Format Window.  You should use caution when creating  fields using the COBOL FormPrint Menu Bar.  The field will be automatically positioned where the cursor is located in the Format Window.  It is important to first locate the cursor to the desired field location in the Format Window before activating the Menu Bar to create the field.

2.	Move the pointer to the beginning of the second field in the Field Characteristics Ribbon and click the left button.  This is the field in which you will establish the actual text for the static text.  Type "Inventory Report" and delete the extra text characters at the end of the field using the (DEL) key.  Press the (ENTER) key.  You will see that the text in the Format Window has been changed to the new value.

Important Issues Involving Static Text in COBOL FormPrint

It is important that the every static text field used in your COBOL FormPrint forms use a special font other than the system default font.  How to change the font style in your form definition is covered in the next chapter.  Furthermore, any fonts used to develop your form definitions also must exist in the target environment where the printing will take place.  This is necessary, because FormPrint needs to have the specific True Type Font in order to print the typeface correctly on the target environment.  It is generally a good idea to try to limit the fonts you use to design your form to those fonts which are distributed with the standard Windows environment.  These fonts which are always present in a Windows system include:

1.	Courier New

2.	Times New Roman

3.	Arial

PLEASE NOTE:  Don't use raster based fonts such as Bitstream fonts. Unpredictable results can occur.  You should always use Microsoft Windows True Type Fonts.

Multiline Text

Static text can be spread over multiple lines by clicking on the I icon and setting the Combination Box on the Field Characteristics Ribbon to "Multi-line text".  This will cause the text you type in to wrap within the area you have allocated.

Move the Line of Static Text in the Form Definition

If you are not using a mouse to design your forms, please refer to the instructions, in Chapter B2, How to Use the COBOL FormPrint Forms Editor, for information on moving and re-sizing fields with the keyboard.

1.	The only problem with our line of static text is that it should be repositioned to the top center of the Inventory Report form.  Reposition the text by double clicking on the static text in the Format Window.  A reverse video border will appear around the text.  Move the pointer to the center of the static text, click once and hold the left mouse button down.  Drag the mouse pointer to the up until the static text is in the top and center of the Format Window.  Release the left mouse button to establish the new location.

The Inventory Report form should now look like this:

2.	Save the form by selecting the Save pull down option from the File menu bar option.

Proceed to Chapter B5


CHAPTER B5 - Changing the Default Font Size and Type

What is a Font?

A Font is a specific style of typeface used on the form.  Fonts can have a number of attributes including:

•	The typeface name, representing the style of the font, such as Times New Roman or Arial.  This text is displayed using the Times New Roman font.  This text is displayed using the Arial font.

•	The size of the font, expressed in terms of point size or width and height.  This font size is a 10 point size.  This font is a 12 point size.

•	The font pitch which can be a fixed pitch (or monospace) or a proportional pitch (variable) pitch.  All characters in a fixed pitch font use the same amount of horizontal space on the panel.  Characters in a variable pitch font vary in width.  For example, in a variable pitch font, an "i" requires much less horizontal spacing than an "m."

Variable pitch font:	mmiimmiimm

Fixed pitch font:	mmiimmiimm

•	The weight of the font refers to the amount of emphasis which is placed on the typeface.  Fonts may be normal or bold.  Bold fonts are generally darker and thicker.  This is a regular weight font.  This is a bold weight font.

•	Other font attributes can include: italics, strikethrough and underline.

This font is in italics.

This font is in strikethrough.

This font is in underline.

Every static text field has to have a font defined. Only True Type Fonts can be used.

Important Issues Involving Fonts in COBOL FormPrint

It is important that the fonts used to develop your form definitions also exist in the target environment where the printing will take place.  This is necessary, because FormPrint needs to have the specific True Type Font in order to print the typeface correctly on the target environment.  It is generally a good idea to try to limit the fonts you use to design your form to those fonts which are distributed with the standard Windows environment.  These fonts which are always present in a Windows system include:

1.	Courier New

2.	Times New Roman

3.	Arial

PLEASE NOTE:  Don't use raster based fonts such as Bitstream fonts. Unpredictable results can occur.

Add Static Text to the Form

1.	If you have not already done so, add the static text, Inventory Report in the top center of the form.  If you are not sure how to add a line of Static Text to the form, please refer to Chapter B4, Working with Static Text in the Form.

Add a New Font Size and Type

1.	Click the mouse on the "Font" icon.  When the pointer changes to the vertical pointer symbol, click the mouse once more on the words "Inventory Report"  You may also select the Options/Display Menu Bar Option if you prefer using the keyboard.

If you prefer to use the keyboard, make sure that the cursor is positioned on the Inventory Report static text field and select the Options/Display Menu Bar Option.  The Field display pop-up window will then display.  Select the Font pushbutton to establish the special font for the field.

2.	The Fonts pop-up window will be displayed.  The two default fonts are both the system default fonts.  Because the text will be changed to a new typeface, select the "New" Push Button to add a new font to the Forms Editor fonts file.

3.	The "Font" pop-up window will be displayed to allow you to specify a new font.  Add the following to the Font pop-up window:

Font:	Times New Roman
Font style:	Select Bold weight
Size (in points):	20
Effects:	use the default settings
Press the (ENTER) key or click the "Ok" Push Button to return to the Font selection pop-up window.

Change the Default Font

1.	The new font has been added to the bottom of the list of available fonts for your panel.  Highlight the "Times New Roman" font with a width of 12 pixels, a height of 31 pixels, variable pitch and bold weight.  Press the (ENTER) key or click the mouse on the "Ok" Push Button.

2.	The Static Text is now larger than the original text.  This means that you must increase the size of the Static Text field

3.	Increase the size of the Static Text in the same manner as you increase the size of any field.

The Inventory Report form should look like this now:

PLEASE NOTE:  Only True Type Fonts can be used with COBOL FormPrint. Remember that any fonts which you use on your forms in your development environment must also exist in the target environment where the printing  will take place.  That means if you use a True Type font which is unique or one which is not distributed with a standard Windows environment, you must make arrangements to have that font installed on the target environment.

Proceed to Chapter B6


CHAPTER B6 - Changing Colors

Establish a Color for a Form Field

1.	If you have not already done so, add the static text, "Inventory Report" in the top center of the form.  If you are not sure how to add a line of Static Text to the form, please refer to Chapter B4, Working with Static Text in the Form.  To change the color for this field, click on the "Color" icon.  The pointer will change to a vertically pointing arrow.

2.	Move the pointer to the "Inventory Report" static text field and click once.  The Colors pop-up window will display.

If you prefer to use the keyboard, make sure that the cursor is positioned on the "Inventory Report" static text field and select the Options/Display Menu Bar Option to display the Field display pop-up window.  Select the Color pushbutton to establish the special color for the field.  The Colors pop-up window will display.

3.	To establish a new color scheme for the static text field, you must first establish a new color set.  Click once on the "New" Push Button.  The Color Definition pop-up window will display.  The colors used for fields in COBOL FormPrint can be either solid or RGB colors, but  for this example we will use RGB colors for both background and foreground colors.

4.	To select an RGB color for the foreground color, click once on the combination box field under the word, "foreground."   Scroll down the drop down list until you see the option entitled "RGB-specific."  Select the "RGB-specific" foreground color option by clicking on it once.  Now click on the pushbutton with the caption of "RGB."  You will see the color pop-up display.  If you click on the "define custom colors" pushbutton, you can specify a very specific RGB color, but for now, just select a the color in the first column, sixth row, which is the bottom left color (should be black).  Press the (ENTER) key or click on the Ok pushbutton.

Next do the same procedure for the background color.  Select an RGB color of light grey which is the color block on the sixth column and sixth row.

Click on the "Ok" Push Button or press the (ENTER) key to add the new color combination to the list of available colors in your color list.  The new color you have just added will be the last color listed in the color list.  It will also show as a an R-000 G-000 B-000 foreground color (black) and an R-192 G-192 B-192 background color (light grey).  Make sure that the new color is highlighted and click on the "Ok" Push Button or press the (ENTER) key to add the new color combination to the static text field and return to the Format Window.  You will see that the static text field color has now been changed to black text on a light grey background..

Your "Inventory Report" form should now look like this:

6.	Save the forms definition by selecting the Save Pulldown Menu option from the File Menu Bar option.

PLEASE NOTE:  Although you can use any combination of RGB foreground and background colors in FormPrint, you should be careful in choosing colors that will print properly on the target printing devices.

For example:  Although a black foreground on a red background may appear to be acceptable on a color printer, on a grey scale printer, such as a laser printer, the red background will print a very dark color.  This may make the form unreadable.  Try to use color combinations which offer a high degree of contrast between the foreground and background RGB colors.

Proceed to Chapter B7


CHAPTER B7 - Working with Custom Fields

What is a Custom Field?

A Custom Data Entry Field is a field on the form into which you can move data from your COBOL application.

Custom Fields are useful for creating single fields or for creating Repeat Groups.  The next few chapters will demonstrate this type of complex form field.

Add Several Custom Fields to the Form

1.	Using the "Custom Data Entry Field" icon or the Field/Custom field Menu bar Option, add a Custom Field to the right of the Inventory Report static text field.  Make sure you leave enough room between Inventory Report and the Custom Field to place a static text field label. Increase the width of the Custom Field by 10 cell columns.

2.	Make sure that the cursor is still located on the Custom Field you just created and add a COBOL Field Name to the field by typing the following text into the first field in the Field Characteristic Ribbon.

PAGE-NUMBER

Delete any extra characters from the default value of Unnamed custom field if any remain.

If you prefer to use the keyboard, make sure that the cursor is on the Custom Field and press the (ESC) key.  The first field in the Field Characteristic Ribbon will be highlighted.  Type the COBOL Field Name indicated above.

3.	Add a Static Text Field to the immediate left of the Custom Field and change the Caption from the default value of Text to Page:.

4.	Add a second Custom Field directly below the first and increase its size to the same width as the first.  Add the following COBOL Field Name:

REPORT-DATE

Add a Static Text Field to the immediate left of the field and change the Caption from the default value of Text to Date:

5.	Next, create the following four fields in a horizontal arrangement, at least 6 cell rows below our form heading.  Start the first field below the FormPrint bitmap logo and locate the remaining fields to the right of the first in sequential order.  Increase the size of each field according to the following specifications:

Field Name	Size of Field in Cell Columns
ITEM-NUMBER	11 to 12
DESCRIPTION	48 to 49
QUANTITY	9 to 10
PRICE	12 to 13

Your Inventory Report Form should now look like this:

Multiline Fields

Field data (text) can be spread over multiple lines by clicking on the ->| icon and setting the Combination Box on the Field Characteristics Ribbon to "Multi-line display".  This will cause the text you pass from your program to wrap within the area you have allocated to the field.  Remember to set the COBOL format large enough to accommodate the text (see the next chapter for details on setting up this format).

Proceed to Chapter B8


CHAPTER B8 - Working with Input Types

What is an Input Field Type?

An Input Field Type represents the type of allowable data which may be passed to a Custom Data Field.  For both Custom Data Fields, the Input Field Type may be Alphanumeric, Numeric or Date.

A Field Type of Alphanumeric will allow passing of any keyboard character as the name implies.  A Numeric Field Type will only allow passing of numeric data and a Date Field Type will allow passing of a valid date.

Once the Input Field Type is selected, it is still necessary to establish an appropriate COBOL Field Format on the Field Characteristic Ribbon.

Establish a Numeric Field

1.	Place the cursor on the Page Number Field by clicking the mouse on the field or using the (ARROW) Keys to position the cursor.

2.	Using the mouse, select the third field on the Field Characteristic Ribbon and change the COBOL Field Format to 9(3).  If you prefer to use the keyboard, press the (ESC) key once and then press the (TAB) key twice to highlight the COBOL Field Format Field in the Field Characteristic Ribbon.  Press the (ENTER) key or click the mouse once in the Format Window.

Establish the Input Type

3.	Click the mouse on the "Input Type" icon and select the "Numeric" option (second option) in the Combination Box on the Field Characteristics Ribbon.  Press the (ENTER) key or click the mouse once in the Format Window.

If you prefer to use the keyboard, first make sure that the cursor is located directly on the Page Number field.  Press the (ESC) key to activate the Field Characteristics Ribbon.  Press the (TAB) key three times to position the cursor in the Combination Box.  Press the (CTRL-RIGHT ARROW) key combination to switch between the various field behavior options.  When the options for the input type are displayed, use the (DOWN ARROW) key to highlight the "Numeric" option.

4.	Now modify the COBOL Field Formats and Field Input Types for the other fields on the Inventory Report Form as follows:

Field Name	Field Format	Input Type
REPORT-DATE	MM/DD/YYYY	Date
ITEM-NUMBER	X(12)	Alphanumeric
DESCRIPTION	X(25)	Alphanumeric
QUANTITY	9(5)	Numeric
PRICE	$(5).99	Numeric

Your Inventory Report Form should now look like this:

Proceed to Chapter B9


CHAPTER B9 - Working with Field Groups

What is a Field Group?

A field group is used to draw a box around fields.  The interior of this box may also be filled with an RGB color.

Establish a Field Group

1.	Now that you have a number of custom data fields on your form, you should establish a field group.  To accomplish this, position the pointer on the group icon and click the left mouse button once.  Move the pointer to the top right corner of the Static Text for the Page Number Field in the Format Window.  Click once to establish the group box.

Using the Keyboard

You may also select the Group/Group Menu Bar Option to create a Field Group in the Format Window.  You should use caution when creating Groups using the  Menu Bar.  The Group will be automatically positioned where the cursor is located in the Format Window.  It is important to first locate the cursor to the left and immediately above the first field to be included in the Group before activating the Menu Bar to create the field.

Include All Fields Within the Field Group

1.	A box with a reverse video border will appear.  If the box is a thin, line, the Group Box was "de-selected."  To change the size of the Group Box, select it by double clicking the mouse on the thin line until it becomes a thick reverse video line.  You may also select the Group with the keyboard by first positioning the cursor on the Group and pressing the (ENTER) key.

2.	To change the size of the group move the pointer to the lower right corner of the reverse video border until the pointer changes to a diagonally pointing double arrow symbol.  When the pointer becomes a double arrow, you can resize the reverse video border down and to the right, until the Group Border includes the Static Text captions as well as the Custom Data Fields for the Page Number and the Report Date Fields.

Using the Keyboard

If you want to use the keyboard to change the size of the Group in the Format Window, first locate the cursor directly on the Group you created with the (ARROW) keys.

If the Group isn't selected, press the (ENTER) key to select the field.  The field will be surrounded by a reverse video border, indicating that it has been selected.

Change the size of the Group by pressing the (CTRL-RIGHT ARROW) key combination to increase the width and (CTRL-DOWN ARROW) key combination to increase the height.

3.	If you used the mouse to re-size the group, release the left mouse button to establish the Field Group.  The reverse video border will become a thin reverse video box around the fields in the group.  If the box doesn't include all the fields in the group, you may delete the field group and start over or change the size to include all the fields in the group.  For more information on deleting a field, please refer to Chapter B2, How to Use the Forms Editor.

Establish a Fill Color for the Field Group

1.	To change the fill color for the group, click on the "Color" icon.  The pointer will change to a vertically pointing arrow.

2.	Move the pointer to the group you just created and click once.  The Colors pop-up window will display.

If you prefer to use the keyboard, make sure that the cursor is positioned on the group and select the Group/Group Menu Bar Option to display the Group definition pop-up window.  Select the Color pushbutton to establish the special fill color for the group.  The Colors pop-up window will display.

3.	Scroll down the Colors pop-up window until you see the color combination with a foreground color of R-000 G-000 B-000 and a background color of R-192 G-192 B-192.  This is an RGB color of a black foreground on a light grey background.  Select this color combination by double clicking it with the mouse or you can highlight the desired color combination and click on the Ok pushbutton.

4.	Change the color for the static text Page and Date included within the group box.  Use the same color combination as you did when filling the group box with the black foreground and light grey background color.

Also change the color for the two custom fields contained within the group box.

Create Static Text Column Headings in the Form Definition

1.	Click the mouse pointer on the "Static Text" Icon.  The pointer will change from a diagonal arrow to a vertical arrow, indicating that the icon has been selected.  Move the pointer approximately 3 cell rows above the ITEM-NUMBER field and click once to establish the static text.  The default value is "Text."

Using the Keyboard

You may also select the Field/Static text Menu Bar Option to create Static Text in the Format Window.  You should use caution when creating  fields using the COBOL FormPrint Menu Bar.  The field will be automatically positioned where the cursor is located in the Format Window.  It is important to first locate the cursor to the desired field location in the Format Window before activating the Menu Bar to create the field.

2.	Move the pointer to the beginning of the second field in the Field Characteristics Ribbon and click the left button.  Type "Item Number" and delete the extra text characters at the end of the field using the (DEL) key.  Press the (ENTER) key.  You will see that the text in the Format Window has been changed to the new value.

3.	Using the same procedure, add three more static text column headings above the following fields:

DESCRIPTION

QUANTITY

PRICE

Your Inventory Report Form should now look like this:

PLEASE NOTE:  Only RGB Colors can be used in COBOL FormPrint.  Dont try to use solid colors as the results may be unpredictable.  The default color is RGB black on RGB white.

Although you can use any combination of RGB foreground and background colors, you should be careful in choosing colors that will print properly on the target printing devices.

For example:  Although a black foreground on a red background may appear to be acceptable on a color printer, on a grey scale printer, such as a laser, the red background will print a very dark color.  This may make the form unreadable.  Try to use color combinations which offer a high degree of contrast between the foreground and background RGB colors.

Proceed to Chapter B10


CHAPTER B10 - Working with Repeat Groups

What is a Repeat Group?

A Repeat Group is a group of one or more Custom Data Fields with multiple vertical occurrences on the form.

Add a Repeat Group on the Panel

If you are not using a mouse to design your forms, please refer to the instructions, in Chapter B2, How to Use the Forms Editor for information on establishing a Repeat Group with the keyboard.

1.	Select the "Repeat Field" icon to repeat the Custom Fields on the form.  Position the mouse pointer in the top left inside corner of the Item Number Custom Field.  Click the left button once.

2.	Change the size of the Repeat Field Box so that it extends to the right and below all four the Custom Fields in the detail area of your form.  This should include the Item Number, Description, Quantity and Price Custom Data Fields.

3.	Now select the Repeat Field Group Box again by double clicking the left mouse button while the pointer is on the Repeat Field Group Border.  Move the pointer to the bottom dark highlight border of the selected Repeat Field Group Box.

4.	When the pointer symbol changes to a double arrow symbol, click and hold the left mouse button and drag the mouse downward.  This will result in increasing the height of the Repeat Field Group.  Increase the height of the Repeat Field Group until you reach the bottom of the form definition.  You will be at the bottom of the form when the form will not scroll downward any longer.  You can also watch the slider box on the vertical scroll bar.  When the slider box reaches the bottom of the vertical slider bar, you have reached the bottom of the form.

Specify the Total Number of Field Occurrences

1.	With the cursor in the Format Window on the Repeat Field Box, move the mouse pointer to the Number of Occurrences (third field) in the Field Characteristics Ribbon.  This is where you will establish the number of times fields in the Repeat Group will be repeated.  If the field does not have the text, "001 Occurrences," the cursor is not on the Repeat Field Box.

2.	Change the text from "001 Occurrences" to "050 Occurrences" and press the (ENTER) key.  You should see the Custom Fields repeat down the form within the Field Repeat Box.  You should also scroll down to the bottom of the form definition to make sure that all the repeated fields are visible on the form definition.  If a field is not visible on the form definition, it will not be printed on the form.  If youre not sure whether or not all the repeated fields are visible, reduce the number of occurrences to 40 or 45.  You should see a difference in the number of repeated rows if you have designed a form that is a standard A4 or 8.5 x 11 paper size.

After you have repeated the fields, it appears that the field borders are overlapping one another.  This doesnt cause any problems for our form, because the borders will be removed.  The next chapter will cover the issue of field borders.

Your Inventory Report form should look like this now:

Proceed to Chapter B11


CHAPTER B11 - Changing the Field Border

What is the Field Border?

A Field Border is the thin line which surrounds various form fields in COBOL FormPrint.  For example, both a Custom Data Entry Field and a Field Group contain a line which surrounds the data that is displayed in these fields.

COBOL FormPrint allows you to keep the default border, replace the default border with a 3-dimensional border or remove the border from the field.

Form fields which allow modification of the border include:

•	Custom Data Fields

•	Field Groups

•	Repeat Groups

Eliminate the Border for a Field

1.	The Field Borders in the Inventory Report form should be removed.  For these types of field, the border is not necessary.  Position the mouse pointer on the Page Number Custom Data Entry Field in the Repeat Field Group and click once to move the cursor to the field.

2.	Select the "Border" icon and choose "No border" (second option) in the Combination Box on the Field Characteristic Ribbon.  You may also use the (ARROW) keys in the Combination Box on the Field Characteristics Ribbon to select the appropriate option.

3.	Press the (ENTER) key or move the mouse pointer back to the Format Window and click once more.  The border should disappear.

4.	Repeat this process for the Report Date Field as well as the Item Number, Description, Quantity and Price Fields in the Repeat Field Group

If you prefer to remove the border for the Field Repeat Group, you may do so as well, but for purposes of this tutorial, it will be left as the default border.

The Inventory Report Form should look like this now:

PLEASE NOTE:  You may notice that there are two other border types, including 3D Border and Thin 3D Border.  The FormPrint forms editor allows you to replace the default border with a 3-dimensional border or thin 3-dimensional border for Custom Data Fields, Field Groups and Repeat Fields.

Proceed to Chapter B12


CHAPTER B12 - Working with Check Boxes

What is a Check Box?

A Check Box is an option field which prints a symbol and associated text.  The Check Box symbol has two different properties, checked and unchecked which indicates whether or not the associated text option has been selected.  Check Boxes are generally used when you must provide the recipient of the form with information on which options have been selected from a limited set of choices.  It is important to note that Check Boxes are generally used when any number of options may be selected as opposed to Radio Buttons which are generally mutually exclusive choices.

By moving the correct value to the program data area which represents the Check Box, you can then decide if a checked or an unchecked check box should be printed.

Add a Check Box to the Form

1.	To create a Check Box field, click the mouse on the "Check Box" icon and click just below the left corner of the Inventory Report Static Text Field.

To establish a Check Box field using the keyboard, first position the cursor beneath the left corner of the Inventory Report Static Text Field and select the Field/Checkbox Menu Bar Option.

Assign a Caption to the Check Box

1.	Move the mouse pointer to the Check Box Caption Field on the Field Characteristics Ribbon.  This is the second field from the left with the default value of "Option."  Type "Final Year End Inventory Report" and delete the default caption (Option).  Press the (ENTER) key to return to the Format Window.

Assign Program Values to the Check Box

1.	To display the Values pop-up window, select the Options/Values menu option.

2.	Position the cursor in the Discrete Values entry area.  Type "Y", then press the (DOWN ARROW) key, then type "N", then press (ENTER) or click "OK".

3.	To turn the Check Box on from your program, set the generated Check Box field to "Y", to turn it off, set the field to "N".

The Inventory Report Form should now look like this:

Proceed to Chapter B13


CHAPTER B13 - Working with Radio Buttons

What is a Radio Button?

A Radio Button is an option field which prints a symbol and associated text.  The Radio Button symbol has two different properties, on and off which indicates whether or not the associated text option has been selected.  Radio Buttons are typically used when you must provide the recipient of the form with information on which single option has been selected from a limited set of choices.  It is important to note that Radio Buttons are generally used when only one option may be selected as opposed to Check Boxes which are normally allow one or more options to be selected.

By moving the correct value to the program data area you can then decide if an on or an off Radio Button should be printed on your form.

Add a Radio Button to the Form

1.	To create a Radio Button field, click the mouse on the "Radio Button" icon, move the pointer to the Format Window  and  click once just below the Check Box Field you created in the last chapter..

If you prefer to use the keyboard to create a Radio Button Field, first position the cursor .  Select the Field/Radiobutton Menu Bar Option to create the default Radio Button Field.

Assign a Caption to the Radio Button

1.	Move the mouse pointer to the Radio Button Caption Field on the Field Characteristics Ribbon.  This is the second field from the left with the default value of "Yes."  Type "Pennsylvania Warehouse" and delete the default caption (Yes).

Create a second Radio Button directly below the first and assign it a caption of Stockholm Warehouse.

Assign Program Values to the Radio Button

1.	To display the Values pop-up window, select the Options/Values menu option.

2.	Position the cursor in the Discrete Values entry area.  Type "Y", then press the (DOWN ARROW) key, then type "N", then press (ENTER) or click "OK".

3.	To turn the Radio Button on from your program, set the generated Radio Button field to "Y", to turn it off, set the field to "N".

The Inventory Report Form should now look like this:

Proceed to Chapter B14


CHAPTER B14 - Guidelines for Creating Forms

Introduction

The Forms Editor makes it a fairly simple task to design forms.  As you become more familiar with the editor, however, you may be tempted to create forms that are more and more sophisticated.  The following information will make your task a little easier.

Spacing of Items within the Form

As you use the Forms Editor, you will notice that items which you place in the form tend to snap to the grid which fills the Forms Editor window.  This makes it easy to line items up within the form but may make it hard to achieve the desired spacing between items.  To avoid this problem, you can reset the cell size (Form/Size) to a lower value than the default size of 8 pixels by 16 pixels.  If you set the size to 1 by 1, you will be able to position at any point within the form.  It is best, however, to use as big a cell size as possible because the smaller the cell size, the more tedious it is to align items.

Lines and Boxes

Individual lines can be created using static fields, setting the type of the field to be a line rather than text.  However, lines on a form are usually in the form of boxes around different areas on the form.  It is normally best to  use a group to create such a box.  If you have multiple adjacent boxes, as in a spreadsheet for instance, use multiple groups.  It does not matter if the edge of one group overlays the edge of the next group.

Fields are by default created with boxes (borders) around them.  Normally it is appropriate to delete these borders.  If you are creating a form that  uses  individually boxed fields, again like a spreadsheet,  consider retaining these field borders.  You can often use a repeat group to generate multiple instances of  a bordered field to create the spreadsheet look.

Spreadsheets and Grids

When defining a large grid, the first method above (multiple group boxes) may run into trouble - FormPrint cannot deal with so many individual fields and groups.  The second method (repeat group with bordered fields) works better but it is sometimes hard to get the field borders overlapping each other so that the grid looks nice and clean.

There is an option for repeat groups that makes this task a little easier.  If the vertical or horizontal gap (Group/Repeat menu option) is set to -1 and the form cell size (Form/Size menu option) is set to 1 by 1, the appropriate field borders will overlap properly.  Once the repeat group has been defined in this way, resizing the first field will resize the rest of the grid cells automatically.  If you have multiple base fields in the grid, be sure to give all these fields the same height.

Colors and Shading

Individual items can be colored and the color will be reflected on the printed form either by shading or the actual color if you are using a color printer.  The most common use of color, however, is to provide shading for a group box.  To do this, set the color of the group and the fields within the group.

Foreground and background colors may be either solid or RGB values in FormPrint.

Fonts

To ensure that the printed form matches as close as possible the form as defined using the Forms Editor, it is best to only use True Type fonts.

Repeating Fields

If you have a lot of data fields on a form, consider using repeat groups wherever possible.  It is much easier to define one field and repeat it than to define the same field multiple times.

Data Field Formatting

Field formatting is defined using COBOL picture clauses and is fairly comprehensive.  This includes numeric formatting (Z,ZZ9.99, etc.), date formatting (MM/DD/YY, etc.) and special formats (999-99-9999, etc.).  Use this capability wherever possible rather than trying to reformat data within your program.

Radio Buttons and Check Boxes

FormPrint supports the printing of check boxes and radio buttons on your forms.  It is possible to use the same logic to check whether a radio button or check box is on or off.  Radio button fields use two bitmaps which must be distributed with your final forms based application.  The names of these buttons are RON.BMP (radio button on) and ROFF.BMP (radio button off).  These should be placed in the current directory or a directory that is defined in the configuration variable QPRDIR.  See Appendix A for details on configuration variables.

Bitmaps

You can use bitmaps in your forms. The format is DIB (device independent bitmap) and bitmap files should have the extension .BMP. These files should be placed in the current directory or a directory that is defined in the configuration variable QPRDIR.  See Appendix A for details on configuration variables.

Proceed to Chapter C1


CHAPTER C1 - Introduction to Programming

This part of the user guide explains how to program with COBOL FormPrint.  Because COBOL FormPrint makes printing forms inherently simple, there is fortunately not too much to cover here - once you have defined your form, as explained in Part B, there is not much left to do.  Chapter C1 introduces programming with COBOL FormPrint.

Chapters C2 and C3 discuss code that can be generated by the forms editor.  Subsequent chapters discuss other miscellaneous issues.

Calling COBOL FormPrint

All CALLs to the COBOL FormPrint runtime are made in the following format:

CALL "QPR" USING function-area parameter-area.

Function Area

The function specifies the type of operation you wish the runtime to perform.  For example:

SELECT-PRINTER or PRINT-PAGE

The function parameter holds information which the runtime references during the operation.  For example, the SELECT-PRINTER function parameter allows you to select the specific printer device to be used in the print job.

The function areas and parameter areas that are used are stored in a copy book called QPR.CPY.

The function area looks like this:

  01  QPR-FUNCTIONS.

      03  QPR-SELECT-PRINTER    PIC S9(4) COMP-5 VALUE 0.

      03  QPR-PRINT-PAGE        PIC S9(4) COMP-5 VALUE 1.

      03  QPR-END-PRINT         PIC S9(4) COMP-5 VALUE 2.

      03  QPR-ABOUT             PIC S9(4) COMP-5 VALUE 3.

      03  QPR-INIT              PIC S9(4) COMP-5 VALUE 4.

How to Initialize FormPrint and Open a Form File

The first thing to be done is to Initialize FormPrint  and open a forms file. This is done with the function QPR-INIT and the area QPR-INIT-AREA.

1.     MOVE LOW-VALUES TO QPR-INIT-AREA.

2.     MOVE "n"        TO QPR-METHOD.

3.     MOVE "C:\FORMEDIT\UTV\AFORM.PAN"      TO QPR-FILE.

4.     CALL "QPR"  USING

                              QPR-INIT

                              QPR-INIT-AREA.

It's very important to initialize the areas with LOW-VALUE before moving values to them.

QPR-METHOD gets the value 'n' to indicate that internal FormPrint routines should be used to format the page.

QPR-FILE should contain the name of the forms file to be opened.

How to Select a Printer

Before actual printing can begin, a printer must be selected.  The easiest way to do this is to select the default printer:

1.     MOVE    LOW-VALUES     TO  QPR-AREA.

2.     MOVE "d"               TO  QPR-DIALOG.

3.     CALL "QPR" USING

                              QPR-SELECT-PRINTER

                              QPR-AREA.

Initialize QPR-AREA to LOW-VALUES.

Set QPR-DIALOG to 'd' to select the default printer.

See chapter C4 for details on selecting the printer in other ways.

How to Print a Form

Once the printer has been selected, a form can be printed:

1.     MOVE    LOW-VALUES     TO  form-DATA

       MOVE    LOW-VALUES     TO  form-FIELDS

       MOVE    LOW-VALUES     TO  form-COLRS

       MOVE    LOW-VALUES     TO  form-TYPES

       MOVE    "form"         TO  form-NEXT-PANEL

2.     CALL "QPR" USING

                              QPR-PRINT-PAGE

                              form-CONVERSE-DATA.

Initialize the generated form data area and set the form name.

Print the form.  The same form can be printed multiple times or other forms can be printed without the need to select the printer again.

How to Finish Up

When all forms have been printed, the printer must be deselected and the forms file closed:

1.     CALL "QPR"  USING

                              QPR-END-PRINT

                              QPR-NULL-PARM.

If you need to print more forms after making the call, you must reselect the printer before continuing.

Proceed to Chapter C2


CHAPTER C2 - The Generated Program Data Division

This program describes items found in the Working-Storage section of the generated program

Function Codes and Parameter area

COPY "QPR.CPY".

This COBOL 'copy-book' contains all function codes and parameter areas

needed to use FormPrint. The expanded copy looks like this :

*****************************

* Standard copy for QPR.DLL *

*****************************

01  QPR-FUNCTIONS.

    03  QPR-SELECT-PRINTER         PIC S9(4) COMP-5 VALUE 0.

    03  QPR-PRINT-PAGE             PIC S9(4) COMP-5 VALUE 1.

    03  QPR-END-PRINT              PIC S9(4) COMP-5 VALUE 2.

    03  QPR-ABOUT                  PIC S9(4) COMP-5 VALUE 3.

    03  QPR-INIT                   PIC S9(4) COMP-5 VALUE

01  QPR-AREA.

    05  QPR-RET-CODE               PIC S9(4) COMP-5.

    05  QPR-DATA.

        10  QPR-DIALOG             PIC X.

        10  QPR-DOC-NAME           PIC X(30).

        10  QPR-ORIENTATION        PIC X.

        10  QPR-COPIES             PIC S9(4) COMP-5.

        10  QPR-STRETCH            PIC X.

        10  QPR-DEVICE-LIST        PIC X(800).

        10  QPR-DRIVER             PIC X(32).

        10  QPR-OUTPUT             PIC X(32).

01  QPR-VERSION.

    05  QPR-QE-RET                 PIC S9(4) COMP-5.

    05  QPR-QE-DATA.

        10  QPR-VERSION-INFO       PIC X(80).

        10  QPR-DISPLAY-BOX        PIC X.

01  QPR-INIT-AREA.

    05  QPR-QI-RET                 PIC S9(4) COMP-5.

    05  QPR-QI-DATA.

        10  QPR-LIBRARY            PIC X.

        10  QPR-METHOD             PIC X.

        10  QPR-FILE               PIC X(80).

        10  FILLER                 PIC X(118).

01  QPR-NULL-PARM.

    03 QPR-NP-RET-CODE             PIC S9(4) COMP-5.

Parameter for PRINT-PAGE Function

COPY "form.CPY".

********************************

* parameter for PRINT-PAGE     *

********************************

 01  form-CONVERSE-DATA.

     05  form-RET-CODE

                                   PIC S9(4) COMP-5.

     05  form-LENS.

         10  form-LEN-LEN

                                   PIC S9(4) COMP-5 VALUE +20.

         10  form-IP-NUM-LEN

                                   PIC S9(4) COMP-5 VALUE +40.

         10  form-IP-CHAR-LEN

                                   PIC S9(4) COMP-5 VALUE +106.

         10  form-OP-NUM-LEN

                                   PIC S9(4) COMP-5 VALUE +6.

         10  form-OP-CHAR-LEN

                                   PIC S9(4) COMP-5 VALUE +2.

         10  form-FIELD-LEN

                                   PIC S9(4) COMP-5 VALUE +2121.

         10  form-COLR-LEN

                                   PIC S9(4) COMP-5 VALUE +178.

         10  form-TYPE-LEN

                                   PIC S9(4) COMP-5 VALUE +178.

         10  FILLER

                                   PIC S9(4) COMP-5 VALUE +0.

         10  FILLER

                                   PIC S9(4) COMP-5 VALUE +0.

     05  form-DATA.

******** form-IP-NUM-DATA ********

         10  form-KEY

                                   PIC S9(4) COMP-5.

         10  form-NEXT-FLD-ID

                                   PIC S9(4) COMP-5.

         10  form-NEXT-FLD-NUM

                                   PIC S9(4) COMP-5.

         10  form-NEXT-TAB-NUM

                                   PIC S9(4) COMP-5.

         10  form-NEXT-OCCURS

                                   PIC S9(4) COMP-5.

         10  form-LAST-FLD-ID

                                   PIC S9(4) COMP-5.

         10  form-LAST-FLD-NUM

                                   PIC S9(4) COMP-5.

         10  form-LAST-TAB-NUM

                                   PIC S9(4) COMP-5.

         10  form-LAST-OCCURS

                                   PIC S9(4) COMP-5.

         10  form-MENU-ID

                                   PIC S9(4) COMP-5.

         10  form-ROW-COL-SW

                                   PIC S9(4) COMP-5.

         10  form-CURSOR-ROW

                                   PIC S9(4) COMP-5.

         10  form-CURSOR-COL

                                   PIC S9(4) COMP-5.

         10  form-LAST-ROW

                                   PIC S9(4) COMP-5.

         10  form-LAST-COL

                                   PIC S9(4) COMP-5.

         10  form-DISP-SW

                                   PIC S9(4) COMP-5.

         10  form-NEXT-VERT

                                   PIC S9(4) COMP-5.

         10  form-LAST-VERT

                                   PIC S9(4) COMP-5.

         10  form-NEXT-HOR

                                   PIC S9(4) COMP-5.

         10  form-LAST-HOR

                                   PIC S9(4) COMP-5.

******** form-IP-NUM-DATA ********

         10  form-NEXT-PANEL

                                   PIC X(8).

         10  form-NEXT-FIELD

                                   PIC X(30).

         10  form-LAST-FIELD

                                   PIC X(30).

         10  form-MENU-OPTION

                                   PIC X(30).

         10  form-SWITCH-SW

                                   PIC X.

         10  form-SIZE-SW

                                   PIC X.

         10  form-MOUSE-SW

                                   PIC X.

         10  form-CAPTURE-SW

                                   PIC X.

         10  form-WAIT-SW

                                   PIC X.

         10  form-CURS-SW

                                   PIC X.

******** form-OP-NUM-DATA ********

         10  form-PAN-POS-SW

                                   PIC S9(4) COMP-5.

         10  form-PAN-ROW

                                   PIC S9(4) COMP-5.

         10  form-PAN-COL

                                   PIC S9(4) COMP-5.

******** form-OP-CHAR-DATA ********

         10  form-NEW-WINDOW

                                   PIC X.

         10  form-CUR-COLR-SW

                                   PIC X.

******** form-OP-VAR-DATA ********

     05  form-FIELDS.

         10  form-PAGE-NUMBER

                                   PIC 9(003).

         10  form-REPORT-DATE

                                   PIC 9(0008).

         10  form-FIELD-ID-104

                                   PIC X(0001).

             88  form-FIELD-ID-104-YES

                                   VALUE "0".

             88  form-FIELD-ID-104-NO

                                   VALUE "1".

         10  form-FIELD-ID-105

                                   PIC X(0001).

             88  form-FIELD-ID-105-YES

                                   VALUE "0".

         10  form-FIELD-ID-106

                                   PIC X(0001).

             88  form-FIELD-ID-106-YES

                                   VALUE "0".

         10  FILLER OCCURS 43.

             15  form-ITEM-NUMBER

                                   PIC X(0012).

             15  form-DESCRIPTION

                                   PIC X(0025).

             15  form-QUANTITY

                                   PIC 9(005).

             15  form-PRICE

                                   PIC 9(05)V9(02).

     05  form-COLRS.

         10  form-PAGE-NUMBER-C

                                   PIC X.

         10  form-formprnt-C

                                   PIC X.

         10  form-REPORT-DATE-C

                                   PIC X.

         10  form-FIELD-ID-104-C

                                   PIC X.

         10  form-FIELD-ID-105-C

                                   PIC X.

         10  form-FIELD-ID-106-C

                                   PIC X.

         10  FILLER OCCURS 43.

             15  form-ITEM-NUMBER-C

                                   PIC X.

             15  form-DESCRIPTION-C

                                   PIC X.

             15  form-QUANTITY-C

                                   PIC X.

             15  form-PRICE-C

                                   PIC X.

     05  form-TYPES.

         10  form-PAGE-NUMBER-T

                                   PIC X.

         10  form-formprnt-T

                                   PIC X.

         10  form-REPORT-DATE-T

                                   PIC X.

         10  form-FIELD-ID-104-T

                                   PIC X.

         10  form-FIELD-ID-105-T

                                   PIC X.

         10  form-FIELD-ID-106-T

                                   PIC X.

         10  FILLER OCCURS 43.

             15  form-ITEM-NUMBER-T

                                   PIC X.

             15  form-DESCRIPTION-T

                                   PIC X.

             15  form-QUANTITY-T

                                   PIC X.

             15  form-PRICE-T

                                   PIC X.

*************

* field ids *

*************

 01  form-IDS.

         05  form-PAGE-NUMBER-I

                                   PIC S9(4) COMP-5 VALUE +2.

         05  form-formprnt-I

                                   PIC S9(4) COMP-5 VALUE +1.

         05  form-REPORT-DATE-I

                                   PIC S9(4) COMP-5 VALUE +3.

         05  form-FIELD-ID-104-I

                                   PIC S9(4) COMP-5 VALUE +104.

         05  form-FIELD-ID-105-I

                                   PIC S9(4) COMP-5 VALUE +105.

         05  form-FIELD-ID-106-I

                                   PIC S9(4) COMP-5 VALUE +106.

         05  form-ITEM-NUMBER-I

                                   PIC S9(4) COMP-5 VALUE +4.

         05  form-DESCRIPTION-I

                                   PIC S9(4) COMP-5 VALUE +5.

         05  form-QUANTITY-I

                                   PIC S9(4) COMP-5 VALUE +6.

         05  form-PRICE-I

                                   PIC S9(4) COMP-5 VALUE +7.

This area is used when calling FormPrint with function QPR-PRINT-PAGE. The forms name precedes all the data items so that multiple forms can be processed in the sample program. In this program one data item is referenced : NEXT-PANEL is set to the name of the form to be printed.

You are not permitted to alter any of the length items in the xxxx-LENS area.

If you wish to suppress the generation of the forms name prefix, edit the UIB.CBX file to remove all "$001-" strings from the file, except on those lines containing an 01-level.

Proceed to Chapter C3


CHAPTER C3 - The Generated Program Procedure Division

This chapter describes the logic found in the Procedure Division of the generated program. This logic is quite simple but illustrates the code that must be included in a program to print a form.

Init FormPrint

     PERFORM INIT.

The first thing to be done is to Initialize FormPrint to work in a stand alone manner.  This is done in the INIT section.

**************

 INIT SECTION.

**************

     MOVE LOW-VALUES TO QPR-INIT-AREA.

     MOVE "n"        TO QPR-METHOD.

     MOVE "C:\FORMEDIT\UTV\AFORM.PAN"      TO QPR-FILE.

     CALL "QPR" USING

                QPR-INIT

                QPR-INIT-AREA.

     IF QPR-QI-RET  = 0

        MOVE    LOW-VALUES      TO  form-DATA

        MOVE    "form"          TO  form-NEXT-PANEL

        MOVE LOW-VALUES TO form-FIELDS

        MOVE LOW-VALUES TO form-COLRS

        MOVE LOW-VALUES TO form-TYPES

     ELSE

        MOVE "N" TO WS-PRINT-OK

     END-IF.

It's very important to initialize the areas with LOW-VALUE before moving values to them.

QPR-METHOD gets the value 'n' to indicate that internal FormPrint routines should be used to format the page.

QPR-FILE should contain the name of the forms file to be opened.

     CALL "QPR" USING

                QPR-INIT

                QPR-INIT-AREA.

This is the call to open the file and initialize FormPrint.

If ret-code is zero, move LOW-VALUES to xxxx-FIELDS, xxxx-COLRS,

xxxx-TYPES.

Selecting the printer

     PERFORM PRINT-form.

***********************

 PRINT-form SECTION.

***********************

     MOVE    LOW-VALUES    TO  QPR-AREA.

     MOVE "Document 1"     TO  QPR-DOC-NAME.

     MOVE "p"              TO  QPR-ORIENTATION.

     MOVE "y"              TO  QPR-DIALOG.

Initialize QPR-AREA to LOW-VALUES.  Move the name of the document to QPR-DOC-NAME.  Decide what orientation to use and choose a method of selecting the printer. In this example, we have set QPR-ORIENTATION to 'p' for portrait and set QPR-DIALOG to 'y' to invoke the Windows Print Dialog box.  We then issue the call to select the printer.

     CALL "QPR"   USING

                            QPR-SELECT-PRINTER

                            QPR-AREA.

If the return code is zero, continue on to print the pages.

     IF  QPR-RET-CODE = 0

         MOVE SPACE      TO  WPRINT-OK

     * add logic here to fill variables declared in form-fields

         PERFORM PRINT-PAGES

*********************

 PRINT-PAGES SECTION.

*********************

     CALL    "QPR"           USING

                             QPR-PRINT-PAGE

                             form-CONVERSE-DATA.

Before you issue this call to QPR, you must move values to the fields that are going to be printed.  This is done by moving values to the items in the data area, xxxx-FIELDS.  Issue a call to QPR with the function QPR-PRINT-PAGE and the generated xxxx-CONVERSE-DATA area.

To end the printing session, call QPR with the function QPR-END-PRINT and QPR-NULL-PARM.

         CALL "QPR"  USING  QPR-END-PRINT

                            QPR-NULL-PARM

Proceed to Chapter C4


CHAPTER C4 - Selecting the Printer with COBOL FormPrint

Methods for Selecting the Printer

Chapter 1 described how to select the default printer and Chapter 4 described using the Print Dialog Box to select the printer.  This chapter discusses these two methods in a little more detail and describes still one more method.

The following are the three methods for selecting the printer:

Method 1	The Windows Print Dialog Box, or

Method 2	By choosing the default printer defined in the WIN.INI [windows] section, or

Method 3	Get all available printers defined in the [devices] section of the WIN.INI file and select one of these.

The First Method for Selecting the Printer

(Using the Windows Print Dialog Box)

1.	MOVE "y" TO QPR-DIALOG.

2.	MOVE "< document name >" TO QPR-DOC-NAME.

3.	CALL "QPR" USING QPR-SELECT-PRINTER QPR-AREA.

If you are using method 1, you can use the features of the Print Dialog Box to choose paper orientation, paper size and other features supported by the default printer driver.

Explanation of the First Method

1.	Move "y" to the QPR-DIALOG parameter to display the Print Dialog Box.

2.	Enter the name of your document, if you want it to be displayed with the name in the print queue.

3.	CALL QPR using the QPR-SELECT-PRINTER function parameter and the QPR-AREA data parameter.

A Flowchart of the First Method for Selecting the Printer

The Second Method for Selecting the Printer

(Using the default printer)

1.	MOVE "d" TO QPR-DIALOG.

2.	MOVE "<document name>" TO QPR-DOC-NAME

3.	MOVE  "l" TO QPR-ORIENTATION.

4.	MOVE "2" TO QPR-COPIES.

5.	CALL "QPR" USING QPR-SELECT-PRINTER QPR-AREA.

The return value is available in QPR-RET-CODE.  If the value of the return code is larger than zero, an error condition has occurred.

Explanation of the Second Method for Selecting the Printer

1.	Move "d" to QPR-DIALOG to choose the default printer.  Setting QPR-DIALOG TO LOW-VALUE will also cause the default printer to be chosen.

2.	Enter the name of your document if you want the document name to be displayed in the print queue.

3.	Choose paper orientation by moving "p" ( Portrait ), "l" (Landscape) to the field QPR-ORIENTATION. Portrait is default.

4.	If you want more than one copy, move the number you want to the field QPR-COPIES.

5.	Call FormPrint with the function QPR-SELECT-PRINTER and the area QPR-AREA.

A Flowchart of the Second Method for Selecting the Printer

The Third Method for Selecting the Printer

 (Selecting from a list of printers)

1.	MOVE "s" TO QPR-DIALOG.

2.	First call to get the printer list:

CALL "QPR" USING QPR-SELECT-PRINTER QPR-AREA.

Return code is -10 if QPR managed to get printers. This must not be altered. QPR needs this value in the next call.

3.	FormPrint returns the list to QPR-DEVICE-LIST. Device names are separated with semicolon ( ; ), and should be unpacked with UNSTRING.

4.	QPR-DEVICE-LIST is unpacked to a table:

WS-TABLE PIC X(80) OCCURS 10.

The printers will be listed in the order they occur in WIN.INI.

5.	Choose which printer you want to use:

MOVE LOW-VALUE TO QPR-DEVICE-LIST.

STRING WS-TABLE (3) DELIMITED BY SIZE

INTO QPR-DEVICE-LIST.

6.	Enter paper orientation and number of copies as described 	above.

7.	Second call to choose printer:

CALL "QPR" USING QPR-SELECT-PRINTER QPR-AREA.

Explanation of the Third Method for Selecting the Printer

A value of 's' will return a list with all available printers defined in the [devices] section in WIN.INI.

From this list you can choose a printer and move it to the parameter QPR-DEVICE-LIST.  To choose the specific printer desired, you should CALL QPR a second time with the function parameter QPR-SELECT-PRINTER.  The return code after the first call should be -10 which must not be changed.

If you want to assign a print job to a specific printer, and if you know which printer is going to be used, you can use the following technique:

CALL QPR with the printer name in QPR-DEVICE-LIST and the value -10 in the QPR-RET-CODE parameter.

A Flowchart of the Third Method for Selecting the Printer

Setting Additional Printer Attributes

Additional printer attributes can be set when selecting the printer by using the function QPR-SELECT-PRINTER-EX instead of QPR-SELECT-PRINTER.  This function works in exactly the same way as QPR-SELECT-PRINTER except that it takes into account additional data items at the end of QPR-AREA.  These are defined as follows:

       01  QPR-AREA.

           05  QPR-RET-CODE          PIC S9(4)   COMP-5.

           05  QPR-DATA.

               ...

               10  QPR-DATA-EX.

                   15  QPR-PAPER-SIZE PIC X.

                       88  QPR-LETTER            VALUE X"01".

                       88  QPR-LEGAL             VALUE X"05".

                       88  QPR-A4                VALUE X"09".

                       88  QPR-B5                VALUE X"0D".

                   15  QPR-PAPER-SOURCE PIC X.

                       88  QPR-UPPER-TRAY        VALUE X"01".

                       88  QPR-LOWER-TRAY        VALUE X"02".

                       88  QPR-MIDDLE-TRAY       VALUE X"03".

                       88  QPR-MANUAL-FEED       VALUE X"04".

                   15  QPR-PREVIEW   PIC X.

                       88  QPR-DO-PREVIEW        VALUE "y".

                   15  FILLER        PIC X(99).

For example, you could use the following code to set the paper size

and source:

           MOVE LOW-VALUES TO QPR-AREA.

           MOVE "d" TO QPR-DIALOG.

           SET QPR-LEGAL TO TRUE.

           SET QPR-LOWER-TRAY TO TRUE.

           CALL "QPR" USING QPR-SELECT-PRINTER-EX QPR-AREA.

For details on using the QPR-PREVIEW item, see Chapter C8.

Proceed to Chapter C5


CHAPTER C5 - Miscellaneous Issues

Completing the Printing Job

When you have finished printing forms using the QPR-PRINT-PAGE function it is very important to finish up by using the QPR-END-PRINT function. This function will make sure that all forms are printed, close your forms file and free up memory so that new documents may be printed.  This is how to make the call:

CALL "QPR" USING QPR-END-PRINT QPR-NULL-PARM.

Checking the Version Number of FormPrint

It may be useful to use know the version number of the QPR DLL that you are using.  To find this out, use the QPR-ABOUT function:

CALL "QPR" USING QPR-ABOUT QPR-VERSION.

The QPR-VERSION parameter returns the FormPrint version information.

The information is presented as text separated by ';' (semi colons).  For example, Version 1.1d for CA-Realia;Copyright 1995-1996;........

 The area looks like this:

01  QPR-VERSION.

    05  QPR-QE-RET             PIC S9(4)   COMP-5.

    05  QPR-QE-DATA.

        10  QPR-VERSION-INFO   PIC X(80).

        10  QPR-DISPLAY-BOX    PIC X.

Normally the version information will also be displayed in a message box. If you do not want this, set QPR-DISPLAY-BOX to n.

Creating a Log File

It is also possible to force QPR to create a log file recording the actions that it took.  To do this, set the configuration variable QPRLOG to 1 (see Appendix A for details on configuration variables). The log file is called QPR.LOG and will be placed  in your working directory.

This log file will allow you to follow the steps executed by FormPrint and also see how much time was used in the printing process.  The log file is very useful for debugging purposes.

PLEASE NOTE:  FormPrint will not delete this file.  The file will continue to be appended as long as the QPRLOG configuration variable is set to 1.

Proceed to Chapter C6


 CHAPTER C6 - Dynamically Modifying the Form at Runtime

Certain characteristics of a form can be modified at runtime.  These characteristics are as follows:

- Bitmap image assigned to a Bitmap field

- Font assigned to a field

- Color assigned to a field

Changing a Bitmap Image

Copy the qprbmpws.cpy file into your working-storage and the qprbmp.cpy file into your procedure division.

Before calling the QPR-PRINT-PAGE function, do the following for each field to be changed:

           MOVE form-name TO QPRBMP-PANEL.

           MOVE field-id TO QPRBMP-ID.

           MOVE new-bitmap-name TO QPRBMP-NAME.

           PERFORM SET-QPRBMP.

The field-id is a generated item at the end of the form-name.CPY file and is made up of the field-name with a -I suffix.

After QPR-PRINT-PAGE, do the following (once only):

           PERFORM CLEANUP-QPRBMP.

Changing a Font

Copy the qprfntws.cpy and qprbmpws.cpy files into your working-storage and the qprfnt.cpy file into your procedure division.

Before calling the QPR-PRINT-PAGE function, do the following for each field to be changed:

           MOVE form-name TO QPRBMP-PANEL.

           MOVE field-id TO QPRBMP-ID.

           MOVE new-font-id TO QPRFNT-FONT-ID.

           PERFORM SET-QPRFNT.

The field-id is a generated item at the end of the form-name.CPY file and is made up of the field-name with a -I suffix.

The new-font-id is the number assigned to the desired font as displayed on the font listing in the editor.  If the size of the new font is greater than the original font, remember to allow extra space when sizing the field in the editor.

After QPR-PRINT-PAGE, do the following (once only):

           PERFORM CLEANUP-QPRFNT.

Changing a Color

Copy the qprclrws.cpy and qprbmpws.cpy files into your working-storage and the qprclr.cpy file into your procedure division.

Before calling the QPR-PRINT-PAGE function, do the following for each field to be changed:

           MOVE form-name TO QPRBMP-PANEL.

           MOVE field-id TO QPRBMP-ID.

           MOVE new-color TO QPRCLR-COLOR.

           PERFORM SET-QPRCLR.

The field-id is a generated item at the end of the form-name.CPY file and is made up of the field-name with a -I suffix.

The new-color is the number assigned to the desired color as displayed on the color listing in the editor.  This number must be represented in hexadecimal notation - for example, if the number of the color is shown as 11 on the color listing, new-color should be X"0B".

After QPR-PRINT-PAGE, do the following (once only):

           PERFORM CLEANUP-QPRCLR.

Proceed to Chapter C7


CHAPTER C7 - Multi-Form Pages

Sometimes, not only the data printed on a page may vary but also the overall format of the page.  This situation can usually be dealt with by using different forms for each page, but this solution is not always convenient.  For example, suppose you have an invoice and the format of the detail lines varies depending on the item being listed.  It may be impossible to define multiple forms to cover all possible combinations of detail lines on a single page.  Although it makes programming more complicated, the only practical solution may be to use a separate form for each area within a page, in this case, a different form for each type of detail line.

Defining Forms for Multi-Form Pages

Forms to be used on multi-form pages are defined in the same way as any other form.  Start the form definition at the top of the editor Format Window even though the form may eventually be printed further down the page.

Programming for Multi-Form Pages

Forms are printed as usual using the QPR-PRINT-PAGE function but with options set to tell QPR that a multi-form page is being output and to specify where on the page a form should be placed.

1.	To specify that a multi-form page is being output, set form-WAIT-SW  to "n".  This will cause QPR to use the form to construct the page in memory but not output it to the printer.  Before the call for the last form to be included on the page, reset form-WAIT-SW to low-value and the page will be printed.

2.	To specify the position of the form on the page, set form-PAN-POS-SW to 1 and form-PAN-ROW and form-PAN-COL to the appropriate row and column (in cells).  This should only be done for the second and subsequent forms - the first form is always positioned at the top of the page.

Proceed to Chapter C8


CHAPTER C8 - Print Preview Facility

This facility allows users to view output from your program before it is actually printed.

Invoking the Print Preview Facility

Print Preview can be invoked either automatically by setting a configuration variable, or by setting an option in your program.

1.	To invoke Print Preview automatically, set configuration variable QPRPVW to 1.  See appendix B for details of using configuration variables.  All print output from your program will automatically be displayed for viewing by the user until the user exits the Print Preview facility.  All print output after this will be sent directly to the printer until your program issues a QPR-END-PRINT call.

2.	To invoke Print Preview programmatically, use QPR-SELECT-PRINTER-EX instead of QPR-SELECT-PRINTER and set QPR-DO-PREVIEW to TRUE before making the call.  As above, Print Preview will be active until the user exits the facility.

Using the Print Preview Facility

Once Print Preview has been invoked, print output from your program will be displayed in a window rather than sent to the printer.  This window has a menu with the following options:

Get all pages - process all pages before previewing

Exit - exit preview facility with the option to print pages so far

Next page - preview next page

Previous page - preview previous page

First page - preview first page

Last page - preview last page processed so far

All print output after the exit option has been chosen will go directly to the printer.  The exit option will automatically be invoked when a QPR-END-PRINT call is made by your program.

Proceed to Chapter D1


CHAPTER D1 - Introduction to Functions

This part of the user guide explains the programming functions in detail.  This Chapter explains the various categories of functions that are available and the subsequent chapters define each function in detail.

Function calls are made to perform a specific task.  Each function has an appropriate descriptive name and uses a single parameter which holds all data items needed by the function.  This helps make your COBOL code more easily understood and therefore more easily maintained.

Functions are classified in the following categories

Primary functions

Information functions

Primary functions are those which you will always use in your program.

Information functions are used to retrieve information about Form Print.

The following is a quick reference list of the functions by category.

The functions are defined in the COBOL copy file QPR.CPY.

       01  QPR-FUNCTIONS.

           03  QPR-SELECT-PRINTER    PIC S9(4) COMP-5 VALUE 0.

           03  QPR-PRINT-PAGE        PIC S9(4) COMP-5 VALUE 1.

           03  QPR-END-PRINT         PIC S9(4) COMP-5 VALUE 2.

           03  QPR-ABOUT             PIC S9(4) COMP-5 VALUE 3.

           03  QPR-INIT              PIC S9(4) COMP-5 VALUE 4.

Primary Functions

QPR-INIT

QPR-SELECT-PRINTER

QPR-PRINT-PAGE

QPR-END-PRINT

QPR-SELECT-PRINTER-EX

Information Functions

QPR-ABOUT

Explanation of the Primary Function Area

QPR-INIT

QPR-INIT is a function used to initialize FormPrint and open the forms file which contains the forms to be printed.  Parameter is

QPR-INIT-AREA.

QPR-SELECT-PRINTER

QPR-SELECT-PRINTER is a function used to select the printing device on which you forms are to be printed.  Parameter is QPR-AREA.

QPR-PRINT-PAGE

QPR-PRINT-PAGE is a function used to actually print a form.  Parameter is generated data area.

QPR-END-PRINT

QPR-END-PRINT is a function used to clean up everything after you have printed all your forms.  Parameter is QPR-NULL-PARM.

QPR-SELECT-PRINTER-EX

QPR-SELECT-PRINTER-EX is used for the same purpose as QPR-SELECT-PRINTER but allows additional options to be set.

Parameter Areas

The parameter areas are also stored in the copy file QPR.CPY:

       01  QPR-AREA.

           05  QPR-RET-CODE          PIC S9(4)   COMP-5.

           05  QPR-DATA.

               10  QPR-DIALOG        PIC X.

               10  QPR-DOC-NAME      PIC X(30).

               10  QPR-ORIENTATION   PIC X.

               10  QPR-COPIES        PIC S9(4)   COMP-5.

               10  QPR-STRETCH       PIC X.

               10  QPR-DEVICE-LIST   PIC X(800).

               10  QPR-DRIVER        PIC X(32).

               10  QPR-OUTPUT        PIC X(32).

               10  QPR-DATA-EX.

                   15  QPR-PAPER-SIZE PIC X.

                       88  QPR-LETTER            VALUE X"01".

                       88  QPR-LEGAL             VALUE X"05".

                       88  QPR-A4                VALUE X"09".

                       88  QPR-B5                VALUE X"0D".

                   15  QPR-PAPER-SOURCE PIC X.

                       88  QPR-UPPER-TRAY        VALUE X"01".

                       88  QPR-LOWER-TRAY        VALUE X"02".

                       88  QPR-MIDDLE-TRAY       VALUE X"03".

                       88  QPR-MANUAL-FEED       VALUE X"04".

                   15  QPR-PREVIEW   PIC X.

                       88  QPR-DO-PREVIEW        VALUE "y".

                   15  FILLER        PIC X(99).

       01  QPR-VERSION.

           05  QPR-QE-RET            PIC S9(4)   COMP-5.

           05  QPR-QE-DATA.

               10  QPR-VERSION-INFO  PIC X(80).

               10  QPR-DISPLAY-BOX   PIC X.

       01  QPR-INIT-AREA.

           05  QPR-QI-RET            PIC S9(4)   COMP-5.

           05  QPR-QI-DATA.

               10  QPR-LIBRARY       PIC X.

               10  QPR-METHOD        PIC X.

               10  QPR-FILE          PIC X(80).

               10  FILLER            PIC X(118).

The data parameter area for use with the QPR-PRINT-PAGE call is generated from the form definition itself using the Forms Editor.  See Chapter C2 for an example of this.

Proceed to Chapter D2


CHAPTER D2 - Primary Functions

QPR-INIT

This function is used to initialize FormPrint and open a forms file.

Parameter: QPR-INIT-AREA

Example:

MOVE LOW-VALUE TO QPR-INIT-AREA.

MOVE "n" TO QPR-METHOD.

MOVE "formfile" TO QPR-FILE.

CALL "QPR" USING QPR-INIT QPR-INIT-AREA.

QPR-SELECT-PRINTER

This function is used to select the printer to use for your output. The function is fully described in chapter C4 Selecting a printer with COBOL FormPrint.

Parameter: QPR-AREA

Example:

MOVE LOW-VALUE TO QPR-AREA.

MOVE "y" TO QPR-DIALOG.

CALL "QPR" USING QPR-SELECT-PRINTER QPR-AREA.

This call will invoke the windows Printer Dialog Box and let you choose a printer.  FormPrint will then obtain a handle to a device context. This will lead to loading the printer device library module as well as the Windows Print Manager program (PRINTMAN.EXE)

QPR-PRINT-PAGE

This function will start the printing and accomplish all of the following:

•	Initialize the page  (set the document name and the beginning of a new document ).

•	Start the page  (prepare the Windows printer driver to accept the form)

•	Merge the data passed in the FIELDS area of the generated data parameter with the form as defined in the Forms Editor.

•	Print the page.

•	End the page.

The parameter area for the QPR-PRINT-PAGE function is the CONVERSE-DATA area located in the generated copybook for the form.

Parameter: Data area generated by Forms Editor

Example:

MOVE LOW-VALUES TO  FORMNAME-DATA.

MOVE LOW-VALUES TO  FORMNAME-FIELDS.

MOVE LOW-VALUES TO  FORMNAME-COLRS.

MOVE LOW-VALUES TO  FORMNAME-TYPES.

MOVE  "FORMNAME"  TO FORMNAME-NEXT-PANEL.

CALL "QPR" USING QPR-PRINT-PAGE FORMNAME-CONVERSE-DATA.

QPR-END-PRINT

With this function FormPrint indicates to the Windows Print Manager that the print job is completed.  The Print Manager will then take responsibility to transfer the document to the printer which will allow your application to accomplish other tasks.

Parameter: QPR-NULL-PARM

Example:

CALL "QPR" USING QPR-END-PRINT QPR-NULL-PARM.

QPR-SELECT-PRINTER-EX

The QPR-SELECT-PRINTER-EX is used is used to select the printer to use for your output  in the same manner as the QPR-SELECT-PRINTER function. The only  difference between the QPR-SELECT-PRINTER and the QPR-SELECT-PRINT-EX is that the QPR-SELECT-PRINT-EX  allows additional options to be set.

The function is fully described in chapter C4 Selecting a Printer with COBOL FormPrint.

Parameter: QPR-AREA

Example:

           MOVE LOW-VALUES TO QPR-AREA.

           MOVE "d" TO QPR-DIALOG.

           SET QPR-LEGAL TO TRUE.

           SET QPR-LOWER-TRAY TO TRUE.

           CALL "QPR" USING QPR-SELECT-PRINTER-EX QPR-AREA.

Proceed to Chapter D3


CHAPTER D3 - Information Functions

QPR-ABOUT

This function is used to retrieve information on the specific version of COBOL FormPrint being used.  This information could be displayed on the screen or returned to your program as a text string.

Parameter: QPR-VERSION

Example:

MOVE LOW-VALUE TO QPR-VERSION.

MOVE "n" TO QPR-DISPLAY-BOX.

CALL "QPR" USING QPR-ABOUT QPR-VERSION.

Proceed to Chapter E1


CHAPTER E1 - Introduction to Data Items

Part E describes the data items used as parameter areas.  All data items are explained and examples will show how they should be used.

The first two bytes of a parameter are reserved for a return code.  This will  be set to 0 unless an error occurs.

The parameter areas that are used are defined in a copy book called QPR.CPY.

Subsequent chapters define each category of data item. The following is a list of categories.

•	data used for opening a forms file and initializing FormPrint

•	data used for selecting the printer

•	data used for printing the page

•	data used for getting version information

Proceed to Chapter E2


CHAPTER E2 - Data Used for Opening a Forms File and Initializing FormPrint

Layout

  01  QPR-INIT-AREA.

        05 QPR-QI-RET            PIC S9(4)   COMP-5.

        05 QPR-QI-DATA.

             10  QPR-LIBRARY     PIC X.

             10  QPR-METHOD      PIC X.

             10  QPR-FILE        PIC X(80).

             10  FILLER          PIC X(118).

QPR-QI-RET

Contains the FormPrint return code (must be 0).

QPR-LIBRARY

This parameter should always be set to low-value.

QPR-METHOD

This parameter should always be set to n.

QPR-FILE

This parameter should be set to the forms file to be opened.

Proceed to Chapter E3


CHAPTER E3 - Data Used for Selecting the Printer

Layout

01  QPR-AREA.

      05  QPR-RET-CODE                PIC S9(4)   COMP-5.

      05  QPR-DATA.

           10  QPR-DIALOG             PIC X.

           10  QPR-DOC-NAME           PIC X(30).

           10  QPR-ORIENTATION        PIC X.

           10  QPR-COPIES             PIC S9(4)   COMP-5.

           10  QPR-STRETCH            PIC X.

           10  QPR-DEVICE-LIST        PIC X(800).

           10  QPR-DRIVER             PIC X(32).

           10  QPR-OUTPUT             PIC X(32).

           10  QPR-DATA-EX.

                   15  QPR-PAPER-SIZE PIC X.

                       88  QPR-LETTER            VALUE X"01".

                       88  QPR-LEGAL             VALUE X"05".

                       88  QPR-A4                VALUE X"09".

                       88  QPR-B5                VALUE X"0D".

                   15  QPR-PAPER-SOURCE PIC X.

                       88  QPR-UPPER-TRAY        VALUE X"01".

                       88  QPR-LOWER-TRAY        VALUE X"02".

                       88  QPR-MIDDLE-TRAY       VALUE X"03".

                       88  QPR-MANUAL-FEED       VALUE X"04".

                   15  QPR-PREVIEW   PIC X.

                       88  QPR-DO-PREVIEW        VALUE "y".

                   15  FILLER        PIC X(99).

QPR-RET-CODE

QPR-RET-CODE  will be initialized to 0 before calling QPR.  If a successful call is made it, it will remain 0 when returning to your program.  When calling QPR with QPR-SELECT-PRINTER set to 's', the return code will then be -10 and may not be changed.  Please see the explanation of the data item QPR-DEVICE-LIST.

QPR-DIALOG

"y"  initiates Windows Printer Dialog.

"s" gives you all the available printers defined in the section [devices] in WIN.INI.

"d" chooses default printer.

The default printer is found in the [windows]  section of the WIN.INI file.

For example:

device=HP LaserJet 4P/4MP,HPPCL5E, LPT1 :

QPR-DOC-NAME

The name of the document to be shown in the print queue.

QPR-ORIENTATION

Sets the custom paper orientation. (If QPR-DIALOG is not set to "y".)

"p"  = Portrait,  "l" (lower-case "L") = Landscape.

QPR-COPIES

Number of copies to print. (If  QPR- DIALOG is not set to "y".) Default is 1.

QPR-STRETCH

This option is not currently used.

QPR-DEVICE-LIST

This parameter is used when QPR-DIALOG is set to "s".  This is where FormPrint will return all printers defined under section [devices] in the WIN.INI file.  Each printer will be separated by a semicolon (;).  The return code for this call is -10 and may not be changed because it's needed for the second SELECT-PRINTER call.  The string has to be unpacked with your COBOL verb used for this purpose.  You can then select a printer and do a second call with the selected printer name stored in QPR-DEVICE-LIST.  The return code after the second call should be 0.

For example:

HP LaserJet 4p/4MP;HP DeskJet 510; Microline 183......

For more information on how to use this option, please refer to Chapter  C4, Selecting the printer with COBOL FormPrint, and review Method Number 3 for selecting the printer.

QPR-DRIVER

The name of the driver is returned to this area.

QPR-OUTPUT

The port to which the printer is connected is returned to this area.

Example:  LPT1

QPR-PAPER-SIZE

The size of the paper to be used.  Can be set to any one of the

following:

                   15  QPR-PAPER-SIZE PIC X.

                       88  QPR-LETTER            VALUE X"01".

                       88  QPR-LEGAL             VALUE X"05".

                       88  QPR-A4                VALUE X"09".

                       88  QPR-B5                VALUE X"0D".

QPR-PAPER-SOURCE

The source of the paper to be used.  Can be set to any one of the

following:

                   15  QPR-PAPER-SOURCE PIC X.

                       88  QPR-UPPER-TRAY        VALUE X"01".

                       88  QPR-LOWER-TRAY        VALUE X"02".

                       88  QPR-MIDDLE-TRAY       VALUE X"03".

                       88  QPR-MANUAL-FEED       VALUE X"04".

QPR-PREVIEW

Set to "y" to turn on the Print Preview facility.

                   15  QPR-PREVIEW   PIC X.

                       88  QPR-DO-PREVIEW        VALUE "y".

Proceed to Chapter E4


CHAPTER E4 - Data Used for Obtaining Version Information

Layout

       01 QPR-VERSION.

            05  QPR-QE-RET                    PIC S9(4)   COMP-5.

            05  QPR-QE-DATA.

                 10  QPR-VERSION-INFO         PIC X(80).

                 10  QPR-DISPLAY-BOX          PIC X.

QPR-QE-RET

The value of the QPR-QE-RET return code must be  zero ( 0 ).

QPR-VERSION-INFO

The value of the QPR-VERSION-INFO parameter contains the version string returned from FormPrint.  The information is presented as text separated by ';' (semi colons ). For example:

" Version 1.2 for  CA-Realia;Copyright 1995-1996;......."

QPR-DISPLAY-BOX

The QPR-DISPLAY-BOX variable is used to select if version information is going to be displayed in a Windows Message Box or returned to the COBOL program as a string.

"n"	return string to COBOL program

"y"	display Message Box.

low-value	display Message Box.

Proceed to Appendix A


APPENDIX A - Configuring COBOL FormPrint

The COBOL FormPrint runtime uses  the COBOL FormPrint configuration file ( QPR.CFG).

To set up an environment variable, use the command that is appropriate for the system that you are running on.  If you are using a configuration file, set up the variables in the following format:

QPR???=?

Please note that the environment variable must always be:

1.	in upper-case;

2.	one environment variable per line, and

3.	must include the full path.

The variables that will affect COBOL FormPrint are listed below.

QPRIBM	• set to 1 to indicate that your program is handling data in ASCII (IBM-PC) rather than ANSI format (only required for users using the extended PC character set) • set to 2 to indicate that your program is handling data using the Roman 8 (HP) character set.
QPRDEC	• set to 1 for "decimal-point is comma"
QPRDIR	• the directory where you keep form files, bitmaps and your fonts.qpr file (FormPrint fonts file). For example: QPRDIR=C:\FP\FORMS;C:\FP\BITMAPS; C:\FP\FONTS
QPRLOG	• force COBOL FormPrint to create a log file.  The name of the log file will be QPR.LOG.  The log file will not be deleted by COBOL FormPrint.  To remove it, you must use an operating system command
QPRMTH	• set to 1 to force new logic without using the QPR-INIT function
QPRPVW	• set to 1 to automatically select the Print Preview facility

Proceed to Appendix B


APPENDIX B - Form File Organization

It is intended that forms files should contain as large a number of forms as you wish.  If you wish to have multiple forms files containing logical groups of forms, this is quite permissible.  You can have up to three forms files open at any one time.  .  It is NOT recommended that you should have a forms file for each form.

Free space within a forms file that results from updating forms definitions may not always be reused.  This may cause your forms file to grow much larger than is necessary.  A utility program is included to compress forms files.  Invoke this program as follows:

QPRCHECK FORMS-FILE-NAME

This will create a new file called CHECKED.PAN which can be copied back to the original file and then deleted.  If  QPRCHECK stops and  reports an error concerning a forms, please contact your technical support representative.

QPRCHECK can also be used to update a forms file as follows:

QPRCHECK SOURCE-FORM-FILE TARGET-FORM-FILE FORM-NAME(S)

In this example, the TARGET-FORM-FILE will be created if it doesn't exist.

A fourth parameter may also be passed to QPRCHECK.  If the fourth parameter is used the form(s) being moved will also be renamed to the name(s) specified in the fourth parameter.

Proceed to Appendix C


APPENDIX C - Return Codes

Code	Description
1	not found
8	printer not selected
9	printer not selected
12	form not found
-10	printer list returned