Using Forms Engine

The primary function of the Forms Engine is to enable high-speed and high-volume printing to PostScript printers. It does this by sending a PostScript print data stream directly to the printer, bypassing any Print Driver routines. It also caches the form layout onto the printer itself so that only the data that changes from page to page must be sent to the printer for each page.

This chapter discusses how to:

• Use the components of Forms Engine.

• Purge form data.

• Modify a form.

• Add data to the form data tables.

• Set up images.

• Change a logo.

Using the Components of Forms Engine

The Forms Engine consists of several components. This section discusses how to:

• Use the application designer.

• Create and modify forms.

• Use the form image text repository.

• Using form image text.

• Upload form image text.

• Review form groups.

• Use output destination formats.

• Specify font names.

• Using PostScript fonts.

• Use the Inquire On Form Data page.

Pages Used with the Forms Engine Components

Using the Application Designer

The Application Designer is not part of the Forms Engine. However, page layouts defined within the Application Designer can be imported into the Form Editor. You can make all of your changes to a form using Application Designer. If you use Application Designer to make changes, you do not need to make changes in Form Editor.

Creating and Modifying Forms

You can create or modify forms using the Form Editor either by importing a page layout from the Application Designer or by manually adding objects to the page definition. If you import a page layout from the Application Designer, the entire contents of the form definition are replaced by the imported page definition.

Access the Form Editor page (Set Up SACR, Common Definitions, Forms Engine, Set Up, Form Editor, Form Editor).

Select Set Page Device to force the form to start on a new piece of paper. This is important when you are duplex printing (printing on both sides of the paper). If you do not select Set Page Device, a new form might print on the backside of a piece of paper.

You can add types of objects to forms such as Box, Data Field, Image, Line, Long Text, and Text. You can set attributes for each of these objects such as color, font, position, length, style, scale, spacing, justification, line thickness, dashes, image ID, and literal text. Not all attributes apply to all form child objects. You can specify to have sample text values appear in data fields when you preview the form.

To preview the form that you are editing, click the Preview link. This saves any unsaved changes, generates the PostScript print data stream, and sends the data to your browser. If your browser is configured to display this type of data, it displays the image of the form. If your browser is not configured to display this type of data, you can save the data to a disk directory. If you save the data to a disk directory and give it a file name, give it a (.ps) extension indicating that it is a PostScript file. Copy this file to a postscript printer. The page image renders graphically to that printer.

If you want to view the PostScript preview page image on your browser, click the Get PostScript Viewer link on the Form Editor page. The system displays a website where you can obtain a PostScript View program.

Using the Form Image Text Repository

Access the Form Image Text Viewer page (Set Up SACR, Common Definition, Forms Engine, Set Up, Form Image Text, Form Image Text Viewer).

The form image text is the actual PostScript text that is sent to the PostScript printer. To access the Form Image Text page, select Design Student Administration, Forms Engine, Setup, Form Image Text.

The only fields that you can update on the setup page are Description and Cache Form On Printer. Cache Form On Printer indicates whether the form is sent to the printer only once at the beginning of the print run or each time that the image is needed.

When you save a form layout in the Form Editor, it generates two corresponding entries in the Form Image Text table. The entry that starts with FEP followed by the form name is the static page layout. It is automatically set to cache on the printer. The other entry is the one that starts with FER followed by the form name. It is the runtime portion of the page and is sent each time that the page is printed. The runtime portion combines the page layout with images and wrapped text.

Uploading Form Image Text

To modify an image that is being rendered on a page, you must create a new or modified form image text file in encapsulated PostScript (EPS) format and upload it to an FTP site that you choose. You can then run the process to upload this text into the Form Image Text repository.

Access the Upload EPS Image File page (Set Up SACR, Common Definition, Forms Engine, Process, Upload EPS Image File).

Follow these steps to upload form image text.

1. Create a run control record.

   The URL is the name of the FTP domain to which you had previously uploaded the EPS file. If you uploaded it to the FTP server called MYFTPSITE, then you would enter MYFTPSITE into this field.

2. Enter the ID and password that you used to log on to the FTP site.

3. Retype the password in the Confirm Password field.

   The unique system file name should be a file name in 8.3-format without any blank spaces.

   Note. Do not enter path information. For example, MYLOGO.EPS is used for the MYLOGO form image text file. The remote file name is the path and name of the file that you specified when you uploaded it to your FTP site. The form image name is the name that Oracle uses as the key to the Form Image Text repository. Our example is MYLOGO.

