This topic describes how to obtain and provide documentation and comments as you build the elements of an Ensemble production.
2.9.1 Online Documentation
When the local Ensemble server is online, it serves documentation in HTML format via a Web browser. The online documentation system gives access to information about core InterSystems technologies and the InterSystems products Ensemble and Caché. You can access the online documentation in any of the following ways:
•
Find the Ensemble cube in the Windows system tray. Click on it to display the Ensemble cube menu. If Ensemble is stopped, start it. Then choose Documentation from the menu.
• Entering the following URL into a browser page on the local Ensemble system, where 57772 is the port number for which your Ensemble server is configured:
• When running Ensemble Studio, choose the Help menu On-line Documentation option.
2.9.2 Class Reference Information
You can supplement the online documentation system with information about the classes you create for an Ensemble production, by placing InterSystems Documatic comments in your class code. These comments automatically appear in the online documentation system under the topic Class Reference
Information.
You have the opportunity to add Documatic comments each time you create a new class, method, property, or query using an Ensemble Studio wizard. If you enter a block of text in the Description
field of the wizard dialog, when you save your changes this text appears in the class in the lines just preceding the Class, Method, Property, or Query label.
Studio inserts three slashes (///) at the far left of each line to indicate that it is a Documatic comment, as shown in the following example.
/// Sample business metric class for Workflow demo
Class Demo.Workflow.WFMetric Extends Ens.BusinessMetric [ ProcedureBlock ] {
/// Active Tasks
Property ActiveTasks As
Ens.DataType.Metric(AUTOHISTORY = 10, RANGELOWER = 0, RANGEUPPER = 50, UNITS = "Tasks")
[ MultiDimensional ]; /// Active Load
Property Load As
Ens.DataType.Metric(AUTOHISTORY = 10, RANGELOWER = 0, RANGEUPPER = 100, THRESHOLDUPPER = 90, UNITS = "%") [ MultiDimensional ];
/// Completed Tasks (since previous day) Property CompletedTasks As
Ens.DataType.Metric(AUTOHISTORY = 10, RANGELOWER = 0, RANGEUPPER = 100, UNITS = "Tasks")
[ MultiDimensional ];
/// Calculate and update the set of metrics for this class Method OnCalculateMetrics() As %Status
{
// set the values of our metrics
// %Instance is the current instance (RoleName in this case) Set tRole = ..%Instance
Set ..ActiveTasks = ##class(EnsLib.Workflow.Engine).BamActiveTasks(tRole) Set ..Load = ##class(EnsLib.Workflow.Engine).BamActiveLoad(tRole)
// Get task since start of previous day Set tStart = $ZDT($H-1,3)
Set ..CompletedTasks =
##class(EnsLib.Workflow.Engine).BamCompletedTasks(tRole,tStart) Quit $$$OK
}
/// Set of instances for this metric class<br>
/// There is one instance for every defined role. Query MetricInstances() As %SQLQuery
{
SELECT Name FROM EnsLib_Workflow.RoleDefinition }
}
Once you compile a class, you can view its generated class documentation as follows. Either: • Start the online documentation system and click the Class Reference Information link,
or:
• Enter the following URL into a browser page on the local Ensemble system, where 1972 is the superserver port number of your Ensemble instance:
http://localhost:1972/Apps/Documatic
You can extend Documatic comments from within Ensemble Studio, either by editing the Description
field for a class in the Studio Inspector window, or by adding lines preceded by three slashes (///) at appropriate locations within the source file. These lines must appear in a consecutive block immediately before the declaration of the class, method, property, or query that they describe, and the first of the three slashes must appear in the first (left-most) position in the line. Studio handles all of this automat- ically when you make these changes by editing and saving the Description field in the Inspector window. If you edit Documatic comments directly in the code, Studio alerts you to Documatic errors: for example, if you insert a blank line between the comments and the declaration, or if you use an insuffi- cient number of slashes at the beginning of a line within a Documatic text block. However, Studio does not alert you to any bad HTML or Documatic syntax that you introduce within a line.
Documatic comments permit any standard HTML element and a small number of specialized Documatic elements, as shown in the following code sample and output display:
• With regard to the allowed HTML elements, use as strict an HTML standard as you can, for example XHTML, to ensure that your comments can be interpreted by any browser.
• For a description of specialized Documatic elements, such as <class>, <method>, <property>, <query>, <parameter>, <example>, and <link>, see the Class Reference Information for
%CSP.Documatic.
2.9.3 Hover Text For Production Settings
If a property definition in an Ensemble host class provide Documatic comments, and if that property is included in the SETTINGS string for the class, context-sensitive help is automatically available for these properties in the configuration display on the [Ensemble] > [Productions] page. Whenever the user hovers the cursor over a property name in the configuration display, the comment text for that property definition displays as a tooltip.
2.9.4 ObjectScript Code Comments
Rules for ObjectScript comments apply wherever you use ObjectScript code, including: • Ensemble class code
• Any <code> elements in BPL, when the scripting language for the business process has been identified as “objectscript” (the default when no language is specified)
• Any <code> elements in DTL, when the scripting language for the data transformation has been identified as “objectscript” (the default when no language is specified)
The double slash // semicolon ; and pound-semicolon pair #; are all single-line comment indicators in ObjectScript. Everything on the line to the right of the indicator is interpreted as a comment.#; comments are suppressed in the compiled routine.
White space can be significant within ObjectScript. In particular, a statement cannot start in the first (left-most) character position on a line. This distinguishes a statement from a label, which does start in first position. Thus, you must make sure whatever comment characters you use are preceded by at least one space on the lines where they appear. For example:
Method OnCalculateMetrics() As %Status {
// Note: these calculations are not accurate; they // are demonstrative.
// set the values of our metrics &sql(SELECT COUNT(*) INTO :count FROM Demo_Loan_Msg.Application) Set ..LoansRequested = count
// set the values of our metrics &sql(SELECT COUNT(*) INTO :count FROM Demo_Loan_Msg.Approval WHERE IsApproved = 1) Set ..LoansApproved = count Quit $$$OK
}
For further details about white space and comments, see the “Syntax Rules” chapter in Using Caché
ObjectScript.
2.9.5 Caché Basic Code Comments
Rules for Caché Basic comments apply wherever you use Caché Basic code, including: • Ensemble class code
• Any <code> elements in BPL, when the scripting language for the business process has been identified as “basic”
• Any <code> elements in DTL, when the scripting language for the data transformation has been identified as “basic”
The following example illustrates several uses of the Rem statement and single-quote ' syntax to provide single-line comments in Caché Basic code:
Dim MyStr1, MyStr2
MyStr1 = "Hello" : Rem Comment after a statement separated by a colon. MyStr2 = "Goodbye" ' This is also a comment; no colon is needed. Rem Comment on a line with no code; no colon is needed.
For further details, see the section “Rem” in the “Caché Basic Commands” chapter of the Caché
Basic Reference.
2.9.6 Annotations in BPL and DTL
BPL and DTL support the <annotation> element for comments that need to be associated with a specific activity within the <process> or <transform> block. The <annotation> element cannot simply appear in any arbitrary location within BPL or DTL. An <annotation> must appear as the child of the element that is annotating. The following example shows a BPL <annotation> element that appears between a beginning <call> tag and an ending </call> tag. This is the correct syntax for annotating a <call> activity.
<call name="BankManana"> <annotation>
<![CDATA[Send an asynchronous request to Bank Manana.]]> </annotation>
</call>
The previous example uses CDATA syntax around the annotation text. This convention is optional, but it lets you use line breaks and special characters such as the apostrophe (') without worrying about XML escape sequences. Note the line break between asynchronous and request in the previous example. This line break is interpreted literally when BPL displays the <call> activity in a BPL diagram. The <annotation> text appears as a commentary on the activity, as follows:
BPL <call> Element Showing <annotation> Text
Both BPL and DTL support the <annotation> element for their activity elements. For language specific details, see these books:
• Ensemble Data Transformation Language Reference
2.9.7 Extended Code Comments in BPL and DTL
If the <annotation> element does not offer wide enough scope for the comments you wish to add, it is possible to add extended code comments within BPL and DTL. However, first you need to be aware of the following caution.
CAUTION: When adding comments to an XData block, as for BPL or DTL, the Studio code view permits you to enter comments using XML format; that is, <!-- and /--> at the beginning and end of each comment line, but saving or compiling the class in the BPL or DTL diagram view strips out the XML comments.
The Ensemble Business Process Language (BPL) offers a <code> element that executes one or more lines of code within a BPL business process. Typically, a developer wraps the contents of a <code> element in a CDATA block to avoid having to worry about escaping special XML characters such as the apostrophe (') or the ampersand (&) .
The <code> block is also useful to provide extended, permanent comments within BPL and DTL code. Comments within the <code> block must uphold the conventions of the scripting language that the <code> block is using. This language can be Caché Basic or ObjectScript. The language is specified by the containing BPL <process> element. If no language is specified, ObjectScript is assumed. The following are two simple examples:
• Caché Basic:
<code><![CDATA[ 'Here are some 'code comments 'in Basic ]]></code>
• ObjectScript:
<code><![CDATA[ // Here are some // code comments
// in ObjectScript ]]></code>
The Ensemble Data Transformation Language (DTL) offers a similar <code> element that executes one or more lines of code within a DTL data transformation. The language within a DTL <code> element can be Caché Basic or ObjectScript. The language is specified by the containing DTL <transform>
element. If no language is specified, ObjectScript is assumed.