IMAGE

Parameters

imagefilespec

File specification of the image (AMOS-style or native). PNG files with WMF extensions are supported. Note that true metafiles with WMF extensions should be handled by METAFILE.

left, top, right, bottom

Bounding rectangle (within current coordinate system) into which the image will be fit. The image may be stretched to fill the rectangle, depending on the flags argument. Setting the right and/or bottom parameter to 0 will be interpreted as the rightmost and/or bottommost edge of the page. Use 0,0,0,0 to fill the entire page, minus the printer’s physical margins.

flags

Add together the applicable options: caution: table is duplicated in XCALL Ref / AUI Image; update there if you update here

Symbol	Value	Description
IMGF_HALFTONE	&h001	Use halftone print method.
IMGF_SCATTER	&h002	Use scatter print method.
IMGF_STRETCH	&h004	Stretch image to fit bounding rectangle. Other­wise retain aspect ratio, meaning the image will likely be smaller than the rectangle in one of the two dimensions.
IMGF_SCALEQ	&h008	Interpolate—i.e., use hq scaling.
IMGF_FORCEXFER	&h010	(ATE) Force image filespec to be treated as relative to the host and transfer it to the client. Applies to IMGOP_LOAD and IMGOP_LOADDISP.
IMGF_OPTIONAL	&h020	Applies only if imagefilespec is missing. Then: if imagefilespec2 is present, print it. If it is not present, print nothing. Value may also be expressed as the text "Optional." See "Image Is Not Present" discussion, below.
IMGF_OFFSET	&h040	Causes images to be shifted according to the XOFFSET and YOFFSET values. Normally images only obey the XORIGIN and YORIGIN values, ignoring the XOFFSET and YOFFSET values (which allows text to be shifted relative to images when lining up computer-generated forms). But when using multiple XOFFSET and YOFFSET statements to shift/repeat sections of GDI output, the ability to move the images along with everything else is critical.

 

borderwidth

If non-zero, specifies the width, in pixels, of a solid black border to be drawn around the outside of the rectangle

imagefilespec2

File specification of the image to be printed if imagefilespec1 is not present.

rotation

The angle in degrees, as in the SETFONT directive. Note that the image is first rotated, then fitted to the specified coordinates.

pageno

Specifies the page from within a multi-page TIF file. The first page is considered page number one, but 0 or nothing is also treated as 1. Note that to use APEX as a multi-page TIF image viewer, you would need to first use the AUI_IMAGE IMGOP_PAGEINFO operation to determine the number of pages, then generate a series of IMAGE directives, one for each page, probably separated by page breaks.

 

File Locations

A-Shell will look for the referenced image file in the directories pointed to by the environment variables ATECACHE and ATE, if it is not found in the originally specified directory. This is mainly useful for ATE printing, where the host may pre-transfer images to one of the cache directories without having to modify the print file or deal with incompatibilities between the directory structure used on the host and on the ATE client.

See the print filter ATPXFR.SBX in SOSLIB:[907,29] for a way to automate such transfers in conjunction with AUXLOC printing. Also see the A-Shell forum topic "AUXLOC printing with //IMAGE" for a detailed description of the issue.

The GDI print commands IMAGE, XTEXT, and METAFILE will locate the specified file in the same directory as the printfile if it fails to find it in the directory specified in the GDI directive or in the local cache. This is mainly a convenience when printing from another directory. For example, if a printfile BAS:TEST.PRT contains //IMAGE,TEST.JPG,... and you tried to print it from another directory using PRINT BAS:TEST.PRT, versions of A-Shell prior to 995.3 would have failed to find the image test.jpg in the BAS: directory, because you weren't logged there. It also comes in handy when moving print files and their associated images to another location (such as with ASHLPD), since you can combine all the associated files in an arbitrary directory.

Beginning with A-Shell 1111 of 3 May 08, XTEXT, IMAGE, and METAFILE will look for the file in the same directory as the printfile itself, if not found at the location specified, even when the location specified is a UNIX path. This was previously true, since 5.0.999, but only when the original spec was a Windows path. The new logic is mainly of use in ASHLPD or other environments where you generate the GDI printfile under UNIX and then transfer it to Windows.

 

Image Is Not Present

Beginning in A-Shell build 1181 of May 2010: A new flag and optional second filespec parameter have been added to allow more flexibility in handling the case where the specified image is not present. Normally in such a case, the text of the IMAGE command will be printed at the current "cursor" location on the page. If you would rather have nothing printed, then you can specify the new flag IMGF_OPTIONAL (&h020). You may also specify a second image filespec, which, if the first image is not present, will be printed instead. Either or both of these can be useful in cases where the image file name is derived from some other data (such as a part number), but is not always present (i.e. not every part has an associated image). Rather than the application having to check individually for the presence of each one, the IMAGE command can do the work for you.

Note that the IMGF_OPTIONAL value can also be expressed as the text "OPTIONAL", for example:

//IMAGE,p123.jpg,100,100,200,200,OPTIONAL,1,generic.jpg

In this example, if p123.jpg is present, it will be printed. If not, and generic.jpg is present, it will be printed. If neither is present, nothing will be displayed (including no border), and there will be no indication of an error.

Also see the print filter ATPXFR.SBX in SOSLIB:[907,29] and the META GDI directive for alternate approaches to making sure that image files referenced by IMAGE directives are transferred to the client PC before needed during remote (AUXLOC:) printing.

 

History

2013 September, A-Shell 6.1.1362:  Add pageno parameter.

2013 February, A-Shell 6.1.1339:  IMAGE now fully supports printing of PNG images, including with rotation, using the new GDI+ library.

2012 November, A-Shell 6.1.1322:  Add rotation parameter.

2012 November, A-Shell 6.0.1263:  Image position may now be set relative to current position, without knowing your current position on the page. The left and/or top coordinate parameters may be set to -1 to indicate the current horizontal and vertical position. The right and/or bottom coordinate parameters may be set to negative values to indicate width and height, rather than absolute right and bottom positions.For example,

//IMAGE, spec, -1, -1, -100, -200

will scale the image to 100 by 200 units (in the current mapmode) and position it with the upper left corner at the current cursor position.

2012 May, A-Shell 6.0.1249:  Added IMGF_OFFSET