Using Caché ObjectScript

	Contents
Chapter 1:	Introduction to Caché ObjectScript
	1.1 Features 1.2 Language Overview 1.2.1 Statements and Commands 1.2.2 Functions 1.2.3 Expressions 1.2.4 Variables 1.2.5 Operators 1.3 Relationship with ANSI Standard M
Chapter 2:	Syntax Rules
	2.1 Case Sensitivity 2.1.1 Identifiers 2.1.2 Keyword Names 2.1.3 Class Names 2.2 Invoking Commands and Functions 2.3 White Space 2.4 Comments 2.4.1 Single-Line Comments 2.4.2 Multiple-Line Comments 2.4.3 Retaining Comment Text in Object Routines 2.5 Literals 2.5.1 String Literals 2.5.2 Numeric Literals 2.6 Identifiers 2.6.1 Special Identifiers 2.6.2 Dot (.) Character within Identifiers 2.7 Labels 2.8 Reserved Words
Chapter 3:	Data Types and Values
	3.1 Strings 3.1.1 Escaping Quotation Marks 3.1.2 Concatenating Strings 3.2 Numbers 3.3 Objects 3.4 Persistent Multi-dimensional Arrays (Globals) 3.5 Undefined Values 3.6 Boolean Values 3.7 Dates
Chapter 4:	Variables
	4.1 Categories of Variables 4.1.1 Local Variables 4.1.2 Globals 4.1.3 Array Variables 4.1.4 System Variables 4.1.5 Object Properties 4.2 Variable Typing and Conversion 4.2.1 Object Values 4.3 Variable Declaration and Scope
