Updated May 2008

//METAFILE, metafilespec, leftorg, toporg, right, bottom

METAFILE "plays" an existing Win32 "enhanced" metafile into the current output context, stretching or squeezing as needed to fit within the specified rectangle.

Parameters

metafilespec

File specification of the image (AMOS-style or native)

left, top, right, bottom

Bounding rectangle (within current coordinate system) into which the metafile will be fit.

Comments

A metafile is a device-independent set of instructions for creating graphic output. Metafiles can be created by a number of popular graphics or drawing programs. As an example, you might use a forms-layout program to create a blank form and then output it as a metafile. The form could then be merged with text and images using the METAFILE command. (This would normally be much easier than using TEXTOUT and LINETO commands to create a form.)

The metafile will be played using the current coordinate system, unless the metafile itself changes the coordinate system. Metafiles that are meant to always appear in the same place on the page should set their own mapping accordingly, and should be played back with the origin set to 0,0. On the other hand, metafiles that are meant to be resized and positioned (e.g. a logo or signature) should be setup to start at location 0,0 in the current coordinate system. This way it can be repositioned with the leftorg and toporg parameters, and sized by changing the mapping system.

Technical Note

In all other cases, the mapping modes are based on the origin being at the upper right corner of the page, with the units increasing in the positive direction as you move down and across the page. However, for metafiles, this is only true for mapping mode Text. For all other modes, the origin is still the upper left corner and the horizontal units increase as you move across the page, but the vertical units decrease (i.e. increase in the negative direction) as you move down the page. Consequently, if your metafiles are internally based on a mapping mode other than Text, you must set the same mode prior to playing the metafile (unless the metafile internally sets its own mapping mode.) Regardless of what happens inside the metafile, the current position and mapping mode for subsequent drawing primitives is preserved (i.e. unchanged).

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.

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.