C$PDF

This routine enables you to perform PDF printing, offering similar (but more comprehensive) functionality to the collection of PDF_ configuration variables.

Usage

CALL "C$PDF" 
    USING OP-CODE, parameters
    GIVING RESULT

Parameters

OP-CODE: A numeric value that selects which C$PDF function to perform. The op-codes are defined in the cpdf.def COPY file, located in the AcuGT\sample\def (Windows) or sample/def (UNIX) sub-directory of your installation directory. The op-codes are designed to match the functions described by the libharu PDF printing library, and it is those functions that are eventually called by the run time. Refer to Supported PDF Printing Functions for a list of currently supported op-codes, which you should cross-reference with the libharu API docs for more detail. The API docs can be found at https://github.com/libharu/libharu/wiki/API:-Document. There are a few programmatical differences in the COBOL emulation; see the Example section for more details.
parameters: The remaining parameters vary depending on the op-code chosen. They provide information and hold results for the operations specified. Parameters may be omitted from those operations that do not require them. You can refer to the cpdf.def COPY file and the libharu API documentation for more details.; Note: If a libharu parameter is allowed to be NULL, you can omit that parameter (if it is the last parameter), or to pass NULL to C$PDF. These parameters are denoted as (optional) in Supported PDF Printing Functions.
RESULT: A signed numeric data item that returns the status of the operation. The data type of the returned value is SIGNED-INT or PIC S9(9) COMP-5. Unless otherwise stated in Supported PDF Printing Functions, zero indicates success, and a non-zero result indicates failure.

DESCRIPTION

To use this library routine, you must include the COPY file cpdf.def, which is located in the AcuGT\sample\def (Windows) or sample/def (UNIX) sub-directory of your installation directory; copy this file into the Working-Storage section of any program that calls C$PDF. Calls to this library routine then call the third-party libharu PDF printing API (http://libharu.org/).

Example

The following example shows the functions for adding a new document and new page using the libharu API:

HPDF_Doc HPDF_New (HPDF_Error_Handler user_error_fn,
                   void *user_data); 
HPDF_Page HPDF_AddPage (HPDF_Doc pdf);

These are the two equivalent COBOL calls that result in the run time calling the above functions:

call "C$PDF" using HPDF-NEW
             giving HPDF-DOC.
call "C$PDF" using HPDF-ADDPAGE
             HPDF-DOC,
             giving HPDF-PAGE.

As you can see in the COBOL syntax, the function names translate to all upper case and the underscores are replaced by hyphens. The parameters are all prefixed HPDF-, and again use upper case and hyphens.

Notes

All libharu values that are of type HPDF-REAL should be treated as PIC S9(9)v999. In most cases, this can be changed if you need more or less precision, but the values for PAGEHEIGHT, PAGEWIDTH, and HPDF-RECT may not be changed; these are assumed to have 3 digits of precision by the interface code.

Normally, the libharu functions return a status value, which is just returned to the COBOL program in the special RETURN-CODE register (or as the GIVING parameter). Where the libharu function returns a pointer to a structure. C$PDF will return a HANDLE, which can be passed to C$PDF as needed.

Some libharu functions return a HPDF_REAL value, which is a floating-point number. ACUCOBOL-GT cannot return such a value as part of the RETURN-CODE special register, and so the easiest way to code around this is to use REDEFINE, as follows:

01 HPDF-PAGEWIDTH-G.
   03 HPDF-PAGEWIDTH-R PIC S9(9) COMP-5 VALUE 0. 
   03 HPDF-PAGEWIDTH REDEFINES HPDF-PAGEWIDTH-R 
                     PIC S9(9)v999 COMP-5.

You can now use HPDF-PAGEWIDTH-R as the giving value, and the actual page width will be in HPDF-PAGEWIDTH:

HPDF_REAL_HPDF_Page_GetWidth(HPDF_Page page);

This is called from COBOL as:

call "C$PDF" using HPDF-PAGE-GETWIDTH, HPDF-PAGE 
             giving HPDF-PAGEWIDTH-R

This call returns the width of the page (HPDF-PAGEWIDTH).

It is possible to use an implementation that uses both the PDF printing techniques (-P PDF) and C$PDF. You can call C$PDF with the name of an open file (see the CALL Statement, General Rule 6), as long as that file is using the PDF interface (-P PDF). There are some restrictions, which will cause the runtime to halt, such as creating new objects (FONT, PAGE, OUTLINE, etc...). Care must be taken to ensure that you do not modify the page in a way that causes the PDF interface to lose the current position.