FinerEdge Publisher Reference Manual

FinerEdge Publisher Support Documents

FinerEdge Publisher IDE Manual.
FinerEdge Publisher Reference Manual (this document).
FinerEdge Publisher Demonstration Tutorial.
FinerEdge Publisher Author's Guide.
FinerEdge Publisher Programmer's Guide.
FinerEdge Publisher Updates and Acknowledgments.

FinerEdge® Publisher Reference Manual

Version 2.3.2.1

FinerEdge Software

Copyright © 2008 FinerEdge Software. All rights reserved.

All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of FinerEdge Software.

The information in this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by FinerEdge Software. FinerEdge Software assumes no responsibility or liability for any errors or inaccuracies that may appear in this manual. The software described in this manual is furnished under license and may only be used or copied in accordance with the terms of such license.

FinerEdge Publisher is a trademark of FinerEdge Software. Windows, .NET, C#, and Visual Basic are registered trademarks of Microsoft Corporation. Java is a registered trademark of Sun Microsystems, Inc. PostScript is a registered trademarks of Adobe Systems Incorporated. XHTML is a trademark of the World Wide Web Consortium (W3C). XML and CSS are trademarks of the Massachusetts Institute of Technology (MIT) and are used by the World Wide Web Consortium (W3C). All other brand or product names are the trademarks or registered trademarks of their respective owners.

Contents

Chapter 1 - Introduction

Overview

FinerEdge Publisher is a revolutionary XML-based document rendering engine that is built from the ground up based upon common industry standards. The FinerEdge Publisher system is specifically designed for server-side automated cross-media publishing of high-quality document productions. Note: All FinerEdge Publisher components and interfaces are multi-threaded capable (i.e., thread-safe).

FinerEdge Publisher documents are XML-based "smart" entities that encompass the twin concepts of conditional processing and conditional formatting to any degree that document authors may require. Thus, FinerEdge Publisher was created to embrace the ever-expanding automation and personalization requirements of competitive businesses today.

FinerEdge Publisher is capable of creating precise, high-quality output for a broad range of document types from "compliant" business documents and documents that require a high-degree of personalization to large catalogs and even sub-catalogs delivered through the Web. FinerEdge Publisher can fully automate most document-related tasks saving a company both time and money from having to repetitively produce documents manually using traditional Desktop publishing systems.

The benefits derived from investing in an automated solution such as FinerEdge Publisher versus traditional desktop publishing systems for high-volume and high-content repetitive tasks are:

●	Greatly reduced cost and time to produce documents.
●	Virtually eliminate all production errors resulting in lost revenue.
●	Take advantage of new opportunities such as automatically "on-the-fly" producing fully compliant and printable business documents and sub-catalogs that are delivered over the Web.

FinerEdge Publisher consists of a number of "interface components" which, in turn, call the FinerEdge Publisher document rendering engine to create output in cross-platform, industry standard formats. The interface components of FinerEdge Publisher are:

●	Document Writer Interfaces (FPWriterNET and FPWriter).
●	Dual Interface Automation Server Interface (FPServer).
●	Java Native Interface (JNI).
●	Dynamic Link Library Interface (DLL).
●	Document Form Interfaces (FPFormNET and FPForm).

The cross-platform industry, standard output formats of FinerEdge Publisher are:

●	Portable Document Format (PDF).
●	PostScript (PS).
●	XML Paper Specification (XPS).
●	Rich Text Format (RTF).
●	Strict compliant XHTML.
●	Text and tagged text.
●	Direct Printing.
●	Direct Viewing.
●	Custom generated Active Server Pages (ASP) document processes.
●	Custom generated Java Server Pages (JSP) document processes.

The standard data input formats of FinerEdge Publisher are:

●	Any ODBC Data Sources.
●	Any XML Data Files.
●	Direct application data.

The FinerEdge Publisher software product runs under the Windows 2000 (or above) operating system.

» Back to the Table of Contents. «

Chapter 2 - Entities and Catalogs

XML Entities in FinerEdge Publisher

XML external entities play a large role in the development of FinerEdge Publisher documents. External entities are files that are included in a document by the XML parser and processed exactly as if they were part of the base "document entity". External entities are also referred to as "module entities" in contrast to the base document entity.

The difference between a document entity and a module entity is that a document entity additionally contains an XML prolog and Document Type Definition (DTD), while the module entity contains only methods. FinerEdge Publisher can easily transform a document entity into a module entity or visa versa.

Even though according to XML rules, all external entities must be declared within the document's DTD, FinerEdge Publisher module entities support a hierarchical structure that emulates the way an individual naturally thinks. FinerEdge Publisher automatically resolves the document hierarchy into the "flat" structure needed for XML processing without involving the document author.

Anytime a document author includes a module entity into either a document entity or another module entity in order to use it's methods ("methods" are discussed later in this chapter), FinerEdge Publisher stores a special XML Processing Instruction (PI) tag at the beginning of the entity. When FinerEdge Publisher automatically builds the DTD and includes it in a document, the special PI tags are located and processed within the applicable entities.

An example of a valid XML FinerEdge Publisher Processing Instruction (PI) in a document entity or module entity is shown below. "Test_Mod1" refers to an catalog entry that is discussed in the next section of this chapter. Module entities may be defined in the catalog or referenced directly.

<?FPINCLUDE Test_Mod1?>
<?FPINCLUDE Test_Mod2 = "C:\mods\mod2.fpm"?>

The Processing Instructions within an entity can also refer to other external entities and so on until a hierarchical "map" is formed. The hierarchical map and the applicable methods are displayed to the document author within the IDE's entity pane for easy navigation between a document's primary elements. From the hierarchical map, duplicate entities are automatically eliminated and the DTD and associated references to the external entities are stored into the document entity.

All FinerEdge Publisher processing is done from within methods. The base document entity declares one method to be the "main" method that is called first by FinerEdge Publisher. When the main method is exited, document processing is complete. All other methods are called directly or indirectly (i.e., through other methods) from the main method. Any method can call any other method; however, methods cannot be embedded within other methods.

Methods can declare "local" variables for their own use. When the method is exited, the local variables are automatically discarded. Methods can also employ global document variables and external variables that were exposed by the ODBC interface, XML data files, application, or calling process.

An example of a document hierarchy is shown in the following diagram:

» Back to the Table of Contents. «

Catalogs in FinerEdge Publisher

A catalog file is a simple ASCII file that contains catalog entries. Each line of a catalog file contains a different catalog entry and is terminated by a carriage return and linefeed. Each entry within a catalog file contains a keyword followed by a value for that keyword.

Catalogs allow indirect references to be used that represent the actual names for external entities or element in a document. By using a catalog file, if the location of the physical entity changes, only the contents of the catalog file need be updated. The documents themselves and all corresponding module entities will not require any modification.

Each document can have it's own catalog file or all documents can share the same catalog file. Typically though, a related group of documents share the same catalog file while another group of documents would utilize a different catalog file.

All catalog entries begin with the keyword "ENTITY". FinerEdge Publisher defines three different variations of the ENTITY keyword that can be utilized within the catalog file as described by the following text.

ENTITY file -

The first variation of the ENTITY keyword relates an internal mnemonic to its corresponding absolute or relative file name. Relative file names are with respect to the document entity's directory path. An example of a FinerEdge Publisher catalog file is as follows:

ENTITY FPMod1 "C:\FP\Mods\fpmod1.fpm"
ENTITY FPMod2 "..\Mods\fpmod2.fpm"

ENTITY font -

The second variation of the ENTITY keyword is used to define fonts. All font entities must be defined in the corresponding catalog file, by utilizing the catalog editor of the IDE, prior to using them in a document. An example of the font variation of the ENTITY keyword is as follows:

ENTITY FONT_MyFont "'Arial','Helvetica',
'Helvetica-Bold','Helvetica-Oblique','Helvetica-BoldOblique'"

The prefix "FONT_" identifies the catalog entry as a font variation of the ENTITY keyword. "MyFont" is the internally defined name that is referenced from within the documents. The five components of the text that follow the internally defined name are the Windows font name and the PDF/PostScript normal, bold, italic, and bold-italic fonts names. These names will be substituted for the internally defined name depending upon the FinerEdge Publisher output format being generated and options selected.

Either TrueType or Type 1 fonts are supported for embedding into both PDF and PostScript output formats. TrueType fonts are supported for embedding into the XPS output format. TrueType fonts must allow embedding as determined by their respective copyright licenses. If a TrueType font does not allow embedding, FinerEdge Publisher will indicate this to the document author in the IDE's font editor. It is the responsibility of the document author using a particular font to adhere to the published font license regarding font embedding.

Adobe Type 1 fonts must be available in Printer Font Binary (PFB) format as is typical for all Type 1 fonts residing on a Windows platform. FinerEdge Publisher automatically converts PFB files into Printer Font ASCII (PFA) files when embedding a font into PDF or PostScript output.

Note: There is no need to define standard Base 14 font names. Base 14 fonts are present in all PDF and PostScript viewers and interpreters. However, defining a Base 14 font yourself will cause the font to be embedded in a document. The Base 14 fonts consist of Courier, Helvetica (i.e., Arial), Times-Roman, Symbol, and ZapfDingbats.

To disallow a font from being embedded into a document, prefix each applicable PDF/PostScript field with a caret (i.e., "^"). This will cause a font reference to be formatted into the document instead of actually embedding the font. This has no effect upon XPS documents as fonts are required to be embedded. (Warning: The referenced font must be available to the PDF viewer or PostScript interpreter, otherwise font substitution will occur.)

ENTITY image -

The third variation of the ENTITY keyword is used to define images. Like entities, it's recommended that commonly used images be defined in the FinerEdge Publisher catalog file as an internally known name instead referencing them directly from a document. If the image location ever needs to be changed, it could simply be updated in the catalog file without directly modifying any documents. An example of the image variation of the ENTITY keyword is as follows:

ENTITY IMAGE_MyImage1 "C:\FP\FPTest\fp1.jpg"
ENTITY IMAGE_MyImage2 "..\Images\fp2.png"
ENTITY IMAGE_MyImage3 "http://www.mysite.com/fp3.tif"

The prefix "IMAGE_" identifies the catalog entry as an image variation of the ENTITY keyword. For example, "MyImage1" is the internally defined name that is referenced from within documents. The text that follows the internally defined name can be an absolute file name, a relative file name, or a url. Relative names are with respect to the document entity's directory path.

Note: It's recommended that an individual use the FinerEdge Publisher Integrated Development Environment (IDE) catalog editor to create and modify catalog entries for a FinerEdge Publisher catalog file.

» Back to the Table of Contents. «

Chapter 3 - FinerEdge Publisher Tags

Overview

The FinerEdge Publisher Markup Language (FPML) is specifically designed to utilize well-known XHTML elements and CSS styles while allowing conditional processing to occur to any extent that the document author may require, and to accommodate the unique needs of paged and precisely formatted documents. Instead of having a large number of physical documents for given document type, the document author can maintain a much smaller number of physical documents that each have the ability to alter themselves based upon the external data made available to the document.

In addition to conditional processing, FPML is designed to inherently make use of external data that is made available to the document. Data is organized into "recordsets" of information that may be arbitrarily large or small as needed. Also, "drilldowns" can be used with recordsets to enable one-to-many relationships to any nesting level desired. External variables, recordsets, and drilldowns are built-in elements of FPML and, as such, are relatively easy and intuitive for a document author to use.

The external data could come from a number of different sources, including the calling application itself. When the external data comes from the calling application, an individual has complete control over what is accessible and how it's accessed and presented to FinerEdge Publisher.

FinerEdge Publisher stores external variables in its symbol table. Unless variables are purposely cleared (i.e., by fetching the next record of a recordset), a document author can reuse the external variables in a document as many times as desired without incurring the overhead of repeated data fetches.

The majority of all formatting in FinerEdge Publisher is accomplished through style properties. Because of the conditional processing capabilities of FinerEdge Publisher and the ability to use conditional expressions directly with style properties, FinerEdge Publisher also embodies the concept of conditional formatting. For example, a table could enlarge itself or add more columns based upon external data or, alternatively, images could change or be added based upon still other external data.

All tags, except DOCUMENT, must occur within a METHOD tag pair. METHODs are the most fundamental component of FinerEdge Publisher and are callable by other METHODs either from within the same entity or another external entity. In addition, METHODs may or may not be defined with formal parameters that may pass variables, expressions, etc. METHOD parameters may also be bi-directional and return data to the caller.

When input is read from a document or module entity, FinerEdge Publisher interprets carriage returns and linefeeds as spaces. In addition, multiple spaces are usually compressed into a single space (the string mnemonic " " may be used to force an absolute space in the output if desired). Finally, spaces prior to a new line of output are also discarded.

Standard XML comments (i.e., "") and CDATA sections (i.e., "<![CDATA[ ... ]]>") can be freely included within any FinerEdge Publisher (FPML) document. One of the common uses of a CDATA section within a FinerEdge Publisher document might be to embed it within an HTML tag pair. The FinerEdge Publisher Integrated Development Environment (IDE) supports both XML comments and CDATA sections as well as the HTML tag pair from within the CDATA editor.

Within a document, non-paired tags (i.e., those tags that do not have an ending tag) are terminated with the character sequence "/>". This syntax is a requirement of XML rules and FinerEdge Publisher strictly adheres to this convention. By utilizing the FinerEdge Publisher IDE visual designer (i.e., WYSIWYG) or markup editors to create and modify FPML elements, styles, and expressions, the document author need not be concerned with syntactical issues.

» Back to the Table of Contents. «

<BR/>

Examples:

<BR/>

Attributes:

None.

Description:

Perform a line break (i.e., end this line and begin a new line). This causes the accumulated line to be formatted and output depending upon the measurements of font sizes, embedded SPANs, etc. The new insertion point is moved to the beginning of the next line within the current element as determined by the calculated overall line-height.

If no text has been accumulated for a line, the BR tag will use the default line-height of the current element's style and font to position to the next line.

» Back to the Table of Contents. «

CASE

<CASE expr = "<expressions>|ELSE"/>

<expressions>:

<expression> [, <expression>]...

Examples:

Attributes:

expr	Specifies valid FinerEdge Publisher <expression>s.

Description:

One or more CASE tags are embedded within a SELECT tag pair. When the SELECT tag is encountered, its <expression> is first evaluated. The result of the SELECT tag's expression is then successively compared to each CASE tag's <expression>s within the SELECT tag pair.

When a match is found, the tags and text following the CASE tag are processed until another CASE tag is encountered or the corresponding end SELECT tag is seen. Subsequent CASE tags within the SELECT tag will not be processed. If no matching CASE tag is encountered, then no tags and text within the SELECT tag pair will be processed.

A special form of the CASE tag (i.e., "CASE ELSE") may be used to provide default processing should no match occur. In this case, the <CASE expr = "ELSE"/> must be the last CASE tag within the SELECT tag pair.

SELECT and CASE tag <expression>s can evaluate to either a <number> (i.e., whole number) or a <string>. However, both the SELECT tag's <expression> and the embedded CASE tag's <expression>s must evaluate to be of the same type (i.e., <number> or <string>).

» Back to the Table of Contents. «

COLBR

Examples:

Attributes:

height

When this attribute is used with the COLBR tag, a COLBR action will only occur if the specified height is greater than the remaining height for the table or for the page (if the height was not explicitly indicated for the table). The remaining height within the current column of the table or page is calculated with respect to formatted boxes, the footer, etc. The "height" attribute is not compatible with XHTML generation and is therefore ignored.

Description:

This tag can only be used within a TABLE tag pair. Since TABLEs can be nested within each other, the COLBR applies to the TABLE at the same level as itself. Alternatively, the XHTML TR/TD model may be used within a TABLE element. In that case, no COLBR tags should appear with the TABLE element. When a table "type" of "Newspaper" is specified, only COLBRs should be used (i.e., without outer DIV elements) or the table's row heights will be visually synchronized. For more information, please refer to the TABLE element.

The COLBR tag causes the next defined column within the current TABLE to be made active (see the "cols" attribute of the TABLE tag). Any subsequent processing is done within the new column until another COLBR tag is encountered or the end TABLE tag is seen. When the table's type has been specified as "Newspaper", this gives a newspaper style appearance to the table where columns heights need not be synchronized with each other.

When a COLBR tag is used in the last column of a TABLE, the first column is again wrapped around and made active. If column wraparound occurs, all of the column heights within the table are normally synchronized with the height of the longest column (i.e., the "rows" can be variable in length but all of the columns within each row start at the same vertical point). This gives a normal table style appearance where the columns for a row are synchronized with each other.

» Back to the Table of Contents. «

DIV

<DIV [id = "<Class selector>"]
     [class = "<ID selector>"]
     [style = "<Style properties>"]>
   ...
</DIV>

Examples:

Attributes:

id	A style "id" previously defined with the STYLE tag.
class	A style "class" previously defined with the STYLE tag.
style	Inline style properties.

Description:

The DIV tag in FinerEdge Publisher is modeled after the DIV tag in XHTML and is a general purpose block-level element. The DIV tag has much of the same properties as the XHTML DIV tag except when it comes to physical page breaks and the page break checkpoint mechanism. DIV tags may be nested within other DIV tags or TABLE tags. Conversely, TABLE tags may be nested within DIV tags. However, DIV tags may not be nested within SPAN tags.

» Back to the Table of Contents. «

DOCUMENT

<DOCUMENT [style = "<Style properties>"]
     [dateformat = "<string constant>"]
     [timeformat = "<string constant>"]
     [datedelim = "<string constant>"]
     [timedelim = "<string constant>"]
     [dpdelim = "<string constant>"]
     [thdelim = "<string constant>"]
     [curdelim = "<string constant>"]
     [defchar = "<string constant>"]
     [deflength = "<number constant>"]
     [staticrefs = "Yes|No"]
   ...
</DOCUMENT>

Examples:

Attributes:

style

Inline style properties.

dateformat

us	Use user specified date.
mm	Use MM/DD/YY date.
dd	Use DD/MM/YY date.
yy	Use YY/MM/DD date.
jj	Use YY/DDD Julian date.
nn	Use straight number of days.
cm	Use MM/DD/YYYY date.
cd	Use DD/MM/YYYY date.
cy	Use YYYY/MM/DD date.
cj	Use YYYY/DDD Julian date.

timeformat

us	Use user specified time.
mm	Use HH:MM 24-hour time.
ss	Use HH:MM:SS 24-hour time.
am	Use HH:MMa/p 12-hour time.
as	Use HH:MM:SSa/p 12-hour time.

datedelim

A single character date delimiter.

timedelim

A single character time delimiter.

dpdelim

A single character decimal point delimiter.

thdelim

A single character thousands delimiter.

curdelim

A single character currency delimiter.

defchar

The default character used by the VAR tag when the resulting expression is an empty string (i.e., ""). Please refer to the VAR tag for more information.

deflength

The default length used by the VAR tag when the resulting expression is an empty string (i.e., ""). Please refer to the VAR tag for more information.

staticrefs

Creates a static reference table (normally used with a Table of Contents).

Description:

There are two types of external entities in FinerEdge Publisher: document entities and module entities. Document entities contain an XML Prolog, FinerEdge Publisher Document Type Definition (DTD), and the DOCUMENT tag. Within the DOCUMENT tag exist one or more METHODs. One of the METHODs is designated to be the "main" METHOD and is processed first. All other METHODs are either called directly or indirectly (i.e., through another METHOD) from the main METHOD.

In contrast, module entities contain only METHODs, each of which may contain any or all FinerEdge Publisher tags, styles, etc. with the exception of the DOCUMENT tag. Also, module entities do not contain an XML prolog or a Document Type Definition (DTD).

The DOCUMENT tag is not directly visible in the FinerEdge Publisher IDE. All manipulation of the DOCUMENT tag is done via the DOCUMENT tag editor. While working in the FinerEdge Publisher IDE, it's easy to turn a document entity into a module entity and visa-versa (in fact, a single checkbox within the DOCUMENT tag editor accomplishes this).

Background images and their related properties may be specified within the DOCUMENT tag's in-line style. When a background image is used at the document level, the region where the image is placed is inclusive of any page areas but exclusive of the document's page margins and gutter. A document's styles may also be dynamically changed during document processing by setting the "style" attribute of the PAGEBR tag.

The "staticrefs" attribute is used to direct FinerEdge Publisher to perform a simple scan of the document, prior to any actual processing, looking for static references (i.e., those references having a constant value in the ref-search property). For each static reference found, the ref-search constant value is stored into an array called "Reference".

The first reference stored into the Reference array is at index 1 while the last reference stored into the Reference array is specified by a preset variable called "RefCount". For example, this allows a "Table of Contents", to be created anytime during document processing for all static references.

Additionally, when the "staticrefs" attribute of the DOCUMENT tag is used with an XHTML generation, anchor tags (i.e., "A" tag) are also inserted at the reference locations within the document. The anchor tag's "name" attribute is set to the value of the ref-search property.

» Back to the Table of Contents. «

ELSE

<ELSE/>

Examples:

Attributes:

None.

Description:

This tag provides a final "else" part to an IF tag pair. The ELSE tag must be embedded within an IF tag pair and is associated with the IF tag at the same level (i.e., IF tags may be nested within other IF tags). This tag is optional within an IF tag and must follow all other ELSEIF tags at the same level (if they exist).

All tags and text that follow the ELSE tag and are prior to the end IF tag will be processed if the <expression> to the preceding IF and ELSEIF tags are false.

» Back to the Table of Contents. «

ELSEIF

Examples:

Attributes:

expr	Specifies a valid FinerEdge Publisher <expression>.

Description:

This tag provides an intermediate conditional "else" part to an IF tag pair. The ELSEIF tag must be embedded within an IF tag pair and is associated with the IF tag at the same level.

All tags and text that follow the ELSEIF tag and are prior to another ELSEIF tag, ELSE tag or the end IF tag will be processed if the <expression> to the preceding IF and ELSEIFs are false and the <expression> to this ELSEIF tag is true.

» Back to the Table of Contents. «

EXIT

Examples:

Attributes:

tag	The type of tag to be exited (i.e., LOOP or METHOD).

Description:

The EXIT tag allows for a premature exit from either a loop (FOR tag or WHILE tag) or a METHOD. If LOOP is specified for the "tag" attribute, the currently active loop (FOR or WHILE) is terminated and control passes to the next tag or text following the end FOR or end WHILE tag respectively.

When METHOD is specified for the "tag" attribute, the currently active METHOD is terminated. If any loops (FOR or WHILE) are active when the EXIT tag is invoked for a METHOD, they are also terminated.

When the currently active METHOD is the main METHOD, the document is then completed. If the currently active METHOD is not the main METHOD, the METHOD is exited normally passing back the values for any parameters specified as "ByRef" to the calling METHOD (please refer to the METHOD tag for more information on this subject).

» Back to the Table of Contents. «

FILE

Examples:

Attributes:

action

Open	Open an existing or new file identified by the "slot" attribute with the path given in the "value" attribute. Optionally open the file with the code page "ANSI" (default value), "OEM", or "UTF8" given in the "value2" attribute.
Read	Read from a previously opened file identified by the "slot" attribute into a <string variable> given in the "value" attribute. Since an empty record will return a zero-length string, the constant "<EOF>" is returned when the end-of-file is seen.
Write	Write to a previously opened file identified by the "slot" attribute with the text given in the "value" attribute.
Close	Close a previously opened file identified by the "slot" attribute.
Exists	Determines if the file given in the "value" attribute exists and places the result (0=Does not exist, 1=Exists) into a <number variable> given in the "value2" attribute.
Delete	Delete an existing file given in the "value" attribute.
Rename	Rename an existing file given in the "value" attribute to the new name given in the "value2" attribute. The Rename action can be used to move a file between directories.
Copy	Copy an existing file given in the "value" attribute as the new name given in the "value2" attribute.

slot

A number ranging from 1 to N (typically 10) that identifies a particular file for Open, Read, Write, and Close actions.

value

Depending upon the action chosen, the content of this attribute varies (see the "action" attribute for additional information).

value2

Depending upon the action chosen, the content of this attribute varies (see the "action" attribute for additional information).

Description:

Performs various actions to include opening, reading, writing, closing, checking the existence of, deleting, and renaming text files. Read actions input the next record of text following the current file position. Write actions output text at the end of the file, which is then terminated by an appropriate newline sequence.

» Back to the Table of Contents. «

FOR

<FOR var = "<number variable>"
     start = "<expression>"
     end = "<expression>"
     [step = "<expression>"]>
   ...
</FOR>

Examples:

Attributes:

var	A <number variable> to be assigned a new value each time through the loop.
start	Specifies a valid FinerEdge Publisher <expression> to start the loop.
end	Specifies a valid FinerEdge Publisher <expression> to end the loop.
step	Specifies an optional FinerEdge Publisher <expression> to step the loop.

Description:

The FOR tag is a conditional processing loop tag within a FinerEdge Publisher document (please refer to the IF, SELECT, and WHILE for additional conditional processing tags). FOR tags may be nested within other FOR tags.

All tags and text following the FOR tag and prior to the end FOR tag are processed each time through the loop. The content of the "var" attribute must be a <number variable>. If the <number variable> has not been previously declared (i.e., with the SET tag), it is automatically declared.

The attributes "start", "end", and optional "step" each specify an expression that is evaluated when the loop is first encountered and must result in a positive or negative whole number. The result of the "start" attribute is initially assigned to the <number variable> as it's beginning value. If the optional "step" attribute is not included, a step value of 1 is used.

The value of the <number variable> is compared to the value of the attribute "end" each time through the loop including the first time the loop is encountered. If the step value is positive, the loop is ended when the start value is greater than the end value. If the step value is negative, the loop is ended when the start value is less than the end value.

When the end FOR tag is seen, the <number variable> is incremented or decremented by the step value. Processing then continues at the beginning of the loop where the "end" attribute condition is again evaluated to determine if the loop will proceed or not. If the loop is terminated, processing continues following the end FOR tag.

» Back to the Table of Contents. «

HEADER

Examples:

<TABLE cols = "50%,50%">
   <HEADER>
     <DIV>Column 1</DIV>
     <COLBR/>
     <DIV>Column 2</DIV>
     <COLBR/>
   </HEADER>
   ...
</TABLE>

Attributes:

None.

Description:

The HEADER tag pair may be used within either TABLE or DIV elements in order to supply content that will be automatically regenerated over page breaks. A good example of this is a table that spans more than one page. In this case, the table header will be regenerated and redisplayed following each page break and prior to continuing with the formatting of the table.

When employed, the beginning HEADER tag must appear just after the beginning TABLE or DIV element tag. When used in a TABLE, the content of the HEADER tag pair must populate an entire row (i.e., all columns for a row). If elements are embedded within each other that each declare HEADER tag pairs, all of the table headers will be regenerated in the proper order following a page break.

» Back to the Table of Contents. «

HTML

Examples:

<HTML>
... (Zero or more lines of HTML output)
</HTML>

Attributes:

None.

Description:

The "HTML" tag allows document authors to include markup and text in a FinerEdge Publisher document that is intended for XHTML generation only. When XHTML is generated from the document, the content of all HTML tags are preserved and included in the generated file, however FPML HTML tags themselves are not included in any document output.

FPML HTML tags cannot contain any PAGEAREA, PAGEBOX, and STYLE tags. All other tags within HTML tags are handled prior to generating the XHTML document output. In addition, all "<", ">", and "&" characters that are intended to be normal text should be escaped (i.e., "\l", "\g", and "\m" respectively) unless a CDATA section is also used within the FPML HTML tag.

» Back to the Table of Contents. «

HTMLELSE

Examples:

<HTML>
... (Zero or more lines of HTML output)
<HTMLELSE/>
... (Zero or more lines of common output)
</HTML>

Attributes:

None.

Description:

The HTMLELSE tag can be used within the FPML HTML tag pair to allow optional generation for other common output types as well as XHTML output type. This allows a document author to further differentiate between paged type output versus non-paged XHTML output.

» Back to the Table of Contents. «

Examples:

Attributes:

expr	Specifies a valid FinerEdge Publisher <expression>.

Description:

The IF tag is a conditional processing tag within a FinerEdge Publisher document (please refer to the FOR, SELECT, and WHILE for additional conditional processing tags). The ELSEIF and ELSE tags may be embedded within this tag to provide optional processing when the result of the IF tag's <expression> is false. IF tags may be nested within other IF tags.

All tags and text that follow the IF tag and are prior to an ELSEIF tag, ELSE tag or the end IF tag at the same level will be processed if the <expression> to this tag is true.

» Back to the Table of Contents. «

MARK

Examples:

Attributes:

type	Fire, Initialize, or Increment (see below).
expr	Specifies a FinerEdge Publisher <expression>.

Description:

Various actions are performed depending on the value of the "type" attribute as follows:

Fire -

The default type of Mark Event is fired during document rendering to inform a calling application of a significant document processing event. However, the "FireMark" property can additionally control when the Mark Event is fired.

Initialize -

To initialize FinerEdge Publisher's document generation status mechanism and receive processing, rendering, and generating events, each participating document must include a Mark tag with a "type" attribute value of "Initialize". In addition, the calling application must also be willing to participate in reporting these status events (Note: The IDE is always enabled to participate in status events).

The "expr" attribute must contain four whole numbers, each of which may specify a sub-expression, as follows:

When the <Processing Maximum> or the <Processing Interval> has a value of zero, processing Mark events will not be sent to the application. Likewise, if <Rendering Interval> or <Generating Interval> have values of zero, rendering Mark events and generating Mark events will not be sent to the application respectively.

The value of <Processing Maximum> is the maximum number of increments that will be performed during document processing. The value of <Processing Interval> is the percentage interval between processing events sent to the application (e.g., if the <Processing Interval> is 10, a processing event will be sent to the application for every 10% of the document processed).

Like the <Processing Interval>, the value of <Rendering Interval> is the percentage interval between rendering events sent to the application (e.g., if the <Rendering Interval> is 10, a rendering event will be sent to the application for every 10% of the document rendered).

Also like the <Processing Interval>, the value of <Generating Interval> is the percentage interval between generating events sent to the application (e.g., if the <Generating Interval> is 10, a generating event will be sent to the application for every 10% of the document generated).

Increment -

The "expr" attribute determines the number of increments that are made. When the number of increments reaches the value set by the <Processing Maximum>, the processing event will report 100%. The default for the "expr" attribute is 1.

» Back to the Table of Contents. «

METHOD

Examples:

Attributes:

name	The name of the method.
params	The optional parameters of the method. For each parameter specified, an initialization value (i.e., following the "=") must be supplied, even if the initialization value is specified as being "any type" ("*").
main	"Yes" indicates the main method, "No" indicates a standard method.

Description:

A METHOD tag pair encapsulates a group of tags and text in a FinerEdge Publisher document. Any tags or text except DOCUMENT and METHOD may appear in the body of a METHOD. METHODs can use other METHODs which, in turn, can use still other METHODs and so on (please refer to the USE tag for more information on this subject). However, METHOD tags cannot be embedded within other METHOD tags.

One such METHOD within a document entity must be declared as the main METHOD by using the attribute "main". The main METHOD may also declare parameters with initialization values. If the main method includes parameters, corresponding variables will be created for each parameter as "@Global_<parameter name>.

The main METHOD is the method that is entered first when a FinerEdge Publisher document is processed. All other METHODs are used either directly or indirectly from this METHOD. When the end METHOD tag is reached for the main METHOD, document processing is complete.

All other METHODs may or may not be declared within the same document entity as the main METHOD. In order to modularize common document sections or routines, METHODs may be declared in module entities. Module entities are entities that consist of only METHODs and their respective tags and text (i.e., module entities have no XML Prolog, Document Type Definition, or DOCUMENT tag).

Parameters -

METHODs may have parameters as specified by the "params" attribute. Parameters are local variables that are declared at the same level as the METHOD. When the end METHOD tag is seen or the EXIT tag exits the METHOD, any parameters or local variables declared at the same level as the METHOD are discarded.

Initialization values ("=") are required for each parameter specified. Apart from the special usage for the main METHOD (see above), initialization values serve three important purposes. First, initialization values define the parameter as either a type of number, float, string, or "any type" ("*"). With the exception of "any type" ("*"), if the USE tag's corresponding parameter does not have the same type, an error will be generated. Second, the USE tag can also specify an asterisk ("*") to indicate that the initialization value should be used for any optional "By Value" parameter. (Note: A parameter of "any type" will initially be seen as an empty string.) Third, the visual designer (WYSIWYG) view in the IDE uses the initialization values to apply a type other than string to parameters and to also supply default values for display purposes while editing a document.

