PDDR/2 - Printer Test Tool (PTT)

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation =Printer Test Tool (PTT)= The Printer Test Tool (PTT) is a Presentation Manager application that enables the user to select one or more tests and execute them.

Overview
The PTT provides a mechanism for testing s by calling graphics programming interface (GPI) functions. Each call, on execution, produces quantifiable output by which the test can be measured. As each test is run, the PTT monitors the return codes from the GRE calls and writes the results to a log file. The current log file can be displayed at any time during manual testing.

PTT Architecture
The PTT is comprised of two major components:
 * A PM master program (PTT.EXE) that provides the user interface for test selection and execution.
 * Test-case dynamic-link libraries (DLLs) that contain the actual test-case executable code.

PTT Master Program
PTT.EXE enables the user to do the following:
 * Select one or more tests from the test cases available.
 * Execute the selected test cases on demand.
 * Specify a test-case PM environment (PS units, PS types, and so forth).
 * Display the PTT test log.
 * Set the PTT test-logging level.
 * Display the PTT release level.
 * Exit PTT.

Command-line options enable the user to specify the following:
 * Output log file name
 * Level of logging to capture
 * Search patterns for DLLs to be preloaded.

Test-Case DLLs
Each test-case DLL contains tests for a family of GPI calls. See for descriptions of the supplied test-case DLLs and the GPI functions called.

Note: The test-case DLLs must reside in the same directory as the PTT executable.

Operating PTT
The PTT can be started from the command line in either an OS/2 window or a full-screen session. The PTT can also be started from the OS/2 Desktop or any other folder by using its icon. When using an icon, command-line options are specified in the Optional Parameters field of the Settings menu for the icon.

Specifying Command Options
All command-line options are specified with a hyphen (-), followed by a case-sensitive alphabetic character. The alpha character is followed immediately by the parameter value, if any, with no intervening spaces. Following are examples of PTT command lines. Load all DLLs in the current directory and set the logging level to 8:

PTT -T*.DLL -L8

Preload the GRELINE DLL. (Search LIBPATH to locate the DLLs.)

PTT -Tgreline.dll Executing PTT with the -? command-line option displays a list of the valid command-line options.

Menu Selections
The following options are available on the PTT menu:

Locating, Preloading, and Loading Test-Case DLLs
Each test case DLL passes a list of its test cases to PTT when PTT initializes the DLL after loading. A test-case index file associates each test-case name with the DLL that contains it. When duplicate test cases are encountered while loading DLLs and test-case index files, only the first instance of a test case is retained.

PTT locates the test cases using the following sequence:
 * 1. DLLs specified using the -T command-line option are preloaded during PTT startup. Preloaded DLLs remain resident for the duration of the PTT session.
 * The -T command-line option specifies a search pattern for locating the test -case DLLs to be preloaded. The -T option value can contain global file- name characters (wildcards) in the file name. Following is an example of the command used to preload DLLs:

Preload all DLLs in the PTT\DLL directory on the current drive.

PTT -T\PTT\DLL\*.DLL
 * The -T command-line option can be specified multiple times (on the command line) with different paths to the DLLs.
 * 2. At this point, if no test cases have been identified to PTT, PTT attempts to preload all the test-case DLLs it can locate using a *.DLL search pattern. This searches the current directory.
 * 3. If PTT fails to locate any test-case DLLs in the current directory, a message to that effect is issued.
 * An OK check box in the informational window permits the user to continue bringing up PTT.

PTT Log File
PTT writes information to a log file. The information to be logged is determined by the current logging level, which is hierarchical. At any given logging level, all information at that level and below is logged.

Specifying the PTT Log File Name
A path and file name for the PTT log file can be specified on the PTT command line using the -F option. If no log file name option is given on the command line, the default file name, PTT_LOG in the current directory, is used. If a log file does not exist when PTT is started, the log file is created automatically. If the log file does exist, the new log is appended to the existing log file.

