GreCreateJournalFile

GreCreateJournalFile creates a journal file on disk. The presentation driver calls GreCreateJournal when responding to DevEscape DEVESC_STARTDOC.

This function is supported by the graphics engine.

Syntax

GreCreateJournalFile(pszFileName, flOption, cSize, pInstance, lFunction);

Parameters

pszFileName (PSZ) - input

Pointer to a string containing the file name.

flOption (ULONG) - input

Options.

Defined values are:

JNL_TEMP_FILE

An ordinary temporary journal file is created. The pszFileName parameter is ignored.

JNL_PERM_FILE

A permanent journal file is created. The pszFileName parameter points to a fully qualified path or file name.

JNL_ENGINERAM_FILE

A memory journal file is created in shared memory allocated by the engine. The pszFileName parameter is ignored.

JNL_USERRAM_FILE

A memory journal file is created in memory supplied by the caller. The location in memory is identified by the pointer passed in pszFileName.

JNL_DRAW_OPTIMIZATION If set, the process control flag PCTL_DRAW is reset (optimization occurs). The Draw bit is not affected.

JNL_BOUNDS_OPTIMIZATION If set, the process control flag PCTL_BOUND is reset (BOUNDS is turned OFF). Otherwise, current behavior continues.

cSize (ULONG) - input

Size.

If greater than 0, cSize is an indication as to how large the file must be. If flOption is JNL_USERRAM_FILE, cSize must be greater than 0 and is the size of the buffer, which cannot be extended.

If cSize is 0, the calling routine does not know the size of the file.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreCreateJournalFile.

Return Code

rc (ULONG) - returns

Return codes.

This function returns the journal file handle (ULONG), or if an error occurs, it returns NULL.

Possible Errors Detected: If this function fails, the graphics engine will set one of the following error codes:

• PMERR_BASE_ERROR
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_IN_AREA
• PMERR_INV_IN_PATH
• PMERR_INV_JOURNAL_OPTION
• PMERR_RAM_JNL_FILE_TOO_SMALL

Refer to the "Error Explanations" section of the Presentation Manager Programming Reference for further explanation.

Sample Code

#define INCL_GRE_JOURNALING
#include <os2.h>

PSZ      pszFileName;  /*  Pointer to a string containing the file name. */
ULONG    flOption;     /*  Options. */
ULONG    cSize;        /*  Size. */
PVOID    pInstance;    /*  Pointer to instance data. */
ULONG    lFunction;    /*  High-order WORD=flags; low-order WORD=NGreCreateJournalFile. */
ULONG    rc;           /*  Return codes. */

rc = GreCreateJournalFile(pszFileName, flOption,
       cSize, pInstance, lFunction);