How To Create Json Object In Javascript Dynamically

Release Information

About...
Release Notes

New and Enhanced Features for InterSystems IRIS 2021.1
General Upgrade Information
Upgrade Compatibility Checklist for InterSystems IRIS 2021.1
Known Issues and Notes
Deprecated and Discontinued Features
Licensing and Use of InterSystems Web Server

Supported Platforms

Supported Technologies
Supported Languages
Discontinued Platforms and Technologies
Supported Version Interoperability
Cross-Product Technology Matrix

First Looks
Downloading Samples
Searching the Documentation

Deployment

About...
Containers

About...
First Look
Try a Community Edition Container
Running in Containers
InterSystems Cloud Manager

About...
InterSystems Cloud Manager
InterSystems Cloud Manager Guide

ICM Overview
Essential InterSystems Cloud Manager Elements
Using InterSystems Cloud Manager
ICM Reference
Containerless Deployment
Sharing ICM Deployments
Scripting with ICM
Using ICM with Custom and Third-Party Containers
Deploying on a Preexisting Cluster

InterSystems Kubernetes Operator

About...
Using the InterSystems Kubernetes Operator

Installation Kit

About...
Installation Basics
Installation Guide

Preparing to Install InterSystems IRIS
Installing InterSystems IRIS on Microsoft Windows
Installing InterSystems IRIS on UNIX®, Linux, and macOS
Upgrading InterSystems IRIS
Creating and Using an Installation Manifest
Adding UNIX® Installation Packages to an InterSystems IRIS Distribution

Configuration

About...
Automating Configuration
Configuration Parameters

Introduction to the Configuration Parameter File
[Actions]
[ComPorts]
[config]
[ConfigFile]
[Databases]
[Debug]
[Devices]
[DeviceSubTypes]
[ECP]
[ECPServers]
[Gateways]
[IO]
[Journal]
[LicenseServers]
[Map]
[MapMirrors]
[MirrorMember]
[Mirrors]
[Miscellaneous]
[Monitor]
[Namespaces]
[SQL]
[SqlSysDatatypes]
[SqlUserDatatypes]
[Startup]
[Telnet]

Data Migration

About...
Server Migration
ISQL Migration Guide

Overview

Transact-SQL (TSQL) Migration Guide

Planning and Performing TSQL Migration
InterSystems TSQL Constructs
InterSystems TSQL Language Elements
TSQL Commands
TSQL Settings
TSQL Functions
TSQL Variables
TSQL System Stored Procedures

DataMove

Adding Compiled Code

Administration

About...
System Administration

Using the Management Portal
Configuring InterSystems IRIS
Managing InterSystems IRIS
Managing InterSystems IRIS Licensing
Using InterSystems IRIS on Windows
Using InterSystems IRIS on UNIX®, Linux, and macOS
Connecting to Remote Servers
Using Multiple Instances of InterSystems IRIS
Configuring Third-Party Software to Work in Conjunction with InterSystems Products
Feature Tracker Collects Usage Statistics

Monitoring

About...
Monitoring Guide

Monitoring InterSystems IRIS Using the Management Portal
Using the InterSystems Diagnostic Report
Using Log Monitor
Using System Monitor
Gathering Global Activity Statistics Using ^GLOSTAT
Monitoring System Performance Using ^PERFMON
Monitoring Routine Performance Using ^PROFILE
Examining Routine Performance Using ^%SYS.MONLBL
Monitoring Block Collisions Using ^BLKCOL
Monitoring Performance Using ^SystemPerformance
Monitoring Performance Using ^mgstat
Monitoring Processes Using ^PERFSAMPLE
History Monitor
Monitoring InterSystems IRIS Using SNMP
Monitoring InterSystems IRIS Using Web Services
Monitoring InterSystems IRIS Using REST API
Monitoring InterSystems IRIS Using the irisstat Utility

Error Reference

General Error Messages
SQL Error Messages
TSQL Error Messages
System Error Messages
Messages Related to Productions

System Alerting and Monitoring Application

Specialized System Tools and Utilities

Introduction
Using System Classes for National Language Support
Customizing Start and Stop Behavior with ^%ZSTART and ^%ZSTOP Routines
Extending Languages with ^%ZLANG Routines
Controlling InterSystems IRIS from a Windows Client
Using ^GBLOCKCOPY for Fast Global Copies
Using Switches
Notes on Managing InterSystems IRIS via Routines
Process Management
Using cvendian for Byte Order Conversion

Architecture

About...
Mirroring and High Availability

About...
High Availability Solutions
High Availability Guide

Failover Strategies for High Availability
Mirroring Overview
Mirroring Architecture and Planning
Configuring Mirroring
Managing Mirroring
Mirror Outage Procedures

Scalability

About...
First Looks

Scaling for User Volume
Scaling for Data Volume

Scalability Guide

InterSystems IRIS Scalability Overview
Vertically Scaling InterSystems IRIS
Horizontally Scaling for User Volume with Distributed Caching
Horizontally Scaling for Data Volume with Sharding

Resiliency and Data Integrity

About...
First Look
Data Integrity Guide

Introduction to Data Integrity
Write Image Journaling and Recovery
Backup and Restore
Journaling
Data Consistency on Multiple Systems

Security

About...
About InterSystems Security
System Management & Security
Securing Your Instance

Security Strategy
Prepare for InterSystems Security
Tighten Security for an Instance
Security Advisor
Secure InterSystems Processes and Operating-System Resources
Checklist for Hardening Your Deployment

Security Tutorial

Authentication

Authentication Mechanisms
InterSystems Authentication Components and Process
Connection Tools and Access Modes
InterSystems Services
Specifying Authentication Mechanisms
Two-Factor Authentication
Users
Predefined Users
Cascading Authentication
Kerberos Authentication
Operating System Based Authentication
Instance Authentication
Example One: %Service_Console
Example One: %Service_Console (cont.)
Example One: %Service_Console (cont.)
Example One: %Service_Console (cont.)
Example Two: Web
Example Two: Web (cont.)
Delegated Authentication
Delegated Authentication Setup
ZAuthenticate
LDAP Authentication
LDAP Authentication Configuration
Recap

Authorization

Overview
Assets and Resources
Privileges
Public Privileges
Privileges, Roles, and Users
Database Resources
Namespaces
Example Setup
Example One: %Developer and %Operator Roles
Example Two: %Development Resource
Example Three: %DB_USER Resource
Example Four: $SYSTEM.Security.Check
Recap

Securing Applications

Overview
Three Types of Application Definitions
Properties of Application Definitions
Web Application Definitions
Example Setup
Example Setup (cont.)
Example One: Disabling an Application
Example Two: Protecting an Application with a Resource
Example Three: Application Roles
Example Four: Matching and Target Roles
Privileged Routine Applications
Example Setup
Example Setup (cont.)
Example: Creating a Privileged Routine Application Definition
Example: Adding a Routine
Example: Adding Application Roles
Example: Executing the Privileged Routine Application
Java, .NET, and Other Applications
Recap

Connection Tools, Access Modes, Services
Code for Authorization Example
Code for Authentication Example
Code for Privileged Routine Example
Creating a User
Creating a Resource
Creating a Role
Adding a User to a Role

Security for Developers

About...
SOAP Security