Specifying the PTT Logging Levels
The PTT logging level can be specified on the PTT command line or changed from the Options pull-down menu after PTT has started. To set the logging level on the command line, specify a -Lxoption, where xis the desired logging level, using a number in the range 1-9. To change the logging level after PTT has started, select Change logging levelfrom the Options pull- down menu or use the accelerator key, Alt+L. The default PTT logging level is 1, L_HDR

The following table describes the logging levels supported by PTT:

Displaying the PTT Log File
To display the PTT log file for the current session, select Display log window from the Options menu or use Alt+D.

Configuring the Device Context and Presentation Space
PTT enables you to specify the device context, presentation-space type, and presentation-space units to use when executing test cases. These parameters can be changed during testing. To change the configuration manually, select Configuration from the Options pull-down menu or use Alt+C.

Setting the Device Driver
To set or change the device driver, select one of the optional s available in the Printer Queue, Printer Name, and Printer Port window by clicking the mouse on the desired driver. If a device driver is installed after PTT is initiated, the user can select Refresh Printer Driver List to list the other optional device drivers.

Setting the Device Context
To set or change the device context, select one of the following options from the Device Context section of the PTT Configuration dialog panel:
 * OD_QUEUED:Output is to be queued. (This is the default.) This option is for hardcopy drivers only. The driver opens a spool file and uses the spooler's Spl interface to send output to that file. The driver must consider the data type if this option is chosen. The following data types are available:
 * PM_Q_STD:The hardcopy driver uses the spooler to create a device- independent spool file using the Spl interfaces. See.
 * PM_Q_RAW:The hardcopy driver processes the GRE functions to generate device -specific output data. This data is written to a spool file using the spooler Spl interfaces. See.

This is the same as OD_METAFILE, except querying of attributes is not permitted. The option is handled by PMGPI and never is passed to the device driver.
 * OD_DIRECT:Output is not queued. The presentation driver processes the GRE routines to generate device-specific data. Hardcopy drivers use the Prt interface routines to pass the output to the physical device driver.
 * OD_INFO:The presentation driver does not generate any output. The information device context is used only to retrieve information.
 * OD_METAFILE:The device context is used to write a metafile. The option is handled by PMGPI and never is passed to the device driver.
 * OD_METAFILE_NOQUERY:
 * OD_MEMORY:This is a device context that is used to contain a bit map. The device driver processes the output data the same as for an OD_DIRECT device type, except the output is written to a bit map that is compatible with the physical device. (PTT creates the bit map and associates it with the device context.)

Setting the Queue Processor
To select the data type to be used when executing test cases, use the mouse to click on the queue processor that is available in the window.

Setting the Data Type
To select the data type to be used when executing test cases, select one of the following options in the Data Type check box of the PTT Configuration dialog panel:
 * PM_Q_RAW Raw data.
 * PM_Q_STD Metafile-formatted data. (This is the default.)

Setting the Presentation-Space Type
To select the presentation-space type to be used when executing test cases, choose one of the following options from the PS Type section of the PTT Configuration dialog panel:
 * GPIT_MICRO Micro-presentation space.
 * GPIT_NORMAL Normal presentation space. (This is the default.)

Setting Presentation-Space Units
To set the presentation page-size units for test-case execution, select one of the following from the PS Units section of the PTT Configuration dialog panel:
 * PU_ARBITRARY Application-convenient units.
 * PU_PELS Pel coordinates. (This is the default.)
 * PU_LOMETRIC Units of 0.1 mm.
 * PU_HIMETRIC Units of 0.01 mm.
 * PU_LOENGLISH Units of 0.01 inch.
 * PU_HIENGLISH Units of 0.001 inch.
 * PU_TWIPS Units of 1/1440 inch.

Selecting and Executing Test Groups and Test Cases
The test cases to be executed are selected from the Test Case Selection dialog panel. Select Testcase from the PTT menu bar or use ALT+T. One or more test cases can be selected for execution during manual operation.

