Debugging Ensemble Productions CAMTA Meeting 11 th November 2010 John Murray

Ensemble What is an Ensemble Session? A collection of messages Begins when the primary request message enters the Ensemble production Continues to exist while the production generates internal requests and responses to process the primary request Ends when the last internal activity prompted by the primary request is complete Messages of a session can be viewed in EMP [Ensemble] > [Messages] > [Visual Trace] Messages flow between numerous background jobs, in which your code executes to produce the appropriate response for each request

Example: Demo.Loan.FindRateFileService Demo.Loan.FindRateProduction in ENSDEMO FindRateFileService looks for xyz.application textfiles in the input directory Reads file, initiates an Ensemble session to process the application for a loan Moves the file to ‘Sent’ subdirectory Writes initial xyz.record file in the output directory, confirming that the application is being processed Sends messages to three Business Processes BankSoprano BankManana BankUS When all responses are in, writes best offer (or refusal if no offers) to xyz.approval in output directory Session ends

Setting Up Demo.Loan.FindRateProduction Focus on FindRateFileService Create FileIn, Sent and FileOut directories Configure FindRateFileService Point “File Path” to FileIn Point “Archive Path” to Sent Apply settings Configure FindRateFileOperation Point “File Path” to FileOut Apply setting Create textfile with.application extension in FileIn 150:Terry: :USA Disable two business hosts FindRateTCPOperation My Terminal Output Start production Check results

Tracing Developer puts $$$TRACE macros in business host code E.g. $$$TRACE("Got this far") If business host configured to “Log Trace Events” the text will be added to the Event Log Also adds an icon in the Message Trace view

Running in Foreground If business host configured to run in “Foreground”, job will launch an Ensemble Terminal window Trace text appears in terminal window Can place hard BREAK commands in code and use command-line debugger Private pool recommended Awkward on Vista

To Interrupt, You Need INT Ensemble executes OBJ code Not readable by us Lowest level of readable source is INT code This is what debuggers step through INT code may be… Hand-written (e.g. you edit Foo.INT) Generated from a MAC (e.g. Foo.MAC) May contain embedded SQL statements Generated from class definition (e.g. User.Foo.CLS) Generated from BPL If INT code is absent, debugging is almost impossible Execution can still happen, provided OBJ exists

Class Compilation Settings Keep INT code during compilation Studio Tools, Options, Compile tab or Compiler tree-node Check “Keep generated source code” Build, Compile With Options Check “Keep generated source code” Consider checking “Set As Default” Same effect as changing setting in Tools, Options Terminal Use the “k” flag on $system.OBJ.Compile* methods Check default flags for namespace, e.g. SAMPLES>D $system.OBJ.ShowFlags()... Default flags for this namespace =adilo1... SAMPLES> Add “k” to default flags using $system.OBJ.SetFlags

Adding Serenji to the Production Download and install Serenji from Install server-side support routines as per Serenji documentation Load the Ens.Serenji package into ENSLIB Compile during import Load modified versions of InterSystems classes into ENSLIB Export your originals first Compile during import Recompile all classes in production, preserving INT code Add two Serenji business hosts to production Ens.Serenji.Debug (BO) Ens.Serenji.Replay (BP) Update running production, or restart it

Debug by Replaying Locate Demo.Loan.FindRateFileService message in Message Browser Set checkbox alongside it Click “Resend Messages” link Choose Ens.Serenji.Replay from dropdown Remember to click “Set New Target” button Click “Yes” button Serenji window should load Demo.Loan.FindRateDecisionProcessCustom.1 and suspend execution at zOnRequest+1

Stepping Through the Session’s Processing Demonstration

Stepping, Going, Disconnecting “Step In” behaves like “Step Over” if target code is part of Ensemble infrastructure “Go” continues to next soft breakpoint, or to beginning of next message handler Break button is available “Fast Forward” continues to next soft breakpoint Break button not active “Disconnect” allows Ensemble session to complete without further Serenji involvement

Timers While debugging, you need time to think Conditionally disable timers Demo.Loan.BankUS OnRequest method Set tSC =..SetTimer("PT15S") becomes If '##class(Ens.Serenji.API).IsEnabled(##this) Set tSC=..SetTimer("PT15S") Demo.Loan.FindRateDecisionProcessCustom OnRequest method Quit..SetTimer("PT5S") becomes Set tSC = $$$OK If '##class(Ens.Serenji.API).IsEnabled(##this) Set tSC =..SetTimer("PT5S") Quit tSC

BPL State Machine Code Demo.Loan.BankSoprano is defined in BPL Compilation generates INT code Demo.Loan.BankSoprano.Thread1.1 Line label zS1 is where state #1 begins Other states are implemented by zS2, zS3 etc. Demo.Loan.BankManana also defined in BPL “Delay” element in BPL can give similar debug issues to those of timers