Introduction
Setup and Other Common Activities
Creating and Using Policies
WS-Policy Configuration Class Details
Adding Security Elements Manually
Adding Timestamps and Username Tokens
Encrypting the SOAP Body
Encrypting Security Header Elements
Adding Digital Signatures
Using Derived Key Tokens for Encryption and Signing
Combining Encryption and Signing
Validating and Decrypting Inbound Messages
Creating Secure Conversations
Using WS-ReliableMessaging
Creating and Adding SAML Tokens
Troubleshooting Security Problems
Details of the Security Elements

SQL Security
Command-Line Security Utilities

Authentication and Authorization

About...
First Looks

Role-Based Access Control
LDAP

Authentication Guide

Introduction
Kerberos Authentication
Operating System–Based Authentication
Instance Authentication
Delegated Authentication
Two-Factor Authentication
Services
Advanced Topics

Authorization Guide

About InterSystems Authorization
Assets and Resources
Privileges and Permissions
Roles
User Accounts
Applications
Using Delegated Authorization

LDAP Guide

LDAP and InterSystems IRIS®
LDAP Authentication
LDAP Authorization
Other LDAP Topics

OAuth 2.0 & OpenID Connect

Overview of OAuth 2.0 and OpenID Connect
How InterSystems IRIS Supports OAuth 2.0 and OpenID Connect
Using an InterSystems IRIS Web Application as an OAuth 2.0 Client
Using an InterSystems IRIS Web Application as an OAuth 2.0 Resource Server
Using InterSystems IRIS as an OAuth 2.0 Authorization Server
Creating Configuration Items Programmatically
Implementing DirectLogin()
Certificates and JWTs (JSON Web Tokens)

Encryption

About...
First Looks

Database Encryption
Public Key Infrastructure

Public Key Infrastructure
Encryption Guide

About Managed Key Encryption
Key Management Tasks
Using Encrypted Databases
Using Data-Element Encryption
Protecting Against Data Loss
Handling Emergency Situations
Additional Encryption Information
FIPS 140–2 Compliance for Database Encryption

Cryptographic Standards

TLS Guide

About TLS
About Configurations
Configuring the InterSystems IRIS Superserver to Use TLS
Configuring InterSystems IRIS Telnet to Use TLS
Configuring Java Clients to Use TLS with InterSystems IRIS
Configuring .NET Clients to Use TLS with InterSystems IRIS
Configuring Studio to Use TLS with InterSystems IRIS
Connecting from a Windows Client Using a Settings File
Configuring InterSystems IRIS to Use TLS with Mirroring
Configuring InterSystems IRIS to Use TLS with TCP Devices
Configuring the Web Gateway to Connect to InterSystems IRIS Using TLS
Establishing the Required Certificate Chain

Auditing Guide

Embedded Language Development

About...
Data Model
Orientation Guide

Introduction to InterSystems IRIS Programming
A Closer Look at ObjectScript
Classes
Objects
Persistent Objects and InterSystems IRIS SQL
Namespaces and Databases
InterSystems IRIS Security
Localization Support
Server Configuration Options
What's That?
Rules and Guidelines for Identifiers
General System Limits
Numeric Computing in InterSystems Applications

Globals

About...
First Look
Multidimensional Data Access
Using Globals

Introduction
Global Structure
Using Multidimensional Storage (Globals)
SQL and Object Use of Multidimensional Storage
Managing Globals
Temporary Globals and the IRISTEMP Database

ObjectScript

About...
First Look
ObjectScript IDEs

Connecting an IDE
About Visual Studio Code
Using Studio

Introduction to Studio
Creating Class Definitions
Adding Properties to a Class
Adding Methods to a Class
Adding Class Parameters to a Class
Adding Relationships to a Class
Adding Queries to a Class
Adding Indices to a Class
Adding Projections to a Class
Adding XData Blocks to a Class
Adding SQL Triggers and Foreign Keys to a Class
Adding Storage Definitions to a Class
Working with CSP Files
Working with Routines and Include Files
Using the Studio Debugger
Using Studio Templates
Studio Menu Reference
Setting Studio Options
Frequently Asked Questions About Studio

Source Control Integration

Using Terminal

Introduction to the Terminal
Using the Terminal Interactively
Controlling the Appearance and Behavior of the Terminal
Using Terminal Scripts
Script Command Reference
Connecting to Remote Hosts
Using the Terminal in Batch Mode
Advanced Topics

Object Data Access
Using ObjectScript

Introducing ObjectScript
Syntax Rules
Data Types and Values
Variables
Operators and Expressions
Regular Expressions
Commands
Callable User-defined Code Modules
ObjectScript Macros and the Macro Preprocessor
Embedded SQL
Multidimensional Arrays
String Operations
Lock Management
Transaction Processing
Error Processing
Command-line Routine Debugging

Class Definitions

About...
Defining & Using Classes

Basic Ideas in Class Programming
Defining and Compiling Classes
Package Options
Defining and Referring to Class Parameters
Defining and Calling Methods
Working with Registered Objects
Introduction to Persistent Objects
Working with Persistent Objects
Defining Persistent Classes
Defining and Using Literal Properties
Working with Collections
Working with Streams
Defining and Using Object-Valued Properties
Defining and Using Relationships
Other Options for Persistent Classes
Defining Method and Trigger Generators
Defining and Using Class Queries
Defining and Using XData Blocks
Defining Class Projections
Defining Callback Methods
Using and Overriding Property Methods
Defining Data Type Classes
Implementing Dynamic Dispatch
Object-Specific ObjectScript Features
Using the Populate Utility
Using the %Dictionary Classes
Using the Object Synchronization Feature

Class Definition Reference

Class Definitions
Class Keywords
Foreign Key Keywords
Index Keywords
Method Keywords
Parameter Keywords
Projection Keywords
Property Keywords
Query Keywords
Trigger Keywords
XData Keywords
Storage Keywords

Classes Page

ObjectScript Reference

Symbols and Abbreviations
ObjectScript Commands
Routine and Debugging Commands
ObjectScript Functions
ObjectScript Special Variables
Structured System Variables

ObjectScript Tutorial

The Basics

Introduction
Class Methods
Terminal
VS Code - ObjectScript
Do Command
Class Methods and Routines
Method Details
Passing Arguments by Reference
Return and Quit Commands
Write Command
Read Command
Set Command
Operator Precedence
Syntax
Common Errors
Write (again) and Kill Commands
If Construct
Simple Conditions
Complex Conditions
Hands-On Exercise 1
Class Compilation
Controlling Execution Flow
$Case Function
For Construct
While and Do/While Constructs
Try/Catch Construct, and Throw Command
Multiple Purpose Characters
Hands-On Exercise 2
Recap of Part 1

The Good Stuff

Strings
Storing a String
Concatenation Operator
Pattern Matching and Regular Expressions
Pattern Matching Examples
String Functions
String Functions, continued
Lists
Compare Pieces and Lists
Setting Substrings, Pieces, and List Items
More List Functions
Bitstrings
Dates
Hands-On Exercise 3
JavaScript Object Notation (JSON)
Arrays
Ordered Trees
Ordered Trees, continued
Value and Existence, and the $Data Function
Viewing and Killing Arrays
Globals
$Increment and $Sequence Functions
Storage Method
Storage Method, continued
Example of Globals
Hands-On Exercise 4
Recap of Part 2

Using Globals