4. Submit the process.

5. Access the Form Image Text page after the process finishes successfully. Enter a description for the image and select the Cache Form On Printer check box.

To create or modify form image text, you can create or modify the corresponding EPS file in the data directory of ps_home. For example, to create a graphic image called MYLOGO, copy the FAPSULGO.EPS file from the data directory to a file called MYLOGO.EPS. Use a simple text editor to edit it and change every occurrence of FAPSULGO with MYLOGO. You can modify the contents of the image text using a simple text editor and enter PostScript command text to construct an image.

An alternative technique for creating an EPS file for your image is to use some other program to generate the PostScript file. A possible future enhancement to this process is that the program that uploads the EPS Image File will accept files with the .JPG extension and convert them to EPS format while loading them into the Form Image Text repository. Some JPG files convert to EPS files that are too large to cache on the printer. You will have to clear the Cache Form On Printer check box if your image is converted from a JPG file.

Reviewing Form Groups

A form group ties a list of forms together. The Form Group Relative Sequence field indicates the relative order for form groups to be rendered when more than one form group is output into a single print stream. The forms are tied to the form groups within an application program. Because of this, you should not modify these settings unless you are customizing a program.

Access the Form Groups page (Set Up SACR, Common Definitions, Forms Engine, Set Up, Form Groups).

Using Output Destination Formats

Access the Output Destination Formats page (Set Up SACR, Common Definition, Forms Engine, Set Up, Out Dest Formats, Output Destination Formats).

This table specifies parameters for various output formats usable by programs, which in turn use the Forms Engine. For example, a program looks at the Print Script field to determine the name of a command script for printing. In the case of the PostScript output destination format, the print script PSPRINTFILE.CMD requires two arguments: the printer name and the file name.

Specifying Font Names

Access the Font Names page (Set Up SACR, Common Definitions, Forms Engine, Set Up, Font Names, Font Names).

This table contains the list of all PostScript font names that you can specify within the Form Editor.

Using PostScript Fonts

Access the PostScript Fonts page (Set Up SACR, Common Definitions, Forms Engine, Set Up, PostScript Fonts, PostScript Fonts).

This table is a list of translations that uses a font name as specified in the Application Designer and translates it into a PostScript font name. You must install the font names specified on all of the PostScript printers at your installation.

Using the Inquire On Form Data Page

This page is normally hidden. You should restrict access to this page. It enables you to view any page printed by the Forms Engine and retained in the Form Data tables. Functions that refer to this data have pages and views that restrict the content to data relating to just that function. Use this page to debug problems.

Purging Form Data

To purge form data, you must first write to the Form Data tables and assign an expiration date for every page printed with the Forms Engine. Schedule a daily purge job to run the process to purge expired pages. To determine whether such a job exists, use your query tool to issue this query:

SELECT

*

FROM PSPRCSRQST

WHERE PRCSNAME = 'FE_FORM_PUR'

AND RUNSTATUS = 5

If no such process is scheduled to run, you must schedule it. Use the following steps to schedule a process.

1. Select Design Student Administration, Forms Engine, Process, Form Data Purge.

2. Create a run control.

3. Click the Run button.

4. Set the server name.

5. Set the Recurrence value to a daily purge schedule. If you do not have a recurrence, create a new one by selecting PeopleTools, Process Scheduler Manager, Use, Recurrence Definitions to create a new one.

6. Click OK.

Modifying a Form

You can modify a form in two ways. You should use the Application Designer. You can also edit the form with the Form Editor. If you modify the form by modifying the related page in the Application Designer (AD), click the Import Page button to import the modified page to the Form Editor.

In the AD, page fields are not tied to record fields, and the page size matches the paper size in units of ENs. 72 ENs are in an inch. If you want to lay out a page in landscape format, you must change the page size so that the width is larger than the length. An 8 ½ by 11 inch piece of paper in portrait layout has the page size of 612 wide by 792 tall. To view or set this, access page properties and select the Use tab.

Currently, no recurring fields are permitted by the Forms Engine. Instead, each field on the page must have a unique name. View or set the PAGEFIELDNAME in the field properties and select the General tab. To see all of the PAGEFIELDNAMEs on a page, select the Order tab in AD for the page. You can rearrange, hide, or delete page fields. However, you cannot move fields to a different page or add new fields without changing the application program.

