PDFMOD is a program utility that implements the routines that access PDF data in STRINGs and in memory. These routines are extensively used by the PDF I/O and Structure Blaster PROCEDUREs. They are useful only for “low-level” manipulation of PDF data; most programs that perform PDF I/O may do so through the standard I/O PROCEDUREs (read, write, cRead, cWrite, etc.). In particular, if the only use of PDF in a given application is for PDF or Structure Blaster I/O, then there is no reason to use any of the facilities provided by PDFMOD; a normal MAINSAIL file POINTER opened for PDF I/O is sufficient, as described in Section 26.3 of the MAINSAIL Language Manual.

PDFMOD is an intmod containing a collection of macros, FORWARD PROCEDUREs, and INLINE PROCEDUREs, rather than an objmod with interface PROCEDUREs, for efficiency reasons. For a given machine and data type, the PDF representation may be the same as the host data representation. Since this is known at compiletime, the PDF routines use conditional compilation to avoid translating between PDF and host data when it is unnecessary. The use of macros and INLINE PROCEDUREs allow many simple routines to be called with no PROCEDURE call overhead.

PDFMOD provides PROCEDUREs to:

• read PDF data from a STRING or CHARADR and store them as host data (the data types BOOLEAN, (LONG) INTEGER, (LONG) REAL, and (LONG) BITS are supported).

• read host data from a STRING or CHARADR and store them as PDF data (the data types BOOLEAN, (LONG) INTEGER, (LONG) REAL, and (LONG) BITS are supported).

• read PDF characters from a STRING or CHARADR and store them as host characters.

• read host characters from a STRING or CHARADR and store them as PDF characters.

To use the PDFMOD PROCEDUREs described in this section, the following line must be included in the source code:

RESTOREFROM "pdfmod";

Before calling any of the PROCEDUREs that read or write PDF data or text, each MODULE that calls such PROCEDUREs must first call the PROCEDURE pdfInit (see Section 27.8) to perform initialization required by those PROCEDUREs. When no more PDF PROCEDUREs are to be called, the calling MODULE should call pdfDeInit (see Section 27.6).

The tables showing the translation of PDF character codes to host codes and vice versa appear in Appendix F of the MAINSAIL Language Manual.

27.1. pdfCharRead

pdfCharRead reads numChars PDF characters from a STRING or a CHARADR and writes them to a CHARADR as host characters. No translation is done if the host character set and the PDF character set are the same.

In the STRING form, characters written to dst are removed from src. In the CHARADR form, src is displaced by the number of characters read. In both forms, dst is displaced by the number of characters written.

In the STRING form, numChars is automatically adjusted so that it does not exceed the length of the STRING.

In the CHARADR form, the result is undefined if the source and destination overlap.

The effect of writing to or reading from NULLCHARADR is undefined.

27.2. pdfChars

pdfChars returns the number of character units required to represent the host data specified by typeCode as PDF data. pdfChars is undefined if typeCode is not one of booleanCode, integerCode, longIntegerCode, realCode, longRealCode, bitsCode, longBitsCode, addressCode, charadrCode, or pointerCode. The types ADDRESS, CHARADR, and POINTER are treated as LONG BITS.

27.3. pdfCharWrite

pdfCharWrite reads numChars host characters from a CHARADR and writes them to a STRING or a CHARADR as PDF characters. No translation is done if the host character set and the PDF character set are the same.

In the STRING form, characters are appended to dst. In the CHARADR form, characters are written to dst and dst is displaced by the number of characters written. In both forms, src is displaced by the number of characters read.

In the CHARADR form, the result is undefined if the source and destination overlap.

The effect of writing to or reading from NULLCHARADR is undefined.

Note that the src parameter comes first in the CHARADR form, and dst first in the STRING form.

27.4. pdfcRead

pdfcRead returns the host character code for the PDF character read from a STRING or CHARADR.

In the STRING form, the character is removed from the STRING. -1 is returned by the STRING form if the STRING is the empty STRING.

In the CHARADR form, the CHARADR is displaced by one character. pdfcRead from NULLCHARADR is undefined.

27.5. pdfcWrite