$Order Function
$Order Function, continued
Working With Indexes
$Order Loop
Nested $Order Loops
Starting Focused $Order Loops
Ending Focused $Order Loops
Hands-On Exercise 5
Conversion Functions
$Get Function
Hands-On Exercise 6
Database Integrity
Lock Command
Lock Command, continued
Lock Command and $Test
Transaction Processing
Hands-On Exercise 7
InterSystems IRIS Objects and SQL
Object Methods
Object Storage
SQL Queries
Recap Of Part 3

RightTriangle Example Class and Exercise Solutions

Right Triangle Example Class
Exercise 1: First Data Entry Class
Exercise 2: Second Data Entry Class
Exercise 3: Third Data Entry Class
Exercise 4: Storage Method
Exercise 5: First Lookup Class
Exercise 6: Second Lookup Class
Exercise 7: Third Lookup Class

%Status Values
Try-Catch
Finding Class References

InterSystems API Manager (IAM)

About...
First Look

About...
First Looks

InterSystems SQL
Optimizing SQL Performance

Using SQL

Introduction to InterSystems SQL
InterSystems SQL Basics
Language Elements
Identifiers
Defining Tables
Defining and Using Views
Relationships Between Tables
Modifying the Database
Querying the Database
Collation
Implicit Joins (Arrow Syntax)
Using Embedded SQL
Using Dynamic SQL
Using the SQL Shell Interface
Using the Management Portal SQL Interface
Importing SQL Code
Using Triggers
Defining and Using Stored Procedures
Storing and Using Stream Data (BLOBs and CLOBs)
Users, Roles, and Privileges
Importing and Exporting SQL Data

Optimizing SQL

Introduction to SQL Performance Optimization
Defining and Building Indices
Optimizing Tables
Cached Queries
Optimizing Query Performance
SQL Performance Analysis Toolkit
Interpreting an SQL Query Plan
SQL Statements
Frozen Plans

InterSystems SQL Reference

Symbols and Syntax Conventions
SQL Commands
SQL Commands for IntegratedML
SQL Predicate Conditions
SQL Aggregate Functions
SQL Window Functions
SQL Functions
SQL Unary Operators
SQL Reference Material

Using the InterSystems SQL Gateway

SQL Gateway Overview
Using the InterSystems SQL Gateway
Connecting the SQL Gateway via JDBC
Connecting the SQL Gateway via ODBC
Using the SQL Gateway Programmatically

Document Database

Introducing InterSystems IRIS Document Database (DocDB)
Managing Documents
REST Client Methods

About...
XML Tools

Introduction to InterSystems XML Tools
Writing XML Output from Objects
Importing XML into Objects
Representing an XML Document as a DOM
Encrypting XML Documents
Signing XML Documents
Using %XML.TextReader
Evaluating XPath Expressions
Performing XSLT Transformations
Customizing How the InterSystems SAX Parser Is Used
Generating Classes from XML Schemas
Generating XML Schemas from Classes
Examining Namespaces and Classes
XML Background

XML Projections

Introduction to Object-XML Projections
Projecting Objects to XML
Controlling Transformations of Values
Handling Empty Strings and Null Values
Controlling the XML Element and Attribute Names
Specifying Namespaces for Elements and Attributes
Controlling the Projection to XML Schemas
Advanced Options for XML Schemas
Special Topics
Summary of XML Projection Parameters

Web Services

About...
Web Gateway Configuration Guide

Installing the Web Gateway
Web Application Architecture
Web Servers for Microsoft Windows
Web Servers for UNIX, Linux, and macOS
Web Gateway Operation and Configuration
Alternative Configurations for Microsoft Windows
Alternative Configurations for UNIX, Linux, and macOS
Apache Considerations UNIX, Linux, and macOS
Building Apache for IBM AIX®
IIS Technical Notes
Using Web Applications with a Remote Web Server

SOAP

About...
Creating SOAP Web Services and Clients

Introduction to Web Services and Web Clients in InterSystems IRIS
Creating SOAP Web Services
SOAP Message Variations
Creating Web Clients
SOAP Fault Handling
Using MTOM for Attachments
Using SOAP with Attachments
Adding and Using Custom Header Elements
Adding and Using WS-Addressing Header Elements
SOAP Session Management
Using the InterSystems IRIS Binary SOAP Format
Using Datasets in SOAP Messages
Fine-Tuning a Web Service in InterSystems IRIS
Fine-Tuning a Web Client in InterSystems IRIS
Troubleshooting SOAP Problems in InterSystems IRIS
Summary of Web Service URLs
Details of the Generated WSDLs
Details of the Generated Classes

REST and JSON

About...
First Look
REST Services

Introduction to Creating REST Services
Using the /api/mgmnt Service
Using the ^%REST Routine to Create REST Services
Using the %REST.API Class to Create REST Services
Modifying the Implementation Class
Modifying the Specification Class
Supporting CORS in REST Services
Using Web Sessions with REST
Securing REST Services
Discovering and Documenting REST APIs
Reference for the /api/mgmnt API
OpenAPI Properties in Use
Creating a REST Service Manually

REST API for Source Code

Introduction to the InterSystems IRIS Source Code File REST API
Source Code File REST API Tutorial
Source Code File REST API Reference

Using JSON

Introduction
Current Page: Creating and Modifying Dynamic Entities
Iteration and Sparse Arrays
Working with Datatypes
Using the JSON Adaptor
Quick Reference for Dynamic Entity Methods

Internet Utilities

Introduction
Sending HTTP Requests
Sending and Receiving Email
Creating, Writing, and Reading MIME Messages
Using FTP
Sending and Receiving IBM WebSphere MQ Messages
Using SSH
Other InterSystems %Net Tools

I/O Device Guide

About I/O Devices
I/O Devices and Commands
Terminal I/O
Local Interprocess Communication
TCP Client/Server Communication
UDP Client/Server Communication
Sequential File I/O
Spool Device
Printers

Advanced Concepts

Locking & Concurrency
Bits & Bitstrings
Structured Logging
Semaphores
String Localization
Process Memory
Work Queue Manager
Secure Logins
Using %Library.File
%UnitTest Tutorial

Unit Testing Overview

What is a Unit Test?
Why Unit Test?
xUnit Testing Frameworks
Structure of %UnitTest and xUnit Frameworks
Test Automation
Test First Methodology
Red – Green – Refactor
Recap

Unit Testing with %UnitTest

What is %UnitTest?
Creating and Executing a Suite of Unit Tests
%UnitTest Classes
Assert Methods and Macros
Creating Classes to Use in the Examples
Example: Creating and Exporting a Test Class
Example: Executing a Test
Example: UnitTest Portal
Example: Viewing the Report in the Unit Test Portal
Setup and Tear Down
Example: Adding Setup and Tear Down Methods to a Test
Example: Executing a Test Using Setup and Tear Down Methods
Options for Executing Tests: Test Specs and Qualifiers
RunTest Examples
DebugRunTestCase
Exercises
Recap

API Index

Tools Index

Glossary

Complete Glossary of Terms

External Language Development

About...
Native APIs
Using InterSystems External Servers

Introduction to InterSystems External Servers
Working with External Languages
Managing External Server Connections
Customizing External Server Definitions
InterSystems External Server Requirements
Quick Reference for the ObjectScript $system.external Interface

Java

About...
First Looks

Java Gateway
Native API for Java
Java Object Persistence with XEP
JDBC and InterSystems Databases

Java Gateway

