DLL - Execute function

Declaration

<AMEXECUTEDLLFUNCTION DLLFILEPATH="text" 
METHODENAME="text" RETURNTYPE="text" 
RESULTVARIABLE="text [variable name]" />

Description: Executes the specified method in a managed or unmanaged dynamic-link library (DLL) and stores the return value of the method in a variable.

WARNING: Incorrect usage of this activity can cause the task to fail or act erratically. Caution should be exercised when calling functions in this manner.

General Parameters

Property

Type

Required

Default

Markup

Description

Dynamic-link library

Text

Yes

(Empty)

DLLFILEPATH=

"newlib.dll"

Specifies the DLL in which to perform this activity on. Navigate to the appropriate DLL file. Thereafter, click the Load button to populate the Type (for managed DLL), Method Name and Method Return Value fields with the queried values.

Type (managed DLL)

Text

Yes

(Empty)

TYPE="newlib.dll"

the DLL class which contains the available methods. After specifying a DLL file in the Dynamic-link library parameter, clicking the Load button will attempt to query available DLL types. Upon a successful query, all discovered types will be populated into this field. Clicking the down arrow corresponding to this field will display a full list of queried type names in which to select from.  

Note: This option is available only for managed DLLs.

Unload DLL after execution

Yes/No

No

Yes

UNLOADDLL="NO"

If set to YES, Enabling this option allows the DLL in use to be unloaded (so it is accessible to other programs or system resources) directly after this action is executed. If this option is disabled, the DLL will not be unloaded until the task has completed (either successfully or unsuccessfully).

Method Name

Text

Yes

(Empty)

METHODENAME="name"

Indicates the DLL method (or operation) to invoke. Upon selection of an available class as specified under the Type parameter, all discovered methods relating to that class will be populated into this field. Clicking the down arrow corresponding to this field will display a full list of queried method names in which to select from.

Method return value type

Text (Options)

Yes

(Empty)

RETURNTYPE="void"

Specifies the type of return value for the method. Click the down arrow to display a drop-down list of available options.

Variable to populate with return value

Text

Yes

(Empty)

RESULTVARIABLE=

"myVar"

Specifies the name of an existing variable to be populated with the return value of the selected method.

Create return complex type structure

Text

No

(Empty)

RESULTSTRUCTURE=

"structname"

Specifies the name of the structure created by the user.

Arguments Parameters

Property

Type

Required

Default

Markup

Description

Type

Text (Options)

No

(Empty)

ArgType="Int16"

Allows you to select the type of argument you want to assign and its value. Click the down arrow to display a drop-down list of available options.

Value

Text (Options)

No

(Empty)

ArgValue="theValue"

The corresponding value to set for the argument type. Click the Add button then enter a value to the argument list. Other options:

  • Move up - Moves the argument up the list.

  • Move down- Moves the argument down the list.

  • Add - Adds a new argument type and value.

  • Modify - Edits an existing argument.

  • Remove - Deletes an existing argument.

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Example

The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.

Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.

Description: Execute DLL function %AMTrigger.Value% from %AMTrigger.TaskLate%. Return type is Single. Place the return value into variable newvariable.

<AMDLL DLLFILEPATH="%AMTrigger.TaskLate%" METHODNAME="%AMTrigger.TaskValue%" RETURNTYPE="Single" RESULTVARIABLE="newvariable" />