STARTDOC

short Escape(hdc, STARTDOC,nCount,lpDocName, NULL)

The STARTDOC printer escape is maintained for backwards compatibility. Applications written for Windows 3.1 should use the StartDoc function.

This escape informs the device driver that a new print job is starting and that all subsequent NEWFRAME escape calls should be spooled under the same job until an ENDDOC escape call occurs. This ensures that documents longer than one page will not be interspersed with other jobs.

Parameters

hdc

HDC Identifies the device context.

nCount

short Specifies the number of characters in the string pointed to by the lpDocName parameter.

lpDocName

LPSTR Points to a null-terminated string that specifies the name of the document. The document name is displayed in the Print Manager window. The maximum length of this string is 31 characters plus the terminating null character.

Return Value

The return value specifies the outcome of the escape. It is –1 if an error such as insufficient memory or an invalid port specification occurs. Otherwise, it is positive.

Comments

Following is the correct sequence of events in a printing operation:

1.Create the device context.

2.Set the Abort function to keep out-of-disk-space errors from terminating a printing operation.

An Abort procedure that handles these errors must be set by using the
SETABORTPROC escape.

3.Begin the printing operation with the STARTDOC escape.

4.Begin each new page with the NEWFRAME escape or each new band with the NEXTBAND escape.

5.End the printing operation with the ENDDOC escape.

6.Destroy the Cancel dialog box, if any.

7.Free the procedure-instance address of the Abort function.

If an application encounters a printing error or a canceled print operation, it must not attempt to terminate the operation by using the Escape function with either the ENDDOC or ABORTDOC escape. Graphics device interface (GDI) automatically terminates the operation before returning the error value.

The STARTDOC escape should not be used inside metafiles.