Adding Data to the Form Data Tables

To change the application program, you need to understand the nature of the various tables that store the form data. A computer programmer typically performs the following application program steps.

1. Obtain the next available FORM_PROC_INST by incrementing the field LAST_FORM_PROCINST in table PS_INSTALLATION_FA.

2. Insert one row into the PS_FORM_INSTANCES table corresponding to a single batch of output to be collated into one output stream.

3. Insert multiple rows into the PS_FORM_COLLATEGRP table, one per unique value of the FORM_GROUP_SEQ field.

   This is the description of the FORM_GROUP_SEQ field from its property in AD: Form Group Sequence enables the sequencing of form groups within a FORM_PROC_INST. Each time a group of forms begins to print, this value is incremented and stays the same within that form group. If the same form group prints again, it is incremented again, so that it is not the same value if the same form group prints twice.

4. Insert multiple rows into the PS_FORM_DATA table, one per data value.

   If the length of the data value exceeds 40 characters, you must also insert a related row into one of these tables: PS_FORM_DATA_C128, PS_FORM_DATA_C254, or PS_FORM_DATA_LONG. Set the value of the FORM_FIELD_LTYPE accordingly. Set the appropriate value for the FORM_GROUP_SUB_SEQ field. This is the description of that field from its property in AD: Form Group Sub Sequence is a sequence number within a form group, one per form. When a new form group begins to print, this sequence number starts back at one.

Setting Up Images

An image must exist in the Form Image Text table. You can use a Adobe PostScript rendering utility to generate a related bitmap or JPG file. Some examples of utilities that you can use are Ghostscript® or Adobe® Distiller.

This section discusses how to:

• Set up a background image.

• Set up a foreground image.

See http://www.ghostscript.com

See http://www.adobe.com

Setting Up a Background Image

If you want to use Application Designer to modify the background image, you must create a modified style sheet and set the background image there. Refer to the Application Designer User Guide for details.

If you want to use the Form Editor to modify the background image, enter the image name in the Image field located to the right of the Background Color group box on the Form Editor page. The name that you enter here must be one of the names in the Form Image Text table.

Setting Up a Foreground Image

If you want to use Application Designer to add, modify, or create a foreground image, you must first create an image object, which you subsequently place on your page. Follow these steps if you want to use the Form Editor to modify or create a foreground image.

1. Insert a row into the list of form field objects.

2. Set form field type to Image.

3. Click the Edit Field Attributes link.

4. Set the image name, position, and scaling factor.

5. Click OK.

Changing a Logo

You can convert an image (for example, the Financial Aid PeopleSoft Univ Logo FAPSULGO) to encapsulated PostScript (eps) format suitable for use by the Forms Engine. To upload your image in eps format, you must first convert your logo from jpeg format to eps format. You must also convert your jpeg to gif format to view it in Application Designer. You must use the same naming convention for all three formats. The only change to the file name is the format extension (for example, Univ_Logo.jpg/Univ_Logo.eps/Univ_Logo.gif).

Note. If you are converting an image other than FAPSULGO, use that name in place of FAPSULGO.

You may want to consult your technical support group before implementing this procedure.

To change FAPSULGO:

Phase 1 – Converting the Application Designer Image to EPS Format

Perform the following 26 steps before proceeding with Phase 2.