Introduction to the Java Gateway
Using Dynamic Object Gateways
Using the Java Gateway in a Production
Sample Code
Mapping Specification

Using Java with InterSystems Software

Document Overview
InterSystems Java Connectivity Options
Using the JDBC Driver
Configuration and Requirements
JDBC for Occasional Users
JDBC Quick Reference

Using the Native SDK for Java

Document Overview
Introduction to the Java Native SDK
Calling ObjectScript Methods and Functions
Using Java Inverse Proxy Objects
Working with Global Arrays
Transactions and Locking
Java Native SDK Quick Reference

Persisting Java Objects with InterSystems XEP

Introduction
Using XEP Event Persistence
XEP Quick Reference

Implementing Third Party APIs

Introduction
JDBC Driver Support
Apache Spark Support
Hibernate Support

JDBC

.NET

About...
First Looks

.NET Gateway
Native API for .NET
ADO.NET and InterSystems Products
.NET Object Persistence with XEP
ODBC and InterSystems IRIS

Using the Object Gateway for .NET

Object Gateway Architecture
Setting Object Gateway Server Properties
Running an Object Gateway Server
Using Dynamic Object Gateways
Creating Static Proxy Classes
Sample Code
Mapping Specification
Using the Object Gateway in a Production

Using .NET with InterSystems Software

Introduction
Connecting to the InterSystems Database
Configuration and Requirements
ADO.NET Managed Provider for Occasional Users
Using the Entity Framework Provider
Quick Reference for the .NET Managed Provider

Using the Native API for .NET

Introduction to the Native API
Calling ObjectScript Methods and Functions
Using .NET Reverse Proxy Objects
Working with Global Arrays
Transactions and Locking
Native API for .NET Quick Reference

Persisting .NET Objects with InterSystems XEP

Introduction
Using XEP Event Persistence
XEP Quick Reference

ODBC

About...
Using the InterSystems ODBC Driver

Overview
Defining an ODBC Data Source on Windows
Defining an ODBC Data Source on UNIX®
ODBC Installation and Validation on UNIX® Systems
ODBC Support for Python and Node.js
Logging and Environment Variables

Python

About...
First Look
Using the Native API for Python

Introduction to the Native API
Working with Global Arrays
Calling ObjectScript Methods and Functions
Native API Quick Reference for Python

Node.js

About...
First Look
Using the Native API for Node.js

Introduction to the Native API
Working with Global Arrays
Calling ObjectScript Methods and Functions
Native API Quick Reference for Node.js

Callin

The Callin Interface
Using the Callin Functions
Callin Function Reference

Callout

Introduction
Running Programs or System Commands with $ZF(-100)
Creating an InterSystems Callout Library
Invoking Callout Library Functions
InterSystems Callout Quick Reference

Interoperability Productions

About...
First Look
Introducing Interoperability Productions

Introduction to Interoperability Productions
Connectivity Options
Business Processes and Business Logic
Other Production Options

Preparing to Create Productions

Road Map to Using InterSystems IRIS Productions
Planning an InterSystems IRIS Server Deployment

Best Practices

Best Practices for Production Development
Design Model for a Routing Production
Converting Interfaces to Production Elements

Developing Productions

About...
Developing Productions Using ObjectScript

Introduction
Programming Business Services, Processes and Operations
Defining Messages
Defining Business Services
Defining Business Processes
Defining Business Operations
Defining an Alert Processor
Defining Data Transformations
Defining Business Metrics
Defining an Enterprise Message Bank
Using the Record Mapper
Using the Complex Record Mapper
Handling Batches of Records Efficiently
Less Common Tasks
Testing and Debugging
Deploying a Production
Life Cycle of a Production and Its Parts

Developing Productions Using Java and .NET

Introduction
Getting Started
About Business Hosts and Adapters
Messaging
Inbound Adapters
Outbound Adapters
Business Services
Business Processes
Business Operations
Running the External Server
PEX API Reference

BPL and DTL

First Look
Developing BPL Processes

About BPL Processes
Using the Business Process Designer
Syntax Rules
List of BPL Elements
Handling Errors in BPL

Developing DTL Transformations

Introduction to DTL Tools
Creating Data Transformations
Syntax Rules
Adding Assign Actions
Adding Other Actions
Testing Data Transformations

BPL and DTL Reference

BPL Elements
DTL Elements

Using a Production as an ESB

Enterprise Service Bus and Registry Overview
Intended Audiences
Accessing the Public Service Registry through the Public REST API
Administering the Public Service and External Service Registries
Configuring an ESB
Configuring ESB Services and Operations
Configuring an InterSystems IRIS System and Creating a Namespace
Configuring a Web Application for a Pass-through Business Service
Pass-through Service and Operation Walkthrough
Service Registry Public API Reference

Configuring, Managing, and Monitoring Productions

About...
Configuring Productions

Introduction to Configuration Tasks
Creating a Production
Adding Business Hosts
Configuring Settings
Configuring Alerts
Defining Reusable Items for Use in Settings
Defining Other Options for Productions
Configuring the Enterprise Message Bank
Identifying Enterprise Systems for Viewing and Monitoring
Creating Dashboards
Settings in All Productions

Managing Productions

Introduction to Managing Productions
Starting and Stopping Productions
Purging Production Data
Using the Archive Manager
Managing Workflow Roles, Users, and Tasks
Defining Publish and Subscribe Message Routing
Controlling Data Storage for Productions
Controlling Access to Management Portal Functions
Finding Information on Menu Items

Monitoring Productions

Core Concepts
Monitoring All Namespaces
Monitoring a Production
Viewing, Searching, and Managing Messages
Viewing the Event Log
Enabling Tracing
Viewing the Business Rule Log
Viewing Business Process Instances
Viewing the I/O Archive for a Production
Viewing Messages from Multiple Productions
Using the Enterprise Message Viewer
Using the Enterprise Message Bank
Viewing Interface Maps
Finding Interface References
Monitoring Alerts
Monitoring Activity Volume
Managing Port Usage

Push Notifications

Push Notifications Overview
Configuring and Using Push Notifications

Defining Workflows

Overview of Workflow within Productions
Developing a Workflow
Including Custom Features in a Workflow
Testing a Workflow
Exploring the Workflow Sample
Available Workflow Metrics

Testing Productions

Testing Productions Tutorial
Testing Productions

TestControl
Callback Methods
Auxiliary Methods
Parameters and Properties
Creating a Test - Summary
Executing a Test
Example Overview
Example: Example Production
Example: Production Test
Example: OnAfterProductionStart
Example: CheckResults
Example: CheckErrors
Example: Executing the Test
Recap

Creating Tutorial.ExampleOperation

Connecting Systems

About...
Supported Formats
Supported Protocols
Email Adapters

Introduction
Using the Email Inbound Adapter
Using the Email Outbound Adapter
Reference for Settings

File Adapters

Introduction
Using the File Inbound Adapter
Using the File Outbound Adapter
Using the File Passthrough Service and Operation Classes
Reference for Settings

FTP Adapters

Introduction
Using the FTP Inbound Adapter
Using the FTP Outbound Adapter
Reference for Settings

HTTP Adapters

About the HTTP Adapters
Using the HTTP Inbound Adapter
Using the HTTP Outbound Adapter
Reference for Settings

Java Messaging Service (JMS)

JMS Overview
Configuring and Using JMS Business Services and Operations
Creating Custom JMS Services and Operations Using the Adapter

