<code>

Execute lines of custom code.

Syntax

<code name='CodeWrittenInBasic'>
   <![CDATA['invoke custom method "MyApp.MyClass".Method(context.Value)   ]]>
</code>

Details

Attribute or Element	Description
name, disabled, xpos, ypos, xend, yend attribute	See “Common Attributes and Elements.”
<annotation> element	See “Common Attributes and Elements.”

Description

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.

Available Variables

The <code> element can refer to the following execution context variables and their properties. Do not use variables not listed here.

Variable	Purpose
context	The context object is a general-purpose data container for the business process. context has no automatic definition. To define the properties of this object, use the <context> element. That done, you may refer to these properties anywhere inside the <process> element using dot syntax, as in: context.Balance
request	The request object contains any properties of the original request message object that caused this business process to be instantiated. You may refer to request properties anywhere inside the <process> element using dot syntax, as in: request.UserID
response	The response object contains any properties that are required to build the final response message object to be returned by the business process. You may refer to response properties anywhere inside the <process> element using dot syntax, as in: response.IsApproved. Use the <assign> element to assign values to these properties.
status	status is a value of type %Status that indicates success or failure. When a BPL business process starts up, status is automatically assigned a value indicating success. 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. In general, this happens automatically, when unsuccessful values are returned from <call> activities. However, BPL business process code can initiate a sudden, but graceful exit by setting the status value using <assign> or <code>. See the description at the end of this topic.
process	The process object represents the current instance of the BPL business process object (an instance of the BPL class). This object has one property for each property defined in that class. You can invoke methods of the process object; for example: process.SendRequestSync()

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.

When a BPL business process starts up, status is automatically assigned a value indicating success. To test that status has a success value, you can use the macro $$$ISOK(status) in ObjectScript and the method $SYSTEM.Status.IsOK(status) in Basic. If the test returns a True value, status has a success value.

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.

status is available to a BPL business process anywhere inside the <process>. You can refer to status with the same syntax as for any variable of the %Status type, that is: status