The Synergy Windows Printing API is a collection of routines that allow you to fully control printing on the Windows platform, and make use of extended printer features.  The API records the print information in a Windows enhanced metafile which can then be played back to devices such as a printer or the print preview window.

Many of you will be using this API to bring true Windows printing capabilities to you applications. So, when you upgraded to version 9.3 of Synergy and rebuilt your applications, where did your prints disappear to?  You may have been caught out by a new feature added to the API.  In version 9.3 two new integer fields were introduced to the font specifications structure to enable you to change the orientation and escapement of the font.  The orientation allows you to specify the angle between the baseline of a character and the page’s horizontal axis.  The escapement specifies the angle between the baseline of a string of text and the page’s horizontal axis.  For full details see the version 9.3 on-line manuals.  The default value for both of these two new fields is zero, meaning that no rotation of the text will occur.

To set the required font characteristics you use the DWP_FONT sub-function of the WPR_SETDEVICE() function.  The font characteristics are defined within a structure called “font_specs”, included in the DBLDIR:winprint.def header file.  This structure is used to allocate memory to store the font specifications, and provide them to the %WPR_SETDEVICE() function.  You allocate the required memory using the %MEM_PROC() function, for example;

    fontHandle = %mem_proc(DM_ALLOC+DM_STATIC, ^size(font_specs))

You can then set the required font details;

    ^m(font_specs.face_name, fontHandle) = “Courier”

However, if you don’t specify values for all of the fields defined within the “font_specs” structure, the values will be undefined, and for the integer fields, most likely be non-zero.  So, the two new fields will actually contain values, and so orientation and escapement settings will be passed to the %WPR_SETDEVICE() function.  Things will no longer print as you expect!

One way to ensure that the integer data is initialised when you allocate dynamic memory is to use the DM_NULL qualifier.  This ensures that any integer data is initialised correctly.  For example;

    fontHandle = %mem_proc(DM_ALLOC+DM_STATIC+DM_NULL, ^size(font_specs))

However, this does not correctly initialise any non-integer data, and is not future-proof.  If the structure is modified to include new alpha/decimal/implied decimal fields in the future, these fields would then contain incorrect values.  An alternative is to initialise a local copy of the font specifications structure and then assign that to the allocated dynamic memory.  The INIT statement ensures that fields within a record or structure are initialised correctly based on the field type.  Firstly, create a structfield, which is a field defined as a structure type.

.ifdef DBLV9

record

    tmpFont    ,font_specs

endrecord

.endc

The code to allocate the memory for the font specification remains the same;

    fontHandle = %mem_proc(DM_ALLOC+DM_STATIC+DM_NULL, ^size(font_specs))

Now we use the structfield to correctly initialise the dynamic memory;

.ifdev DBLV9

init tmpFont    ;ensures individual fields correctly initialised

^m(font_specs, fontHandle) = tmpFont

.endc

This same coding structure can be applied to the other structure specifications defined in the DBLDIR:winprint.def header file.  The code is backward compatible with earlier versions of Synergy, and will prevent any similar issues in the future.

Alternatively, from version 9.1 you can remove the need to allocate memory, and simply use the structfield.  For example;

record

    textFont    ,font_specs

endrecord

And then use the structfield to define font characteristics;

    init textFont    ;ensures individual fields are correctly initialised

    textFont.facename = “Courier”

    textFont.weight = 700

    wpr_setdevice(rptHandle, DWP_FONT, textFont)

    wpr_pint(rptHandle, DWP_WRITEOUT, x, y, “Hello Bloggers!”)

This second approach has two advantages.  Firstly, you no longer need to allocate and clean up any dynamic memory.  The second is that you get full intellisense within workbench, listing the available fields within the font structfield.