By default, the parameter are passed from the caller to the METHOD "By Value". That is, copies of the data from the USE tag's parameters are created so that any modification to the METHODs parameters will not affect the caller. When a parameter is preceded by the optional keyword "ByRef", it is declared "By Reference" (i.e., when the METHOD is exited, the updated value of the parameter variable is copied back to the corresponding USE tag's variable prior to discarding it). If a "ByRef" parameter variable changes it's type within a METHOD (via a "SET" tag), that change is reflected back to the corresponding USE tag's parameter variable.

Any parameters that are declared as "ByRef" by the METHOD must be passed as actual variables (i.e., not <expression>s) by the USE tag calling the METHOD. In addition, the same number of parameters must exist in the USE tag as are declared in the called METHOD unless an asterisk "*" optional parameter is given in the USE tag.

» Back to the Table of Contents. «

PAGEAREA

Examples:

Attributes:

A style "id" previously defined with the STYLE tag.

class

A style "class" previously defined with the STYLE tag.

style

Inline style properties.

type

HEADER	Header page area.
FOOTER	Footer page area.
LEFT	Left page area.
RIGHT	Right page area.

scope

ALL	All page areas.
ALL-ODD	Only odd page page areas.
ALL-EVEN	Only even page page areas.
FIRST	First page page areas.
FIRST-ODD	Only odd first page areas.
FIRST-EVEN	Only even first page areas.
BODY	Only non-first page areas.
BODY-ODD	Only odd non-first page areas.
BODY-EVEN	Only even non-first page areas.
HTML	Applies to a HEADER type only. Content is placed within the HEAD tag pair for XHTML generation.

model

HF-LR	Header and Footer page areas overlap Left and Right page areas.
LR-HF	Left and Right page areas overlap Header and Footer page areas.

Description:

The PAGEAREA tag specifies tags and text that are formatted and output into the appropriate portion of the page (i.e., HEADER, FOOTER, LEFT or RIGHT). Any tags or styles may be embedded within a page area except DOCUMENT, METHOD, PAGEAREA, PAGEBOX, PAGEBR, or STYLE.

All completed pages will include the applicable page areas until those page areas are subsequently changed. In addition, due to late evaluation expressions, each page area is re-processed for each page that is output.

The page areas must be defined prior to any text being output for the applicable page(s) or the respective page areas will be queued (i.e., will not take effect) until the next page is formatted. If any page areas are changed within a block that does not fit on the current page and is designated with the "page-break-inside:avoid" style, that page area's changes are not performed until the block is again reprocessed on the subsequent page.

The "model" attribute of the PAGEAREA tag permits a document author to set the page area model that they wish to utilize. In addition, the page area model may be changed dynamically at any time so that more than one model can be used within a single document. If the "model" attribute only is specified in the PAGEAREA tag, then the page area model will be changed to the new value without invoking any further page area processing.

There are two types of page area models that can be selected within a document. The first type of page area model, called "HF-LR", allows the header and footer page areas to overlap the left and right page areas. The second type of page area model, called "LR-HF", allows the left and right page areas to overlap the header and footer page areas.

The following information applies to XHTML generation only:

If the page area scope is "HTML" for a type of "HEADER", it must be specified prior to any tags that generate document output (otherwise it will be ignored). In addition, a PAGEAREA tag with a scope of "HTML" is ignored for all other types of document generation.

A PAGEAREA tag with a scope of "HTML" outputs the contents of the header within the XHTML HEAD tag element. Any class, id, or style attributes are ignored. The content of this type of header are normally surrounded by an HTML tag pair with an embedded CDATA section as can be seen in the following example:

» Back to the Table of Contents. «

PAGEBOX

Examples:

An example of a PAGEBOX tag using the optional attribute "gutter" is as follows:

Attributes:

size	A mnemonic indicating the paper size.
height	If the "size" attribute of the PAGEBOX tag is selected as "Custom", then this attribute determines the height of the paper. The values "*" and "auto" indicates a variable height page. When a variable height page is specified, only one page results in the document, which is adjusted for the content. In addition, orientation, left, right, and footer page areas cannot be used with a variable height page.
width	If the "size" attribute of the PAGEBOX tag is selected as "Custom", then this attribute determines the width of the paper.
orientation	The orientation of the document on the paper.
top	The top margin for all pages of the document.
right	The right margin for all pages of the document.
bottom	The bottom margin for all pages of the document.
left	The left margin for all pages of the document.
gutter	When set to a value greater than zero, specifies an additional left margin for odd pages and an additional right margin for even pages. The gutter margin is applied inside of the normal page margins and outside of the page areas. When a gutter is applied to a document, odd/even page processing is invoked. Additionally, if the odd/even variations of any page areas are applied to a document, odd/even page processing is also invoked.
pagesegment	Determines when the PDF and PostScript generations are to be segmented into multiple output files. If "PageSegment" is set to a value of zero (default), PDF and PostScript generation results in a single file.
pageoffset	Determines where page numbering begins in a document. For example, if the "PageOffset" property was set to a value of 5, the first page number would be displayed as page 5.
media	Optional attribute that is only applicable when directly printing a document. This attribute must designate a valid printer that is either attached to the local machine or to the network.

Description:

The PAGEBOX tag sets the size of the paper, orientation, page margins, optional media output, etc. While conditional tags and <expression>s can be used to set the PAGEBOX tag and it's attribute values, the PAGEBOX tag must be specified prior to any actual document formatting.

If a PAGEBOX tag is not included in a document, letter size paper is selected in a portrait orientation. In addition, ½ inch margins are also set and no specific media device is selected.

When a PAGEBOX tag is included in a document, it must be located within the document entity so that the CreatePageBox Program method can quickly determine the actual page specifications. The CreatePageBox Program method determines the actual page specifications so that an application can notify a user of the size of the paper required prior to the document(s) being printed or generated.

» Back to the Table of Contents. «

PAGEBR

Examples:

Attributes:

height	Specifies an optional height that must remain on the page otherwise a logical page break will occur.
next	If the "next" attribute is set to "Auto" (default), the next page will immediately follow the current page. However, if the "next" attribute is set to "Odd", "OddBlank" or "Even", "EvenBlank", the next page will start on an odd or even page boundary respectively. The values "OddBlank" and "EvenBlank" will not format any page areas on blank pages (otherwise, page areas are formatted on blank pages).
page	Changes the document page number for display purposes.
style	Inline style properties.

Description:

The PAGEBR tag performs a "logical" page break which may or may not result in a physical page break. If the attribute "height" is used, the logical page break will only occur if the specified height is greater than the remaining height on the page. The remaining height within the current column on the page is calculated with respect to box elements, footers, etc.

When a percentage unit is used to specify a logical page break, the available height of the page is first calculated with respect to the page areas, margins, etc. Then, if the specified percentage is greater than the remaining height within the current column divided by the available height of the page (in terms of a percentage), a logical page break will occur.

When "logical" page breaks are encountered (either implicitly or explicitly by invoking the PAGEBR tag) within a TABLE element, a "checkpoint" is taken of the current location, styles, etc. and the next column of the TABLE element is processed if it exists. This procedure is repeated until all of the tags and text that can be formatted on the page have been processed (including all embedded TABLE elements or other elements).

Then, the active box elements are closed, the footer (if any) is formatted, and a physical page break is performed. On the next page, the header (if any) is taken into account, the box elements are reopened, and the "checkpoints" are resumed. The checkpoints themselves are dynamic and may span several pages prior to being closed.

The "next" attribute insures that after a physical page break occurs, the next page begins on either an odd or even page boundary. When a blank page is inserted to start the next page on an odd or even page boundary, the blank page is normally formatted with the current page areas prior to being output. However, if the new "OddBlank" or "EvenBlank" options are used with the "next" attribute, blank pages are formatted and output without the current page areas.

The "page" attribute of the PAGEBR tag may be utilized to dynamically change the "displayed" page number during document processing. This feature allows, for example, a document author to specify multiple sections within a single document, with each section beginning at page one. The "page" attribute may only be used with the PAGEBR tag at the outermost element level (i.e., the PAGEBR tag using the "page" attribute cannot be nested within another element).

The "style" attribute is used to specify style properties that are applied at the document level. By using the style property on this tag, document level styles can be changed over physical page break boundaries (i.e., all style changes are queued until a physical page break occurs.

» Back to the Table of Contents. «

QUERYDATA

Examples:

Attributes:

name	Specifies the absolute or relative name of a FinerEdge Publisher SQL file. Relative names are with respect to the document entity's directory path.

Description:

The QUERYDATA tag causes the contents of a FinerEdge Publisher SQL file to be processed in preparation for database information to be subsequently extracted. The individual unique query names that are defined within FinerEdge Publisher SQL files are referred to RECORDSET tags.

More than one FinerEdge Publisher SQL file may be specified via multiple QUERYDATA tags within a document entity or module entity. However, all connection and query element names must be unique so that they can be accurately referenced from RECORDSET tags (otherwise an error will be generated). If the same FinerEdge Publisher SQL file is specified more than once by a QUERYDATA tag, it will be ignored.

Please refer to the topic "Database Query Data Sources" within the chapter "Application Data Interface" for more information.

» Back to the Table of Contents. «

RECORDSET

<RECORDSET name = "<alphanumeric>"
   action = "Select|New|Delete|Record"
   [expr = "<expression>"]/>
   [fetch = "Now|Later"]

Examples:

Attributes:

name	The name of an application, query (ODBC), or XML data defined recordset.
action	Specifies the action that is to be performed, which can be the values "Select", "New", "Delete", or "Record".
expr	Specifies a valid FinerEdge Publisher <expression>.
fetch	Controls when the recordset's variables are populated after positioning to a record. The "fetch" attribute is only valid when the "action" attribute is "Record". After positioning to a record using the RECORDSET tag with the "action" attribute set to "Record", the external variables belonging to the recordset can be populated immediately ("Now") or when the first variable of the recordset is used ("Later"). The value of "Later" might be employed to reduce overhead when the variables of the recordset might not be accessed in certain cases.

Description:

Prior to referencing this tag, it is presumed that the individual has read and understood the chapter "Application Data Interface". The chapter "Application Data Interface" gives a detailed explanation of the interaction between an application, documents, and FinerEdge Publisher in creating and populating external variables. (The term "application" refers to the ODBC, XML data, and calling Application interfaces.)

The RECORDSET tag is the primary communication vehicle between an application and a FinerEdge Publisher document. Application data in FinerEdge Publisher is represented by external variables that may contain whole numbers, floating point values, strings of text, dates, and times.

External variables are organized into functional groups called recordsets. Each recordset is created and named by the application including all of the external variables that belong to that recordset. The "name" attribute must refer to the application defined name that identifies a particular recordset when using the RECORDSET tag.

Recordsets can be broken down into two categories: single-record recordsets and multiple-record recordsets (i.e., one-to-many relationships). In addition, one-to-many relationships are represented by a dynamic "drilldown" mechanism in FinerEdge Publisher that is superimposed upon the applicable recordsets.

Single-record recordsets and global external variables do not require the use of the RECORDSET tag. Once the external variables are created and populated by the application, they are intrinsically available to the document author simply by referring to their names.

However, a document author and the application administrator must mutually agree upon a handshake for passing information from the document to the application. This is accomplished by setting parameters through the "expr" attribute for a particular recordset. For an action "Select" or action "New", the "expr" attribute syntax is as follows:

<keyword>:<value> [; <keyword>:<value>]...

The <keyword> must be in <alphanumeric> format. The <value> can be any characters except a semicolon. Only the application administrator and document author know the meaning of the <keyword> and <value> pairs. Alternatively, parameters may be defined and passed from an outer recordsets to inner recordsets from within the FinerEdge Publisher query (ODBC) mechanism as described in the IDC manual. In this case, parameters are not needed from the document. Also, parameters are not applicable to XML data recordsets.

When the action "Select" is used to set parameters for a single-record recordset, the corresponding external variables of that recordset are also "cleared". This action, in turn, forces the application to re-fetch the data from possibly a different source.

Multiple-record recordsets require the use of the RECORDSET tag. First, a drilldown is created for a particular recordset by using the attribute action "New". The optional attribute "expr" may be used to provide information from the document to the application regarding the records requested in the drilldown (the "expr" attribute must be in the <keyword> and <value> pair format described above).

The application then creates one or more <keyword> and <value> pairs for each record that describes (to itself) how to efficiently fetch the data for each record. To the document, each record in a drilldown is indexed by a whole number starting from 1 and continuing until the last record requested. The FinerEdge Publisher functions "rsrecord" and "rsrecords" can be used with the currently active recordset drilldown to assist in looping through all of the records within a drilldown.

In order to fetch a particular record, the document specifies action "Record" for the particular recordset name (usually within a loop). The record number is given to the application by the document through the "expr" attribute. In this case, the result of the "expr" attribute must evaluate to be a <number>.

FinerEdge Publisher then accesses the <keyword> and <value> pairs for the requested record of the drilldown and passes them to the application. The application, in turn, fetches the physical data based upon the <keyword> and <value> pairs and populates the external variables of the recordset.

When a document has finished with a drilldown, it must discard it by using the action "Delete" for the particular recordset. This, in turn, returns the application to the previously active drilldown (if a previously active drilldown was active).

» Back to the Table of Contents. «

SELECT

Examples:

Attributes:

expr	Specifies a valid FinerEdge Publisher <expression>.

Description:

The SELECT tag is a conditional processing tag within a FinerEdge Publisher document (please refer to the FOR, IF, and WHILE for additional conditional processing tags). One or more CASE tags are embedded within a SELECT tag pair. When the SELECT tag is encountered, its <expression> is first evaluated. The result of the SELECT tag's expression is then compared to each CASE tag's <expression>s within the SELECT tag pair.

When a match is found, the tags and text following the CASE tag are processed until another CASE tag is encountered or the corresponding end SELECT tag is seen. Subsequent CASE tags within the SELECT tag will not be processed. If no matching CASE tag is encountered, then no tags and text within the SELECT tag pair will be processed.

SELECT and CASE tag <expression>s can evaluate to either a <number> (i.e., whole number) or a <string>. However, both the SELECT tag's <expression> and the embedded CASE tag's <expression>s must evaluate to be of the same type (i.e., <number> or <string>).

A special form of the CASE tag (i.e., "ELSE") may be used to provide default processing should no match occur. In this case, the <CASE expr = "ELSE"/> should be the last CASE tag within the SELECT tag pair.

» Back to the Table of Contents. «

SET

Examples:

Attributes:

var	A variable name to assign the value of the <expression>. An optional prefix consisting of a question mark ("?") character is used to specify a late evaluation expression. Please refer to the topic "Late evaluation expressions" within the chapter "FinerEdge Publisher Expressions" for more information on this subject.
expr	Specifies a valid FinerEdge Publisher <expression> to assign to the variable. An optional prefix consisting of a question mark ("?") character is used to specify a late evaluation expression. Please refer to the topic "Late evaluation expressions" within the chapter "FinerEdge Publisher Expressions" for more information on this subject.

Description:

The SET tag sets the variable specified by the attribute "var" to the result of the <expression> specified by the "expr" attribute. The variable indicated by the attribute "var" is always set to the resulting <expression>'s type (i.e., <number>, <float>, or <string>). Dates and time can be represented as either <number>s (internal form) or <string>s (external form) depending upon the resulting <expression>'s type.

The SET tag is used to declare local or global variables and to further modify the contents of local or global variables already declared. If the local or global variable or array element specified by the attribute "var" is not currently declared, it is initially declared to be the same type as the resulting <expression> specified by the attribute "expr".

» Back to the Table of Contents. «

SPAN

<SPAN [id = "<Class selector>"]
     [class = "<ID selector>"]
     [style = "<Style properties>"]>
   ...
</SPAN>

Examples:

Attributes:

id	A style "id" previously defined with the STYLE tag.
class	A style "class" previously defined with the STYLE tag.
style	Inline style properties.

Description:

The SPAN tag in FinerEdge Publisher is modeled after the SPAN tag in XHTML and is a general-purpose "inline" element. SPAN tags may be either categorized as "inline" SPANs or "box" SPANs. If the "width" style property was not specified or has a resulting value of 0, an inline SPAN is formatted. However, if the "width" style property is greater than 0, a box SPAN is formatted.

As previously stated, both types of SPANs (inline and box) are considered "inline" elements. Inline elements are formatted within the current line. Also, inline elements affect the formatting of the current line in terms of line-height, wraparound, etc.

Inline SPANs are typically used to change a style property. Like all content tag pairs, when the end tag is encountered, the current style again reverts back to the parent element's style properties. Changing the font-family, font-size, and font-weight are just some of the common uses of an inline SPAN.

Box SPANs are typically used to format a fixed size field on a form that may or may not have a visible border. Another use of box SPANs is to format a multi-line box within the current line (that also may or may not have a visible border). With a box SPAN, since there is no baseline, it is by default aligned to the bottom of the current line.

» Back to the Table of Contents. «

STYLE

<STYLE>
<style>
[<style>]...
</STYLE>

<style>:

<Class selector>|<ID selector> { <Style properties> }

Examples:

<STYLE>
   TABLE { width: 80% }
   .COLORBLUE { background-color: blue }
   DIV.SMALLBOX { border-style:solid; width:1in }
   #FONTFIXED { font-family:'Courier'; font-size:10pt }
</STYLE>

Attributes:

None.

Description:

The STYLE tag in FinerEdge Publisher is modeled after the STYLE tag in XHTML and allows one or more <Class selector> or <ID selector> styles to be defined for later use in the document. The styles either add to an internally known list of styles or change any existing styles that have the same names as in the internally known list of styles. The styles can be subsequently used many times throughout a document.

Since FinerEdge Publisher supports the concept of callable METHODs, a number of styles can be defined for use in many documents by creating a module entity with METHODS that contain one or more STYLE tags, each defining one or more styles within them. When the document is processed, a document can call the applicable METHODs containing the STYLE tags prior to using any of the declared styles.

Please refer to the chapter "Style Sheet Properties" for an explanation of <Class selector>, <ID selector>, and how to create styles.

» Back to the Table of Contents. «

TABLE

Examples:

Attributes:

id	A style "id" previously defined with the STYLE tag.
class	A style "class" previously defined with the STYLE tag.
style	Inline style properties.
cellstyle	Inline style properties applied to the cells of the table whenever a TD element is seen. A special case arises when the border-style property is set to the single value of "solid" (i.e., as applicable to all four sides). In this case the borders of adjacent TD cells will be displayed only once.
cols	The number of columns in the TABLE and their respective dimensions. The formatting columns "D" and "S" cannot be the first or last column of a TABLE. (In this case, the standard border and padding styles should be employed.) When a "D" (Divider) is specified, the column will be skipped when performing an explicit or implicit COLBR action. In addition, a centered vertical divider line is drawn from the top border to the bottom border for that column. The line is drawn with the same width and color that is currently set for the right border of the table. When an "S" (skip) is specified, the column will be skipped when performing an explicit or implicit COLBR action. No additional drawing will take place within the column with the exception of filling in the skipped area with the currently set background color. When a "V" (variable) is specified, the column is explicitly designated as being variable. When a column is variable, only the initial steps are performed as discussed in the paragraph regarding a "variable width column" below. When an "A" (adjust) is specified, the content of each column is measured to determine it's maximum line width. The maximum line widths for all variable width columns are then added together to determine the total maximum line width. Next, the maximum line width for each column is divided by the total maximum line width resulting in a fraction of the total. Finally, each fraction is then applied to the remaining width of the TABLE element thus yielding the adjusted width for each variable column. When either a "L" (left), "C" (center), or "R" (right) is specified, the content of each column is measured to determine it's maximum line width and recorded. For these types of columns, when table model includes an inner DIV element (i.e., TABLE, DIV, DIV), the recorded value is applied to the inner element's width. Inner elements are additionally aligned to the "L" (left), "C" (center), "R" (right) of the parent element. An asterisk ("*") for any TABLE column indicates a variable width column. FinerEdge Publisher adds the widths for all known TABLE columns first and then subtracts that sum from the width of the parent element. The result is then evenly distributed over the TABLE's variable width columns. Additionally, when an individual column is formatted with an "A", "L", "C", or "R" option, a number of additional steps are performed as discussed in the respective option above.
type	Most of the time, a table will operates within the constraints of FinerEdge Publisher's TR/TD table model (i.e., where cells are represented as individual TD elements). In this case, the synchronization of variable heights rows are automatically handled by FinerEdge Publisher. If the TABLE's "type" attribute has a value of "Adjust", "Left", "Center", or "Right", it will be applied as a default to any columns that have not been specified with an explicit formatting option. Additionally, If the TABLE's "type" attribute has a value of "Left", "Center", or "Right", and the TR/TD table model is used, an inner DIV is automatically added with a text-align style of "Right" for the "Left" and "Center" column options, and a text-align style of "Left" for the "Right" column option. If the TABLE's "type" attribute has a value of "Newspaper", then newspaper style columns are formatted in the TABLE. With newspaper style columns, FinerEdge Publisher's table model is not used. The elements in each column are not related and the formatting is correspondingly less restrictive. When the TABLE's "type" attribute has a value of "AutoCOLBR", then automatic column breaks (i.e., COLBR) are performed on the columns of the TABLE. While the AutoCOLBR option exhibits similar behavior to the COLBR tag with the height attribute, the COLBR with a height attribute allows a conditional COLBR to be performed on a group of lines instead of just the current line being formatted. Conversely, the AutoCOLBR option operates in the "background" and requires no knowledge of a specific height to function properly.

Description:

The TABLE tag is a general-purpose multi-column block-level element that is modeled after the XHTML TABLE element. TABLE tags may be nested within other TABLE or DIV tags. The dimensions of a TABLE's columns are always with respect to their parent element's width or column width (in the case of parent TABLE elements). TABLE tags may not be nested within SPAN tags.

The columns of a TABLE may be arbitrarily long without regard to physical page breaks. Page breaks are automatically handled by the FinerEdge Publisher dynamic checkpoint mechanism. Please refer to the PAGEBR tag for an explanation of what occurs when an implicit or explicit page break is encountered.

TABLE elements may employ either an XHTML TR/TD model or the flexible DIV/COLBR model. The TR/TD model is most often used. However when a table type of "Newspaper" is specified, COLBR's should be used without any inner DIV element (otherwise, the table's row heights will be visually synchronized). No COLBRs should be used with a table type of "AutoCOLBR" as COLBRs are inserted automatically between table columns with respect to each page formatted.

» Back to the Table of Contents. «

<TD [id = "<Class selector>"]
     [class = "<ID selector>"]
     [style = "<Style properties>"]>
   ...
</TD>

Examples:

Attributes:

id	A style "id" previously defined with the STYLE tag.
class	A style "class" previously defined with the STYLE tag.
style	Inline style properties.

Description:

The TD tag in FinerEdge Publisher is modeled after the TD tag in XHTML and is a block-level element that must be embedded within a TABLE element. The TD element represents a single cell in a table and is the equivalent of a DIV tag pair followed by a COLBR tag. As such, TR elements are not strictly required (i.e., following the last column of a row, a new row is automatically started at the first column.

The TD tag inherits any inline style properties that are defined by the cellstyle attribute of the TABLE element. Furthermore, the TD tag also inherits any inline style properties that are defined by an enclosing TR element. In addition, if the TD tag does not define an id or class attribute, any id or class attributes that are defined by a TR element are also inherited.

» Back to the Table of Contents. «

<TR [id = "<Class selector>"]
     [class = "<ID selector>"]
     [style = "<Style properties>"]
     [header = "Yes|No"]>
   ...
</TR>

Examples:

Attributes:

id	A style "id" previously defined with the STYLE tag.
class	A style "class" previously defined with the STYLE tag.
style	Inline style properties.
header	"Yes" designates this row as a table header.

Description:

The TR tag in FinerEdge Publisher is modeled after the TR tag in XHTML and is a block-level element that must be embedded within a TABLE element. The TR element represents a single row in a table. One or more TD elements are normally defined within a TR tag to represent the cells of a row. If the number of TD elements within a TAG tag is less than the number of columns, as defined by the "cols" attribute of the enclosing TABLE tag, empty TD elements are automatically generated with appropriate styles for the table and row.

All TD elements within an enclosing TR tag inherit any inline style properties that are defined by the cellstyle attribute of the TABLE element. Furthermore, the TD tag also inherits any inline style properties that are defined by the TR element. In addition, if the TD tag does not define an id or class attribute, any id or class attributes defined by the TR element are also inherited.

» Back to the Table of Contents. «

USE

<USE name = "<alphanumeric>"
[params = "<parameter> [, <parameter>]..."]/>

<parameter>:

<number>|<float>|<string>|*

Examples:

Attributes:

name	The name of the method to use.
params	The parameters passed to the method.

Description:

A USE tag calls a corresponding METHOD that has the same "name" attribute as the USE tag itself (please refer to the METHOD tag for an explanation of declaring and using METHODs). The called METHOD may or may not be declared within the same entity as the USE tag.

USE tags may or may not have parameters as specified by the "params" attributes. An asterisk ("*") for a "By Value" parameter indicates that the initialization value of the method's parameter should be used.

By default, parameters are passed from the USE tag to the METHOD "By Value" (i.e., copies of the values from the USE tag's parameters are created so that any modification to the METHODs parameters will not affect the caller). When a particular METHOD tag's parameter is preceded by the optional keyword "ByRef", it is declared "By Reference" (i.e., when the METHOD is exited, the updated value of the parameter variable is copied back to the corresponding USE tag's variable parameter).

If a "ByRef" parameter variable changes it's type (via the "SET" tag) within a METHOD, that change is reflected back to the corresponding USE tag's parameter variable. Any parameters that are declared as "ByRef" by the METHOD must be passed as actual variables (i.e., not <expression>s) by the USE tag. In addition, the same number of parameters must exist in the USE tag as exist in the called METHOD.

» Back to the Table of Contents. «

VAR

<VAR [id = "<Class selector>"]
   [class = "<ID selector>"]
   [style = "<Style properties>"]
   expr = "[?]<expression>"
   [char = "<string>"]
   [length = "<number>"]
   [bz = "Yes|No"]
   [option = "xml|tag"]/>

Examples:

Attributes:

id	A style "id" previously defined with the STYLE tag.
class	A style "class" previously defined with the STYLE tag.
style	Inline style properties.
expr	Specifies a valid FinerEdge Publisher <expression> to be formatted into the document. An optional prefix consisting of a question mark ("?") character is used to specify a late evaluation expression. Please refer to the topic "Late evaluation expressions" within the chapter "FinerEdge Publisher Expressions" for more information on this subject.
char	The default character that is used when the resulting expression is an empty string (i.e., "").
length	The default length that is used when the resulting expression is an empty string (i.e., "").
bz	"Yes" indicates that a zero value for the <expression> results in a empty string. "No" (the default) indicates that a zero value is formatted "as is".
option	When the option is "xml", all "<", ">", and "&" characters are translated to "<", ">", and "&" xml entities sequences respectively. Furthermore, any carriage return, linefeed, or carriage return/linefeed pairs are translated to "<BR/>" (i.e., for subsequent use in another VAR tag using the attribute option value of "tag"). When the option is "tag", the value of the resulting expression is assumed to contain embedded FPML tags. In this case, the value of the expression contains additional content elements and late evaluation expressions. These are, in turn, processed during document generation.

Description:

The VAR tag in FinerEdge Publisher is a special purpose "inline" element. As an inline element, the VAR tag can refer to a <Class selector>, <ID selector>, and specify inline style properties specific to the scope of the VAR tag itself.

The VAR tag takes the result of an <expression> specified by the attribute "expr" and formats it into the document's output. The result of the <expression> may be either a <number>, <float>, or <string>. Typically, the <expression> of a VAR tag uses one or more local, global, or external variables within it. Any carriage return, linefeed, or carriage return/linefeed pairs in a <string> are interpreted as a <BR/> action unless the attribute option specifies a value of "xml" (see above explanation).

When the resulting expression of a VAR tag is an empty string (i.e., ""), the default character for a length value is substituted in the output. This behavior can be controlled both at the document level (i.e., a default for the entire document) and within the individual VAR tags themselves.

If default character and length values are supplied with a VAR tag, these values will override the document level for the respective values. Also, if default values are not specified either at the document level or within a specific VAR tag, a default character of "_" with a length of 10 is used instead.

A number of special features are also employed with the VAR tag. If the default length evaluates to a value of zero, no default characters will be substituted in the output. In addition, if the default character is an underscore (i.e., "_"), the "text-decoration:underline" style attribute will be employed along with absolute spaces to allow normal wraparound and justification to occur. Finally, if the default character is a space (i.e., " "), absolute spaces are used to insure the intended output along with normal wraparound.

» Back to the Table of Contents. «

WHILE

Examples:

Attributes:

expr	Specifies a valid FinerEdge Publisher <expression>.

Description:

The WHILE tag is a conditional processing loop tag within a FinerEdge Publisher document (please refer to the FOR, IF, and SELECT for additional conditional processing tags). WHILE tags may be nested within other WHILE tags.

The <expression> is evaluated each time through the loop. If the result of the <expression> is true, all tags and text following the WHILE tag and prior to the end WHILE tag are processed. When the end WHILE tag is seen, processing continues at the beginning of the loop where the <expression> is again re-evaluated.

If the result of the <expression> is false, the loop is terminated and processing continues following the end WHILE tag.

» Back to the Table of Contents. «

XMLDATA

Examples:

Attributes:

name	Specifies the absolute or relative name of an XML file. Relative names are with respect to the document entity's directory path.

Description:

The XMLDATA tag opens an XML data file and establishes the XML hierarchy for that data file in preparation for processing the data. If a subsequent XMLDATA tag is seen, the first XML data file is automatically closed prior processing the second XML data file.

Please refer to the topic "XML Data Files" within the chapter "Application Data Interface" for more information.

» Back to the Table of Contents. «

Chapter 4 - Styles Sheet Properties

Overview

FinerEdge Publisher adheres to the Cascading Style Sheet (i.e., CSS) specification for it's built-in style properties. CSS is a mature specification that is stable and not subject to substantial change of existing properties.

A list of terms used with style properties and their respective descriptions is as follows:

Normal flow

The page layout proceeds in a left-to-right, top-to-bottom manner.

Static positioning

Normal flow without involving any subsequent adjustment of the elements.

Relative positioning

Normal flow with the affected elements being offset relative to their static position.

Absolute positioning

Affected elements that are not part of normal flow and are offset from their parent element's position. Since absolute positioning is not part of normal flow, absolute positioned elements that exceed the current page size will be ignored.

Block-level elements

Those elements that are outside the formatting of the current line (i.e., those elements that would begin a new line when they are encountered). Examples of block-level elements are DIV, PAGEAREA, TABLE, TD, and TR.

Inline elements

Those elements that affect the formatting within the current line. Inline elements include the tags SPAN and VAR.

Inheritance

Elements can be nested within each other with respect to nesting rules (i.e., block-level elements cannot be nested within inline elements). Certain style properties will inherit their initial values from the style properties of the parent element. Those properties that inherit values from the parent element are marked as "inherited" in the style property definitions presented in this chapter.

In addition, elements and style properties can have a certain intrinsic size, especially in terms of width (see "box" properties). Style properties such as width, height, margin, border, and padding affect the resulting size that is available to a nested child element. Also, child elements can also adjust a parent element's width and height if a corresponding width or height style property is not explicitly specified or specified as "auto" (i.e., automatic).

Cascading

Cascading refers to the order in which styles are applied to an element. Please note that cascading is always performed in the following order, and always follows inheritance:

Contextual selectors
Class selectors
ID selectors
Inline styles

Contextual selector

FinerEdge Publisher supports single-level contextual selectors. For example, a default style may be applied to all SPANs or all DIVs. TD elements equate to DIV elements for contextual selectors. When cascading, specific style properties may be subsequently overridden by applying a class selector, ID selector, and/or inline style.

Any number of class selectors may be specified and used in a document. When defined within the context of the STYLE tag, a class selector consists of an optional tag name followed by a period character that is, in turn, followed user-defined key word (e.g., "SPAN.myclass", ".myclass", etc.). When referenced from within the context of a particular tag's "class" attribute, a class selector specifies only the user-defined key word (e.g., "myclass"). If the optional tag name is present, the search is constrained to that particular tag name, otherwise the search is irrespective of the tag's name. TD and TR elements equate to DIV elements for class selectors. Please refer to the STYLE tag for additional information on class selectors. As an option, an <expression> may be used anywhere that a <Class selector> is specified in the attribute of a tag.

Any number of ID selectors may be specified and used in a document. When defined within the context of the STYLE tag, an ID selector consists of the "#" character followed by a user-defined key word (e.g., "#myid"). When referenced from within the context of a particular tag's "id" attribute, an ID selector specifies only the user-defined key word (e.g., "myid"). Please refer to the STYLE tag for additional information on ID selectors. As an option, an <expression> may be used anywhere that an <ID selector> is specified in the attribute of a tag.

Inline styles can be used with the following tags: DIV, DOCUMENT, PAGEAREA, SPAN, TABLE, TD, TR, and VAR. Inline style specifications are meant for single use or when an individual needs to override preceding style properties as specified through inheritance, context, class, and ID selectors.

Length units can be either relative to the current font (i.e., em and ex) or an absolute measurement (i.e., in, cm, mm, pt, and pc) as shown in the following table:

em	The average height of the element's font.
ex	The height of the letter "x" in the element's font.
in	Inches (1in = 2.54 cm).
cm	Centimeters.
mm	Millimeters.
pt	Points (1pt = 1/72 in).
pc	Picas (1pc = 1/6 in).
<empty>	Twips (1 twip = 1/1440 in).

Percentage units are extremely useful when setting a child element's dimensions relative to the dimensions of the parent element. For example, if a two-column table was needed where each column should be half the width of the table itself, we could simply indicate 50% and 50% for the two columns without knowing the actual dimensions of the TABLE element.

FinerEdge Publisher supports a large list of color mnemonics. The applicable IDE ComboBox fields are always pre-filled with these color mnemonics.

An RGB (Red, Green, Blue) color is specified using the syntax "#rrggbb" where "rr" is the red component represented as two hex digits, "gg" is the green component represented as two hex digits, and "bb" is the blue component represented as two hex digits.

A CMYK (Cyan, Magenta, Yellow, Black) color is specified using the syntax "#ccmmyykk" where "cc" is the cyan component represented as two hex digits, "mm" is the magenta component represented as two hex digits, "yy" is the yellow component represented as two hex digits, and "kk" is the black component represented as two hex digits.

When the color mnemonic "transparent" is used with the "background-color" property of an element, any background image of the parent element to is allowed to "show through" the current element's box. As such, the "transparent" color mnemonic allows text to be precisely placed on top of an image by utilizing embedded elements within the parent element that specifies the background image.

Box Model

Whenever a block level element is used or a SPAN tag is specified with a "width" greater than 0, a box is constructed that may have margins, padding, and visible borders. While constructing a box, FinerEdge Publisher adheres to the W3C box model. As such, the relationship of width and height to margins, padding, and borders is shown in the following diagram (note that the box width and height properties do not include margins, borders, or padding):

» Back to the Table of Contents. «

Style properties

Examples:

font-family: 'Helvetica'; font-size: 10pt

width: 1.5in; border-style: solid; border: 1pt

Description:

The style properties are divided into 5 groups - font, color, text, box, and border - that correspond to the 5 panels of the IDE's style editor. However, because this manual is organized in a reference format, the style properties are presented in a strict alphabetical order herein.

The question mark ("?") character prefix, prior to any style properties, causes the style properties to be re-evaluated after each page break. The question mark prefix is only effective when used with the "style" attribute of the DIV, SPAN, TABLE, TD, TR, and VAR tags. The question mark prefix is considered a form of late evaluation and takes precedence over any other form of late evaluation.

In contrast, a question mark ("?") character prior to an <expression> is used to specify a late evaluation expression. Please refer to the topic "Late evaluation expressions" within the chapter "FinerEdge Publisher Expressions" for more information on this subject.

» Back to the Table of Contents. «

Document references

FinerEdge Publisher document references allow information to be accumulated into a reference table during document processing and then be subsequently used during document rendering. As such, references can be used from anywhere in the document both before and after the definition of the references themselves.

References are defined by assigning values to the style properties "ref-search" and "ref-text" for an element. To create a reference, the "ref-search" property must designate a unique value. The "ref-text" property may also designate an optional value.

All references are automatically assigned an "index", starting from 1 in the order of appearance, in order to allow both absolute and relative referencing. The current reference location in the reference table is determined by the most recent reference search performed.

The value assigned to the "ref-search" property is used with the reference functions to search for a specific reference by performing regular expression pattern matching. Both the contents of the "ref-search" and "ref-text" properties can be used in a document by employing the reference functions as discussed in the chapter "Expressions and Functions".

» Back to the Table of Contents. «

background-color

inherited - default: white

background-color: <color unit>|([?]<expression>)

Examples:

background-color: yellow

Description:

Sets the background color for the current element. The box padding (if any) will be filled in with the background color of the current element. The border colors are independently specified via the "border-color" style. The box margin (if any) will be filled in with the background color of the parent element.

When the background color is set to "transparent" for an element, the image and background color of the parent element is allowed to "show through" the child element.

» Back to the Table of Contents. «

background-image

default: none

Background-image: <name-1> [ , <name-2> ]

<name-1> and <name-2>:

'<catalog name>'|'<external name>'|([?]<expression>)

<catalog name>:

Specifies an "image" <catalog name> within the currently active catalog. Each <catalog name> relates to an absolute file name, relative file name, or url. Relative names are with respect to the document entity's directory path.

Images stored within database BLOB fields are also supported by FinerEdge Publisher. For more information, see "Image Formats" in this topic.

<external name>:

Specifies an absolute file name, relative file name, or url. Relative names are with respect to the document entity's directory path.

Examples:

Background-image: 'company_logo'
Background-image: 'C:\images\logo.tif'
Background-image: 'http://www.mysite.com/logo.tif'
Background-image: '../images/logo.tif'

Description:

Places a background image inside an element's border but exclusive of any text padding specified.

PDF generation -

Optional catalog substitution is performed for <name-1> and subsequently converted into a DSC file name and output as the "/F" parameter. For OPI, if <name-2> is supplied, optional catalog substitution is performed and then output as the "/MainImage" parameter. Otherwise, if <name-2> is not supplied, the path prefix is eliminated from <name-1> and the resulting name is output as the "/MainImage" parameter.

PostScript generation -

Optional catalog substitution is performed for <name-1> and subsequently converted into a DSC file name and output as the "%%ImageFileName" DSC comment. For OPI, if <name-2> is supplied, optional catalog substitution is performed and then output as the "%%MainImage" DSC comment. Otherwise, if <name-2> is not supplied, the path prefix is eliminated from <name-1> and the resulting name is output as the "%%MainImage" DSC comment.

XPS generation -

Optional catalog substitution is performed for <name-1> and the image is subsequently embedded in the resulting XPS file. The <name-2> is not used with XPS generation as there is no OPI support in XPS.

RTF generation -

Optional catalog substitution is performed for <name-1> and the image is subsequently embedded in the resulting RTF file. The <name-2> is not used with RTF generation as there is no OPI support in RTF.

HTML generation -

If <name-2> is supplied, catalog substitution is optionally performed and the result is output. Otherwise, optional catalog substitution is performed on <name-1>. If a file name is given (as opposed to a url), the result is subsequently converted into a valid file url.

Image masks -

FinerEdge Publisher supports masks for image types that have transparent or alpha channel capabilities. Images that have transparent capabilities (i.e., GIF and PNG) define a single color to designate areas of transparency. Images that have an alpha channel (i.e., PNG and TIFF) define an additional byte of information for each pixel. Each byte of additional information specifies the level of opaqueness from 0 to 255 (where 0 is fully transparent and 255 is fully opaque).

Regardless of the image format using transparency or alpha channel, an image mask of the transparent areas is generated and stored with the image. Since the image mask is composed of bits (where 0 is transparent and 1 is opaque), alpha channel values of 1-127 are interpreted as transparent while alpha channel values of 128-255 are interpreted as opaque.

The image mask is compatible with the concept of an image mask in all generated forms of PDF, PostScript, and XPS and can also be directly applied to Windows viewing and printing.

Open Prepress Interface (OPI) -

FinerEdge Publisher supports the Open Prepress Interface (OPI), version 2.0 standard, for both PDF and PostScript output. OPI is applicable to all currently supported versions of PDF and PostScript generation.

The Open Prepress Interface defines conventions which allow FinerEdge Publisher to use low and medium resolution images in place of the original high-resolution images for document layout and proofing. The low and medium resolution images are automatically created "on-the-fly" from the original high-resolution images by FinerEdge Publisher. When the final film or plates are created by the prepress system, the original high-resolution images are substituted for the low and medium resolution images.

Image formats:

BMP images -

Monochrome, 4-bit and 8-bit palettized, and 24-bit True Color RGB colorspace images.

GIF images -

8-bit palettized RGB colorspace images.

JPEG images -

True Color RGB and CMYK colorspace images. (Note: CMYK colors are preserved by FinerEdge Publisher for both PDF and PostScript generations, and automatically converted to RGB colors for XPS, direct viewing, and printing.)

PNG images -

8-bit palettized and 24-bit True Color RGB colorspace images.

TIFF images -

Monochrome, 4-bit and 8-bit palettized, and 24-bit True Color RGB and CMYK colorspace images. (Note: CMYK colors are preserved by FinerEdge Publisher for both PDF and PostScript generations, and converted to RGB colors for XPS, direct viewing, and printing.)

Database images -

FinerEdge Publisher supports the use of images stored within database BLOB fields in any of the above image formats. In addition, BMP images embedded within OLE Objects (e.g., from MSAccess databases) are also supported by FinerEdge Publisher. The images are extracted as needed and cached on disk within temporary files for efficiency (i.e., duplicate images are not repeatedly extracted). (All temporary image files created are autommatically removed by FinerEdge Publisher when document processing has been completed.)

The database variable name for the image BLOB field contains the absolute file name of the image's temporary disk file, which can then be subsequently used by this style. For more information, please refer to the topic "Database Definitions and Query Editor" within the FinerEdge Publisher IDE manual.

» Back to the Table of Contents. «

background-position

default: top left

Examples:

background-position: center center

Description:

Determines how an image is positioned within the current element. The first option specifies the image's vertical alignment while the second option specifies the image's horizontal alignment. Any background-repeat specification will always follow after the positioning of the image within the current element.

» Back to the Table of Contents. «

background-repeat

default: repeat

background-repeat: repeat|repeat-x|
repeat-y|no-repeat|([?]<expression>)

Examples:

background-repeat: no-repeat

Description:

When a background-image is specified, this property determines how the image is to be repeated. The option "no-repeat" indicates that the image is not to be repeated. The option "repeat" indicates that the image is to be repeated in both the x (left-to-right) and y (top-to-bottom) directions. The options "repeat-x" and "repeat-y" repeat the image in just the x and y directions respectively.

» Back to the Table of Contents. «

border-color

default: black

border-color: <border-color> [<border-color>
[<border-color> [<border-color>]]]

<border-color>:

<color unit>|([?]<expression>)

Examples:

border-color: green

Description:

Designates a border color to the border that is around the element and inbetween the margin and padding (please refer to the box diagram at the beginning of this chapter). Borders are not applied unless the "border-style" is set to a value other than "none" for the respective side(s). From 1 to 4 values may be given for a border color setting and are interpreted as follows:

1 value	Sets the border color for all 4 sides.
2 values	Sets the border color for the (top, bottom) and (right, left) sides respectively.
3 values	Sets the border color for the (top) and (right, left) and (bottom) sides respectively.
4 values	Sets the border color for the (top) and (right) and (bottom) and (left) sides respectively.

» Back to the Table of Contents. «

border-style

default: none

Examples:

border-style: solid

Description:

Applies a border style to the border that is around the element and inbetween the margin and padding (please refer to the box diagram at the beginning of this chapter). The "border-style" property effectively makes the border(s) visible and factored into the box layout. From 1 to 4 values may be given for a border style setting and are interpreted as follows:

1 value	Sets the border style for all 4 sides.
2 values	Sets the border style for the (top, bottom) and (right, left) sides respectively.
3 values	Sets the border style for the (top) and (right, left) and (bottom) sides respectively.
4 values	Sets the border style for the (top) and (right) and (bottom) and (left) sides respectively.

The possible options and their respective descriptions for broder-style are as follows:

none	No border.
solid	Single solid border.
dotted	Border with dots.
dashed	Border with dashes.
double	Double solid border.
groove	Grooved 3-D border.
ridge	Ridge 3-D border.
inset	Inset 3-D border.
outset	Outset 3-D border.

» Back to the Table of Contents. «

border-width

default: 1pt

border-width: <border> [<border> [<border> [<border>]]]

<border>:

<number constant>|([?]<expression>) <length unit>|<percentage unit>

Examples:

border-width: 3pt

Description:

Designates a border around the element and inbetween the margin and padding (please refer to the box diagram at the beginning of this chapter). Borders are not applied unless the "border-style" is set to a value other than "none" for the respective side(s). From 1 to 4 values may be given for a border setting and are interpreted as follows:

1 value	Sets the border-width for all 4 sides.
2 values	Sets the border-width for the (top, bottom) and (right, left) sides respectively.
3 values	Sets the border-width for the (top) and (right, left) and (bottom) sides respectively.
4 values	Sets the border-width for the (top) and (right) and (bottom) and (left) sides respectively.

» Back to the Table of Contents. «

bottom

default: 0

bottom: auto|<number constant>|([?]<expression>)
<length unit>|<percentage unit>

Examples:

bottom: 2cm

Description:

This style property is only applicable if the "position" style property is set to either "relative" or "absolute". When the "position" style property is set to "relative", this property determines the element's additional vertical positioning relative to its normal flow "static" position (with a positive value indicating up and a negative value indicating down).

When the "position" style property is set to "absolute", this property determines the element's vertical positioning with respect to its parent element's bottom position. In all cases, when the properties "top" and "bottom" are simultaneously set, the "top" property takes precedence.

» Back to the Table of Contents. «

clear

default: none

clear: none|left|right|both|(<expression>)

Examples:

clear: both

Description:

Utilized with a block-level element in order to position it vertically and immediately following an applicable floating element. When the "clear" is set to "left", positioning occurs if the left edge of the block-level element is adjacent to an applicable floating element. When the "clear" is set to "right", positioning occurs if the right edge of the block-level element is adjacent to an applicable floating element. When the "clear" is set to "both", positioning occurs if either the left or right edge of the block-level element is adjacent to an applicable floating element.

» Back to the Table of Contents. «

color

inherited - default: black

color: <color unit>|([?]<expression>)

Examples:

color: blue

Description:

Sets the foreground color for both the stroke and fill of the text.

» Back to the Table of Contents. «

decoration-align

inherited - default: none

decoration-align: left|right|center|justify|([?]<expression>)

Examples:

decoration-align: justify

Description:

This style property only has an effect if the "text-decoration" property is set to an option other than "none". In this case, "decoration-align" will cause the line to be drawn to the indicated left, right, or both left and right edges of the element (with respect to padding, etc.). This style property is most often used with a "SPAN" tag when defining a field on a form where the text may be less than the width of the element.

left	Align to left edge of element.
right	Align to right edge of element.
center	No alignment to edge of element.
justify	Align to both left and right edge of element.

» Back to the Table of Contents. «

float

default: none

float: none|left|right|(<expression>)

Examples:

float: right

Description:

Utilized with a block-level element in order to float it either to the "left" or "right" within a parent block-level element. If an element is floated to the "left" of a parent element, subsequent text and elements are positioned (wrap-around) to the right of the floated element. If an element is floated to the "right" of a parent element, subsequent text and elements are positioned (wrap-around) to the left of the floated element. Float is reset to "none" when "position" is set to "absolute" for an element.

» Back to the Table of Contents. «

font-family

inherited - default: Times

font-family: <family-name> [, <family-name>]...

<family-name>:

'<internal name>'|'<catalog name>'|([?]<expression>)

<internal name>:

The following font names are known internally by FinerEdge Publisher and will translate correctly to all output formats (i.e., Viewed, Printed, PDF, PostScript, XPS, RTF, XHTML, etc.). The column "Windows" applies to the Viewer, Printer, XPS, RTF formats, and XHTML whereas the columns Normal, Bold, Italic, and Bold-Italic apply to the PDF and PostScript formats.

Name	Windows	Normal	Bold	Italic	Bold-Italic
Courier	Courier New	Courier	Courier-Bold	Courier-Oblique	Courier-BoldOblique
Helvetica	Arial	Helvetica	Helvetica-Bold	Helvetica-Oblique	Helvetica-BoldOblique
Symbol	Symbol	Symbol	Symbol	Symbol	Symbol
Times	Times New Roman	Times-Roman	Times-Bold	Times-Italic	Times-BoldItalic
ZapfDingbats	ZapfDingbats	ZapfDingbats	ZapfDingbats	ZapfDingbats	ZapfDingbats

<catalog name>:

Specifies a "font" <catalog name> within the currently active catalog. Each <catalog name> is composed of the 5 components that were presented along with the <internal name> shown above (i.e., Windows, Normal, Bold, Italic, and Bold-Italic). It's highly recommended that the FinerEdge Publisher IDE catalog editor be used to construct font entities.

Examples:

font-family: 'Times'

Description:

Set the element's font to one of the names specified in the font-family list. Each name must be either an internally known name or a catalog name. If the first name in the list is not known, the subsequent names are selected in the order of appearance until a known font name is encountered.

» Back to the Table of Contents. «

font-size

inherited - default: 10pt

font-size: <number constant>|([?]<expression>) <length unit>

Examples:

font-size: 10pt

Description:

Set the size of the font for the selected font-family. The length unit "pt" (i.e., points) is most often used to select the size of the font (however, any length unit may be used to select the font size). If the line-height is less than 120% of the font size, the line-height is automatically adjusted up to be 120% of the font size.

» Back to the Table of Contents. «

font-style

inherited - default: normal

font-style: normal|italic|([?]<expression>)

Examples:

font-style: italic

Description:

Set a normal or italic face for the selected font-family. The option "italic" implies "oblique" if the font-family has an oblique face.

» Back to the Table of Contents. «

font-weight

inherited - default: normal

font-weight: normal|bold|([?]<expression>)

Examples:

font-weight: bold

Description:

Set the weight of the font face for the selected font-family. The options "normal" and "bold" are supported by most fonts except Symbol and ZapfDingbats.

» Back to the Table of Contents. «

height

default: 0

height: auto|<number constant>|([?]<expression>)
<length unit>|<percentage unit>

Examples:

height: 3in

Description:

Designates the height of a box element, which does not include any margins, borders, or padding. When an implicit or explicit page break is encountered, the box element is closed with respect to any margins, borders, or padding that have been specified. When additional columns exist (i.e., for table elements), they are subsequently processed prior to performing a physical page break (to include any embedded or nested columns). Then on the new page, all previously active box elements are re-opened with respect to any margins, borders, or padding.

When the content of a box element exceeds it's height and the style property "overflow" is set to "visible", the height of the box is automatically increased to accommodate the additional information. However, if the style property "overflow" is set to "hidden" and the box height is 0, the text is truncated prior to it wrapping to the second line (i.e., one line of text is output).

In contrast, if the style property "overflow" is set to "hidden" and the box height has been explicitly set, the box height will not be automatically increased. Under these conditions, when the content of the box exceeds its height, the content is truncated following the last line of text that can be output within the dimensions of the box element.

An element's width and/or height can be automatically set by the width and/or height of an image. That is, if a "background-image" is specified with an element such as a DIV, SPAN, or TABLE, the element's width and/or height can be automatically determined by the interpreted size of the image itself. When a "background-image" is specified with an element and the element's "height" property is either not specified, a value of 0, or a value of "auto", the height of the element will be determined from the interpreted height of the image.

» Back to the Table of Contents. «

left

default: 0

left: auto|<number constant>|([?]<expression>)
<length unit>|<percentage unit>

Examples:

left: 2cm

Description:

This style property is only applicable if the "position" style property is set to either "relative" or "absolute". When the "position" style property is set to "relative", this property determines the element's additional horizontal positioning relative to its normal flow "static" position (with a positive value indicating to the right and a negative value indicating to the left).

When the "position" style property is set to "absolute", this property determines the element's horizontal positioning with respect to its parent element's left position. In all cases, when the properties "left" and "right" are simultaneously set, the "left" property takes precedence.

» Back to the Table of Contents. «

line-height

inherited - default: 120%

line-height: <number constant>|([?]<expression>)
<length unit>|<percentage unit>

Examples:

line-height: 120%

Description:

Designates the distance between the baselines of two adjacent lines of text. The line-height is most often set to be 120% of the font-size (the default). However, if the line-height has been explicitly set and is less than 100% of the font size, the line-height is automatically adjusted up to be 100% of the font size.

If the font-size is changed within a line of text, the line-height will be a minimum of 100% (and will usually default to 120%) of the largest font-size unless it has been explicitly set to another value.

» Back to the Table of Contents. «

margin

default: 0

margin: <margin> [<margin> [<margin> [<margin>]]]

<margin>:

<number constant>|([?]<expression>) <length unit>|<percentage unit>

Examples:

margin: 1pt

Description:

Apply a margin around the element and outside of the border and/or padding (please refer to the box diagram at the beginning of this chapter). The margin area will always be filled with the background-color of the parent element. From 1 to 4 values may be given for a margin setting and are interpreted as follows:

1 value	Sets the margin for all 4 sides.
2 values	Sets the margin for the (top, bottom) and (right, left) sides respectively.
3 values	Sets the margin for the (top) and (right, left) and (bottom) sides respectively.
4 values	Sets the margin for the (top) and (right) and (bottom) and (left) sides respectively.

» Back to the Table of Contents. «

OPI

default: false

OPI: true|false|([?]<expression>)

Examples:

OPI: true

Description:

When "true", OPI instructions should be output with the element's image. When "false", OPI instructions should not be output with the element's image.

Whenever one or more OPI images are included in either PDF or PostScript output, an ASCII text file is also created that contains the names of the OPI images. The content of the ASCII text file allows the authors to know which particular images need to be transferred to the prepress image server.

The ASCII text file has the following naming convention:

<ResultFile>_OPI.txt

The content of the ASCII text file are as follows (every two lines in the file represents a single OPI image):

<name-1><carriage return/linefeed>
<horizontal tab><name-2><carriage return/linefeed>
...

» Back to the Table of Contents. «

overflow

default: visible

overflow: visible|hidden|([?]<expression>)

Examples:

overflow: hidden

Description:

When this property is set to "hidden" and the box height is 0, the text is truncated prior to it wrapping to the second line (i.e., one line of text is output). In contrast, if this property is set to "hidden" and the box height has been explicitly set, the text is truncated following the last line of text that can be output within the dimensions of the box.

If this property is set to "visible" and the contents of a box exceeds its height, the box is automatically increased in height to accommodate the additional information. This property is particularly useful with a "SPAN" tag when defining a field on a form that cannot exceed a given width and cannot wrap to the next line.

» Back to the Table of Contents. «

padding

default: 0

padding: <padding> [<padding> [<padding> [<padding>]]]

<padding>:

<number constant>|([?]<expression>) <length unit>|<percentage unit>

Examples:

padding: 1pt

Description:

Apply a padding around the element and inside of the margin and/or border (please refer to the box diagram at the beginning of this chapter). The padding area will always be filled with the background-color of the current element. From 1 to 4 values may be given for a padding setting and are interpreted as follows:

1 value	Sets the padding for all 4 sides.
2 values	Sets the padding for the (top, bottom) and (right, left) sides respectively.
3 values	Sets the padding for the (top) and (right, left) and (bottom) sides respectively.
4 values	Sets the padding for the (top) and (right) and (bottom) and (left) sides respectively.

» Back to the Table of Contents. «

page-break-inside

default: auto

page-break-inside: auto|avoid|avoidrow|(<expression>)

Examples:

page-break-inside: avoid

Description:

If the "page-break-inside" property is set to "auto" for a formatting element (e.g., DIV, SPAN, or TABLE), the content of the element can be split over a logical page break (the default behavior).

However, if the "page-break-inside" property is set to "avoid" for a formatting element, the entire element (including it's content) must fit on the remaining portion of the current page otherwise a logical page break is performed and the element is formatted on the next page.

Also, if the "page-break-inside" property is set to "avoidrow" for a TABLE element (that may contain variable height rows), an entire row (including it's content) must fit on the remaining portion of the current page otherwise a logical page break is performed and the row is formatted on the next page.

The "page-break-inside" property should only be set to "avoid" or "avoidrow" for those elements that actually require this type of formatting. Overuse of this property with a value of "avoid" or "avoidrow" can result in some amount of performance degradation during document processing due to excessive checkpointing.

» Back to the Table of Contents. «

position

default: static

position: static|relative|absolute|(<expression>)

Examples:

position: absolute

Description:

If the "position" property is set to "static" (the default value), the formatting element is part of normal flow. That is, the formatting element participates with all pagination mechanisms in a normal and predictable manner. The properties "left", "top", "right" and "left" are not applicable for the position "static".

However, if the "position" property is set to "relative", the formatting element is part of normal flow, but is further positioned relative to its "static" normal flow location by utilizing the "left", "top", "right" and "left" properties.

Also, if the "position" property is set to "absolute", the formatting element is taken out of normal flow. That is, the formatting element is positioned relative to its parent element by utilizing the "left", "top", "right" and "left" properties. Since absolute positioning is not part of normal flow, absolute positioned elements that exceed the current page size will be ignored.

» Back to the Table of Contents. «

prescale

default: no

prescale: no|max-uniform|<number constant>|(<expression>)

Examples:

prescale: max-uniform

Description:

Proportional pre-scaling of images is supported for all types of cross-media output formats except XHTML. Whereas the "scale" property will scale the images at display time, "prescale" will scale images prior to being output in the resulting media type.

A common notion is to pre-scale huge images to twice the size of the parent element's box, which will preserve the image integrity for document "zooming" purposes and result in a much smaller output file. Then, the images are subsequently scaled down for actual display by using the "scale" property.

The mnemonic "max-uniform" will proportionally pre-scale the image to the maximum size of the parent element's box. In contrast, the <number constant> is a floating point factor where a value of 1.0 implies pre-scaling the image to the maximum size of the parent element (i.e., the same as "max-uniform").

However, unlike the "scale" property, which scales relative to the image's size, the "prescale" property scales relative to the size of the parent element. Therefore, a value of 2.0 will proportionally pre-scale the image to twice the size of the parent element.

» Back to the Table of Contents. «

ref-keys

default: none

ref-keys: '<string constant>'|([?]<expression>)
[, '<string constant>'|([?]<expression>)]...

Examples:

ref-keys: 'C','01'

ref-keys: (strKey1),(strKey2)

Description:

The values assigned to this property represent the keys for the reference that are used in sorting. The "refsort" function may be subsequently used to temporarily sort the reference table based upon any combination of the specified reference keys.

» Back to the Table of Contents. «

ref-link

default: none

ref-link: '<string constant>'|([?]<expression>)

Examples:

ref-link: 'C01'

ref-link: (strSearch)

Description:

The value assigned to this property creates a hypertext link to a reference having the same "ref-search" name. This property is only applicable to box elements and is compatible with all output types.

Hypertext links will be generated for the View, PDF, XPS, RTF, and XHTML outputs.

» Back to the Table of Contents. «

ref-search

default: none

ref-search: '<string constant>'|([?]<expression>)

Examples:

ref-search: 'C01'

ref-search: (strSearch)

Description:

The value assigned to the this property must be unique and is used with the reference functions to search for and retrieve a specific reference by performing regular expression pattern matching. Both the contents of the "ref-search" and "ref-text" properties can be retrieved in a document via the reference functions.

» Back to the Table of Contents. «

ref-text

default: none

ref-text: '<string constant>'|([?]<expression>)

Examples:

ref-text: 'Sample reference text'

ref-text: (strText)

Description:

The optional value assigned to the this property supplies additional text that is stored with the reference. Both the contents of the "ref-search" and "ref-text" properties can be retrieved in a document by the reference functions. If a value is assigned to this property, the "ref-search" property must also be specified.

» Back to the Table of Contents. «

right

default: 0

right: auto|<number constant>|([?]<expression>)
<length unit>|<percentage unit>

Examples:

right: 2cm

Description:

This style property is only applicable if the "position" style property is set to either "relative" or "absolute". When the "position" style property is set to "relative", this property determines the element's additional horizontal positioning relative to its normal flow "static" position (with a positive value indicating to the left and a negative value indicating to the right).

When the "position" style property is set to "absolute", this property determines the element's horizontal positioning with respect to its parent element's right position. In all cases, when the properties "left" and "right" are simultaneously set, the "left" property takes precedence.

» Back to the Table of Contents. «

rotate

default: no

rotate: <number constant>|(<expression>)

Examples:

rotate: 90
rotate: -90

Description:

Rotate the element clockwise the specified number of degrees. If a negative number is specified, rotate the element counter-clockwise. All embedded text and elements are rotated by this operation, however embedded elements may not be rotated within already rotated parent elements.

The angle of rotation can be either 0 (i.e., no rotation), 90 (i.e., -270), or 270 (i.e., -90). This style is not utilized with XHTML and RTF outputs.

» Back to the Table of Contents. «

scale

default: no

scale: no|max-uniform|<number constant>|([?]<expression>)

Examples:

scale: max-uniform

Description:

Proportional scaling of images is supported for all types of cross-media output formats except XHTML. Because Browsers do not support scaling of images in CSS level 2, the rendered images are cropped instead.

The mnemonic "max-uniform" will proportionally scale the image to the maximum size of the parent element's box dimensions. In contrast, a <number constant> is a floating point factor where the value of 1.0 implies no scaling of the image. A value of 0.5 will proportionally scale the image to half it's normal size while a value of 2.0 will proportionally scale the image to twice it's normal size.

» Back to the Table of Contents. «

text-align

inherited - default: left

text-align: left|right|center|justify|([?]<expression>)

Examples:

text-align: left

Description:

Designates the horizontal alignment of each line of text within the current element. If the option "justify" is selected, all lines will be fully justified (i.e., left and right aligned) except the last line of the element or lines that have been prematurely ended with a "BR", "COLBR", or "PAGEBR" tag.

left	Left justified text.
right	Right justified text.
center	Centered text.
justify	Fully justified text.

» Back to the Table of Contents. «

text-decoration

inherited - default: none

text-decoration: none|underline|overline|
line-through|([?]<expression>)

Examples:

text-decoration: underline

Description:

This style property causes a horizontal underline, overline, or line-through to be drawn along with the text of the element.

none	No line is drawn.
underline	Draw a line along the baseline of the text.
overline	Draw a line along the top of the text.
line-through	Draw a line through the middle of the text.

» Back to the Table of Contents. «

text-indent

inherited - default: 0

text-indent: <number constant>|([?]<expression>)
<length unit>|<percentage unit>
[hanging]

Examples:

text-indent: .5in

text-indent: 5mm hanging

Description:

Indicates the indentation that will occur within a block-level element. If the key word "hanging" is not used, only the first line of a block-level element is indented (otherwise all lines but the first line of a block-level element are indented).

Note: For XHTML output, the key word "hanging" is a CSS level 3 enhancement and, as such, will only affect browsers that adhere to the CSS level 3 standard.

» Back to the Table of Contents. «

top

default: 0

top: auto|<number constant>|([?]<expression>)
<length unit>|<percentage unit>

Examples:

top: 2cm

Description:

This style property is only applicable if the "position" style property is set to either "relative" or "absolute". When the "position" style property is set to "relative", this property determines the element's additional vertical positioning relative to its normal flow "static" position (with a positive value indicating down and a negative value indicating up).

When the "position" style property is set to "absolute", this property determines the element's vertical positioning with respect to its parent element's top position. In all cases, when the properties "top" and "bottom" are simultaneously set, the "top" property takes precedence.

» Back to the Table of Contents. «

vertical-align

default: baseline

Examples:

Vertical-align: baseline

Description:

Sets the vertical alignment of text for a given font-size within the line height. All vertical alignment is performed relative to the baseline of the current line. The baseline of the current line is dynamic and is ultimately determined after all of the text fragments for the line have been calculated (due to changing font-sizes, etc.). Unless the line-height has been explicitly enlarged beyond 120% of the current font-size or differing vertical sized elements exist within a line, the vertical alignment might not have a visible effect.

When vertical-align is applied to a box SPAN, the box will be aligned to the top, middle, or bottom (default) of the current line. With a box SPAN, "baseline" and "sub" result in the same action as "bottom" while "super" results in the same action as "top".

baseline	Baseline of the font.
sub	Subscript.
super	Superscript.
top	Top of the line.
middle	Middle of the line.
bottom	Bottom of the line.

» Back to the Table of Contents. «

width

default: 0

width: auto|<number constant>|([?]<expression>)
<length unit>|<percentage unit>

Examples:

width: 1.5in

Description:

Designates the width of a box element, which does not include any margins, borders, or padding. In the case of a "SPAN" tag, this property differentiates between an inline SPAN (i.e., a width was not specified or was 0) and a box SPAN (i.e., a width greater than 0). With a box SPAN, since there is no baseline, it is by default aligned to the bottom of the current line unless changed with the vertical-align property.

An element's width and/or height can be automatically set by the width and/or height of an image. That is, if a "background-image" is specified with an element such as a DIV, SPAN, or TABLE, the element's width and/or height can be automatically determined by the interpreted size of the image itself.

When a "background-image" is specified with an element and the element's "width" property is either not specified, a value of 0, or a value of "auto", the width of the element will be determined from the interpreted width of the image.

» Back to the Table of Contents. «

word-spacing

inherited - default: 0

word-spacing: <number constant>|([?]<expression>)
<length unit>|<percentage unit>

Examples:

word-spacing: 98%

Description:

A value of normal or a zero value absolute measurement implies default word spacing, which is usually optimal for cross-media generation. Non-percent measurements may be either positive or negative and the resulting values are then factored into the default word spacing.

Percentage values are relative to the default setting being 100%. Since the default word padding is 5% of a word's width (with a maximum of half the width of a space character in the selected font), then a value of 95% represents no default word padding.

» Back to the Table of Contents. «

Chapter 5 - Expressions and Functions

Constants and Variables

In FPML, variable names can be up to 60 characters in length and can contain lower or upper case letters, digits (i.e., 0-9), and underscores (i.e., "_"). Variable names may not begin with a digit or an underscore. Variables are by default always "local" to the "method" that they are declared in (i.e., via the "SET" tag) and are discarded when the "method" is exited. However, "ByRef" parameter variables will still pass the value of the variable back to the caller prior to being discarded.

When a variable name is preceded by a "!" character, the variable is considered "global" to the "method" that it is declared in and is therefore not discarded when the "method" is exited. If a variable name is preceded by a "@" character, the variable is considered to be an external variable (i.e., a variable containing data from an application). Like global variables, external variables are considered "global" to any "method" and are therefore not discarded when the "method" is exited.

An external variable is automatically constructed by FinerEdge Publisher by utilizing the governing recordset name as follows:

@<recordset name>_<variable name>

Variables are always initially declared to be of the same data type as the value, <function>, or <expression> result. If the variable is already declared, its type is automatically changed to be of the same data type as the value being assigned.

Variables fit into three basic categories: whole numbers, floating point numbers, and strings. Date and time values may be represented as either whole numbers or strings with the internal representation for date and time values being whole numbers. When variables are created and assigned values from an external source (i.e., database, file, etc.), the values are automatically converted by FinerEdge Publisher into the applicable format.

All variables may have an optional subscript thus making them an element of an array. However, not all elements of an array need be allocated nor be of the same data type. The function "type" indicates if an element of an array is allocated and it's data type.

Numbers can hold whole values in the range of -2,147,483,648 to 2,147,483,647 (i.e., a 32-bit long). Floats can hold large floating point values in the range of 1.7 x 10 to the power of -308 to 308 (i.e., a 64-bit IEEE double).

Individual strings or string array elements created while generating a document can each hold, by default, up to 4095 characters. An external string variable (i.e., beginning with a "@" character) can hold greater than 4095 characters for output purposes via the VAR tag. Unpredictable results can occur if a variable containing greater than 4095 characters is used in any expressions or functions.

The basic expression syntactic element definitions are as follows:

<number constant>:

[-] <digit>...

The optional minus sign indicates a negative <number constant>.

<float constant>:

[-] <digit>... <period> <digit>...

The optional minus sign indicates a negative <float constant>. The <period> specifies the character "." (i.e., internal format).

<digit>:

0|1|2|3|4|5|6|7|8|9

<decimal point>:

The <decimal point> is the user defined decimal point character.

<thousand>:

The <thousand> is the user defined thousand character.

<currency>:

The <currency> is the user defined currency character.

<string constant>:

'<string mnemonic>...'

<string mnemonic>:

\\|\a|\g|\l|\m|\p|\q|\s|\xhh|\uhhhh|<string character>

Any other characters beginning with a backslash, other than those listed above, are not translated and result in the original character. When specifying a <string constant> containing backslash characters as actual text, two contiguous backslashes indicate a single backslash character of text.

\	backslash
a	apostrophe
g	greater than
i	page number in lowercase roman numeral format
I	page number in uppercase roman numeral format
l	less than
m	ampersand
p	page number in decimal format
q	quote
s	absolute space
x	ascii character indicated by the two subsequent hexadecimal digits ("hh")
u	unicode character indicated by the four subsequent hexadecimal digits ("hhhh")

<string character>:

Any character except the null and apostrophe characters.

Examples:

   23

   -671

   inx

   num[2]

   len('abc')

   inx*num[2]-1

Examples:

   2.3

   -67.1

   val

   newval[8]

   float(76)

   (val*newval[8])

Examples:

   'abc'

   str_1

   strval[5]

   format(987)

   str_1+strval[5]

<number variable>:
<float variable>:
<string variable>:

[!|@] <alphanumeric> [<subscript>]

A variable beginning with a "!" character is considered to be a global variable and is therefore not discarded when the "method" that declared it is exited. A variable beginning with a "@" character is an external variable from the application and is also considered global to any "method". All other variables (i.e., those not beginning with either a "!" or "@" character) are local to the "method" that they are declared in and are therefore discarded when the "method" is exited.

<alphanumeric>:

The characters: A-Z, a-z, 0-9, and "_" (but may not begin with the characters 0-9 or "_").

<subscript>:

[ <number> ]

References a particular element of an array. All elements of an array are not declared until they are initially assigned values of either <number>, <float>, or <string>. You may test if an element of an array is declared by using the "type" function.

Pointers to strings

Tag attribute values may contain one or more pointers to string variables. A pointer to a string variable is specified within the text of a tag's attribute as follows:

^strVariable
^!strGlobal
^@rs_var

The content of a string variable used as a pointer is evaluated as if it were actually part of the text of the attribute. For example if the string variable "strCols" contained the text "50%,50%", the following TABLE tag would declare two columns each having a width of 50% of it's parent element:

» Back to the Table of Contents. «

Expression Elements and Operators

FinerEdge Publisher employs a comprehensive set of operators that can be used to construct expressions. In addition, parenthesis may be used anywhere within an expression to affect the precedence of operators or for clarity.

Expressions can appear anywhere a <number>, <float>, or <string> may be used. Examples of this is as follows:

   format(len(str))
   format(len(str)*2+1)
   format(ary[inx])
   format(ary[inx+1])

<expression>:

[-|not] <operand> [<operator> <operand>]...

Examples:

   num*2+1

Input: num = 3
Result: 7

   2.2+flt

Input: flt = 1.57
Result: 3.77

   '123'+':'+str+':'+'789'

Input: str = "456"
Result: "123:456:789"

   num >= 1 ' num <= 10

Input: num = 5
Result: 1

   (num+1)*2 > 10

Input: num = 2
Result: 0

Any of the above operands may be used anywhere in an <expression>.

<sub-expression>:

( <expression> )

The <operator> table shown below indicates the evaluation precedence. In addition, the precedence may be overridden by specifically enclosing portions of an <expression> within parenthesis.

<operator>:

Operators with equal precedence are evaluated from left to right in an <expression>. Operators with a higher precedence value are evaluated before operators having a lower precedence value. Enclosing parts of an <expression> within parenthesis overrides precedence and changes the order of evaluation.

The column "Operand" in the table below shows the type of operands that may be used with a particular operator where N = <number>, F = <float>, and S = <string>.

Operator	Operands	Precedence	Description
-	N,F	5	Unary minus
Not	N	5	Unary not
*	N,F	4	Multiply
/	N,F	4	Divide
Mod	N	4	Modulus
+	N,F,S	3	Add or string concatenate
-	N,F	3	Subtract
>	N,F	2	Greater than
>=	N,F	2	Greater than or equal to
<	N,F	2	Less than
<=	N,F	2	Less than or equal to
=	N,F,S	2	Equal to
<>	N,F,S	2	Not equal to
And	N	1	Logical "and" condition
Or	N	1	Logical "or" condition

» Back to the Table of Contents. «

Late evaluation expressions

Late evaluation expressions are supported in FinerEdge Publisher during the document rendering phase. That is, when a late evaluation expression is detected, the evaluation of various tags and style properties are deferred until document rendering.

Late evaluation expressions are most useful when embedded within page areas, which are re-evaluated for each generated page. However, late evaluation expressions may also be effectively used anywhere in a document.

All late evaluation expressions begin with a question mark ("?") and are followed by normal expression rules. Late evaluation expressions are recognized within a content tag's attributes or style properties.

Late evaluation expressions are also recognized when used with a SET or VAR tag's "expr" attribute. In these two cases, the entire evaluation of the SET or VAR tag is deferred until document rendering.

In addition, if a SET tag's "var" attribute begins with a question mark ("?"), a special form of late evaluation is recognized. In this case, if the SET tag's "expr" attribute does not also begin with a question mark ("?"), the expression is evaluated normally in document processing while the actual SET tag assignment is handled in document rendering. This capability is especially useful to embed the results of expressions from document processing for later use during document rendering.

Examples of late evaluation expressions are as follows:

Since late evaluation expressions are evaluated during document rendering, the current page number is available for use as a variable (named "numPage") that has a type of number. If the variable "numPage" is used with normal document processing, the resulting value will always be 1.

» Back to the Table of Contents. «

Regular Expressions

FinerEdge Publisher comes with a full regular expression facility built in. Also, any time a regular expression is used, a simple pattern may be substituted by simply passing it through the "pattern" function first. The "pattern" function yields a valid regular expression that corresponds to the original simple pattern.

<regular expression>:

[#|~|^]... <re>... [$]

#	Whole phrase (i.e., no alpha-numeric characters before or after matched text).
~	Ignore upper/lower case differences.
^	Must be the beginning of the text.
$	Must be the end of the text.

Examples:

   abz

   #~abz

   .*a?z.*

   a{0:.*}z

   a[b-y]z

   a(bc|cd)z

   a+{0:[0-9]+}b+{1:[0-9]+}c+

A number of extensions to regular expressions enable FinerEdge Publisher to further process additional pattern matching conditions. Specifically, the prefix character "#" indicates that the text being matched must be a whole phrase while the prefix character "~" indicates that upper and lowercase differences are to be ignored.

There are no delimiters of any kind (including spaces) that separate any of the elements in a <regular expression>. Spaces are considered a valid part of the <regular expression>.

The <re> element may be given as many times as needed to create the desired <regular expression>. Each <re> element may be composed of either <expr> or <return item>.

<return item>:

{ <number constant> : <expr> }

{	Begin return item <number>.
}	End current return item.

While recognizing a pattern, a document author may isolate and return parts of the pattern into <string variable>s as facilitated by the "match" and "picture" functions. The <number constant> maps the text that was isolated into a specific <string variable>. The <number constant> 0 specifies the first <string variable>, 1 the second <string variable>, and so on.

<expr>:

<element>... [ | <expr>]

\|	Or expression.

One or more <element>s can comprise an <expr> element. This can be optionally followed by a pipe character ("|") and another <expr> in order to specify an "or" condition. With multi-character text, an <expr> is often enclosed in parenthesis as a <sub-expr>. For example, the pattern "abc(def|xyz)" would match either the text "abcdef" or "abcxyz".

<element>:

<re char>|<escape char>|<set>|<sub-expr>|. [*|+|?]

*	Match zero or more occurrences of the preceding <element>.
+	Match one or more occurrences of the preceding <element>.
?	Match zero or one occurrence of the preceding <element>.

Each element of the <regular expression> can be either a <re char>, <escape char>, <set>, <sub- expr> or a period (i.e., ".") optionally followed by either a "*", "+", or "?". A period (i.e., ".") matches any single character. To match a string of any characters, the regular expression ".*" (i.e., a period followed by an asterisk) may be used.

<re char>:

Any character except * + ? | . [ ] ( ) { }.

Any single character may be specified by preceding it with a backslash character. A single backslash character is specified by two consecutive backslash characters.

<set>:

[ [^] <set range>... ]

A <set> specifies a set of valid characters that match against one or more characters in the pattern. One or more <set ranges> are enclosed within brackets and define the <set>. The optional "^" character following the open bracket indicates a "not" condition (i.e., any character is valid except for the characters in the <set>).

<set range>:

<set char> [- <set char>]

A <set range> defines characters that are included in the <set>. If the first <set char> is followed by a hyphen ("-") and another <set char>, all of the characters within the range of the two <set char>s are part of the <set> (including the <set char>s themselves). For example "A-Z" indicates all of the uppercase characters of the English alphabet.

Either the character itself or an <escape char> may indicate a single character in a <set> (i.e., the character itself preceded by a backslash).

<sub-expr>:

( <expr> )

A <sub-expr> is an <expr> that is enclosed in parenthesis in order to establish grouping and override evaluation precedence.

» Back to the Table of Contents. «

chr

chr ( <number> )

Examples:

chr(65)

chr(numVal)

Description:

The "chr" function accepts a single numeric parameter and returns a string containing a single character that corresponds to the ordinal position given by the value of the numeric parameter.

» Back to the Table of Contents. «

cvt

cvt ( in|cm|mm|pc|pt|wm|ex|iu , in|cm|mm|pc|pt|em|ex|iu , <number> )

Examples:

cvt(in,iu,1)

Result: 1440

Description:

Returns a <number> representing the converted <number> parameter. The first mnemonic parameter is the "from" (or current) unit of measure and the second mnemonic parameter is the "to" (or new) unit of measure. The mnemonic parameter options are as follows:

in	Inches
cm	Centimeters
mm	Millimeters
pc	Picas
pt	Points
em	Em width.
ex	Ex width.
iu	Internal units (twips).

» Back to the Table of Contents. «

date

Examples:

   date(current)

Result: 19980101

   date(difference,19980101,19980201,0)

Result: 31

   date(offset,19980101,11,0)

Result: 19980112

   date(cin,us,'1/1/98')

Result: 19980101

   date(cout,usz,19980101)

Result: "1/1/98"

Description:

Return a <number> or <string> value for the date calculation indicated by the first parameter. The <params> differ based upon the date calculation to be performed. If a date is invalid, a value of 0 is returned.

When a <ctype> (i.e., convert type) parameter is used with any of the <params> below (i.e., cin or cout), a mnemonic is also expected and has the following description:

us	Use user specified date.
mm	Use MM/DD/YY date.
dd	Use DD/MM/YY date.
yy	Use YY/MM/DD date.
jj	Use YY/DDD Julian date.
nn	Use straight number of days.
cm	Use MM/DD/YYYY date.
cd	Use DD/MM/YYYY date.
cy	Use YYYY/MM/DD date.
cj	Use YYYY/DDD Julian date.

The following <ctype> parameters may also be used with the "cout" form of this function:

usz	Use user specified date with zero suppression.
mmz	Use MM/DD/YY date with zero suppression.
ddz	Use DD/MM/YY date with zero suppression.
yyz	Use YY/MM/DD date with zero suppression.
jjz	Use YY/DDD Julian date with zero suppression.
cmz	Use MM/DD/YYYY date with zero suppression.
cdz	Use DD/MM/YYYY date with zero suppression.
cyz	Use YYYY/MM/DD date with zero suppression.
cjz	Use YYYY/DDD Julian date with zero suppression.

When an <option> parameter is used in any of the <params> below, a <number> is subsequently expected and has the following description (all date calculations that use <option> will account for weekends and holidays where appropriate):

0	Include weekends and holidays.
1	Exclude weekends.
2	Exclude holidays.
3	Exclude weekends and holidays.

The type of date calculation is determined by the first parameter. The mnemonic for the type of date calculation and remaining <params> are listed below:

validate -

Validate the date and return a <number> (1=Valid date, 0=Invalid date).

difference -

Returns a <number> indicating the number of days difference between the date given by the first <number> and the date given by the second <number>. If the second <number> is larger than the first <number>, a positive result is returned (otherwise a negative result is returned).

offset -

Returns a <number> indicating a new date, given a date in the first <number> and the number of days (positive or negative) in the second <number>.

week -

Returns a <number> indicating the day of the week, given a date in <number> (0=Sunday through 6=Saturday).

month -

Returns a <number> indicating the number of days in the month given a date in <number>.

holiday -

Returns a <number> indicating if the date, given in <number> is a holiday (0=Not a holiday, 1=Holiday).

start -

Returns a new date as a <number> indicating the start of the week for the date given in <number>.

end -

Returns a new date as a <number> indicating the end of the week for the date given in <number>.

current -

Returns a <number> indicating the current date.

cin -

Converts the external form date in <string> and returns a date as a <number>. Leading and trailing spaces are ignored.

cout -

<ctype> , <number> [, <string>]

Converts a date in <number> and returns an external form date as a <string>. The first character of the optional <string> is a delimiter used to format the date (e.g., "/"). If the string is empty (i.e., ""), no delimiter is used. If no delimiter is given, the user specified date delimiter is used.

us -

Return a <string> indicating one of the date formats selected by the user. This is useful to display the date format currently selected by the user. For example, if the user selected the date format MMDDYYYY, this function would return the <string> "MM/DD/YYYY".

fd -

<number> [, <number>]

Converts a date in the first <number> to an external date string. If the second <number> is not given, the date is converted using the default format. For example, if the second <number> is given, a date of 1/1/1998 would be formatted as follows:

0	Jan 1 2000.
1	January 1 2000.
10	Sat Jan 1 2000.
11	Saturday January 1 2000.

fm -

Returns a <string> specifying a mnemonic for the month given by the date in <number>.

fw -

Returns a <string> specifying a mnemonic for the day of the week given by the date in <number>.

Note: Please refer to the "time" function for additional functionality relating to both times and dates.

» Back to the Table of Contents. «

first

first ( <string variable> , [not] <string> )

Examples:

first(str,not ' ')

Input: str = "22.1 17.6"
Result: "22.1", str = " 17.6"

first(str,'1234567890')

Input: str = "34.2"
Result: "34", str = ".2"

Description:

Returns a <string> containing the first token found in the <string variable> parameter. The leading characters of the <string variable> parameter are returned as a <string> result that exist in the set of characters specified by the <string> parameter. The content of the <string variable> are updated to eliminate the token just parsed in preparation for the next call to this function.

If the option "not" is used prior to the <string> parameter, the set of characters is reversed (i.e., not in the set of characters specified by the <string> parameter).

» Back to the Table of Contents. «

float

float ( <number> )

Examples:

float(867)

Result: 867.0

Description:

Returns a <float> representing the value of the <number> parameter. The decimal part of the floating point number is 0. To convert a <float> into a <number>, see the function "number".

» Back to the Table of Contents. «

format

format ( <number>|<float> [: <format options>...]

[, <number> [: <number> ] [, <string>] ] )

<format options>:

a|c|t|s|e|n

Examples:

   format(345)

Result: "345"

   format(34.5)

Result: "34.5"

   format(34.5,2)

Result: "34.50"

   format(34.5,4,'*')

Result: "34.5***"

   format(1234567.89:ct)

Result: "$1,234,567.89"

Description:

Returns a <string> representation of the <number> or <float> parameter. The user defined decimal point character is used when formatting a <float> parameter.

When a <float> parameter is specified and an optional <number> is designated after the <float>, the <number> designates the number of decimal places. If the number of decimal places in <float> is less than <number>, the <string> is padded with fill characters (otherwise the <number> is rounded and the resulting <string> is truncated).

If a <float> parameter is specified whose value is a whole number (without an optional <number> parameter), the user defined decimal point character followed by "0" is appended to the resulting <string>. The default fill character is "0"; however, the fill character may be explicitly designated by the first character of the subsequent optional <string>.

A number of single character options may be specified with the <format options>. No space characters can be present between single character options. The single character options and their respective descriptions are as follows:

a -

If this option is not specified and the <number> or <float> is negative, a negative sign precedes the result (no prefix is used if the <number> or <float> is positive). A leading negative sign always precedes a currency sign if used.

If this option is specified and the <number> or <float> is negative, a negative sign is appended to the result (no suffix is used if the <number> or <float> is positive).

c -

The user defined currency character is prefixed to the <number> or <float> after any leading negative sign.

t -

The user defined thousand character is formatted with the <number> or <float>.

s -

Append a suffix to the number as related to the value (e.g., 2nd, 12th, 1.5ths, etc.). The "s" option cannot be used with the "a" option.

e -

Format the number as English currency (e.g., One Dollar And 50 Cents). The "e" option cannot be used with any of the other options.

n -

Format the number using one of the indicated numbering schemes (e.g., AA,ab,IV, etc.). The "n" option cannot be used with any of the other options.

When using this option, the optional <number> parameter specifies the numbering scheme (0=English legal (default), 1=Roman numerals). A colon and a second optional <number> may also follow the optional <number>. The second optional <number> indicates if upper or lower case is used for the numbering scheme (0=lower case (default), 1=upper case).

» Back to the Table of Contents. «

if ( <number> , <number>|<float>|<string> ,

<number>|<float>|<string> )

Examples:

if(val,'CR','DB')

Input: val = 1
Result: "CR"

if(val > 10,1.01,1.03)

Input: val = 5
Result: 1.03

Description:

Performs a test on the value of the <number> parameter (<number> may also be an <expression>). If the value of <number> is not 0 (i.e., true), the result of the second parameter is returned. If the value of <number> is 0 (i.e., false), the result of the third parameter is returned. This function returns either a <number>, <float>, or <string> depending upon the resulting value of the applicable second or third parameter.

» Back to the Table of Contents. «

len

len ( <string> )

Examples:

len("Hello there")

Result: 11

Description:

Returns a <number> representing the length of the <string> parameter.

» Back to the Table of Contents. «

match

match ( <match parameters> )

<match parameters>:

[+] <string> , <string> [, <match constant>|<match variable>]

<match constant>:

<number constant> [, <number constant>]

<match variable>:

<number variable> , <number variable> [, <string variable>]...

Examples:

   match('12xyz34','abc')

Result: 0

   match(strText,'abc',startval,lenval)

Result: 1, startval = 2, lenval = 3

   match('12abc34','12{0:.*}34',startval,endval,retstr)

Result: 1, startval = 0, lenval = 7, retstr = "abc"

Description:

Matches the <regular expression> in the second <string> parameter to the contents of the first <string> parameter. A simple pattern can easily be converted to a <regular expression> by using the "pattern" function. The "match" function returns a <number> indicating that the match either succeeded (1) or failed (0).

Normally, the first match of the <regular expression> in the initial <string> parameter is used (with respect to the character offset where the match began). If the optional plus sign character ("+") is specified, the last match of the <regular expression> in the initial <string> parameter is used.

Either the <match constant> or <match variable> formats may be used. The first <number> variable or <number constant> (if present) determines the character offset within the text of the <string> where the match begins (relative to 1).

The second <number> variable or <number constant> (if present) determines the maximum length beginning from the offset that will be matched. If this value is not specified, the remainder of the text beginning from the offset is matched.

The following information applies when using the <match variable> format:

After the function successfully completes, the first <number variable> contains a character offset to the start of the text matched (relative to 1). The second <number variable> contains the length of the text matched.

The optional <string variable>s contain the text of the returned items from the match (i.e., by using the <regular expression> "{}" braces syntax).

» Back to the Table of Contents. «

mid

mid ( <string> , <number> , <number> )

Examples:

   mid('1234567890',4,3)

Result: "456"

   mid('1234567890',1,5)

Result: "12345"

   mid('1234567890',6,0)

Result: "67890"

Description:

Returns a sub-string of the <string> indicated by the first parameter. The second parameter designates the starting offset within the <string> and is relative to 1. The third parameter designates the number of characters to return. If a value of 0 is used with the third parameter, the remainder of the <string> is returned past the starting offset (including the starting offset).

» Back to the Table of Contents. «

number

number ( <float> )

Examples:

number(867.2)

Result: 867

Description:

Returns a <number> representing the value of the <float> parameter. The decimal portion of the floating point number is truncated. To convert a <number> into a <float>, see the function "float".

» Back to the Table of Contents. «

ord

ord ( <string> )

Examples:

ord('abc')

ord(strText)

Description:

The "ord" function accepts a single string parameter and returns, as a numeric result, the ordinal position corresponding to the first character in the string parameter.

» Back to the Table of Contents. «

parse

parse ( <string variable> , [not] <string> )

Examples:

parse(str,' ')

Input: str = " Hello there"
Result: "Hello", str = " there"

parse(str,not '1234567890')

Input: str = " #34 #27"
Result: "34", str = " #27"

Description:

Returns a <string> containing the next token found in the <string variable> parameter. The leading characters of the <string variable> parameter are first discarded that are in the set of characters specified by the <string> parameter. Then, the remaining leading characters of the <string variable> parameter are returned as the <string> result of this function until one of the characters specified by the <string> parameter are recognized. The content of the <string variable> are updated to eliminate the token just parsed in preparation for the next call to this function.

If the option "not" is used prior to the <string> parameter, the set of characters is reversed (i.e., not in the set of characters specified by the <string> parameter).

» Back to the Table of Contents. «

pattern

pattern ( <string> )

Examples:

pattern('a*b??c')

Result: "a.*b..c"

Description:

Returns a <string> containing the <regular expression> equivalent of the simple pattern in the <string> parameter. Simple patterns use "*" to represent ".*" and "?" to represent ".".

» Back to the Table of Contents. «

picture

picture ( <string> , <string> [, <output list>] )

<output list>:

<output item> [, <output item>]...

<output item>:

*|<space item>

<space item>:

[+] [<number>] <string>

Examples:

picture('xx12xxx345xx','x+{0:[0-9]+}x+{1:[0-9]+}x+')

Result: "12345"

picture('xxx45xx123xxx','x+{1:[0-9]+}x+{0:[0-9]+}x+',*,':',*)

Result: "123:45"

Description:

The "picture" function matches the <regular expression> in the second <string> parameter to the first <string> parameter. This function returns a formatted <string> based upon the <return item>s of the <regular expression> and an optional <output list>. If the <regular expression> does not match the first <string> parameter, the content of the <string> parameter is returned.

If an <output list> is not specified, the text of the <return item>s are concatenated together and returned as the <string> result. If an <output list> is specified, remaining <return item>s (if any) after the <output list> has been applied, are concatenated to the <string> result.

The <output list> is composed of one or more <output item>s that are formatted into the <string> result. If the <output item> is an asterisk (i.e., "*"), the next <regular expression> <return item> is concatenated to the <string> result.

A <space item> "spaces out" to either a fixed or relative column in the <string> result and always proceeds in a forward direction. For example, if the result is already at column 30, spacing to column 20 has no effect.

If a plus sign is not specified, the entire content of the <space item> <string> is used for spacing. The optional <number> indicates the number of times the <space item> <string> is written to the <string> result (a minimum of 1 is presumed). If the <space item> <string> is empty (i.e., ""), a single blank space character is used instead.

If a plus sign is specified, the subsequent <number> is the absolute column spaced to. In this case the first character of the <space item> <string> parameter indicates the character used to space out to the designated column. If the <space item> <string> is empty (i.e., ""), a blank space character is used.

» Back to the Table of Contents. «

record

record ( <string> , <string> [, <alphanumeric>] )

Examples:

record('1234 5678','6 4, 0 4',ary)

Input: ary[1] = Not declared, ary[2] = Not declared
Result: 2, ary[1] = "5678", ary[2] = "1234"

record(' 1/1/94 12.34 ','0 10 10 10',ary)

Input: ary[1] = 0, ary[2] = 0.0
Result: 2, ary[1] = 940101, ary[2] = 12.34

Description:

Returns a <number> indicating the number of fixed fields found in the first <string> parameter. The second <string> parameter designates one or more <field>s.

Each <field> has 2 <number>s. The first <number> indicates the starting position of the fixed <field> (relative to 1). The second <number> indicates the length of the <field> (in characters). The word "length" preceding the second <number> is optional. If the second <number> is a value of 0, the rest of the <string> parameter is presumed.

The syntax for the second <string> is as follow:

   <field> [[,] <field>]...

   <field>:

   <number> [length] <number>

The optional <alphanumeric> is used to name an array excluding the subscript. For each field seen, the text of the field is placed into an element of the array starting from a subscript of 1.

If the element of the array is not declared, it is automatically declared as having a type of <string>. However, if the element of the array is already declared, the text of the field is automatically converted to be of the same type as the array element (i.e., string, number, or float).

In addition, if the element of the array is a number and the text of the field includes the user defined date delimiter, the date is converted via the date format (see the "date" function). Also, when the text of the field includes the user defined time delimiter, the time is converted via the time format (see the "time" function).

The resulting <number> of this function can be used to determine the maximum array subscript that was used (starting from 1).

» Back to the Table of Contents. «

refget

refget ( <string> )

Examples:

refget('search')

refget('text')

Description:

The <string> parameter determines the type of information to be returned as follows:

The contents of the "ref-search" property for the current reference is returned as a string.

text

The contents of the "ref-text" property for the current reference is returned as a string.

page

The display page number where the reference appears is returned as a string. A forward reference will result in a special character sequence being returned. If the special character sequence is then formatted into the output of a document, it will be subsequently translated into an actual page number.

pagenum

The display page number where the reference appears is returned as a number. A forward reference will result in the current display page number being returned.

rpagenum

The real page number (i.e., without respect to the pageoffset) where the reference appears is returned as a number. A forward reference will result in the current real page number being returned.

offset

The document rendering input file offset is returned as a number.

index

The unique reference index value starting from one, assigned in the order of appearance, is returned as a number.

» Back to the Table of Contents. «

refsearch

refsearch ( <string> [, <string> [, <number>]] )

Examples:

refsearch('begin')

refsearch('page-begin-down','Group.*')

refsearch('page-begin-down','Item.*',3)

Description:

Returns the "index" of the found reference or 0 if a reference was not found. The first <string> parameter defines the type of search being performed and can contain the following values:

begin

Position the current reference pointer to the first reference in the reference table.

end

Position the current reference pointer to the last reference in the reference table.

page-begin-down
page-begin-down-adjust

Position the current reference pointer to the first reference for the currently processed page with a bias for searching down. If the "adjust" suffix is used and the found reference starts on the currently processed page and continues to the next page, position to the next reference.

page-begin-up
page-begin-up-adjust

Position the current reference pointer to the first reference for the currently processed page with a bias for searching up. If the "adjust" suffix is used and the previous reference continues to the currently processed page, position to the previous reference.

page-end-down
page-end-down-adjust

Position the current reference pointer to the last reference for the currently processed page with a bias for searching down. If the "adjust" suffix is used and the found reference starts on the currently processed page and continues to the next page, position to the next reference.

page-end-up
page-end-up-adjust

Position the current reference pointer to the last reference for the currently processed page with a bias for searching up. If the "adjust" suffix is used and the previous reference continues to the currently processed page, position to the previous reference.

Position the current reference pointer to the next reference in the reference table. If active sort information is present (i.e., see the refsort function), position the current reference pointer to the next sorted reference.

Position the current reference pointer to the previous reference in the reference table. If active sort information is present (i.e., see the refsort function), position the current reference pointer to the previous sorted reference.

The second optional <string> parameter supplies a regular expression pattern that is matched with the "ref-search" value to further constrain the search. The optional <number> parameter specifies the number of times that the search is repeated with the same parameters.

» Back to the Table of Contents. «

refset

refset ( <string> , <string> [, <expression>] )

Examples:

refset('end','A100001')

refset('end',strRefSearch)

Description:

The second <string> parameter is used to locate the reference, via the ref-search field, where the information will be set. The first <string> parameter determines the type of information to be set as follows:

end

Mark the end location of a reference to be subsequently used with with the "adjust" suffixes of the refsearch function. If the "adjust" suffixes are not used with the refsearch function for a particular reference, the refset function with the "end" option does not need to be employed.

» Back to the Table of Contents. «

refsort

refsort ( null|<key options> )

<key options>:

<number> <string> [, <number> <string>]...

Examples:

refsort(1 'Asc')

refsort(2 'Desc',1 '~Asc')

Description:

Sort the reference table using the keys that have were assigned to each reference with the "ref-keys" style property. After performing a sort, the references are accessed by using the "refsearch" function along with any non-page oriented options (i.e., first, last, next, previous).

When the option "null" is given, the active sort information is cleared. That is, the reference table will revert to its natural ordering, which is the order that the references were originally added into the reference table.

When the option <key options> is given, one of more <number> and <string> combinations may be designated separated by commas. The <number> specifies an index for a specific key within the "ref-keys" style property (starting from 1). The <string> specifies either "Asc" (Ascending) or "Desc" (Descending). A tilde character (i.e., "~") prior to the option "Asc" or "Desc" causes any uppercase or lowercase differences to be ignored when comparing reference keys.

» Back to the Table of Contents. «

repeat

repeat ( <string> , <number> )

Examples:

repeat('0',5)

Result: "00000"

repeat('abc',3)

Result: "abcabcabc"

Description:

Returns a <string> containing the parameter <string> repeated for the number of times indicated by the value of <number>.

» Back to the Table of Contents. «

replace

replace ( <string> , <string> , <string> )

Examples:

replace('zzzabczzzabczzzabczzz','abc','def')

Result: "zzzdefzzzdefzzzdefzzz"

replace(str,pattern('a?c'),'_')

Result: "zzz_zzz_zzz_zzz"

Description:

The "replace" function matches the <regular expression> in the second <string> parameter to the first <string> parameter. For each match found in the first <string> parameter, the matched text is replaced by the content of the third <string> parameter and the resulting new string is returned.

» Back to the Table of Contents. «

rgb

rgb ( <number> , <number> , <number> )

Examples:

rgb(255,0,255)

Result: "#ff00ff"

Description:

Returns a <string> containing the RGB color given by the three <number> parameters (i.e., red, green, and blue respectively). The result of this function is compatible with all of the color oriented style properties.

» Back to the Table of Contents. «

rsrecord

rsrecord ( )

Examples:

rsrecord()

Result: 5

Description:

Returns the logical record number for the currently active recordset drilldown (relative to 1).

» Back to the Table of Contents. «

rsrecords

rsrecords ( )

Examples:

rsrecords()

Result: 10

Description:

Returns the number of records in the currently active recordset drilldown.

» Back to the Table of Contents. «

scan

scan ( <string> , [+] [not] <string> [, <alphanumeric>] )

Examples:

   scan('12,345',',')

Result: 2

   scan('12,345',',',ary)

Input: ary[1] = Not declared, ary[2] = Not declared
Result: 2, ary[1] = "12", ary[2] = "345"

   scan('12,345',not '12345',ary)

Input: ary[1] = Not declared, ary[2] = Not declared
Result: 2, ary[1] = "12", ary[2] = "345"

   scan('12 , 345',+' ,',ary)

Input: ary[1] = Not declared, ary[2] = Not declared
Result: 2, ary[1] = "12", ary[2] = "345"

   scan('12 , 345',+not '12345',ary)

Input: ary[1] = Not declared, ary[2] = Not declared
Result: 2, ary[1] = "12", ary[2] = "345"

Description:

Returns a <number> indicating the number of fields found in the first <string> parameter. The second <string> parameter designates one or more field delimiter characters (i.e., those characters separating fields in a record).

If the optional character "+" is not specified, only one of the field delimiter characters separates each field. However, if the optional character "+" is specified, one or more field delimiter characters can separate each field.

If the option "not" is specified, the set of characters is reversed (i.e., not in the set of characters specified by the second <string> parameter).

The optional <alphanumeric> is used to name an array excluding the subscript. For each field seen, the text of the field is placed into an element of the array starting from a subscript of 1.

If the element of the array is not declared, it is automatically declared with a type of <string>. However, if the element of the array is already declared, the text of the field is automatically converted to be of the same type as the array element (i.e. string, number, or float).

In addition, if the element of the array is a number and the text of the field includes the user defined date delimiter, the date is converted via the date format (see the "date" function). Also, when the text of the field includes the user defined time delimiter, the time is converted via the time format (see the "time" function).

The resulting <number> from this function can be used to determine the maximum array subscript that was stored (starting from 1).

» Back to the Table of Contents. «

time

Examples:

   time(current)

Result: 143500

   time(difference,143500,155800,0)

Result: 012300

   time(offset,143500,012300,0)

Result: 155800

   time(cin,'2:35p')

Result: 143500

   time(cout,amz,143500)

Result: "2:35p"

Description:

Return a <number> or <string> value for the date/time calculation indicated by the first parameter. The <params> differ based upon the time calculation to be performed.

When a <ctype> (i.e., convert type) parameter is used in any of the <params> below, a mnemonic is expected and has the following description:

us	Use user specified time.
mm	Use HH:MM 24-hour time.
ss	Use HH:MM:SS 24-hour time.
am	Use HH:MMa/p 12-hour time.
as	Use HH:MM:SSa/p 12-hour time.

The following <ctype> parameters may also be used with the "cout" form of this function:

usz	Use user specified time with zero suppression.
mmz	Use HH:MM 24-hour time with zero suppression.
ssz	Use HH:MM:SS 24-hour time with zero suppression.
amz	Use HH:MMa/p 12-hour time with zero suppression.
asz	Use HH:MM:SSa/p 12-hour time with zero suppression.

The type of time calculation is determined by the first parameter. The time calculation type and the remaining <params> are listed below:

difference -

Returns a <number> indicating the time difference between the time in the first <number> and the time in the second <number>. If the second <number> is larger than the first <number>, a positive result is returned (otherwise a negative result is returned).

If the third <number> is 0, the new time is wrapped around so that it remains on the clock. If the third <number> is 1, the new time is not wrapped around. This mode is used to perform time addition and subtractions where the actual resulting hours are needed.

offset -

Returns a <number> indicating a new time given a time value in the first <number> and a time value in the second <number> (either positive or negative). If the third <number> is 0, the new time is wrapped around so that it remains on the clock. If the third <number> is 1, the new time is not wrapped around. This mode is used to perform time addition and subtractions where the actual resulting hours are needed.

fdifference -

Returns the full difference between the date and time in the first two <number>s and the date and time in the remaining two <number>s. The new calculated number of days and time are returned in the first and second <number variable>s respectively.

foffset -

Returns a full calculated date and time given a date and time in the first two <number>s and the number of days and a time in the remaining two <number>s (either positive or negative). The new date and time are returned in the first and second <number variable>s respectively.

current -

Returns a <number> indicating the current time.

cin -

Converts the external form of time in <string> and returns a time as a <number>. Leading and trailing spaces are ignored.

cout -

<ctype> , <number> [, <string>]

Converts a time in <number> and returns an external form time as a <string>. The first character of the optional <string> is a delimiter used to format the time (i.e., ":", etc.). If the string is empty (i.e., ""), no delimiter is used. If the delimiter is not specified, the user specified time delimiter is used.

» Back to the Table of Contents. «

translate

Examples:

   translate(lower,'aBc')

Result: "abc"

   translate(hex,'abc')

Result: "616263"

   translate(recordset,'_a*b*1*2_')

Result: "ab12"

   translate(variable,'_a*b*1*2_')

Result: "a_b_1_2"

Description:

Returns a <string> with the characters of the first <string> translated according to the type of translation indicated by the first parameter. The values of the first parameter are as follows:

upper -

Translate all lowercase letters to uppercase letters.

lower -

Translate all uppercase letters to lowercase letters.

proper -

Translate the first character of each alphanumeric word to an uppercase letter and translate all other characters to lowercase letters.

ascii -

Translate hexadecimal characters to ascii characters.

hex -

Translate ascii characters to hexadecimal characters.

recordset -

Delete any non-alphanumeric characters from the returned <string>, which is then suitable to be used as recordset name.

variable -

Translate all non-alphanumeric characters to an underscore character. In addition, delete any leading or trailing non-alphanumeric characters, which is then suitable to be used as a variable name.

xml -

Translate all xml sensitive characters into their xml internal entity representations, which is then suitable to be used with the VAR option "tag" or evaluated by utilizing a pointer to string variable (e.g., ^strVar).

» Back to the Table of Contents. «

trim

trim ( <string> , [not] <string> [, first|last|all] )

Examples:

trim(' abc ',' ')

Result: "abc"

trim(' abc# ',' #',last)

Result: " abc"

Description:

Return a <string> eliminating the leading and trailing characters from the first <string> that are in the set of characters specified by the second <string>.

If the option "not" is used prior to the second <string> parameter, the set of characters is reversed (i.e., not in the set of characters specified by the second <string> parameter).

When either the third parameter is not given or the third parameter is the mnemonic "all", both the leading and trailing characters are trimmed from the first <string> parameter. If the third parameter is the mnemonic "first", only the leading characters are trimmed. If the third parameter is the mnemonic "last", only the trailing characters are trimmed.

» Back to the Table of Contents. «

type

type ( <number variable>|<float variable>|<string variable> [, <expression>] )

Examples:

   type(num)

Result: 1

   type(str)

Result: 3

   type(num,0.0)

Result: 0.0 (when "num" is not declared)

   type(str,'')

Result: '' (when "str" is not declared)

Description:

The first form of the "type" function does not use the second parameter <expression>. This form returns a <number> indicating the type of the parameter. The value of the returned <number> is as follows:

0	Unknown variable.
1	Number.
2	Float.
3	String.

The second form of the "type" function returns a result having a variable type that is consistent with the type of the second parameter <expression>.

When the <variable name> does not exists, the <expression> is returned instead. However, if the <variable name> does exists and is the same type as that of the <expression>, the content of the <variable name> is returned.

In the event that the <variable name> does exists and is not the same type as that of the <expression>, the content of the <variable name> is converted to be the same type as that of the <expression> prior to it being returned.

» Back to the Table of Contents. «

val

val ( <string> [, <number> ] )

Examples:

   val('45')

Result: 45

   val('45.6')

Result: 45.6

   val('45.6',0)

Result: 45

   val('45',1)

Result: 45.0

Description:

Returns a <number> or <float> representation of the first parameter. If the optional <number> parameter is not given, a type of <float> or <number> is returned depending upon the presence of the user defined decimal point character. If the <number> parameter is a value of 0, a type of <number> is explicitly returned. If the <number> parameter is a value of 1, a type of <float> is explicitly returned.

» Back to the Table of Contents. «

xmlatt

xmlatt ( <string> [, <string> ] )

Examples:

xmlatt('height')

Result: "2.1"

xmlatt('width','north_wall')

Result: "4.2"

Description:

Any of the attributes for the tags within an XML data file may be individually accessed, relative to their scope within recordsets, by employing the "xmlatt" function. The "xmlatt" function always returns a string representing the contents of the attribute (or an empty string if the attribute is not found).

If the optional second string is not specified, the first string is used to lookup an attribute for the XML data tag corresponding to the immediate record of the recordset. If the optional second string is specified, the first string is used to lookup an attribute for a specifically named XML data variable, designated by the second string, residing within the immediate record of the recordset.

» Back to the Table of Contents. «

Chapter 6 - Application Data Interface

Overview

This chapter presents the interface between the application, FinerEdge Publisher, and FPML documents. (The term "application" refers to the Database Query, XML Data, and the calling Application interfaces.)

The purpose of the application data interface is to expose external data in a read-only manner for inclusion into generated document outputs. The documents can also utilize the application data to govern portions of their processing (in addition to formatting the data into the generated outputs).

A number of FinerEdge Publisher application interfaces can be used to initiate document processing. For example, some applications might choose to call the .NET Windows Form Controls FPWriterNET and FPFormNET (C# and Visual Basic .NET) while other applications might choose to call the traditional ActiveX Controls FPWriter and FPForm (Visual Basic and other languages), the FPServer Dual Interface Automation Server (VBScript and JScript), the Java Native Interface (Java), or the FPEngine DLL (C++).

Regardless of the FinerEdge Publisher application interface employed, the same underlying mechanism is used to expose application data to documents. As a result of this common data interface, the information presented in this chapter applies to all of the application interfaces discussed above.

When using any of the FinerEdge Publisher application interfaces, an application defines what data is exposed by utilizing elements called external variables. The application is then enlisted by FinerEdge Publisher to populate the external variables at various points during the processing of a document.

In addition to controlling what data is exposed to documents, an application can also control how the data is to be presented to the FinerEdge Publisher engine. The data can be modified in any manner prior to populating the external variables.

FinerEdge Publisher always caches external data for documents. As such, an application is only prompted for information when absolutely necessary. Regardless of how many times an external variable is used in a document, FinerEdge Publisher will only request the application to fetch data for a variable once, or until the logical record is changed or the cached values are cleared for a logical record (i.e., when fetching a new record).

» Back to the Table of Contents. «

Defining recordsets and external variables

Each variable that is defined by the application is grouped into an application/document defined recordset name. Recordsets are dynamically created by the application using the FinerEdge Publisher interface functions and may hold as many external variables as needed.

When FinerEdge Publisher signals an application to populate external variables, it does so relative to a particular recordset name. All variables belonging to a specific recordset will be populated at the same time by the application.

Therefore, an application should define the variables of a recordset to include those that can be most easily and efficiently fetched as a single unit. For example, since most databases fetch information based upon a database-defined record, an application should group the applicable fields from the database record into a single FinerEdge Publisher recordset.

The following diagram shows an example of a possible relationship between a FinerEdge Publisher recordset and an application database table:

As an example, the database table fields "Last_updated" and "Middle_initial" were purposely not exposed to the FinerEdge Publisher document by the application. In contrast, the FinerEdge Publisher external variable "Whole_name" is formatted by the application from the database table fields "First_name", "Middle_initial", and "Last_name".

» Back to the Table of Contents. «

Creating external variables

Before a document is processed or edited, FinerEdge Publisher will call the InitDocument interface event or the initDocument DLL callback function. The application then creates the external variables and corresponding recordsets for the document by calling the interface method AppendVariable or the DLL function FPAppendVariable as shown in the diagram below:

The name of the main FinerEdge Publisher METHOD is passed as a parameter to InitDocument. The application can use the name of the main METHOD to differentiate between the variables of different documents (if applicable).

The recordset name that the variable is associated with is passed as a parameter to AppendVariable in addition to the name of the variable itself. If the recordset does not currently exist, it is dynamically created prior to appending the variable to it. The recordset name must not include any underscore characters.

The newly created external variables are referenced by the document by the following format:

@<recordset name>_<variable name>

» Back to the Table of Contents. «

Creating and populating global variables

Calling the SetVarLong, SetVarDouble, SetVarString, SetVarDate, or SetVarTime interface methods prior to a document being generated will cause the creation of those variables to be queued. The variables are then created and populated when the document is first being generated. Any external variables that are queued prior to document creation are also present for all successive document generated outputs until explicitly cleared by calling the interface Clear method.

Variables created prior to the document being processed utilize a recordset name of Global (Note: the interface method AppendVariable is NOT used to create external variables with a recordset name of Global). For example, a variable name of "Test1" would be referenced within a document by the name:

@Global_Test1

» Back to the Table of Contents. «

Using FinerEdge Publisher recordset parameters passed from documents

Recordset parameters allow a document to communicate any instructions to the application in a well-defined manner. Recordset parameters are retrieved by an application by calling the interface methods FindParam and GetParam or the FPEngine DLL functions FPFindParam and FPGetParam.

For single-record recordsets (presented below), a document author can set one or more parameters for a particular recordset prior to accessing any of the variables associated with the recordset. The parameters are set by using the "Select" action of the RECORDSET tag.

When the "Select" action is used to set parameters for a single-record recordset, the corresponding external variables for that recordset are also "cleared". This, in turn, forces the application to refetch the data from a possible different source (i.e., database record, etc.).

For multiple-record recordsets (also presented below), a document author can set one or more parameters for a particular recordset "drilldown". The parameters are set when creating a recordset drilldown by using the "New" action of the RECORDSET tag.

The word "drilldown" is a common data processing term that also implies a one-to-many relationship (i.e., we drilldown from a single parent record to one or more child records). Drilldown recordsets can be nested within each other when accessing information from within a FinerEdge Publisher document (i.e., for each record of a multiple-record drilldown recordset, this can result in further embedded one-to-many relationships, etc.).

» Back to the Table of Contents. «

Single-record recordsets (one-to-one relationships)

Single record-recordsets are both simple and straightforward to use in FinerEdge Publisher. Single-record recordsets do not necessarily imply that the corresponding application table contains only fixed data. Instead, based upon information known only by the application or through recordset parameters (or both), only one logical record exists.

For example, suppose an application accessed an account table in a database. If the account number was known by the application, only a single record of that table might be applicable to the document being processed. The same document could be subsequently processed many times perhaps using different account numbers. Regardless, FinerEdge Publisher considers this type of situation a single-record recordset.

In addition, external variables could be fetched for a particular recordset that, in turn, are used to set parameters for different recordsets. The application could fetch the parameters and use the information to access a single record in another table. (Note: External variables are always initialized when using the "Select" action of the RECORDSET tag which, in turn, forces an interface GetRecord call when the variables are accessed by the document.)

When FinerEdge Publisher calls the interface "GetRecord" method, the applicable recordset name is passed as a parameter to the method or function. This allows the application to fetch just the data for that particular recordset and populate the applicable external variables.

The following diagram shows how external variables are populated for a document when using single-record recordsets (note that use of the RECORDSET tag is optional when utilizing this type of access):

» Back to the Table of Contents. «

Multiple-record recordsets (one-to-many relationships)

As mentioned previously in this chapter, multiple-record recordsets (i.e., one-to-many relationships) are also known as "drilldown" recordsets in FinerEdge Publisher. That is to say, we drilldown from a parent record into one or more child records based on, in part, the data acquired from the parent record.

In addition, drilldown recordsets can be nested within each other. A parent record could reference one or more child records in another recordset that, in turn, each reference one or more child records in still other recordsets, etc.

Drilldown recordsets are created by using the "New" action of the RECORDSET tag in a document. When a document is finished accessing all of the records in a drilldown recordset, it deletes the recordset by using the "Delete" action of the RECORDSET tag. In turn, this causes FinerEdge Publisher to revert back to the previously active drilldown recordset along with current record of that recordset.

When a document wishes to access the external variables for a particular record of a drilldown, it sets the logical record number using the "Record" action of the RECORDSET tag. FinerEdge Publisher then initializes the external variables associated with that recordset and calls the interface "InitRecord" method, passing the applicable recordset name as a parameter.

A call to the interface "InitRecord" method instructs the application to store any parameters necessary to efficiently access each of the requested records in the "GetRecord" method or function. For each of the requested records to be returned, the application then calls the interface "AppendRecord" method. Then, for each parameter that must be stored with each record, the application calls the interface "AppendRecordParam" method. (Note: In database applications, a single parameter can usually be appended to each record that stores the "Identity" or "Counter" field of that record.)

Each record appended to the recordset during the interface "InitRecord" call is known to the document by a logical record number. A logical record number is simply a sequential number that starts from one. In addition, the last record returned by the application for a drilldown recordset can be accessed by the document through the "rsrecords" function.

When the document references an external variable that has not been populated by the application, FinerEdge Publisher calls interface "GetRecord" method, passing the recordset name as a parameter. This allows the application to fetch just the data for that particular recordset and populate its applicable external variables.

An application accesses the parameters for a specific record of a recordset by calling the interface "FindParam" and "GetParam" methods. These methods will return just the parameters for a logical record that was set by the document, which was initially stored by the application during the interface "InitRecord" call.

The following diagram depicts how drilldown recordsets are created and deleted. The diagram also shows how logical records are selected by a document and how external variables are populated for a document when using multiple-record recordsets:

» Back to the Table of Contents. «

Database Query Data Sources

FinerEdge Publisher utilizes a built-in database query facility for all FinerEdge Publisher components. ODBC data sources can be utilized along with XML data files and data supplied directly from applications in a concurrent manner. ODBC access is controlled by definition files that are specified via QUERYDATA tags. These definitions are called FinerEdge Publisher SQL files.

The same callback functions and/or events are employed for database query access as are utilized to fetch XML Data or data from a host application. When the interface methods InitDocument, InitRecord, GetRecord, and CloseRecord are called, the applicable FinerEdge Publisher application interfaces call the ODBC definition if one is currently attached to the document.

As such, a FinerEdge Publisher document can be generated in a standard mode where an application supplies all external data, in a pure ODBC mode where FinerEdge Publisher manages all data access, in a pure XML data mode of operation, or in a mixed-mode of operation where all of the aforementioned data sources are used simultaneously.

FinerEdge Publisher SQL files:

When FinerEdge Publisher SQL files are specified via QUERYDATA tags, data access is handled by FinerEdge Publisher through it's ODBC implementation. These SQL definition files are created and updated by the FinerEdge Publisher Query Designer that is built into the IDE. Please refer to the FinerEdge Publisher IDE Manual and the Query Designer Tutorial for more information on this subject.

More than one FinerEdge Publisher SQL file may be specified via multiple QUERYDATA tags within a document entity or module entity. However, all connection and query element names must be unique so that they can be referenced from a RECORDSET tag (otherwise an error will be generated). If the same FinerEdge Publisher SQL file is specified more than once, it will simply be ignored.

» Back to the Table of Contents. «

XML Data Files

FinerEdge Publisher can directly access one or more XML data files from documents. XML data files can be used along with database queries, and data supplied directly from an application.

XML data files contain a hierarchical structure of tags, attributes, and data that is encapsulated by tags. While XML data files do not generally replace relational databases for repositories of data, they do represent a very powerful and flexible way for exchanging information over networks including the Internet.

FinerEdge Publisher uses it's built-in recordset facility (i.e., RECORDSET tags) along with recordset "drilldowns" to access the XML data in exactly the same manner as it accesses application specific information. The RECORDSET tags are nested within other RECORDSET tags to provide hierarchical drilldown access into the XML data file structures.

Please refer to the XMLDATA tag, IDE Manual, and installation supplied document "FinerEdge Publisher XML Data Tutorial" for more information on this subject.

Standard XML Data types supported:

The FinerEdge Publisher XML data implementation normally interprets all XML data as string values unless XML data types are used within the XML data file. The built-in FinerEdge Publisher functions can also convert most types of XML data into another data type if desired.

The XML data types are specified by the following attribute names:

dt = "<value>" or

dt:dt = "<value>" or

<any name>:dt = "<value>"

The <value> shown above are interpreted as follows (any mnemonic not listed below is automatically interpreted as a string):

"boolean", "int" -

A FinerEdge Publisher whole number variable.

"number", "float", "decimal", "fixed" -

A FinerEdge Publisher floating point number variable.

"date" -

A date value that is translated into a FinerEdge Publisher number variable. If the XML data contains a user defined delimiter character, it's interpreted according to FinerEdge Publisher conversion rules (otherwise, the date must be in the XML date format of "YYYYMMDD").

"time" -

A time value that is translated into a FinerEdge Publisher number variable and interpreted according to FinerEdge Publisher conversion rules.

Please refer to the FinerEdge Publisher XML Data Tutorial and the example XML data file "XMLTest.xml" for more information on this subject.

» Back to the Table of Contents. «

Chapter 7 - FPWriter, FPWriterNET, and FPServer

Overview

Prior to referring to this chapter, it is presumed that the individual has read and understood the chapter "Application Data Interface". The chapter "Application Data Interface" gives a detailed explanation of the interaction between an application, documents, and FinerEdge Publisher in creating and populating external variables.

This chapter describes the properties, methods, and events for the FPWriter, FPWriterNET, and FPServer interfaces. The FPWriter and FPWriterNET interfaces enable an application to view FinerEdge Publisher documents from within the application in addition to generating all supported cross-media outputs. The FPWriter interface is an ActiveX control while the FPWriterNET interface is a .NET assembly Windows Form Control.

A standard control panel is built into the FPWriter and FPWriterNET interfaces that allow an individual to position the document, zoom in and out, etc. The panel can be positioned at the top of the view (i.e., prior to the document viewing area) or at the bottom of the view (i.e., after the document viewing area). In addition, an individual may decide to not show the panel at all. In this case, the FPWriter and FPWriterNET interfaces have supporting properties, methods, and events that allow a person to design their own control panel that, in turn, calls the applicable interfaces to perform the same actions as the built-in control panel.

The FPServer interface is an Automation Server that has a dual implementation, which supports the IDispatch interface (i.e., late binding) for VBScript and JScript compatibility. The FPServer interface supports all FinerEdge Publisher functionality except the built-in document viewer and event facilities. In addition to the database query and XML data interfaces, initial application variables can be set from VBScript and JScript applications by calling the standard FinerEdge Publisher "SetVar..." methods.

A number of methods and events deal specifically with external application data that is made available to a document. An individual can decide what application data will be made available to the document and also how the application data is accessed and formatted. The data is presented to the document in the form of external variables. External variables are cached in FinerEdge Publisher so that a document author can repeatedly utilize them without refetching the data. One-to-many relationships (i.e., "drilldowns") are also an integral part of the FinerEdge Publisher application data interface and may be nested to any degree required.

» Back to the Table of Contents. «

AppendRecord (FPWriter,FPWriterNET)

C#:

void AppendRecord()

Visual Basic:

Sub AppendRecord()

Return value:

None.

Parameters:

None.

Description:

This method should only be called while processing the InitRecord event. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

While handling the InitRecord event for a multiple-record recordset, the AppendRecord method appends a new record to the currently defined recordset. One or more calls to this method are normally performed within the InitRecord event.

The records are appended to the recordset starting with a logical record of 1 (i.e., as referred to by the document). For each record appended to the recordset, one or more subsequent calls to the AppendRecordParam method can be performed to supply a number of "keys" for the application to fetch the appropriate record during the GetRecord event.

» Back to the Table of Contents. «

AppendRecordParam (FPWriter,FPWriterNET)

C#:

void AppendRecordParam(String strKey,
String strValue)

Visual Basic:

Sub AppendRecordParam(ByVal strKey As String,
ByVal strValue As String)

Return value:

None.

Parameters:

strKey	An application defined "key" that is recognized during the GetRecord event.
strValue	An application defined "value" that is used during the GetRecord event to fetch the proper record.

Description:

This method should only be called while processing the InitRecord event. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

Following a call to the AppendRecord method, one or more calls to AppendRecordParam are performed by the application to supply a number of "keys" for the application to fetch the appropriate record during the GetRecord event. The FindParam or GetParam methods are used to retrieve the application defined "key" and "value" pairs during the GetRecord event.

In a relational database application, multiple-record recordsets can usually be retrieved during the GetRecord event by storing their respective Identity or Counter fields with a single call to the AppendRecordParam method for each record requested.

» Back to the Table of Contents. «

AppendVariable (FPWriter,FPWriterNET)

C#:

bool AppendVariable(String strRSName,
String strName,
String strDesc)

Visual Basic:

Function AppendVariable(ByVal strRSName As String,
ByVal strName As String,
ByVal strDesc As String) As Boolean

Return value:

A "true" value returned by this method indicates that the variable was successfully created. In contrast, a "false" value indicates that a variable with the same name already exists.

Parameters:

strRSName	The name of the recordset that this variable is a part of (underscore characters cannot be used in the recordset name). If the name of the application defined recordset is not known, a new recordset is automatically established for the variable by FinerEdge Publisher.
strName	The name of the external variable that is a part of the previously supplied recordset name (underscore characters can be used in the variable name). If the name of the recordset is "GenInfo" and the variable name is "IntRate", the external variable would be constructed and known to the document as: "@GenInfo_IntRate".
strDesc	A optional description of the external variable currently being defined. The variable name and its description is displayed to the document author(s) while in the expression editor of the FinerEdge Publisher IDE.

Description:

This method should only be called while processing the InitDocument event. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

During the InitDocument event, an application must define an external variable for each piece of information it wishes to expose to the application by calling the AppendVariable method.

» Back to the Table of Contents. «

Catalog (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

The Catalog property gets or sets the name of the catalog file. This property must be set prior to using any of the "Create..." methods (i.e., FinerEdge Publisher always employs a catalog while processing documents). Different groups of documents may use different catalog files or all documents may use the same catalog file.

Catalog files can be created and modified from the FinerEdge Publisher Integrated Development Environment (IDE).

» Back to the Table of Contents. «

Clear (FPWriter,FPWriterNET,FPServer)

C#:

bool Clear()

Visual Basic:

Function Clear() As Boolean

Return value:

A "true" value returned by this method indicates that the Clear method was successful.

Parameters:

None.

Description:

The Clear method can be called to discard any queued external variables (i.e., variables that are automatically created during document initialization).

» Back to the Table of Contents. «

Close (FPWriter,FPWriterNET,FPServer)

C#:

bool Close()

Visual Basic:

Function Close() As Boolean

Return value:

A "true" value returned by this method indicates that the Close method was successful and the form can unload (if applicable).

Parameters:

None.

Description:

This Close method explicitly causes all resources and the temporary file used by a document to be discarded and removed. In contrast, when a form is unloaded all resources and the temporary file are implicitly discarded and removed.

» Back to the Table of Contents. «

CloseDocument (FPWriter,FPWriterNET)

C#:

void CloseDocument()

Visual Basic:

Sub CloseDocument()

Parameters:

None.

Description:

The "CloseDocument" Program event can be used to close or discard any document level resources in the calling application or to call the RefSearch and RefGet methods after the reference table has been fully populated.

» Back to the Table of Contents. «

CloseRecord (FPWriter,FPWriterNET)

C#:

void CloseRecord(String strRSname)

Visual Basic:

Sub CloseRecord(ByVal strRSname As String)

Parameters:

strRSname	A <string> that specifies the name of the application defined recordset that is currently being closed.

Description:

The "CloseRecord" Program event can be used to close or discard resources such as database recordsets in the calling application.

» Back to the Table of Contents. «

ControlPanel (FPWriter,FPWriterNET)

Integer, Get/Set

Description:

This property gets or sets the visibility of the FPWriter built-in control panel. The control panel allows a user to position the document, zoom in and out, etc. An individual may choose to provide the functionality of the panel with their own controls by interfacing them with the appropriate FPWriter properties, methods, and events.

The ControlPanel property may be set to one of the following values:

0	Do not display the control panel.
1	Display the control panel at the top of the control (default).
2	Display the control panel at the bottom of the control.

» Back to the Table of Contents. «

CreateDocument (FPWriter,FPWriterNET,FPServer)

C#:

void CreateDocument()

Visual Basic:

Sub CreateDocument()

Return value:

None.

Parameters:

None.

Description:

The CreateDocument method processes a document and creates a resulting file (known internally by FinerEdge Publisher). The resulting file is subsequently used by one or more "Generate..." methods to output the document in various formats.

All application interaction, processing, and formatting of a document are accomplished by this method. The "Error" property and "GetErrorText" methods should be checked following a call to this method. In addition, the "DocCreated" property can also be checked prior to calling any of the "Generate..." methods.

» Back to the Table of Contents. «

CreateHTML (FPWriter,FPWriterNET,FPServer)

C#:

void CreateHTML()

Visual Basic:

Sub CreateHTML()

Return value:

None.

Parameters:

None.

Description:

The "CreateHTML" method processes a document and creates an XHTML file representing the FinerEdge Publisher document. The "Error" property and "GetErrorText" methods should be checked following a call to this method. The property "ResultFile" must be set to name the resulting XHTML file. By convention, the resulting file name should have an extension of "htm" or "html".

With few exceptions, no headers, footers, or page breaks are included in the resulting file. All external variables and conditional processing are resolved prior to creating the HTML file. DIV, SPAN, and TABLE tags are translated into their corresponding HTML equivalents.

If a header or footer is active with a type of "FIRST" or "ALL", it's contents will be output at the beginning or end of the XHTML resulting file respectively surrounded by a DIV tag with the applicable id, class, and style attributes assigned. Please refer to the PAGEAREA tag for additional information.

» Back to the Table of Contents. «

CreatePageBox (FPWriter,FPWriterNET)

C#:

void CreatePageBox()

Visual Basic:

Sub CreatePageBox()

Return value:

None.

Parameters:

None.

Description:

This method quickly determines the page specifications for a particular document. Because the PAGEBOX tag should be contained in the document entity, no other module entities are read or processed by this method. In addition, after the PAGEBOX tag is seen and the page specifications are determined, document processing is discontinued. No document output is generated by this method.

Following a call to this method, the GetPageBox method may be called to obtain a document's page specifications. A PAGEBOX tag within a document initializes the page specifications. In addition, the values of the PAGEBOX tag can also be based upon conditional processing to adjust paper size, margins, etc.

An issue arises from the use of conditional processing to adjust a document's page specifications. That is, a user printing a document may have a printer with a single paper bin that is, for example, only loaded with either letter size or legal size paper at any one point in time. In order to print a group of conditional documents at one time that utilize the same paper sizes, an application needs to quickly ascertain this information prior to any of the documents actually being printed.

By calling the CreatePageBox and GetPageBox methods for each document within a group of documents, an application can quickly determine the paper sizes that will be required for each conditional document. The documents and corresponding paper sizes can be subsequently displayed to the user. The user can then select and print all documents that have the same paper sizes at one time.

» Back to the Table of Contents. «

CreateRTF (FPWriter,FPWriterNET,FPServer)

C#:

void CreateRTF()

Visual Basic:

Sub CreateRTF()

Return value:

None.

Parameters:

None.

Description:

The "CreateRTF" method processes a document and creates a Rich Text Format (RTF) file representing the FinerEdge Publisher document. The "Error" property and "GetErrorText" methods should be checked following a call to this method. The property "ResultFile" must be set to name the resulting RTF file. By convention, the resulting file name should have an extension of "rtf".

» Back to the Table of Contents. «

CreateText (FPWriter,FPWriterNET,FPServer)

C#:

void CreateText()

Visual Basic:

Sub CreateText()

Return value:

None.

Parameters:

None.

Description:

The "CreateText" method processes a document and creates a Text file representing the FinerEdge Publisher document. The "Error" property and "GetErrorText" methods should be checked following a call to this method. The property "ResultFile" must be set to name the resulting Text file. By convention, the resulting file name should have an extension of "txt".

All resolved text fragments are assembled from the document stream and written to the file name designated by the ResultFile property. However, no style information or page-relative information is output to the resulting file.

» Back to the Table of Contents. «

CurrencyDelim (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

Sets or gets the currency delimiter that is used in various FinerEdge Publisher functions. The default value is the "$" character.

» Back to the Table of Contents. «

DateDelim (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

Sets or gets the date delimiter that is used in various FinerEdge Publisher functions. The default value is the "/" character.

» Back to the Table of Contents. «

DateFormat (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

This property gets or sets the date format that is used in various FinerEdge Publisher functions. The DateFormat property may be set to one of the following values:

us	Use the user specified date.
mm	Use MM/DD/YY date.
dd	Use DD/MM/YY date.
yy	Use YY/MM/DD date.
jj	Use YY/DDD Julian date.
nn	Use straight number of days.
cm	Use MM/DD/YYYY date (default).
cd	Use DD/MM/YYYY date.
cy	Use YYYY/MM/DD date.
cj	Use YYYY/DDD Julian date.

» Back to the Table of Contents. «

DecimalDelim (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

This property gets or sets the decimal point delimiter that is used in various FinerEdge Publisher functions. The default value is the "." character.

» Back to the Table of Contents. «

DocCreated (FPWriter,FPWriterNET,FPServer)

Boolean, Get only

Description:

Gets the status of the resulting document following a call to the "CreateDocument" method. If "true", this property indicates that a resulting document has been successfully created and is available for the "Generate..." methods.

» Back to the Table of Contents. «

DocCreatedVal (FPServer)

Integer, Get only

Description:

Gets the status of the resulting document following a call to the "CreateDocument" method. When set to a value of 1, this property indicates that a resulting document has been successfully created and is available for the "Generate..." methods. A value of 0 returned by this property indicates that a resulting document has not been successfully created.

» Back to the Table of Contents. «

Document/DocName (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

This property gets or sets the name of the current FinerEdge Publisher document and must be set prior to using any of the "Create..." methods. The property DocName can be used as a synonym for Document.

» Back to the Table of Contents. «

Error (FPWriter,FPWriterNET,FPServer)

Boolean, Get only

Description:

Gets the status of the error flag for the last "Create..." method called. If a value of "true" is returned by this property for the FPWriter, a subsequent call to the "GetErrorText" method retrieves additional information regarding the error. If a value of "true" is returned by this property for the FPServer, a subsequent call to the "GetError..." properties can be made to retrieve additional information regarding the error. A value of "false" returned by this property indicates that the last "Create..." method completed successfully.

Since the value of this property is reset at the beginning of each method call, the "DocCreated" property should be used to determine if a resulting document was successfully created and is available to the "Generate..." methods.

» Back to the Table of Contents. «

ErrorVal (FPServer)

Boolean, Get only

Description:

Gets the status of the error flag for the last "Create..." method called. When set to a value of 1, a subsequent call to the "GetError..." properties can be made to retrieve additional information regarding the error. A value of 0 returned by this property indicates that the last "Create..." method completed successfully.

Since the value of this property is reset at the beginning of each method call, the "DocCreated" property should be used to determine if a resulting document was successfully created and is available to the "Generate..." methods.

» Back to the Table of Contents. «

FindParam (FPWriter,FPWriterNET)

C#:

bool FindParam(String strKey,
String strValue)

Visual Basic:

Function FindParam(ByVal strKey As String,
strValue As String) As Boolean

Return value:

A "true" value returned by this method indicates that the parameter "key" was found. In contrast, a "false" value indicates that the parameter "key" was not found.

Parameters:

strKey	The application defined "key" to fetch.
strValue	The returned application defined "value" corresponding to the "key".

Description:

This method should only be called while processing the InitRecord and GetRecord events. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

When called while processing the InitRecord or GetRecord events, this method returns the parameters that were optionally set by a document's RECORDSET tag. However, if this method is called while processing the GetRecord event for a multiple-record recordset, the parameters are returned that were set by the application with the AppendRecordParam method in the InitRecord event. In this case, the parameters refer to a specific physical record corresponding to a logical record number requested by the document.

» Back to the Table of Contents. «

FireMark (FPWriter,FPWriterNET)

Integer, Get/Set

Description:

The "FireMark" property controls when the Mark event is fired as follows:

0	Fire the Mark event for all MARK tags (default).
1	Fire the Mark event for first MARK tag on each page.
2	Fire the Mark event for last MARK tag on each page.
3	Fire the Mark event for first and last MARK tag on each page.

If no MARK tag(s) are present for a page, then no Mark events will be fired. However, if the "FireMark" property is set to 3 and only one MARK tag exists on a particular page, then two Mark events will be fired on the same MARK tag which represents the first and last MARK tag on that page.

» Back to the Table of Contents. «

GeneratePDF (FPWriter,FPWriterNET,FPServer)

C#:

void GeneratePDF(String strOptions)

Visual Basic:

Sub GeneratePDF(ByVal strOptions As String)

Return value:

None.

Parameters:

strOptions

[ <keyword> = <value> ]...

Version	1.2 \| 1.3 \| 1.4 \| 1.5 \| 1.6 \| 1.7 (Default: 1.7) The PDF version is written into the header portion of the resulting PDF file. In addition, if the PDF version is greater than or equal to 1.3, PageLabels are also included in the resulting PDF file. PageLabels allow PDF viewers to display a starting page number greater than one. This is especially convenient for a user when viewing files that have been split into segments.
OPI	disable \| enable \| explicit When OPI is "disable", no OPI instructions are output regardless of the setting of the OPI style property. When OPI is "enable", OPI instructions are output if the value of an element's OPI style property is "true". However if OPI is "explicit", OPI instructions are output for all applicable elements regardless of the setting of the OPI style property.
OPIOnly	true \| false (Default: false) When OPIonly is set to "true", OPI instructions will be output for applicable images without "preview" images (i.e., the backgrounds will show instead). When OPIonly is "false", preview images are output in a normal manner with OPI instructions.

Description:

The GeneratePDF method generates a PDF file that represents the FinerEdge Publisher document. A prior call to the CreateDocument method must have been successfully performed (although multiple "Generate..." methods can be called following a single successful CreateDocument call). In addition, this method must only be called if the DocCreated property returns a value of "true". The property ResultFile must be set to name the resulting PDF file. By convention, the resulting file should have an extension of "pdf".

» Back to the Table of Contents. «

GeneratePostScript (FPWriter,FPWriterNET,FPServer)

C#:

void GeneratePostScript(String strOptions)

Visual Basic:

Sub GeneratePostScript(ByVal strOptions As String)

Return value:

None.

Parameters:

strOptions

[ <keyword> = <value> ]...

Version	2 \| 3 (Default: 3) The PostScript version is written into the header portion of the resulting PostScript file. In addition, if the PostScript version is greater than or equal to 3, all embedded TrueType fonts, Type 1 fonts, and in-line images are encoded using the "Flate" filter for optimum data compression.
OPI	disable \| enable \| explicit When OPI is "disable", no OPI instructions are output regardless of the setting of the OPI style property. When OPI is "enable", OPI instructions are output if the value of an element's OPI style property is "true". However if OPI is "explicit", OPI instructions are output for all applicable elements regardless of the setting of the OPI style property.
OPIOnly	true \| false (Default: false) When OPIonly is set to "true", OPI instructions will be output for applicable images without "preview" images (i.e., the backgrounds will show instead). When OPIonly is "false", preview images are output in a normal manner with OPI instructions.

Description:

The GeneratePostScript method generates a PostScript file that represents the FinerEdge Publisher document. A prior call to the CreateDocument method must have been successfully performed (although multiple "Generate..." methods can be called following a single successful CreateDocument call). In addition, this method must only be called if the DocCreated property returns a value of "true". The property ResultFile must be set to name the resulting PostScript file. By convention, the resulting file should have an extension of "ps".

» Back to the Table of Contents. «

GeneratePrint (FPWriter,FPWriterNET,FPServer)

C#:

void GeneratePrint()

Visual Basic:

Sub GeneratePrint()

Return value:

None.

Parameters:

None.

Description:

The GeneratePrint method directly prints a FinerEdge Publisher document to a locally known or network printer device. A prior call to the CreateDocument method must have been successfully performed (although multiple "Generate..." methods can be called following a single successful CreateDocument call). In addition, this method must only be called if the DocCreated property returns a value of "true".

If the property "Media" is set to a locally known or network printer device, the document is directly printed to that device without displaying a Windows printer dialog box. However, if the property "Media" is not set, the standard Windows printer dialog box is first displayed to the user prior to printing the document.

» Back to the Table of Contents. «

GenerateView (FPWriter,FPWriterNET)

C#:

void GenerateView()

Visual Basic:

Sub GenerateView()

Return value:

None.

Parameters:

None.

Description:

The GenerateView method displays the FinerEdge Publisher document in the FPWriter "viewer" window. A prior call to the CreateDocument method must have been successfully performed (although multiple "Generate..." methods can be called following a single successful CreateDocument call). In addition, this method must only be called if the DocCreated property returns a value of "true".

» Back to the Table of Contents. «

GenerateXPS (FPWriter,FPWriterNET,FPServer)

C#:

void GenerateXPS(String strOptions)

Visual Basic:

Sub GenerateXPS(ByVal strOptions As String)

Return value:

None.

Parameters:

strOptions

[ <keyword> = <value> ]...

Version	1.0 (Default: 1.0) The XPS version is used to control XPS output.

Description:

The GenerateXPS method generates an XPS file that represents the FinerEdge Publisher document. A prior call to the CreateDocument method must have been successfully performed (although multiple "Generate..." methods can be called following a single successful CreateDocument call). In addition, this method must only be called if the DocCreated property returns a value of "true". The property ResultFile must be set to name the resulting XPS file. By convention, the resulting file should have an extension of "xps".

» Back to the Table of Contents. «

GetErrorEntity (FPServer)

String, Get only

Description:

Returns the entity's name where the error occurred.

» Back to the Table of Contents. «

GetErrorFile (FPServer)

String, Get only

Description:

Returns the entity's file where the error occurred.

» Back to the Table of Contents. «

GetErrorLine (FPServer)

Integer, Get only

Description:

Returns the line number where the error occurred (relative to one).

» Back to the Table of Contents. «

GetErrorCol (FPServer)

Integer, Get only

Description:

Returns the column number where the error occurred (relative to one).

» Back to the Table of Contents. «

GetErrorMsg (FPServer)

String, Get only

Description:

Returns a descriptive text message for the error.

» Back to the Table of Contents. «

GetErrorText (FPWriter,FPWriterNET)

C#:

void GetErrorText(ref String strEntityName,
   ref String strEntityFile,
   ref int intLine,
   ref int intCol,
   ref String strErrorText)

Visual Basic:

Sub GetErrorText(strEntityName As String,
   strEntityFile As String,
   intLine As Integer,
   intCol as Integer,
   strErrorText As String)

Return value:

None.

Parameters:

strEntityName	The entity name that the error occurred in.
strEntityFile	The file name that the error occurred in.
intLine	The line number (relative to one) within the entity where the error occurred.
intCol	The column number (relative to one) within the entity where the error occurred.
strErrorText	The error message may be up to three lines separated by a carriage return character. In addition, the error message should be displayed using a "fixed" font (i.e., not a proportionally spaced font).

Description:

Following a "Create..." method call, the "Error" property should be checked for a value of "true" to determine if an error has occurred ("false" implies that no error occurred during the "Create..." method call). If the "Error" property is "true", additional information regarding the error may be obtained by calling the GetErrorText method.

The error information returned by this method may be subsequently utilized by an application to display error text to the user, open the entity file and position to the line and column of the error, or both. In many cases only the entity name and file, the position of the error, and the error text is displayed to the user.

» Back to the Table of Contents. «

GetPageBox (FPWriter,FPWriterNET)

C#:

void GetPageBox(ref String strPaperName,
   ref int intPaperType,
   ref int intPaperWidth,
   ref int intPaperHeight,
   ref int intOrientation,
   ref int intMarginTop,
   ref int intMarginRight,
   ref int intMarginBottom,
   ref int intMarginLeft,
   ref int intGutter,
   ref int intPageSegment,
   ref int intPageOffset,
   ref String strMedia)

Visual Basic:

Sub GetPageBox(strPaperName As String,
   intPaperType As Integer,
   intPaperWidth As Integer,
   intPaperHeight As Integer,
   intOrientation As Integer,
   intMarginTop As Integer,
   intMarginRight As Integer,
   intMarginBottom As Integer,
   intMarginLeft As Integer,
   intGutter As Integer,
   intPageSegment As Integer,
   intPageOffset As Integer,
   strMedia As String)

Return value:

None.

Parameters:

strPaperName	The name of the paper size required by the document (i.e., Letter, etc.).
intPaperType	The Windows defined number that corresponds to the previously mentioned paper size name.
intPaperWidth	The width of the paper in Twips (i.e., 1/1440 of an inch).
intPaperHeight	The height of the paper in Twips (i.e., 1/1440 of an inch).
intOrientation	The orientation of the printed document (0=Portrait, 1=Landscape).
intMarginTop	The top margin of the entire document in Twips (i.e., 1/1440 of an inch).
intMarginRight	The right margin of the entire document in Twips (i.e., 1/1440 of an inch).
intMarginBottom	The bottom margin of the entire document in Twips (i.e., 1/1440 of an inch).
intMarginLeft	The left margin of the entire document in Twips (i.e., 1/1440 of an inch).
intGutter	Returns the optional additional left margin for odd pages and right margin for even pages in Twips (i.e., 1/1440 of an inch). The gutter margin is applied inside of the normal page margins and outside of the page areas.
intPageSegment	Returns when the PDF and PostScript generations are to be segmented into multiple output files. This value can also be set during document processing.
intPageOffset	Returns where page numbering begins in a document. This value can also be set during document processing.
strMedia	The optional printer device where the document will be printed.

Description:

Following a call to a "Create..." method, the GetPageBox method may be called to obtain a document's page specifications. A PAGEBOX tag within a document initializes the page specifications. In addition, the values of the PAGEBOX tag can be based upon conditional processing to adjust paper size, margins, etc.

Please refer to the CreatePageBox method in this chapter for more information on this topic. Also, please refer to the PAGEBOX tag for a list of the available paper sizes.

» Back to the Table of Contents. «

GetParam (FPWriter,FPWriterNET)

C#:

bool GetParam(int intIndex,
ref String strKey,
ref String strValue)

Visual Basic:

Function GetParam(ByVal intIndex As Integer,
strKey As String,
strValue As String) As Boolean

Return value:

A "true" value returned by this method indicates that a parameter was retrieved. In contrast, a "false" value indicates that a parameter was not retrieved.

Parameters:

intIndex	An index value that corresponds to the "key" and "value" pair to be returned (relative to 1).
strKey	The returned application defined "key".
strValue	The returned application defined "value" corresponding to the "key".

Description:

GetRecord (FPWriter,FPWriterNET)

C#:

void GetParam(String strRSname)

Visual Basic:

Sub GetRecord(ByVal strRSname As String)

Parameters:

strRSname	A <string> that specifies the name of the application defined recordset that is currently being processed.

Description:

The GetRecord event signals the application to fetch a recordset's data and assign the variables of the recordset using the SetVarDate, SetVarDouble, SetVarLong, SetVarString, and SetVarTime methods. For a detailed explanation of the use of this event, please refer to the chapter "Application Data Interface".

All of the variables of the recordset, as defined by the application, should be explicitly assigned values even if they are only set to zero or empty strings. If not done, any variables of the recordset that were not explicitly assigned values are automatically set to be a type of <number>s with a value of 0. In general, each time this event is called for a particular recordset, the variables of that recordset should always be assigned the same types (i.e., <number>, <float>, or <string>).

For a single-record recordset, the FindParam and GetParam methods are be used to fetch any optional parameters that were set via the document's RECORDSET tag. However, for a multiple-record recordset, the FindParam and GetParam methods are used to fetch the parameters that were set by the application during the InitRecord event for this recordset.

In the multiple-record case, the application assigned parameters indicate how to fetch the physical record corresponding to the logical record being requested by the document through the RECORDSET tag.

» Back to the Table of Contents. «

InitDocument (FPWriter,FPWriterNET)

C#:

void InitDocument(String strMainName)

Visual Basic:

Sub InitDocument(ByVal strMainName As String)

Parameters:

strMainName	A <string> that corresponds to the name of the main METHOD tag in the document. This name can be used by the application to perform special processing for specifically named documents or even types of documents if desired.

Description:

The InitDocument event signals the application to create all of the external variables for each recordset as well as optionally populate the holiday table. Both the external variables and their respective recordsets are created with the AppendVariable method. The optional holiday table is populated with the LoadHoliday method.

» Back to the Table of Contents. «

InitRecord (FPWriter,FPWriterNET)

C#:

void InitRecord(String strRSname)

Visual Basic:

Sub InitRecord(ByVal strRSname As String)

Parameters:

strRSname	A <string> that specifies the name of the application defined recordset that is currently being processed.

Description:

The InitRecord event signals the application to assign parameters that corresponds to each record requested by a document's RECORDSET tag. This event is only called for a multiple-record recordset. For a detailed explanation of the use of this event, please refer to the chapter "Application Data Interface".

The FindParam and GetParam methods are used to fetch any optional parameters that were set via a document's RECORDSET tag. Following that, uniquely identifying values (e.g., a relational database table's Identity or Counter column) for each physical record can be fetched by the application and assigned to each logical record via the AppendRecord and AppendRecordParam methods.

» Back to the Table of Contents. «

LoadHoliday (FPWriter,FPWriterNET,FPServer)

C#:

void LoadHoliday(String strDate)

Visual Basic:

Sub LoadHoliday(ByVal strDate As String)

Return value:

None.

Parameters:

strDate	The externally formatted date to be appended into the holiday table. This parameter must be in the format specified by the "DateFormat" property.

Description:

This method should normally only be called while processing the InitDocument event. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The optional "LoadHoliday" method appends a date corresponding to a holiday into the internal FinerEdge Publisher holiday table. If the holiday table is used, all applicable holiday dates should be loaded into the table within the InitDocument event. Loaded holiday dates affect FinerEdge Publisher date calculations (please refer to the "date" function for more information).

» Back to the Table of Contents. «

Mark (FPWriter,FPWriterNET)

C#:

void Mark(int intType,
   String strText1,
   String strText2,
   String strText3)

Visual Basic:

Sub Mark(ByVal intType As Integer,
   ByVal strText1 As String,
   ByVal strText2 As String,
   ByVal strText3 As String)

Parameters:

intType	The type of the mark event (see below).
strText1, strText2, strText3	String parameters that vary in content based upon the type of the mark event.

Description:

When the MARK tag is encountered in a document, a Mark event is fired. The Mark event may also be fired implicitly for status updates while processing a document. The first parameter determines the type of the mark event as follows:

0 -

Mark "Fire" events (i.e., a "type" value of "Fire"). In this case strText1 contains the page number where the MARK tag was seen while rendering the document, whereas strText2 contains the result of the MARK tag's "expr" attribute.

1 -

Document processing events. In this case strText1 contains the percent of processing that has been completed, whereas strText2 contains the result of the MARK tag's "expr" attribute.

2 -

Document rendering events. In this case strText1 contains the percent of rendering that has been completed, whereas strText2 contains the current page number where the rendering event occurred.

3 -

Document generation events. In this case strText1 contains the percent of generation that has been completed, whereas strText2 contains the current page number where the generating event occurred.

11 -

Completion event type 1. An application will always receive this event one time at the end of document processing and document rendering. In this case strText1 contains the number of seconds that have elapsed during document processing, whereas strText2 contains the number of seconds that have elapsed while performing only data access (i.e., data fetching) within document processing. In addition, strText3 contains the number of seconds that have elapsed during document rendering.

12 -

Completion event type 2. An application will always receive this event one time at the end of document generation. In this case strText1 contains the number of seconds that have elapsed while generating the document.

» Back to the Table of Contents. «

Media (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

Gets or sets a string that specifies a printer device which is either local to the machine processing the document or a valid network printing device. This is an optional property that is only used while directly printing a document to a particular device from FinerEdge Publisher.

If this property is set, the standard Windows printer dialog is not displayed to the user (otherwise a standard Windows printer dialog is displayed to the user prior to printing the document). Also, if the string "DEFAULT" is used with the Program property Media, the default printer name for the Windows workstation is used instead.

» Back to the Table of Contents. «

MinHDSpace (FPWriter,FPWriterNET,FPServer)

Integer, Get/Set

Description:

This property specifies the minimum amount of free hard disk space in MBytes that must be present on the local workstation in order to store temporary files utilized during document generation. This property has a default value of 50 MBytes.

If less than the minimum amount of free hard disk space is present on the local workstation, document generation is discontinued along with a descriptive error message.

» Back to the Table of Contents. «

NewPage (FPWriter,FPWriterNET)

C#:

void NewPage(int intPage)

Visual Basic:

Sub NewPage(ByVal intPage As Integer)

Parameters:

intPage	A value that specifies the new page number that is about to be displayed (relative to 1).

Description:

FinerEdge Publisher calls the NewPage event prior to the first page of a document being viewed or just prior to a subsequent new page being displayed. This event is only applicable to the viewer (i.e., printing or generating output formats will not call this event).

Normally, if the FPWriter control panel is being used (default setting), the application need not perform any action when this event is called. However, if the control panel is not being used, an application can make use of this event to update it's own page number display.

» Back to the Table of Contents. «

Page (FPWriter,FPWriterNET)

Integer, Get/Set

Description:

This property gets or sets the page number of the document currently being viewed (relative to 1). This property has no effect on documents being printed or generated for one of the output formats.

When set, the "Page" property causes the indicated page of the currently viewed document to be immediately displayed to the user. In addition the "NewPage" event is fired just prior to the indicated page being displayed in the viewer.

» Back to the Table of Contents. «

Pages (FPWriter,FPWriterNET,FPServer)

Integer, Get only

Description:

Gets the total number of pages in the document.

» Back to the Table of Contents. «

PageEnd (FPWriter,FPWriterNET,FPServer)

Integer, Get/Set

Description:

The PageStart, and PageEnd properties determine the Start and End range of pages in a document. For example, if the PageStart property was set to 3 and the PageEnd property was set to 8, pages 3 through 8 would be rendered. The PageStart and PageEnd values are not with respect to the PageOffset, Page or Pages Program property values.

» Back to the Table of Contents. «

PageHeight (FPWriter,FPWriterNET,FPServer)

Integer, Get only

Description:

Gets the height of the last rendered page in Twips.

» Back to the Table of Contents. «

PageOffset (FPWriter,FPWriterNET,FPServer)

Integer, Get/Set

Description:

The PageOffset property determines where page numbering begins in a document. For example, if the PageOffset property was set to 5, the first page would be displayed as page 5. The PageOffset value is not with respect to the PageStart, PageEnd, Page or Pages Program property values.

The mnemonic PageOffset is also supported as an attribute of the PAGEBOX tag that when utilized overrides the value set by this property.

» Back to the Table of Contents. «

PageSegment (FPWriter,FPWriterNET,FPServer)

Integer, Get/Set

Description:

The PageSegment property determines how PDF and PostScript generation is to occur. If PageSegment is set to a value of zero (default), PDF and PostScript generation results in a single file.

However, if PageSegment is set to a value greater than zero, a new file will result for every PageSegment number of pages with both PDF and PostScript generation. For example, if "PageSegment" is set to a value of 100, a new file is generated every 100 pages. The last file generated may contain less pages than are specified by this property.

When segmenting output, FinerEdge Publisher assigns the individual segmented files according to the following naming convention:

The mnemonic PageSegment is also supported as an attribute of the PAGEBOX tag that when utilized overrides the value set by this property.

» Back to the Table of Contents. «

PageStart (FPWriter,FPWriterNET,FPServer)

Integer, Get/Set

Description:

RefGet (FPWriter,FPWriterNET)

C#:

int RefGet(ref String strRefSearch,
   ref String strRefText,
   ref int intPage,
   ref int intRealPage,
   ref int intOffset)

Visual Basic:

Function RefGet(strRefSearch As String,
   strRefText As String,
   intPage As Integer,
   intRealPage As Integer,
   intOffset As Integer) As Integer

Return value:

The "index" of the found reference or 0 if a reference was not found.

Parameters:

strRefSearch	Returns the value of the "ref-search" property applied to the current reference.
strRefText	Returns the value of the "ref-text" property applied to the current reference.
intPage	Returns the display page number of the current reference.
intRealPage	Returns the real page number of the current reference.
intOffset	Returns the document rendering input file offset value.

Description:

The RefGet function retrieves the item values for the current reference. This method should only be called during the "CloseDocument" event after all references have been accumulated and resolved.

» Back to the Table of Contents. «

RefSearch (FPWriter,FPWriterNET)

C#:

int RefSearch(String strPosition,
   String strPattern,
   String strValue,
   int intOptions)

Visual Basic:

Function RefSearch(ByVal strPosition As String,
   ByVal strPattern As String,
   ByVal strValue as String,
   ByVal intOptions As Integer) As Integer

Return value:

The "index" of the found reference or 0 if a reference was not found.

Parameters:

strPosition	The values "begin", "page-begin-down", "page-begin-down-adjust", "page-begin-up", "page-begin-up-adjust", "page-end-down", "page-end-down-adjust", "page-end-up", "page-end-up-adjust", "next", or "previous".
strPattern	The regular expression or simple search pattern.
strValue	When the parameter strPosition is either "page-begin-down", "page-begin-up", "page-end-down" or "page-end-up" (including the "adjust" suffixes), this parameter specifies a page number. However, if the parameter strPosition is either "next" or "previous", this parameter specifies the number of times the search is repeated with the same parameters.
intOptions	When the value of this parameter is 0, the strPattern parameter is a regular expression. However, if the value of this parameter is 1, the strPattern parameter is a simple pattern (see the "pattern" function for more information).

Description:

The RefSearch function searches and selects a reference in the reference table in preparation for calling the RefGet function to retrieve the information for the specific reference. This method should only be called during the "CloseDocument" event after all references have been accumulated and resolved.

» Back to the Table of Contents. «

ResultFile (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

This property gets or sets the name of the current FinerEdge Publisher result file and must be set prior to using any of the "Create..." methods or "Generate..." methods that require a result file. The meaning of the result file varies depending upon the method used. For example, the "GeneratePDF" method uses this property to name the resulting PDF file. Please refer to the applicable method to determine if ResultFile is required and it's respective meaning.

» Back to the Table of Contents. «

SetVarDate (FPWriter,FPWriterNET,FPServer)

C#:

void SetVarDate(String strName,
String strDate)

Visual Basic:

Sub SetVarDate(ByVal strName As String,
ByVal strDate As String)

Return value:

None.

Parameters:

strKey	The name of an existing external variable (not including the name of the recordset or the preceding "@" character).
strDate	The externally formatted date to be assigned to the variable. This parameter must be in the format specified by the "DateFormat" property.

Description:

This method is normally called while processing the GetRecord event. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The "SetVarDate" method assigns the external variable specified by the first parameter to a <number> type and sets it to the converted value of the second parameter. The external variable must have been previously defined by the AppendVariable method.

» Back to the Table of Contents. «

SetVarDouble (FPWriter,FPWriterNET,FPServer)

C#:

void SetVarDouble(String strName,
double dblValue)

Visual Basic:

Sub SetVarDouble(ByVal strName As String,
ByVal dblValue As Double)

Return value:

None.

Parameters:

strKey	The name of an existing external variable (not including the name of the recordset or the preceding "@" character).
dblValue	The "double" value to be assigned to the external variable.

Description:

SetVarLong (FPWriter,FPWriterNET,FPServer)

C#:

void SetVarLong(String strName,
int intValue)

Visual Basic:

Sub SetVarLong(ByVal strName As String,
ByVal intValue As Integer)

Return value:

None.

Parameters:

strKey	The name of an existing external variable (not including the name of the recordset or the preceding "@" character).
intValue	The "int" value to be assigned to the external variable.

Description:

SetVarString (FPWriter,FPWriterNET,FPServer)

C#:

void SetVarString(String strName,
String strValue)

Visual Basic:

Sub SetVarString(ByVal strName As String,
ByVal strText As String)

Return value:

None.

Parameters:

strKey	The name of an existing external variable (not including the name of the recordset or the preceding "@" character).
strText	The text string to be assigned to the external variable.

Description:

This method is normally called while processing the GetRecord event. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The "SetVarString" method assigns the external variable specified by the first parameter to a <string> type and sets it to the value of the second parameter. The length of the second string parameter should be limited to no more than 4095 characters unless it is to be only output in a document with the VAR tag. Carriage returns, linefeeds, and carriage return/linefeed pairs are interpreted as a "<BR/>" action by the VAR tag.

» Back to the Table of Contents. «

SetVarTime (FPWriter,FPWriterNET,FPServer)

C#:

void SetVarTime(String strName,
String strTime)

Visual Basic:

Sub SetVarTime(ByVal strName As String,
ByVal strTime As String)

Return value:

None.

Parameters:

strKey	The name of an existing external variable (not including the name of the recordset or the preceding "@" character).
strTime	The externally formatted time to be assigned to the variable. This parameter must be in the format specified by the "TimeFormat" property.

Description:

This method is normally called while processing the GetRecord event. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The "SetVarTime" method assigns the external variable specified by the first parameter to a <number> type and sets it to the converted value of the second parameter. The external variable must have been previously defined by the AppendVariable method.

» Back to the Table of Contents. «

ThousandDelim (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

Sets or gets the thousands delimiter that is used in various FinerEdge Publisher functions. The default value is the "," character.

» Back to the Table of Contents. «

TimeDelim (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

Sets or gets the time delimiter that is used in various FinerEdge Publisher functions. The default value is the ":" character.

» Back to the Table of Contents. «

TimeFormat (FPWriter,FPWriterNET,FPServer)

String, Get/Set

Description:

This property gets or sets the time format that is used in various FinerEdge Publisher functions. The TimeFormat property may be set to one of the following values:

us	Use the user specified time.
mm	Use HH:MM 24-hour time.
ss	Use HH:MM:SS 24-hour time.
am	Use HH:MMa/p 12-hour time.
as	Use HH:MM:SSa/p 12-hour time (default).

» Back to the Table of Contents. «

Zoom (FPWriter,FPWriterNET)

Integer, Get/Set

Description:

Gets or sets the zoom factor of the document currently being viewed. This property has no effect on documents being printed or generated for one of the output formats.

When set, the "Zoom" property immediately causes the currently viewed document to be zoomed to the indicated zoom factor and then redisplayed to the user. The zoom factor is a percentage where a value of 100 designates "normal" size (i.e., 100%) and 50 designates ½ the "normal" size (i.e., 50%).

» Back to the Table of Contents. «

Chapter 8 - FPJNI (Java)

Overview

The FinerEdge Publisher Java Native Interface (JNI) or FPJNI was primarily developed for use with server-side Java components (i.e., EJBs, Beans, and Servlets). FPJNI supports all FinerEdge Publisher functionality, including events and document generation cross-media outputs. However, FPJNI does not support directly viewing documents, which is considered to be client functionality.

The FinerEdge Publisher JNI (i.e., "FPJNI.dll") is accessed by creating an instance of the "FPJNIDefs" class located within the supplied file "FPJNIDefs.java". The callback events of the FPJNIDefs class (i.e., InitDocument, InitRecord, GetRecord, and CloseRecord) are supported by an interface class called FPJNIEvents located within the supplied file "FPJNIEvents.java".

» Back to the Table of Contents. «

AppendRecord

void AppendRecord();

Parameters:

None.

Description:

This method should only be called while processing the FPInitRecord interface method. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

While handling the FPInitRecord interface method for a multiple-record recordset, the AppendRecord method appends a new record to the currently defined recordset. One or more calls to this method are usually performed within the FPInitRecord interface method.

The records are appended to the recordset starting from a logical record of 1 (as is known by the document). For each record appended to the recordset, one or more subsequent calls to the AppendRecordParam method are usually performed to supply a number of "keys" for the application to fetch the appropriate record during the FPGetRecord interface method.

» Back to the Table of Contents. «

AppendRecordParam

void AppendRecordParam(String strKey,String strValue);

Parameters:

strKey	An application defined "key" that is recognized during the FPGetRecord interface method.
strValue	An application defined "value" that is used during the FPGetRecord interface method to fetch the proper record.

Description:

This method should only be called while processing the FPInitRecord interface method. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

Following a call to the AppendRecord method, one or more calls to AppendRecordParam are performed by the application to supply a number of "keys" for the application to fetch the appropriate record during the FPGetRecord interface method. The FindParam or GetParam methods are used to retrieve the application defined "key" and "value" pairs during the FPGetRecord interface method.

In a relational database application, multiple-record recordsets can usually be retrieved during the FPGetRecord interface method by storing their respective Identity or Counter fields via a call to the AppendRecordParam method for each record requested.

» Back to the Table of Contents. «

AppendVariable

boolean AppendVariable(String strRSName,String strName);

Parameters:

strRSName	The name of the recordset that this variable is a part of (underscore characters must not be used in the recordset name). If the name of the application defined recordset is not known, a new recordset is automatically established for the variable by FinerEdge Publisher.
strName	The name of the external variable that is a part of the previously supplied recordset name (underscore characters can be used in the variable name). If the name of the recordset is "GenInfo" and the variable name is "IntRate", the external variable would be constructed and known to the document as: "@GenInfo_IntRate".

Description:

A "true" value returned by this method indicates that the variable was successfully created. In contrast, a "false" value indicates that a variable with the same name already exists.

This method should only be called while processing the FPInitDocument interface method. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

During the FPInitDocument interface method, an application must define an external variable for each piece of information it wishes to expose to the application by calling the AppendVariable method.

» Back to the Table of Contents. «

Clear

void Clear();

Parameters:

None.

Description:

Discard any queued external variables (i.e., variables that are automatically created during document initialization).

» Back to the Table of Contents. «

void Close();

Parameters:

None.

Description:

Releases all memory resources allocated during the call to the "CreateDocument" method. Automatically called when a subsequent "CreateDocument" method is called or the calling process is detached from the FPJNI DLL.

» Back to the Table of Contents. «

CreateDocument

void CreateDocument();

Parameters:

None.

Description:

Performs all processing and rendering of a document in preparation for subsequent calls to "GeneratePDF", "GeneratePostScript", "GenerateXPS", and "GeneratePrint".

» Back to the Table of Contents. «

CreateHTML

void CreateHTML();

Parameters:

None.

Description:

Performs all processing and creates a corresponding XHTML file representing the document.

» Back to the Table of Contents. «

CreateRTF

void CreateRTF();

Parameters:

None.

Description:

Performs all processing and creates a corresponding Rich Text Format (RTF) file representing the document.

» Back to the Table of Contents. «

CreateText

void CreateText();

Parameters:

None.

Description:

Processes a document and creates a Text file representing the FinerEdge Publisher document. All resolved text fragments are assembled from the document stream and written to the file name designated by the ResultFile property. However, no style information or pagearea information is output to the resulting file.

» Back to the Table of Contents. «

FindParam

boolean FindParam(String strKey);

Parameters:

strKey	The application defined "key" to fetch.
strValue	The returned application defined "value" corresponding to the "key".

Description:

A "true" value returned by this method indicates that the parameter "key" was found. In contrast, a "false" value indicates that the parameter "key" was not found.

This method should only be called while processing the FPInitRecord or FPGetRecord interface methods. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

When called while processing the FPInitRecord interface method, this method returns the parameters that were optionally set by a document's RECORDSET tag. Alternatively, if this method is called while processing the FPGetRecord interface method for a single-record recordset, the parameters are also returned that were set by the document's RECORDSET tag.

However, if this method is called while processing the FPGetRecord interface method for a multiple-record recordset, the parameters are returned that were set by the application with the AppendRecordParam method in the FPInitRecord interface method. In this case, the parameters refer to a specific physical record that correspond to the logical record number requested by the document.

» Back to the Table of Contents. «

GeneratePDF

void GeneratePDF(String strOptions);

Parameters:

strOptions

Version	1.2 \| 1.3 \| 1.4 \| 1.5 \| 1.6 \| 1.7 (Default: 1.7) The PDF version is written into the header portion of the resulting PDF file. In addition, if the PDF version is greater than or equal to 1.3, PageLabels are also included in the resulting PDF file. PageLabels allow PDF viewers to display a starting page number greater than one. This is especially convenient for a user when viewing files that have been split into segments.
OPI	disable \| enable \| explicit When OPI is "disable", no OPI instructions are output regardless of the setting of the OPI style property. When OPI is "enable", OPI instructions are output if the value of an element's OPI style property is "true". However if OPI is "explicit", OPI instructions are output for all applicable elements regardless of the setting of the OPI style property.
OPIOnly	true \| false (Default: false) Also, when OPIonly is set to "true", OPI instructions will be output for applicable images without "preview" images (i.e., the backgrounds will show instead). When OPIonly is "false", preview images are output in a normal manner with OPI instructions.

Description:

Can be called after a successful call to "CreateDocument" to generate a Portable Document Format (PDF) file.

» Back to the Table of Contents. «

GeneratePostScript

void GeneratePostScript(String strOptions);

Parameters:

strOptions

Version	2 \| 3 (Default: 3) The PostScript version is written into the header portion of the resulting PostScript file. In addition, if the PostScript version is greater than or equal to 3, all embedded TrueType fonts, Type 1 fonts, and in-line images are encoded using the "Flate" filter for optimum data compression.
OPI	disable \| enable \| explicit When OPI is "disable", no OPI instructions are output regardless of the setting of the OPI style property. When OPI is "enable", OPI instructions are output if the value of an element's OPI style property is "true". However if OPI is "explicit", OPI instructions are output for all applicable elements regardless of the setting of the OPI style property.
OPIOnly	true \| false (Default: false) Also, when OPIonly is set to "true", OPI instructions will be output for applicable images without "preview" images (i.e., the backgrounds will show instead). When OPIonly is "false", preview images are output in a normal manner with OPI instructions.

Description:

Can be called after a successful call to "CreateDocument" to generate a PostScript file.

» Back to the Table of Contents. «

GeneratePrint

void GeneratePrint();

Parameters:

None.

Description:

Can be called after a successful call to "CreateDocument" to directly print a document.

» Back to the Table of Contents. «

GenerateXPS

void GenerateXPS(String strOptions);

Parameters:

strOptions

Version	1.0 (Default: 1.0) The XPS version is used to control XPS output.

Description:

Can be called after a successful call to "CreateDocument" to generate an XML Paper Specification (XPS) file.

» Back to the Table of Contents. «

GetCatalog

String GetCatalog();

Parameters:

None.

Description:

Returns the name of the currently set Catalog.

» Back to the Table of Contents. «

GetCurrencyDelim

String GetCurrencyDelim();

Parameters:

None.

Description:

Returns the currency delimiter character.

» Back to the Table of Contents. «

GetDateDelim

String GetDateDelim();

Parameters:

None.

Description:

Returns the date delimiter character.

» Back to the Table of Contents. «

GetDateFormat

String GetDateFormat();

Parameters:

None.

Description:

Returns the date format. For more information, please refer to the FPWriter/FPServer DateFormat property.

» Back to the Table of Contents. «

GetDecimalDelim

String GetDecimalDelim();

Parameters:

None.

Description:

Returns the decimal point delimiter character.

» Back to the Table of Contents. «

GetDocCreated

boolean GetDocCreated();

Parameters:

None.

Description:

Returns "true" if the document was successfully created by a call to "CreateDocument".

» Back to the Table of Contents. «

public native String GetDocName();

GetError

boolean GetError();

Parameters:

None.

Description:

Returns "true" if an error was encountered during the last call to any of the "Create..." or "Generate..." methods. Further information may then be obtained by calling the "GetError..." methods.

» Back to the Table of Contents. «

GetErrorEntity

String GetErrorEntity();

Parameters:

None.

Description:

If "GetError" returns "true", this method returns the name of the entity where the error occurred.

» Back to the Table of Contents. «

GetErrorFile

String GetErrorFile();

Parameters:

None.

Description:

If "GetError" returns "true", this method returns the name of the file where the error occurred.

» Back to the Table of Contents. «

GetErrorLine

long GetErrorLine();

Parameters:

None.

Description:

If "GetError" returns "true", this method returns the line number where the error occurred (relative to 1).

» Back to the Table of Contents. «

GetErrorCol

long GetErrorCol();

Parameters:

None.

Description:

If "GetError" returns "true", this method returns the column number where the error occurred (relative to 1).

» Back to the Table of Contents. «

GetErrorMsg

String GetErrorMsg();

Parameters:

None.

Description:

If "GetError" returns "true", this method returns a message indicating the type of error that occurred.

» Back to the Table of Contents. «

GetMark

int GetMark();

Parameters:

None.

Description:

Returns the currently set mark value (see SetMark for more details).

» Back to the Table of Contents. «

GetMedia

String GetMedia();

Parameters:

None.

Description:

Returns the name of the currently set media device (i.e., the local or network printer name).

» Back to the Table of Contents. «

GetMinHDSpace

long GetMinHDSpace();

Parameters:

None.

Description:

Returns the minimum amount of free hard disk space in MBytes that must be present on the local workstation in order to store temporary files utilized during document generation.

» Back to the Table of Contents. «

GetPageEnd

long GetPageEnd();

Parameters:

None.

Description:

GetPageHeight

long GetPageHeight();

Parameters:

None.

Description:

Returns the height of the last rendered page in Twips.

» Back to the Table of Contents. «

GetPageOffset

long GetPageOffset();

Parameters:

None.

Description:

GetPages

long GetPages();

Parameters:

None.

Description:

Called after a successful call to "CreateDocument" to return the number of pages rendered by the document.

» Back to the Table of Contents. «

GetPageSegment

long GetPageSegment();

Parameters:

None.

Description:

The PageSegment property determines how PDF and PostScript generation is to occur. If PageSegment is set to a new value of zero (default), PDF and PostScript generation results in a single file.

However, if PageSegment is set to a new value greater than zero, a new file will result for every PageSegment number of pages with both PDF and PostScript generation. For example, if "PageSegment" is set to a value of 100, a new file is generated every 100 pages. The last file generated may contain less pages than are specified by this property.

When segmenting output, FinerEdge Publisher assigns the individual segmented files according to the following naming convention:

The mnemonic PageSegment is also supported as an attribute of the PAGEBOX tag that when utilized overrides the value set by this property.

» Back to the Table of Contents. «

GetPageStart

long GetPageStart();

Parameters:

None.

Description:

GetParam

boolean GetParam(int intIndex);

Parameters:

intIndex	An index value that corresponds to the "key" and "value" pair to be returned (relative to 1).

Description:

A "true" value returned by this method indicates that a parameter was retrieved. In contrast, a "false" value indicates that a parameter was not retrieved.

This method should only be called while processing the FPInitRecord or FPGetRecord interface methods. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

When called while processing the FPInitRecord interface method, this method returns the parameters that were optionally set by a document's RECORDSET tag. Alternatively, if this method is called while processing the FPGetRecord interface method for a single-record recordset, the parameters are also returned that were set by the document's RECORDSET tag.

However, if this method is called while processing the FPGetRecord interface method for a multiple-record recordset, the parameters are returned that were set by the application with the AppendRecordParam method in the FPInitRecord interface method. In this case, the parameters refer to a specific physical record that corresponds to the logical record number requested by the document.

» Back to the Table of Contents. «

GetParamKey

String GetParamKey();

Parameters:

None.

Description:

This method should only be called while processing the FPInitRecord or FPGetRecord interface methods. For a detailed explanation of presenting application data to document and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

Following a successful call to either the FindParam or GetParam methods, this method returns the parameter "key" that was found (otherwise an empty string is returned).

» Back to the Table of Contents. «

GetParamValue

String GetParamValue();

Parameters:

None.

Description:

This method should only be called while processing the FPInitRecord or FPGetRecord interface methods. For a detailed explanation of presenting application data to document and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

Following a successful call to either the FindParam or GetParam methods, this method returns the parameter "value" that was found (otherwise an empty string is returned).

» Back to the Table of Contents. «

GetRefSearch

String GetRefSearch();

Parameters:

None.

Description:

This method should only be called during the FPCloseDocument interface method (i.e., after the reference table has been populated). Following a successful call to the RefSearch method, this method returns the search value of the currently found reference.

» Back to the Table of Contents. «

GetRefText

String GetRefText();

Parameters:

None.

Description:

This method should only be called during the FPCloseDocument interface method (i.e., after the reference table has been populated). Following a successful call to the RefSearch method, this method returns the text value of the currently found reference.

» Back to the Table of Contents. «

GetRefPage

long GetRefPage();

Parameters:

None.

Description:

This method should only be called during the FPCloseDocument interface method (i.e., after the reference table has been populated). Following a successful call to the RefSearch method, this method returns the display page number of the currently found reference.

» Back to the Table of Contents. «

GetRefRealPage

long GetRefRealPage();

Parameters:

None.

Description:

This method should only be called during the FPCloseDocument interface method (i.e., after the reference table has been populated). Following a successful call to the RefSearch method, this method returns the real (actual) page number of the currently found reference.

» Back to the Table of Contents. «

GetRefOffset

long GetRefOffset();

Parameters:

None.

Description:

This method should only be called during the FPCloseDocument interface method (i.e., after the reference table has been populated). Following a successful call to the RefSearch method, this method returns the document rendering input file offset value of the reference.

» Back to the Table of Contents. «

GetRefIndex

int GetRefIndex();

Parameters:

None.

Description:

This method should only be called during the FPCloseDocument interface method (i.e., after the reference table has been populated). Following a successful call to the RefSearch method, this method returns the index of the reference starting from 1.

» Back to the Table of Contents. «

GetResult

String GetResult();

Parameters:

None.

Description:

Returns the name of the currently set result file.

» Back to the Table of Contents. «

GetThousandDelim

String GetThousandDelim();

Parameters:

None.

Description:

Returns the thousands delimiter character.

» Back to the Table of Contents. «

GetTimeDelim

String GetTimeDelim();

Parameters:

None.

Description:

Returns the time delimiter character.

» Back to the Table of Contents. «

GetTimeFormat

String GetTimeFormat();

Parameters:

None.

Description:

Returns the time format. For more information, please refer to the FPWriter/FPServer TimeFormat property.

» Back to the Table of Contents. «

LoadHoliday

void LoadHoliday(String strDate);

Parameters:

strDate	The date to load into the holiday table (must be in the format specified by the SetDateFormat method).

Description:

Loads a date into the holiday table for subsequent use with the date function (within a document).

» Back to the Table of Contents. «

RefSearch

int RefSearch(String strPosition,String strPattern,String strValue,int intOptions);

Parameters:

strPosition	The values "begin", "page-begin-down", "page-begin-down-adjust", "page-begin-up", "page-begin-up-adjust", "page-end-down", "page-end-down-adjust", "page-end-up", "page-end-up-adjust", "next", or "previous".
strPattern	The regular expression or simple search pattern.
strValue	When the parameter strPosition is either "page-begin-down", "page-begin-up", "page-end-down" or "page-end-up" (including the "adjust" suffixes), this parameter specifies a page number. However, if the parameter strPosition is either "next" or "previous", this parameter specifies the number of times the search is repeated with the same parameters.
intOptions	When the value of this parameter is 0, the strPattern parameter is a regular expression. However, if the value of this parameter is 1, the strPattern parameter is a simple pattern (see the "pattern" function for more information).

Description:

This method should only be called during the FPCloseDocument interface method (i.e., after the reference table has been populated). The RefSearch function searches and selects a reference in the reference table in preparation for calling the GetRef... functions to retrieve the information for the specific reference. Returns the "index" of the found reference or 0 if a reference was not found.

» Back to the Table of Contents. «

SetCatalog

void SetCatalog(String strCatalog);

Parameters:

strCatalog	The new name of the catalog file to set.

Description:

Sets the catalog to a new file name.

» Back to the Table of Contents. «

SetCurrencyDelim

void SetCurrencyDelim(String strCurrencyDelim);

Parameters:

strCurrencyDelim	The new currency delimiter character to set.

Description:

Sets the currency delimiter character to a new value.

» Back to the Table of Contents. «

SetDateDelim

void SetDateDelim(String strDateDelim);

Parameters:

strDateDelim	The new date delimiter character to set.

Description:

Sets the date delimiter character to a new value.

» Back to the Table of Contents. «

SetDateFormat

void SetDateFormat(String strDateFormat);

Parameters:

strDateFormat	The new date format to set.

Description:

Sets the date format to a new value. For more information, please refer to the FPWriter/FPServer DateFormat property.

» Back to the Table of Contents. «

SetDecimalDelim

void SetDecimalDelim(String strDecimalDelim);

Parameters:

strDecimalDelim	The new decimal delimiter character to set.

Description:

Sets the decimal delimiter character to a new value.

» Back to the Table of Contents. «

SetDocName

void SetDocName(String strDocName);

Parameters:

strDocName	The new FP document name to set.

Description:

Sets the FP document name to a new file name (used by the "Create..." and "Generate..." methods).

» Back to the Table of Contents. «

SetMark

void SetMark(int intMark);

Parameters:

intMark	The new mark value to set.

Description:

Controls when the Mark event is fired as follows:

0	Fire the Mark event for all MARK tags (default).
1	Fire the Mark event for first MARK tag on each page.
2	Fire the Mark event for last MARK tag on each page.
3	Fire the Mark event for first and last MARK tag on each page.

If no MARK tag(s) are present for a page, then no Mark events will be fired. However, if the mark value is set to 3 and only one MARK tag exists on a particular page, then two Mark events will be fired on the same MARK tag, which represents the first and last MARK tag on that page.

» Back to the Table of Contents. «

SetMedia

void SetMedia(String strMedia);

Parameters:

strMedia	The new name of the media to set.

Description:

Sets the media to a new local or network printer name.

» Back to the Table of Contents. «

SetMinHDSpace

void SetMinHDSpace(long lngMinHDSpace);

Parameters:

lngMinHDSpace	The new minimum hard disk space value to set.

Description:

SetPageEnd

void SetPageEnd(long lngPageEnd);

Parameters:

lngPageEnd	The new page end value to set.

Description:

SetPageOffset

void SetPageOffset(long lngPageOffset);

Parameters:

lngPageOffset	The new page offset value to set.

Description:

SetPageSegment

void SetPageSegment(long lngPageSegment);

Parameters:

lngPageSegment	The new page segment value to set.

Description:

The mnemonic PageSegment is also supported as an attribute of the PAGEBOX tag that when utilized overrides the value set by this property.

» Back to the Table of Contents. «

SetPageStart

void SetPageStart(long lngPageStart);

Parameters:

lngPageStart	The new page start value to set.

Description:

SetResult

void SetResult(String strResult);

Parameters:

strResult	The new name of the result file to set.

Description:

Sets the result file name to a new value (used by the "Create..." and "Generate..." methods).

» Back to the Table of Contents. «

SetTimeDelim

void SetTimeDelim(String strTimeDelim);

Parameters:

strTimeDelim	The new time delimiter character to set.

Description:

Sets the time delimiter character to a new value.

» Back to the Table of Contents. «

SetThousandDelim

void SetThousandDelim(String strThousandDelim);

Parameters:

strThousandDelim	The new thousands delimiter character to set.

Description:

Sets the thousands delimiter character to a new value.

» Back to the Table of Contents. «

SetTimeFormat

void SetTimeFormat(String strTimeFormat);

Parameters:

strTimeFormat	The new time format to set.

Description:

Sets the time format to a new value. For more information, please refer to the FPWriter/FPServer TimeFormat property.

» Back to the Table of Contents. «

SetVarLong

void SetVarLong(String strName,long lngValue);

Parameters:

strName	The variable's name within the document (e.g. "@Global_<strName>").
lngValue	The value to assign to the newly created variable.

Description:

Creates a "long" whole number external variable for use with document processing.

» Back to the Table of Contents. «

SetVarDouble

void SetVarDouble(String strName,double dblValue);

Parameters:

strName	The variable's name within the document (e.g. "@Global_<strName>").
dblValue	The value to assign to the newly created variable.

Description:

Creates a "double" floating-point number external variable for use with document processing.

» Back to the Table of Contents. «

SetVarString

void SetVarString(String strName,String strValue);

Parameters:

strName	The variable's name within the document (e.g. "@Global_<strName>").
strValue	The value to assign to the newly created variable.

Description:

Creates a "String" external variable for use with document processing.

» Back to the Table of Contents. «

SetVarDate

void SetVarDate(String strName,String strDate);

Parameters:

strName	The variable's name within the document (e.g. "@Global_<strName>").
strDate	The value to assign to the newly created variable (the date must be in the "cm" format).

Description:

Creates a "long" whole number external variable representing a date in the internal format of "YYYYMMDD" for use with document processing.

» Back to the Table of Contents. «

SetVarTime

void SetVarTime(String strName,String strTime);

Parameters:

strName	The variable's name within the document (e.g. "@Global_<strName>").
strTime	The value to assign to the newly created variable (the time may be in any supported format).

Description:

Creates a "long" whole number external variable representing a time in the internal format of "HHMMSS" for use with document processing.

» Back to the Table of Contents. «

FPCloseDocument (Interface method)

void FPCloseDocument();

Parameters:

None.

Description:

The FPCloseDocument interface method can be used to close or discard any document level resources in the calling application or to call the RefSearch and GetRef... methods after the reference table has been fully populated..

» Back to the Table of Contents. «

FPCloseRecord (Interface method)

void FPCloseRecord(String strRSName);

Parameters:

strRSname	A <string> that specifies the name of the application defined recordset that is currently being closed.

Description:

The FPCloseRecord interface method can be used to close resources such as database recordsets in the calling application.

» Back to the Table of Contents. «

FPGetRecord (Interface method)

void FPGetRecord(String strRSName);

Parameters:

strRSname	A <string> that specifies the name of the application defined recordset that is currently being processed.

Description:

The FPGetRecord interface method signals the application to fetch a recordset's data and assign the variables of the recordset to appropriate values using the SetVarDate, SetVarDouble, SetVarLong, SetVarString, and SetVarTime methods. For a detailed explanation of the use of this interface method, please refer to the chapter "Application Data Interface".

All of the variables of the recordset, as defined by the application, should be explicitly assigned values even if they are simply set to zero or empty strings. If this is not done, any variables of the recordset that were not explicitly assigned values are set to be <number>s with a value of 0. In general, each time this interface method is called for a particular recordset, the variables of that recordset should always be assigned the same types (i.e., <number>, <float>, or <string>).

For a single-record recordset, the FindParam and GetParam methods may be used to fetch any optional parameters that were set via the document's RECORDSET tag. However, for a multiple-record recordset, the FindParam and GetParam methods are used to fetch the parameters that were set by the application during the FPInitRecord interface method for this recordset.

In the multiple-record case, the application assigned parameters indicate to the application how to fetch the physical record that corresponds to the logical record being requested by the document. The parameters returned by FinerEdge Publisher in this interface method are relative to the logical record being requested by the document's RECORDSET tag.

» Back to the Table of Contents. «

FPInitRecord (Interface method)

void FPInitRecord(String strRSName);

Parameters:

strRSname	A <string> that specifies the name of the application defined recordset that is currently being processed.

Description:

The FPInitRecord interface method signals the application to assign parameters that corresponds to each record requested by the document's RECORDSET tag. This interface method is only called for a multiple-record recordset. For a detailed explanation of the use of this interface method, please refer to the chapter "Application Data Interface".

The FindParam and GetParam methods may be used to fetch any optional parameters that were set via the document's RECORDSET tag. Then, uniquely identifying values for each physical record are fetched by the application and assigned to each logical record via the AppendRecord and AppendRecordParam methods.

In the case of a database application, a single Identity or Counter field can usually be employed for each record and assigned to a record parameter with the AppendRecordParam method. As many records as needed may be initialized while processing this interface method. In addition, as many record parameters as needed may be assigned to each record initialized.

» Back to the Table of Contents. «

FPInitDocument (Interface method)

void FPInitDocument(String strRSName);

Parameters:

strMainName	A <string> that corresponds to the name of the main METHOD tag in the document. This name can be used by the application to perform special processing for specifically named documents.

Description:

The FPInitDocument interface method signals the application to create all of the external variables for each recordset as well as optionally populate the holiday table. Both the external variables and their respective recordsets are created with the AppendVariable method. The optional holiday table is populated with the LoadHoliday method.

» Back to the Table of Contents. «

FPMark (Interface method)

void FPMark(int intType, String strText1, String strText2, String strText3);

Parameters:

intType	The type of the mark event (see below).
strText1, strText2, strText3	String parameters that vary in content based upon the type of the mark event.

Description:

Chapter 9 - FPEngine

Overview

The FPEngine is a multi-threaded capable (i.e., thread-safe) Dynamic Link Library (DLL) that implements the major portion of the FinerEdge Publisher functionality including the ability to directly print documents and generate PDF, PostScript, XPS, RTF, XHTML, and Text files from FinerEdge Publisher documents.

All facilities of FinerEdge Publisher including external variables, tags, styles, functions, and expressions are handled by the FPEngine DLL. For example, a process running on a Windows platform can choose to either use the FPWriter or FPServer interface controls, the FPJNI Java interface, or call the entry points of the FPEngine DLL directly.

The FPEngine entry points employ application provided "callback functions" to communicate with the calling process. The programming language of the application must be able to pass "callback functions" in order to utilize the FPCreate function. C++ is an example of the type of language that supports the use of callback functions. The FinerEdge Publisher functions are all exported using standard "C" linkage conventions.

The DLL's library file "FPEngine.lib" is included in the FinerEdge installation to allow direct access to the documented entry points of "FPEngine.dll". In addition, the file "FPEngine.h" is also included in the installation and contains the "C" prototypes for all FPEngine DLL functions.

Note: FPAddThread allocates thread local storage and so must be called prior to calling any functions that use an intThreadID parameter. In addition, FPDelThread must be called after all FinerEdge Publisher processing has been completed to deallocate thread local storage. Failure to call FPDelThread will cause thread local storage to be retained until the process detaches from FPEngine.

» Back to the Table of Contents. «

FPAddThread

int FPAddThread(void)

Return value:

The thread ID that refers to the unique thread local storage allocated in the FPEngine.

Parameters:

None.

Description:

This entry point allocates thread local storage and so must be called prior to calling any functions that use an intThreadID parameter.

» Back to the Table of Contents. «

FPAppendRecord

void FPAppendRecord(int intThreadID)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.

Description:

This entry point should only be called while processing the "initRecord" option of the "callFunction" callback function within the FPCreate entry point. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The FPAppendRecord entry point appends a new record to the currently processed multiple-record recordset. For more information on this topic, please refer to the FPWriter/FPServer method "AppendRecord".

» Back to the Table of Contents. «

FPAppendRecordParam

void FPAppendRecordParam(int intThreadID,const char *name,const char *value)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
name	Sets the key of the parameter that is associated with the current record.
value	Sets the value of the parameter's key that is associated with the current record.

Description:

This entry point should only be called while processing the "initRecord" option of the "callFunction" callback function within the FPCreate entry point. For a detailed explanation of presenting application data to the documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The FPAppendRecordParam entry point appends a new parameter to the current record of the currently processed multiple-record recordset. For more information on this topic, please refer to the FPWriter/FPServer method "AppendRecordParam".

» Back to the Table of Contents. «

FPAppendVariable

int FPAppendVariable(int intThreadID,const char *rsname,const char *name)

Return value:

A value of 1 indicates that the variable was successfully appended to the recordset. A value of 0 indicates that the variable already exists for the recordset.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
rsname	Sets the name of the recordset that the variable is appended to.
name	Sets the name of the variable to be appended to the recordset.

Description:

This entry point should only be called while processing the "initDocument" callback function within the FPCreate entry point. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The FPAppendVariable entry point appends a new external variable into FinerEdge Publisher's symbol table for the indicated recordset. If the indicated recordset is not defined, it is created prior to appending the variable. For more information on this topic, please refer to the FPWriter/FPServer method "AppendVariable".

» Back to the Table of Contents. «

FPClear

void FPClear(int intThreadID)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.

Description:

The FPClear entry point can be called to discard any queued external variables (i.e., variables that are automatically created during document initialization).

» Back to the Table of Contents. «

FPClose

void FPClose(intThreadID)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.

Description:

When the FPCreate entry point is called or a process detaches from the FinerEdge Publisher FPEngine DLL, all currently allocated font, image, catalog, and page resources are automatically released for the last document processed. However, the FPClose entry point can also be called by an application process to immediately release resources for a document after FPCreate and the "FPGenerate..." functions have been called.

For more information on this topic, please refer to the FPWriter/FPServer method "Close".

» Back to the Table of Contents. «

FPCreate

int FPCreate(
   int intThreadID,int mode,int opt,
   const char *catalog,const char *document,
   const char *resultname,const char *options,
   int &errorval,char *entityname,char *entityfile,
   long &linenum,long &colnum,char *errortext,
   char *media,char *pagename,
   int &pagetype,long &pagewidth,
   long &pageheight,int &orientation,
   long &margintop,long &marginright,
   long &marginbottom,long &marginleft,
   long &gutter,long &pagesegment,
   long &pageoffset,long &totalpages,
   long &pageheight,
   void callFunction(int,char *,char *,char *))

Return value:

A value other than 0 indicates that an error has occurred while processing the document (otherwise processing completed successfully). The application can use the errorval, entityname, entityfile, linenum, colnum, and errortext parameters to display additional information regarding the error.

Parameters:

intThreadID

The unique thread ID returned from an initial called to FPAddThread.

mode

Sets the mode for the type of processing that is to occur in this function as follows:

0	Create a normal resulting file used by the "FPGenerate..." functions. Please refer to the FPWriter/FPServer method CreateDocument for additional information.
1	Acquire page specifications (the resultname parameter is not used). Please refer to the FPWriter/FPServer method CreatePageBox for additional information.
2	Create an HTML file representing the document. Please refer to the FPWriter/FPServer method CreateHTML for additional information. FinerEdge Publisher generates strict compliant XHTML for this type of output.
3	Create a Rich Test Format (RTF) file representing the document. Please refer to the FPWriter/FPServer method CreateRTF for additional information.
20	Create a Text file representing the document. Please refer to the FPWriter/FPServer method CreateText for additional information.

opt

0	Call callFunction for all MARK tags (default).
1	Call callFunction for first MARK tag on each page.
2	Call callFunction for last MARK tag on each page.
3	Call callFunction for first and last MARK tag on each page.

catalog

Sets the name of the catalog file to be used with the processing of this document.

document

Sets the name of the FinerEdge Publisher document to be processed.

resultname

Sets the name of the resulting file created by this function.

options

Sets initial values for various date/time formats, assorted delimiters and general options. If this parameter is NULL or an empty string, the internal default values will be used to process the document. However, if the application supplies any optional values, this parameter must be in the format:

<option>: <value> [; <option>: <value> ]...

The following table shows the various options and their respective descriptions:

dateformat	The default date format. Please refer to the FPWriter/FPServer property DateFormat for additional information.
datedelim	The default date delimiter character.
timeformat	The default time format. Please refer to the FPWriter/FPServer property TimeFormat for additional information.
timedelim	The default time delimiter character.
dpdelim	The default decimal point character.
thdelim	The default thousands character.
curdelim	The default currency character.
pagesegment	Determines when the PDF and PostScript generations are to be segmented into multiple output files. If "PageSegment" is set to a value of zero (default), PDF and PostScript generation results in a single file.
pagestart	Determines which page document generation starts. This value is irrespective of the pageoffset value.
pageend	Determines which page document generation ends. This value is irrespective of the pageoffset value.
pageoffset	Determines where page numbering begins in a document. For example, if the "PageOffset" property was set to a value of 5, the first page number would be displayed as page 5.
minhdspace	Specifies the minimum amount of free hard disk space in MBytes that must be present on the local workstation in order to store the temporary file that is created during document generation.

errorval

Returns an internally defined error number that corresponds to the value returned by this function. A value other than 0 indicates that an error has occurred while processing the document (otherwise processing completed successfully).

entityname

If errorval is other than 0, returns the name of the entity where the error occurred.

entityfile

If errorval is other than 0, returns the file of the entity where the error occurred.

linenum

If errorval is other than 0, returns the line number (relative to 1) where the error occurred within the entityfile.

colnum

If errorval is other than 0, returns the column number (relative to 1) where the error occurred.

errortext

If errorval is other than 0, returns the text of the error message. This may be up to three lines each separated by a carriage return character. In addition, the error message should be displayed in a fixed font for formatting purposes.

media

Returns the optional media printing device set by the PAGEBOX tag. This parameter can then be passed directly to the FPGeneratePrint function.

papername

Returns the paper name set by the PAGEBOX tag (e.g., Letter, etc).

papertype

Returns a number corresponding to the Windows paper type.

pagewidth

Returns the page width in Twips (Twip = 1/1440 of an inch).

pageheight

Returns the page height in Twips (Twip = 1/1440 of an inch).

orientation

Returns the orientation of the printed document on the paper (0=Portrait, 1=Landscape).

margintop

Returns the top margin for all pages in Twips (Twip = 1/1440 of an inch).

marginright

Returns the right margin for all pages in Twips (Twip = 1/1440 of an inch).

marginbottom

Returns the bottom margin for all pages in Twips (Twip = 1/1440 of an inch).

marginleft

Returns the left margin for all pages in Twips (Twip = 1/1440 of an inch).

gutter

Returns the optional additional left margin for odd pages and right margin for even pages in Twips (Twip = 1/1440 of an inch). The gutter margin is applied inside of the normal page margins and outside of the page areas.

pagesegment

Returns when the PDF and PostScript generations are to be segmented into multiple output files. This value can also be overridden by the document.

pageoffset

Returns where page numbering begins in a document. This value can also be overridden by a document.

totalpages

Returns the total number of pages in the document.

pageheight

Returns the height of the last page in Twips.

callFunction

1 - initDocument	Char pointer 1 optionally contains the name of the main method. Char pointer 2 optionally contains the name of a FPSQL file referenced from a QUERYDATA tag.
2 - initRecord	Char pointer 1 contains the name of the RecordSet being processed.
3 - getRecord	Char pointer 1 contains the name of the RecordSet being processed.
4 - closeRecord	Char pointer 1 contains the name of the RecordSet being closed.
5 - closeDocument	Allows the calling program a chance to access the complete reference table before it is discarded.
11 - Mark	Char pointer 1 contains the page number of the mark tag. Char pointer 2 contains the evaluated text of the mark tag.
21 - Processing	Char pointer 1 contains the percent processing completion. Char pointer 2 contains the evaluated text of the mark tag.
22 - Rendering	Char pointer 1 contains the percent rendering completion. Char pointer 2 contains the last page number rendered.
23 - Generation	Char pointer 1 contains the percent generation completion. Char pointer 2 contains the last page number generated.
31 - Processing and rendering statistics	Char pointer 1 contains the elapsed time for document processing in seconds. Char pointer 2 contains the elapsed time for just the data access portion of document processing in seconds. Char pointer 3 contains the elapsed time for document rendering in seconds.
32 - Generation statistics	Char pointer 1 contains the elapsed time for document generation in seconds.

Description:

The FPCreate function is the first library entry point that is called to process a FinerEdge Publisher document. This entry point creates a resulting file that is used by the FinerEdge Publisher "FPGenerate..." entry points to produce a number of industry standard output formats.

The FPCreate entry point performs all page formatting and resolves all conditional processing, tags, and style specifications for a FinerEdge Publisher document. The resulting file created by this function contains primitive absolute formatting instructions that is used as input for the FinerEdge Publisher "FPGenerate..." entry points. One or more of the "FPGenerate..." entry points can then be called with the same resulting file created by this function.

The FPCreate entry point communicates with calling applications in order to acquire the external variable descriptions and their respective data. The communication with the application is accomplished through the single callback function "callFunction" that is supplied as a parameter to FPCreate by the application. For a detailed explanation of this facility, please refer to the chapter "Application Data Interface".

» Back to the Table of Contents. «

FPDelThread

void FPDelThread(int intThreadID)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.

Description:

This entry point must be called after all FinerEdge Publisher processing has been completed to deallocate the unique thread local storage. Failure to call FPDelThread will cause thread local storage to be retained until the process detaches from FPEngine.

» Back to the Table of Contents. «

FPFindParam

int FPFindParam(int intThreadID,const char *name,char *value)

Return value:

A value of 1 indicates that the parameter was found. A value of 0 indicates that the parameter was not found.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
name	Sets the name of the parameter key to find.
value	Returns the value of the parameter corresponding to the key.

Description:

This entry point should only be called while processing the "initRecord" or "getRecord" options of the callback function "callFunction" within the FPCreate entry point. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The FPFindParam entry point locates a recordset parameter for the requested record and returns its value to the application. For more information on this topic, please refer to the FPWriter/FPServer method "FindParam".

» Back to the Table of Contents. «

FPGeneratePDF

int FPGeneratePDF(
   int intThreadID,const char *docname,const char *options,
   const char *resultname,const char *papername,
   int orientation,long pagewidth,
   long pageheight,long totalpages,
   long pagesegment,char *errtext,
   void callFunction(int,char *,char *,char *))

Return value:

A value of 0 indicates a successful completion of this function. A value other than 0 indicates that an error occurred and the parameter errtext contains an additional error message for most types of errors.

Parameters:

intThreadID

The unique thread ID returned from an initial called to FPAddThread.

docname

Sets the name of the file that resulted from the FPCreate function.

options

[ <keyword> = <value> ]...

Version	1.2 \| 1.3 \| 1.4 \| 1.5 \| 1.6 \| 1.7 (Default: 1.7) The PDF version is written into the header portion of the resulting PDF file. In addition, if the PDF version is greater than or equal to 1.3, PageLabels are also included in the resulting PDF file. PageLabels allow PDF viewers to display a starting page number greater than one. This is especially convenient for a user when viewing files that have been split into segments.
OPI	disable \| enable \| explicit When OPI is "disable", no OPI instructions are output regardless of the setting of the OPI style property. When OPI is "enable", OPI instructions are output if the value of an element's OPI style property is "true". However if OPI is "explicit", OPI instructions are output for all applicable elements regardless of the setting of the OPI style property.
OPIOnly	true \| false (Default: false) Also, when OPIonly is set to "true", OPI instructions will be output for applicable images without "preview" images (i.e., the backgrounds will show instead). When OPIonly is "false", preview images are output in a normal manner with OPI instructions.

resultname

Sets the name of the PDF file to be generated by this function.

papername

Sets the paper name as returned by the FPCreate function.

orientation

Sets the orientation of the document on the paper as returned by the FPCreate function.

pagewidth

Sets the page width as returned by the FPCreate function.

pageheight

Sets the page height as returned by the FPCreate function.

totalpages

Sets the total pages as returned by the FPCreate function.

pagesegment

Determines when generation is to be segmented into multiple output files. If pagesegment is set to a value of zero (default), generation results in a single file.

errtext

Additional error message for most types of errors returned by this function.

callFunction

Please refer to the FPCreate function in this chapter for additional information.

Description:

The FPGeneratePDF entry point generates a self-contained Portable Document Format (PDF) file from a FinerEdge Publisher document that was initially processed with the FPCreate entry point. This entry point must only be called after a successful call to the FPCreate entry point.

The "Flate" filter is used with all PDF generations. In general, all fonts and images are encoded using the Flate filter. Portability is ensured by encoding the binary output of the Flate filter with the ASCII85 filter thus producing displayable output.

» Back to the Table of Contents. «

FPGeneratePrint

int FPGeneratePrint(
int intThreadID,const char *docname,const char *mediactrl,
const char *media,int papertype,int orientation)

Return value:

This function can return the following values:

0	Indicates a successful completion of this function.
1	Cannot acquire the default Windows printing device (when media is not set).
2	Cannot access the indicated printing device.
3	Cannot acquire the printing device's attributes.
4	Cannot acquire a device context for the printing device (when media is set).

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
docname	Sets the name of the file that resulted from the FPCreate function.
mediactrl	When set, overrides the media printing device that was set via the media parameter. The calling application can use this parameter to override the location where the document will be directly printed if applicable.
media	Sets media printing device as returned by the FPCreate function.
papertype	Sets the Windows paper type value as returned by the FPCreate function.
orientation	Sets the orientation of the document on the paper as returned by the FPCreate function.

Description:

The FPGeneratePrint entry point directly prints a FinerEdge Publisher document to either a locally known or network printing device. If the calling program gives the name of the printing device, the document is directly output to that printer. However, if the name of the printing device is not given by the calling program, the standard Windows print dialog will be displayed.

This entry point should only be called after a successful call to the FPCreate entry point. The resulting file from the FPCreate entry point is passed into this function as it's first parameter. It's the responsibility of the application to remove the temporary resulting file from the FPCreate function after all "FPGenerate..." entry points have been called.

For more information on this topic, please refer to the FPWriter/FPServer method "GeneratePrint".

» Back to the Table of Contents. «

FPGeneratePS

int FPGeneratePS(
   int intThreadID,const char *docname,const char *options,
   const char *resultname,const char *papername,
   int orientation,long pagewidth,
   long pageheight,long totalpages,
   long pagesegment,char *errtext,
   void callFunction(int,char *,char *,char *))

Return value:

A value of 0 indicates a successful completion of this function. A value other than 0 indicates that an error occurred. The parameter errtext contains an additional error message for most types of errors.

Parameters:

intThreadID

The unique thread ID returned from an initial called to FPAddThread.

docname

Sets the name of the file that resulted from the FPCreate function.

options

[ <keyword> = <value> ]...

Version	2 \| 3 (Default: 3) The PostScript version is written into the header portion of the resulting PostScript file. In addition, if the PostScript version is greater than or equal to 3, all embedded TrueType fonts, Type 1 fonts, and in-line images are encoded using the "Flate" filter for optimum data compression.
OPI	disable \| enable \| explicit When OPI is "disable", no OPI instructions are output regardless of the setting of the OPI style property. When OPI is "enable", OPI instructions are output if the value of an element's OPI style property is "true". However if OPI is "explicit", OPI instructions are output for all applicable elements regardless of the setting of the OPI style property.
OPIOnly	true \| false (Default: false) Also, when OPIonly is set to "true", OPI instructions will be output for applicable images without "preview" images (i.e., the backgrounds will show instead). When OPIonly is "false", preview images are output in a normal manner with OPI instructions.

resultname

Sets the name of the PostScript file to be generated by this function.

papername

Sets the paper name as returned by the FPCreate function.

orientation

Sets the orientation of the document on the paper as returned by the FPCreate function.

pagewidth

Sets the page width as returned by the FPCreate function.

pageheight

Sets the page height as returned by the FPCreate function.

totalpages

Sets the total pages as returned by the FPCreate function.

pagesegment

Determines when generation is to be segmented into multiple output files. If pagesegment is set to a value of zero (default), generation results in a single file.

errtext

Additional error message for most types of errors returned by this function.

callFunction

Please refer to the FPCreate function in this chapter for additional information.

Description:

The FPGeneratePS entry point generates a self-contained PostScript file from a FinerEdge Publisher document that was initially processed with the FPCreate entry point. This entry point must only be called after a successful call to the FPCreate entry point.

The "Flate" filter is used with all PostScript version 3.0 or greater generations. In general, all fonts and images are encoded using the Flate filter. Portability is ensured by encoding the binary output of the Flate filter with the ASCII85 filter thus producing displayable output. When generating PostScript version 2.0, all fonts and images are encoded using only the ASCII85 filter, and thus produces larger output files.

» Back to the Table of Contents. «

FPGenerateXPS

int FPGenerateXPS(
   int intThreadID,const char *docname,const char *options,
   const char *resultname,const char *papername,
   int orientation,long pagewidth,
   long pageheight,long totalpages,
   long pagesegment,char *errtext,
   void callFunction(int,char *,char *,char *))

Return value:

Parameters:

intThreadID

The unique thread ID returned from an initial called to FPAddThread.

docname

Sets the name of the file that resulted from the FPCreate function.

options

[ <keyword> = <value> ]...

Version	1.0 (Default: 1.0) The XPS version is used to control XPS output.

resultname

Sets the name of the XPS file to be generated by this function.

papername

Sets the paper name as returned by the FPCreate function.

orientation

Sets the orientation of the document on the paper as returned by the FPCreate function.

pagewidth

Sets the page width as returned by the FPCreate function.

pageheight

Sets the page height as returned by the FPCreate function.

totalpages

Sets the total pages as returned by the FPCreate function.

pagesegment

Determines when generation is to be segmented into multiple output files. If pagesegment is set to a value of zero (default), generation results in a single file.

errtext

Additional error message for most types of errors returned by this function.

callFunction

Please refer to the FPCreate function in this chapter for additional information.

Description:

The FPGenerateXPS entry point generates an XML Paper Specification (XPS) file from a FinerEdge Publisher document that was initially processed with the FPCreate entry point. This entry point must only be called after a successful call to the FPCreate entry point.

» Back to the Table of Contents. «

FPGetParam

int FPGetParam(int intThreadID,int index,char *name,char *value)

Return value:

A value of 1 indicates that the parameter was fetched. A value of 0 indicates that the parameter does not exist.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
index	Sets the index of the parameter to be fetched (relative to 1).
name	Returns the name of the parameter key fetched.
value	Returns the value of the parameter corresponding to the key fetched.

Description:

This entry point should only be called while processing the "initRecord" or "getRecord" options of the callback function "callFunction" within the FPCreate entry point. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The FPGetParam entry point iterates through the stored parameters for the requested record of the recordset and returns their respective keys and values to the application. For more information on this topic, please refer to the FPWriter/FPServer method "GetParam".

» Back to the Table of Contents. «

FPLoadHoliday

void FPLoadHoliday(int intThreadID,const char *date)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
date	Appends the date into the optional holiday table. The date must be in the format indicated by the <dateformat> options parameter of FPCreate.

Description:

This entry point should only be called while processing the "initDocument" callback function within the FPCreate entry point. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The optional FPLoadHoliday entry point appends a date corresponding to a holiday into FinerEdge Publisher's internal holiday table. The optional holiday table is used when calculating dates with the "date" function. For more information on this topic, please refer to the FPWriter/FPServer method "LoadHoliday".

» Back to the Table of Contents. «

FPRefGet

int FPRefGet(int intThreadID,char *refseaach,char *reftext,
long page,long realpage,long offset)

Return value:

The "index" of the found reference or 0 if a reference was not found.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
refsearch	Returns the value of the "ref-search" property applied to the current reference.
reftext	Returns the value of the "ref-text" property applied to the current reference.
page	Returns the display page number of the current reference.
realpage	Returns the real page number of the current reference.
offset	Returns the document rendering input file offset value.

Description:

This entry point retrieves the item values for the current reference and should only be called during the "CloseDocument" event.

» Back to the Table of Contents. «

FPRefSearch

int FPRefSearch(int intThreadID,char *position,char *pattern,
char *value,int options)

Return value:

The "index" of the found reference or 0 if a reference was not found.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
position	The values "begin", "page-begin-down", "page-begin-down-adjust", "page-begin-up", "page-begin-up-adjust", "page-end-down", "page-end-down-adjust", "page-end-up", "page-end-up-adjust", "next", or "previous".
pattern	The regular expression or simple search pattern.
value	When the parameter position is either "page-begin-down", "page-begin-up", "page-end-down" or "page-end-up" (including the "adjust" suffixes), this parameter specifies a page number. However, if the parameter position is either "next" or "previous", this parameter specifies the number of times the search is repeated with the same parameters.
intOptions	When the value of this parameter is 0, the pattern parameter represents a regular expression. However, if the value of this parameter is 1, the pattern parameter represents a simple pattern (see the "pattern" function for more information).

Description:

This entry point searches and selects a reference in the reference table in preparation for calling the FPRefGet entry point to retrieve the information for the specific reference and should only be called during the "CloseDocument" event.

» Back to the Table of Contents. «

FPSetVarDate

void FPSetVarDate(int intThreadID,const char *name,const char *date)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
name	Sets the name of the variable (that the value of the date parameter will be assigned to).
date	Sets the value that the variable is assigned (as indicated by the name parameter). The date must be in the format indicated by the options <dateformat> parameter of FPCreate.

Description:

This entry point is normally called while processing the "getRecord" callback function of the FPCreate entry point. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The FPSetVarDate entry point assigns the <number> value of the converted date to the named external variable. The named external variable must not include the name of the recordset or the preceding "@" character. For more information on this topic, please refer to the FPWriter/FPServer method "SetVarDate".

» Back to the Table of Contents. «

FPSetVarDouble

void FPSetVarDouble(int intThreadID,const char *name,double value)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
name	Sets the name of the variable (that the value parameter will be assigned to).
value	Sets the value that the variable is assigned (as indicated by the name parameter).

Description:

FPSetVarLong

void FPSetVarLong(int intThreadID,const char *name,long value)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
name	Sets the name of the variable (that the value parameter will be assigned to).
value	Sets the value that the variable is assigned (as indicated by the name parameter).

Description:

FPSetVarString

void FPSetVarString(int intThreadID,const char *name,const char *text)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
name	Sets the name of the variable (that the text parameter will be assigned to).
text	Sets the value that the variable is assigned (as indicated by the name parameter).

Description:

This entry point is normally called while processing the "getRecord" callback function of the FPCreate entry point. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The FPSetVarString entry point assigns the <string> value to the named external variable. The named external variable must not include the name of the recordset or the preceding "@" character.

By default, the length of the supplied <string> value should be limited to no more than 4095 characters unless it is to be simply output in a document using the VAR tag. Carriage returns, linefeeds, and carriage return/linefeed pairs are interpreted as a "<BR/>" action by the VAR tag. For more information on this topic, please refer to the FPWriter/FPServer method "SetVarString".

» Back to the Table of Contents. «

FPSetVarTime

void FPSetVarTime(int intThreadID,const char *name,const char *time)

Return value:

None.

Parameters:

intThreadID	The unique thread ID returned from an initial called to FPAddThread.
name	Sets the name of the variable (that the value of the time parameter will be assigned to).
time	Sets the value that the variable is assigned (as indicated by the name parameter). The time must be in the format indicated by the options <timeformat> parameter of FPCreate.

Description:

This entry point is normally called while processing the "getRecord" callback function of the FPCreate entry point. For a detailed explanation of presenting application data to documents and the interaction between the application and FinerEdge Publisher, please refer to the chapter "Application Data Interface".

The FPSetVarTime entry point assigns the <number> value of the converted time to the specifically named external variable. The named external variable must not include the name of the recordset or the preceding "@" character. For more information on this topic, please refer to the FPWriter/FPServer method "SetVarTime".

» Back to the Table of Contents. «

Chapter 10 - FPForm and FPFormNET

Overview

This chapter describes the properties, methods, and events for the FPForm and FPFormNET interfaces. The FPWriter and FPWriterNET interfaces are front-end data collection mechanisms for FinerEdge Publisher documents and their governing processes. The form mechanisms can simultaneously produce both "on-the-fly" GUI and HTML data input forms from a common WYSIWYG editor. The FPForm interface is an ActiveX control while the FPFormNET interface is a .NET assembly Windows Form Control.

The formatting model that is employed by the form facility uses relative positioning to place various controls and control groups onto a form. This is the default method of positioning for most Web standards and addresses the problems inherent in an absolute positioning model. For example, when another font face or size is used in place of an original font (either explicitly or by implicit substitution), absolute positioning may require manual modification to the form while relative positioning usually requires no modifications to the form.

Each line (or row) of a form may contain a number of controls or control groups of varying sizes prior to a line break. The overall height of the line is determined by the largest height of the controls or control groups on that particular line. When the next line is started, it is positioned below the overall height of the previous line. These same basic rules apply within control groups and extend to all levels of nested control groups.

The form facility is present within the FinerEdge Publisher IDE as the Form Definition and Form Generation views. The user-oriented description of the form facility, including the form properties, form controls, and generation options is included within the FinerEdge Publisher IDE manual. However, the form facility is also available as standalone interfaces that may be embedded within many types of applications. The remainder of this chapter describes the properties and methods of the form facility's application interfaces.

» Back to the Table of Contents. «

Catalog (FPForm,FPFormNET)

String, Get/Set

Description:

The Catalog property gets or sets the name of the catalog file. This property must be set prior to calling LoadForm.

» Back to the Table of Contents. «

CtlGotFocus (FPForm,FPFormNET)

C#:

void CtlGotFocus(int intIndex)

Visual Basic:

Sub CtlGotFocus(ByVal intIndex As Integer)

Parameters:

intIndex	The index of the field that lost the focus (relative to 1).

Description:

This event is called anytime a field (i.e., a control) receives the input focus. The index of the specific field that has obtained the input focus is designated by the intIndex parameter. A subsequent call to the GetField method can be made to retrieve further information about the field corresponding to the intIndex parameter if desired.

» Back to the Table of Contents. «

CtlLostFocus (FPForm,FPFormNET)

C#:

void CtlLostFocus(int intIndex)

Visual Basic:

Sub CtlLostFocus(ByVal intIndex As Integer)

Parameters:

intIndex	The index of the field that lost the focus (relative to 1).

Description:

This event is called anytime a field (i.e., control) loses the input focus. The index of the specific field that has lost the input focus is designated by the intIndex parameter. A subsequent call to the GetField method can be made to retrieve further information about the field corresponding to the intIndex parameter if desired.

» Back to the Table of Contents. «

Error (FPForm,FPFormNET)

String, Get only

Description:

This property contains an error message from the last LoadForm method if a failure was detected. If the last LoadForm method was successful, this property contains an empty string.

» Back to the Table of Contents. «

FieldChanged (FPForm,FPFormNET)

Boolean, Get only

Description:

Following a successful call to the GetField method, this property returns True if the content of the field has changed since the form was initially loaded, otherwise this property returns False if the content of the field has not changed.

» Back to the Table of Contents. «

FieldHelp (FPForm,FPFormNET)

String, Get only

Description:

Following a successful call to the GetField method, this property returns the optional help text. The single line help text is shown when the user focuses the corresponding control in both the GUI and Web environments.

» Back to the Table of Contents. «

FieldIndex (FPForm,FPFormNET)

Integer, Get only

Description:

Following a successful call to the GetField method, this property returns the index of the selected field. The field index values are assigned at the time that the fields are created within the form definition in the order of appearance beginning with 1.

» Back to the Table of Contents. «

FieldName (FPForm,FPFormNET)

String, Get only

Description:

Following a successful call to the GetField method, this property returns the unique field name associated with the control. A field name is required for all controls that return values to uniquely identify them for subsequent processing.

» Back to the Table of Contents. «

FieldType (FPForm,FPFormNET)

Integer, Get only

Description:

Following a successful call to the GetField method, this property returns the type of the field as follows:

1	Label.
2	Edit.
3	Combobox.
4	List Box.
5	Checkbox.
6	Radio Button.
7	Image.
8	Group.

» Back to the Table of Contents. «

FieldUser (FPForm,FPFormNET)

String, Get only

Description:

Following a successful call to the GetField method, this property returns the optional user text. The user text is entirely dependent upon the calling application and is not used within the Form facility.

» Back to the Table of Contents. «

FieldValue (FPForm,FPFormNET)

String, Get only

Description:

Following a successful call to the GetField method, this property returns the value of the field, which is dependent upon it's declared type. For checkboxes and radio buttons, a value of 0 is returned if the control is unchecked and a value of 1 is returned if the control is checked.

» Back to the Table of Contents. «

FormHeight (FPForm,FPFormNET)

Integer, Get only

Description:

This property represents the actual height of the dynamic form in Twips (i.e., not just the scrollable frame). If desired, FormHeight can be used to resize the caller's host form to be the height of the dynamic form (please refer to the Resize event).

» Back to the Table of Contents. «

FormLoaded (FPForm,FPFormNET)

Boolean, Get only

Description:

This property returns True if a form is currently loaded and False if a form is not currently loaded.

» Back to the Table of Contents. «

FormName (FPForm,FPFormNET)

String, Get/Set

Description:

This property gets or sets the name of the form definition currently being processed. A subsequent call to the method LoadForm will physically load the form into memory. This property must be set prior to calling LoadForm.

» Back to the Table of Contents. «

FormWidth (FPForm,FPFormNET)

Integer, Get only

Description:

This property represents the actual width of the dynamic form in Twips (i.e., not the scrollable frame). If desired, FormWidth can be used to resize the caller's host form to be the width of the dynamic form (please refer to the Resize event).

» Back to the Table of Contents. «

GenFormASP (FPForm,FPFormNET)

C#:

void GenFormASP()

Visual Basic:

Sub GenFormASP()

Return value:

None.

Parameters:

None.

Description:

This method generates a complete Active Server Pages (ASP) process to include the HTML representation of the form and the applicable calls to the FPServer interface. The ASP file directory, URL directory, and document generation options are specified from within the form properties user dialog.

» Back to the Table of Contents. «

GenFormASPX (FPForm,FPFormNET)

C#:

void GenFormASPX()

Visual Basic:

Sub GenFormASPX()

Return value:

None.

Parameters:

None.

Description:

This method generates a complete Active Server Pages .NET (ASPX) process to include the HTML representation of the form, a C# code-behind file, and the applicable calls to the FPServer interface. The ASP file directory, URL directory, and document generation options are specified from within the form properties user dialog.

» Back to the Table of Contents. «

GenFormHTML (FPForm,FPFormNET)

C#:

void GenFormHTML()

Visual Basic:

Sub GenFormHTML()

Return value:

None.

Parameters:

None.

Description:

This method generates HTML output from the currently loaded form definition. The HTML output closely resembles the "look and feel" of the GUI output.

» Back to the Table of Contents. «

GenFormJSP (FPForm,FPFormNET)

C#:

void GenFormJSP()

Visual Basic:

Sub GenFormJSP()

Return value:

None.

Parameters:

None.

Description:

This method generates a complete Java Server Pages (JSP) process to include the HTML representation of the form and the applicable calls to the FPServer interface. The JSP file directory, URL directory, and document generation options are specified from within the form properties user dialog

» Back to the Table of Contents. «

GetField (FPForm,FPFormNET)

C#:

bool GetField(object varKey)

Visual Basic:

Function GetField(ByVal varKey As Variant) As Boolean

Return value:

Returns True if the field was found, otherwise returns False if the field was not found.

Parameters:

varKey	This parameter specifies the field to load. If a string is used, it indicates the unique name of the field to load. If an integer number is used, it indicates the index of the field to load. (Field indexes are assigned in the order that fields appear in the form definition beginning from 1.)

Description:

Locates a specific field within the currently loaded form definition. If a successful result is returned by this function, the loaded field becomes the currently selected field. Subsequent use of the "Field..." properties will yield results that are relative to the currently selected field.

» Back to the Table of Contents. «

LoadForm (FPForm,FPFormNET)

C#:

bool LoadForm()

Visual Basic:

Function LoadForm() As Boolean

Return value:

Returns True if the form was successfully loaded and False if an error occurred while loading the form definition into memory. If an error occurs while loading a form definition, the Error property can be used to display a message indicating the type of error.

Parameters:

None.

Description:

This method processes the form definition indicated by the FormName property. Usually, a subsequent call to the method ShowForm follows this call in order to display the form within the interface control.

However, if an individual only needed to generate HTML output, this call can be followed by a call to any of the "Gen..." methods without ever calling the ShowForm method.

» Back to the Table of Contents. «

Resize (FPForm,FPFormNET)

C#:

void Resize()

Visual Basic:

Sub Resize()

Parameters:

None.

Description:

This event is called when the dynamic portion of the form has been resized. This allows the application the opportunity to further resize it's own outer form to match the dimensions of the dynamic portion of the form if desired by using the FormHeight and FormWidth properties.

» Back to the Table of Contents. «

SetFieldUser (FPForm,FPFormNET)

C#:

bool SetFieldUser(String strUser)

Visual Basic:

Function SetFieldUser(ByVal strUser As String) As Boolean

Return value:

Returns True if the field's user string was changed, otherwise returns False.

Parameters:

strUser	The new user string of the field.

Description:

The user string of the currently selected field is replaced by the new value as indicated by the strUser parameter. The field must first be selected by calling the GetField method.

» Back to the Table of Contents. «

SetFieldValue (FPForm,FPFormNET)

C#:

bool SetFieldValue(String strValue)

Visual Basic:

Function SetFieldValue(ByVal strValue As String) As Boolean

Return value:

Returns True if the field's value was changed, otherwise returns False.

Parameters:

strValue	The new value of the field that is dependent upon it's declared type. For checkboxes and radio buttons, a value of 0 unchecks the field while a value of 1 checks the field.

Description:

The value of the currently selected field is replaced by the new value as indicated by the strValue parameter. The field must first be selected by calling the GetField method.

» Back to the Table of Contents. «

ShowForm (FPForm,FPFormNET)

C#:

void ShowForm()

Visual Basic:

Sub ShowForm()

Return value:

None.

Parameters:

None.

Description:

Displays the currently loaded form definition within the boundaries of the interface control. This call does nothing if a form definition has not been first loaded by a successful call to the LoadForm method.

» Back to the Table of Contents. «

UnloadForm (FPForm,FPFormNET)

C#:

void UnloadForm()

Visual Basic:

Sub UnloadForm()

Return value:

None.

Parameters:

None.

Description:

This method destroys the dynamic form window (if currently shown) and releases all memory occupied by the active form definition. If a form is not currently loaded via the LoadForm method, this method does nothing.

In addition, this method should always be explicitly called from the application form's "Unload" procedure when the property DesignMode has set to True. This action is necessary so that the user has a chance to save their modified form definition (otherwise any pending changes will be lost).

» Back to the Table of Contents. «

Appendix A

Syntactical Conventions

The following conventions are used throughout this reference manual to describe the various syntactic elements employed by FinerEdge Publisher.

item

Constant text.

[item]

Optional constant text.

item|item

Conditional constant text (i.e., item "or" item).

[item|item]

Optional conditional constant text.

<item>

Reference to an item or <item>.

Reference to a conditional item or <item>.

<item>...

Reference to an item or <item> that can be repeated.

[<item>]

Reference to an optional item or <item>.

[<item>|<item>]

Reference to an optional conditional item or <item>.

[<item>]...

Reference to an optional item or <item> that can be repeated.

[<item>|<item>]...

Reference to an optional conditional item or <item> that can be repeated.

» Back to the Table of Contents. «