Chapter 5:	Operators and Expressions
	5.1 Introduction to Operators and Expressions 5.1.1 Operator Precedence 5.1.2 Expressions 5.1.3 Assignment 5.2 Arithmetic Operators 5.2.1 Unary Positive Operator (+) 5.2.2 Unary Negative Operator (-) 5.2.3 Addition Operator (+) 5.2.4 Subtraction Operator (-) 5.2.5 Multiplication Operator () 5.2.6 Division Operator (/) 5.2.7 Exponentiation Operator (*) 5.2.8 Integer Divide Operator ( \ ) 5.2.9 Modulo Operator (#) 5.3 Logical Comparison Operators 5.3.1 Binary And 5.3.2 Binary Or 5.3.3 Unary Not 5.4 String Operators 5.4.1 Binary Concatenate 5.5 Numeric Relational Operators 5.5.1 Binary Less Than 5.5.2 Binary Greater Than 5.5.3 Greater Than or Equal To 5.5.4 Less Than or Equal To 5.6 String Relational Operators 5.6.1 Binary Equals 5.6.2 Binary Contains 5.6.3 Binary Follows 5.6.4 Binary Sorts After 5.7 Pattern Matching 5.7.1 Specifying How Many Times a Pattern Can Occur 5.7.2 Specifying Multiple Patterns 5.7.3 Specifying a Combination Pattern 5.7.4 Specifying an Indefinite Pattern 5.7.5 Specifying an Alternating Pattern (Logical OR) 5.7.6 Using Incomplete Patterns 5.7.7 Multiple Pattern Interpretations 5.7.8 Not Match Operator 5.8 Indirection 5.8.1 Name Indirection 5.8.2 Pattern Indirection 5.8.3 Argument Indirection 5.8.4 Subscript Indirection 5.8.5 $TEXT Argument Indirection
Chapter 6:	Commands
	6.1 Command Arguments 6.1.1 Multiple Arguments 6.1.2 Argumentless Commands 6.2 Command Postconditional Expressions 6.2.1 Postconditional Syntax 6.2.2 Evaluation of Postconditionals 6.2.3 Command Arguments with Postconditionals 6.3 Invoking Code 6.3.1 Do 6.3.2 Quit 6.3.3 Job 6.3.4 Xecute 6.4 Assignment Commands 6.4.1 Set 6.4.2 Kill 6.4.3 New 6.5 Flow Control Commands 6.5.1 If, ElseIf, and Else 6.5.2 For 6.5.3 While and Do/While 6.6 I/O Commands 6.6.1 Write 6.6.2 Read 6.6.3 Open, Use, and Close 6.7 Other Commands
Chapter 7:	Functions
	7.1 Function Syntax
Chapter 8:	User-Defined Code
	8.1 Procedures, Routines, Subroutines, Functions, and Methods: What Are They? 8.1.1 Routines 8.1.2 Subroutines 8.1.3 Functions 8.2 Procedures in Detail 8.2.1 Invoking Procedures 8.2.2 Procedure Syntax 8.2.3 Procedure Variables 8.2.4 Public and Private Procedures 8.2.5 Procedure Parameters 8.2.6 Procedure Code 8.2.7 Indirection and Xecute Commands within Procedures 8.2.8 Error Traps within Procedures 8.3 Legacy User-Defined Code 8.3.1 Subroutines 8.3.2 Functions
Chapter 9:	ObjectScript Macros
	9.1 Defining Macros 9.1.1 Saving Macros 9.2 Referring to Macros in External Files 9.3 Calling Macros 9.4 Using Conditional Macros
Chapter 10:	Multidimensional Arrays
	10.1 What Multidimensional Arrays Are 10.1.1 Multidimensional Tree Structures 10.1.2 Sparse Multidimensional Storage 10.1.3 Settings for Multidimensional Arrays 10.2 Manipulating Multidimensional Arrays 10.3 For More Information
Chapter 11:	String Operations
	11.1 Basic String Operations and Functions 11.1.1 Advanced Features of $Extract 11.2 Delimited Strings 11.2.1 Advanced $Piece Features 11.3 List-Structure String Operations 11.3.1 Advanced List Features 11.4 Lists Versus $Piece and Strings
Chapter 12:	Calling Out of Caché
	12.1 Issuing Operating System Commands from Caché 12.1.1 Issuing Operating System Commands with %CLI 12.1.2 Issuing Operating System Commands from Caché with $ZF(-1) 12.1.3 Issuing Operating System Commands from Caché with $ZF(-2) 12.2 Calling External Applications with $ZF 12.2.1 Calling External Applications with $ZF on OpenVMS Platforms 12.2.2 Calling External Functions with $ZF on UNIX or Windows Platforms 12.2.3 $ZF Calls Support Byte Arrays 12.3 Building Callout Modules as Dynamic Shared Libraries 12.4 Referencing a User-Defined Callout Module 12.4.1 Statically Linked Callouts 12.4.2 A Single Active DLL: The $ZF(-3) Call Interface 12.4.3 Multiple Simultaneous Dynamic Libraries 12.4.4 Referencing a DLL by Externally-Defined Index 12.4.5 DLL Runup and Rundown Functions 12.5 Sample Caché Callout DLL Build Procedures 12.5.1 Windows 12.5.2 Linux 12.5.3 Tru64 UNIX 12.5.4 HP 32-bit 12.5.5 HP 64-bit 12.5.6 PowerPC 12.5.7 OpenVMS 12.6 Reading and Writing to Devices Opened in UNIX 12.6.1 Opening the File Descriptor 12.6.2 Closing the File Descriptor
Chapter 13:	Call-in Interface
	13.1 Call-In Interface and C Programs 13.1.1 Overview of Using the Call-in Interface 13.1.2 Call-In Files Supplied 13.1.3 Linking Your Routines 13.1.4 ccallin.h Contents 13.1.5 Specifying ASCII or Unicode Conditionally 13.1.6 ccallin.c Example File 13.2 Call-In Interface Functions 13.2.1 Call-In Function Overview 13.2.2 CacheAbortA 13.2.3 CacheContextA 13.2.4 CacheConvertA 13.2.5 CacheCtrlA 13.2.6 CacheCvtInA 13.2.7 CacheCvtInW 13.2.8 CacheCvtOutA 13.2.9 CacheCvtOutW 13.2.10 CacheEndA 13.2.11 CacheErrorA and CacheErrorW 13.2.12 CacheErrxlateA and CacheErrxlateW 13.2.13 CacheEvalA and CacheEvalW 13.2.14 CacheExecuteA 13.2.15 CachePromptA 13.2.16 CacheTypeA 13.2.17 CacheStartA 13.3 Requirements for Call-In Programs 13.3.1 Exiting Your Program 13.3.2 Do Not Disable Interrupt Delivery 13.3.3 Assigning Event Flags on OpenVMS 13.3.4 Exit Handlers Must Return to OpenVMS 13.3.5 Call CacheEndA After CacheStartA Before Halting 13.3.6 Opening Files 13.3.7 Compiling, Linking, and Running Your Program 13.3.8 Using Call-In Functions in $ZF Routines 13.4 Using ccallin.c 13.4.1 Compiling and Linking ccallin.c 13.5 Terminating Call-In Programs on OpenVMS
Chapter 14:	Transaction Processing
	14.1 Managing Transactions Within Applications 14.1.1 Transaction Commands 14.1.2 Using the Lock Command in Transactions 14.1.3 Transaction Rollback Within An Application 14.1.4 Examples of Transaction Processing Within Applications 14.2 Automatic Transaction RollBack 14.2.1 Rollback During Caché Startup 14.2.2 Rollback at Halt from Caché 14.2.3 Rollback During RESJOB 14.2.4 Restore Journal Option of JOURNAL Utility 14.3 System-Wide Issues with Transaction Processing 14.3.1 Backups with Transaction Processing 14.3.2 Journaling with Transaction Processing 14.3.3 Globals to Avoid in Transactions 14.3.4 Caché Network Transaction Processing 14.3.5 Asynchronous Error Notifications
Chapter 15:	Error Processing
	15.1 How Error Processing Works 15.1.1 Internal Error-Trapping Behavior 15.1.2 $ETRAP Error Handlers 15.1.3 Error Codes 15.1.4 The $STACK Special Variable 15.1.5 The $ESTACK Special Variable 15.1.6 The $STACK Function 15.2 Handling Errors with $ETRAP 15.2.1 Context-Specific $ETRAP Error Handlers 15.2.2 $ETRAP Flow of Control Options 15.3 Handling Errors with $ZTRAP 15.3.1 Setting Up $ZTRAP 15.3.2 Using $ZTRAP 15.3.3 Unstacking New Commands With Error Traps 15.3.4 $ZTRAP Flow of Control Options 15.4 Handling Errors in an Error Handler 15.4.1 Errors in a $ETRAP Error Handler 15.4.2 Errors in a $ZTRAP Error Handler 15.4.3 Error Information in the $ZERROR and $ECODE Special Variables 15.5 Forcing an Error 15.5.1 Setting $ECODE 15.5.2 Creating Application-Specific Errors 15.6 Processing Errors in Programmer Mode 15.6.1 Understanding Error Message Formats 15.6.2 Understanding the Programmer Mode Prompt 15.6.3 Recovering from the Error 15.6.4 <EDITED> Errors
Chapter 16:	Command-Line Routine Debugging
	16.1 Debugging with the Caché Debugger 16.1.1 Entering the Debugger from the Control Panel 16.1.2 Using Breakpoints and Watchpoints 16.1.3 Establishing Breakpoints and Watchpoints 16.1.4 Disabling Breakpoints and Watchpoints 16.1.5 Delaying Execution of Breakpoints and Watchpoints 16.1.6 Deleting Breakpoints and Watchpoints 16.1.7 Single-Step Breakpoint Actions 16.1.8 Tracing Execution 16.1.9 INTERRUPT Keypress and Break 16.1.10 Displaying Information About the Current Debug Environment 16.1.11 Using the Debug Device 16.1.12 Caché Debugger Example 16.1.13 Understanding Caché Debugger Errors 16.2 Debugging With Break 16.2.1 Using Argumentless Break to Suspend Routine Execution 16.2.2 Using Argumentless Break with a Condition 16.2.3 Using Argumented Break to Enable or Disable Interrupts 16.2.4 Using Argumented Break to Suspend Routine Execution 16.2.5 Enabling Single Stepping at the Previous Execution Level 16.2.6 Understanding the Programmer Mode Prompt Information 16.2.7 Resuming Execution after a Break or an Error 16.2.8 The NEW Command in Programmer Mode 16.2.9 The QUIT Command in Programmer Mode 16.2.10 Caché Error Messages 16.3 Using %STACK to Display the Stack 16.3.1 Running %STACK 16.3.2 Displaying the Process Execution Stack 16.3.3 Understanding the Stack Display 16.4 Error Trap Utilities 16.4.1 %ETN Application Error Trap 16.4.2 %ERN Application Error Report
Chapter 17:	Controlling Caché from a Windows Client
	17.1 CctrlGetDirs 17.1.1 Syntax 17.1.2 Return Value 17.2 CctrlConfigStatus 17.2.1 Syntax 17.2.2 Return Values 17.3 CctrlControl 17.3.1 Syntax 17.3.2 Return Values 17.4 CctrlRun 17.4.1 Syntax 17.4.2 Return Values 17.5 CctrlRunIO 17.5.1 Syntax 17.5.2 Return Values
Chapter 18:	Open M Language Compatibility
	18.1 Displaying and Switching Language Mode 18.2 DSM-11 Language Compatibility 18.2.1 Using Routine Interlock Devices 18.2.2 Issuing I/O Commands for Routine Interlock Devices 18.2.3 Working with DSM-11 Mode Routines 18.2.4 Transferring Globals from DSM-11 Systems 18.2.5 I/O Programming in DSM-11 Compatibility Mode 18.2.6 View Command and $View Function 18.2.7 ZAllocate and ZDeallocate 18.2.8 Extended Functions for DSM-11 Mode 18.2.9 Unsupported DSM-11 Functions 18.2.10 Extended Special Variables for DSM-11 Mode 18.2.11 Extended Commands for DSM-11 Compatibility Mode 18.2.12 Error Handling for DSM-11 Compatibility Mode 18.2.13 $TEXT Comment Lines 18.3 DSM Language Compatibility 18.3.1 Porting Routines from DSM to Caché 18.3.2 Programming in DSM Language Mode 18.3.3 Device Control Mnemonic Spaces and Device Control Mnemonics 18.3.4 Other DSM Language Features Implemented in Compatibility Mode 18.3.5 View Command and $View Function 18.3.6 Database Conversion 18.4 DSM-J Language Compatibility 18.5 DTM Language Compatibility 18.5.1 Programming in DTM Compatibility Mode 18.5.2 DTM Compatibility Mode Commands, Functions, and Special Variables 18.5.3 Database Conversion 18.6 MSM Language Compatibility 18.6.1 MSM Compatibility Mode Commands, Functions, and Special Variables 18.6.2 Database Conversion