Execute DLL Function

Declaration

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

See Also

MSMQ (Microsoft Message Queuing) | Microsoft SharePoint | AS2 (Applicability Statement 2) | Amazon EC2 (Elastic Compute Cloud) | Amazon RDS (Relational Database Service) | Amazon S3 (Simple Storage Service) | Amazon SimpleDB | Amazon SQS (Simple Queue Service)

Description

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

Practical Usage

See Description.

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

Parameters

General Properties

Property

Type

Req'd

Default

Markup

Description

Dynamic-link library

Text

Yes

(Empty)

DLLFILEPATH=

"newlib.dll"

Specifies the DLL to perform the action on. Click the Folder icon to navigate to the appropriate DLL file. Thereafter, click Go 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"

Specifies the DLL class which contains the available methods. After specifying a DLL file in the Dynamic-link library parameter, clicking the Go 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 Properties

Property

Type

Req'd

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"

Allows you to assign a value to the argument. 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 Properties

The Description tab allows you to customize the text description of any step when it appears in the Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab is part of AutoMate's Error Handling functionality which allows you to select / omit specific errors that will cause a particular step to fail.

More about error causes properties

On Error Properties

The On Error tab is part of AutoMate's Error Handling functionality which allows you to determine what the task should do if a particular step encounters an error.

More about on error properties

Additional Notes

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressing F2.

More on variables
More on expressions

More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

 

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

 

<AMEXECUTEDLLFUNCTION DLLFILEPATH="%AMTrigger.TaskLate%" METHODENAME="%AMTrigger.Value%" RETURNTYPE="Single" RESULTVARIABLE="newvariable" />