T2.1: Uses Recommended Development Tools and Workflows

Overview

Visual Studio Code has become the recommended IDE for InterSystems IRIS development through the official InterSystems ObjectScript extension. This extension provides syntax highlighting, IntelliSense code completion, debugging capabilities, and direct connectivity to IRIS instances.

Initial Setup

• Install the extension from the VS Code marketplace
• Use the InterSystems Server Manager to define connections to one or more IRIS instances
• Configure through Server Manager UI or by editing settings.json directly

Connection Requirements

• Hostname: IP address or FQDN
• Web Server Port: Typically 52773 for embedded web server
• Namespace: Target namespace for development
• Authentication: Username/password or OAuth2 token-based authentication
• Advanced Options: SSL/TLS settings, web application paths, custom API endpoints

Workspace Features

• Multi-Instance Support: Work with multiple IRIS instances simultaneously
• Environment Switching: Easily switch between development, test, and production environments
• isfs Protocol: Browse and edit code directly on the server
• Client-Side Editing: Export/import workflows with local file editing

Best Practices

• Use source control integration (Git) with client-side editing to maintain version history
• Enable collaborative development through version control
• Use integrated ObjectScript debugger for breakpoints, variable inspection, and stepping through code

Overview

InterSystems IRIS provides multiple debugging approaches to suit different development scenarios.

ZBREAK Command

• Purpose: Set breakpoints at specific code locations with optional conditions and execute actions
• Conditional Breakpoints: Pause execution when a variable reaches a specific value
• Watchpoints: Monitor local variables and trigger actions when values change
• Use Case: Track state changes without manually inspecting each step

BREAK Command

• Static Breakpoints: BREAK without arguments inserts breakpoints directly into code
• Single-Step Execution: BREAK with letter string arguments:
• "L" for line-by-line execution
• "S" for step-by-step execution
• When Hit: Execution suspends and returns to terminal prompt for variable examination and command execution
• Stack Analysis: Use $STACK and related functions to understand call hierarchy

Debug Device Feature

• Run applications on one device while debugging I/O goes to a separate terminal
• Crucial for debugging full-screen applications without disturbing their display

VS Code Integrated Debugger

Modern development typically uses the VS Code ObjectScript extension's integrated debugger:

• Breakpoints: Conditional and unconditional
• Watch Expressions: Monitor specific expressions during execution
• Variable Inspection: Examine current variable values
• Call Stack Navigation: View and navigate the execution stack
• Step Execution: Step over, step into, step out
• Connection: Uses Debug Adapter Protocol for seamless IRIS connectivity

Overview

Docker Compose simplifies the orchestration of containerized IRIS development environments by defining multi-container applications in a YAML configuration file.

Basic Service Configuration

• Image Source: InterSystems IRIS image from Docker Hub or private registry
• Container Name: Unique identifier for the container
• Restart Policies: Define container restart behavior

Port Mapping

• Port 1972: SuperServer connections
• Port 52773: Management Portal and REST APIs
• Custom Ports: Any application-specific ports

Volume Mounts for Data Persistence

• Durable %SYS Approach: Mount external directory to /durable within the container
• Persistent Data: Databases, configuration files, and journal files
• Source Code Volumes: Mount source code directories for live editing from host

Environment Variables

• ISC_DATA_DIRECTORY: Durable %SYS location
• IRIS_PASSWORD: Default credentials
• ISC_CPF_MERGE_FILE: Apply configuration merge files during startup

Advanced Configurations

• Network Definitions: Enable inter-container communication for mirroring, sharding, or distributed cache clusters
• Health Checks: Monitor container status and automatically restart failed services
• depends_on: Ensure containers start in correct order when services have dependencies
• CPF Merge Files: Vary IRIS configurations across containers deployed from the same image for different environments

Overview

InterSystems provides a comprehensive suite of development tools to support various workflows and developer preferences.

Management Portal

• Access: Web-based interface accessible via browser on port 52773
• Development Capabilities:
• Class Editor for defining and compiling classes
• SQL interface for query development and database management
• System Explorer for namespace and configuration management
• Various monitoring and diagnostic tools
• Best For: Quick edits, system configuration, and administrative tasks

Visual Studio Code (Recommended)

• Extension: InterSystems ObjectScript extension
• Modern Features:
• Git version control integration
• Debugging with breakpoints and variable inspection
• IntelliSense code completion
• Multi-language support for ObjectScript with JavaScript, Python, or Java
• Editing Modes:
• Server-side editing via isfs protocol
• Client-side editing with export/import workflows (preferred for source control)

Command-Line Development

• IRIS Terminal: Direct ObjectScript execution, class compilation, global management, system administration
• WebTerminal: Browser-based terminal access for remote development
• Utilities:
• %SYSTEM classes for programmatic system management
• ObjectScript Debugger for terminal-based debugging
• Batch scripts for automated builds and deployments

Tool Selection Guidelines

• VS Code: Daily coding and development work
• Management Portal: Configuration and troubleshooting
• Command-Line: Automation and scripting tasks

Overview

InterSystems IRIS provides a built-in documentation system that generates Class Reference documentation directly from comments in class definitions.

Triple-Slash Comment Syntax

• Format: Use /// at the start of each line
• Position: Must appear at the first column position
• Placement: Consecutive block immediately before the class, property, method, or parameter
• Compilation: Comments are processed and incorporated into auto-generated Class Reference documentation

HTML Markup Support

• Paragraphs: p tags
• Lists: ul/ol/li for ordered and unordered lists
• Headings: h2 and below (not h1)
• Emphasis: strong/em tags
• Code Formatting: Standard code tags

Special InterSystems Tags

• CLASS: Creates links to other class documentation
• METHOD: Links to method documentation
• PROPERTY: Links to property documentation
• EXAMPLE: Formats code samples with syntax highlighting

Best Practices

What to Document:

• All public APIs comprehensively
• Class summaries describing purpose and primary use cases
• Method parameters (types, constraints), return values, exceptions, and side effects
• Property purpose, valid values, and relationships

Documentation Workflow:

• Include code examples using EXAMPLE blocks
• Regular documentation reviews during code reviews
• Follow XHTML standards for cross-browser compatibility

Benefits:

• Reduced onboarding time for new developers
• Decreased support requests
• Living specifications that stay synchronized with implementation changes

Overview

Background execution in InterSystems IRIS enables applications to perform long-running tasks, parallel processing, and asynchronous operations without blocking interactive user sessions.

JOB Command

• Purpose: Creates child processes (jobbed or spawned processes) that execute independently
• Process ID: Each process receives a unique system-generated PID for identification
• Specification: Entry point (label^routine or ##class(package.class).Method), optional parameters, namespace, and device output

Batch Mode Processing

• Use Case: Processes that access large portions of databases (data compaction, bulk imports, reporting)
• Activation: %SYSTEM.Process.BatchFlag(1)
• Behavior: Uses separate caching strategy that limits impact on shared memory buffers
• Key Distinction: A jobbed process runs in the background but may execute in either batch mode or normal mode depending on cache requirements

Process Coordination

• LOCK Commands: Acquire and release locks on global nodes to prevent race conditions
• %SYS.ProcessQuery: Programmatic access to process information for monitoring and management

Best Practices

• Error Handling: Background processes don't have interactive terminals; implement proper error handling
• Logging: Log to files or globals for troubleshooting
• Timeout Mechanisms: Prevent runaway processes
• Graceful Shutdown: Respond to termination signals properly
• Process Pools: Implement task queues to manage background workload efficiently
• Concurrency Control: Use configurable limits and monitoring for resource utilization