IBM WebSphere MQ Adapters

About the IBM WebSphere MQ Adapters
Using the IBM WebSphere MQ Inbound Adapter
Using the IBM WebSphere MQ Outbound Adapter
Troubleshooting
Reference for Settings

MQTT Adapters

Introduction to Message Queuing Telemetry Transport (MQTT)
Using the MQTT Adapters
Configuring and Using the MQTT Passthrough Business Service and Operation
Reference for Settings

REST Services and Adapters

Overview of Using REST in Productions
Creating REST Services in Productions
Creating REST Operations in Productions

SOAP Services and Web Clients

About SOAP and Web Services
Creating a Web Service in a Production
Creating a Web Client in a Production
Configuring a Production for SOAP Services
Using the SOAP Inbound Adapter
Older Web Service Variation
Reference for Settings

SAP Java Connector

Overview
Setup Tasks
Using the SAP Java Connector

SQL Adapters

About the SQL Adapters
Using the SQL Inbound Adapter
Using the SQL Outbound Adapter
Creating Adapter Methods for SQL
Using Result Sets
Using Snapshots

TCP Adapters

Introduction
Using the Inbound TCP Adapters
Using the Outbound TCP Adapters
Special Topics
Reference for Settings

Managed File Transfer

First Look
MFT Services

Introduction
Prerequisites and Configuration
Enabling a Production to Use MFT Services
Using the MFT API for InterSystems IRIS

Routing EDIFACT, X12, and XML Documents

About...
Using Virtual Documents in Productions

Virtual Documents
Schema Definitions
Virtual Property Paths
Using Virtual Documents in a Production
Defining Search Tables
Controlling Message Validation
Creating Custom Schema Categories
Portal Tools
Syntax Guide for Virtual Property Paths
Common Settings

EDIFACT

Introduction
Available Tools
Configuring the Production
Additional Steps
Reference for Settings

Introduction
X12 Schemas and Available Tools
Configuring the Production
Creating an X12 Data Transformation
Handling X12 Interchanges
Reference for Settings

Introduction
Available Tools
Configuration Steps
Overview of Property Paths in XML Virtual Documents
Specifying Schema-dependent Paths for XML Virtual Documents
Specifying DOM-style Paths for XML Virtual Documents
Defining Data Transformations for XML Virtual Documents
Defining Rule Sets for XML Virtual Documents
Defining Search Tables for XML Virtual Documents
XML-Enabled Objects Compared to XML Virtual Documents
Reference for Settings

Developing Business Rules

About Business Rules
Introduction to the Rule Editor
Creating and Editing Rule Sets
Debugging Routing Rules
Utility Functions for Use in Productions

Analytics and Data Science

About...
InterSystems IRIS Adaptive Analytics
Business Intelligence

About...
BI Introduction

Introduction to Business Intelligence
Introduction to the Business Intelligence User Interfaces
Introduction to the Other Business Intelligence Tools
Business Intelligence Glossary

BI Modeling

Introduction
Basic Concepts
Summary of Model Options
Principles and Recommendations
Defining Models for InterSystems Business Intelligence
Compiling and Building Cubes
Defining Dimensions, Hierarchies, and Levels
Details of Defining Levels
Defining Properties
Defining Measures
Defining Listings
Defining Listing Fields
Defining Calculated Members
Defining a Named Set
Defining Subject Areas
Defining Listing Groups
Reference Information for Cube Classes
Reference Information for Subject Area Classes
Details for the Fact and Dimension Tables

BI Advanced Modeling

Defining Computed Dimensions
Defining Shared Dimensions and Compound Cubes
Defining Cube-Cube Relationships
Using Text Analytics in Cubes
Defining Term Lists
Defining Worksheets
Defining Quality Measures
Defining Basic KPIs
Defining KPIs with Filters and Listings
Defining Advanced KPIs
Defining Plug-ins
Using Cube Inheritance
Defining Intermediate Expressions
Other Options
Reference Information for KPI and Plug-in Classes
Generating Secondary Cubes for Use with Text Analytics

Using Dashboards and the User Portal

Introduction to the User Portal
Using the Portal Features
Orientation to Dashboards
Using Dashboards
Using the Pivot Analysis Window

BI Dashboards

Introduction to Dashboards
Creating and Modifying Dashboards
Specifying Common Widget Options
Adding Pivot Table Widgets
Adding Chart Widgets
Customizing the Appearance of a Chart Widget
Adding Meter Widgets
Adding Scorecard Widgets
Adding Other Widgets
Defining and Using Themes
Adding Widget Controls

Implementing InterSystems IRIS Business Intelligence

Overview
Performing the Initial Setup
Configuring Settings
Defining Data Connectors
Performance Tips
Defining Custom Actions
Accessing Dashboards from Your Application
Keeping the Cubes Current
Executing Business Intelligence Queries Programmatically
Performing Localization
Packaging Business Intelligence Elements into Classes
Creating Portlets for Use in Dashboards
Other Development Work
Setting Up Security
Using Cube Versions
How the Analytics Engine Works
Using the MDX Performance Utility
Diagnostics for InterSystems Business Intelligence
Other Export/Import Options
Business Intelligence and Disaster Recovery

BI Analyzer

Introduction to the Analyzer
Creating Pivot Tables
Filtering Pivot Tables
Defining Calculated Elements
Defining and Using Pivot Variables
Customizing Pivot Tables
Working with Pivot Tables
Performing Ad Hoc Analysis
Configuring InterSystems IRIS for PDF Output

Using MDX

Background
Introduction to MDX Queries
Working with Levels
Working with Dimensions and Hierarchies
Working with Sets
Tuples and Cubes
Filtering a Query
Adding Summaries
Creating Calculated Measures and Members

MDX Reference

Basic Rules
Expression Types
MDX Statements and Clauses
MDX Functions
Intrinsic Properties
NOW Member for Time Levels
Quick Function Reference

Power BI
BI Clients

Introduction
DeepSee.js
Business Intelligence REST API

BI Tutorial

Getting Started
Introduction to Cube Elements
Creating a Cube
Expanding the Cube Definition
Creating Subject Areas
Creating and Packaging Pivot Tables and Dashboards

Apache Spark

About...
Using the InterSystems Spark Connector

Document Overview
Introduction
Spark Connector Data Source Options
Using Spark Connector Extension Methods
Spark Connector Best Practices
Spark Connector Internals
Spark Connector Quick Reference

Machine Learning

About...
Using IntegratedML

Introduction to ML
IntegratedML Basics
Providers
ML Configurations
Model Maintenance
About AutoML
SQL Commands
SQL Functions

Text Analytics (Natural Language Processing)

About...
Text Analytics with InterSystems Products
Using NLP

Conceptual Overview
NLP Implementation
Domain Architect
REST Interface
Alternatives for Creating an NLP Environment
Loading Text Data Programmatically
Performance Considerations when Loading Texts
NLP Queries
Semantic Attributes
Stemming
Skiplists
Filtering Sources
Text Categorization
Dominance and Proximity
Custom Metrics
Smart Matching: Creating a Dictionary
Smart Matching: Using a Dictionary
User Interfaces
IRIS Natural Language Processing (NLP) Tools
iKnow Web Services
KPIs and Dashboards
Customizing NLP
Language Identification
Domain Parameters

SQL Search

About...
First Look
Using SQL Text Search

InterSystems SQL Search Tool
SQL Search REST Interface