Test Group Selection
There is a 1:n relationship between test groups and test-case DLLs. Each test group represents a specific DLL. Before a test case can be selected, the test group containing the test case must be selected from the Test Groups section of the PTT Test Case Selection dialog panel. When you select a test group, the list of test cases it contains is added to the Test Cases section of the dialog panel. De-selecting a test group removes the list of test cases it contains from the Test Cases section.

Note: Test groups must be de-selected specifically. PTT never de-selects a test group automatically.

Test Case Selection
Once the test groups are selected, the individual test cases can be selected from the Test Cases section of the PTT Test Case Selection dialog panel. Test cases can be selected and de-selected individually, or groups of test cases can be selected with the match patterns provided using the Add Match and Delete Match push buttons.

Note: Test cases must be de-selected specifically unless the user's test group is de-selected. When that happens, all test cases are de-selected and made unavailable. The PTT never de-selects a test case automatically.

Saving Selected Test Cases
After selecting one or more test cases, use the Save push button or Alt+S to close the Test Case Selection dialog panel.

Executing Test Cases
After selecting and saving one or more test cases, select Display to Screen from the Action topic of the PTT menu bar, or use Alt+S to begin test-case execution to the monitor or display output device. To send the output of the test case to the printer, select Start Printing from the Action topic of the PTT menu bar. Each test case selected is executed in the order it appeared in the Test Cases section of the Test Case Selection dialog panel.

During test execution, ***** Printer Test Tool: Test Running ***** appears in the PTT window title bar. When the test is complete, the name of the individual test selected reappears in the title bar if a single test was selected. Printer Test Tool: MULTIPLE TESTS SELECTED appears if more than one test is selected.

Displaying the PTT Release and Revision Levels
To display the current PTT release and revision levels, select About from the PTT menu bar or use ALT+A.

Exiting PTT
To terminate PTT, select Exit from the PTT menu bar or use ALT+F4 from the keyboard.

GPI Function Tests (32-Bit)
This section shows the GPI calls made by the Printer Test Tool's test groups. The following tables are organized by test group. Each table lists the test cases in the group and the functions tested by each test case. Configuration Settings describes settings that must be selected in the Configuration dialog box to run the test. If no Configurations Settings are specified, use the default settings of OD_QUEUED, PM_Q_STD, GPIT_MICRO, and PU_PELS.

Note: These tables represent GPI calls for the 32-bit PTT.

GPIARC Test Group
The GpiArc test case verifies printer drivers' arc-related functionality. This test case consists of precision, functionality, and exhaustive tests.

The precision tests verify the GPI Arc APIs for page positioning and different arc shapes sizing. The functionality test verifies the GPI Arc APIs as they function together and with other GPI APIs such as GpiBeginPath and GpiEndPath. Exhaustive testing of the GPI Arc APIs involves verifying the functionality of a given API with respect to the print driver.

This table lists the test cases and the functions called by each test case in the GpiArc test group. The GpiArc test group is found in GPIARC.DLL.

GpiArea Test Group
The GpiArea test group tests area manipulation functions. All tests include a basic functionality test and an exhaustive (test all return codes at the lowest level) test.

This table lists the test cases and the functions called by each test case in the GpiArea test group. The GpiArc test group is found in GPIAREA.DLL.

GpiBitmaps Test Group
The GpiBitmaps test group tests bit map manipulation functions. These functions include creating, deleting, querying, selecting, and manipulating bit maps.

All tests include a basic functionality test and an exhaustive (test all return codes at the lowest level) test.

Limitations: All hard-copy vector devices will fail on all bit map operation since it is impossible to translate bit maps to vectors.

This table lists the test cases and the functions called by each test case in the GpiBitmaps test group. The GpiBitmaps test group is found in GPIBTMP.DLL.