pdfcWrite writes the PDF character for a host character ch to a STRING or CHARADR.

The STRING forms append the character to s. In the area form, area specifies the destination area for the resulting STRING.

The CHARADR form writes the character to its CHARADR argument. The CHARADR is then positioned to the next character location. The effect is undefined if the CHARADR is NULLCHARADR.

27.6. pdfDeInit

pdfDeInit releases resources allocated by pdfInit. pdfDeInit may be called more than once; it has no effect if all resources have already been released.

27.7. pdfFldRead

pdfFldRead reads a PDF “field” from a STRING or a CHARADR and returns a host STRING, where a field is a STRING with the specified width.

If width is less than one, the empty STRING is returned.

area specifies the destination area for the result STRING.

In the STRING form, width is automatically adjusted so that it does not exceed the length of the STRING. Characters written to the result STRING are removed from the source STRING.

In the CHARADR form, the source CHARADR is displaced by the number of characters read. The effect of reading from NULLCHARADR is undefined.

27.8. pdfInit

pdfInit performs initialization required by other PDFMOD PROCEDUREs and must be called before any of the other PDFMOD PROCEDUREs is called. pdfInit may be called more than once; it has no effect if all resources have already been allocated.

pdfInit and pdfDeInit must be called from each MODULE that uses PDFMOD PROCEDUREs; it is not sufficient to call them just once from a program consisting of several MODULEs. The reason for this is that the PDF facilities are obtained from the PDFMOD intmod, and are compiled directly into the objmod that uses them; initialization and deinitialization are thus done on a per-MODULE basis.

27.9. pdfRead

pdfRead reads PDF data from a STRING or CHARADR and produces host data.

The forms that read BOOLEAN, (LONG) INTEGER, (LONG) REAL, or (LONG) BITS read PDF data and the STRING forms read PDF characters from the source STRING or CHARADR.

In the forms that read from a STRING, characters read are removed from the STRING. In the forms that read from a CHARADR, the CHARADR is displaced by the number of characters read.

In the forms that read a STRING, the STRING is obtained by scanning the source for the PDF character eol. If the source is a STRING, all scanned characters, including the eol, are removed from the STRING. If the source is a CHARADR, the CHARADR is displaced by the number of scanned characters, including the eol. In the area forms, area specifies the destination area for the produced STRING.

In the forms that read BOOLEAN, (LONG) INTEGER, (LONG) REAL, or (LONG) BITS values from a STRING, the effect is undefined if the length of the STRING is less than the number of characters required to represent the host data as PDF data. In all forms that read a BOOLEAN, (LONG) INTEGER, (LONG) REAL, or (LONG) BITS value, the effect is undefined if the PDF datum is outside the MAINSAIL guaranteed range for the data type.

The effect of reading from NULLCHARADR is undefined.

27.10. pdfWrite

pdfWrite writes host data to a STRING or CHARADR as PDF data.

The forms that write BOOLEAN, (LONG) INTEGER, (LONG) REAL, or (LONG) BITS write PDF data and the STRING forms write PDF characters to the destination STRING or CHARADR.

In the forms that write to a STRING, the characters written are appended to the STRING. In the forms that write to a CHARADR, the CHARADR is displaced by the number of characters written.

In the forms that write to a STRING and in which area is specified, area is the destination area for the resulting STRING.

The effect of the forms that write BOOLEAN, (LONG) INTEGER, (LONG) REAL, or (LONG) BITS is undefined if the value is outside the MAINSAIL guaranteed range.

The effect of writing to NULLCHARADR is undefined.

27.11. The PDF CHARADR Read PROCEDUREs

The PDF CHARADR read PROCEDUREs read PDF data from a source and write them to a destination as host data.

The source CHARADR is displaced by the number of characters read. The destination CHARADR is displaced by the number of characters written.

The effect of reading from or writing to NULLCHARADR is undefined.

27.12. The PDF CHARADR Write PROCEDUREs

The PDF CHARADR write PROCEDUREs read host data from a source and write them to a destination as PDF data.

The source CHARADR is displaced by the number of characters read. The destination CHARADR is displaced by the number of characters written.

The effect of reading from or writing to NULLCHARADR is undefined.