Unstructured Information Management Architecture

About...
InterSystems IRIS and UIMA
Using UIMA

Overview

Predictive Modeling Markup Language
InterSystems Reports

Introduction
InterSystems Reports Designer
InterSystems Reports Server with InterSystems IRIS

Creating and Modifying Dynamic Entities

This chapter provides basic information on how dynamic entities work.

Using JSON Literal Constructors

Dynamic entities are instances of %DynamicObject or %DynamicArray , which are designed to integrate JSON data manipulation seamlessly into ObjectScript applications. Although you can create instances of these classes with the standard %New() method, dynamic entities support a much more flexible and intuitive set of constructors. JSON literal constructors allow you to create dynamic entities by directly assigning a JSON string to a variable. For example, the following code creates empty instances of %DynamicObject and %DynamicArray :

              set dynamicObject = {}    set dynamicArray = []    write dynamicObject,!,dynamicArray  3@%Library.DynamicObject 1@%Library.DynamicArray

Unlike the %New() constructor, literal constructors {} and [] can accept a string in JSON format as an argument. For example, the following code creates a dynamic object with a property named prop1:

              set dynamicObject = {"prop1":"a string value"}    write dynamicObject.prop1  a string value

In fact, JSON literal constructors {} and [] can be used to specify any valid JSON array or object structure. In simple terms, any valid JSON literal string is also a valid ObjectScript expression that evaluates to a dynamic entity.

Note:

JSON property names must always be quoted

