| Oracle® Outside In Image Export Release 8.3.5 |
|
|
View PDF |
Options are parameters affecting the behavior of an export or transformation. These options are available to the developer when using Image Export. This chapter presents both the C/C++ and SOAP options relevant to the Image Export product.
While default values are provided, users are encouraged to set all options for a number of reasons. In some cases, the default values were chosen to provide backwards compatibility. In other cases, the default values were chosen arbitrarily from a range of possibilities.
One reason that users may want to avoid using the default value for an option is that the default value may change from one release to the next. This is because as standards evolve over time, defaults may be updated to reflect the current status of the technology.
Options are set using the DASetOption call. It is recommended that developers familiarize themselves with all of the options available.
Options may be Local, in which case they only affect the handle for which they are set, or Global, in which case they automatically affect all handles associated with the hDoc and must be set before the call to DAOpenDocument.
This section discusses character mapping options.
This option is used in cases where Outside In cannot determine the character set used to encode the text of an input file. When all other means of determining the file's character set are exhausted, Outside In will assume that an input document is encoded in the character set specified by this option. This is most often used when reading plain-text files, but may also be used when reading HTML or PDF files. The possible character sets are listed in charsets.h.
When "extended test for text" is enabled (see "SCCOPT_FIFLAGS"), this option will still apply to plain-text input files that are not identified as EBCDIC or Unicode.
This option supersedes the SCCOPT_FALLBACKFORMAT option for selecting the character set assumed for plain-text files. For backwards compatibility, use of deprecated character-set -related values is still currently supported for SCCOPT_FALLBACKFORMAT, though internally such values will be translated into equivalent values for the SCCOPT_DEFAULTINPUTCHARSET. As a result, if an application were to set both options, the last such value set for either option will be the value that takes effect.
Handle Types
NULL, VTHDOC
Scope
Global
Data Type
VTDWORD
Default
ANSI1252 on Windows and Latin-1 on UNIX.
Data
The data types are listed in charsets.h.
This option selects the character used when a character cannot be found in the output character set. This option takes the Unicode value for the replacement character. It is left to the user to make sure that the selected replacement character is available in the output character set.
Handle Types
VTHDOC
Scope
Local
Data Type
VTWORD
Data
The Unicode value for the character to use.
Default
0x002a = "*"
This section discusses output options.
This option is only valid on 32-bit Linux (Red Hat and Suse) and Solaris Sparc platforms.
When this option is set to TRUE, the technology will attempt to use its internal graphics code to render fonts and graphics. When set to FALSE, the technology will render images using the operating system's native graphics subsystem (X11 on UNIX/Linux platforms). Note that this option only works when at least one of the appropriate output solutions is present. For example, if the UNIX $DISPLAY variable does not point to a valid X Server, but the OSGD and/or WV_GD modules required for the Outside In output solution exist, Outside In will default to the Outside In rendering code. The option will fail if neither of these output solutions is present.
It is important for the system to be able to locate useable fonts when this option is set to TRUE. Only TrueType fonts (*.ttf or *.ttc files) are currently supported. To ensure that the system can find them, make sure that the environment variable GDFONTPATH includes one or more paths to these files. If the variable GDFONTPATH can't be found, the current directory is used. If fonts are called for and cannot be found, Image Export will exit with an error. Also note that when copying Windows fonts to a UNIX system, the font extension for the files (*.ttf or *.ttc) must be lowercase, or they will not be detected during the search for available fonts. Oracle does not provide fonts with any Outside In product.
Handle Types
NULL, VTHDOC
Scope
Global
Data Type
VTBOOL
Data
One of the following values:
TRUE: Use the technology's internal graphics rendering code to produce bitmap output files whenever possible.
FALSE: Use the operating system's native graphics subsystem.
Default
FALSE
This section discusses input handling options.
This option controls how files are handled when their specific application type cannot be determined. This normally affects all plain-text files, because plain-text files are generally identified by process of elimination, for example, when a file isn't identified as having been created by a known application, it is treated as a plain-text file.
It is recommended that FI_NONE be set to prevent Image Export from exporting unidentified binary files as though they were text, which could generate many pages of "garbage" output.
This option must be set for an hDoc before any subhandle has been created for that hDoc.
A number of values that were formerly allowed for this option have been deprecated. Specifically, the values that selected specific plain-text character sets are no longer to be used. Instead, applications should use the SCCOPT_DEFAULTINPUTCHARSET option for such functionality.
Handle Types
NULL, VTHDOC
Scope
Global
Data Type
VTDWORD
Data
The high VTWORD of this value is reserved and should be set to 0, and the low VTWORD must have one of the following values:
FI_TEXT: Unidentified file types will be treated as text files.
FI_NONE: Outside In will not attempt to process files whose type cannot be identified. This will include text files. When this option is selected, an attempt to process a file of unidentified type will cause Outside In to return an error value of DAERR_FILTERNOTAVAIL (or SCCERR_NOFILTER).
Default
FI_TEXT
This option affects how an input file's internal format (application type) is identified when the file is first opened by the Outside In technology. When the extended test flag is in effect, and an input file is identified as being either 7-bit ASCII, EBCDIC, or Unicode, the file's contents will be interpreted as such by the export process.
The extended test is optional because it requires extra processing and cannot guarantee complete accuracy (which would require the inspection of every single byte in a file to eliminate false positives.)
Handle Types
NULL, VTHDOC
Scope
Global
Data Type
VTDWORD
Data
One of the following values:
SCCUT_FI_NORMAL: This is the default value. When this is set, standard file identification behavior occurs.
SCCUT_FI_EXTENDEDTEST: If set, the File Identification code will run an extended test on all files that are not identified.
Default
SCCUT_FI_EXTENDEDTEST: The technology will attempt an extra test after the file is first opened to see if it is 7-bit text or EBCDIC.
This option allows the developer to specify the location of a Lotus Notes or Domino installation for use by the NSF filter. A valid Lotus installation directory must contain the file nnotes.dll.
Note:
The NSF filter is currently only supported on Win32.Handle Types
NULL
Scope
Global
Data Type
VTLPBYTE
Data
A path to the Lotus Notes directory.
Default
If this option isn't set, then OIT will first attempt to load the Lotus library according to the operating system's PATH environment variable, and then attempt to find and load the Lotus library as indicated in HKEY_CLASSES_ROOT\Notes.Link.
This option allows the user to define an offset to GMT that will be applied during date formatting, allowing date values to be displayed in a selectable time zone. This option affects the formatting of numbers that have been defined as date values (e.g., most dates in spreadsheet cells). This option will not affect dates that are stored as text.
Note:
Daylight savings is not supported. The sent time in msg files when viewed in Outlook can be an hour different from the time sent when an image of the msg file is created.Handle Types
NULL, VTHDOC
Scope
Global
Data Type
VTLONG
Data
Integer parameter from -96 to 96, representing 15-minute offsets from GMT. To query the operating system for the time zone set on the machine, specify SCC_TIMEZONE_USENATIVE.
Default
0: GMT time
This option allows the developer to set flags that enable options that span multiple export products.
Handle Types
VTHDOC
Scope
Local
Data Type
VTDWORD
Data
SCCOPT_FLAGS_ALLISODATETIMES: When this flag is set, all Date and Time values are converted to the ISO 8601 standard. This conversion can only be performed using dates that are stored as numeric data within the original file.
Default
0: All flags turned off
This option can disable the password verification of files where the contents can be processed without validation of the password. If this option is not set, the filter should prompt for a password if it handles password-protected files.
As of Release 8.3.5, only the PST Filter supports this option.
Scope
Global
Data Type
VTBOOL
Data
TRUE: Ignore validation of the password
FALSE: Prompt for the password
Default
FALSE
This option controls how the technology reorders bidirectional text.
Data Type
VTDWORD
Data
One of the following values:
SCCUT_REORDER_UNICODE_OFF: This disables any processing for unicode characters. This option is the default.
SCCUT_REORDER_UNICODE_LTOR: Characters reordered using the Unicode bidirectional algorithm
SCCUT_REORDER_UNICODE_RTOL: Characters displayed in right-to-left order
This section describes compression options.
This option can disable access to any files using JPEG compression, such as JPG graphic files or TIFF files using JPEG compression, or files with embedded JPEG graphics. Attempts to read or write such files when this option is enabled will fail and return the error SCCERR_UNSUPPORTEDCOMPRESSION if the entire file is JPEG compressed, and grey boxes for embedded JPEG-compressed graphics.
The following is a list of file types affected when this option is disabled:
JPG files
Postscript files containing JPG images
PDFs containing JPEG images
Note that the setting for this option overrides the requested output graphic format when there is a conflict.
Handle Types
HDOC, HEXPORT
Scope
Local
Data Type
VTDWORD
Data
SCCVW_FILTER_JPG_ENABLED: Allow access to files that use JPEG compression
SCCVW_FILTER_JPG_DISABLED: Do not allow access to files that use JPEG compression
Default
SCCVW_FILTER_JPG_ENABLED
This option can disable access to any files using Lempel-Ziv-Welch (LZW) compression, such as .GIF files, .ZIP files or self-extracting archive (.EXE) files containing "shrunk" files. Attempts to read or write such files when this option is enabled will fail and return the error SCCERR_UNSUPPORTEDCOMPRESSION if the entire file is LZW compressed, and grey boxes for embedded LZW-compressed graphics.
The following is a list of file types affected when this option is disabled:
GIF files
TIF files using LZW compression (note that TIF files will still be created when LZW compression is used and this option is enabled, but the resulting images will be large, uncompressed TIF files)
PDF files that use internal LZW compression
ZIP and self-extracting archive (.EXE) files containing "shrunk" files
Postscript files using LZW compression
Image Export will not be affected by this option when processing formats that compress subfile contents but not subfile names, such as TAR and ZIP.
Although this option can disable access to files in ZIP or EXE archives stored using LZW compression, any files in such archives that were stored using any other form of compression will still be accessible.
The setting for this option overrides the requested output graphic format when there is a conflict.
Handle Types
HDOC, HEXPORT
Scope
Local
Data Type
VTDWORD
Data
SCCVW_FILTER_LZW_ENABLED: LZW compressed files will be read and written normally.
SCCVW_FILTER_LZW_DISABLED: LZW compressed files will not be read or written.
Default
SCCVW_FILTER_LZW_ENABLED
This section discusses graphics options.
This option allows the developer to specify interlaced or non-interlaced GIF output. Interlaced GIFs are useful when graphics are to be downloaded over slow Internet connections. They allow the browser to begin to render a low-resolution view of the graphic quickly and then increase the quality of the image as it is received. There is no real penalty for using interlaced graphics.
This option is only valid if the dwOutputID parameter of the EXOpenExport function is set to FI_GIF.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTBOOL
Data
One of the following values:
TRUE: Produce interlaced GIFs.
FALSE: Produce non-interlaced GIFs.
Default
TRUE
When set to SCCGRAPHIC_CROPTOCONTENT, this option forces Image Export to crop whitespace from the edge of each output image. This includes margins and any unused space at the end of a page. This results in smaller output files without any loss of original input document content.
If there is no content, then no cropping is performed.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
SCCGRAPHIC_CROPTOCONTENT: Files are cropped to smallest bounding rectangle.
SCCGRAPHIC_NOCROPPING: Files are not cropped.
Default
SCCGRAPHIC_NOCROPPING
This option defines the absolute height in pixels to which exported graphics will be resized. If this option is set and the SCCOPT_GRAPHIC_WIDTH option is not, the width of the image will be calculated based on the aspect ratio of the source image. The developer should be aware that very large values for this option or SCCOPT_GRAPHIC_WIDTH could produce images whose size exceeds available system memory, resulting in conversion failure.
If you are exporting a non-graphic file (word processing, spreadsheet or archive) and the settings for SCCOPT_GRAPHIC_HEIGHT and SCCOPT_GRAPHIC_WIDTH do not match the aspect ratio of the original document, the exported image will have whitespace added so that the original file's aspect ratio is maintained.
The settings for the SCCOPT_GRAPHIC_HEIGHTLIMIT and SCCOPT_GRAPHIC_WIDTH options can override the setting for SCCOPT_GRAPHIC_HEIGHT.
Handle Types
VTDWORD
Scope
Local
Data Type
VTDWORD
Data
The desired absolute height of the output image, in pixels.
Default
0: No absolute height specified.
Note that this option differs from the behavior of setting the height of graphics by using in that it sets an upper limit on the image height. Images larger than this limit will be reduced to the limit value. However, images smaller than this height will not be enlarged when using this option. Setting the height using SCCOPT_GRAPHIC_HEIGHT causes all output images to be reduced or enlarged to be of the specified height.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
The maximum height of the output graphic in pixels. A value of zero is equivalent to SCCGRAPHIC_NOLIMIT, which causes this option to be ignored.
Default
SCCGRAPHIC_NOLIMIT: No absolute height limit specified.
This option allows the user to specify the output graphics device's resolution in DPI and only applies to images whose size is specified in physical units (in/cm). For example, consider a 1" square, 100 DPI graphic that is to be rendered on a 50 DPI device (SCCOPT_GRAPHIC_OUTPUTDPI is set to 50). In this case, the size of the resulting TIFF, BMP, JPEG, GIF, or PNG will be 50 x 50 pixels.
In addition, the special #define of SCCGRAPHIC_MAINTAIN_IMAGE_DPI, which is defined as 0, can be used to suppress any dimensional changes to an image. In other words, a 1" square, 100 DPI graphic will be converted to an image that is 100 x 100 pixels in size. This value indicates that the DPI of the output device is not important. It extracts the maximum resolution from the input image with the smallest exported image size.
Setting this option to SCCGRAPHIC_MAINTAIN_IMAGE_DPI may result in the creation of extremely large images. Be aware that there may be limitations in the system running this technology that could result in undesirably large bandwidth consumption or an error message. Additionally, an out of memory error message will be generated if system memory is insufficient to handle a particularly large image.
Also note that the SCCGRAPHIC_MAINTAIN_IMAGE_DPI setting will force the technology to use the DPI settings already present in raster images, but will use the current screen resolution as the DPI setting for any other type of input file.
For some output graphic types, there may be a discrepancy between the value set by this option and the DPI value reported by some graphics applications. The discrepancy occurs when the output format uses metric units (DPM, or dots per meter) instead of English units (DPI, or dots per inch). Depending on how the graphics application performs rounding on meters to inches conversions, the DPI value reported may be 1 unit more than expected. An example of a format which may exhibit this problem is PNG.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
The DPI to use when exporting graphic images. The maximum value allowed is SCCGRAPHIC_MAX_SANE_BITMAP_DPI, which is currently defined to be 2400 DPI.
Default
SCCGRAPHIC_DEFAULT_OUTPUT_DPI: Currently defined to be 96 dots per inch.
This option is used to set the maximum size of the exported graphic in pixels. It may be used to prevent inordinately large graphics from being converted to equally cumbersome output files, thus preventing bandwidth waste.
SCCOPT_GRAPHIC_SIZELIMIT takes precedence over all other options and settings that affect the size of a converted graphic.
When creating a multi-page TIFF file, this limit is applied on a per page basis. It is not a pixel limit on the entire output file.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
The total number of pixels in the output graphic. A value of zero ("0"), which is equivalent to SCCGRAPHIC_NOLIMIT, causes this option to be ignored.
Default
SCCGRAPHIC_NOLIMIT: Option is turned off.
This option determines the method used to size graphics. The developer can choose among three methods, each of which involves some degree of trade off between the quality of the resulting image and speed of conversion.
Using the quick sizing option results in the fastest conversion of color graphics, though the quality of the converted graphic will be somewhat degraded. The smooth sizing option results in a more accurate representation of the original graphic, as it uses anti-aliasing. Antialiased images may appear smoother and can be easier to read, but rendering when this option is set will require additional processing time. The grayscale only option also uses antialiasing, but only for grayscale graphics, and the quick sizing option for any color graphics.
The smooth sizing option does not work on images which have a width or height of more than 4096 pixels.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
One of the following values:
SCCGRAPHIC_QUICKSIZING: Resize without antialiasing
SCCGRAPHIC_SMOOTHSIZING: Resize using antialiasing
SCCGRAPHIC_SMOOTHGRAYSCALESIZING: Resize using antialiasing for grayscale graphics only (no antialiasing for color graphics)
Default
SCCGRAPHIC_SMOOTHSIZING
This option allows the user to set the color used as the "transparency color" in the output graphic file. Naturally, this option is only used when the selected output graphic file format supports transparency (GIF and PNG only). If the option is not set, the default behavior is to use the same color value that the input file used as the transparency color.
Use the SCCVWRGB(r, g, b) macro to create the color value to pass to this option. The red, green and blue values are percentages of the color from 0-255 (with 255 being 100%). Note that this macro should be used to set a variable of type SCCVWCOLORREF and that variable should then be passed to the set option routine (instead of trying to use the macro as part of the set option call directly).
Since there is no way to "unset" an option once it has been set, the developer may set the option to SCCGRAPHIC_DEFAULTTRANSPARENCYCOLOR if they wish to revert to the default behavior.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
SCCVWCOLORREF
Data
An RGB color value created with the SCCVWRGB(r, g, b) macro.
Default
SCCGRAPHIC_DEFAULTTRANSPARENCYCOLOR: Use the same transparency color as the source document.
This option defines the absolute width in pixels to which exported graphics will be resized. If this option is set and the Section B.1.5.3, "SCCOPT_GRAPHIC_HEIGHT" option is not, the height of the image will be calculated based on the aspect ratio of the source image. The developer should be aware that very large values for this option or SCCOPT_GRAPHIC_HEIGHT could produce images whose size exceeds available system memory, resulting in conversion failure.
If you are exporting a non-graphic file (word processing, spreadsheet or archive) and the settings for SCCOPT_GRAPHIC_HEIGHT and SCCOPT_GRAPHIC_WIDTH do not match the aspect ratio of the original document, the exported image will have whitespace added so that the original file's aspect ratio is maintained.
The settings for the SCCOPT_GRAPHIC_HEIGHTLIMIT and SCCOPT_GRAPHIC_WIDTHLIMIT options can override the setting for SCCOPT_GRAPHIC_WIDTH.
Handle Types
VTDWORD
Scope
Local
Data Type
VTDWORD
Data
The desired absolute width of the output image, in pixels.
Default
0: No absolute width specified.
This option allows a hard limit to be set for how wide in pixels an exported graphic may be. Any images wider than this limit will be resized to match the limit. It should be noted that regardless whether the SCCOPT_GRAPHIC_HEIGHTLIMIT option is set or not, any resized images will preserve their original aspect ratio.
Note that this option differs from the behavior of setting the width of graphics by using SCCOPT_GRAPHIC_WIDTH in that it sets an upper limit on the image width. Images larger than this limit will be reduced to the limit value. However, images smaller than this width will not be enlarged when using this option. Setting the width using SCCOPT_GRAPHIC_WIDTH causes all output images to be reduced or enlarged to be of the specified width.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
The maximum width of the output graphic in pixels. A value of zero is equivalent to SCCGRAPHIC_NOLIMIT, which causes this option to be ignored.
Default
SCCGRAPHIC_NOLIMIT: No absolute width limit specified.
This option allows the developer to specify sub-options unique to the TIFF output file type, in order to control color depth, byte structure and rendering method.
This option is only required if the dwOutputId in the EXOpenExport call is set to FI_TIFF.
When any of the CCITT compression models are used, the color space must be black and white (SCCGRAPHIC_TIFF1BITBW).
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
The EXTIFFOPTIONS structure.
This structure is used by the SCCOPT_IMAGEX_TIFFOPTIONS option to set various options related to TIFF conversion.
EXTIFFOPTIONS is a C data structure defined in sccop.h as follows:
typedef struct
{
VTDWORD dwSize;
VTDWORD dwColorSpace;
VTDWORD dwCompression;
VTDWORD dwByteOrder;
VTDWORD dwTIFFFlags;
VTDWORD dwFillOrder;
} EXTIFFOPTIONS, * LPEXTIFFOPTIONS;
Parameters
dwSize: Must be set to sizeof(EXTIFFOPTIONS).
dwColorSpace: This option will specify the TIFF color depth and color options. The following settings are valid:
SCCGRAPHIC_TIFF1BITBW: 1 bit black and white
SCCGRAPHIC_TIFF8BITPAL: 8 bit palette
SCCGRAPHIC_TIFF24BITRGB: 24 bit RGB (this is the default value for this parameter)
dwCompression: This option will specify the type of compression used in the TIFF file that is generated. The following settings are valid:
SCCGRAPHIC_TIFFCOMPNONE: No compression
SCCGRAPHIC_TIFFCOMPPB: Packbits compression (this is the default value for this parameter)
SCCGRAPHIC_TIFFCOMPLZW: LZW compression
SCCGRAPHIC_TIFFCOMP1D: CCITT – 1D. Please note that when setting this type of compression, dwColorSpace must be set to SCCGRAPHIC_TIFF1BITBW.
SCCGRAPHIC_TIFFCOMPGRP3: CCITT – Group 3 Fax. Please note that when setting this type of compression, dwColorSpace must be set to SCCGRAPHIC_TIFF1BITBW.
SCCGRAPHIC_TIFFCOMPGRP4: CCITT – Group 4 Fax. Please note that when setting this type of compression, dwColorSpace must be set to SCCGRAPHIC_TIFF1BITBW.
dwByteOrder: This option determines the byte order used within the file:
SCCGRAPHIC_TIFFBOBIGE: This will use "big-endian" (Motorola) byte ordering.
SCCGRAPHIC_TIFFBOLITTLEE: This will use "little-endian" (Intel) byte ordering (this is the default value for this parameter).
dwTIFFFlags: These are additional flags for setting other options in a TIFF file:
SCCGRAPHIC_TIFFFLAGS_NONE: No flags are used (this is the default value for this parameter).
SCCGRAPHIC_TIFFFLAGS_ONEFILE: When this flag is set, the output of multiple pages from one input document will generate a single file with a separate image for each page converted.
dwFillOrder: This option determines the fill order used within the file. The value of this element only affects TIFF output when the dwCompression element is set to SCCGRAPHIC_TIFFCOMPGRP3 and the dwColorSpace element is set to SCCGRAPHIC_TIFF1BITBW.
SCCGRAPHIC_TIFF_FILLORDER1: Selects TIFF fill order 1, which is the default for this parameter and is recommended for most TIFF files intended for file stores.
SCCGRAPHIC_TIFF_FILLORDER2: Selects TIFF fill order 2, which is the recommended fill order for TIFF files intended for electronic transmission (for example, fax).
This option allows the developer to specify the lossyness of JPEG compression. The option is only valid if the dwOutputID parameter of the EXOpenExport function is set to FI_JPEGFIF.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
A value from 1 to 100, with 100 being the highest quality but the least compression, and 1 being the lowest quality but the most compression.
Default
100
This section discusses spreadsheet and database options.
This option scales a spreadsheet file to a certain percent or to a page width or height. However, in an effort to preserve readability after scaling, Image Export will not shrink a database document to under approximately one-third of its original size.
It should be noted that when this option is set to SCCVW_DBPRINTFITMODE_NOMAP, the pages of the database file are printed down first and then across.
Please note that any margins applied as a result of settings for the SCCOPT_DEFAULTPRINTMARGINS option will be included in any scaling that is applied to the output image as a result of settings for this option.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
One of the following values:
SCCVW_DBPRINTFITMODE_NOMAP: This will not do any scaling of the database image. It will render in its original size onto as many pages as are required to fit the data.
SCCVW_DBPRINTFITMODE_FITTOPAGES: This will fit the database to one page, scaling to the image width or height depending on the page size and database size.
SCCVW_DBPRINTFITMODE_FITTOWIDTH: This will scale the database on the rendered image so it is no larger than one page wide.
SCCVW_DBPRINTFITMODE_FITTOHEIGHT: This will scale the database on the rendered image so it is no larger than one page high.
Default
SCCVW_DBPRINTFITMODE_FITTOPAGES
If this option is TRUE, lines are generated between cells in the rendered images.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTBOOL
Default
TRUE
If this option is TRUE, field headings will be generated along with the data.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTBOOL
Default
TRUE
Normally, the size of images generated from spreadsheet worksheets and database tables is limited to the size of the page defined by the input document's page size information and how the SCCOPT_USEDOCPAGESETTINGS, SCCOPT_GRAPHIC_WIDTH and SCCOPT_GRAPHIC_HEIGHT options are set. If, after scaling is factored in, the resulting image is too large to fit on a single page, it is split up into multiple pages.
The SCCOPT_MAXSSDBPAGEWIDTH and SCCOPT_MAXSSDBPAGEHEIGHT options are used to change the size of a page to match the scaled size of the page being rendered - within limits. The key reason for those limits is that rendering very large pages can easily overwhelm the memory available on the system. When using this feature, a calculation should be made to be sure that the values passed in work within said memory limits. The values for these two options will override the current page dimensions if necessary.
The memory needed may be calculated based on the following:
memory = [max. worksheet/table height (in inches)] x [max. worksheet/table width (in inches)] x [dpi setting]2 x 3 bytes/pixel + a bit extra for the needs of the rest of the conversion
By default, these options are set to the current page dimensions. Users may choose to set only one of the two options if desired. If, for example, only the SCCOPT_MAXSSDBPAGEWIDTH is set, then the height of the page will be based on the normal page height.
When a worksheet or table is larger than the maximum values specified by these options, then the file is rendered on multiple pages, with the requested (larger) page dimensions.
These new options grow the page size (if needed) to match the size of the worksheet or table. This differs from the SCCOPT_GRAPHIC_WIDTH and SCCOPT_GRAPHIC_HEIGHT options, which set an absolute page size without regard to the size of the worksheet or table.
Please see Figure B-1, "Logic Flow for Determining the Page Size of Spreadsheet and Database Pages" for a diagram that clarifies the interactions of all of the options mentioned in this discussion.
If text in cells ends up extending past the edge of the cell and beyond the edge of the page, Image Export writes one or more additional pages for the overflow text.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
The maximum page height (including margins) specified in twips (1440 twips are in 1 inch). If the value specified is smaller than the page height, then Image Export will return a SCCERR_INVALIDMAXSSDBPAGE error.
Default
0: Use the page height defined by the input document's page size information and by the SCCOPT_USEDOCPAGESETTINGS, SCCOPT_GRAPHIC_HEIGHTLIMIT and SCCOPT_GRAPHIC_HEIGHT options.
See the documentation for SCCOPT_MAXSSDBPAGEHEIGHT for a full discussion of how this option works and interacts with other options affecting the page size of images generated from spreadsheet and database pages.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Size
VTDWORD
Data
The maximum page width (including margins) specified in twips (1440 twips are in 1 inch). If the value specified is smaller than the page width, then Image Export will return a SCCERR_INVALIDMAXSSDBPAGE error.
Default
0: Use the page width defined by the input document's page size information and by the SCCOPT_USEDOCPAGESETTINGS, SCCOPT_GRAPHIC_WIDTHLIMIT and SCCOPT_GRAPHIC_WIDTH options.
This option controls the pattern in which the pages are rendered, either across first and then down, or down first and then across.
This option is overridden when the SCCOPT_USEDOCPAGESETTINGS option is set to TRUE and print direction is specified in the input document.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
One of the following values:
SCCVW_SSPRINTDIRECTION_ACROSS: Will specify that pages are printed across first and then down.
SCCVW_SSPRINTDIRECTION_DOWN: Will specify that pages are printed down first and then across.
Default
SCCVW_SSPRINTDIRECTION_DOWN
This option requests that the spreadsheet file be fit to one page.
Please note that any margins applied as a result of settings for the SCCOPT_DEFAULTPRINTMARGINS option will be included in any scaling that is applied to the output image as a result of settings for this option.
This option is overridden when the SCCOPT_USEDOCPAGESETTINGS option is set to TRUE and fitting the page to the printer's image limits is specified in the input document.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
One of the following values:
SCCVW_SSPRINTFITMODE_NOMAP: No scaling is performed on the spreadsheet image. It will render in its original size onto as many pages as are required to fit the data.
SCCVW_SSPRINTFITMODE_FITTOPAGES: Will scale the spreadsheet in the rendered image to fit to the number of pages specified in the SCCOPT_SSPRINTSCALEXHIGH and SCCOPT_SSPRINTSCALEXWIDE options. Since aspect ratio is maintained, the lesser of the two dimensions (width or height) will determine the scale factor. Note that if either SCCOPT_SSPRINTSCALEXHIGH or SCCOPT_SSPRINTSCALEXWIDE is set to 0, the value in the other option will be nullified.
SCCVW_SSPRINTFITMODE_FITTOWIDTH: Will scale the spreadsheet in the rendered image so it is no larger than one page wide.
SCCVW_SSPRINTFITMODE_FITTOHEIGHT: Will scale the spreadsheet in the rendered image so it is no larger than one page high.
SCCVW_SSPRINTFITMODE_SCALE: Will scale the spreadsheet in the rendered image using the scale value stored in the SCCOPT_SSPRINTSCALEPERCENT option.
Default
SCCVW_SSPRINTFITMODE_SCALE; Scales the rendered image of the spreadsheet using the scale value stored in the SCCOPT_SSPRINTSCALEPERCENT option (which is 100 by default).
If this option is TRUE, a line is generated between cells in the rendered image.
This option is overridden when the SCCOPT_USEDOCPAGESETTINGS option is set to TRUE and printing grid lines between cells is specified in the input document.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTBOOL
Default
TRUE
If this option is TRUE, row and column headings will be rendered along with the data.
This option is overridden when the SCCOPT_USEDOCPAGESETTINGS option is set to TRUE and printing column and row headers is specified in the input document.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTBOOL
Default
FALSE
This option will scale spreadsheet pages by the percentage specified. The option has no effect unless the SCCOPT_SSPRINTFITTOPAGE option is set to SCCVW_SSPRINTFITMODE_SCALE.
This option must take a value between 1 and 100. If any value outside of this range is used, the option will be ignored.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Default
100
This option will fit the spreadsheet image to the number of vertical pages specified. The setting for this option will have no effect unless the SCCOPT_SSPRINTFITTOPAGE option is set to SCCVW_SSPRINTFITMODE_FITTOPAGES.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Default
1
This option will fit the spreadsheet image to the number of horizontal pages specified. The setting for this option will have no effect unless the SCCOPT_SSPRINTFITTOPAGE option is set to SCCVW_SSPRINTFITMODE_FITTOPAGES.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Default
1
This option lets you determine whether or not to show hidden rows or columns when rendering spreadsheets. It is used to expand the widths of cells that are hidden by virtue of having their row height or column width reduced to 0. This is a BOOLEAN option that will leave the data hidden when it is FALSE, and show all hidden rows and columns when it is TRUE, displayed using the default row width or default column height.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTBOOL
Data
TRUE: Displays hidden cells.
FALSE: Does not display hidden cells.
Default
FALSE
The setting for this option determines whether or not hidden sheets in a spreadsheet will be included in the output. When set to FALSE (the default), the hidden elements are not written. When set to TRUE, they are placed in the output in the same manner as regular spreadsheet data.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTBOOL
Data
TRUE: Allow hidden data to be placed in the output.
FALSE: Prevent hidden data from being placed in the output.
Default
FALSE
This section discusses page rendering options.
This option specifies the top, left, bottom and right margins in twips from the edges of the image. For instance, setting all the values to 1440 creates a 1-inch margin on all sides. Page margins will only be applied when formatting word processing, database and spreadsheet files.
Please note all margins are applied before scaling with the SCCOPT_DBPRINTFITTOPAGE, SCCOPT_SSPRINTFITTOPAGE, Section B.1.5.3, "SCCOPT_GRAPHIC_HEIGHT", SCCOPT_GRAPHIC_WIDTH, or SCCOPT_GRAPHIC_SIZELIMIT options.
This option is overridden when the SCCOPT_USEDOCPAGESETTINGS option is set to TRUE and print margins are specified in the input document.
This option does not affect the output of bitmap, presentation, vector or archive files.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
The SCCVWPRINTMARGINS structure.
This structure is used by the SCCOPT_DEFAULTPRINTMARGINS option to specify margin settings.
SCCVWPRINTMARGINS is a C data structure defined in sccvw.h as follows:
typedef struct SCCVWPRINTMARGINStag
{
VTDWORD dwTop;
VTDWORD dwBottom;
VTDWORD dwLeft;
VTDWORD dwRight;
} SCCVWPRINTMARGINS, * PSCCVWPRINTMARGINS;
Parameters
dwTop: Margin from the top edge of the image (in twips). Default is 1 inch.
dwBottom: Margin from the bottom edge of the image (in twips). Default is 1 inch.
dwLeft: Margin from the left edge of the image (in twips). Default is 1 inch.
dwRight: Margin from the right edge of the image (in twips). Default is 1 inch.
This option indicates the page that rendering should end on. It is only valid if the option SCCOPT_WHATTOPRINT has the value SCCVW_PRINT_PAGERANGE.
Note that page range settings are one-based and inclusive. Therefore, specifying a range with SCCOPT_PRINTENDPAGE equal to 5 and SCCOPT_PRINTSTARTPAGE equal to 3 would export any of the three pages that follow, if they exist: 3, 4 and 5.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Default
0: The last page at the end of the document.
This option indicates the page rendering should start on. It is only valid if the option SCCOPT_WHATTOPRINT has the value SCCVW_PRINT_PAGERANGE.
Note that page range settings are one-based and inclusive. Therefore, specifying a range with SCCOPT_PRINTENDPAGE equal to 5 and SCCOPT_PRINTSTARTPAGE equal to 3 would export any of the three pages that follow, if they exist: 3, 4 and 5.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Default
0: Printing will begin with the first page of the document.
This option is used to select the document's page layout information when rendering.
If TRUE the document's native (or author selected) page margins, paper size, page scaling and page orientation are used when available from the filter.
The values of the SCCOPT_DEFAULTPRINTMARGINS, SCCOPT_SSPRINTGRIDLINES, SCCOPT_SSPRINTHEADINGS, SCCOPT_SSPRINTDIRECTION, and SCCOPT_SSPRINTFITTOPAGE options are overridden if this option is set to TRUE and the properties associated with those options are specified in the input document. Additionally, print area and page breaks in spreadsheet documents are ignored unless this option is set to TRUE.
If FALSE, the page margins, size, orientation and scaling are set to specific values rather than those in the native document. The page size is forced to 8 1/2" x 11" in portrait orientation, but this may be changed by setting the SCCOPT_GRAPHIC_HEIGHT and/or SCCOPT_GRAPHIC_WIDTH options. The margins are forced 1" all around, but may be changed by setting the defaultMargins option. The scaling for the document will be set to 100%, although this may be changed by setting any of the various scaling options.
It should be noted that this option also affects page orientation for both input spreadsheets and word processing documents.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTBOOL
Default
TRUE
This option indicates whether the whole file or a selected range of pages should be rendered.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
One of the following values:
SCCVW_PRINT_PAGERANGE: The pages in the one-based, inclusive range from SCCOPT_PRINTSTARTPAGE to SCCOPT_PRINTENDPAGE will be printed.
SCCVW_PRINT_ALLPAGES: The entire document will be printed.
Default
SCCVW_PRINT_ALLPAGES
This option is used to control the formatting of numbers. It is useful for setting environment dependent variables related to international support. The default values are retrieved from the operating system for the Windows platform, and are set to logical U.S. defaults on all other platforms.
Data Type
SCCVWNUMBERFORMAT and SCCVWNUMBERFORMAT775 structures
These structures are used to set the SCCID_NUMBERFORMAT option. The fields of the structures allow the developer to control variables related to international support. Please note that the SCCVWNUMBERFORMAT775 structure always assumes 2-digit year data, whereas the SCCVWNUMBERFORMAT structure allows for both 2- and 4-digital year data.
These are C data structures defined in sccvw.h as follows:
typedef struct SCCVWNUMBERFORMAT775tag
{
VTTCHAR cDecimalSep;
VTTCHAR cThousandSep;
VTTCHAR cDateSep;
VTTCHAR cTimeSep;
VTTCHAR szCurrencySymbol[8];
VTTCHAR szAM[8];
VTTCHAR szPM[8];
VTDWORD dwNumBytesAM;
VTDWORD dwNumBytesPM;
VTWORD wCurrencyPosition;
VTWORD wShortDateOrder;
} SCCVWNUMBERFORMAT775, * PSCCVWNUMBERFORMAT775;
typedef struct SCCVWNUMBERFORMATtag
{
VTTCHAR cDecimalSep;
VTTCHAR cThousandSep;
VTTCHAR cDateSep;
VTTCHAR cTimeSep;
VTTCHAR szCurrencySymbol[8];
VTTCHAR szAM[8];
VTTCHAR szPM[8];
VTDWORD dwNumBytesAM
VTDWORD dwNumBytesPM;
VTWORD wCurrencyPosition
VTWORD wShortDateOrder;
VTWORD wShortDateYearDigits;
VTWORD wShortDateMonthDigits;
VTWORD wShortDateDayDigits;
VTWORD wShortDateFlags;
} SCCVWNUMBERFORMAT, * PSCCVWNUMBERFORMAT;
Parameters
cDecimalSep: The character used for the decimal separator when formatting currency.
cThousandSep: The character used for the thousands separator when formatting currency.
cDateSep: The character used to separate years, months, and days when formatting dates. This option only works on variable formats. For example, only one of the several date formats in Microsoft Excel is variable.
cTimeSep: The character used to separate hours, minutes, and seconds when formatting times. This option only works on variable formats. For example, only one of the several time formats in Microsoft Excel is variable.
szCurrencySymbol: The string used for the currency symbol when formatting currency.
szAM: The string used to indicate "AM" when formatting times.
szPM: The string used to indicate "PM" when formatting times.
dwNumBytesAM: Number of bytes of the string stored in szAM.
dwNumBytesPM: Number of bytes of the string stored in szPM.
wCurrencyPosition: Flags that indicate the positioning of the currency symbol when formatting currency. Only six specific filters are supported: SOC6, WG2, WK4, WK6, WPW, and VISO.
SCCVW_CURRENCY_LEADS: The currency symbol is placed before the amount.
SCCVW_CURRENCY_TRAILS: The currency symbol is placed after the amount.
SCCVW_CURRENCY_SPACE: A space is placed between the currency and the amount.
SCCVW_CURRENCY_NOSPACE: A space is not placed between the currency and the amount.
wShortDateOrder: Indicates the order used when formatting short dates (numeric dates). This option only works on variable formats. For example, only one of the several date formats in Microsoft Excel is variable. One of the following:
SCCVW_DATEORDER_MDY: Month, Day, Year
SCCVW_DATEORDER_DMY: Day, Month, Year
SCCVW_DATEORDER_YMD: Year, Month, Date
wShortDateYearDigits: This parameter is specific to the SCCVWNUMBERFORMAT structure. This is the number of digits in the year as specified by the Windows registry entry sShortDate. This option only works on variable formats. For example, only one of the several date formats in Microsoft Excel is variable.
wShortDateMonthDigits: This parameter is specific to the SCCVWNUMBERFORMAT structure. This is the number of digits in the month as specified by the Windows registry entry sShortDate.
wShortDateDayDigits: This parameter is specific to the SCCVWNUMBERFORMAT structure. This is the number of digits in the day as specified by the Windows registry entry sShortDate.
wShortDateFlags: This parameter is specific to the SCCVWNUMBERFORMAT structure. It is reserved for internal use.
The former option SCCOPT_WPMIMEHEADEROUTPUT has been deprecated. This option controls rendering of email headers.
Scope
Global
Data Type
VTDWORD
Data
One of these values:
SCCUT_WP_EMAILHEADERSTANDARD: Displays "To," "From," "Subject," "CC," "BCC," "Date Sent," and "Attachments" header fields only. The filter outputs any fields not listed above as hidden fields, so they will not display.
SCCUT_WP_EMAILHEADERALL: Displays all available email headers.
Default
SCCUT_WP_EMAILHEADERSTANDARD
This section discusses font rendering options.
This option sets the font to use when the chunker-specified font is not available on the system. It is also the font used when the font in source file is not available on the system performing the conversion.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
SCCVWFONTSPEC Structure
This structure is used by various options to specify a font.
SCCVWFONTSPEC is a C data structure defined in sccvw.h as follows:
typedef struct
{
VTTCHAR szFace[40];
VTWORD wHeight;
VTWORD wAttr;
VTWORD wType;
} SCCVWFONTSPEC, * LPSCCVWFONTSPEC;
Parameters
szFace: The name of the font. For example, "Helvetica Compressed." The default is "Arial", however this default is constrained by the fonts available on the system.
wHeight: Size of the font in half points. For example, a value of 24 will produce a 12-point font. This size is only applied when the font size is not known. The default is 10-point, however this default is constrained by the font sizes available on the system.
wAttr: The attributes of the font. This parameter is used primarily by the Outside In Viewer Technology and is currently ignored by ImageExport.
wType: Should be set to 0.
This option sets or gets printer font aliases according to the SCCVWFONTALIAS structure.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
The SCCVWFONTALIAS structure.
This structure is used in the SCCOPT_PRINTFONTALIAS option.
SCCVWFONTALIAS is a C data structure defined in sccvw.h as follows:
typedef struct SCCVWFONTALIAS
{
VTDWORD dwSize;
VTDWORD dwAliasID;
VTDWORD dwFlags;
VTWORD szwOriginal[SCCVW_FONTNAMEMAX];
VTWORD szwAlias[SCCVW_FONTNAMEMAX];
} SCCVWFONTALIAS;
Parameters
dwSize: Must be set by the developer to sizeof(SCCVWFONTALIAS).
dwAliasID: ID of the aliasing in the current list of aliases. In Image Export, the default is that no alias is applied.
dwFlags: The usage of these flags depends on whether this structure is being used with the DASetOption or DAGetOption message. It should be set to one of the following:
SCCVW_FONTALIAS_COUNT (DAGetOption): dwAliasID will be filled with the count of current font aliases for that device.
SCCVW_FONTALIAS_ALIASNAME (DASetOption): The alias of szwAlias for szwOriginal will be used when szwOriginal is not available on the device. When a font alias is added to the list, this can affect the alias count. If an alias already exists for szwOriginal, the new szwAlias will replace it.
SCCVW_FONTALIAS_ALIASNAME (DAGetOption): szwAlias will be filled if there is an alias in the alias list for the font in szwOriginal on that device.
SCCVW_FONTALIAS_GETALIASBYID (DAGetOption): szwAlias and szwOriginal will be filled by the technology for the alias in the numbered slot identified by the ID.
SCCVW_FONTALIAS_GETALIASID (DAGetOption): dwAliasID will be set for the font in szwOriginal. If none exists, the dwAliasID will be 0xFFFFFFF.
SCCVW_FONTALIAS_REMOVEALIASBYID (DASetOption): The alias in that slot will be removed if one exists. When a font alias is removed from the list, this can affect the other alias IDs.
SCCVW_FONTALIAS_REMOVEALIASBYNAME (DASetOption): The alias for the font szwOriginal will be removed from the alias list if one exists. When a font alias is removed from the list, this can affect the other alias IDs.
SCCVW_FONTALIAS_REMOVEALL (DASetOption): The alias list will be cleared out and the count will be zero.
SCCVW_FONTALIAS_USEDEFAULTS (DASetOption): This clears the existing alias list and sets it to a list of default aliases that is variable by platform.
szwOriginal: This represents the original name of a font that will be mapped when this font is not available. This name should be a Unicode string.
szwAlias: This represents the new name of a font that will be used as a replacement for the unmapped font named in szwOriginal. This name should be a Unicode string.
Data
The technology assumes the following default mappings. The first value is the szwOriginal Value, the second is the szwAlias Value.
Chicago = Arial
Geneva = Arial
New York = Times New Roman
Helvetica = Arial
Helv = Arial
times = Times New Roman
Times = Times New Roman
Tms Roman = Times New Roman
Symbol = Symbol
itc zapfdingbats = Zapfdingbats
itc zapf dingbats = Zapfdingbats
This section discusses watermark options.
By default, the watermark image is centered in the middle of the target image.
This option must be set and defined to turn on watermarking support. A value of 0 is default and turns watermarking off. Values (1 to 255) specify a level of transparency. 255 is fully opaque. 1 is very transparent.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
A value between 1 and 255. The value of 0 turns watermarking off.
Default
0
This option needs to be set to specify a watermark file and path.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTLPVOID
Data
A pointer to a buffer containing a null-terminated string. The buffer must contain a path to the file containing the watermark image. The buffer can be no larger than sizeof(IMGWATERMARKPATH) bytes.
Default
There is no default. If you intend to use watermarks, you must set this option.
Indicates whether to scale the watermark image or not. A value of SCCGRAPHIC_WATERMARK_SCALETYPE_NONE means that we blend the watermark onto the original graphic with the original watermark height and width. This is the default value. A value of SCCGRAPHIC_WATERMARK_SCALETYPE_PERCENT means that we will scale the watermark to be a certain percentage of the original watermark's height and width.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
SCCGRAPHIC_WATERMARK_SCALETYPE_NONE: When set means no scaling of the watermark image is to be done.
SCCGRAPHIC_WATERMARK_SCALETYPE_PERCENT: When set means that the watermark image is to be scaled to a percentage of its size. The percentage that is used is set by the SCCOPT_GRAPHIC_WATERMARK_SCALEPERCENT option.
Default
SCCGRAPHIC_WATERMARK_SCALETYPE_NONE
Active when SCCOPT_GRAPHIC_WATERMARK_SCALETYPE is set to SCCGRAPHIC_WATERMARK_SCALETYPE_PERCENT. Values (1 to 100) scale the watermark to be a specified percent of its original size. A value of 100 (default) overlays the target image with the watermark image at its original size; e.g., if the original graphic watermark is 4x4 and the target image is 6x8, the graphic watermark will be scaled to 4x4 to overlay the target image.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTDWORD
Data
Values of 1 to 100 scale the watermark image to a percentage of the watermark image's size.
Default
100
Offset in pixels within target image to adjust watermark position. Default value is 0.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTLONG
Data
The number of pixels to offset the image in the horizontal direction. The watermark image is centered in the middle of target image, and then the watermark image is moved by this many pixels. A positive value moves the watermark towards the right, a negative value moves the watermark towards the left.
Default
0
Offset in pixels to adjust the watermark position within the target image. Default value is 0.
Handle Types
VTHDOC, VTHEXPORT
Scope
Local
Data Type
VTLONG
Data
The number of pixels to offset the image in the vertical direction. The watermark image is centered in the middle of the target image, and then the watermark image is moved by this many pixels. A positive value moves the watermark towards the bottom, and a negative value moves the watermark towards the top.
Default
0
This section discusses callback options.
This is an advanced option that casual users of Image Export may ignore.
This option is used to disable callbacks being made from Image Export. Callbacks that are disabled will behave as if they were made and the developer had returned SCCERR_NOTHANDLED.
The option takes a VTDWORD field of flags. When the flag is set, the callback is enabled. By default, all callbacks are enabled. You can activate multiple callbacks by bitwise OR-ing them together. You can also disable multiple callbacks by bitwise &-ing the SCCEX_CALLBACKFLAG_ALLENABLED value with the one's complement of the corresponding callback flags. The following #defines are to be used for enabling the various callbacks:
| Flag | Associated Callbacks |
|---|---|
| SCCEX_CALLBACKFLAG_CREATENEWFILE | EX_CALLBACK_ID_CREATENEWFILE |
| SCCEX_CALLBACKFLAG_NEWFILEINFO | EX_CALLBACK_ID_NEWFILEINFO |
In addition, the following two special values are available:
SCCEX_CALLBACKFLAG_ALLDISABLED: Disables the receipt of all callbacks. Additionally, bitwise OR-ing this value with one or more flags enables the corresponding callbacks. For example, SCCEX_CALLBACKFLAG_ALTLINK | SCCEX_CALLBACKFLAG_CREATENEWFILE enables the ALTLINK and CREATENEWFILE callbacks, but disables all others.
SCCEX_CALLBACKFLAG_ALLENABLED: Enables the receipt of all callbacks. Additionally, bitwise &-ing this value with the one's complement of one or more flags disables the corresponding callbacks. For example, SCCEX_CALLBACKFLAG_ALLENABLED& (~SCCEX_CALLBACKALTLINK & ~SCCEX_CALLBACKFLAG_CREATENEWFILE) disables the ALTLINK and CREATENEWFILE callbacks, but enables all others.
Handle Types
VTHDOC
Scope
Local
Data Type
VTDWORD
Data
One or more of the valid flags, bitwise OR-ed together
Default
SCCEX_CALLBACKFLAG_ALLENABLED: All callbacks are available to the developer.
This option determines the format of strings used in the callback functions. For those structures that contain a field of type BYTE or LPBYTE, a comparable structure has been added which has a similar field of type WORD or LPWORD. These structures will have the same name as the original structure, with the addition of a "W" at the end.
When this option is set to TRUE, any time a callback uses a structure with a string, it will use the new structure. Also, any strings that the callback function returns will be expected to follow the same guidelines. If the option is set to FALSE, all callbacks will use single-byte character strings.
For example, if this option is set to TRUE, and the EX_CALLBACK_ID_CREATENEWFILE callback is called, the pExportData parameter to the callback will point to an EXURLFILEIOCALLBACKDATAW structure. If the option is set to FALSE, the pCommandOrInfoData parameter will point to an EXURLFILEIOCALLBACKDATA structure.
This option should be set before EXOpenExport is called.
Handle Types
VTHDOC
Scope
Local
Data Type
VTBOOL
Data
One of the following values:
TRUE: Use Unicode strings in callbacks.
FALSE: Do not use Unicode strings in callbacks.
Default
FALSE
This section discusses file sysem options.
This set of three options allows the user to adjust buffer sizes to tailor memory usage to the machine's ability. The numbers specified in these options are in kilobytes. These are advanced options that casual users of Image Export may ignore.
Handle Type
NULL, VTHDOC
Scope
Global
Data Type
SCCBUFFEROPTIONSstructure
Data
A buffer options structure
typedef struct SCCBUFFEROPTIONStag
{
VTDWORD dwReadBufferSize; /* size of the I/O Read buffer
in KB */
VTDWORD dwMMapBufferSize; /* maximum size for the I/O
Memory Map buffer in KB */
VTDWORD dwTempBufferSize; /* maximum size for the memory-
mapped temp files in KB */
VTDWORD dwFlags; /* use flags */
} SCCBUFFEROPTIONS, *PSCCBUFFEROPTIONS;
Parameters
dwReadBufferSize: Used to define the number of bytes that will read from disk into memory at any given time. Once the buffer has data, further file reads will proceed within the buffer until the end of the buffer is reached, at which point the buffer will again be filled from the disk. This can lead to performance improvements in many file formats, regardless of the size of the document.
dwMMapBufferSize: Used to define a maximum size that a document can be and use a memory-mapped I/O model. In this situation, the entire file is read from disk into memory and all further I/O is performed on the data in memory. This can lead to significantly improved performance, but note that either the entire file can be read into memory, or it cannot. If both of these buffers are set, then if the file is smaller than the dwMMapBufferSize, the entire file will be read into memory; if not, it will be read in blocks defined by the dwReadBufferSize.
dwTempBufferSize: The maximum size that a temporary file can occupy in memory before being written to disk as a physical file. Storing temporary files in memory can boost performance on archives, files that have embedded objects or attachments. If set to 0, all temporary files will be written to disk.
dwFlags
SCCBUFOPT_SET_READBUFSIZE 1
SCCBUFOPT_SET_MMAPBUFSIZE 2
SCCBUFOPT_SET_TEMPBUFSIZE 4
To set any of the three buffer sizes, set the corresponding flag while calling dwSetOption.
Default
The default settings for these options are:
#define SCCBUFOPT_DEFAULT_READBUFSIZE 2: A 2KB read buffer.
#define SCCBUFOPT_DEFAULT_MMAPBUFSIZE 8192: An 8MB memory-map size.
#define SCCBUFOPT_DEFAULT_TEMPBUFSIZE 2048: A 2MB temp-file limit.
Minimum and maximum sizes for each are:
SCCBUFOPT_MIN_READBUFSIZE 1: Read one Kbyte at a time.
SCCBUFOPT_MIN_MMAPBUFSIZE 0: Don't use memory-mapped input.
SCCBUFOPT_MIN_TEMPBUFSIZE 0: Don't use memory temp files
SCCBUFOPT_MAX_READBUFSIZE 0x003fffff, SCCBUFOPT_MAX_MMAPBUFSIZE 0x003fffff, SCCBUFOPT_MAX_TEMPBUFSIZE 0x003fffff: These maximums correspond to the largest file size possible under the 4GB DWORD limit.
From time to time, the technology needs to create one or more temporary files. This option sets the directory to be used for those files.
It is recommended that this option be set as part of a system to clean up temporary files left behind in the event of abnormal program termination. By using this option with code to delete files older than a predefined time limit, the OEM can help to ensure that the number of temporary files does not grow without limit.
Note:
This option will be ignored if SCCOPT_REDIRECTTEMPFILE is set.Handle Types
NULL, VTHDOC
Scope
Global
Data Type
SCCUTTEMPDIRSPEC structure
This structure is used in the SCCOPT_TEMPDIR option.
SCCUTTEMPDIRSPEC is a C data structure defined in sccvw.h as follows:
typedef struct SCCUTTEMPDIRSPEC
{
VTDWORD dwSize;
VTDWORD dwSpecType;
VTBYTE szTempDirName[SCCUT_FILENAMEMAX];
} SCCUTTEMPDIRSPEC, * LPSCCUTTEMPDIRSPEC;
There is currently a limitation. dwSpecType describes the contents of szTempDirName. Together, dwSpecType and szTempDirName describe the location of the source file. The only dwSpecType values supported at this time are:
IOTYPE_ANSIPATH: Windows only. szTempDirName points to a NULL-terminated full path name using the ANSI character set and FAT 8.3 (Win16) or NTFS (Win32 and Win64) file name conventions.
IOTYPE_UNIXPATH: X Windows on UNIX platforms only. szTempDirName points to a NULL-terminated full path name using the system default character set and UNIX path conventions.
Specifically not supported at this time are IOTYPE_UNICODEPATH and IOTYPE_REDIRECT.
Users should also note that temporary files created by the technology are not subject to callbacks (such as EX_CALLBACK_ID_CREATENEWFILE) normally made when files are created.
Parameters
dwSize: Set to sizeof(SCCUTTEMPDIRSPEC).
dwSpecType: IOTYPE_ANSIPATH, IOTYPE_UNICODE or IOTYPE_UNIXPATH
szTempDirName: The path to the directory to use for the temporary files. Note that if all SCCUT_FILENAMEMAX bytes in the buffer are filled, there will not be space left for file names.
Default
The system default directory for temporary files. On UNIX systems, this is the value of environment variable $TMP. On Windows systems, it is the value of environment variable %TMP%.
This option determines the maximum amount of memory that the chunker may use to store the document's data, from 4 MB to 1 GB. The more memory the chunker has available to it, the less often it needs to re-read data from the document.
Handle Types
NULL, VTHDOC
Scope
Global
Data Type
VTDWORD
Parameters
SCCDOCUMENTMEMORYMODE_SMALLEST 1 - 4MB
SCCDOCUMENTMEMORYMODE_SMALL 2 - 16MB
SCCDOCUMENTMEMORYMODE_MEDIUM 3 - 64MB
SCCDOCUMENTMEMORYMODE_LARGE 4 - 256MB
SCCDOCUMENTMEMORYMODE_LARGEST 5 - 1 GB
Default
SCCDOCUMENTMEMORYMODE_SMALL 2 - 16MB
This option is set when the developer wants to use redirected IO to completely take over responsibility for the low level IO calls of the temp file.
Handle Types
NULL, VTHDOC
Scope
Global (not persistent)
Data Type
VTLPVOID: pCallbackFunc
Function pointer of the redirect IO callback.
Redirect call back function:
typedef
{
VTDWORD (* REDIRECTTEMPFILECALLBACKPROC)
(HIOFILE *phFile,
VTVOID *pSpec,
VTDWORD dwFileFlags);
There is another option to handle the temp directory, SCCOPT_TEMPDIR. Only one of these two can be set by the developer. The SCCOPT_TEMPDIR option will be ignored if SCCOPT_REDIRECTTEMPFILE is set. These files may be safely deleted when the Close function is called.
This chapter details the Web Services implementation of options in Transformation Server. However, there are links to API-specific information for the C and JAVA client interfaces to the technology within each of the following sections.
An option is defined by an identifier and an associated value. The identifier (hOptions) indicates what particular option is being specified. The option value data must be in a form that conforms to the set of supported data types.
Note that it is not necessarily an error to specify options that are not understood by the export engine, but some transformation engines may require that certain options be specified.
This section applies to character mapping options.
This option is used in cases where Outside In cannot determine the character set used to encode the text of an input file. When all other means of determining the file's character set are exhausted, Outside In will assume that an input document is encoded in the character set specified by this option. This is most often used when reading plain-text files, but may also be used when reading HTML or PDF files.
When the "extended test for text" is enabled (see extendedTestForText), this option will still apply to plain-text input files that are not identified as EBCDIC or Unicode.
This option supersedes the fallbackFormat option for selecting the character set assumed for plain-text files. For backwards compatibility, use of deprecated character-set -related values is still currently supported for fallbackFormat, though internally such values will be translated into equivalent values for the defaultInputCharset. As a result, if an application were to set both options, the last such value set for either option will be the value that takes effect.
Data Type
DefaultInputCharSet
Data
The SOAP representation of the character set to use, from the values in defaultInputCharSetEnum.
This option selects the character used when a character cannot be found in the output character set. This option takes the Unicode value for the replacement character. It is left to the user to make sure that the selected replacement character is available in the output character set.
Data Type
xsd:unsignedShort
Data
The Unicode value for the character to use.
Default
0x002a = "*"
Links
C Client Implementation: XSD_unsignedShort
JAVA Client Implementation: UnsignedShort
This section applies to output options.
This option is only valid on the Linux (Red Hat and Suse) and Solaris Sparc platforms.
When this option is set to true, the technology will attempt to use its internal graphics code to render fonts and graphics. When set to false, the technology will render images using the operating system's native graphics subsystem (X11 on UNIX/Linux platforms). Note that this option only works when at least one of the appropriate output solutions is present. For example, if the UNIX $DISPLAY variable does not point to a valid X Server, but the OSGD and/or WV_GD modules required for the Outside In output solution exist, Outside In will default to the Outside In rendering code. The option will fail if neither of these output solutions is present.
It is important for the system to be able to locate useable fonts when this option is set to true. Only TrueType fonts (*.ttf or *.ttc files) are currently supported. To ensure that the system can find them, make sure that the environment variable GDFONTPATH includes one or more paths to these files. If the variable GDFONTPATH can't be found, the current directory is used. If fonts are called for and cannot be found, Image Export will exit with an error. Also note that when copying Windows fonts to a UNIX system, the font extension for the files (*.ttf or *.ttc) must be lowercase, or they will not be detected during the search for available fonts. Oracle does not provide fonts with any Outside In product.
If preferOITRendering is set in a particular instance of tsagent, it cannot be changed in that agent until the agent is terminated.
Data Type
xsd:boolean
Data
One of the following values:
true: Use the technology's internal graphics rendering code to produce bitmap output files whenever possible.
false: Use the operating system's native graphics subsystem.
Default
false
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
This section discusses input handling options.
This option controls how files are handled when their specific application type cannot be determined. This normally affects all plain-text files, because plain-text files are generally identified by process of elimination, for example, when a file isn't identified as having been created by a known application, it is treated as a plain-text file.
It is recommended that noFallbackFormat be set to prevent Image Export from exporting unidentified binary files as though they were text, which could generate many pages of "garbage" output.
A number of values that were formerly allowed for this option have been deprecated. Specifically, the values that selected specific plain-text character sets are no longer to be used. Instead, applications should use the defaultInputCharset option for such functionality.
Data Type
FallbackFormatEnum
Data
One of the following values:
fallbackToText: Unidentified file types will be treated as text files.
noFallbackFormat: Outside In will not attempt to process files whose type cannot be identified. This will include text files. When this option is selected, an attempt to process a file of unidentified type will cause Outside In to return an error value of SCCERR_UNSUPPORTEDFORMAT.
Default
ASCII-8
Links
C Client Implementation: OIT_FallbackFormatEnum
JAVA Client Implementation: FallbackFormatEnum
This option affects how an input file's internal format (application type) is identified when the file is first opened by the Outside In technology. When the extended test flag is in effect, and an input file is identified as being either 7-bit ASCII, EBCDIC, or Unicode, the file's contents will be interpreted as such by the export process.
The extended test is optional because it requires extra processing and cannot guarantee complete accuracy (which would require the inspection of every single byte in a file to eliminate false positives.)
Data Type
xsd:boolean
Data
One of the following values:
false: This is the default value. When this is set, standard file identification behavior occurs.
true: If set, the File Identification code will run an extended test on all files that are not identified.
Default
true: The technology will attempt an extra test after the file is first opened to see if it is 7-bit text or EBCDIC.
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
This option can disable the password verification of files where the contents can be processed without validation of the password. If this option is not set, the filter should prompt for a password if it handles password-protected files.
As of Release 8.3.5, only the PST Filter supports this option.
Data Type
xsd:boolean
Data
true: Ignore validation of the password
false: Prompt for the password
Default
false
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
This option allows the user to define an offset to GMT that will be applied during date formatting, allowing date values to be displayed in a selectable time zone. This option affects the formatting of numbers that have been defined as date values (e.g., most dates in spreadsheet cells). This option will not affect dates that are stored as text.
Data Type
xsd:int
Data
Integer parameter from -96 to 96, representing 15-minute offsets from GMT. To query the operating system for the time zone set on the machine, specify the numeric value of 61440 (0xF000 in hexadecimal).
Default
0: GMT time
Links
C Client Implementation: XSD_int
JAVA Client Implementation: Integer
This section discusses compression options.
This option can disable access to any files using JPEG compression, such as JPG graphic files or TIFF files using JPEG compression, or files with embedded JPEG graphics. Attempts to read or write such files when this option is enabled will fail and return the error SCCERR_UNSUPPORTEDCOMPRESSION if the entire file is JPEG compressed, and grey boxes for embedded JPEG-compressed graphics.
The following is a list of file types affected when this option is disabled:
JPG files
Postscript files containing JPG images
PDFs containing JPEG images
Note that the setting for this option overrides the requested output graphic format when there is a conflict.
Data Type
xsd:boolean
Data
true: Allow access to files that use JPEG compression
false: Do not allow access to files that use JPEG compression
Default
true
This option can disable access to any files using Lempel-Ziv-Welch (LZW) compression, such as .GIF files, .ZIP files or self-extracting archive (.EXE) files containing "shrunk" files. Attempts to read or write such files when this option is enabled will fail and return the error SCCERR_UNSUPPORTEDCOMPRESSION if the entire file is LZW compressed, and grey boxes for embedded LZW-compressed graphics.
The following is a list of file types affected when this option is disabled:
GIF files
TIF files using LZW compression: TIF files will still be created when LZW compression is used and this option is enabled, but the resulting images will be large, uncompressed TIF files)
PDF files that use internal LZW compression
ZIP and self-extracting archive (.EXE) files containing "shrunk" files
Postscript files using LZW compression
Image Export will not be affected by this option when processing formats that compress subfile contents but not subfile names, such as TAR and ZIP.
Although this option can disable access to files in ZIP or EXE archives stored using LZW compression, any files in such archives that were stored using any other form of compression will still be accessible.
The setting for this option overrides the requested output graphic format when there is a conflict.
Data Type
xsd:boolean
Data
true: LZW compressed files will be read and written normally.
false: LZW compressed files will not be read or written.
Default
true
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
This section discusses graphics options.
This option allows the developer to specify interlaced or non-interlaced GIF output. Interlaced GIFs are useful when graphics are to be downloaded over slow Internet connections. They allow the browser to begin to render a low-resolution view of the graphic quickly and then increase the quality of the image as it is received. There is no real penalty for using interlaced graphics.
This option is only valid if the dwOutputID parameter of the EXOpenExport function is set to FI_GIF.
Data Type
xsd:boolean
Data
One of the following values:
true: Produce interlaced GIFs.
false: Produce non-interlaced GIFs.
Default
true
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
When set to cropToContent, this option forces Image Export to crop whitespace from the edge of each output image. This includes margins and any unused space at the end of a page. This results in smaller output files without any loss of original input document content.
If there is no content, then no cropping is performed.
Data Type
GraphicCroppingEnum
Data
cropToContent: Files are cropped to smallest bounding rectangle.
noCropping: Files are not cropped.
Default
noCropping
Links
C Client Implementation: OIT_GraphicCroppingEnum
JAVA Client Implementation: GraphicCroppingEnum
This option defines the absolute height in pixels to which exported graphics will be resized. If this option is set and the graphicWidth option is not, the width of the image will be calculated based on the aspect ratio of the source image. The developer should be aware that very large values for this option or graphicWidth could produce images whose size exceeds available system memory, resulting in conversion failure.
If you are exporting a non-graphic file (word processing, spreadsheet or archive) and the settings for graphicHeight and graphicWidth do not match the aspect ratio of the original document, the exported image will have whitespace added so that the original file's aspect ratio is maintained.
The settings for the graphicHeightLimit and graphicWidthLimit options can override the setting for graphicHeight.
Handle Types
VTDWORD
Scope
Local
Data Type
xsd:unsignedInt
Data
The desired absolute height of the output image, in pixels.
Default
0: No absolute height specified.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option allows a hard limit to be set for how tall in pixels an exported graphic may be. Any images taller than this limit will be resized to match the limit. It should be noted that regardless of whether the graphicWidthLimit option is set or not, any resized images will preserve their original aspect ratio.
Note that this option differs from the behavior of setting the height of graphics by using in that it sets an upper limit on the image height. Images larger than this limit will be reduced to the limit value. However, images smaller than this height will not be enlarged when using this option. Setting the height using graphicHeight causes all output images to be reduced or enlarged to be of the specified height.
Data Type
xsd:unsignedInt
Data
The maximum height of the output graphic in pixels. A value of zero causes this option to be ignored.
Default
0: No absolute height limit specified.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option allows the user to specify the output graphics device's resolution in DPI and only applies to images whose size is specified in physical units (in/cm). For example, consider a 1" square, 100 DPI graphic that is to be rendered on a 50 DPI device (graphicOutputDPI is set to 50). In this case, the size of the resulting TIFF, BMP, JPEG, GIF, or PNG will be 50 x 50 pixels.
You may also specify the value 0 for the DPI, which will cause the output image to be created with identical pixel dimensions as the original input image, without consideration for physical measurements of image size.
Setting this option to 0 may result in the creation of extremely large images. Be aware that there may be limitations in the system running this technology that could result in undesirably large bandwidth consumption or an error message. Additionally, an out of memory error message will be generated if system memory is insufficient to handle a particularly large image.
Also note that the 0 setting will force the technology to use the DPI settings already present in raster images, but will use the current screen resolution as the DPI setting for any other type of input file.
For some output graphic types, there may be a discrepancy between the value set by this option and the DPI value reported by some graphics applications. The discrepancy occurs when the output format uses metric units (DPM, or dots per meter) instead of English units (DPI, or dots per inch). Depending on how the graphics application performs rounding on meters to inches conversions, the DPI value reported may be 1 unit more than expected. An example of a format which may exhibit this problem is PNG.
Data Type
xsd:unsignedInt
Data
The DPI to use when exporting graphic images. The maximum value allowed is 2400 DPI.
Default
96: 96 dots per inch.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option is used to set the maximum size of the exported graphic in pixels. It may be used to prevent inordinately large graphics from being converted to equally cumbersome output files, thus preventing bandwidth waste.
graphicSizeLimit takes precedence over all other options and settings that affect the size of a converted graphic.
When creating a multi-page TIFF file, this limit is applied on a per page basis. It is not a pixel limit on the entire output file.
Data Type
xsd:unsignedInt
Data
The total number of pixels in the output graphic. A value of zero ("0") causes this option to be ignored.
Default
0: Option is turned off.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option determines the method used to size graphics. The developer can choose among three methods, each of which involves some degree of trade off between the quality of the resulting image and speed of conversion.
Using the quick sizing option results in the fastest conversion of color graphics, though the quality of the converted graphic will be somewhat degraded. The smooth sizing option results in a more accurate representation of the original graphic, as it uses anti-aliasing. Antialiased images may appear smoother and can be easier to read, but rendering when this option is set will require additional processing time. The grayscale only option also uses antialiasing, but only for grayscale graphics, and the quick sizing option for any color graphics.
The smooth sizing option does not work on images which have a width or height of more than 4096 pixels.
Data Type
GraphicSizeMethodEnum
Data
One of the following values:
quick: Resize without antialiasing
smooth: Resize using antialiasing
smoothGray: Resize using antialiasing for grayscale graphics only (no antialiasing for color graphics)
Default
smooth
Links
C Client Implementation: OIT_GraphicSizeMethodEnum
JAVA Client Implementation: GraphicSizeMethodEnum
This option allows the user to set the color used as the "transparency color" in the output graphic file. Naturally, this option is only used when the selected output graphic file format supports transparency (GIF and PNG only). If the option is not set, the default behavior is to use the same color value that the input file used as the transparency color.
Use the SCCVWRGB(r, g, b) macro to create the color value to pass to this option. The red, green and blue values are percentages of the color from 0-255 (with 255 being 100%). Note that this macro should be used to set a variable of type xsd:unsignedInt and that variable should then be passed to the set option routine (instead of trying to use the macro as part of the set option call directly).
Since there is no way to "unset" an option once it has been set, the developer may set the option to -1 if they wish to revert to the default behavior.
Data Type
xsd:unsignedInt
Data
An RGB color value created with the SCCVWRGB(r, g, b) macro.
Default
-1: Use the same transparency color as the source document.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option defines the absolute width in pixels to which exported graphics will be resized. If this option is set and the graphicHeight option is not, the height of the image will be calculated based on the aspect ratio of the source image. The developer should be aware that very large values for this option or graphicHeight could produce images whose size exceeds available system memory, resulting in conversion failure.
If you are exporting a non-graphic file (word processing, spreadsheet or archive) and the settings for graphicHeight and graphicWidth do not match the aspect ratio of the original document, the exported image will have whitespace added so that the original file's aspect ratio is maintained.
The settings for the graphicHeightLimit and graphicWidthLimit options can override the setting for graphicWidth.
Handle Types
VTDWORD
Scope
Local
Data Type
xsd:unsignedInt
Data
The desired absolute width of the output image, in pixels.
Default
0: No absolute width specified.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option allows a hard limit to be set for how wide in pixels an exported graphic may be. Any images wider than this limit will be resized to match the limit. It should be noted that regardless of whether the graphicHeightLimit option is set or not, any resized images will preserve their original aspect ratio.
Note that this option differs from the behavior of setting the width of graphics by using graphicWidth in that it sets an upper limit on the image width. Images larger than this limit will be reduced to the limit value. However, images smaller than this width will not be enlarged when using this option. Setting the width using graphicWidth causes all output images to be reduced or enlarged to be of the specified width.
Data Type
xsd:unsignedInt
Data
The maximum width of the output graphic in pixels. A value of zero causes this option to be ignored.
Default
0: No absolute width limit specified.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option allows the developer to specify sub-options unique to the TIFF output file type, in order to control color depth, byte structure and rendering method.
This option is only required if the output type is set to tiff.
When any of the CCITT compression models are used, the color space must be black and white (Black and White).
Data Type
TiffOptions is a complexType data structure composed of four elements, corresponding to the color space, compression, byte-ordering and multi-page aspects of generated TIFF files. The elements of this data type are as follows:
Parameters
colorSpace: This element has a data type of TiffColorSpaceEnum, which contains values that specify the TIFF color depth and color options. The following settings are valid:
Black and White: 1 bit black and white
8 Bit Palette: 8 bit palette
24 Bit RGB: 24 bit RGB (this is the default value for this parameter)
compression: This element has a data type of TiffCompressionEnum, which contains values that specify the type of compression used in the TIFF file that is generated. The following settings are valid:
None: No compression
PackBits: Packbits compression (this is the default value for this parameter)
LZW Compression: LZW compression
CCITT - 1D: CCITT – 1D. Please note that when setting this type of compression, colorSpace must be set to Black and White.
CCITT - Group 3 Fax: CCITT – Group 3 Fax. Please note that when setting this type of compression, colorSpace must be set to Black and White.
CCITT - Group 4 Fax: CCITT – Group 4 Fax. Please note that when setting this type of compression, colorSpace must be set to Black and White.
byteOrder: This element has a data type of TiffByteOrderEnum that determines the byte order used within the file:
tiff_big_endian: This will use "big-endian" (Motorola) byte ordering.
tiff_little_endian: This will use "little-endian" (Intel) byte ordering (this is the default value for this parameter).
createOneFile: This element has an xsd:boolean data type that determines whether or not multi-page TIFFs will be created. These are additional flags for setting other options in a TIFF file:
false: A TIFF image will be created for each page of a multi-page input document. No flags are used (this is the default value for this parameter).
true: The output of multiple pages from one input document will generate a single file with a separate image for each page converted.
fillOrder: This element has a data type of TiffFillOrderEnum that determines the fill order used within the file. The value of this element only affects TIFF output when the compression element is set to CCITT - Group 3 Fax and the colorSpace element is set to Black and White.
fillOrder-1: Selects TIFF fill order 1, which is the default for this parameter and is recommended for most TIFF files intended for file stores.
fillOrder-2: Selects TIFF fill order 2, which is the recommended fill order for TIFF files intended for electronic transmission (for example, fax).
Links
C Client Implementation: OIT_TiffOptions
JAVA Client Implementation: TiffOptions
This option allows the developer to specify the lossyness of JPEG compression. The option is only valid if the option is set to jpeg.
Data Type
xsd:unsignedInt
Data
A value from 1 to 100, with 100 being the highest quality but the least compression, and 1 being the lowest quality but the most compression.
Default
100
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This section discusses spreadsheet and database options.
This option scales a spreadsheet file to a certain percent or to a page width or height. However, in an effort to preserve readability after scaling, Image Export will not shrink a database document to under approximately one-third of its original size.
It should be noted that when this option is set to dbNoScaling, the pages of the database file are printed down first and then across.
Please note that any margins applied as a result of settings for the defaultMargins option will be included in any scaling that is applied to the output image as a result of settings for this option.
Data Type
DatabaseFitToPageEnum
Data
One of the following values:
dbNoScaling: This will not do any scaling of the database image. It will render in its original size onto as many pages as are required to fit the data.
dbFitToPages: This will fit the database to one page, scaling to the image width or height depending on the page size and database size.
dbFitToWidth: This will scale the database on the rendered image so it is no larger than one page wide.
dbFitToWidth: This will scale the database on the rendered image so it is no larger than one page high.
Default
dbFitToPages
Links
C Client Implementation: OIT_DatabaseFitToPageEnum.
JAVA Client Implementation: DatabaseFitToPageEnum
If this option is true, lines are generated between cells in the rendered images.
Data Type
xsd:boolean
Default
true
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
If this option is true, field headings will be generated along with the data.
Data Type
xsd:boolean
Default
true
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
Normally, the size of images generated from spreadsheet worksheets and database tables is limited to the size of the page defined by the input document's page size information and how the useDocumentPageSettings, graphicWidth and graphicHeight options are set. If, after scaling is factored in, the resulting image is too large to fit on a single page, it is split up into multiple pages.
The maxSsDbPageWidth and maxSsDbPageHeight options are used to change the size of a page to match the scaled size of the page being rendered - within limits. The key reason for those limits is that rendering very large pages can easily overwhelm the memory available on the system. When using this feature, a calculation should be made to be sure that the values passed in work within said memory limits. The values for these two options will override the current page dimensions if necessary.
The memory needed may be calculated based on the following:
memory = [max. worksheet/table height (in inches)] x [max. worksheet/table width (in inches)] x [dpi setting]2 x 3 bytes/pixel + a bit extra for the needs of the rest of the conversion
By default, these options are set to the current page dimensions. Users may choose to set only one of the two options if desired. If, for example, only the maxSsDbPageWidth is set, then the height of the page will be based on the normal page height.
When a worksheet or table is larger than the maximum values specified by these options, then the file is rendered on multiple pages, with the requested (larger) page dimensions.
These new options grow the page size (if needed) to match the size of the worksheet or table. This differs from the graphicWidth and graphicHeight options, which set an absolute page size without regard to the size of the worksheet or table.
Please see Figure B-1, "Logic Flow for Determining the Page Size of Spreadsheet and Database Pages" for a diagram that clarifies the interactions of all of the options mentioned in this discussion.
If text in cells ends up extending past the edge of the cell and beyond the edge of the page, Image Export writes one or more additional pages for the overflow text.
Data Type
xsd:unsignedInt
Data
The maximum page height (including margins) specified in twips (1440 twips are in 1 inch). If the value specified is smaller than the page height, then Image Export will return a SCCERR_INVALIDMAXSSDBPAGE error.
Default
0: Use the page height defined by the input document's page size information and by the useDocumentPageSettings, graphicHeightLimit and graphicHeight options.
See the documentation for maxSsDbPageHeight for a full discussion of how this option works and interacts with other options affecting the page size of images generated from spreadsheet and database pages.
Data Size
xsd:unsignedInt
Data
The maximum page width (including margins) specified in twips (1440 twips are in 1 inch). If the value specified is smaller than the page width, then Image Export will return a SCCERR_INVALIDMAXSSDBPAGE error.
Default
0: Use the page width defined by the input document's page size information and by the useDocumentPageSettings, graphicWidthLimit and graphicWidth options.
This option lets you determine whether or not to show hidden rows or columns when rendering spreadsheets. It is used to expand the widths of cells that are hidden by virtue of having their row height or column width reduced to 0. This is a BOOLEAN option that will leave the data hidden when it is false, and show all hidden rows and columns when it is true, displayed using the default row width or default column height.
Data Type
xsd:boolean
Data
true: Displays hidden cells.
false: Does not display hidden cells.
Default
false
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
This option controls the pattern in which the pages are rendered, either across first and then down, or down first and then across.
This option is overridden when the useDocumentPageSettings option is set to true and print direction is specified in the input document.
Data Type
SpreadSheetPageDirectionEnum
Data
One of the following values:
acrossThenDown: Will specify that pages are printed across first and then down.
downThenAcross: Will specify that pages are printed down first and then across.
Default
downThenAcross
Links
C Client Implementation: OIT_SpreadsheetPageDirectionEnum
JAVA Client Implementation: SpreadsheetPageDirectionEnum
This option requests that the spreadsheet file be fit to one page.
Please note that any margins applied as a result of settings for the defaultMargins option will be included in any scaling that is applied to the output image as a result of settings for this option.
This option is overridden when the useDocumentPageSettings option is set to true and fitting the page to the printer's image limits is specified in the input document.
Data Type
SpreadsheetFitToPageEnum
Data
One of the following values:
ssNoScaling: No scaling is performed on the spreadsheet image. It will render in its original size onto as many pages as are required to fit the data.
ssFitToPages: Will scale the spreadsheet in the rendered image to fit to the number of pages specified in the spreadsheetScaleXPagesHigh and spreadsheetScaleXPagesWide options. Since aspect ratio is maintained, the lesser of the two dimensions (width or height) will determine the scale factor. Note that if either spreadsheetScaleXPagesHigh or spreadsheetScaleXPagesWide is set to 0, the value in the other option will be nullified.
ssFitToWidth: Will scale the spreadsheet in the rendered image so it is no larger than one page wide.
ssFitToHeight: Will scale the spreadsheet in the rendered image so it is no larger than one page high.
ssScaleByPercentage: Will scale the spreadsheet in the rendered image using the scale value stored in the spreadsheetScalePercentage option.
Default
ssScaleByPercentage: Scales the rendered image of the spreadsheet using the scale value stored in the spreadsheetScalePercentage option (which is 100 by default).
Links
C Client Implementation: OIT_SpreadsheetFitToPageEnum
JAVA Client Implementation: SpreadsheetFitToPageEnum
If this option is true, a line is generated between cells in the rendered image.
This option is overridden when the useDocumentPageSettings option is set to true and printing grid lines between cells is specified in the input document.
Data Type
xsd:boolean
Default
true
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
If this option is true, row and column headings will be rendered along with the data.
This option is overridden when the useDocumentPageSettings option is set to true and printing column and row headers is specified in the input document.
Data Type
xsd:boolean
Default
false
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
This option will scale spreadsheet pages by the percentage specified. The option has no effect unless the spreadsheetFitToPage option is set to ssScaleByPercentage.
This option must take a value between 1 and 100. If any value outside of this range is used, the option will be ignored.
Data Type
xsd:unsignedInt
Default
100
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option will fit the spreadsheet image to the number of vertical pages specified. The setting for this option will have no effect unless the spreadsheetFitToPage option is set to ssFitToPages.
Data Type
xsd:unsignedInt
Default
1
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option will fit the spreadsheet image to the number of horizontal pages specified. The setting for this option will have no effect unless the spreadsheetFitToPage option is set to ssFitToPages.
Data Type
xsd:unsignedInt
Default
1
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This section discusses age rendering options.
This option specifies the top, left, bottom and right margins in twips from the edges of the image. For instance, setting all the values to 1440 creates a 1-inch margin on all sides. Page margins will only be applied when formatting word processing, database and spreadsheet files.
Please note all margins are applied before scaling with the databaseFitToPage, spreadsheetFitToPage, graphicHeight, graphicWidth, or graphicSizeLimit options.
This option is overridden when the useDocumentPageSettings option is set to true and print margins are specified in the input document.
This option does not affect the output of bitmap, presentation, vector or archive files.
Data Type
DefaultMargins
Data
top: Margin from the top edge of the image (in twips). Default is 1 inch.
bottom: Margin from the bottom edge of the image (in twips). Default is 1 inch.
left: Margin from the left edge of the image (in twips). Default is 1 inch.
right: Margin from the right edge of the image (in twips). Default is 1 inch.
Links
C Client Implementation: OIT_DefaultMargins
JAVA Client Implementation: DefaultMargins
This option controls display of email headers in the output.
Data Type
EmailHeaderOutputEnum
Data
One of these values:
emailHeaderStandard: Displays "To," "From," "Subject," "CC," "BCC," "Date Sent," and "Attachments" header fields only. The filter outputs any fields not listed above as hidden fields, so they will not display.
emailHeaderAll: Displays all available email headers.
Default
emailHeaderStandard
Links
C Client Implementation: OIT_EmailHeaderOutputEnum
JAVA Client Implementation: EmailHeaderOutputEnum
This option indicates the page that rendering should end on. It is only valid if the option usePageRange has the value true.
Note that page range settings are one-based and inclusive. Therefore, specifying a range with endPage equal to 5 and startPage equal to 3 would export any of the three pages that follow, if they exist: 3, 4 and 5.
Data Type
xsd:unsignedInt
Default
0: The last page at the end of the document.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option indicates the page rendering should start on. It is only valid if the option usePageRange has the value true.
Note that page range settings are one-based and inclusive. Therefore, specifying a range with endPage equal to 5 and startPage equal to 3 would export any of the three pages that follow, if they exist: 3, 4 and 5.
Data Type
xsd:unsignedInt
Default
0: Printing will begin with the first page of the document.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option is used to select the document's page layout information when rendering.
If true the document's native (or author selected) page margins, paper size, page scaling and page orientation are used when available from the filter.
The values of the defaultMargins, spreadsheetShowGridLines, spreadsheetShowHeadings, spreadsheetPageDirection, and spreadsheetFitToPage options are overridden if this option is set to true and the properties associated with those options are specified in the input document. Additionally, print area and page breaks in spreadsheet documents are ignored unless this option is set to true.
If false, the page margins, size, orientation and scaling are set to specific values rather than those in the native document. The page size is forced to 8 1/2" x 11" in portrait orientation, but this may be changed by setting the graphicHeight and/or graphicWidth options. The margins are forced 1" all around, but may be changed by setting the defaultMargins option. The scaling for the document will be set to 100%, although this may be changed by setting any of the various scaling options.
It should be noted that this option also affects page orientation for both input spreadsheets and word processing documents.
Data Type
xsd:boolean
Default
true
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
This option indicates whether the whole file or a selected range of pages should be rendered.
Data Type
xsd:boolean
Data
One of the following values:
true: The pages in the one-based, inclusive range from startPage to endPage will be printed.
false: The entire document will be printed.
Default
false
Links
C Client Implementation: XSD_boolean
JAVA Client Implementation: Boolean
This section pertains to font rendering options.
This option sets the font to use when the chunker-specified font is not available on the system. It is also the font used when the font in a source file is not available on the system performing the conversion.
Data Type
The DefaultFont option is a complexType data structure composed of two elements. The elements are as follows:
Parameters
fontName: An xsd:string value indicating the name of the font. For example, "Helvetica Compressed." The default is "Arial", however this default is constrained by the fonts available on the system.
height: An xsd:unsignedShort value indicating the size of the font in half points. For example, a value of 24 will produce a 12-point font. This size is only applied when the font size is not known. The default is 10-point, however this default is constrained by the font sizes available on the system.
Links
C Client Implementation: OIT_DefaultFont
JAVA Client Implementation: DefaultFont
This option sets or gets printer font aliases. For example, Chicago=Arial forces Chicago to be rendered as Arial.
Data Type
xsd:string
Data
The xsd:string value takes the form of font=alias, as in this example:
Chicago=Arial
The technology assumes the following default mappings. The first value is the font name, the second is the alias name.
Chicago = Arial
Geneva = Arial
New York = Times New Roman
Helvetica = Arial
Helv = Arial
times = Times New Roman
Times = Times New Roman
Tms Roman = Times New Roman
Symbol = Symbol
itc zapfdingbats = Zapfdingbats
itc zapf dingbats = Zapfdingbats
Links
C Client Implementation: XSD_string
JAVA Client Implementation:String
This section discusses watermark options.
By default, the watermark image is centered in the middle of the target image.
This option must be set and defined to turn on watermarking support. A value of 0 is default and turns watermarking off. Values (1 to 255) specify a level of transparency. 255 is fully opaque. 1 is very transparent.
Data Type
xsd:unsignedInt
Data
A value between 1 and 255. The value of 0 turns watermarking off.
Default
0
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
This option needs to be set to specify a watermark file and path.
Data Type
xsd:string
Data
A pointer to a buffer containing a null-terminated string. The buffer must contain a path to the file containing the watermark image. The buffer can be no larger than sizeof(IMGWATERMARKPATH) bytes.
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
Indicates whether to scale the watermark image or not. A value of scaleWatermarkOff means that we blend the watermark onto the original graphic with the original watermark height and width. This is the default value. A value of scaleWatermarkByPercent means that we will scale the watermark to be a certain percentage of the original watermark's height and width.
Data Type
GraphicWatermarkScaleTypeEnum
Data
scaleWatermarkOff: When set means no scaling of the watermark image is to be done.
scaleWatermarkByPercent: When set means that the watermark image is to be scaled to a percentage of its size. The percentage that is used is set by the graphicWatermarkScalePercent option.
Default
scaleWatermarkOff
Links
C Client Implementation: OIT_GraphicWatermarkScaleTypeEnum
JAVA Client Implementation: GraphicWatermarkScaleTypeEnum
Active when graphicWatermarkScaleType is set to scaleWatermarkByPercent. Values (1 to 100) scale the watermark to be a specified percent of its original size. A value of 100 (default) overlays the target image with the watermark image at its original size; e.g., if the original graphic watermark is 4x4 and the target image is 6x8, the graphic watermark will be scaled to 4x4 to overlay the target image.
Data Type
xsd:unsignedInt
Data
Values of 1 to 100 scale the watermark image to a percentage of the watermark image's size.
Default
100
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
Offset in pixels within target image to adjust watermark position. Default value is 0.
Data Type
xsd:int
Data
The number of pixels to offset the image in the horizontal direction. The watermark image is centered in the middle of target image, and then the watermark image is moved by this many pixels. A positive value moves the watermark towards the right, a negative value moves the watermark towards the left.
Default
0
Links
C Client Implementation: XSD_int
JAVA Client Implementation: Integer
Offset in pixels to adjust the watermark position within the target image. Default value is 0.
Data Type
xsd:int
Data
The number of pixels to offset the image in the vertical direction. The watermark image is centered in the middle of the target image, and then the watermark image is moved by this many pixels. A positive value moves the watermark towards the bottom, and a negative value moves the watermark towards the top.
Default
0
Links
C Client Implementation: XSD_int
JAVA Client Implementation: Integer
This section pertains to file system options.
This option supplies information to OIT when information is required to open an input file. This information may be the password of the file or a support file location.
Further information about how Transformation Server implements this option will be forthcoming.
Used to define the number of bytes that that will read from disk into memory at any given time. Once the buffer has data, further file reads will proceed within the buffer until the end of the buffer is reached, at which point the buffer will again be filled from the disk. This can lead to performance improvements in many file formats, regardless of the size of the document.
Data Type
xsd:unsignedInt
Data
The size of the buffer in kilobytes.
Default
2
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
Used to define a maximum size that a document can be and use a memory-mapped I/O model. In this situation, the entire file is read from disk into memory and all further I/O is performed on the data in memory. This can lead to significantly improved performance, but note that either the entire file can be read into memory, or it cannot. If both of these buffers are set, then if the file is smaller that the dwMMapBufferSize, the entire file will be read into memory, if not, it will be read in blocks defined by the dwReadBufferSize.
Data Type
xsd:unsignedInt
Data
The size of the buffer in kilobytes.
Default
8192
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
The maximum size that a temporary file can occupy in memory before being written to disk as a physical file. Storing temporary files in memory can boost performance on archives, files that have embedded objects or attachments. If set to 0, all temporary files will be written to disk.
Data Type
xsd:unsignedInt
Data
The size of the buffer in kilobytes.
Default
2048
Links
C Client Implementation: XSD_unsignedInt
JAVA Client Implementation: UnsignedInt