GpiChar Test Group
The GpiChar test group tests GPI text functions that: This testcase includes application tests that test the behavior of these character functions with other GPIs.
 * Set and query the current value of the baseline angle.
 * Set and query the current value of the character box attribute.
 * Set and query the current value of the character direction attribute.
 * Set and query the current value of the character-mode attribute.
 * Set and query the current value of the character-shear angle.
 * Draw a character string at the current character position.
 * Draw a character string at a specified character position.
 * Set and query the position at which each character in a string is drawn with positioning controls.
 * Set and query the position at which each character in a positioned string is drawn with positioning controls.
 * Query the size of the default graphics character box.
 * Query the relative coordinates of the four corners of a text box.

This table lists the test cases and the functions called by each test case in the GpiChar test group. The GpiChar test group is found in GPICHAR.DLL.

GpiClip Test Group
The GpiClip test group tests the GPI clipping visible APIs. The following APIs are tested:
 * GpiExcludeClipRectangle
 * GpiIntersectClipRectangle
 * GpiOffsetClipRegion
 * GpiSetClipRegion
 * GpiSetClipPath
 * GpiQueryClipBox
 * GpiQueryClipRegion
 * GpiPtVisible
 * GpiRectVisible

This table lists the test cases and the functions called by each test case in the GpiClip test group. The GpiClip test group is found in GPICLIP.DLL.

GpiColor Test Group
The GpiColor test group tests the GPI Color API, GpiSetColor.

This table lists the test cases and the functions called by each test case in the GpiColor test group. The GpiColor test group is found in GPICOLOR. DLL.

GpiElement Test Group
This testcase is designed to test the GPI element functions that:
 * Open an element bracket.
 * Close an element bracket.
 * Delete the element referenced by the current value of the element pointer.
 * Delete a section of elements inclusively delimited by element pointer values.
 * Delete a section of elements exclusively delimited by labels.
 * Add a single element to the current segment.
 * Query the graphics orders for a single element.
 * Get the graphics orders for a specified segment.
 * Add a buffer of graphics orders to the current segment.
 * Insert a label into the current segment.
 * Move the element pointer by a specified increment.
 * Query information associated with the current element.
 * Set the current edit mode to either insert or replace.
 * Query the current edit mode setting.
 * Set the value of the element pointer.
 * Query the value of the element pointer.
 * Set the value of the element pointer to point at a specified label.

This testcase includes application tests that are designed to test the behavior of these character functions with other GPIs.

Limitations: All exhaustive element functions must be executed within a normal PS.

This table lists the test cases and the functions called by each test case in the GpiElement test group. The GpiElement test group is found in GPIELMNT.DLL.

GpiFont Test Group
The GpiFont test group tests GPI text functions including:
 * Determine whether a given file is a font resource file.
 * Query the font metrics for the current logical font.
 * Query the font metrics for all available fonts, or for the fonts specified by facename.
 * Load one or more fonts from the specified resource file.
 * Unload fonts previously loaded from the resource file.
 * Create a logical definition of a font that an application requires to use.
 * Query kerning pair information for the logical font identified by the current value of the character set attribute.
 * Set the current value of the character-set attribute.
 * Query the character-set lcid.
 * Sets the code page ID for graphics characters for the default font.
 * Query the currently selected graphics code page.
 * Query the fonts that have been created by GpiCreateLogFont, and tagged bit maps.
 * Query the number of local identifiers currently in use, referring to fonts or bit maps.
 * Delete a logical font or bit-map tag.
 * Query width table information for the logical font identified by the value of the character-set attribute.
 * Query the device characteristics.

This table lists the test cases and the functions called by each test case in the GpiFont test group. The GpiFont test group is found in GPIFONT.DLL.

GpiImage Test Group
This module is called by PTT to test the GPI Image APIs. This GPI is used to display raster (bit map) images. The functionality of this GPI and all the error codes that may be returned by this GPI will be tested.

Limitations: GpiImage cannot be used to load bitmaps that a pixel is represented by more than one bit.

