DevQueryHardcopyCaps

This function queries the hard-copy capabilities of a device.

Syntax

DevQueryHardcopyCaps(hdc, lStartForm, lForms, phciHcInfo);

Parameters

hdc (HDC) - input

Device-context handle.

lStartForm (LONG) - input

Start-forms code.

Forms-code number from which the query is to start. The first forms code has the value 0. lStartForm is used with lForms.

lForms (LONG) - input

Number of forms to query.

If 0, the number of forms codes defined is returned. If greater than zero, this function returns the number of forms codes for which information is returned.

For example, if there are five forms codes defined, and lStartForm = 2 and lForms = 3, a query is performed for forms codes 2, 3, and 4. The result is returned in the buffer pointed to by phciHcInfo.

phciHcInfo (PHCINFO) - output

Hard-copy capabilities information.

A buffer containing the results of the query. The result consists of lForms copies of the HCINFO structure.

At least one of the defined forms codes must have the HCAPS_CURRENT bit set. There might be more than one with either the HCAPS_CURRENT or the HCAPS_SELECTABLE bits set.

For a job to be selected by the spooler for printing, each one of the forms specified in the FORM spooler parameter (see pszSpoolerParams in DEVOPENSTRUC) must be either HCAPS_CURRENT or HCAPS_SELECTABLE. In other cases, the spooler holds the job with a "forms mismatch" error.

Return Code

lFormsReturned (LONG) - returns

Details of forms:

• DQHC_ERROR Error.

• >=0
  • If lForms equals 0, number of forms available.
  • If lForms does not equal 0, number of forms returned.

Errors

Possible returns from WinGetLastError

• PMERR_INV_HDC (0x207C) : An invalid device-context handle or (micro presentation space) presentation-space handle was specified.
• PMERR_INV_FORMS_CODE (0x2076) : An invalid forms code parameter was specified with DevQueryHardcopyCaps.
• PMERR_INV_LENGTH_OR_COUNT (0x2092) : An invalid length or count parameter was specified.

Example Code

#define INCL_DEV /* Or use INCL_PM, */
#include <os2.h>

HDC        hdc;             /*  Device-context handle. */
LONG       lStartForm;      /*  Start-forms code. */
LONG       lForms;          /*  Number of forms to query. */
PHCINFO    phciHcInfo;      /*  Hard-copy capabilities information. */
LONG       lFormsReturned;  /*  Details of forms: */

lFormsReturned = DevQueryHardcopyCaps(hdc,
                   lStartForm, lForms, phciHcInfo);

The height and width of the capability of the output device is queried for each form code available. Note that a valid device context handle must be passed. This example assumes a DevOpenDC call has been made to obtain the device context handle of a say a printer.

#define INCL_DEV
#include <OS2.H>

HDC hdc;
LONG lStartForm;      /* Form code number from which the query */
                      /* is to start                           */
LONG lForms;          /* number of forms to query              */
/* array of structures containing return information. */
HCINFO ahciHcInfo[5];
LONG lreturn;
int i;
HCINFO height[5];
HCINFO width[5];

lStartForm = 0L;
lForms = 0L;           /* the actual number of forms codes is */
                       /* returned. There will be lreturn      */
                       /* copies of the HINFO structure.       */

lreturn = DevQueryHardcopyCaps(hdc,
                               lStartForm,
                               lForms,
                               ahciHcInfo);
if (lreturn > 5)
{
 lreturn = 5L;        /* we only want the first five form codes */
}                     /* if there are more than five            */

for(i = 0; i < lreturn; i++)
{
 width[lreturn].cx = ahciHcInfo[lreturn].cx;
 height[lreturn].cy = ahciHcInfo[lretu

Related Functions

Prerequisite Functions

DevOpenDC

Related Functions

DevQueryCaps

DevQueryDeviceNames