1. Install Microsoft Photo Editor, GhostScript (http://www.ghostscript.com) and GsView, and JPEG2PS Utility (http://umn.dl.sourceforge.net/sourceforge/gnuwin32/jpeg2ps-1.9-bin.zip).

2. In Application Designer, open image FAPSULGO.

   • To add a new image:

     When prompted to select the image, select the gif. (for example, FAPSULGO.gif). The system displays the message, Image format cannot be displayed in Windows. Do you want to import an alternate image?

     Click Yes and then select the .jpg (for example, FAPSULGO.jpg).

     Right click and select image properties.

     Enter a description. On the Use tab, omit the Image URL.

     Click OK and save.

   • To export an existing image:

     Click File, Export Image.

     Save it to a temporary location (for example, c:\temp\FAPSULGO.GIF) in GIF format.

   • Close Application Designer.

3. Use Microsoft Photo Editor to convert the GIF to JPG format. Double-click the GIF file in Windows Explorer to invoke Photo Editor and open this file. Select File, Save As and select Jpeg format. Use the MORE button to reduce the size of the jpg file. Alternatively, you can override the scaling factor in step 13 to avoid losing image resolution.

4. Reopen the jpg file in Photo Editor to confirm that you like the way it looks in jpg format and then close Photo Editor.

5. If you are using the jpeg2ps utility, issue the command jpeg2ps FAPSULGO jpg > FAPSULGO eps.

6. Edit FAPSULGO.eps in Notepad.

7. Save the file as FAPSULGO.ps. Note. It is '.ps', not '.eps'.

8. Remove the comments at the start of the file that start with '%'.

9. Remove the language level test and the 'save' line.

10. At this point, all of the lines prior to the /RawData ... line have been deleted. The first line of the file now starts with /RawData.

11. Remove the 'showpage' line.

12. Remove the 'restore' line.

13. Change the 'scale' line to specify the width (65) and height (54) of the image (for example, 65 54 scale). The width and height can be seen in the image attributes three lines down. You can override the scaling factors here to resize your image without losing resolution.

14. Change the 'translate' to locate the image on the page. A page of 8.5 by 11 inches would have the dimensions in Ens' of 612 by 792 (multiply inches by 72). For example, to place the image 1/2 inch from the top and 1/2 inch from the left, change the translate line to 36 702 translate. The 702 = 792 – 36 – 54 (image height).

15. Insert this comment line after the 'scale' line: % /BBox [0 0 1 1] def.

16. Although this file does not need a /BBox statement, the Form Editor looks for a /BBox statement when it is importing a page's image.

17. Add a 'showpage' line at the end of the file.

18. File FAPSULGO.ps.

19. Display FAPSULGO.ps using Ghostview. Verify that this looks like what you want.

20. Print FAPSULGO.ps by copying it to your printer from a command line: copy FAPSULGO.ps\\prtserver\printername.

21. Confirm that the output looks good.

22. Using Notepad, edit FAPSULGO.ps. Save it as FAPSULGO.eps (note it is '.eps', not '.ps').

23. Remove the 'showpage' at the end of the file.

24. Comment out the scale and translate lines near the top of the file by inserting a '%' at the front of each of those lines.

25. Add a comment at the very top of the file starting with a '%' describing this image. for example, % PeopleSoft Logo Icon.

26. File FAPSULGO.eps.

Phase 2 – Uploading and Editing Form Image Text

Perform steps 1 through 6 before proceeding with Phase 3.

1. Upload FAPSULGO.eps into the form image text FAPSULGO:

   • Select Design Student Administration, Forms Engine, Process, Upload EPS Image File.

   • URL: ftp.myserver.com

   • File Transfer ID: ftpid

   • Operator Password: ftppw

   • Unique System Filename: FAPSULGO.eps

   • Remote File Name: FAPSULGO.eps

   • Form Image Name: FAPSULGO

   • Submit

2. Edit the eps image file settings. For example, select Design Student Administration, Forms Engine, Setup, Form Image Text.

3. Open FAPSULGO.

4. For the description, enter the description of the image. For example: PeopleSoft Logo Icon.

5. Do not enable the Cache Form On Printer check box.

6. Save.

Phase 3 – Using Application Designer to Establish Field Properties and Create a New Image

Perform the following 17 steps.

1. Open Application Designer.

2. Open the page FA_AWD_NOTIF_LTR1 in Application Designer.

   • In the page field properties, change the existing image to the image that you just created.

   • In the Image/Format Size section, set the width and the height. See Step 13 in Phase 1 for values.

   • Click OK and save your changes.

3. Right-click the image on the page.

4. Select Page Field Properties.

5. Select the image ID FAPSULGO.

6. Select the 'Size' option on the image.

7. Set the width to 65 and the height to 54. Refer to Step 13 in Phase 1.

8. Click OK.

9. The image on the page in Application Designer should now show the new logo.

10. Save the page.

11. Click OK to all the prompts for Warning: Page field with label ''not related to database field. You can hold down the Enter key and let it auto-repeat the enter.

12. Close Application Designer.

13. Access Form Editor. Select Design Student Administration, Forms Engine, Setup, Form Editor.

14. Open the form FA_AWD_NOTIF_LTR1.

15. Click the Import Page button.

16. Click the Preview link. This automatically saves the form with the newly imported page values.

17. If the icon looks good here, you are ready to test.