This table lists the test cases and the functions called by each test case in the GpiImage test group. The GpiImage test group is found in GPIIMAGE. DLL.

GpiLine Test Group
The GpiLine test group tests the line and polyline APIs with respect to line characteristics and precision.

This table lists the test cases and the functions called by each test case in the GpiLine test group. The GpiLine Test Group is found in GPILINE.DLL.

GpiMarker Test Group
The GpiMarker test group covers the GPI Marker APIs with respect to precision, size, and variation.

This table lists the test cases and the functions called by each test case in the GpiMarker test group. The GpiMarker test group is found in GPIMARKER.DLL.

GpiMeta Test Group
The GpiMeta test group covers the GPI Meta APIs and tests the loading, copying, playing, deletion, and querying of meta files.

This table lists the test cases and the functions called by each test case in the GpiMeta test group. The GpiMeta test group is found in GPIMETA.DLL.

GpiPath Test Group
Paths are used to draw and fill lines and non-rectangular areas. This testcase covers the accuracy of the path limits, the basic functionality of path GPIs and each of the path drawing functions in detail.

Limitations: This testcase does not cover the use of paths for clipping purposes. See the test group GpiClip.

This table lists the test cases and the functions called by each test case in the GpiPath test group. The GpiPath test group is found in GPIPATH.DLL.

GpiPathclip Test Group
The GpiPathClip test group exhaustively tests the GPI Set Clip Path API.

This table lists the test cases and the functions called by each test case in the GpiPathclip test group. The GpiPathclip test group is found in GPIPATH.DLL.

GpiRegion Test Group
The GpiRegion test case tests the GPI Region APIs.

This table lists the test cases and the functions called by each test case in the GpiRegion test group. The GpiRegion test group is found in GPIREGN.DLL.

GpiSegment Test Group
The GpiSegment test case tests the GPI functions associated with segments, including: opening, drawing, deleting, and closing.

This table lists the test cases and the functions called by each test case in the GpiSegment test group. The GpiSegment test group is found in GPISEG.DLL.

GpiShade Test Group
The GpiShade test group tests Pel spacing and shading, vertical box overlapping in Overpaint mode, circle shading in Fill and Outline mode, and FM_OR shading against the color table.

This table lists the test cases and the functions called by each test case in the GpiShade test group. The GpiShade test group is found in GPISHADE. DLL.

GpiStandard Test Group
This module is called by the PTT to test GPI Standard Precision.

This testcase consists of the drawing of a set of grids, using GPI functions, and measuring their accuracy in printed form. This is a visual test; therefore, logging is minimal.

Limitations: The GPI APIs used to draw the grids are not tested for functionality and exhaustive return codes in this testcase. They are covered in the GpiLine test group.

This table lists the test cases and the functions called by each test case in the GpiStandard test group. The GpiStandard test group is found in GPISTD.DLL.

GpiTransform Test Group
The GpiTransform test group tests: This table lists the test cases and the functions called by each test case in the GpiTransform test group. The GpiTransform test group is found in GPIXFORM.DLL.
 * The Page Viewpoint functions
 * Common support functions to set up a transform matrix
 * That all transform GPI work together.
 * Manipulates the transform GPI relationships and combination possibilities
 * Modal transforms
 * Segment transforms
 * The Default View Matrix
 * The Viewing transform GPIs

GpiView Test Group
The GpiView test group tests the following GPIs:
 * GpiSetDefViewingLimits
 * GpiSetGraphicsField
 * GpiSetViewingLimits
 * GpiSetPageViewport

This table lists the test cases and the functions called by each test case in the GpiView test group. The GpiView Test Group is found in GPIVIEW.DLL.

STRESS Test Group
The STRESS test group uses GPI test cases which use a great deal of system resources, such as memory and swapper file space.

This table lists the test cases and the functions called by each test case in the STRESS test group. The STRESS Test Group is found in STRESS.DLL.