PDRREF:Format of the Journal File

Presentation Device Driver Reference for OS/2

Introduction to OS/2 Presentation Drivers Design Considerations for All Drivers Graphics Engine/Presentation Driver Design Changes Design Considerations for Display Drivers Design Considerations for Hardcopy Drivers Display Drivers Distributed Console Access Facility (DCAF) Architecture Graphics Engine Hardcopy Drivers Queue Drivers Port Drivers Presentation Manager Function Categories Exported Driver Function Reference Mandatory and Simulated Graphics Engine Function Reference Device Support Function Reference DBIDI Command Structures and Command Flow Appendixes A - OS/2 Version Compatibility Considerations B - Syntax Conventions C - Format of the Journal File D - Bit-Map Simulation for 16-Bit Hardcopy Drivers E - Data Types F - Notices Miscellaneous G - Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Note: The journal file format is subject to change and should only be accessed by the engine functions. It is presented here to aid debugging of hardcopy drivers that use journal files.

The OS/2 graphics engine journal functions create a file, either in memory or on disk. This file is used to record all OS/2 Presentation Manager graphics functions so that a balance can be achieved between memory usage, image detail, hardcopy device capabilities, and hardcopy device performance.

The format of the record is as follows:

┌───────────────┬───────────────┬───────────────┬───────────────┐
│Flags          │Length         │Function       │arg data (if   │
│(Low Memory)   │               │Arguments      │any)           │
│               │               │               │(High Memory)  │
├───────────────┼───────────────┼───────────────┼───────────────┤
│1 WORD         │1 WORD         │(arg cnt       │Variable size  │
│               │               │DWORDs)        │               │
└───────────────┴───────────────┴───────────────┴───────────────┘

The arg data is the data pointed to by any arguments in the function argument list. The actual journaled argument is changed into an offset to the journal arg data and is fixed up at playback time.

If the bit-map bits or region rects are dumped, they will be written to disk immediately following the journal record to which they belong.

The format of this additional data for bit maps is:

┌───────┬───────┬──────┬──────┬─────────┬─────────────────────────┐
│Data   │Bit Map│Height│Planes│Bit Count│BITS                     │
│Size   │Width  │      │      │         │                         │
├───────┼───────┼──────┼──────┼─────────┼─────────────────────────┤
│1 DWORD│1 WORD │1 WORD│1 WORD│1 WORD   │n bytes, where n =       │
│       │       │      │      │         │((bitcount * width + 31) │
│       │       │      │      │         │/32) * height * planes *4│
└───────┴───────┴──────┴──────┴─────────┴─────────────────────────┘

The format of this additional data for regions rects is:

┌──────────────────────────────┬──────────────────────────────┐
│Data Size                     │DATA                          │
├──────────────────────────────┼──────────────────────────────┤
│1 DWORD                       │Data size/ 16 RECTs           │
└──────────────────────────────┴──────────────────────────────┘

The journal record for any function (including any arg data but not including dumped bit map or region data) is assumed to fit into the journal buffer. If regions or bit maps are written out, they are first dumped into the region/bit-map buffer. It is not necessary for the data to fit into this buffer all at once. However, it is assumed that regions do not have more than 64KB rectangles and bit maps do not have more than 64KB scans.

When private objects are created for the four special case functions, they are recorded. In this way, they can be destroyed by DeleteJournalFile and reused on subsequent playbacks to the same journal file handle. If metafiling this, avoid re-creating the regions from rects or the bit map from the bits for every play.