Image
- Join
Declaration
<AMIMAGE ACTIVITY="join" MATCHCASE="YES/NO" SUBFOLDERS="YES/NO" KEEPFOLDERSTRUCT="YES/NO" ARCHIVETURNOFF="YES/NO" OVERWRITE="YES/NO" ISNEWER="YES/NO" ONLYIFEXIST="YES/NO" OVERWRITEREADONLY="YES/NO" OVERWRITEHIDDEN="YES/NO" EXCLUDE="text" RE="YES/NO" ISNEWERTHAN="%DateSerial+TimeSerial%" ISOLDERTHAN="%DateSeria+TimeSerial%" ATTRFILTER="+r+a-s+h+c+e" FIRSTIMAGE="text" SECONDIMAGE="text" JOIN="vertical" DATASET="text" DESTINATIONIMAGE="text" />
Overview
Merges two images side by side (horizontally) or top to bottom (vertically).
Practical usage
Normally used to combine scanned images.
Parameters
General
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Source image 1 | Text | Yes | (Empty) | FIRSTIMAGE="c:\temp\image1" | The path and file name of the first source image. Supported image formats are JPG, JPEG, PNG, BMP, TIF, TIFF, and GIF. Photos, pictures or other graphic content can be combined. This can be a fully qualified path and file name (preferred) or a single file (requires use of the File System - Change folder activity). You can use wildcard characters (for example, * or ?) to specify all files matching a certain mask. You can specify multiple files and file masks by separating each entry with a pipe (|). For example, c:\temp\*.txt|c:\backup\*.bak. See File Masks & Wildcards for more information. |
| Source image 2 | Text | Yes | (Empty) | SECONDIMAGE="c:\temp\image2" | The path and file name of the second source image to combine with the first image. This activity supports merging of different types of images (JPG, JPEG, PNG, BMP, TIF, TIFF, and GIF). Photos, pictures, and other graphic content can be combined. |
| Destination | Text | Yes | (Empty) | DESTINATIONIMAGE="c:\temp\image3" | The
path and file name of the destination image. This allows you to
save your file under a new path, name, and/or type to avoid overwriting
the source (original) file. To overwrite the source file, enter
its original path and file name. NOTE: If performing an overwrite,
make sure to set the Overwrite
if exists
parameter to YES (enabled) in the File
Options
properties. This allows matching files found in the destination
folder to be overwritten. |
| Join type | Text (options) | Yes | Horizontal | JOIN="vertical" | How
the two images should be joined. The available options are:
|
Advanced
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Create and populate dataset | Text | No | (Empty) | DATASET="datasetName" | The name of a dataset to create and populate with information about the results of the activity. For more details, see Datasets . |
File Options
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Exclude mask | Text | No | (Empty) |
|
Omits files matching the masks specified. You can use file names or wildcard masks. You can specify multiple entries by separating them with a pipe (|) (for example, *.txt|*.bak). |
| Regular expression | Yes/No | No | No | RE="YES" | Specifies whether the Exclude mask parameter is a regular expression. If disabled (default), the Exclude mask parameter contains literal text. |
| Only if newer than | Date | No | (Empty) | ISNEWERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" | If enabled, causes this action to only act on files that are newer than the specified date/time. If this parameter is left blank or disabled (default), files with newer than dates are ignored. Click Custom to select from a list of pre-defined date parameters. Select the Expression check box to allow entry of a date/time expression. |
| Only if older than | Date | No | (Empty) | ISOLDERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" | If enabled, causes this action to only act on files that are older than the specified date/time. If this parameter is left blank or disabled (default), files with older than dates are ignored. Click Custom to select from a list of pre-defined date parameters. Select the Expression check box to allow entry of a date/time expression. |
| Overwrite if exists | Yes/No | No | No | OVERWRITE="YES" | If selected, indicates that, if files with matching names already exist in the destination, they are overwritten. If disabled (default), files with matching names are not overwritten, however, an error occurs during runtime stating a file with the same name already exists. |
| Only if newer | Yes/No | No | No | ISNEWER="YES" | If selected, indicates that, if files with matching names already exist in the destination, only source files that are newer overwrite existing files. If disabled (default), all matching files found in the destination folder are overwritten regardless of their date properties. This parameter is active only if the Overwrite if Exists parameter is selected. |
| Only if exists in destination | Yes/No | No | No | ONLYIFEXIST="YES" | If selected, only files that already exist in the destination are copied from the source. All other files, regardless of whether they match the mask or other parameter settings are bypassed. This parameter is disabled by default and becomes active only if the Overwrite if Exist parameter is selected. |
| Overwrite read-only files | Yes/No | No | No | OVERWRITEREADONLY="YES" | If selected, matching files found in the destination folder are overwritten even if they are marked with the read-only attribute. If disabled (default), read-only files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected. |
| Overwrite hidden files | Yes/No | No | No | OVERWRITEHIDDEN="YES" | If selected, matching files found in the destination folder are overwritten even if they are marked with the hidden attribute. If disabled (default), hidden files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected. |
| Include subfolders | Yes/No | No | No | SUBFOLDERS="YES" | If selected, subfolders are searched for files matching the mask specified in the Source parameter. If disabled (default), subfolders are ignored. Only files that exist in the root of the source folder are searched. |
| Preserve folder structure | Yes/No | No | No | KEEPFOLDERSTRUCT="NO" | If selected, subfolders found in the source folder are created in the destination folder and source files are copied into their respective folders. If disabled (default), subfolders are not created in the destination. Instead, source files that exist in these subfolders are copied into the root of the destination folder. This parameter is active only if the Include subfolders parameter is selected. |
| Turn archive attribute off | Yes/No | No | No | ARCHIVETURNOFF="YES" | If selected, specifies that the archive attribute of the source files is OFF. The Windows archive attribute is generally used to track whether a file is backed up. Dsiabling the source file archive attribute indicates to many backup programs that the file is backed up. This parameter is disabled by default. |
| Match case | Yes/No | No | No | MATCHCASE="YES" | If selected (default), the activity is case sensitive. If disabled, the activity is case insensitive, whereas, it does not distinguish between uppercase and lowercase characters. |
File Attributes
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Attributes | Text (Options) | No | (Empty) |
|
Instructs
the activity to filter the files it acts on based on whether
the original attribute settings of the file match the attribute settings
specified in this parameter. For example, if the Read-only
attribute is set to Off
(in visual mode) or "-R"
(in AML mode), only source files where the Read-only attribute is disabled are affected. Source files where the Read-only attribute is enabled are ignored. In visual mode, a group of controls are provided
to assist in the selection of attribute settings. In AML mode,
a single text item must be entered that contains the original
attribute mask of the files you wish to affect. Available options
are:
|
Additional notes
Datasets
A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset with the following fields (rows):
| Name | Type | Return Value |
|---|---|---|
| theDataset.Destination | Text | The path and file name of the output file. |
| theDataset.Message | Number | If theDataset.Result returns 1, this field returns a description of the error. If theDataset.Result returns 0, this field is left blank. |
| theDataset.Result | Number | The runtime result of this activity. If 0 is returned, this activity ran successfully. If 1 is returned, this activity failed with an error. |
| theDataset.Source | Text | The path and file name of the source (original) file. |
Example
NOTE:
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
Description
The following sample task vertically joins two images and saves them as a new image:
Copy
<AMIMAGE ACTIVITY="join" MATCHCASE="YES" OVERWRITE="YES" ISNEWER="YES" FIRSTIMAGE="C:\temp2\am_126.bmp" SECONDIMAGE="C:\temp2\am_127.bmp" JOIN="vertical" DATASET="theDataset" DESTINATIONIMAGE="C:\temp2\am_128.bmp" />