|
Business Process and Data Transformation Language Reference
<code>
|
|
Execute lines of custom code.
Synopsis
<code name='CodeWrittenInBasic'> <![CDATA[ 'invoke custom method "MyApp.MyClass".Method(context.Value) ]]> </code>
The BPL <code> element executes one or more lines of user-written code within a BPL business process. You can use the <code> element to perform special tasks that are difficult to express using the BPL elements. Any properties referenced by the <code> element must be properties within the business process execution context.
The scripting language for a BPL <code> element is specified by the
language attribute of the containing
<process> element. This can be either Caché Basic or ObjectScript. Any expressions found in the business process, as well as lines of code within <code> elements, must use the specified language. If not specified, the default is ObjectScript.
For further information about these Caché programming languages, see:
MVBasic is not supported in <code> elements.
Typically a developer wraps the contents of a <code> element within a
CDATA block so that it is not necessary to escape special XML characters such as the apostrophe (') or the ampersand (&). For example:
<code name="MyCode" language="objectscript">
<![CDATA[ callrequest.Name = request.FirstName & " " & request.LastName]]>
</code>
To ensure you can properly suspend and restore execution of a business process, follow these guidelines when using the <code> element:
-
The execution time should be short; custom code should not tie up the general execution of the business process.
-
Do not allocate any system resources (such as taking out locks or opening devices) without releasing them within the same <code> element.
-
If a <code> element starts a transaction, make sure that the same <code> element ends the transactions in
all possible scenarios; otherwise, the transaction can be left open indefinitely. This could prevent other processing or can cause significant downtime.
-
Do not rely on variables that are not part of the business process execution context. Ensemble automatically restores the contents of the execution context whenever a business process is suspended and later resumed; any other variables will be cleaned up.
Also, InterSystems strongly recommends that instead of including multiple lines of code within <code>, you invoke a class method or a routine that contains the needed code. This approach makes it far easier to test and debug your processing.
The <code> element can refer to the following execution context variables and their properties. Do not use variables not listed here.
Caution:
Like all other execution context variable names,
status is a reserved word in BPL. Do not use it in <code> blocks except to cause the <code> block to exit.
Using <code> to Set the status Variable
status is a business process execution context variable of type
%Status that indicates success or failure.
Note:
Error handling for a BPL business process happens automatically, without your ever needing to test or set the
status value in the BPL source code. The
status value is documented here in case you need to trigger a BPL business process to exit under certain special conditions.
As the BPL business process runs, if at any time
status acquires a failure value, Ensemble immediately terminates the business process and writes the corresponding text message to the
Event Log. This happens regardless of how
status acquired the failure value. Thus, the best way to cause a BPL business process to exit suddenly, but gracefully is to set
status to a failure value.
Statements within a
<code> activity can set
status to a failure value. The BPL business process does not perceive the change in the value of
status until the <code> activity has fully completed. Therefore, if you want a failure
status to cause an immediate exit from a <code> activity, you must place a quit command in the <code> activity immediately after setting a failure value for
status.