The JSON language specification (see https://json.org/ ) is a subset of Javascript Object Notation, and enforces stricter rules in some areas. One important difference is that the JSON specification requires all property names to be enclosed in double-quotes. Javascript syntax, on the other hand, permits unquoted names in many cases.

A dynamic entity stores an exact representation of each object property or array element in the JSON string. Any dynamic entity can use the %ToJSON() method to return the stored data as a JSON string. There is no loss or corruption of data when converting to or from a literal string. The following example creates a dynamic array and then calls %ToJSON() to construct and return a new JSON string representing the stored data:

              set dynamicArray = [[1,2,3],{"A":33,"a":"lower case"},1.23456789012345678901234,true,false,null,0,1,""]    write dynamicArray.%ToJSON()  [[1,2,3],{"A":33,"a":"lower case"},1.23456789012345678901234,true,false,null,0,1,""]

This dynamic array has stored and returned several significant values:

The first two elements are a nested array and a nested object. In JSON syntax, array and object structures can be nested to any depth.
Property names are case-sensitive. The nested object has two distinct properties named "A" and "a".
The third value is a very high-precision decimal number. This value would have been rounded down if it were stored as a standard floating point number, but the dynamic array has retained an exact representation of the original value.
The final six elements contain JSON datatype values true, false, and null, and corresponding ObjectScript values 0, 1, and "". Once again, dynamic entities preserve an exact representation of each value.

Using Dynamic Expressions and Dot Syntax

There are significant differences between the way values are stored in JSON and the way they are expressed in ObjectScript. JSON data storage would not be very useful if you had to convert an ObjectScript value to or from JSON syntax every time you wanted to use it, so dynamic entities are designed to make this conversion process transparent. You can always store and retrieve an ObjectScript value without worrying about its representation in JSON syntax.

Literal JSON constructors are no exception to this rule. So far, all of our examples have been entirely in JSON syntax, but literal constructors can also accept values defined in dynamic expressions, which are simply ObjectScript expressions enclosed in parentheses.

For example, the following dynamic array constructor stores two Unicode characters. At runtime, the literal constructor evaluates each element and stores the evaluated value. The first element is defined in JSON syntax and the second element is an ObjectScript function call, but the resulting stored values are identical:

              write ["\u00E9",($CHAR(233))].%ToJSON()  ["é","é"]

You can think of an ObjectScript expression as the code on the right side of a set statement. Any ObjectScript expression that evaluates to a value rather than an object reference can be serialized to a JSON literal string. The following example stores a $LIST value (which is a delimited string, not an object) in object property obj.list. It then creates array and extracts each list item in obj.list to a separate element:

              set obj = {"list":($LISTFROMSTRING("Deborah Noah Martha Bowie"," "))}    set array = [($LIST(obj.list,1)),($LIST(obj.list,2)),($LIST(obj.list,3)),($LIST(obj.list,4))]    write obj.%ToJSON(),!,array.%ToJSON()  {"list":"\t\u0001Deborah\u0006\u0001Noah\b\u0001Martha\u0007\u0001Bowie"} ["Deborah","Noah","Martha","Bowie"]

You cannot use a dynamic expression to define a property name (although there are ways to define property names programmatically. See "Using %Set(), %Get(), and %Remove()" for details).

Of course, literal constructors are not the only way to manipulate object properties and array elements. For example, the following code creates an empty dynamic object and uses standard object dot syntax to define the contents:

              set dynArray = []    set dynArray."0" = "02"_"33"    set dynArray."1" = {}    set dynArray."1".foo = $CHAR(dynArray."0")    write dynArray.%ToJSON()  [233,{"foo":"é"}]

In this example, literal constructors are used only to create empty dynamic entities. The assignment statements obey a few simple rules:

The assigned values are standard ObjectScript expressions. (In this example, "02"_"33" is an ObjectScript string expression that evaluates to integer 233).
Array elements are addressed by array index numbers, which must be numeric literals enclosed in double quotes. Dynamic arrays are zero-based.
Object properties are addressed by property names. Although property names are string literals, double quotes are optional if the property name is a valid class member name.
If the specified entity member does not yet exist, it will be created when you assign a value to it.

As previously mentioned, values are always stored and retrieved in ObjectScript format regardless of how they are represented in JSON syntax. The following examples demonstrate a few more facts that you should be aware of when using dot syntax.

Creating dynamic object properties with dot syntax

This example uses a literal constructor and dot syntax to create dynamic object dynObj, containing properties named A, a, and C quote. In the literal string, all property names must be quoted. In the set statements and the write statement, quotes are not required for property names a or A, but must be used for C quote:

                  set dynObj = {"a":"stuff"}    set dynObj."C quote" = " ""C quote"" contains a space "    set dynObj.a = " lower case ""a"" "    set dynObj.A = " upper case ""A"" "    write !,dynObj.%ToJSON()  {"a":" lower case \"a\" ","C quote":" \"C quote\" contains a space ","A":" upper case \"A\" "}

Dynamic objects are unordered lists, so values will not necessarily be stored in the order they were created. See "Iterating over a Dynamic Entity with %GetNext()" for examples that demonstrate this.

Creating dynamic array elements with dot syntax

Dynamic arrays are zero-based. This example assigns a value to array element 3 before defining element 2. Elements do not have to be defined in order, and element 2 could have been left undefined. See "Understanding Sparse Arrays and Unassigned Values" for detailed information.

                  set dynArray = [true,false]    set dynArray."3" = "three"    set dynArray."2" = 0    write dynArray.%ToJSON()  [true,false,0,"three"]

Although the first two elements were defined and stored as JSON boolean values true and false, they are returned as integers 1 and 0, which are the equivalent ObjectScript boolean values:

                  write "0=/"_dynArray."0"_"/, 1=/"_dynArray."1"_"/, 2=/"_dynArray."2"_"/, 3=/"_dynArray."3"_"/"  0=/1/, 1=/0/, 2=/0/, 3=/three/

Since stored values are always returned in ObjectScript format, JSON true, false, and null are returned as ObjectScript 0, 1, and "" (empty string). However, the original JSON values are preserved in the dynamic entity and can be recovered if necessary. See "Working with Datatypes" for information on identifying the original datatype of a stored value.

Note:

Dot syntax should not be used with very long property names

Although dynamic object properties can have names of any length, ObjectScript cannot use property names longer than 180 characters. If a dynamic object property name exceeds this limit, an attempt to use the name in dot syntax will result in a misleading <PROPERTY DOES NOT EXIST> error, even though the property exists and the name is valid. You can avoid this error by using the %Set() and %Get() methods, which accept property names of any length.

Using %Set(), %Get(), and %Remove()

Although literal constructors and dot syntax can be used to create dynamic entity members and manipulate values, they are not adequate for all purposes. Dynamic entities provide %Set(), %Get(), and %Remove() methods for full programmatic control over create, read, update, and delete operations.

One of the most important advantages to these methods is that member identifiers (property names and array index numbers) do not have to be literals. You can use ObjectScript variables and expressions to specify both values and identifiers.

Specifing values and identifiers programmatically with %Set(), %Get(), and %Remove()

The following example creates an object using literal constructor {}, and calls the %Set() method of the new object to add a series of properties named prop n with a value of 100+ n. Both names and values are defined by ObjectScript expressions:

                  set dynObj = {}    for i=1:1:5 { do dynObj.%Set("prop"_i,100+i) }    write dynObj.%ToJSON()  {"prop1":101,"prop2":102,"prop3":103,"prop4":104,"prop5":105}

The same variables can be used with %Get() to retrieve the property values:

                  for i=1:1:5 { write dynObj.%Get("prop"_i)_" " }  101 102 103 104 105

The %Remove() method deletes the specified member from the dynamic entity and returns the value. This example removes three of the five properties and concatenates the return values to string removedValues. The write statement displays the string of removed values and the current contents of dynObj:

                  set removedValues = ""    for i=2:1:4 { set removedValues = removedValues_dynObj.%Remove("prop"_i)_" " }    write "Removed values: "_removedValues,!,"Remaining properties: "_dynObj.%ToJSON()  Removed values: 102 103 104 Remaining properties: {"prop1":101,"prop5":105}

Both %Get() and %Remove() return an ObjectScript value for the specified member, but there is an important difference in how embedded dynamic entities are returned:

%Get() returns the value by reference. The return value is an OREF (object reference) to the property or element, which in turn contains a reference to the embedded entity.
%Remove() destroys the specified property or element (making the member OREF invalid), but returns a valid OREF that points directly to the formerly embedded entity.

Retrieving a nested dynamic entity with %Get() and %Remove()

In the following example, the value of property dynObj.address is a dynamic object. The %Get() statement stores a reference to the property (not the property value) in variable addrPointer. At this point, addrPointer can be used to access the road property of embedded entity address:

                  set dynObj = {"name":"greg", "address":{"road":"Old Road"}}    set addrPointer = dynObj.%Get("address")    set dynObj.address.road = "New Road"    write "Value of "_addrPointer_" is "_addrPointer.road  Value of 2@%Library.DynamicObject is New Road

The %Remove() statement destroys the property and returns a new OREF to the property value.

                  set addrRemoved =  dynObj.%Remove("address")    write "OREF of removed property: "_addrPointer,!,"OREF returned by %Remove(): "_addrRemoved  OREF of removed property: 2@%Library.DynamicObject OREF returned by %Remove(): 3@%Library.DynamicObject

After the call to %Remove(), addrRemoved contains a valid OREF to the formerly embedded dynamic object, and variable addrPointer contains an invalid OREF to the former location of property dynObj.address:

                  write addrRemoved.%ToJSON()  {"road":"New Road"}     write addrPointer.%ToJSON()  WRITE addrPointer.%ToJSON() ^ <INVALID OREF>

You can use the %Remove() method to remove members in any order. This has different implications for objects and arrays, as demonstrated in the following examples.

Removing an object property

Object properties have no fixed order. This means that properties can be destroyed in any order, but removing a property and adding another may also change the order in which properties are serialized and returned. The following example creates a dynamic object, and defines three properties with three consecutive calls to %Set():

                  set dynObject={}.%Set("propA","abc").%Set("PropB","byebye").%Set("propC",999)    write dynObject.%ToJSON()  {"propA":"abc","PropB":"byebye","propC":999}

Now %Remove() is called to destroy property PropB, after which new property PropD is added. The resulting dynamic object does not serialize its properties in the order they were created:

                  do dynObject.%Remove("PropB")    set dynObject.propD = "added last"    write dynObject.%ToJSON()  {"propA":"abc","propD":"added last","propC":999}

This also affects the order in which iterator method %GetNext() returns properties. See Iterating over a Dynamic Entity with %GetNext() for a similar example that uses %GetNext().

Removing an array element

An array is a zero-based ordered list. When you call %Remove() on an element, all elements after that one will have their array index number decremented by 1. The following example makes three consecutive calls to %Remove(1), removing a different element each time:

                  set dynArray = ["a","b","c","d","e"]    set removedValues = ""    for i=1:1:3 { set removedValues = removedValues_dynArray.%Remove(1)_" " }    write "Removed values: "_removedValues,!,"Array size="_dynArray.%Size()_": "_dynArray.%ToJSON()  Removed values: b c d Array size=2: ["a","e"]

A stack operation is usually implemented with %Push() and %Pop() rather than %Set() and %Remove(), but you can implement a queue by replacing %Pop() with %Remove(0) (see "Using %Push and %Pop with Dynamic Arrays").

%Remove() works the same way with all arrays, including those that contain elements with undefined values. See "Understanding Sparse Arrays and Unassigned Values" for an example demonstrating how %Remove() works with sparse arrays.

Assigning Dynamic Entities as Property Values

You can use %Set() or %Push() to nest a dynamic entity within another dynamic entity. For example, you can assign a dynamic object as a property value or an array element. An earlier example in this chapter showed how to retrieve a nested object (see "Retrieving a nested dynamic entity with %Get() and %Remove()"). The following example demonstrates one way to create a nested object.

Assigning a dynamic entity as a property value

This example creates a dynamic object with a property named myData, which has another dynamic object as its value:

                    {"myData":{"myChild":"Value of myChild"}}

The following code creates this object. It is not necessary to specify %Set() arguments as variables, but doing so will allow you to assign any valid name or value at runtime:

                    set mainObj = {}    set mainPropName="myData"     set nestedObj = {}    set nestedPropName="myChild"    set nestedPropValue="Value of myChild"     do nestedObj.%Set(nestedPropName, nestedPropValue)    do mainObj.%Set(mainPropName,nestedObj)    write mainObj.%ToJSON()

This code produces the following output:

USER>write mainObj.%ToJSON() {"myData":{"myChild":"Value of myChild"}}

Note:

Do not use the type parameter with object values

The %Set() method has an optional type parameter that allows you to specify the datatype of the value argument in some limited cases (see "Overriding a Default Datatype with %Set() or %Push()"). The type parameter cannot be used when the value argument is a dynamic entity. An error will be thrown if you attempt to do so.

Method Chaining

The %Set(), and %Push() methods return a reference to the entity that they have modified. The returned reference can immediately be used to call another method on the same entity, within the same expression.

The dynamic entity that begins a chain can be either a constructor ({}, or []) or an existing entity. Methods %Set() and %Push() return chainable references and can be called from anywhere in the chain. The last item in a chain can be any method available to the entity.

In the following example, a single write statement uses chained calls to %FromJSON(), %Set(), %Push(), and %ToJSON() to create, modify, and display a dynamic array:

              set jstring = "[123]"    write [].%FromJSON(jstring).%Set(1,"one").%Push("two").%Push("three").%Set(1,"final value").%ToJSON()  [123,"final value","two","three"]

%FromJSON() is only useful as the first method call in a chain, since it does not return a modified version of the calling entity. Instead, it simply ignores the calling entity and returns an entirely new instance deserialized from a JSON string. For more information, see "Converting Dynamic Entities to and from JSON".

You could also start a chain by retrieving a nested entity with %Get(), %Pop(), %GetNext(), or %Remove().

Error Handling

Dynamic entities throw exceptions in the case of an error, rather than returning a %Status value. In the following example, the thrown exception includes enough information to conclude that the second character in the method argument is invalid:

              set invalidObject = {}.%FromJSON("{:}")  <THROW>%FromJSON+37^%Library.DynamicAbstractObject.1 *%Exception.General Parsing error 3 Line 1 Offset 2

When dealing with dynamic data, it is always wise to assume that some data will not fit your expectations. Any code that makes use of dynamic objects should be surrounded with a TRY-CATCH block at some level (see "The TRY-CATCH Mechanism" in Using ObjectScript). For example:

              TRY {       set invalidObject = {}.%FromJSON("{:}")    }    CATCH errobj {       write errobj.Name_", "_errobj.Location_", error code "_errobj.Code,!       RETURN    }  Parsing error, Line 1 Offset 2, error code 3

Converting Dynamic Entities to and from JSON

You can use the %ToJSON() method to serialize a dynamic entity (convert it to a JSON string) and the %FromJSON() method to deserialize (convert JSON to a dynamic entity).

Serializing a dynamic entity to JSON

The following example creates and modifies a dynamic object, and then uses %ToJSON() to serialize it and display the resulting string:

                  set dynObject={"prop1":true}.%Set("prop2",123).%Set("prop3","foo")    set objString = dynObject.%ToJSON()    write objString  {"prop1":true,"prop2":123,"prop3":"foo"}

A dynamic array is serialized in the same way:

                  set dynArray=[].%Push("1st value").%Push("2nd value").%Push("3rd value")    set arrayString = dynArray.%ToJSON()    write arrayString  ["1st value","2nd value","3rd value"]

Both of these examples use method chaining (see "Method Chaining" earlier in this chapter).

Deserializing from JSON to a dynamic object

The %FromJSON() method converts a JSON string to a dynamic entity. The following example constructs a dynamic array and serializes it to string jstring. A call to %FromJSON() deserializes jstring to a new dynamic entity named newArray, which is then modified and displayed:

                  set jstring=["1st value","2nd value","3rd value"].%ToJSON()    set newArray={}.%FromJSON(jstring)    do newArray.%Push("new value")    write "New entity:"_newArray.%ToJSON()  New entity:["1st value","2nd value","3rd value","new value"]

Notice this example calls %FromJSON() from a dynamic object constructor ({}) even though the returned value is a dynamic array. %FromJSON() is a class method of %DynamicAbstractObject , and can therefore be called from any dynamic entity or constructor.

Cloning with %ToJSON() and %FromJSON()

Since each call to %FromJSON() creates a new dynamic entity, it can be used to duplicate an existing entity or initialize a set of identical entities.

In the following example, the value of property dynObj.address is a dynamic object. The property is referenced by variable addrPointer, and the property value is cloned by calling %FromJSON() to create new dynamic object addrClone:

                  set dynObj = {}.%FromJSON({"name":"greg", "address":{"road":"Dexter Ave."}}.%ToJSON())    set addrPointer = dynObj.address    set addrClone = {}.%FromJSON(dynObj.address.%ToJSON())

Variable addrPointer is just a reference to property dynObj.address, but addrClone is an independent instance of %DynamicObject that can be modified without affecting the original value:

                  set addrPointer.road = "Wright Ave."    set addrClone.road = "Sinister Ave."    write !,"Property = "_dynObj.address.%ToJSON(),!,"Clone = "_addrClone.%ToJSON()  Property = {"road":"Wright Ave."} Clone = {"road":"Sinister Ave."}

Serializing Large Dynamic Entities to Streams

If a dynamic entity is large enough, the output of %ToJSON() may exceed the maximum possible length for a string (see "String Length Limit" in the Orientation Guide for Server-Side Programming). The examples in this section use a maximum length string named longStr. The following code fragment demonstrates how longStr is generated:

                set longStr=""    for i=1:1:$SYSTEM.SYS.MaxLocalLength() { set longStr = longStr_"x" }    write "Maximum string length = "_$LENGTH(longStr)  Maximum string length = 3641144

Whenever an expression uses the return value of %ToJSON(), the string is built on the program stack, which is subject to the string length limit. For example, a read/write statement such as write dyn.%ToJSON() or an assignment statement such as set x=dyn.%ToJSON() will attempt to put the string on the stack. The following example adds two copies of longStr to a dynamic array and attempts to assign the serialized string to a variable, causing ObjectScript to return a <MAXSTRING> error:

                set longArray = [(longStr),(longStr)]    set tooBig = longArray.%ToJSON()

SET tooBig = longArray.%ToJSON() ^ <MAXSTRING>

The general solution to this problem is to pass the %ToJSON() output by reference in a DO command, without actually examining the return value. Output is written directly to the current device, and there is no limit on the length of the output. In the following examples, the device is a stream.

Writing to a file stream

This example writes dynamic object longObject to a file and then retrieves it. Variable longStr is the value defined at the beginning of this section:

                    set longObject = {"a":(longStr),"b":(longStr)}    set file=##class(%File).%New("c:\temp\longObjectFile.txt")    do file.Open("WSN")    do longObject.%ToJSON(file)    do file.Close()     do file.Open("RS")    set newObject = {}.%FromJSON(file)    write !,"Property newObject.a is "_$LENGTH(newObject.a)_" characters long."  Property newObject.a is 3641144 characters long.

This solution can also be used to read input from other streams.

Reading and writing global character streams

In this example, we serialize two large dynamic entities (using temporary streams because %ToJSON() can only serialize one entity per stream). Standard stream handling methods are used to store each temporary stream as a separate line in stream bigLines:

                    set tmpArray = ##class(%Stream.GlobalCharacter).%New()    set dyn = [(longStr),(longStr)]    do dyn.%ToJSON(tmpArray)     set tmpObject = ##class(%Stream.GlobalCharacter).%New()    set dyn = {"a":(longStr),"b":(longStr),"c":(longStr)}    do dyn.%ToJSON(tmpObject)     set bigLines = ##class(%Stream.GlobalCharacter).%New()    do bigLines.CopyFrom(tmpArray)    do bigLines.WriteLine()    do bigLines.CopyFrom(tmpObject)

Later, we can deserialize each dynamic entity from bigLines:

                    do bigLines.Rewind()    while ('bigLines.AtEnd) {       write !,{}.%FromJSON(bigLines.ReadLineIntoStream())    }  7@%Library.DynamicArray 7@%Library.DynamicObject