Open M/SQL Developer Guide

Transcription

1 Ope M/SQL Developer Guide Versio: Ope M/SQL F.6, F.7 Revisio Date: April 25, 1996 Prit History Creatio Date: July, 1992 Revisio Dates: March, 1993 September, 1995

2 Ope M/SQL Developer Guide Copyright IterSystems Corporatio 1995 All rights reserved NOTICE PROPRIETARY CONFIDENTIAL This documet cotais trade secret ad cofidetial iformatio which is the property of IterSystems Corporatio, Oe Memorial Drive, Cambridge, MA 02142, or its affiliates, ad is furished for the sole purpose of the operatio ad maiteace of the products of IterSystems Corporatio. No part of this publicatio is to be used for ay other purpose, ad this publicatio is ot to be reproduced, copied, disclosed, trasmitted, stored i a retrieval system or traslated ito ay huma or computer laguage, i ay form, by ay meas, i whole or i part, without the express prior writte coset of IterSystems Corporatio. The copyig, use ad dispositio of this documet ad the software programs described herei is prohibited except to the limited extet set forth i the stadard software licese agreemet(s) of IterSystems Corporatio coverig such programs ad related documetatio. IterSystems Corporatio makes o represetatios ad warraties cocerig such software programs other tha those set forth i such stadard software licese agreemet(s). I additio, the liability of IterSystems Corporatio for ay losses or damages relatig to or arisig out of the use of such software programs is limited i the maer set forth i such stadard software licese agreemet(s). THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COP- IES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST. IterSystems Corporatio disclaims resposibility for errors which may appear i this documet, ad it reserves the right, i its sole discretio ad without otice, to make substitutios ad modificatios i the products ad practices described i this documet. M/SQL, M/PACT, ad M/NET are registered trademarks, ad IterSystems, Ope M, Ope M/SQL, ISM, DTM, DT-MAX, DT Widows, DSM, ad DASL are trademarks of IterSystems Corporatio. MUMPS, ow called M Techology, is a registered trademark of Massachusetts Geeral Hospital. DSM DDP, VAX, VMS, Ope VMS, ad DEC are trademarks of Digital Equipmet Corporatio. Microsoft, MS-DOS, Microsoft Access, ad, Excel are registered trademarks ad Widows, Visual Basic, ad Visual C++ are trademarks of Microsoft Corporatio. ORACLE is a registered trademark of Oracle Corporatio. For Support questios about ay IterSystems products, cotact the IterSystems Worldwide Support Ceter: U.S.: Tel: Fax: Europe: Tel: Fax: Iteret [email protected]

3 Preface Ope M/SQL is a itegrated eviromet for developig ad ruig database applicatios. It icludes a advaced relatioal database maagemet system, a applicatio ad report geerator, ad a procedural programmig laguage. Ope M/SQL combies two ANSI-Stadard laguages M, the oly procedural programmig laguage desiged specifically for database applicatios, ad SQL (Structured Query Laguage), the most widely used relatioal query laguage. Ope M/SQL provides two program developmet eviromets: The M eviromet, i which you ca execute system maagemet commads, ad create, modify, ad execute M routies. The relatioal eviromet, i which you defie the database i relatioal terms ad use the applicatio geerator tools to create, modify, ad execute advaced relatioal database applicatios. Ope M/SQL s relatioal eviromet is a complete RDBMS (Relatioal Database Maagemet System) it icludes a developmet eviromet for creatig advaced relatioal database applicatios, a maagemet system for maitaiig them, ad a ru-time eviromet for executig them. Ope M/SQL s relatioal eviromet has the followig compoets: Relatioal Data Dictioary eviromet where you defie tables to represet the logical structure of a relatioal database, or map the physical structure of a existig database to relatioal tables. These tables act as the foudatio o which Ope M/SQL relatioal database applicatios are built. Form Geerator a applicatio geeratio tool used to create ready-toru data screes through which ed users ca add, retrieve, edit, ad delete database iformatio. Ope M/SQL Developer Guide iii

4 Preface Meu Geerator a applicatio geeratio tool used to create pop-up meus ad meu bars which uite the various compoets of a applicatio i a logical ad visually sophisticated maer ad structure a applicatio by defiig how it is orgaized ad how it is preseted to ed users. M/PACT (Report Geerator) a report-writig tool used to create ad ru sophisticated ed-user data reportig applicatios that iteract with the Ope M/SQL Relatioal Data Dictioary. Query Geerator eviromet i which you ca create ad ru database queries o a ad-hoc basis. Relatioal Server a optioal compoet of Ope M/SQL that allows o-m applicatios to access ad modify your Ope M/SQL relatioal database. The Ope M/SQL Developer Guide describes all aspects of Ope M/SQL program developmet that are idepedet of cosideratios specific to hardware platform, operatig system, ad host M system. This documet provides a overview of the Ope M/SQL program developmet eviromet (icludig both the M eviromet ad the relatioal eviromet) ad presets various strategies for developig applicatios. More specifically, it cotais iformatio o the followig topics: Developmet of macro source routies Use of the Full Scree Editor Use of routie maagemet utilities Use of the Ope M/SQL developer utilities Overview of Ope M/SQL s implemetatio of SQL Various methods for usig SQL to query a Ope M/SQL relatioal database Audiece This documet is iteded for use by programmers who are usig IterSystems Ope M/SQL Developer product to create Ope M/SQL relatioal database applicatios. The term applicatio programmer i this documet refers to the programmers who create Ope M/SQL relatioal database applicatios. The term user i this documet refers to the ed user of a Ope M/SQL relatioal database applicatio. This documet assumes that you have programmig experiece. I specific, it assumes familiarity with programmig i the M laguage ad the SQL laguage. iv Ope M/SQL Developer Guide

5 Preface Orgaizatio of this Guide This maual is divided ito four sectios. Sectio I, Gettig Started, cotais the followig two chapters: Chapter 1, Itroductio to Ope M/SQL, itroduces IterSystems Ope M/SQL ad discusses its uses i a 4GL applicatio geerator eviromet. Chapter 1 begis with a discussio of applicatio developmet strategies, the goes o to discuss the compoets of Ope M/SQL ad their various applicatios. Chapter 2, The Ope M/SQL Relatioal Database, describes relatioal cocepts ad their implemetatio i SQL as well as the database cocept ad its implemetatio i Ope M/SQL. Sectio II, Program Developmet, cotais the followig five chapters: Chapter 3, Ope M/SQL Program Developmet, outlies the rage of facilities available for program developmet i Ope M/SQL. Chapter 4, Full Scree Editor, describes the Ope M/SQL Full Scree Editor used i editig macro source routies, itermediate code routies, ad iclude files. Chapter 5, Developig Macro Source Routies, describes how to create routies at the macro source level, icludig descriptios of all the macro costructs permitted by Ope M/SQL at this level. Chapter 6, Routie Hadlig ad Maiteace, presets a overview of the Ope M/SQL routie eviromet ad describes routie hadlig ad maiteace. Chapter 7, Ope M/SQL Routie Maagemet Utilities, describes the built-i utilities that IterSystems supplies to assist i examiig ad maipulatig routies ad iclude files. Sectio III, SQL Laguage Implemetatio, cotais the followig three chapters: Chapter 8, Embedded SQL, describes the two ways of usig SQL i a Ope M/SQL program: cursor-based ad o-cursor-based. Chapter 9, Ope M/SQL Implemetatio of SQL, describes extesios to ANSI-Stadard SQL that IterSystems has icorporated ito Ope M/SQL. Chapter 10, Query Geeratio ad Processig, describes the Query Geerator ad the Query Editor the two facilities provided by Ope M/SQL for the geeratio ad processig of ad hoc SQL queries. Ope M/SQL Developer Guide v

6 Preface Sectio IV, Applicatio Programmig, cotais the followig chapter: Chapter 11, Programmer Iterface to Applicatios, presets a overview of the M variables ad globals that iteract with forms ad reports. It also discusses the uses of iserted M code i a applicatio, the covetios for callig forms, reports, queries, ad meus ad emulatig forms, ad the cotets of applicatios. Chapter 12, Ope M/SQL Developer Utilities, describes the built-i utilities that IterSystems supplies to assist i examiig ad maipulatig routies ad iclude files. This guide cotais the followig appedices: Appedix A, SQL Error Messages, which lists ad describes all message codes (successful completio messages ad error messages) that ca be retured to the SQLCODE variable. Appedix B, Ope M/SQL Reserved Words, which lists all Ope M/SQL reserved words. Appedix C, Ope M/SQL Supported Termial Types, which lists all termial types curretly supported by Ope M/SQL. Appedix D, Keyboard Actios for the Full Scree Editor, which shows the keyboard mappig for usig the Full Scree Editor o keyboards associated with the termial types supported by Ope M/SQL/ A glossary defies the termiology used i this guide. vi Ope M/SQL Developer Guide

7 Preface Other Refereces Depedig o the cofiguratio of your system, you may also wish to refer to the followig guides: The Ope M/SQL Database Admiistrator s Guide, which describes how to cofigure, maage, ad maitai a Ope M/SQL eviromet, icludig both the applicatio developmet eviromet ad the applicatio ru-time eviromet. For sites that use the Ope M/SQL Relatioal Server to make Ope M/SQL data available to exteral applicatios, this guide also describes how to cofigure, maage, ad maitai the Relatioal Server. The Ope M/SQL User Iterface Programmig Guide, which describes how to use the applicatio geeratio tools withi Ope M/SQL Developer to create a user iterface for your relatioal database. These applicatio geeratio tools iclude the Form Geerator used to create ready-to-ru data screes through which ed users ca add, retrieve, edit, ad delete database iformatio; the Meu Geerator used to create pop-up meus ad meu bars which uite the various compoets of a applicatio i a logical ad visually sophisticated maer ad structure a applicatio by defiig how it is orgaized ad how it is preseted to users; ad the Applicatio Help Facility used to create ad deploy a cotext-sesitive o-lie help system for your Ope M/SQL relatioal database applicatio. The Ope M/SQL Data Dictioary Guide, which describes how to defie tables to represet the logical structure of a relatioal database, or how to map the physical structure of a existig database to relatioal tables. These tables act as the foudatio o which Ope M/SQL relatioal database applicatios are built. The Ope M/SQL Relatioal Cliet User Guide, which describes how to access a Ope M/SQL relatioal database (retrieve ad modify data) from various third-party applicatio developmet tools. The Ope M/SQL Server Programmig Guide, which describes how to access a Ope M/SQL relatioal database from applicatios created usig the C or C++ programmig laguage. The M/PACT Guide, which describes how to create ad ru sophisticated ed-user data reportig applicatios that iteract with the Ope M/SQL Relatioal Data Dictioary. A tutorial etitled Ope M/SQL: A Getle Itroductio, which uses a project maagemet demostratio applicatio to show how to develop ad use a Ope M/SQL applicatio. The Ope M/SQL M Programmig Guide, which describes ISM (IterSystems origial implemetatio of the M programmig laguage), icludig global database cocepts, the developmet of itermediate code routies, ad the use of ISM utilities. Ope M/SQL Developer Guide vii

8 Preface The appropriate system guide for your Ope M system platform, which describes the system-specific elemets of usig Ope M o your particular computer ad operatig system. viii Ope M/SQL Developer Guide

9 Preface Typographic Covetios Used i this Guide This guide observes the followig typographic covetios: Covetio Descriptio Body text appears i Times Roma type. Computer geerated iformatio appears i Courier type. Computer geerated required fields appear i Courier Bold type. User iput appears i Courier Bold Italic type. Keystrokes appear i uppercase ad eclosed withi agle brackets. Simultaeous keystrokes appear hypheated, i uppercase, ad eclosed withi agle brackets. Commad sytax appears ideted i Courier type with variable iformatio i Courier Italic type ad eclosed withi agle brackets. Examples of user-typed commads appear ideted i Courier Bold Italic type. Procedure titles appear i bold Helvetica type ad are desigated by a uderlied sidehead prefix. Note, Cautio, Warig, ad Hit statemets appear i Helvetica type with a appropriate sidehead. Titles of other guides ad other chapters withi this guide appear i Times Italic type. Example Ope M/SQL offers a variety of strategies for developig a applicatio. Likig/Sytax Checkig...DONE Update New M Database Defaults? Yes <RETURN> <CTRL-Z> > do setaid^%msql( <UserName> ) > do setaid^%msql( Zeus ) Procedure Note To access the System Cofiguratio widow: Turig DBMS security OFF is a useful way to guaratee access to curret applicatios by users who will eed them while you are i the process of implemetig a privilege system. Ope M/SQL User Iterface Programmig Guide Ope M/SQL Developer Guide ix

10 Preface x Ope M/SQL Developer Guide

11 Table of Cotets Preface Audiece iv Orgaizatio of this Guide v Other Refereces vii Typographic Covetios Used i this Guide ix Part I Gettig Started 1 Itroductio to Ope M/SQL What Is Ope M/SQL? What Is Ope M/SQL Developer? Applicatio Developmet Strategies Automated Program Geeratio Procedural Programmig i ANSI M Mixed Eviromets Overview of the System Eviromet Hardware ad Operatig System Eviromets Memory Eviromet Global Database ANSI-Stadard M Laguage Processor ANSI-Stadard SQL Laguage Processor Relatioal Data Dictioary Program Developmet Eviromet The Form Geerator ad M/PACT Meu Geerator Query Optimizer M/NET Networkig Ope M/SQL Developer Guide xi

12 Table of Cotets DT Network Ope M/SQL Rus o Top of Ay M Implemetatio Itegratio of Two ANSI Stadards Embedded SQL Iserted Code for Data Dictioary, Forms, ad Reports Accessig the Global Database SQL - Relatioal Database Access M Global Refereces Ope M/SQL Program Structure Macro Source Routies Itermediate Code Routies Object Code Routies Ope M/SQL Routie Utilities ad Editors Distributed Data Processig The Ope M/SQL Relatioal Database Ope M/SQL Implemets Relatios as Tables Ope M/SQL Tables Follow The First Normal Form Ope M/SQL Supports Two Types of Tables Ope M/SQL Implemets Schemas as M Directories Ope M/SQL Database Structure for No-ISM Implemetatios of M. 2-4 The Ope M/SQL Relatioal Data Dictioary Accessig Data i a Ope M/SQL Relatioal Database Usig SQL to Query the Database Cartesia Product Project Restrict Jois IterSystems Extesios to the Relatioal Model Oe-Way Outer Jois Implicit Jois Multi-Lie Fields Part II Program Developmet 3 Ope M/SQL Program Developmet Programmig Methods The Full Scree Editor Itermediate Code Routies Routie Lie Editor xii Ope M/SQL Developer Guide

13 Table of Cotets Routie Maagemet Utilities Developer Utilities Programmer Iterface to Applicatios Full Scree Editor Overview of the Full Scree Editor Full Scree Editor Features Routie Types for Editig Ivokig the Full Scree Editor Loadig Existig Routies Creatig New Routies Prevetig Overwrites Full Scree Editor Scree Display Navigatig the Full Scree Editor Meu System Primary Meu Buffers Meu Widows Meu Mark Meu Other Meu Editig Operatios Movig the Cursor Isertig Text DeletigText Cuttig ad Pastig Text Editig Multiple Copies of a Routie Displayig Multiple Buffers Settig a Mark i Your Curret Buffer Searchig For Text Strigs ReplacigText Strigs Usig Cotrol Key Commads for Quicker Editig Gettig Help Exitig the Full Scree Editor Automatic Sytax Checkig Automatic Date ad Time Stamps Developig Macro Source Routies Creatig Macro Source Routies Compilig Macro Source Routies Macro Source Routies ad Iclude Files Macro Source Routies Are Portable Across M Implemetatios Ope M/SQL Developer Guide xiii

14 Table of Cotets The Ope M/SQL Macro Preprocessor Macro Preprocessor Commads Macro Preprocessor Fuctios Macro Refereces Summary of Macro Preprocessor Commads #defie ad #udef Nested Expasio #ifdef, #ifudef, #if, #else, #elseif, ad #edif #iclude Idicatig Commet Lies Summary of Macro Preprocessor Fuctios &sql(...) ##vedor Routie Hadlig ad Maiteace Routie Eviromet Writig Routies Covertig Itermediate Code to Macro Source Code Routie Names, Extesios, ad Versio Numbers Routie Names Must Be Uique Case Sesitivity Routie Extesios Versio Numbers Usig Wildcard Symbols to Specify Routies Wildcards for Routie Names Wildcards for Extesios Wildcards for Versio Numbers Referecig Routies i Other Directories Restrictios o Usig Remote Directory Sytax Routie Sets Creatig a Routie Set Usig a Routie Set Compilig Routies Backig Up Routies How Backups are Shuffled ad Reumbered The Full Scree Editor Geerates Backups Whe You Save Restorig a Backup Versio to the Curret Versio Deletig Routies %urdel %urpurge Routie Copyig ad Compilig Sychroizatio xiv Ope M/SQL Developer Guide

15 Table of Cotets 7 Ope M/SQL Routie Maagemet Utilities Summary of Routie Maagemet Utilities Accessig the Routie Maagemet Utilities Callig the Routie Utilities Directly from M Accessig the Routie Utilities from withi Ope M/SQL %urprit Selectig a Output Device %urload Routie Iput Optios Compile Macro Source Routies %urdir %urchage %urcomp %urcopy %urfid %urfad %urdel %urverma %urpurge %urset The Global ^mtemp Parameters of %urset Part III SQL Laguage Implemetatio 8 Embedded SQL Preprocessor Sytax Delimits Embedded SQL Ope M/SQL Supports Two Kids of Embedded SQL No-Cursor-Based SQL Cursor-Based SQL Referecig Macros i Embedded SQL Iteral ad Exteral Values Multi-Lie Values Reserved Tag ad Variable Names Portability Detailed Example Ope M/SQL Developer Guide xv

16 Table of Cotets 9 Ope M/SQL Implemetatio of SQL Summary of Extesios Added Keywords ad Symbols Jois Oe-Way Outer Jois Implicit Jois Aggregate Extesios Aggregates as Query Colums %FOREACH %AFTERHAVING DISTINCT BY Duplicate Rows Embedded SQL Usig the INTO Clause You May Use INTO i Cursor Declaratio Usig INTO with Arrays SELECT INTO Usig Arrays INSERT ad UPDATE INTO Usig Arrays VALUES Extesio for INSERT ad UPDATE Queries Multi-Lie Fields Usig Multi-Lie Fields i SELECT Queries Usig Multi-Lie Fields i INSERT ad UPDATE Queries Iteral ad Exteral Values %INTERNAL ad %EXTERNAL Fuctios M Operators Patter Match Operator Ca Test Variables Extesios to SQL Operators [NOT] IN Operator Cocateatio Operator %STARTSWITH LIKE Predicate Special Patter Matchig Characters Specifyig a Host Variable as the Search Patter ESCAPE Qualifier Error Hadlig Collatio Sequece EXACT ALPHAUP UPPER Plus, Mius, ad Space xvi Ope M/SQL Developer Guide

17 Table of Cotets Field Collatio Sequece Collatio Sequece ad ORDER BY Collatio Sequece ad Comparisos %ALPHAUP, %UPPER, ad %EXACT Chagig the Default Collatio Sequece %NOCHECK SQL Trasactio Processig Privilege Operators GRANT REVOKE %CHECKPRIV Keyword SQLCODE Values Usig Subqueries Usig a Subquery i a WHERE Clause Usig a Subquery i a FROM clause Ope M/SQL Subquery Extesios Query-Based Views CREATE VIEW ALTER VIEW DROP VIEW Restrictios o Defiig Query-Based Views You May Name Query-Based Views i FROM Clause Query Geeratio ad Processig Facilities for Creatig SQL Queries Accessig the Query Geeratio Facilities Usig the Query Geerator Example Query Defiitio Meu Bar Usig the Iteractive Query Editor Query Types Creatig a Query i the Iteractive Query Editor Editig Commads Query Editor Horizotal Optios Meu Ruig Queries Privileges Required to Ru Queries Ruig a Query From its Defiitio Eviromet Usig the Ru Existig Queries Utility Ruig a Query from M Code Selectig a Output Device Ope M/SQL Developer Guide xvii

18 Table of Cotets ASCII-Delimited Output for Queries Cotets of a ASCII-Delimited File Queries Support Dual Output Formats Copyig Queries List Queries Report Detailed Query Listig Report Part IV Applicatio Programmig 11 Programmer Iterface to Applicatios Ope M/SQL Variables List of Ope M/SQL Percet (%) Variables Etry Poits to the %msql Routie Ope M/SQL Globals Object Defiitio Globals Ope M/SQL Percet (%) Globals Isertig Code ito Ope M/SQL Applicatios Iserted Code Ca Referece Fields Iserted Code Ca Referece Variables ad Globals Ope M/SQL Performs Sytax Checkig o Iserted M Code Triggers Override Queries for Lookups Computed Fields Iteral/Exteral Coversio Code Additioal Validatio Code Required-Maybe Fields Map Subscripts ad Pieces NEXT Subroutie Coditioal Map Callig Ope M/SQL Objects from M Programs Callig Forms Callig Reports Callig Queries Callig Old-Style Meus Callig Meu Objects Emulatig Form Behavior from M Programs Displayig Help Text i a Help Text Box Writig Message Text Readig Fields Cleaig Up Widows xviii Ope M/SQL Developer Guide

19 Table of Cotets Establishig Authorizatio ID from Programmer Mode Itermixig Ope M/SQL Objects with User-Defied M Routies pushvars^%msqlutl popvars^%msqlutl $$msqlvars^%msqlutl Cotets of Applicatios Routie Names Cotets of Base Table Routies Cotets of Form Routies Cotets of Meu Object Routies Cotets of Old-Style Meu Routies Cotets of Report Routies Cotets of Query Routies Ope M/SQL Developer Utilities Accessig the Developer Utilities Meu Usig the Object Compile Driver Utility Settig Compilatio Optio Defaults Defiig the Cotets of a Compilatio Cofiguratio Compilig the Cofiguratio Viewig the Results of the Last Compilatio Compilig a Compilatio Cofiguratio from M Program Code Checkig the Itegrity of Ope M/SQL Objects Checks o Base Tables Checks o Views Checks o Forms Checks o Reports Checks o Meu Objects Checks o Triggers Ruig the Itegrity Checker Utility Error Fixig Mode Searchig for Strigs i Ope M/SQL Objects Ivokig Macro Source Routie Utilities Queryig Objects by Routie Prefix Natioal Laguage Reports Ope M/SQL Developer Guide xix

20 Table of Cotets Appedices A B C D SQL Error Messages Successful Completio Messages A-2 Error Messages A-3 Ope M/SQL Reserved Words Ope M/SQL Supported Termial Types Ope M/SQL for DSM C-3 Ope M/SQL for DTM C-3 Ope M/SQL for MSM Eviromet C-3 Full Scree Editor Keyboard Actios Altos D-1 ANSI D-4 CIT D-7 Dasher D-11 IBM 3151 ASCII Display Statio D-13 IBM PC D-17 QUME D-20 Su D-23 Televideo D-26 DEC VT D-29 DEC VT D-32 DEC VT D-35 WYSE-60 (Native Mode) D-39 Glossary of Terms Idex xx Ope M/SQL Developer Guide

21 PART Gettig Started I Chapter 1 Itroductio to Ope M/SQL Chapter 2 The Ope M/SQL Relatioal Database

22

23 CHAPTER Itroductio to Ope M/SQL 1 This chapter itroduces IterSystems Ope M/SQL ad discusses its uses i a 4GL applicatio geerator eviromet. Specifically, it covers the followig topics: What Is Ope M/SQL? What Is Ope M/SQL Developer? Applicatio Developmet Strategies Overview of the System Eviromet Itegratio of Two ANSI Stadards Accessig the Global Database Ope M/SQL Program Structure Ope M/SQL Developer Guide 1-1

24 Chapter 1 Itroductio to Ope M/SQL What Is Ope M/SQL? Ope M/SQL is a itegrated eviromet cosistig of a advaced relatioal database maagemet system, applicatio geerator, ad procedural programmig laguage that offers a variety of strategies for developig ad ruig database applicatios. Ope M/SQL combies two ANSI Stadard programmig laguages, SQL ad M. SQL is the most widely used relatioal query laguage. M is a database-orieted procedural laguage that has bee used to develop ad ru performace-critical olie applicatios at thousads of sites. The merger of these two laguages provides a powerful stadards-based system that offers extremely high performace. The Ope i Ope M/SQL refers to its ope systems architecture, which allows it to ru i a vedor-idepedet host M eviromet. Specifically, you ca develop ad ru Ope M/SQL applicatios o top of the followig M implemetatios: ISM DTM DSM Microetics MSM All Ope M/SQL applicatios are completely portable betwee these M systems. This meas you ca develop a applicatio o oe M system, the port it to aother M system without makig ay modificatios. 1-2 Ope M/SQL Developer Guide

25 What Is Ope M/SQL Developer? What Is Ope M/SQL Developer? Ope M/SQL Developer is IterSystems developmet eviromet for creatig Ope M/SQL relatioal applicatios. Ope M/SQL Developer ecompasses the relatioal Data Dictioary, where you defie relatioal data structures, the Form Geerator, where you build iteractive data etry screes, ad the Meu Geerator, where you brig the various compoets together ito a coheret applicatio. It also supports various applicatios of SQL, icludig the iteractive costructio of queries ad the embeddig of SQL code withi M routies. Ope M/SQL Developer allows you to produce sophisticated reports, queries, ad forms with speed ad ease. The Ope M/SQL Data Dictioary describes the elemets of a Ope M/SQL relatioal database ad as such costitutes the structural foudatio of a Ope M/SQL applicatio. The Data Dictioary provides a advaced, widow-based approach to defiig, storig, ad retrievig data. The Ope M/SQL Form Geerator creates ready-to-ru data etry screes to add, delete, retrieve, ad edit database iformatio. The geerated forms are equipped with data validatio, full-scree display hadlig, powerful fuctio keys, ad SQL queries used iterally to retrieve ad store data. M/PACT is a Ope M/SQL add-o optio that allows you to geerate highly formatted reports from data served by the relatioal Data Dictioary. The Ope M/SQL Relatioal Server is a related product that allows o-m, third party applicatio developmet tools ad C programs o cliet systems to access your Ope M/SQL relatioal databases o a server system. Ope M/SQL Developer Guide 1-3

26 Chapter 1 Itroductio to Ope M/SQL Applicatio Developmet Strategies Ope M/SQL offers a variety of strategies for developig a applicatio: developmet ca take place at a purely automated level; programs ca be etirely had-coded; or, most commoly, applicatios ca be developed i a mixed eviromet that icludes programs created usig M, the Ope M/SQL procedural programmig laguage, as well as automatically-geerated forms, reports, ad SQL queries, ad other acillary fuctios usig the applicatio geeratio tools of Ope M/SQL. The followig discussio addresses the differet strategies for applicatios developmet i Ope M/SQL. Automated Program Geeratio Automated program geeratio takes place i five phases: 1. Map the fuctioal specificatios for the applicatio out o paper. 2. Defie the data structures i the Data Dictioary, alog with itegrity costraits, table relatioships, ad triggers. 3. Use the Form Geerator to develop data etry ad iquiry forms. 4. Use M/PACT to develop reports. 5. Use the Meu Geerator to tie the differet parts of the applicatio together. Mappig the Fuctioal Specificatios The first step i developig a applicatio is to orgaize the logical structure of the data o paper as a series of tables, just as you might desig a paper filig system. To do this, cosider the fuctioal eeds of your applicatio ad make a list of all the differet pieces of data that you eed. The object of the desig is to describe the tables that costitute the database ad how those tables will iteract with oe aother. For example, oe applicatio might have a customer table, a ivoice table, a ivoice lie item table, a parts table, etc. The customer table might the cosist of fields for customer ame, address, phoe, curret balace, etc. Defiig the Data Structure i the Data Dictioary Oce you have desiged a data structure o paper, you ext defie that data structure i the Ope M/SQL Data Dictioary, alog with ay itegrity costraits o the data. See the Ope M/SQL Data Dictioary Guide for details about how to create ad modify the uderlyig M global structure for your relatioal database. Itegrity costraits may be very simple; for example, you ca specify a rage of valid umbers that ca be etered for a field. Other costraits may be more complex; perhaps you wat to specify that a ivoice caot be etered ito the ivoice table without a correspodig customer etry i the customer table. Eve 1-4 Ope M/SQL Developer Guide

27 Applicatio Developmet Strategies more complex costraits may require the additio of complete SQL queries or procedural M code. The Data Dictioary will also cotai descriptios of the relatioships betwee tables. For example, where rows of a ivoice lie item table caot exist without a correspodig row i a ivoice table, the lie item table should be defied as a characteristic table of the ivoice table. Oe field i the ivoice table should also be defied to serve as a desigative referece to rows i the customer table. Ope M/SQL uses this iformatio to eforce itegrity costraits ad produce automatic jois i queries. You may also defie processig triggers i the Data Dictioary. Triggers are sequeces of actios defied to automatically occur, or be triggered, whe certai other evets occur. A trigger defiitio usually cosists of a SQL query or M code segmet that should be ivoked whe rows are created, modified, or deleted. For example, if a medical record for a give patiet is deleted, you may wat to establish a trigger that will automatically delete all of that patiet's lab test iformatio from various lab files. Developig Forms ad Reports Oce you have defied the data structure i the Data Dictioary, the ext step is to geerate forms that eable data etry ad iquiry usig the Form Geerator. See the Ope M/SQL User Iterface Programmig Guide for details about how to use the Form Geerator. Forms are sets of widows for eterig, retrievig, modifyig, ad displayig data. The Form Geerator creates visually sophisticated widows complete with data validatio capabilities, full scree display hadlig, ad powerful fuctio keys. The Form Geerator uses iterally stored SQL queries to retrieve ad store data. You ca geerate widows automatically ad modify them easily usig cut-ad-paste editig facilities. For more complex applicatios, you ca ehace the widows by addig SQL queries or M code to the widow defiitio. You ca add very simple lies of code, or add etire programs that perform complex calculatios or geerate their ow displays ad prompts i cooperatio with the Form Geerator. M/PACT geerates reports. Reports are defied through a series of questios o the scree; o complex procedural programmig is required. See the Ope M/SQL M/PACT Guide for iformatio about usig M/PACT. SQL queries ca be etered iteractively through the SQL Query Defiitio widow. Ope M/SQL Developer Guide 1-5

28 Chapter 1 Itroductio to Ope M/SQL Tyig the Applicatio Together with the Meu Geerator The Meu Geerator ties the differet compoets of the applicatio together. You may create pop-up meus ad meu bars that uite the various compoets of a applicatio, apply a orderly structure to the applicatio, ad offer the user easy access. For details about creatig ad usig the Meu Geerator, see the Ope M/SQL User Iterface Programmig Guide. Procedural Programmig i ANSI M It is also possible to develop applicatios etirely i M, a powerful procedural programmig laguage that affords rapid program developmet ad high performace i a database applicatio eviromet. M is a ANSI Stadard procedural programmig laguage. Other ANSI Stadard procedural programmig laguages iclude COBOL, C, FORTRAN, PL/1, BASIC, ad PASCAL. Withi M programs, data ca be accessed i the followig ways: Directly through M global refereces that view the database as a collectio of arrays; Through stadard SQL Data Maipulatio Laguage (DML) costructs: isert, update, ad delete. Cursors are fully supported. For stadard SQL sytax, refer to a commercial textbook or the ANSI X stadard, also kow as ISO 9075:1989. Through embedded SQL queries that access or edit a sigle row (provided you have also defied the data structures i the Data Dictioary); Through embedded SQL queries that access multiple rows oe row at a time usig cursors; Through embedded SQL queries usig UPDATE or DELETE statemets that operate o multiple rows. Direct global refereces ad SQL queries ca be used to access the same data. Programmig i a procedural laguage allows the creatio of complex programs that use sophisticated algorithms. However, procedurally geerated programs take loger to develop ad are more difficult to maitai tha applicatios geerated automatically i Ope M/SQL. The combied power of M, the Data Dictioary, the Form Geerator, M/PACT, ad SQL delivers a flexible, productive, ad easily maitaied eviromet for applicatio developmet. 1-6 Ope M/SQL Developer Guide

29 Applicatio Developmet Strategies Mixed Eviromets While may applicatios ca be developed etirely through automatic geeratio, ad some are so specialized that they must be etirely had coded, most applicatios fall somewhere i betwee. For this, Ope M/SQL offers the advatages of a mixed programmig strategy. It geerally makes sese to use the Form Geerator ad M/PACT to develop as much of the applicatio as possible, utilizig customizatio capabilities where ecessary. The, use M to program those portios that have to be writte procedurally. Thus, a laboratory applicatio might perform most of its data etry through geerated widows but use M for direct iput from specialized istrumets. The result is a itegrated applicatio created ad ru etirely withi Ope M/SQL. Ope M/SQL Developer Guide 1-7

30 Chapter 1 Itroductio to Ope M/SQL Overview of the System Eviromet Ope M/SQL rus o a variety of platforms ad offers a varied systems eviromet. It also rus i a vedor-idepedet host M eviromet, equally supportig the ISM, DTM, DSM, ad Microetics MSM implemetatios of M. The followig discussio itroduces the various elemets of the system eviromet, icludig: Hardware ad Software Operatig System Eviromets Memory Eviromet Global Database ANSI M Processor ANSI SQL Processor Relatioal Data Dictioary Program Developmet Eviromet The Form Geerator ad M/PACT Meu Geerator Query Optimizer M/NET Networkig DT Network Ope M/SQL Rus o Top of Ay M Implemetatio Hardware ad Operatig System Eviromets Ope M/SQL rus o a variety of hardware platforms ad operatig systems, ragig from sigle-user PCs to large UNIX- ad VMS-based systems supportig may hudreds of users, icludig most major supermicro ad miicomputer systems from the leadig hardware vedors. Operatig systems iclude MS- DOS, Microsoft Widows 3.1, VMS, ad Uix. Oe of Ope M/SQL s most exceptioal features is its portability. Although the host operatig system may vary, the Ope M/SQL eviromet is cosistet across platforms. Applicatios developed o oe system ca be moved to aother easily ad usually with o modificatio. Frequetly, these applicatios ca be ported with o chages. 1-8 Ope M/SQL Developer Guide

31 Overview of the System Eviromet Memory Eviromet Global Database Each M process rus as a separate process o the host operatig system, except for MS-DOS ad Microsoft Widows systems. I additio to a private memory sectio for each M process, there are two cofigurable caches, oe for database trasactios ad oe for shared re-etrat use of applicatio programs. The global database is paged i a data pool that is shared by all of the processes, ad rutime code is shared amog processes. This strategy results i a highly optimized, memory-efficiet system. The global database is the physical structure that cotrols the storage of data. The database ca be accessed through SQL requests or M global refereces, as the programmer sees fit. A full set of utilities for database maagemet are also provided. ANSI-Stadard M Laguage Processor The M programmig laguage is widely used for database applicatios, particularly i iteractive eviromets. Although it is best kow for offerig programmers the ability to develop programs rapidly ad chage them easily, M is also recogized for providig high performace i iteractive trasactio-orieted database eviromets. M is oe of the few laguages that is defied by a ANSI Stadard, which idicates its importace to a wide audiece i the data processig commuity. Coformity to this stadard protects software ad hardware ivestmets ad facilitates a level of portability ucommo i other programmig laguages. M is accepted by ANSI-Stadard SQL as a host laguage for embedded SQL. ANSI-Stadard SQL Laguage Processor ANSI-Stadard SQL is the most widely used query laguage for relatioal database systems. Ope M/SQL permits SQL queries to be etered directly through a iteractive widow, or to be embedded i M routies. SQL ca be used ot oly to retrieve data, but also to isert, update, ad delete data. IterSystems SQL implemetatio is compatible with ANSI-Stadard SQL. IterSystems also provides umerous SQL laguage extesios to ehace the power of SQL queries. Ope M/SQL Developer Guide 1-9

32 Chapter 1 Itroductio to Ope M/SQL Relatioal Data Dictioary Ope M/SQL icludes a advaced relatioal Data Dictioary that allows you to defie the database as a group of tables. Extesive capabilities are built ito the Data Dictioary to avoid code redudacy. Data Dictioary maps defie the coectio betwee the logical ad physical storage structure of the tables. Maps ca be automatically geerated to produce default structured tables. Alteratively, advaced M programmers may wish to defie their ow maps to coform with the global structures of existig applicatios or to desig a ew database structure compliat to applicatio specificatios. Relatioships amog tables ca be described i the Data Dictioary by defiig characteristic or desigative relatioships betwee tables. Whe you defie these relatioships i the Data Dictioary, jois amog tables are implicit ad occur i queries automatically, freeig the programmer ad ed-user from the tedious ad demadig task of specifyig explicit jois i SQL statemets. The Data Dictioary ca also be used to eforce itegrity costraits that apply to database modificatios made usig SQL ad forms desiged usig the Form Geerator. Processig triggers ca be attached to evets i database update ad form executio that cause related processig to occur automatically. For example, a trigger ca specify that whe a ivoice is deleted, associated lie items of the ivoice are also deleted. The system thus provides a meas to eforce referetial itegrity ad to defie applicatio-specific processig i the dictioary, elimiatig redudat programmig efforts. A database is defied as a fuctioally-related group of tables that have bee explicitly liked i the Data Dictioary. Tables i a sigle database ca be used to create a view. Views are cosidered virtual tables because they appear to be tables to the ed user, but are ot stored as such i the database. A view ca be used as a data source i queries ad reports. Views also perform a security fuctio by restrictig users' access to specified fields i database tables. Although describig the database i the Data Dictioary is essetial to the use of SQL queries, the Form Geerator, ad M/PACT, it is ot required for M programs that access the database oly through direct global refereces. Program Developmet Eviromet A Ope M/SQL applicatio ca cosist of data structures defied etirely i the Data Dictioary, with forms for data etry ad iquiry developed usig the Form Geerator ad reports for data output developed usig M/PACT. Alteratively, you ca write programs i the ANSI M programmig laguage, which is exteded i Ope M/SQL to allow the use of macros, iclude files, ad embedded SQL (M is a ANSI-approved host laguage for SQL). Ope M/SQL also provides a full set of utilities for routie developmet ad maagemet Ope M/SQL Developer Guide

33 Overview of the System Eviromet Had-Coded Programmig i Ope M/SQL For had-coded programmig, Ope M/SQL allows you to work at two levels of processig the macro source code level ad the itermediate source code level. Typically, you create routies a the macro source level, though you may also create routies at the itermediate code level. Macro source code permits the defiitio of macros ad embedded SQL statemets usig a combiatio of ANSI Stadard M sytax, special macro preprocessor commads, ad ANSI Stadard SQL. The macro preprocessor phase of the Ope M/SQL Compiler coverts macro source code ito M routies called itermediate code. You ca view ad edit itermediate code routies usig the Full Scree Editor. From itermediate code the Ope M/SQL Compiler geerates executable code, called object code. Macro source code ca make use of iclude files, which cotai defiitios that are used i the preprocessor phase of compilatio to expad macros ad determie whether optioal lies of code should be icluded. They ca also be used to iclude a commo block of code i several routies, savig the overhead of calls to a commo subroutie. Ope M/SQL Iterpreted Compiler Ope M/SQL combies the best elemets of iterpreted ad compiled systems. Iterpreters are easy to use because they allow program developmet, testig, ad modificatio i a simple, itegrated process. Fully compiled code rus faster tha iterpreted code but typically ivolves more work for the programmer. Ope M/SQL provides program debuggig facilities at the itermediate code level. These debuggig facilities operate like iterpreted systems. Whe a error or breakpoit occurs, the routie is suspeded ad a message appears idicatig exactly where the error or breakpoit occurred. You ca examie ad modify variables, arrays, ad database data, edit the routie, ad resume debuggig at ay locatio i the program without restartig the testig process. Whe you isert a ew lie ito a Ope M/SQL itermediate code routie, Ope M/SQL s icremetal Compiler automatically processes the code, producig efficiet object code. The system always executes the object code versio of the routie ever the itermediate code versio. The Ope M/SQL icremetal Compiler is totally trasparet; you eed ever issue separate compilatio or likage commads explicitly. For purposes of security, you ca delete the macro source or itermediate code versio of ay routie ad still execute the object code. Furthermore, by simply erasig a lie with the ZREMOVE commad ad isertig a ew lie i its place with the ZINSERT commad, you ca edit a object code routie as if the source code were preset. Ope M/SQL will maitai a audit trail of ay ew lies. Ope M/SQL Developer Guide 1-11

34 Chapter 1 Itroductio to Ope M/SQL The Form Geerator ad M/PACT Meu Geerator Query Optimizer The Form Geerator allows you to automatically geerate data etry/iquiry forms from Data Dictioary table defiitios. You ca the modify these forms to your exact specificatios usig a scree editor called QuickForm. The Form Geerator also supports the isertio of M code ad SQL statemets to further ehace the processig scope of your forms. M/PACT is a add-o optio that allows you to geerate highly formatted reports based o data from the Data Dictioary. Desiged for use by o-programmers as well as programmers, M/PACT eables you to desig sophisticated reports without the use of a complex commad laguage. Reports are geerated from your aswers to questios logically preseted i a easy-to-use widow-based iterface. Though a M/PACT developmet licese is required i order to develop M/PACT reports, a RDBMS Egie licese is sufficiet to ru M/PACT reports. Ope M/SQL icludes a Meu Geerator that ties a variety of programs ad optios together. The Meu Geerator ca create two types of meus: meu objects ad old-style meus. Meu objects are defiitios that iclude the list of optios for a meu, its scree positioig, ad its display attributes. Meu objects ca be ru as either meu bars, which display horizotally across the scree, or pop-up meus, which display optios vertically o the scree. Old-style meus ca be either vertical meus, which display a variety of optios i a vertical list, or horizotal meus, which display optios i a horizotal list across the bottom of the scree. Meu optios ca iclude the followig: M code, SQL code, routies, forms, widows, reports, queries, ad other meus. A usee but extremely importat part of Ope M/SQL is the query optimizer. Durig program compilatio ad query processig, the query optimizer aalyzes hudreds ad sometimes thousads of differet solutios to a iformatio request, ultimately selectig the best solutio. The result is compiled routies whose speed ad efficiecy guaratee optimal database throughput ad respose time, based o the applicatio ad database desig Ope M/SQL Developer Guide

35 Overview of the System Eviromet M/NET Networkig The database eed ot reside o a sigle computer. M/NET is a add-o optio that supports both local area ad wide area etworks withi Ope M/SQL. M/NET works trasparetly, i.e. it is ivisible to both the programmer ad eduser. M/NET ca access remote databases ad split a database across multiple computers. M/NET also allows mixig the hardware of differet vedors. M/NET features the Distributed Cache Protocol (DCP), which is a high-speed, blockorieted etworkig protocol that is proprietary to IterSystems. Some of the other etworkig protocols curretly supported by M/NET are: Etheret TCP/IP DSM-DDP OMI UDP RS-232 DT Network DT Network is IterSystems PC etwork techology for distributig databases over Local- ad Wide-Area etworks (LANS ad WANS). It supports cliet/server architecture flexibly, i that each etworked computer ca act as a cliet, a router, a server, or all three. DT Network supports a variety of database protocols, icludig: Distributed Cache Protocol (DCP) ISNET for sharig globals with Ope M/SQL platforms Ope M/Itercoect (OMI), for coectivity to other M databases DSM/DDP, IterSystems implemetatio of Digital Equipmet Corporatio s Distributed Database Protocol (DDP) Serial Networkig usig serial lies for coectivity It is possible to use multiple database protocols o the same machie. These database protocols also operate over a variety of etwork protocol stacks. For more iformatio, see the DT-MAX Network Cofiguratio Guide. Ope M/SQL Developer Guide 1-13

36 Chapter 1 Itroductio to Ope M/SQL Ope M/SQL Rus o Top of Ay M Implemetatio Ope M/SQL rus i a eviromet that is idepedet of the uderlyig M implemetatio. You ca develop ad ru Ope M/SQL applicatios o ay of the followig host M systems: ISM DSM DTM Microetics MSM No matter what M implemetatio you are usig as the host eviromet, Ope M/SQL supports full applicatio developmet ad ru-time capabilities. This allows existig users of these M systems to protect their curret software ivestmets while takig full advatage of Ope M/SQL s extesive relatioal database ad applicatio developmet capabilities. O ISM systems, Ope M/SQL stores routies i a global called ^ROUTINE. O all other host M systems, Ope M/SQL stores routies i a global called ^mroutie. O all of the above host M eviromets, you may create ad edit macro source routies usig the Ope M/SQL Full Scree Editor. You may also use the full suite of Ope M/SQL routie maagemet utilities to operate o routies. Note To comply with all M implemetatios, IterSystems has reamed the routie maagemet utilities to be implemetatio-idepeedet. The implemetatioidepedet ames of the utilities all begi with u ad are lowercase. See Chapter 7, Ope M/SQL Routie Maagemet Utilities for more iformatio about these utilities. Ope M/SQL applicatios are completely portable across M systems. This meas applicatios ca be developed o oe M system ad ported to other M systems (for cotiued developmet or ru time purposes) without modificatio, as log as they are writte i ANSI-Stadard M code ad do ot iclude implemetatiospecific extesios. This portability is made possible by Ope M/SQL s Export/Import facility, which geerates programs specific to a supported M system without disturbig the programs o the developmet system Ope M/SQL Developer Guide

37 Itegratio of Two ANSI Stadards Itegratio of Two ANSI Stadards Embedded SQL Ope M/SQL itegrates two ANSI Stadard programmig laguages: SQL ad M. SQL is a stadard query laguage for relatioal databases. M is a powerful procedural programmig laguage ad ANSI-approved host laguage for SQL. Together they form a itegrated eviromet for applicatios developmet. SQL statemets that access the database to select, isert, update, or delete rows (records) ca be directly embedded withi M routies. SQL statemets iserted ito M routies are called embedded SQL statemets. No-embedded queries are SQL queries etered ito a special query template or etered iteractively through a query editor; the results of a o-embedded query ca be output to the termial scree or to a priter. If the query is a SELECT query, the result may or may ot be a sigle row. Cursors Embedded SQL statemets ca be cursor-based or o-cursor-based. A cursorbased statemet is used to retrieve multiple rows from a table repetitively, oe row at a time. A cursor-based query icludes a DECLARE statemet, a OPEN statemet, oe or more FETCH statemets, ad a CLOSE statemet. For example, if a programmer is writig a routie to access all ivoices for a particular customer that are older tha a give date, his routie must: 1) DECLARE a cursor, 2) issue a OPEN of the specified cursor, 3) perform a FETCH repetitively o that cursor to get the ext ivoice that meets the query criteria, ad fially 4) perform a CLOSE o the cursor whe the processig is complete. A UPDATE or DELETE could also be used followig a FETCH to edit or delete the row retured by the FETCH. A o-cursor-based SQL statemet embedded i a routie performs a sigle operatio, such as retrievig a sigle row, isertig a ew row ito a table, or updatig or deletig a specific row. A o-cursor-based SQL statemet is appropriate whe the operatio is iteded to act o oly oe row. Iserted Code for Data Dictioary, Forms, ad Reports Programmers ca also isert M ad SQL code ito tables, forms, ad reports i a variety of places, icludig triggers, lookup queries, computed field defiitios, ad coversio ad validatio codes. This allows the programmer to take full advatage of Ope M/SQL s automatic geerator capabilities without costig him/her the ability to create highly customized applicatios. The powerful sytax ad flexible variable ad database structures of M makes it, alog with SQL, a excellet laguage for providig this customizatio. Ope M/SQL Developer Guide 1-15

38 Chapter 1 Itroductio to Ope M/SQL Accessig the Global Database The Ope M/SQL global database ca be accessed via the SQL laguage or the M laguage, both together, usig SQL code embedded withi M code, ad idepedetly. I this way existig M applicatios ca icorporate the use of SQL over time; o large coversio is required. SQL - Relatioal Database Access SQL ca be used for database queries or to isert, update, or delete rows i a table. SQL queries ca be etered iteractively ad the results displayed o a termial, or they ca be embedded withi M routies. Global structures that were built i a o-relatioal maer by M programs ca be described relatioally i the Data Dictioary. This is cosistet with the relatioal model, which does ot demad a specific physical storage structure or desig. This special feature eases the migratio to SQL ad the applicatio geerator features of Ope M/SQL for cliets whose applicatios were developed with M. M Global Refereces M also allows the use of global refereces for direct access to ad modificatio of the database. It is possible to make direct global refereces to global structures, regardless of whether they have bee defied i the Data Dictioary. The same data ca be refereced by either SQL or global refereces. The choice of access techique is up to the programmer ad database maager. Thus, existig M applicatios ca icorporate the use of SQL over time; o large coversio is required Ope M/SQL Developer Guide

39 Ope M/SQL Program Structure Ope M/SQL Program Structure Ope M/SQL programs are orgaized i uits called routies. A routie is a idividual block of code that is compiled, ad the ru. I Ope M/SQL, all routie likig is dyamic at ru time. The programmer ever eeds to lik routies explicitly. Ope M/SQL routies ca exist at three levels: Macro source level Itermediate code level Object code level The three types of routies ad their developmet ad maagemet i Ope M/SQL are discussed below. Macro Source Routies Typically, you create routies at the macro source level. Macro source routies ca iclude preprocessor sytax that permits macros, optioal lie iclusio, iclude files, ad embedded SQL. Macro source routies are compiled ito itermediate ad object code routies. All routies have macro source code, o matter what host M eviromet you are usig. Itermediate Code Routies The middle level of routies is called itermediate code, which is the stadard 3GL M source code available i all M implemetatios. The macro preprocessor phase of the Ope M/SQL Compiler produces itermediate code from macro source code. At the itermediate code level, all preprocessor sytax is resolved, ad the routie cotais oly pure M source code. You may create, view, ad edit routies at the itermediate code level usig the Full Scree Editor. Whe you create routies at the itermediate code level, you must do so without the beefit of embedded SQL or ay preprocessor sytax, such as macros. Itermediate level source code is displayed o the termial durig debuggig or error message display. Ope M/SQL Developer Guide 1-17

40 Chapter 1 Itroductio to Ope M/SQL Object Code Routies Object code is the lowest level of routie code. This is the code that is actually executed. The Ope M/SQL Compiler produces object code from itermediate code. Routies ca ru i their object code form eve if the macro source ad itermediate code have bee deleted. Each M implemetatio hadles object code differetly. Ope M/SQL Routie Utilities ad Editors Ope M/SQL icludes a umber of routie utilities; some are desiged to aid program developmet, while others assist system operatios ad maiteace: Routie developmet utilities provide editig, error aalysis, date ad time coversio, compilatio, ad maiteace capabilities. Developer utilities provide editig, object itegrity checkig, strig search, ad compilatio capabilities. Global utilities provide aalysis ad cotrol of the global database. System operatio ad maiteace utilities check hardware ad database itegrity, protect globals, ad maage ad cotrol the database ad etworks. Most Ope M/SQL utilities are respose drive. I other words, they use meus ad prompt you for iput. I additio, the utilities ofte iclude o-lie documetatio describig their uses ad fuctios. Ope M/SQL provides the Full Scree Editor for use i creatig ad editig of macro source routies, iclude files, ad itermediate code routies. A lie-by-lie editor for the editig ad debuggig of itermediate code routies is also available. Routie Utilities for No-ISM Implemetatios of M Ope M/SQL provides a set of utilities for editig Ope M/SQL macro source routies. These routie utilities are available to all Ope M/SQL users regardless of the host M eviromet. I additio, for users of Ope M/SQL ruig o o-ism systems, the host M implemetatio will usually provide its ow utilities for itermediate ad object code maagemet, global maagemet, ad system maagemet Ope M/SQL Developer Guide

41 Ope M/SQL Program Structure Distributed Data Processig Ope M/SQL s distributed data processig feature eables you to lik computer systems. From ay system ode, a user with appropriate access privileges ca read ad modify the global database aywhere i the system etwork. To referece a global o aother system, you ca: Issue the global referece with a exteded sytax that specifies the directory ad a system ame for the other computer, or Use stadard global sytax to referece a implicit global (a global that resides o aother computer or i aother directory o the same computer). Ope M/SQL Developer Guide 1-19

42 Chapter 1 Itroductio to Ope M/SQL 1-20 Ope M/SQL Developer Guide

43 CHAPTER The Ope M/SQL Relatioal Database 2 Ope M/SQL is based o a advaced relatioal model, which defies the database as a group of tables. IterSystems has exteded the relatioal model to allow the defiitio of desigative ad characteristic relatioships betwee tables. I Ope M/SQL, ay related group of tables that resides withi a M data partitio is cosidered a database. The M data partitio is usually referred to as a directory or UCI, depedig o your M system. A Ope M/SQL database correspods to the schema i the relatioal model. Ope M/SQL cosiders ay related group of tables that resides withi a M data partitio to be a database. The M data partitio is usually referred to as a directory or UCI, depedig o your M system. This chapter discusses relatioal cocepts ad their implemetatio i Ope M/SQL. Specifically, it covers the followig topics: Ope M/SQL Implemets Relatios as Tables Ope M/SQL Implemets Schemas as M Directories The Ope M/SQL Data Dictioary Accessig Data i a Ope M/SQL Relatioal Database IterSystems Extesios to the Relatioal Model Ope M/SQL Developer Guide 2-1

44 Chapter 2 The Ope M/SQL Relatioal Database Ope M/SQL Implemets Relatios as Tables A relatioal database is characterized by: A database structure that cosists of a collectio of tables (also called relatios or files ). The presece of a query laguage that permits the maipulatio of these tables i a mathematically complete maer. The table, which is the basic uit of data storage i the relatioal model, is a collectio of rows (also called tuples or records ) ad colums (also called fields or attributes ). Each colum cotais a particular type of data, such as iteger, date, or text. (Colums may also cotai ull values.) Each row i a table correspods to a real world etity ad cotais exactly oe value for each colum i the table. Below is a sample relatioal table: Table 2-1: A Sample Relatioal Table EmpName EmpNum HireDate Status Salary Graiger,Lisa /06/90 Part-Time 28, Corso,Bob /08/86 Active 15, Doe,Suzae /05/87 Active 38, Fast,Felix /23/89 Active 44, Filey,Jack /09/85 Part-Time 77, Gable,Bill /02/92 Active 44, Ope M/SQL Tables Follow The First Normal Form Tables follow what is called the First Normal Form; that is, each colum of a sigle row cotais exactly oe value, which may be ull if the field is empty. I some o-relatioal database systems, a colum for a sigle row might cotai several values. For example, the Child field i a People table might cotai the ames of three childre; a sigle child field might also have three gradchildre. However, i a relatioal system, each paret/child/gradchild relatioship is represeted by a separate row. For istace, each child of a give paret will occupy a uique row i the table despite the commoality of their paret fields. Likewise, each gradchild of that paret will also occupy its ow uique row. This meas that if a paret has three childre who i tur have three childre apiece, the relatioal model uses ie separate rows to describe the etire geealogy. 2-2 Ope M/SQL Developer Guide

45 Ope M/SQL Implemets Relatios as Tables Alteratively, separate tables called characteristic tables (see below) ca be used to desigate relatioships betwee parets, childre, ad gradchildre. The database desiger must choose how s/he wats Ope M/SQL to hadle paret/child relatioships. Ope M/SQL Supports Two Types of Tables Ope M/SQL supports two types of tables: Base tables Virtual tables A base table is a autoomous, amed table. Ulike virtual tables, base tables exist physically i the sese that they are mapped directly to physical storage structures. We say that base tables are amed because the table is explicitly give a ame via a appropriate defiitio statemet, ulike, for example, the result of a query, which is ot explicitly amed ad exists oly ephemerally. A virtual table is a amed table derived from oe or more base tables. Virtual tables are ot directly represeted i physical storage. Rather, they are abstract collectios of base tables. Examples of virtual tables iclude the output from a SELECT query ad views. Views are widows through which data from multiple base tables ca be viewed. Ope M/SQL allows views to serve as data sources for M/PACT reports, SQL queries, ad other views. No two rows of a base table are idetical. I virtual tables, two or more rows may be idetical. RowID/Primary Key The primary key or RowID is a field or combiatio of fields that serve as the uique idetifier to each row i a base table. At ay give time, o two rows of the base table may cotai the same primary key value.for example, the primary key of a Employees table might be the uique employee umber; as each employee is idetified by a uique employee umber, each employee row i the table is idetified by the value of the employee umber field. Sice two rows of a base table caot be idetical while two rows of a virtual table ca, oly base tables have primary keys. Virtual tables (results of queries, for example) do ot have primary keys. I Ope M/SQL, the RowID field is the primary key. The RowID is a sigle field of the table that uiquely idetifies the row. Optioally, the database desiger ca base the RowID field o oe or more other fields. Ope M/SQL Developer Guide 2-3

46 Chapter 2 The Ope M/SQL Relatioal Database Ope M/SQL Implemets Schemas as M Directories I the relatioal model, a schema is a coceptual repository for a group of relatios. No relatio withi the schema ca have the same ame as aother. I Ope M/SQL, the uit equivalet to the schema is a M database. I Ope M/SQL, a M database ca be spread over oe or more directories. Each directory cotais oe compoet MUMPS.DAT file of the etire M database. A MUMPS.DAT file is usually referred to by the ame of the operatig system directory i which it resides. All tables defied i the same M directory must have uique ames. The system maager's directory cotais a database directory table. The database directory table cotais the database ame, directory, ad directory set if etworked. Ope M/SQL Database Structure for No-ISM Implemetatios of M Whe Ope M/SQL is layered o top of a o-ism implemetatio of M, the database cocept is implemeted differetly. For example, uder DSM, Ope M/SQL cosiders all tables withi a uique UCI ad volume set to be a commo database. Other M systems employ various other schemes for storig the list of databases. For more iformatio, see the documetatio provided with your M system. 2-4 Ope M/SQL Developer Guide

47 The Ope M/SQL Relatioal Data Dictioary The Ope M/SQL Relatioal Data Dictioary I Ope M/SQL, tables are defied ad mapped to M global storage structures through the Ope M/SQL Relatioal Data Dictioary. Mappig defies the lik from the logical represetatio of a table to the physical storage of that table. Whe you defie a database, the Relatioal Data Dictioary ca geerate a default global storage structure, or if you prefer, you may specify a customized global storage structure. The Relatioal Data Dictioary also lets you map existig global structures to Ope M/SQL. The Data Dictioary cotais defiitios for all the base tables that comprise the database. It also cotais map specificatios for the uderlyig data storage structures. The Form Geerator, the SQL query facilities, ad M/PACT all rely o Data Dictioary-defied structures. The widow-based Data Dictioary makes the process of defiig data structures very simple. It allows the programmer to develop applicatios usig automated map geeratio facilities, ad eables the likig of existig Ope M/SQL applicatios, thus providig access to stored data through SQL, forms, ad reports. The followig aspects of a database are defied i the Data Dictioary: Its coceptual elemets (base tables, fields) RowIDs that eable data retrieval Global data storage ( map specificatios of global structures) Idexes for data access efficiecy Implicit jois - characteristic relatioships ad desigative refereces Triggers that eforce referetial itegrity ad cotrol applicatio processig Views that cotrol users' access to tables Data validatio parameters for data isert ad update Code to covert field values betwee data etry formats (exteral format) ad database storage formats (iteral format) Lookups for row selectio i forms Field access code for forms Field display iformatio for forms ad reports Ope M/SQL Developer Guide 2-5

48 Chapter 2 The Ope M/SQL Relatioal Database Accessig Data i a Ope M/SQL Relatioal Database Oce you have defied tables i the Ope M/SQL Relatioal Data Dictioary, you ca access data from those tables by ay of the followig meas: SQL queries you may embed queries i M macro source code, or you may defie them via the Ope M/SQL Query Defiitio template or the Iteractive SQL Query Editor M global refereces (i cojuctio with or idepedet of SQL) Data etry, iquiry, ad update forms desiged usig the Form Geerator Reports defied ad formatted usig M/PACT This sectio provides a brief overview of relatioal operatios i SQL, the ANSI- Stadard Query Laguage. SQL eables the retrieval of data from the relatioal database for the geeratio of queries ad reports. Refer to a SQL text for a full uderstadig of this laguage. Chapter 9, Ope M/SQL Implemetatio of SQL, describes IterSystems extesios to stadard SQL. Usig SQL to Query the Database Ope M/SQL lets you query the database usig stadard SQL SELECT statemet queries. Queries access data i tables ad views. The output from a query forms a virtual table ad leaves the targeted table(s) uchaged. You ca referece multiple tables i a sigle query. SQL eables you to use the followig relatioal operatios whe queryig a database: Combiig tables (or, more accurately, viewig tables as if they had bee combied ito oe larger table) Selectig particular colums from a sigle table or a combied table Specifyig particular rows i a sigle table or a combied table Relatioal algebra provides the coceptual foudatio for these relatioal operatios. Uderstadig how the relatioal algebra works will help you take full advatage of the capabilities of SQL. Coceptually, the relatioal algebra operates o oe or more tables to produce a ew (virtual) table. For example, a joi combies two tables ito a third. Or, a select operatio extracts selected rows from oe table to produce aother table. A virtual output table is the result of the relatioal operatio. 2-6 Ope M/SQL Developer Guide

49 Accessig Data i a Ope M/SQL Relatioal Database The list of fudametal relatioal operators icludes: Cartesia Product creates a cross-product of multiple tables, i.e. views the tables as if they had bee combied ito oe larger table Project selects particular colums from a sigle table or a combied table Restrict selects particular rows from a sigle table or a combied table Joi selects some fields from some rows of multiple tables based o some relatioship betwee the fields of the differet tables Cartesia Product Table.Name Sytax Whe referecig fields i a SQL query you may optioally precede the field ame with the ame of the base table to which it belogs, usig the followig sytax: Table.Field For example, a SELECT clause might read as follows: SELECT Employees.EmpName, Depts.DeptName If you do ot use prefixes whe creatig field ames that reflect the ame of the base table i which they reside, it is geerally a good idea to use this sytax for clarity. If a query refereces multiple tables ad those tables cotai fields with idetical field ames, you must use the Table.Name sytax. The Cartesia Product of two tables is the cross-product of all possible combiatios of rows from the two tables, such that each row of the first table is combied (cocateated) with each row of the secod table. I SQL, the Cartesia Product operatio occurs whe two or more tables are explicitly or implicitly (withi a view) amed i the FROM clause, all fields i those tables are amed i the SELECT clause, ad o WHERE clause is preset to specify relatioships amog the tables. Example I the example below, the tables Employees ad Departmets are combied to form a virtual table, which is their Cartesia Product, by issuig the followig SQL statemet: SELECT * FROM Employees,Departmets The asterisk i the SQL SELECT statemet is used to deote all fields i the specified tables. Ope M/SQL Developer Guide 2-7

50 Chapter 2 The Ope M/SQL Relatioal Database The Employees table is show below: Table 2-2: Employees Table EmpName EmpNum DeptNum Bravo, Vicki Doe, Suzae Corso, Bob The Departmets table is show below: Table 2-3: Departmets Table DeptNum DeptName NumEmp DeptMgr 1000 Sales 50 Bravo, Vicki 2000 Admiistratio 101 Corso, Bob 3000 Developmet 200 Doe, Suzae The table below represets the Cartesia Product of the Employees table ad the Departmets table: Table 2-4: Output Table After Cartesia Product Operatio E.EmpName E.EmpNum E.Dept- Num D.Dept- Num D. DeptName D.Num- Emp D.DeptMgr Bravo, Vicki Sales 50 Bravo,Vicki Bravo, Vicki Admiistratio 101 Corso, Bob Bravo, Vicki Developmet 200 Doe, Suzae Corso, Bob Sales 50 Bravo,Vicki Corso, Bob Admiistratio 101 Corso, Bob Corso, Bob Developmet 200 Doe, Suzae Doe, Suzae Sales 50 Bravo,Vicki Doe, Suzae Admiistratio 101 Corso, Bob Doe, Suzae Developmet 200 Doe, Suzae Note that this output may ot be ordered by the Employees.EmpName field. The orderig is subject to the specificatios i the ORDER BY clause of the SQL query, ad 2-8 Ope M/SQL Developer Guide

51 Accessig Data i a Ope M/SQL Relatioal Database Project The project operatio extracts a subset of fields from a existig table. The result is a ew table (a virtual table) with the same umber of rows but fewer fields. You ca perform a Project operatio o a sigle table or o a combiatio of tables. Example I the example below, the fields EmpName ad DeptName are selected from the Cartesia Product of the tables Employees ad Departmets. SELECT Employees.EmpName,Departmets.DeptName FROM Employees,Departmets The SELECT clause specifies the fields to be icluded i the projected table. The Cartesia Product is derived from the tables amed i the FROM clause. This Project operatio yields the followig table: Table 2-5: Output Table After Cartesia Product Operatio EmpName Bravo, Vicki Bravo, Vicki Bravo, Vicki Corso, Bob Corso, Bob Corso, Bob Doe, Suzae Doe, Suzae Doe, Suzae DeptName Sales Admiistratio Developmet Sales Admiistratio Developmet Sales Admiistratio Developmet Whether you perform a query o oe or may tables, the coceptual result is always a ew table that is derived from existig tables i the database. Ope M/SQL Developer Guide 2-9

52 Chapter 2 The Ope M/SQL Relatioal Database Restrict The Restrict operatio selects a desigated set of rows from oe or more tables. I the SQL query laguage, restrictio is expressed through the WHERE clause, which uses the compariso operatios, such as >, <, ad =, for example: or WHERE City= Bosto WHERE Age>20 You ca perform a Restrict operatio o a sigle table or o a combiatio of tables. Example I the example below, all fields are selected from the Cartesia Product of the tables Employees ad Departmets, but the output table is restricted to oly those rows for which the NumEmp field has a value greater tha 100: SELECT * FROM Employees,Departmets WHERE Employees.NumEmp > 100 The SELECT clause uses the asterisk (*) to select all fields for iclusio i the table. The Cartesia Product is derived from the tables amed i the FROM clause. The WHERE clause desigates the coditio for the restrictio operatio. This Restrict operatio yields the followig table: Table 2-6: Output Table After Restrict Operatio E.EmpName E.EmpNum E.Dept- Num D.Dept- Num D.DeptName D.Num- Emp D.DeptMgr Bravo, Vicki Admiistratio 101 Corso, Bob Bravo, Vicki Developmet 200 Doe, Suzae Corso, Bob Admiistratio 101 Corso, Bob Corso, Bob Developmet 200 Doe, Suzae Doe, Suzae Admiistratio 101 Corso, Bob Doe, Suzae Developmet 200 Doe, Suzae Note that restrictio occurs through the WHERE statemet, ot through the SELECT statemet. The SELECT statemet is used for projectio, as discussed above Ope M/SQL Developer Guide

53 Accessig Data i a Ope M/SQL Relatioal Database Jois Jois provide the meas of likig data i oe table with data i aother table ad are frequetly used i defiig reports ad queries. A joi is a operatio that combies two tables to produce a third, subject to a restrictive coditio. Every row of the ew table must satisfy the restrictive coditio. Usually, whe the two tables (A ad B) are combied to form a third table (C), some coditio is specified i the WHERE clause. This coditio determies how a row from B is chose to combie with a row from A. Ofte, this coditio is equality, such that the value of a particular field from table A equals the value from a particular field from table B. Combiig tables i this way is called a equijoi. Equijois are ofte referred to as ier jois. Although jois are ofte thought of as fudametal operators, they represet a combiatio of Cartesia Product plus Restrictio. Example For a example of a ier joi, cosider the followig two tables, a Suppliers table ad a Parts table: Table 2-7: Suppliers Table SNum SName SCity S1 Smith Paris S2 Joes Lodo S3 Blake Bosto S4 Whitey Bosto S5 Roberts Paris Table 2-8: Parts Table PNum PName PCity P1 Nut Paris P2 Screw Housto P3 Cog New York P4 Wheel Bosto P5 Switch Bosto Ope M/SQL Developer Guide 2-11

54 Chapter 2 The Ope M/SQL Relatioal Database Suppose you wish to query the database for the ames of every supplier, part, ad city, where the supplier ad part are located i the same city. To do this, you would use the followig SQL query: SELECT SName,PName,SCity FROM Suppliers,Parts WHERE Suppliers.SCity=Parts.PCity The SELECT clause specifies the fields to be icluded i the projected table. The Cartesia Product is derived from the tables amed i the FROM clause of the above SQL statemet, which combies the tables Suppliers ad Parts. The WHERE clause i the above statemet (Suppliers.SCity=Parts.PCity) specifies the ier joi coditio. The Cartesia Product of the Suppliers table ad Parts table is show below. The rows that satisfy the ier joi coditio are shaded. Table 2-9: Output Table After Cartesia Product Operatio SNum SName SCity PNum PName PCity S1 Smith Paris P1 Nut Paris S1 Smith Paris P2 Screw Housto S1 Smith Paris P3 Cog New York S1 Smith Paris P4 Wheel Bosto S1 Smith Paris P5 Switch Bosto S2 Joes Lodo P1 Nut Paris S2 Joes Lodo P2 Screw Housto S2 Joes Lodo P3 Cog New York S2 Joes Lodo P4 Wheel Bosto S2 Joes Lodo P5 Switch Bosto S3 Blake Bosto P1 Nut Paris S3 Blake Bosto P2 Screw Housto S3 Blake Bosto P3 Cog New York S3 Blake Bosto P4 Wheel Bosto S3 Blake Bosto P5 Switch Bosto S4 Whitey Bosto P1 Nut Paris S4 Whitey Bosto P2 Screw Housto S4 Whitey Bosto P3 Cog New York S4 Whitey Bosto P4 Wheel Bosto 2-12 Ope M/SQL Developer Guide

55 Accessig Data i a Ope M/SQL Relatioal Database Table 2-9: Output Table After Cartesia Product Operatio (Cotiued) SNum SName SCity PNum PName PCity S4 Whitey Bosto P5 Switch Bosto S5 Roberts Paris P1 Nut Paris S5 Roberts Paris P2 Screw Housto S5 Roberts Paris P3 Cog New York S5 Roberts Paris P4 Wheel Bosto S5 Roberts Paris P5 Switch Bosto This joi operatio yields the followig output table: Table 2-10: Output After Joi Operatio SName SCity PName Smith Paris Nut Blake Bosto Wheel Blake Bosto Switch Whitey Bosto Wheel Whitey Bosto Switch Roberts Paris Nut Whe the joi is based o a exact match betwee fields from the two tables, it is a simple joi. Rows i the both tables where o match is foud do ot appear i the output table. There are o rows i the output table for the cities, Lodo, New York, or Housto. Ope M/SQL Developer Guide 2-13

56 Chapter 2 The Ope M/SQL Relatioal Database IterSystems Extesios to the Relatioal Model IterSystems has exteded SQL ad the relatioal model to iclude two additioal types of jois: oe-way outer jois ad implicit jois. Oe-Way Outer Jois With stadard ier jois, whe rows of oe table are liked with rows of a secod table, a row i the first table that fids o correspodig row i the secod table is excluded from the output table. With oe-way outer jois, all rows from the first table are icluded i the output table eve if there is o match i the secod table. The first table pulls relevat iformatio out of the secod table but ever sacrifices its ow rows for lack of a match i the secod table. Whe specifyig a oe-way outer joi, the order i which you ame the tables i the FROM clause is very importat. The first table you specify is the source table for the joi. You specify a outer joi by usig the symbol =* i place of = i the WHERE clause of the SQL query. Example I the example below, the Suppliers table is specified as the source table for a oe-way outer joi operatio (=*) with the Parts table, where the SCity field matches the PCity field. SELECT SName,PName,SCity FROM Suppliers,Parts WHERE Suppliers.SCity=*Parts.PCity The SELECT clause specifies the fields to be icluded i the projected table. The Cartesia Product is derived from the tables amed i the FROM clause of the above SQL statemet, which combies the tables Suppliers ad Parts. The WHERE clause i the above statemet (Suppliers.SCity=*Parts.PCity) specifies the oe-way outer joi coditio. This query returs all rows from the Suppliers source table as well as ay rows from the Parts table where the SCity field matches the PCity field Ope M/SQL Developer Guide

57 IterSystems Extesios to the Relatioal Model This joi operatio yields the followig output table: Table 2-11: Output After Joi Operatio SName SCity PName Smith Paris Nut Joes Lodo Blake Bosto Wheel Blake Bosto Switch Whitey Bosto Wheel Whitey Bosto Switch Roberts Paris Nut Implicit Jois Oe of the most powerful features of the relatioal model is its ability to hadle uaticipated ad hoc queries i a graceful ad straightforward maer. However, for may implemetatios this capability is costly: the power to joi tables i complex ways ofte meas sacrificig the ease of executig jois for the more commo coectios betwee tables. IterSystems has solved this problem by implemetig the implicit joi. Implicit jois are pre-defied jois betwee tables which you specify i the Data Dictioary. They allow you to defie queries without specifyig the WHERE coditio that is used to joi tables. Ope M/SQL supports two types of implicit jois, desigative refereces ad characteristic relatioships. Desigative refereces ad characteristic relatioships are useful for: Pre-defiig commoly used jois Improvig data access efficiecy Formally specifyig itegrity costraits Note You may oly defie desigative ad characteristic relatioships amog tables that reside withi a sigle database. Ope M/SQL Developer Guide 2-15

58 Chapter 2 The Ope M/SQL Relatioal Database Desigative Refereces A desigative referece is a may-to-oe lik betwee tables i which oe field of the desigatig table cotais the Row IDs of all rows i the desigated table. A desigative referece is said to be a o-depedet lik because rows i the refereced table exist idepedetly of rows i the desigatig table. I relatioal database termiology, the desigatig table has a foreig key o the refereced table. I M termiology, the desigatig table has a poiter to the refereced table. I Ope M/SQL, a field that desigates aother table is called a desigative referece field. I the example below, the Customer field of the Ivoice table serves as the Desigative Referece field to rows i the Customer desigated table: Table 2-12: Ivoice Table IvNum IvTotal Customer C , C , C4 Table 2-13: Customer Table Number Name Address C1 Acme Hardware 10 Mai Stree Bosto, MA C2 Waterfrot Motors 210 Willow Street Brighto, MA C3 Global Furiture th Street New York, NY C4 Hill Pharaceuticals 958Jorda Ave. Pittsburgh, PA The Desigative Referece field, whe it is ot empty, cotais a value that idetifies oe ad oly oe row of the refereced table. Every etry i the Customer field of the Ivoice table that is ot empty must have exactly oe correspodig etry i the Customer table. However, ot all of the Number values i the Customer table eed appear i the Customer field of the Ivoice table. I this way, a desigative referece satisfies the relatioal defiitio of a oe-way outer joi Ope M/SQL Developer Guide

59 IterSystems Extesios to the Relatioal Model Furthermore, whe the Ivoice table is liked by desigative referece to the Customer table, the followig is true: There may be ivoices with o Customer value, but If a Customer value appears, there must also be a Number value i the Customer table with the same value, ad There may be customers with o ivoices Desigative refereces cotribute to data storage efficiecy by helpig to elimiate uecessary redudacy. Sice you ca access the iformatio through a desigative referece to the Customer table, it is ot ecessary to store the customer ames ad addresses i the Ivoice table. Accordigly, updates eed be made i oly oe table, rather tha i two or more tables. A table may have several fields that desigate the same or differet tables. Similarly, a table may be desigated by ay umber of tables. For example, the Ivoice table may cotai aother desigative referece field to the Accouts table. Ad the Accouts table might have a desigative referece to the Customer table. Characteristic Relatioships A characteristic relatioship is a lik betwee tables i which rows i oe table (the child table ) are existece-depedet (caot exist without) o rows i aother table (the paret table ), such that paret rows have a oe-to-may relatioship with child rows. A child table always desigates its paret table. For this reaso, a characteristic relatioship ca be thought of as a kid of desigative referece. However, a characteristic relatioship is more restrictive tha a desigative referece sice the joi coditio specifies that all rows of the child table must desigate the same paret table row. I this way, a characteristic relatioship satisfies the relatioal defiitio of a ier joi. Extedig our previous example, the Lie Items table, show below, is a child table of the Ivoice table (its paret). The existece of the Lie Items table is etirely depedet o its paret Ivoice table. If a ivoice is deleted from the paret table, its lie items become 'orphaed' ad must also be deleted, or trasferred to a foster paret. Withi the Data Dictioary defiitio of a table, you may set a trigger that will fuctio to automatically delete all child rows whe its paret is deleted. Ope M/SQL Developer Guide 2-17

60 Chapter 2 The Ope M/SQL Relatioal Database Each row of the Ivoice table ca have multiple lie items, illustratig the oe-to-may relatioship: Table 2-14: Ivoice Table IvNum IvTotal Customer , C , C C1 Table 2-15: Lie Items Table IvNum Item UitCost Quatity Amout 2222 Chair , Desk , Rug , Bookshelf , A Ivoice row might also have o lie items. Though characteristic relatioships may be perceived as hierarchical, they comply with the teets of the relatioal model; just as other tables, child tables ca be addressed through SQL without explicit referece to the paret table. A paret table may have several child tables. For example, a Patiet table may have Visits, Medical Problems, ad Lab Tests as child tables. However, a child table may have oly oe paret. (The Visits table, for example, may be a child oly of the Patiet table.) A child table ca ever be 'orphaed', i.e. exist without a paret table Ope M/SQL Developer Guide

61 IterSystems Extesios to the Relatioal Model Implicit Joi Sytax Implicit jois simplify the process of queryig the database. By defiig characteristic relatioships ad desigative refereces i the Data Dictioary, you may take advatage of Ope M/SQL's implicit joi sytax to facilitate the defiitio of queries. Arrow sytax, a dash followed by a greater-tha symbol ( -> ), is a IterSystems SQL extesio used to idicate a implicit joi betwee tables. This sytax causes a additioal outer joi coditio to be added implicitly to the WHERE clause ad the joied table to be added implicitly to the FROM clause of a SQL query. I Ope M/SQL, you may use arrow sytax i the followig three cases: 1. To sigify Desigative Refereces betwee tables 2. To sigify Child-to-Paret Refereces betwee tables 3. To sigify Paret-to-Child Refereces betwee tables Implicit Joi Sytax i a Desigative Referece If the field A.b desigates table B, ad x is a field i table B, the referece: A.b->x poits to the value of x i the row of table B correspodig to A.b. It is iterpreted as a referece to B.x with B added implicitly to the FROM clause ad a additioal outer joi coditio added implicitly to the WHERE clause. For example, the followig query retrieves the patiet's ame ad patiet's doctor's ame for every patiet who lives i Bosto: SELECT Patiet.Pame, Patiet.Doctor->Dame FROM Patiet WHERE Patiet.City = Bosto Assumig that Patiet.Doctor is a desigative referece to the Doctor table, the above query is equivalet to: SELECT Patiet.Pame,Doctor.Dame FROM Patiet,Doctor WHERE Patiet.City = Bosto AND Patiet.Doctor = *Doctor.Doctor Ope M/SQL Developer Guide 2-19

62 Chapter 2 The Ope M/SQL Relatioal Database Implicit Joi Sytax i a Child-to-Paret Referece If P is the paret of C ad x is a field i P, the implicit joi sytax: C.P->x for a give row poits to the value of x i that row's paret row. It is iterpreted as a referece to P.x with P added implicitly to the FROM clause ad a additioal outer joi coditio added implicitly to the WHERE clause. For example, give a paret table Customer with a child table Ivoice, the followig query: SELECT Ivoice.Customer->Name FROM Ivoice WHERE Ivoice.Number = is equivalet to: SELECT Customer.Name FROM Ivoice,Customer WHERE Ivoice.Number = AND Ivoice.Customer = Customer.Customer Implicit Joi Sytax i a Paret-to-Child Referece If P is the paret of C ad x is a field i C, the implicit joi referece: P.C->x for a give P row poits to the value of x i a child row of that row. It is iterpreted as a referece to C.x with C added implicitly to the FROM clause ad a additioal outer joi coditio added to the WHERE clause. For example, give paret Customer with child Ivoice, the followig query for all ivoices for all customers amed Smith: SELECT Customer.Ivoice->Number FROM Customer WHERE Customer.Name = Smith is equivalet to: SELECT Ivoice.Number FROM Customer,Ivoice WHERE Customer.Name = Smith AND Customer.Customer = Ivoice.Customer 2-20 Ope M/SQL Developer Guide

63 IterSystems Extesios to the Relatioal Model Itegrity Costraits Implicit joi defiitios iclude built-i itegrity costraits. For istace, the existece-depedet relatioship betwee the Lie Items table ad the Ivoice table may be regarded as a itegrity costrait: o lie item ca exist without a correspodig ivoice. The Ope M/SQL relatioal Data Dictioary ca be used to defie other itegrity costraits, such as: Field validatio code to eforce itegrity costraits at the field processig level, such as affect field values, required fields, ad field formats. Triggers to eforce table itegrity costraits, such as complex iteractios betwee fields, or the prohibitio of DELETEs from the table. Multi-Lie Fields Ope M/SQL exteds the relatioal database model by permittig the creatio of multi-lie fields. Such fields are useful for storig iformatio about a sigle etity where that iformatio spas several lies. A typical multi-lie field might be used for a address or a block of commet text. Ope M/SQL treats the data i multi-lie fields as a sigle etity, i accordace with First Normal Form priciple of the relatioal model. IterSystems SQL supports the use of multi-lie fields i iput operatios (INSERT ad UPDATE statemets) ad output operatios usig INTO lists by creatig a array ad matchig each lie of the multi-lie field to a ode i the array. IterSystems SQL also supports the amig of multi-lie fields i the SELECT statemet of SQL SELECT queries. It does ot, however, allow the use of multi-lie fields to perform comparisos or row orderig i a SQL SELECT query. You ca access pieces of multi-lie field data usig the M laguage, but this use of multi-lie fields is ot recommeded, because it does ot adhere to first ormal form. Ope M/SQL Developer Guide 2-21

64 Chapter 2 The Ope M/SQL Relatioal Database 2-22 Ope M/SQL Developer Guide

65 PART Program Developmet II Chapter 3 Ope M/SQL Program Developmet Chapter 4 Full Scree Editor Chapter 5 Developig Macro Source Routies Chapter 6 Routie Hadlig ad Maiteace Chapter 7 Ope M/SQL Routie Maagemet Utilities

66

67 CHAPTER Ope M/SQL Program Developmet 3 This chapter presets a brief overview of the facilities available for program developmet i Ope M/SQL. Specifically, it covers the followig topics: Programmig Methods Full Scree Editor Itermediate Code Routies Routie Maagemet Utilities Developer Utilities Programmer Iterface to Applicatios Ope M/SQL Developer Guide 3-1

68 Chapter 3 Ope M/SQL Program Developmet Programmig Methods Ope M/SQL allows the programmer to develop had-coded applicatios at two levels: the macro source level ad the itermediate code level. Typically, you create routies at the macro source level. At the macro source level, you may defie macros, refer to existig macros, ad write pure M code or embed SQL statemets usig a combiatio of ANSI-Stadard M sytax, special macro preprocessor commads, ad ANSI-Stadard SQL. Macro source code also makes use of iclude files. Like macro source code, iclude files may cotai M sytax, SQL sytax, ad preprocessor sytax. The macro preprocessor phase of the Ope M/SQL Compiler coverts macro source code ito M code with a iteral form of embedded SQL. This coverted code is called itermediate code. You may view ad edit routies at the itermediate code level. You may also create routies directly at the itermediate code level, although without the beefit of embedded SQL or preprocessor sytax, such as macros. Oe strategy you may use is to create pure M routies at the itermediate code level, copy those routies to the macro source level usig the %urcopy utility, the edit the routies i the Full Scree Editor to iclude preprocessor sytax ad embedded SQL. The Full Scree Editor You may use the Full Scree Editor to edit ay of the followig types of routies: Macro source routies Iclude files Itermediate code routies You must use the Full Scree Editor to create ad edit macro source routies ad iclude files. You may create ad edit itermediate code routies either usig the Full Scree Editor or directly from the M prompt usig the Routie Lie Editor. 3-2 Ope M/SQL Developer Guide

69 Itermediate Code Routies Itermediate Code Routies Routie Lie Editor Ope M/SQL provides three ways to create itermediate code routies: 1. Itermediate code routies are the products of compiled macro source code routies these routies cosist of M code with the possible iclusio of embedded SQL statemets. 2. You may create itermediate code routies i the Full Scree Editor these routies cosist of pure M source code. 3. You may create itermediate code routies at the M programmer mode prompt these routies cosist of pure M source code. The Routie Lie Editor lets you edit ad debug itermediate code routie lies ad isert ew routie lies directly from the M programmer prompt. The Routie Lie Editor operates oly o itermediate code it does ot operate o macro source code or iclude files. For more iformatio o usig the Routie Lie Editor to develop ad edit itermediate code routie lies, see the Ope M/SQL M Programmig Guide. Routie Maagemet Utilities IterSystems provides a set of pre-defied utilities for examiig ad maipulatig routies ad iclude files. These routie utilities are useful for developig ad maitaiig Ope M/SQL applicatios. See Chapter 7, Ope M/SQL Routie Maagemet Utilities, for a complete descriptio of the Ope M/SQL routie maagemet utilities. Ope M/SQL Developer Guide 3-3

70 Chapter 3 Ope M/SQL Program Developmet Developer Utilities IterSystems provides a set of utilities useful for testig ad developig programs ad maipulatig program objects. These utilities perform fuctios that iclude checkig the itegrity of program objects, searchig for strigs i objects, ad compilig sets (called cofiguratios) of objects. For a complete descriptio of the Ope M/SQL developer utilities see Chapter 12, Ope M/SQL Developer Utilities. Programmer Iterface to Applicatios Ope M/SQL combies the precisio of had-coded programmig with the speed ad ease of applicatio geeratio to provide a totally itegrated applicatio developmet eviromet. You ca referece Data Dictioary-defied global structures usig ay combiatio of SQL ad M code. Ope M/SQL provides etry poits that eable you to call meus, forms, ad reports from aywhere i your applicatio. You ca isert M ad SQL code directly ito base table defiitios, form defiitios, meu defiitios, ad report defiitios, which allows you to develop highly customized applicatios while still preservig Ope M/SQL s automatic-geeratio capabilities. I the Data Dictioary, you ca defie processig triggers to eforce itegrity costraits or to automatically ivoke related processig actios every time a certai evet occurs. You ca eter code to perform data validatio checkig ad coversio of user-etered ad edited data. You ca defie computed fields that will automatically calculate data values based o user iput. Ad you ca maually isert your ow M code to customize lookup ad filig routies. I the Form Geerator, you ca maually isert M ad SQL code at the form level, widow level or field level to customize your applicatio to your exact specificatios. You ca use processig triggers to program widow brachig that respods i differet ways to differet situatios. These are but a few of the may ways the Ope M/SQL eviromet combies custom programmig flexibility with the ease of automatic geeratio. 3-4 Ope M/SQL Developer Guide

71 CHAPTER Full Scree Editor 4 This chapter describes the Ope M/SQL Full Scree Editor. The Full Scree Editor is used for creatig, editig, ad viewig macro source routies, itermediate code routies, ad iclude files. Specifically, this chapter covers the followig topics: Overview of the Full Scree Editor Ivokig the Full Scree Editor Full Scree Editor Scree Display Navigatig the Full Scree Editor Meu System Editig Operatios Gettig Help Exitig the Full Scree Editor Ope M/SQL Developer Guide 4-1

72 Chapter 4 Full Scree Editor Overview of the Full Scree Editor The Full Scree Editor is a Ope M/SQL utility that allows you to view a etire block of source code ad edit sectios of it. By cotrast, the alterative editig utility, the Routie Lie Editor, allows oly lie-by-lie editig (see the Ope M/SQL M Programmig Guide for a i-depth descriptio of the Routie Lie Editor). Full Scree Editor Features The Full Scree Editor provides all of the followig capabilities: Cut ad paste capabilities Search ad replace fuctios Ability to work i more tha oe buffer or widow at a time Automatic sytax checkig A lockout mechaism to prevet overwrites Whe you edit a routie i the Full Scree Editor, you are editig a temporary copy of the routie. Pressig the <PREVIOUS> key ivokes a save meu that displays optios for savig, compilig, ad reamig the routie as well as a optio for exitig the Full Scree Editor. Routie Types for Editig Usig the Full Scree Editor, you may edit ay of the followig types of routies: Macro source routies Iclude files Itermediate code routies (ANSI Stadard M) The routie i your curret M partitio 4-2 Ope M/SQL Developer Guide

73 Ivokig the Full Scree Editor Ivokig the Full Scree Editor You ca ivoke the Full Scree Editor from either the M programmer prompt or from withi the Ope M/SQL developmet eviromet. Procedure To ivoke the Full Scree Editor from the M programmer prompt: 1. Issue ay of the followig commads at the M programmer prompt: > do ^%rde or: > do ^% or: > x ^% Edit:.E To exit from the Edit: prompt befor ivokig the Full Scree Editor, type a period (.), ad press <RETURN>. Note If you are ruig Ope M/SQL o a o-ism host M system, you must use the first commad (^%rde). Oce ivoked, the Full Scree Editor prompts you to load a routie, as follows: Load Routie: At this prompt you may either load a existig routie or create a ew routie. See below for iformatio o both optios. Ope M/SQL Developer Guide 4-3

74 Chapter 4 Full Scree Editor Procedure To ivoke the Full Scree Editor from the Ope M/SQL developmet eviromet: 1. At the M programmer prompt, type the followig commad to eter Ope M/SQL: > do ^%msql You see the Termial Type prompt, as show below: Termial Type: VT220 => 2. At the Termial Type prompt, eter the ame of the termial type you are curretly usig. You may press <RETURN> to accept the system-wide default termial type. You see the Ope M/SQL User Idetificatio widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³³ Ope M/SQL User Idetificatio ³³ ³ÃÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ÃÙ À ³ ³³ WELCOME TO OPEN M/SQL ³³ ³³ ³³ ³³ Versio F ³³ ³³ Maiteace Release F.7 ³³ ³Ã Ú ³ ³ÀÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÙ³ ³ÚÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ÃÙ À ³ ³³ User Name Password ³³ ³³ ³³ ³³ ³³ ³³ Laguage ³³ ³³ ³³ ³Ã Ú ³ ³ÀÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÙ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ User Logi Eter a valid Ope M/SQL userame. Press <Help> For Help 3. At the UserName field o the Ope M/SQL User Idetificatio widow, eter your Ope M/SQL UserName, ad press <RETURN>. 4. At the Password field o the Ope M/SQL User Idetificatio widow, eter the Password for your Ope M/SQL UserName, ad press <RETURN>. 4-4 Ope M/SQL Developer Guide

75 Ivokig the Full Scree Editor 5. At the Laguage field o the Ope M/SQL User Idetificatio widow, eter the laguage i which you wat to ru Ope M/SQL. To accept the system-wide default ru-time laguage, press <RETURN>. To choose a differet ru-time laguage, press <CTRL-L> to delete the system-wide default laguage. You may press the <LIST CHOICES> key to see a lookup box that lists the rutime laguages supported by Ope M/SQL. You see the Ope M/SQL Mai Meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄOpe M/SQL MeuÄÄÄ ³ ³ ³ Data Dictioary ³ ³ Forms ³ ³ Reports ³ ³ Queries ³ ³ Meu Geerator ³ ³ System Maagemet ³ ³ Privileges ³ ³ Developer Utilities ³ ³ User Utilities ³ ³ Server Maagemet ³ ³ Relatioal Gateway ³ ³ Help Optios ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Jul 05, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio Ope M/SQL Meu 03:50PM Press <Help> For Help 6. From the Ope M/SQL Mai meu, select the Developer Utilities optio. You see the M/SQL Developer Utilities meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄÄM/SQL Developer UtilitiesÄÄÄÄ ³ ³ ³ Export/Import Optios ³ ³ Object Compile Driver ³ ³ M/SQL Object Itegrity Checkig ³ ³ Object Strig Search Utility ³ ³ Full Scree Editor ³ ³ Macro Routie Utilities ³ ³ Query Object By Routie Prefix ³ ³ Natioal Laguage Reports ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Jul 05, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio Ope M/SQL Developer Guide 4-5

76 Chapter 4 Full Scree Editor M/SQL Developer Utilities 03:50PM Press <Help> For Help 7. From the M/SQL Developer Utilities meu, select the Full Scree Editor optio to ivoke the Full Scree Editor. Note: You may type f to select this optio it is a memoic accelerator. Oce ivoked, the Full Scree Editor prompts you to load a routie, as follows: Load Routie: At this prompt you may either load a existig routie or create a ew routie. See below for iformatio o both optios. Loadig Existig Routies To load a existig routie, eter the ame ad extesio of the routie or iclude file you wish to edit at the Load Routie prompt. Whe eterig the ame of a routie, if you do ot specify a suffix, Ope M/SQL assumes the.mac suffix. For example, to load the routie ABC.MAC, you may type the followig: Load Routie: ABC If you specify the ame of a routie that already exists, Ope M/SQL loads the routie ad ivokes the Full Scree Editor. Loadig Routies Automatically You ca set up Ope M/SQL to automatically load a specified routie wheever you ivoke the Full Scree Editor. You do this by settig the %first variable to the routie that you wat to be auto-loaded. Procedure To load a specified routie automatically: 1. From the M programmer prompt, set the %first variable to the routie that you wat to be auto-loaded. Use the followig sytax to do this: > SET %first= routie.ext where routie.ext is the ame ad extesio of the routie you wat to autoload. 2. Ivoke the Full Scree Editor. 4-6 Ope M/SQL Developer Guide

77 Ivokig the Full Scree Editor Creatig New Routies The Full Scree Editor automatically loads the routie stored i the %first variable. To create ad load a ew routie, use the procedure below: Procedure To create a ew routie usig the Full Scree Editor: 1. At the Load Routie prompt, eter the ame of a ew routie, as follows: Load Routie: NEWROU The Full Scree Editor automatically appeds the default extesio.mac to the routie ame you etered ad the issues the followig prompt: Load Routie: NEWROU the source 'NEWROU.MAC' does ot exist Cotiue with ew buffer? Y=> 2. Press <RETURN> to accept the Yes default ad load the ew routie ito the Full Scree Editor, or type No ad press <RETURN> to retur to the Load Routie prompt. Prevetig Overwrites The Full Scree Editor provides a lockout mechaism to esure that two programmers caot modify the same routie simultaeously. This mechaism issues a lock o a routie as soo as the first user retrieves it. The lockig mechaism prevets the followig scearios from occurrig: Prevets two users from editig the same.mac file simultaeously Prevets two users from editig the same.int file simultaeously Prevets two users from editig the same.inc file simultaeously Prevets oe user from editig the.mac versio of a routie while aother user is simultaeously editig the.int versio of the same routie, or vice versa. Whe the Full Scree Editor detects a lock o a routie, it allows the secod user to browse the routie i read mode, but the user caot edit or file the routie. Whe this happes, the termial beeps ad the Full Scree Editor displays the followig message at the bottom of the scree: ROUTINE IS LOCKED: Now i Read Mode Ope M/SQL Developer Guide 4-7

78 Chapter 4 Full Scree Editor As you browse the locked routie, the Status Lie cotiues to display the tag: (read) 4-8 Ope M/SQL Developer Guide

79 Full Scree Editor Scree Display Full Scree Editor Scree Display Below is a typicat Full Scree Editor scree display: EMPLIST ;List the employees i a give departmet ;Defie macro to covert a strig to uppercase ad remove ;puctuatio. Calls the etry poit 4alphaup^yraz(%a) as a ;fuctio ; #defie ALPHAUP(%a) $$alphaup^yraz(%a) ; ;Defie macro to get the exteral value of a retured field. ; #defie EXTERNAL(%a) $p(%a,$c(1),2) ; ;Declare cursors for accessig departmet tables. Selects fields ; Departmet ad Name from the Departmet: table ad puts them ito ;the M variables deptid ad deptame. ; ##sql(declare deptcurs CURSOR FOR SELECT Departmet, Name INTO :deptid, :deptame FROM Departmet WHERE (%ALPHAUP(NAME) %STARTSWITH :ame) ; ;Declare cursor for accessig Employee table. Selects fields "Name" EMPLIST.MAC(modified) Goto Fid Next Prev Select Cut/ Replace Check Buffer Mark Other Tag Strig Fid Fid Block Paste Strig Errors Meu Meu Meu The scree display is divided ito the followig three parts: Edit Field the top (ad major) portio of the scree Status Lie Directly below the Edit Field Horizotal Optios Meu Directly below the Status Lie Edit Field The Full Scree Editor display cosists of as may lies as will fit o your termial scree. Oe of those lies is reserved for the Status Lie ad two more are reserved for the Horizotal Optios Meu. The remaiig lies belog to the Edit Field. The typical termial scree cosists of 24 lies, therefore the Edit Field of a typical termial scree displays up to 21 lies of text. The Full Scree Editor is always i isert mode. The Edit Field scrolls appropriately as you isert ad delete text. Ope M/SQL Developer Guide 4-9

80 Chapter 4 Full Scree Editor Status Lie The Status Lie appears i reverse video betwee the Edit Field ad the Horizotal Optios Meu. It displays the followig iformatio: Name of the curret buffer Name of the curret routie Type of routie beig edited (.MAC,.INT,.INC) Whe chages have bee made to the curret routie, the Status Lie displays the followig tag: (modified) If the curret routie is o-modifiable, the Status Lie displays the tag: (read) The iformatio displayed o the Status Lie is stadard ad does ot vary across systems. The system, however, may alter the appearace of the iformatio. The stadard appearace format is as follows: Horizotal Optios Meu [buffer]routie_ame.type The Horizotal Optios Meu displays across the bottom of the scree, directly beeath the Status Lie. You ca use the optios o this meu to perform basic editig fuctios such as selectig ad movig text. Procedure To access a optio o the Horizotal Optios Meu: 1. From aywhere i the Edit Field of the Full Scree Editor, press the <GO TO BOTTOM MENU> key. The cursor moves to the Horizotal Optios Meu. 2. O the Horizotal Optios Meu, you may select ad ivoke a optio usig ay oe of the followig methods: a. Use the arrow keys to positio the cursor o the desired optio, ad press <RETURN> to ivoke it. b. Type the first letter of a optio (the cursor selects ad automatically ivokes the optio). c. Press <CTRL-E> plus the first letter of the desired optio. d. If you are selectig a optio from a submeu, you may type <CTRL-E>xy where x is the first letter of the primary meu optio ad y is the first letter of the submeu optio Ope M/SQL Developer Guide

81 Navigatig the Full Scree Editor Meu System Navigatig the Full Scree Editor Meu System Primary Meu The followig sectios list ad describe the optios located o each of the horizotal optios meus i the Full Scree Editor meu system The followig table lists ad describes the optios o the Primary Meu: Table 4-1: Optios o Primary Meu Optio Goto Tag Fid Strig Next Fid Prev Fid Select Block Cut/Paste Replace Strig Check Errors Buffer Meu Mark Meu Other Meu Fuctio Specify the tag ad offset withi your M routie that you wish to locate, usig the sytax: TAG TAG+3 TAG-3 Specify a strig to be located. Fids ext occurrece of a strig specified i previous Fid, workig towards the bottom of the buffer. Fids previous occurrece of a strig specified i a previous Fid, workig towards the top of the buffer. Tur o select mode. Ay cursor movemet while i select mode results i highlightig the text betwee the curret cursor positio ad its positio whe select mode was activated. Selectig this optio a secod time elimiates the highlightig. If select mode is o, cuts the cotets of the select regio from the text ad iserts it ito the paste buffer, the turs off select mode. If select mode is off, iserts the cotets of the paste buffer ito the curret buffer. Scas the buffer for a specified strig, ad optioally replaces it with aother. Sytax checks the routie from the locatio of the cursor dow, replacig the cursor at the begiig of the first lie i which it detects a sytax error. This is a error-by-error sytax checkig mechaism. Ivokes Buffers submeu (described below). Ivokes Mark submeu (described below). Ivokes Other submeu (described below). Ope M/SQL Developer Guide 4-11

82 Chapter 4 Full Scree Editor Buffers Meu Whe you select the Buffers Meu optio from the Primary Meu, you see the Buffers Meu. The table below lists ad describes the optios o the Buffers Meu: Table 4-2: Optios o Buffers Meu Optio Make Buffer Use Buffer Directory of Buffers Prit Buffer Load Routie Isert Routie Widows Meu Fuctio Make a ew buffer with a specified routie ame ad load that routie if it exists. Switch from oe buffer to aother. View the ames of all existig buffers. Prit the cotets of buffer to a device. Load a routie ito curret buffer, deletig the existig cotets of the buffer. Isert a routie ito curret buffer, without deletig the existig cotets. Ivokes Widows meu. Widows Meu Whe you select the Widows Meu optio from the Buffers Meu, you see the Widows Meu. The table below lists ad describes the optios o the Widows Meu: Table 4-3: Optios o Widows Meu Optio Two Widows Oe Widow Switch Widows Grow Curret Widow Fuctio Arrages the termial scree to display two buffers at the same time, each i its ow area (widow). Sets the termial scree to display oe buffer usig the etire scree area. Moves the cursor from oe buffer widow to the other. Icreases the size of oe of the two displayed widows, allowig it to occupy a greater portio of the scree Ope M/SQL Developer Guide

83 Navigatig the Full Scree Editor Meu System Mark Meu Whe you select the Mark Meu optio from the Primary Meu, you see the Mark Meu. The table below lists ad describes the optios o the Mark Meu: Table 4-4: Optios o Mark Meu Optios Set Mark Clear Mark Fid Mark Fuctio Mark a locatio i the curret buffer. Remove a mark from the curret buffer. Go to a specified mark i the curret buffer. Other Meu Whe you select the Other Meu optio from the Primary Meu, you see the Other Meu. The table below lists ad describes the optios o the Other Meu: Table 4-5: Optios o Other Meu Optio Redraw Scree Execute M Code M/SQL Fuctio Redraws scree without savig or deletig cotets of buffer. Prompts for lies of M code ad executes them. Type Q to exit from this optio. Ivokes Ope M/SQL Ope M/SQL Developer Guide 4-13

84 Chapter 4 Full Scree Editor Editig Operatios This sectio describes how to perform the followig text editig operatios: Movig the Cursor Isertig ad Deletig Text Cuttig ad Pastig Text Editig Multiple Copies of a Routie Displayig Multiple Buffers Settig a Mark i Your Curret Buffer Searchig For Text Strigs Replacig Text Strigs Movig the Cursor The use of cotrol keys simplifies cursor movemet for touch typists. The followig table describes the cursor positioig keys available for use i the Full Scree Editor: Table 4-6: Full Scree Editor Cursor Movemet Key Commads Keystroke(s) <RIGHT ARROW> or <CTRL-K> <LEFT ARROW> or <CTRL-H> <UP ARROW> or <CTRL-U> <DOWN ARROW> or <CTRL-J> <ENHANCE><RIGHT ARROW> <ENHANCE><LEFT ARROW> <ENHANCE><UP ARROW> <ENHANCE><DOWN ARROW> <CTRL-N> <CTRL-P> <CTRL-V> Fuctio Cursor moves oe character to the right. If at right physical margi, cursor moves to the first character of the ext lie. Cursor moves oe character to the left. If at left physical margi, cursor moves to the last character of the previous lie. Moves the cursor to the same colum positio o the ext physical lie up. Moves the cursor to the same colum positio o the ext physical lie dow. Moves the cursor to the ed of the curret M code lie. Moves the cursor to the begiig of the curret M code lie. Moves the cursor to the first character of the edit field. Moves the cursor to the first character of the last lie of the edit field. Moves the cursor to the ext tag. Moves the cursor to the previous tag. Moves the cursor to the last character of the routie beig edited (bottom of routie) Ope M/SQL Developer Guide

85 Editig Operatios Table 4-6: Full Scree Editor Cursor Movemet Key Commads (Cotiued) Keystroke(s) <CTRL-F> <CTRL-B> <CTRL-E><1> Fuctio Moves the cursor to the first character of the ext word*. Moves the cursor to the last character of the previous word*. Repaits the scree whe it is split ito two widows for the sytax error report. Isertig Text * A word is defied as ay sequece of characters delimited by oe or more spaces or commas. The Full Scree Editor is always i isert mode. Procedure To isert text: 1. Use the arrow keys to locate the cursor at the place where you wish to isert text. 2. Begi typig. Note: There is a implicit hard retur at the ed of each M code lie. Pressig <RETURN> breaks the lie. Deletig a <RETURN> jois the lie. DeletigText To delete text, use the appropriate key or key sequece from the followig table: Table 4-7: Text Delete Optios Keystroke Fuctio Descriptio <CTRL-D> Delete Curret Character Deletes the character o which the cursor is curretly positioed. <DELETE> Delete Previous Character Deletes the character to the left of the curret cursor positio. <CTRL-W> Delete Word Deletes from the curret cursor positio to the ed of the curret word. <CTRL-L> Delete to Ed of Lie Deletes from curret cursor positio to the ed of the curret physical scree lie. <CTRL-X> Udelete Restores a previously deleted character, word, or lie. Ope M/SQL Developer Guide 4-15

86 Chapter 4 Full Scree Editor Cuttig ad Pastig Text To cut ad paste text, use the followig procedure. Procedure To cut ad paste text: 1. Place the cursor at the begiig of the block of text that you wat to cut. 2. Press the <GO TO BOTTOM MENU KEY> to access the Horizotal Optios Meu. 3. From the Horizotal Optios Meu, choose the Select Block optio. The Select optio makes the cursor fuctio as a tool for highlightig blocks of text. 4. Move the cursor to the ed of the block of text that you wat to select. The cursor highlights all text i its path from the locatio where Select mode was activated. 5. Press the <GO TO BOTTOM MENU KEY> to access the Horizotal Optios Meu. 6. From the Horizotal Optios Meu, select the Cut/Paste optio to cut the text. Whe you cut text from the documet, the Full Scree Editor stores it i a area called the Paste Buffer. Each time you cut a block of text, the ew text overwrites the previous cotets of the Past Buffer. The Paste Buffer always cotais the most recetly cut block of text. 7. Move the cursor to the locatio where you wish to isert the text. 8. Press the <GO TO BOTTOM MENU KEY> to access the Horizotal Optios Meu. 9. From the Horizotal Optios Meu, select the Cut/Paste optio agai to paste the text Ope M/SQL Developer Guide

87 Editig Operatios Editig Multiple Copies of a Routie The Full Scree Editor provides buffers ad widows to let you edit multiple routies ad multiple copies of the same routie simultaeously. Buffers are coceptual spaces where you ca temporarily store text to be edited. The first routie loaded ito the Editor is automatically placed i a buffer called MAIN. You ca the create ad ame additioal buffers, ad place ew text ito the ew buffers. You ca also create empty buffers for use durig a editig sessio. Whe placig routies i buffers, you ca LOAD or INSERT. LOAD places the text ito the buffer, overwritig the curret cotets of the buffer. INSERT places the desigated text ito the buffer without deletig the curret cotets. Creatig a New Buffer Use the procedure below to create a ew buffer. Procedure To create a ew buffer: 1. Press the <GO TO BOTTOM MENU KEY> to access the Horizotal Optios Meu. 2. From the Horizotal Optios Meu, select the Buffer Meu optio. You access the Buffers Meu. 3. From the Buffers Meu, select the Make Buffer optio. You see the followig prompt i the bottom right-had corer of the scree: Make Buffer: 4. At the Make Buffer prompt, eter the ame of a ew buffer, ad press <RETURN>. The Full Scree Editor opes a ew buffer ad places you i isert mode. Selectig a Existig Buffer Use the procedure below to select a existig buffer. Procedure To select a existig buffer: 1. Press the <GO TO BOTTOM MENU KEY> to access the Horizotal Optios Meu. 2. From the Horizotal Optios Meu, select the Buffers Meu optio. You access the Buffers Meu. Ope M/SQL Developer Guide 4-17

88 Chapter 4 Full Scree Editor 3. From the Buffers Meu, select the Use Buffer optio. You see the followig prompt i the bottom right-had corer of the scree: Use Buffer: 4. At the Use Buffer prompt, eter the ame of the buffer you wat to edit, ad press <RETURN>. Note: To see a list of all curret buffers, select the Directory optio from the Buffer Meu. The Full Scree Editor opes the specified buffer ad places you i isert mode. Loadig a Routie ito the Curret Buffer Use the procedure below to load a routie ito the curret buffer. Procedure To load a routie ito the curret buffer: 1. Press the <GO TO BOTTOM MENU KEY> to access the Horizotal Optios Meu. 2. From the Horizotal Optios Meu, select the Buffer Meu optio. You access the Buffers Meu. 3. From the Buffers Meu, select the Load Routie optio. You see the followig prompt i the bottom right-had corer of the scree: Load Routie: 4. At the Load Routie prompt, eter the ame of the routie you wat to load, ad press <RETURN>. The Full Scree Editor load the specified routie ito the curret buffer, overwritig its previous cotets. Note: Usig the Isert Buffer optio allows you to isert the specified routie ito the curret buffer without overwritig its previous cotets Ope M/SQL Developer Guide

89 Editig Operatios Displayig Multiple Buffers The Full Scree Editor displays the cotets of a buffer i a widow. Widows i the Full Scree Editor let you display up to two buffers simultaeously. You ca cotrol the display of your buffers usig the Widows Meu. Whe displayig two buffers, the Full Scree Editor splits the display scree so that oe widow occupies the top half of the scree ad the other widow occupies the remaiig area of the scree above the status lie. Whe two buffers are sharig the scree, you ca cut ad paste betwee them. Editig commads fuctio o differetly for two widows tha for oe. Because the positio of the cursor determies the curret widow status, all editig commads fuctio o the widow i which the cursor is located. Procedure To display ad edit multiple buffers simultaeously: 1. Press the <GO TO BOTTOM MENU KEY> to access the Horizotal Optios Meu. 2. From the Horizotal Optios Meu, select the Buffer Meu optio. You access the Buffers Meu. 3. From the Buffers Meu, select the Widows Meu optio. You access the Widows Meu. 4. From the Widows Meu, select the Two Widows optio. You see the followig prompt i the bottom right-had corer of the scree: Use Buffer: 5. At the Use Buffer prompt, eter the ame of the buffer you wat to display i the secod widow, ad press <RETURN>. The Full Scree Editor splits the scree ito two halves, oe half for each of the two buffers beig displayed. Note: You ca cut ad paste betwee these two buffers. Ope M/SQL Developer Guide 4-19

90 Chapter 4 Full Scree Editor Settig a Mark i Your Curret Buffer You ca set a mark i your curret buffer to defie a locatio withi the text. Settig a mark does ot affect the surroudig text i ay way. Marks oly serve to defie locatios withi the text. Procedure To set a mark i the curret buffer: 1. Positio the cursor at the place i your text where you wat to set a mark. 2. Press the <GO TO BOTTOM MENU> key to access the Horizotal Optios Meu. 3. From the Horizotal Optios Meu, select the Mark Meu optio. You access the Mark Meu. 4. From the Mark Meu, select the Set Mark optio. You see the followig prompt i the bottom right-had corer of the scree: Mark Name: 5. At the Mark Name prompt, eter the ame of the mark you wat to edit, ad press <RETURN>. This sets a mark at the place i your text where the cursor is curretly positioed. You ca relocate the cursor back to this positio at ay time by selectig the Fid Mark optio o the Mark Meu ad specifyig the ame of the mark you wat to fid at the Goto Mark prompt. You ca also delete the mark at ay time by selectig the Clear Mark optio o the Mark Meu ad specifyig the ame of the mark you wat to delete at the Clear Mark prompt Ope M/SQL Developer Guide

91 Editig Operatios Searchig For Text Strigs You ca search your buffer for a text strig by usig the followig optios o the Horizotal Optios Meu: Optio Fid Strig Next Fid Prev Fid What It Does prompts you to specify a text strig ad searches for the strig from the curret cursor positio to the ed of the buffer searches from the curret cursor positio to the ed of the buffer for the ext istace of the same text strig searches from the curret cursor positio to the top of the buffer for the previous istace of the same text strig ReplacigText Strigs You ca use the Replace Strig optio o the Horizotal Optios Meu to specify a strig of text to search for (at the Replace prompt) ad a strig of text to replace each istace of the search strig (at the With prompt). The Replace Strig optio fids ad replaces all istaces of the search strig from the curret cursor positio to the ed of the buffer. Usig Cotrol Key Commads for Quicker Editig May commads i the Full Scree Editor are desigated by <CTRL-letter> keystroke sequeces. The followig table summarizes the keystrokes you ca use to issue commads for the Full Scree Editor. Noe of the iformatio cotaied here is termial specific. However, you may fid that ot all the <CTRL-letter> fuctios listed here are available to you, as they ted to vary with operatig system: Table 4-8: <CTRL-letter> Commads <CTRL-letter> <CTRL-A> <CTRL-B> <CTRL-D> <CTRL-E>-<letter> <CTRL-F> <CTRL-G>-<CTRL-H> <CTRL-G>-<CTRL-J> <CTRL-G>-<CTRL-K> Fuctio Advaces cursor several lies of text. Backs up cursor to first letter of previous word. Deletes curret character. Ivokes optio from primary meu begiig with specified letter. Advaces cursor to first character of ext word. Returs cursor to first character of curret M code lie. Moves cursor to ed of last physical lie displayed o scree. Moves cursor to ed of curret M code lie. Ope M/SQL Developer Guide 4-21

92 Chapter 4 Full Scree Editor Table 4-8: <CTRL-letter> Commads (Cotiued) <CTRL-letter> <CTRL-G>-<CTRL-U> <CTRL-G>-<CTRL-X> <CTRL-H> <CTRL-J> <CTRL-K> <CTRL-L> <CTRL-N> <CTRL-R> <CTRL-U> <CTRL-W> <CTRL-X> Fuctio Moves cursor to begiig of first physical lie displayed o scree. Udoes previous deletio. Moves cursor oe character to left. Moves cursor dow oe physical lie. Moves cursor oe character to right. Deletes rest of lie from curret cursor positio. Next tag. Moves the cursor back 15 lies, maitaiig the same cursor positio. Moves cursor up oe physical lie. Deletes to ed of curret word. Udoes previous deletio. Note For a complete listig of all keyboard-specific Full Scree Editor actio commads for each termial type supported by IterSystems, see the Appedix to this maual Ope M/SQL Developer Guide

93 Gettig Help Gettig Help You may press the <EXPLAIN> key at ay time while the cursor is located i the Edit Field to access the Full Scree Editor Help Meu. The Help Meu is a horizotal optios meu that appears at the bottom of the scree. Use the <LEFT ARROW> ad <RIGHT ARROW> keys to avigate the meu, ad press <RETURN> to select a optio. The table below lists ad describes the optios o the Help Meu: Table 4-9: Optios o Help Meu Optio Geeral Keys Optios Actio Fuctio This optio displays a list of all cotrol sequece commads curretly defied for the Full Scree Editor. This optio is ot curretly implemeted. This optio is ot curretly implemeted. This optio lets you select a actio o which you would like more iformatio. Whe you select this optio, you see the followig prompt i the bottom right-had corer of the scree: Actio: At the Actio prompt, specify the ame of a actio o which you would like more iformatio, ad press <RETURN>. The system displays a help widow that cotais a descriptio of the specified actio. You may also perform lookups of actios at the Actio prompt. Eter the first letter or sequece of letters for a actio ad press <RETURN> to see a lookup box that lists all actios with matchig ames. Ope M/SQL Developer Guide 4-23

94 Chapter 4 Full Scree Editor Exitig the Full Scree Editor Whe fiish editig a routie i the Full Scree Editor, you may press the <PRE- VIOUS> key to access the Full Scree Editor Save Meu. The Save Meu lets you save edits to a routie, compile a routie, reame a routie, ad exit the Full Scree Editor. You may press the <PREVIOUS> key at ay time while the cursor is located i the Edit Field. The Save Meu is a horizotal optios meu that appears at the bottom of the scree. Use the <LEFT ARROW> ad <RIGHT ARROW> keys to avigate the Save Meu, ad press <RETURN> to select a optio. The table below lists ad describes the optios o the Save Meu: Table 4-10: Optios o the Save Meu Optio Quit Save & Compile Oly Save Reame & Save Fuctio Exit the Full Scree Editor without savig or compilig the routie. Note: If you select this optio while there are usaved edits made to the routie, the Full Scree Editor displays the followig cofirmatio prompt before allowig you to exit the Editor without savig your edits: Quit without filig chages? Save ad compile routie. This optio may disrupt ay other process that is ruig the routie. See the discussio o ZSAVE i the Ope M Programmig Guide to lear the cosequeces of savig a program that aother process is executig. Save but do ot compile the cotets of the curret buffer. Save but do ot compile the cotets of the curret buffer as a ew routie. Automatic Sytax Checkig Wheever you compile a macro source or itermediate code routie, the Ope M/SQL Compiler automatically sytax-checks the code ad records all errors i a sequetial error log. The error log displays to the scree upo the completio of the compilatio. I the Full Scree Editor, you ca display the error log by selectig the Check Errors optio o the Primary Meu. The error log displays i its ow widow located i the lower half of a split scree. This scree split eables you to correct the routie while lookig at the error report. To erase the error log widow ad repait the scree, type <CTRL-E><1>. Note The Full Scree Editor does ot support sytax checkig for Ope M/SQL systems ruig o o-ism host M implemetatios Ope M/SQL Developer Guide

95 Exitig the Full Scree Editor Automatic Date ad Time Stamps The Full Scree Editor ca automatically stamp the date ad time i the form of a commet o the first lie of itermediate code routies wheever chages are saved. To eable this feature as the system-wide default behavior, the System Maager must issue the followig commad from the System Maager's directory: > set ^%rde( MARK )=1 Ope M/SQL Developer Guide 4-25

96 CHAPTER Developig Macro Source Routies 5 IterSystems recommeds that you write all routies (eve pure M routies) at the top level the macro source level. I order to create a macro source code routie, you must use the Full Scree Editor. This chapter describes how to develop macro source routies. Specifically, it covers the followig topics: Creatig Macro Source Routies The Ope M/SQL Macro Preprocessor Summary of Macro Preprocessor Commads Summary of Macro Preprocessor Fuctios Ope M/SQL Developer Guide 5-1

97 Chapter 5 Developig Macro Source Routies Creatig Macro Source Routies To create ad edit both macro source routies ad iclude files i Ope M/SQL, you must use the Full Scree Editor. Note You ca also create itermediate code routies usig the Full Scree Editor, but IterSystems recommeds creatig routies at the macro source level. Macro source code permits the use of macros ad embedded SQL statemets usig a combiatio of ANSI-Stadard M sytax, special macro preprocessor commads, ad ANSI-Stadard SQL. Macro source routies ca also refer to iclude files, which are useful for stadardizig the behavior of a set of programs ad for customizig a sigle source for differet eviromets. Macro source code ca use preprocessor commads ad keywords to do all of the followig: Provide ames for costats, expressios, ad other arbitrary text, which ca be replaced at compile time without sacrificig ru-time performace. Coditioally iclude lies of code. Iclude macro source code from amed iclude files. Tailor a sigle macro source routie to differet eviromets. Execute SQL statemets as part of a program. Compilig Macro Source Routies Whe you compile macro source routies, the Compiler works i two phases. First, the Compiler coverts the macro source routie ito pure M code, called itermediate code. This level of compilatio is called the macro preprocessor phase. Subsequetly, the Compiler compiles the itermediate code routie ito executable code, called object code. To compile a macro source routie, you may select the Save ad Compile optio of the Full Scree Editor after editig a macro source routie, or you may compile the routie directly from the M programmer prompt usig the %urcomp utility. 5-2 Ope M/SQL Developer Guide

98 Creatig Macro Source Routies Macro Source Routies ad Iclude Files Macro source code ca use iclude files. Iclude files cotai defiitios that are used i the preprocessor phase of compilatio to expad macros ad determie whether optioal lies of code should be icluded. They ca also be used to iclude a commo block of code i several routies, savig the overhead of calls to a commo subroutie. The table below summarizes the differeces betwee iclude files ad a macro source routies: Table 5-1: Macro Source Routies versus Iclude Files Macro Source Routie Created usig Full Scree Editor Named with suffix.mac Compiler produces itermediate code from the macro source routie, the traslates itermediate code ito executable object code routies Commets i source are icluded i the itermediate file Iclude File Created usig Full Scree Editor Named with suffix.inc Caot ivoke Compiler directly; must be refereced i a macro source routie Commets i iclude file are ot icluded i the itermediate file uless specified by the #show commad The Ope M/SQL routie maagemet utilities use the fileame suffix to distiguish betwee iclude files (FILENAME.INC) ad macro source routies (FILENAME.MAC). The suffixes may appear i either lower or upper case. Macro source routie ad iclude file ames may iclude up to 235 alphaumeric characters. They must begi with a alphabetic character. Uderscores are ot allowed. Case is sigificat. Macro Source Routies Are Portable Across M Implemetatios Macro source routies are completely portable across Ope M/SQL systems ruig o ay of the followig M implemetatios: ISM DTM DSM MSM You may create macro source routies i Ope M/SQL o ay of these M implemetatios, compile the routie ito itermediate code, ad the ru it o the same or ay other M implemetatio. Ope M/SQL Developer Guide 5-3

99 Chapter 5 Developig Macro Source Routies The Ope M/SQL Macro Preprocessor The Ope M/SQL macro preprocessor recogizes three kids of costructs, as show i the followig table: Costruct Symbol Preprocessor Commads # Preprocessor Fuctios ## or & Macro Refereces $$$ Macro Preprocessor Commads A preprocessor commad ca prompt the preprocessor to execute ay of the followig actios: Defie or udefie a macro Iclude the text of a iclude file Coditioally process cosecutive lies i the curret source Set a mode of operatio for the preprocessor A preprocessor commad must appear o a lie by itself, at the left margi or preceded by oe or more space or tab characters, as i the followig: tag set x=5,y=10 #iclude LIBNAME quit The followig is icorrect: tag set x=5,y=10 #iclude LIBNAME quit With the exceptio of the #defie commad, preprocessor commads ca be followed by a commet o the same lie. 5-4 Ope M/SQL Developer Guide

100 The Ope M/SQL Macro Preprocessor Macro Preprocessor Fuctios Macro Refereces A preprocessor fuctio is a expadable costruct that ca appear aywhere withi a lie of M code. Whe you compile the macro source code, the preprocessor lie expads ad is replaced by the desigated code. The preprocessor fuctio, &sql (or ##sql), is used to embed SQL statemets i a M program. A preprocessor fuctio ca appear aywhere i the text of a macro source routie, as i: set id=5 &sql(fetch ecurs INTO :ame) write!,ame quit Eve if the fuctio exteds across two or more lies, it ca be followed by code o its last lie, for example: set id=5 &sql(fetch ecurs INTO :ame) write!,ame quit The Compiler does ot expad preprocessor fuctios whe they are embedded iside quoted strigs, i.e., whe eclosed i double quote characters ( ), or i commets. A referece to a previously defied macro should cosist of the macro ame preceded by 3 dollar sigs ($$$) ad optioally followed by oe or more argumets i paretheses. Whe iserted, a macro referece is replaced by the defiitio of the macro as established by a previously specified macro defie (#defie) statemet. If the macro has bee defied to take argumets, argumet substitutio is performed to geerate the text value of the macro referece. A macro referece must be preceded ad followed by puctuatio characters or the begiig or ed of the macro source lie. The macro defiitio: #defie DATE $ZD($H,2) assigs the value $ZD($H,2) to the macro DATE. Thus, a subsequet occurrece of the macro source text, such as: w!, The date is,$$$date is replaced by: w!, The date is,$zd($h,2) The followig macro referece: xyz$$$versio is ivalid because it immediately follows a alphaumeric character. Ope M/SQL Developer Guide 5-5

101 Chapter 5 Developig Macro Source Routies The source text: $$$versioxyz is iterpreted as a referece to the macro amed versioxyz. Sice a macro referece caot be adjacet to a alphaumeric character, you caot use a macro to geerate part of a idetifier ame. The Compiler does ot expad macro refereces ad preprocessor fuctios whe they are embedded iside quoted strigs, i.e., whe eclosed i double quote characters ( ), or i commets. Refereces to udefied macros will produce error messages at compile time. The $$$ precedig the macro ame is left itact. Macro source lies that, after expasio, do ot cotai ay characters other tha space ad tab are omitted from the itermediate routie. 5-6 Ope M/SQL Developer Guide

102 Summary of Macro Preprocessor Commads Summary of Macro Preprocessor Commads The followig table lists ad briefly describes the commads supported by the macro preprocessor: Table 5-2: Macro Preprocessor Commads Preprocessor Commad #defie #udef #iclude #show #oshow #if #ifdef #ifudef (#ifdef) #else #elseif (#elif) #edif What It Does Defie a macro. Remove a macro defiitio. Iclude macro source text from a specified, previously created iclude file. Iclude commets from iclude files. Do't iclude commets from iclude files. (Default) Coditioally iclude the followig macro source text if a expressio is true. Coditioally iclude macro source text if a specified macro is defied. Coditioally iclude macro source text if a specified macro is ot defied. Iclude macro source text if the previous #if, #ifdef, or #ifudef failed. Iclude macro source text if the previous #if, #ifdef, or #ifudef failed ad a expressio is true. Termiate coditioal text. #; Defie sigle-lie, macro-oly commet lies #defie ad #udef The #defie statemet ca appear i several forms ad the #udef statemet i just oe form: #defie MACRONAME #defie MACRONAME VALUE #defie MACRONAME(PARAMETERS) VALUE #udef MACRONAME where MACRONAME is a valid macro ame (without the $$$) ad VALUE, separated from MACRONAME by at least oe space, cosists of the rest of the lie. VALUE ca be ay arbitrary text. The macro preprocessor strips leadig ad trailig spaces from VALUE. If the lie eds i a commet, the commet is icluded i the macro value. Ope M/SQL Developer Guide 5-7

103 Chapter 5 Developig Macro Source Routies #defie MACRONAME The first form of #defie causes MACRONAME to be defied with a ull value. This is useful primarily i combiatio with the #ifdef ad #ifudef commads (described below) that test whether or ot a macro is defied. #defie MACRONAME VALUE The secod form of #defie causes MACRONAME to be defied with the value of VALUE, for example: #defie release 3 A later referece to this macro, such as: go:currel<$$$release oldrel expads ito: go:currel<3 oldrel Aother example is the defiitio: #defie var ^abc(qsub for which the followig refereces: set x=$$$var_,) set y=$$$var_ ) expad ito: set x=^abc(qsub,) set y=^abc(qsub) #defie MACRONAME() VALUE The third form of #defie defies a macro that takes argumets, also called a fuctio macro. The argumet(s) may be oe or more alphaumeric strigs, each begiig with percet sigs ad separated by commas. Each of the parameter strigs ca occur oe or more times i VALUE, idicatig a substitutio. A referece to a fuctio macro takes the form $$$MACRONAME(), where the argumet(s) are ay character strigs separated by commas. Commas ad right paretheses ca be passed as macro argumets oly if they are part of quoted strigs. At expasio time, the macro preprocessor expads ay $$$MACRONAME refereces iside the paretheses, the substitutes the argumets for the correspodig % parameters i the macro s defiitio. 5-8 Ope M/SQL Developer Guide

104 Summary of Macro Preprocessor Commads For example, if the macro versio is defied as: #defie versio(%a,%b) %a_".0"_%b the the referece: write VERSION=,$$$versio($$$release, subrel ) causes the macro preprocessor to replace $$$release with 3 (defied i the example above) ad the substitute the argumets 3 ad subrel ito the text to produce: write VERSION=,3_.0 _ subrel Whe a macro is defied to accept argumets, you must referece it with the correct umber of argumets; otherwise, the macro preprocessor geerates a error. If a macro is defied without argumets, you may ever iclude paretheses i a referece to that macro. For example, the followig source text: #defie foo precise $$$foo()_ ly expads ito: Nested Expasio precise()ly I this case, the macro preprocessor will issue a warig message about the ull paretheses. #udef MACRONAME The #udef statemet causes MACRONAME to have a udefied value. The distictio betwee a ull value ad a udefied value is importat to the #ifdef ad #ifudef commads. Nested expasio occurs whe oe expadable property cotais a secod expadable property withi its expaded evaluatio. Macro defiitios, iclude file ames, ad embedded SQL text ca all cotai $$$MACRO refereces. Whe this happes, the macro preprocessor must resolve ested expasio. A macro referece is always expaded at the time that it is used to produce actual text. For example, whe the macro preprocessor ecouters the #iclude commad: #iclude $$$system it must evaluate the macro referece $$$system to decide which iclude file to use. Ope M/SQL Developer Guide 5-9

105 Chapter 5 Developig Macro Source Routies Macro refereces iside embedded SQL are expaded before the SQL text itself is evaluated. For more iformatio o usig macro refereces i embedded SQL, refer to the sectio etitled Referecig Macros i Embedded SQL i Chapter 8, Embedded SQL. Whe a macro referece is expaded, the macro preprocessor scas the result for additioal macro refereces. If it fids aother macro referece, the macro preprocessor expads it, the agai scas the result for further macro refereces, ad so forth util o macro refereces remai. If a macro referece is located iside a #defie statemet, it is ot evaluated util the macro beig defied is refereced. For example, the followig defie statemets: #defie release 3 #defie versio(%a) $$$release_.0 _%a cause the fuctio macro versio to be defied with the value: $$$release_.0 _%a where %a is the macro s argumet. The macro preprocessor expads the referece to $$$release oly whe the macro versio is refereced. The source text: write $$$versio( subrel ) expads ito: write $$$release_.0 _ subrel ad fially ito: write 3_.0 _ subrel If a #defie statemet later redefies release to be 4, the a subsequet occurrece of the statemet write $$$versio(subrel) i the macro source will expad ito: write 4_.0 _ subrel 5-10 Ope M/SQL Developer Guide

106 Summary of Macro Preprocessor Commads #ifdef, #ifudef, #if, #else, #elseif, ad #edif The #ifdef preprocessor commad icludes a block of source text oly if the specified macro ame has a defied value. The #ifudef commad (also abbreviated #ifdef for compatibility with the C programmig laguage) has the opposite meaig. It icludes a block of source text if the specified macro ame does ot have a defied value. The #if commad icludes a block of source text if the specified expressio evaluates to true (i.e., a o-zero, umeric value). The expressio cosists of M macro source that, after expasio, produces a M expressio. Sice this expressio is evaluated at compile time (ot at ru time), ay refereces to local variables or extrisic fuctios are resolved i the eviromet i which the program is compiled. Sice the compilatio eviromet is difficult to predict, you should use cautio whe referecig local variables ad extrisic fuctios iside #if expressios. The #else commad specifies a block of source text to be icluded if the previous #ifdef, #ifudef, #if, or #elseif commad was ot satisfied. The #elseif commad (also abbreviated #elif) icludes a block of source text if the previous #ifdef, #ifudef, #if, or #elseif commad was ot satisfied ad if the specified expressio evaluates to true. These statemets have four sytax optios, as described i the followig sectios. Sytax 1 #if EXPRESSION (SOURCE TO INCLUDE IF EXPRESSION IS TRUE) #else (SOURCE TO INCLUDE IF EXPRESSION IS FALSE) #edif ;optioal ;optioal For example: #if $$$versio<$$$latestversio do covert($$$versio) #edif Ope M/SQL Developer Guide 5-11

107 Chapter 5 Developig Macro Source Routies Sytax 2 #if EXPRESSION A (SOURCE TO INCLUDE IF EXPRESSION A IS TRUE) #elseif EXPRESSION B ;optioal (SOURCE TO INCLUDE IF EXPRESSION A IS FALSE AND EXPRESSION B IS TRUE) ;optioal #elseif EXPRESSION C ;optioal (SOURCE TO INCLUDE IF EXPRESSIONs A & B ARE FALSE AND EXPRESSION C IS TRUE) ;optioal #edif For example: #if $extract($$$applicatio)= F #iclude FINANCIAL #elseif $extract($$$applicatio)= S #iclude SALES #elseif $extract($$$applicatio)= M #iclude MARKETING #edif Sytax 3 #ifdef MACRONAME (SOURCE TO INCLUDE IF MACRO DEFINED) #else (SOURCE TO INCLUDE IF MACRO NOT DEFINED) #edif ;optioal ;optioal For example: #ifdef debug if dbmode= halt do ^dbhalt #else if dbmode= go do ^dggo #edif 5-12 Ope M/SQL Developer Guide

108 Summary of Macro Preprocessor Commads Sytax 4 #ifudef MACRONAME (SOURCE TO INCLUDE IF MACRO NOT DEFINED) #else (SOURCE TO INCLUDE IF MACRO DEFINED) #edif ;optioal ;optioal For example: Notes #ifudef TERMTYPE #defie BUFSIZE 512 #else #defie BUFSIZE 1024 #defie DECTYPE 220 #edif Note the followig: The source code coditioally icluded by #if, #ifdef, ad #ifudef may iclude preprocessor commads. As is show i the above examples, #if's, #ifdef's, ad #ifudef's may be ested. The ames of macros refereced iside #if expressios must be prefaced by $$$. Idetatio of preprocessor commads, as is used i the above examples, is optioal. It is used here to assist readability. #iclude The preprocessor commad: #iclude FILENAME.INC causes the macro preprocessor to treat the cotets of the iclude file FILE- NAME.INC i the curret directory as the ext part of the macro source code. The iclude file ca cotai ay kid of macro source text, icludig ested #icludes. Ope M/SQL Developer Guide 5-13

109 Chapter 5 Developig Macro Source Routies The differeces betwee a iclude file ad a macro source routie are: Iclude files have the suffix.inc. Macro source routies have the suffix.mac. You caot directly ivoke the Compiler o a iclude file. Whereas commets i a macro source routie are icluded i the itermediate code routie, commets i a iclude file are ot, uless otherwise specified by the #show commad. Whe you compile a macro source routie that refereces a iclude file, the macro preprocessor replaces the #iclude commad with the text of the iclude file. If the iclude file icludes macro defiitios, the macro preprocessor expads those defiitios as it ecouters them. You may also have a #iclude commad withi a iclude file. This causes ested iclusio. #show, ad #oshow The #show commad istructs the macro preprocessor to preserve all subsequet commets i a iclude file i the itermediate code routie. The #oshow commad restores the default coditio of ot preservig commets i a iclude file i the itermediate code routie. The macro preprocessor always preserves commets i the macro source code i the itermediate code. Advatages of Usig Iclude Files Iclude files are useful for stadardizig the behavior of a set of programs ad for customizig a sigle source file for differet eviromets. More specifically, some of the advatages to usig iclude files are: Processig a sigle macro source with differet iclude files is a way to customize a applicatio for differet eviromets. Usig macro ames defied i a commoly shared iclude file to stad for costat values ($$$MAXSIZE istead of 511, or $$$REPEATSW(10,251) istead of $p(^mdd(1,10,2,251,3),$c(1),6)) reduces the likelihood of errors i which two cooperatig programs fail to use the same value, or look i differet places for a item of data. It also does ot suffer the performace pealty of usig a variable i place of the costat. If several programs eed to execute the same block of M code, without the added overhead of calls to a cetralized routie, you ca put that code i a iclude file ad have each macro source routie referece that iclude file. Doig so esures that each program will execute exactly the same code Ope M/SQL Developer Guide

110 Summary of Macro Preprocessor Commads For example, suppose you wat to customize a sigle set of macro source routies for eviromets A, B, ad C by havig them all share the iclude file FILEA.INC, FILEB.INC, or FILEC.INC. You begi each macro source routie with the lie: #iclude FILECHOICE The iclude file FILECHOICE.INC cosists of the sigle lie: #iclude FILENAME where FILENAME is FILEA, FILEB, or FILEC. Each of the iclude files FILEA.INC, FILEB.INC, ad FILEC.INC cotais a set of #defie commads used to customize the eviromet for A, B, or C. To tailor all routies for a particular eviromet, you may edit the FILENAME value i FILECHOICE.INC ad recompile all the macro source routies. Idicatig Commet Lies You may use the #; preprocessor commad to provide a sigle-lie of commet text withi a macro source routie. The commet lie appears i the macro source code but is suppressed by the macro preprocessor from the itermediate code. For example: #; This is a old versio The poud sig (#) ad the semicolo (;) may be separated by ay umber of spaces. Whe you use this preprocessor commad, your commet text must ot exceed oe lie. Ope M/SQL Developer Guide 5-15

111 Chapter 5 Developig Macro Source Routies Summary of Macro Preprocessor Fuctios The followig table lists ad briefly describes the fuctios supported by the macro preprocessor: Table 5-3: Macro Preprocessor Fuctios Preprocessor Fuctio ##sql &sql ##vedor What It Does Delimits embedded SQL code. Either symbol is acceptable. IterSystems-specific preprocessor fuctio used to make macro source routies portable amog Ope M/SQL-supported host M systems (ISM, DSM, DTM, ad Microetics MSM). &sql(...) To embed a SQL statemet withi a M macro source routie, you must use the Ope M/SQL preprocessor sytax &sql(...) or ##sql(...). Either sytax is acceptable. The embedded SQL statemet begis after the prefix &sql( ad cocludes with the matchig right parethesis. Embedded SQL ca stretch across multiple lies or ca occupy just a portio of a sigle lie. However, you may ot split SQL keywords or tokes across lies. The followig is a example of a sigle-lie embedded SQL statemet where SQL code is itermixed with M code o the same lie: for i=1:1 &sql(fetch c ito :x,:y) quit:sqlcode=10020 do output The followig is a example of a multi-lie embedded SQL statemet: &sql(declare xcurs CURSOR FOR SELECT Name,Age FROM Patiets WHERE Age <12 AND Ward= 4D ) SQL statemets, like the rest of the macro source code, ca cotai $$$MACRO refereces. The macro preprocessor expads ad replaces macro refereces iside embedded SQL statemets before evaluatig the SQL statemets themselves. The macro preprocessor reports a error if it reaches the ed of the macro source routie without ecouterig the right parethesis to match &sql(. For a descriptio of how M routies ca use embedded SQL to access a Ope M/SQL database, see Chapter 8, Embedded SQL Ope M/SQL Developer Guide

112 Summary of Macro Preprocessor Fuctios ##vedor ##vedor is a IterSystems-specific preprocessor fuctio used to make Ope M/SQL routies portable amog the host M systems supported by Ope M/SQL. The Ope M/SQL-supported host M systems iclude: ISM DTM DSM Microetics MSM You ca observe the use of the ##vedor(...) sytax throughout the Ope M/SQL system-geerated code. For example, you ca see it i default-geerated Iteralto-Exteral ad Exteral-to-Iteral Coversio Code, Validatio Code, field legth code, ad help message code. At the macro source level, you may use ##vedor to delimit vedor-specific M costructs, thus producig vedor-idepedet code. This allows the macro preprocessor to compile the routie ito itermediate code for the specified target M system. IterSystems reserves ##vedor for its ow use. Ope M/SQL Developer Guide 5-17

113 Chapter 5 Developig Macro Source Routies 5-18 Ope M/SQL Developer Guide

114 CHAPTER Routie Hadlig ad Maiteace 6 This chapter presets a overview of the Ope M/SQL routie eviromet ad discusses topics related to routie hadlig ad maiteace, icludig iformatio o referecig routies by ame, extesio, ad versio as well as istructios for copyig, compilig, ad backig up routies. Specifically, it covers the followig topics: Routie Eviromet Routie Names, Extesios, ad Versio Numbers Usig Wildcard Sytax to Specify Routies Referecig Routies i Other Directories Routie Sets Compilig Routies Backig Up Routies Deletig Routies Routie Copyig ad Compilig Sychroizatio Ope M/SQL Developer Guide 6-1

115 Chapter 6 Routie Hadlig ad Maiteace Routie Eviromet I Ope M/SQL, you ca create routies at two levels: Macro source Itermediate code Writig Routies The macro source level permits the use of macros ad embedded SQL statemets usig a combiatio of ANSI-Stadard M sytax, special macro preprocessor commads, ad ANSI-Stadard SQL. Macro source routies ca refer to iclude files, which are useful for stadardizig the behavior of a set of programs ad for customizig a sigle source for differet eviromets. You ca also write pure M routies (routies that do ot iclude embedded SQL or ay macro preprocessor statemets) at the macro source level. Whe macro source code is compiled, it is first coverted ito M code with embedded SQL, called itermediate code. This level of compilatio is called the preprocessor phase. Itermediate code routies are subsequetly compiled ito executable object code. IterSystems recommeds that you create all routies (eve pure M routies) at the top level the macro source level. I order to create a macro source code routie, you must use the Full Scree Editor. Where macro source code exists, you should always compile from the macro source level. Whe macro source code is compiled, it produces both itermediate code ad object code. Whe a macro source routie cotais embedded SQL or refers to a iclude file, or both, itermediate ad object code must always be regeerated from the macro level. The macro source level allows you to save backup copies of routies. For more iformatio o writig routies at the macro source level, refer to Chapter 5, Developig Macro Source Routies. You may also create routies directly at the itermediate code level. For iformatio o developig ad editig itermediate code routies o a ISM system, refer to the Ope M/SQL M Programmig Guide. Covertig Itermediate Code to Macro Source Code Ope M/SQL allows a mixed eviromet i which some routies have macro source versios ad others have oly itermediate code versios. You ca copy itermediate code routies to the macro source level usig the %urcopy utility, provided the itermediate code routies do ot iclude embedded SQL. This is a particularly useful feature if you are covertig pure M applicatios to applicatios that make use of macros, SQL, ad other relatioal database features. 6-2 Ope M/SQL Developer Guide

116 Routie Names, Extesios, ad Versio Numbers Routie Names, Extesios, ad Versio Numbers Whe usig the Full Scree Editor or ay of the routie maagemet utilities provided by IterSystems, you may refer to routies ad iclude files ot oly by ame but also by extesio ad versio umber. The complete sytax for routie idetificatio is: NAME.EXTENSION.VERSION For example: ROU.MAC.1 ROU.MAC.2 ABC.INC.1 Sometimes you may use the remote directory sytax to specify a routie that resides i a directory other tha the curret directory, for example: [ DIR ]ROU.MAC.2 Routie Names Must Be Uique Case Sesitivity Routie Extesios A routie may have the same ame as a iclude file, but o two routies i a sigle directory may have the same ame, ad o two iclude files may have the same ame. Routie ad iclude file ames are case sesitive; thus, ABC.INT is ot the same as abc.int. Routie extesios are ot case sesitive; thus, ABC.INT is the same as ABC.it. The followig table lists the routie extesios: Extesio.MAC.INT.INC.OBJ Meaig For macro source routies For itermediate code routies For iclude files For object code routies Ope M/SQL Developer Guide 6-3

117 Chapter 6 Routie Hadlig ad Maiteace For example, the routie ROU might have the followig ames: Specificatio ROU.MAC ROU.INT ROU.OBJ Meaig Macro source level for ROU Itermediate level for ROU The object code level for ROU You ca also create/edit iclude files usig the Full Scree Editor as well as maipulate them usig the routie maagemet utilities. To idetify a iclude files, you must specify the extesio.inc, as i: ABC.INC which specifies the iclude file ABC. Whe No Extesio Is Specified If you do ot specify a file extesio for a routie, Ope M/SQL assigs the.mac suffix by default. If o.mac routie exists, Ope M/SQL assigs the.int suffix. This allows M programmers who do ot make use of the macro source level but rather write routies that cosist oly of pure M code to use the routie maagemet utilities without adaptig their routies or programmig methods. I a mixed programmig eviromet where some routies have a macro source level ad others do ot, programmers ca still use the routie utilities without specifyig extesios. I this case, whe routies have a macro source level, processig takes place at that level. Whe oly itermediate code exists, processig begis at the itermediate level. 6-4 Ope M/SQL Developer Guide

118 Routie Names, Extesios, ad Versio Numbers Versio Numbers Macro source routies ad iclude files ca have up to 9 backup versios. Itermediate ad object code routies caot have backup versios. Therefore, you ever eed to specify versio umbers for.int or.obj routies; their versio umber is always 1 implicitly. The table below shows how you refer to multiple versios of a macro source routie called ROU : Specificatio ROU.MAC.1 ROU.MAC.2 ROU.MAC.3 Meaig Curret versio 1st backup 2d backup etc., up to a maximum of ROU.MAC.9. The table below shows how you refer to multiple versios of a iclude file called ABC : Specificatio ABC.INC.1 ABC.INC.2 ABC.INC.3 Meaig Curret versio 1st backup 2d backup etc., up to a maximum of.inc.9. You must explicitly specify the versio umber oly whe referrig to versios other tha the curret versio (versio 1). Thus, the followig specificatios are equivalet: ad.mac =.MAC.1.INC =.INC.1 Ope M/SQL Developer Guide 6-5

119 Chapter 6 Routie Hadlig ad Maiteace Usig Wildcard Symbols to Specify Routies IterSystems provides a series of wildcard symbols to assist you i specifyig sets of routies to be acted o by the routie maagemet utilities. You may use these wildcard symbols whe specifyig routies at the Routie(s): prompt. Wildcards for Routie Names Whe specifyig routie ames, you may use ay of the special character ( wildcard ) symbols described i the table below: Table 6-1: Wildcard Symbols for Use Whe Specifyig Routie Names Wildcard Symbol Meaig * Sigifies zero or more characters. For example: * meas all ames AB*D meas all ames that start with AB ad ed with D? Sigifies oe ad oly oe wildcard character. For example: A?C meas all ames that start with A, ed with C, ad have exactly oe character i betwee. : Sigifies a rage. For example: AB:D meas all ames from AB through D iclusive. Sigifies exclusio from a previously specified list. For example: A* ABC meas all ames that start with A except for ABC. Similarly, A* AB:AD AF* meas all ames that start with A except for those i the rage AB through AD iclusively ad those that start with AF. = I utilities that use the two-colum format (e.g., %urcopy, where routies i the first colum are copied to those i the secod), the equals sig (=) ca be used to sigify the same routie ame as specified i the From colum. If o directory is specified, Ope M/SQL assumes the curret directory. If o extesio is specified, Ope M/SQL assumes.mac. =.EXT The equals sig followed by a extesio (=.EXT) ca be used to sigify the same routie ame as specified before with the specified extesio. =:. The equals sig followed by a colo ad period (=:.) ca be used to sigify the same routie ad extesio as i the From colum. Note Type a questio mark (?) at the Routie(s) prompt to view help text with iformatio about the wildcard symbols. Type?L to see a list of the routies you have chose so far. 6-6 Ope M/SQL Developer Guide

120 Usig Wildcard Symbols to Specify Routies Wildcards for Extesios You may also use the asterisk symbol (*) i the file extesio idetifier. I this case, it meas all extesios for the specified routie ame(s). For example: ROU.* expads to: ROU.MAC, ROU.INT, ROU.INC, ad ROU.OBJ More specifically, it expads to: ROU.MAC.1, ROU.INT, ROU.INC.1, ad ROU.OBJ Wildcards for Versio Numbers It is ecessary to specify a versio umber oly whe the versio you are referecig is ot the curret versio (versio 1). Whe o versio umber is specified, the versio is implicitly.1. You may use the asterisk symbol (*) i the versio idetifier. I this case, it meas all versios for the specified routie(s). The table below shows several examples of the use of the asterisk symbol i the versio idetifier: Specificatio ROU.MAC.* ROU.OBJ.* ROU.INC.* ROU.*.* Meaig Meas ROU.MAC.1, ROU.MAC.2, etc. Meas ROU.OBJ.1 (there are o backups) Meas ROU.INC.1, ROU.INC.2, etc. Meas all versios of all extesios of routie ROU *.*.* Meas all versios of all extesios of all routies Ope M/SQL Developer Guide 6-7

121 Chapter 6 Routie Hadlig ad Maiteace Referecig Routies i Other Directories Ope M/SQL s routie maagemet utilities allow you to referece routies located i directories other tha the curret directory, icludig directories o other computers, where applicable. To specify routies located i a directory other tha your curret directory, you may use remote directory sytax at the Routie(s): prompt, as show below: [directory,directory_set_ame]routie.extesio.versio where directory is the ame of the target directory ad directory_set_ame is the ame give to the target computer i your M/NET etworkig cofiguratio. If your target directory is the curret directory, you do ot eed to specify remote directory sytax at all. If your target directory is aother directory o the same computer, you may igore the directory_set_ame parameter. Note If you are ruig Ope M/SQL o a o-ism host M system, the remote directory sytax may be differet. Cosult your system guide for this iformatio. For example: Routie(s): [ DIR, SYS ]ROU.MAC Routie(s): [ DIR2 ]ABC.INT This example selects the.mac versio of routie ROU i directory DIR, directory set SYS ad the.int versio of routie ABC i directory DIR2 o the curret computer. To avoid repeatedly retypig remote directory iformatio where a list of routies is required, you may use the followig sytax to referece the last explicitly specified directory: [^] The followig example selects routies AAA, BBB, ad CCC i directory DIR$SYSX : Routie(s): [ DIR$SYSX ]AAA Routie(s): [^]BBB Routie(s): [^]CCC For routie maagemet utilities that use two-colum format (e.g., %urcopy, where routies from colum oe are copied to those i colum two), the [^] sytax is colum-specific. I the followig example, routie AAA i DIR1 of system SYS is copied to routie BBB i the curret directory, the routie 6-8 Ope M/SQL Developer Guide

122 Referecig Routies i Other Directories XXX also i directory DIR of system SYS is copied to YYY i the curret directory: Copy Routie(s): [ DIR1, SYS ]AAA Copy Routie(s): [^]XXX To: BBB To: YYY Restrictios o Usig Remote Directory Sytax Use of remote directory sytax has the followig restrictios: 1. The routie maagemet utilities do ot permit you to alter the cotets of a directory other tha the curret directory. 2. The utilities %urchage, %urcomp, ad %urdel do ot support remote directory sytax. 3. The %urcopy utility lets you copy routies from a remote directory ito the curret directory, but you caot copy routies from the curret directory ito a remote directory. Ope M/SQL Developer Guide 6-9

123 Chapter 6 Routie Hadlig ad Maiteace Routie Sets The Ope M/SQL Routie Set facility allows you to create a list of routies uder oe ame ad referece that routie set ame at the Routie(s): prompt for ay of the routie maagemet utilities. This feature is useful whe you have a group of routies o which you commoly perform a particular fuctio, such as compilig all the routies i a particular applicatio. Creatig a Routie Set You may create a routie set at the Routie(s): prompt of ay of the routie maagemet utilities. Procedure To create a routie set: 1. At the Routie(s) prompt for ay of the routie maagemet utilities, specify all the routies you wat to iclude i the routie set, either by amig them explicitly or by usig the wildcard sytax. 2. Whe you have amed all the routies you wat to iclude, type.f at the ext appearace of the Routie(s): prompt, ad press <RETURN>. The system prompts you to provide a ame ad descriptio for the routie set, as show below: Usig a Routie Set >d ^%urdir Routie(s): test*.mac Routie(s):.F File as Routie Set: TESTSET With Descriptio: Routies for testig OK to File? Yes= <RETURN> Filig... doe Routie set ames are case sesitive, so ROUTINESET is ot the same as routieset. To use a pre-defied routie set, type the routie set ame preceded by character at the Routie(s): prompt, as show i the example below: >d ^%urdir --.MAC-- test1.mac test2.mac test3.mac test4.mac test5.mac 6-10 Ope M/SQL Developer Guide

124 Compilig Routies Compilig Routies You may use the %urcomp utility to compile either the macro source or itermediate code level of a routie. Whe you ivoke %urcomp o a macro source routie, Ope M/SQL compiles the routie i two phases. First, the macro preprocessor phase of the Compiler produces itermediate code, the the mai Compiler produces object code. If you ivoke %urcomp o itermediate code routies, the mai Compiler directly produces object code. Some itermediate code routies caot be compiled. Whe the Compiler caot compile a routie, it issues a abort compilatio message ad does ot modify the routie. The followig two coditios ca cause this to happe: 1. Source lies are missig from the itermediate code level of ^ROUTINE. 2. The itermediate code cotais embedded SQL. I either case, you must compile the routie at the macro source level. Most M-level ad SQL-level sytax errors do ot cause the compilig process to abort. Other ways to compile a routie iclude: 1. You may compile a routie as a result of executig the utilities %urchage ad %urcopy. These utilities prompt you to specify whether or ot you wat to compile the specified routies. 2. You may elect to compile a routie from withi the Full Scree Editor. Ope M/SQL Developer Guide 6-11

125 Chapter 6 Routie Hadlig ad Maiteace Backig Up Routies The Full Scree Editor ad the utilities %urchage, %urcomp, ad %urcopy all provide the optio of producig backup versios of macro source routies ad iclude files. You ca use the %urverma utility o a per-directory basis to set the maximum umber of versios to be maitaied for macro source routies ad iclude files. The default umber of versios is four (oe curret versio ad three backups). The maximum umber of versios that Ope M/SQL ca maitai is ie (oe curret versio ad eight backups). Ope M/SQL maitais backups for macro source routies ad iclude files oly. It does ot maitai backups for itermediate code or object code routies; their versio umbers are always.1. How Backups are Shuffled ad Reumbered Wheever Ope M/SQL geerates a backup versio of a macro source routie or iclude file, it shuffles the existig backups dow. Whe the umber of backups exceeds the maximum umber of versios to be maitaied, which you may set usig the %urverma utility, Ope M/SQL deletes the last backup o the list. For example, suppose the followig backup versios of the macro source routie ABC are maitaied: Routie Name ABC.MAC.2 ABC.MAC.3 ABC.MAC.4 Versio First backup Secod backup Third backup Whe you modify the curret versio of the routie ad the save it, Ope M/SQL geerates a ew backup, ad the other backups shuffle dow, as show below: Origial Name ABC.MAC ABC.MAC.2 ABC.MAC.3 ABC.MAC.4 New Name ABC.MAC.2 ABC.MAC.3 ABC.MAC.4 Deleted You ca use the utilities %urpurge ad %urdel to delete old backup copies of macro source routies ad iclude files Ope M/SQL Developer Guide

126 Backig Up Routies The Full Scree Editor Geerates Backups Whe You Save Whe editig a macro source routie or iclude file i the Full Scree Editor, the Editor automatically geerates a backup copy of the routie or file ad shuffles dow its existig backups (i accordace with the per-directory backup maximum) wheever you elect to save ad compile your edits. For example, whe you save ad compile the macro source routie ABC.MAC after editig it i the Full Scree Editor, the previous curret versio becomes ABC.MAC.2, ad the versio you are editig becomes the curret versio ( ABC.MAC ). Ay older versios of the routie ( ABC.MAC.3 through ABC.MAC.9 ) are shuffled dow ad/or out. If you have specified that a maximum of 2 backup versios is to be maitaied, the previous ABC.MAC.1 versio is reamed to ABC.MAC.2, ad the previous ABC.MAC.2 versio is deleted. Restorig a Backup Versio to the Curret Versio To restore a backup versio of a macro source routie or iclude file to the curret versio, you may use the %urcopy utility. To do this, you copy from the backup versio you wat to restore to the ew versio. For example, copyig from ROU.MAC.2 to ROU.MAC.1 effectively restores the first backup, makig ROU.MAC.1 ad ROU.MAC.2 idetical. Whe you use %urcopy to copy oe versio of a routie to aother versio of the same routie ad extesio, the backups do ot shuffle dow. Ope M/SQL Developer Guide 6-13

127 Chapter 6 Routie Hadlig ad Maiteace Deletig Routies %urdel %urpurge To delete routies ad iclude files, you may use either of the two utilities described below. You may use the %urdel utility to delete routies ad iclude files. To use this utility, you must specify a list of the routies ad iclude files with extesios ad versio umbers that you wat to delete. For example, if you wat to delete all the versios of the macro source routie ad iclude file ABC, you specify: Routie(s): ABC.*.* As aother example, you may specify the followig: Routie(s): DEF.MAC.* Routie(s): GHI.MAC.2 to delete all.mac versios of routie DEF ad macro versio 2 (the first backup) of routie GHI. Deletig macro versio 2 of routie GHI causes subsequet macro backups of GHI to be shuffled forward, hece the old GHI.MAC.3 becomes GHI.MAC.2. To delete all macro source ad itermediate code routies i the curret directory, leavig oly object code, type: Routie(s): *.MAC.* Routie(s): *.INT To delete all levels of all routies ad iclude files i the curret directory, type: Routie(s): *.*.* You may use the %urpurge utility to delete some or all backups for macro source routies ad iclude files. This utility prompts you to specify a set of routies ad iclude files that you wat to purge. You may oly specify routies with.mac extesios or iclude files with.inc extesios i the list of routies ad iclude files to purge. The utility also prompts you to specify how may versios of the routie or iclude file to keep after the purge. The default value is 1, meaig the curret versio oly ad o backups Ope M/SQL Developer Guide

128 Routie Copyig ad Compilig Sychroizatio Routie Copyig ad Compilig Sychroizatio It is the programmer s resposibility to keep the.mac,.int, ad.obj levels of a routie i syc, or out of syc if desired. You keep the differet levels of a routie i syc by compilig the routie. Copyig or editig a routie at either the.mac or.int level does ot automatically result i compilig that routie, although the utilities for copyig ad editig do give you the optio of compilig. Thus, the resposibility for determiig whe a routie should be compiled is yours; Ope M/SQL does ot do it automatically ad does ot attempt to keep compiled routies i syc with source code. Sometimes you may wat to keep the differet levels of a routie out of syc. For example, you may wat to edit oe or more macro source routies for several days ad ot disturb the.int ad.obj levels util all editig is complete. Although Ope M/SQL does permit copyig of.mac file extesios to.int as well as copyig of.int file extesios to.mac, IterSystems does ot recommed this..int files do ot always cotai all of the iformatio ecessary to produce correspodig.mac files source lies may be missig or embedded SQL code may exist (for which there is o source code). If a.mac routie icludes preprocessor statemets (such as #if statemets or macros) or embedded SQL, you should ot copy it to the.int level because it caot be compiled there. Ope M/SQL Developer Guide 6-15

129 Chapter 6 Routie Hadlig ad Maiteace 6-16 Ope M/SQL Developer Guide

130 CHAPTER Ope M/SQL Routie Maagemet Utilities 7 IterSystems provides a set of utilities for examiig ad maipulatig routies ad iclude files. These utilities are collectively kow as the Ope M/SQL routie maagemet utilities. This chapter summarizes the routie maagemet utilities, shows how to access them, ad the provides a detailed descriptio with examples of how to use each utility. Specifically, it covers the followig topics: Summary of Routie Maagemet Utilities Accessig the Routie Maagemet Utilities %uro %uri %url %urprit %urload %urdir %urchage %urcomp %urcopy %urfid %urfad %urdel %urverma %urpurge %urset Ope M/SQL Developer Guide 7-1

131 Chapter 7 Ope M/SQL Routie Maagemet Utilities Summary of Routie Maagemet Utilities The followig table lists ad describes the routie maagemet utilities provided by Ope M/SQL: Table 7-1: Ope M/SQL Routie Maagemet Utilities Utility Meaig Descriptio %urprit Routie Output Prits selected macro source routie(s) ad iclude file(s) from the curret directory to a storage file or to a specified output device. %urload Routie Iput Loads macro source routies ad iclude files that have bee output to a file by the %urprit utility. %urdir Routie Directory Lists routies i the curret directory. %urchage Routie Chage Chages all occurreces of specified strig(s) i selected routie(s). %urcomp Routie Compile Compiles macro source code ito itermediate code, ad itermediate code ito object code for a specified set of routies. %urcopy Routie Copy Copies macro source routies, itermediate code routies, ad iclude files from ay directory ito the curret directory. %urfid Routie Search Searches through routies for occurreces of oe of a specified set of strigs. %urfad Routie Search Searches through routies for occurreces of all of a specified set of strigs. %urdel Routie Delete Deletes routies ad iclude files from the curret directory. %urverma %urpurge %urset Set Maximum Number of Backups Routie Backup Purge Select a Set of Routies Specifies the maximum umber of backup versios maitaied i the curret directory for macro source routies ad iclude files. Deletes backup versios of macro source routies ad iclude files. Creates a set of routies to be used by other utilities for other operatios. 7-2 Ope M/SQL Developer Guide

132 Accessig the Routie Maagemet Utilities Accessig the Routie Maagemet Utilities There are two ways to access the Ope M/SQL routie maagemet utilities: 1. You may call them directly from the M programmer prompt. 2. You may access them as meu optios from withi Ope M/SQL. Callig the Routie Utilities Directly from M To call the routie maagemet utilities directly from the M programmer prompt, you issue the followig commad sytax: do ^%utility_ame For example, to call the %urcopy utility from the M programmer prompt, you issue the followig: >do ^%urcopy You may use the same sytax to call the routie utilities from withi M programs. Accessig the Routie Utilities from withi Ope M/SQL Alteratively, you may access the Ope M/SQL routie maagemet utilities by selectig them as optios from the Macro Routie Utilities meu, which is a submeu of the Developer Utilities meu. All the routie maagemet utilities listed i the table o the previous page are available as optios o this meu, except the followig: %urprit %urload %urset Procedure To access the routie maagemet utilities via Ope M/SQL: 1. At the M programmer prompt, type the followig commad to eter Ope M/SQL: > do ^%msql You see the Termial Type prompt, as show below: Termial Type: VT220 => 2. At the Termial Type prompt, eter the ame of the termial type you are curretly usig. You may press <RETURN> to accept the system-wide default termial type. Ope M/SQL Developer Guide 7-3

133 Chapter 7 Ope M/SQL Routie Maagemet Utilities You see the Ope M/SQL User Idetificatio widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³³ Ope M/SQL User Idetificatio ³³ ³ÃÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ÃÙ À ³ ³³ WELCOME TO OPEN M/SQL ³³ ³³ ³³ ³³ Versio F ³³ ³³ Maiteace Release F.7 ³³ ³Ã Ú ³ ³ÀÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÙ³ ³ÚÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ÃÙ À ³ ³³ User Name Password ³³ ³³ ³³ ³³ ³³ ³³ Laguage ³³ ³³ ³³ ³Ã Ú ³ ³ÀÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÙ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ User Logi Eter a valid Ope M/SQL userame. Press <Help> For Help 3. At the UserName field o the Ope M/SQL User Idetificatio widow, eter your Ope M/SQL UserName, ad press <RETURN>. 4. At the Password field o the Ope M/SQL User Idetificatio widow, eter the Password for your Ope M/SQL UserName, ad press <RETURN>. 5. At the Laguage field o the Ope M/SQL User Idetificatio widow, eter the laguage i which you wat to ru Ope M/SQL. To accept the system-wide default ru-time laguage, press <RETURN>. To choose a differet ru-time laguage, press <CTRL-L> to delete the system-wide default laguage. You may press the <LIST CHOICES> key to see a lookup box that lists the rutime laguages supported by Ope M/SQL. 7-4 Ope M/SQL Developer Guide

134 Accessig the Routie Maagemet Utilities You see the Ope M/SQL Mai Meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄOpe M/SQL MeuÄÄÄ ³ ³ ³ Data Dictioary ³ ³ Forms ³ ³ Reports ³ ³ Queries ³ ³ Meu Geerator ³ ³ System Maagemet ³ ³ Privileges ³ ³ Developer Utilities ³ ³ User Utilities ³ ³ Server Maagemet ³ ³ Relatioal Gateway ³ ³ Help Optios ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Jul 05, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio Ope M/SQL Meu 03:50PM Press <Help> For Help 6. From the Ope M/SQL Mai Meu, select the Developer Utilities optio. Note: You may type v to select this optio it is a memoic accelerator. You see the Developer Utilities meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄÄM/SQL Developer UtilitiesÄÄÄÄ ³ ³ ³ Export/Import Optios ³ ³ Object Compile Driver ³ ³ M/SQL Object Itegrity Checkig ³ ³ Object Strig Search Utility ³ ³ Full Scree Editor ³ ³ Macro Routie Utilities ³ ³ Query Object By Routie Prefix ³ ³ Natioal Laguage Reports ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Jul 05, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio M/SQL Developer Utilities 03:50PM Press <Help> For Help 7. From the Developer Utilities meu, select the Macro Routie Utilities optio. Note: You may type r to select this optio it is a memoic accelerator. Ope M/SQL Developer Guide 7-5

135 Chapter 7 Ope M/SQL Routie Maagemet Utilities You see the M/SQL Routie Utilities meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄÄÄÄÄÄM/SQL Routie UtilitiesÄÄÄÄÄÄÄÄ ³ ³ ³ Routie Output (%uro) ³ ³ Routie Iput (%uri) ³ ³ Routie Lister (%url) ³ ³ Routie Directory (%urdir) ³ ³ Routie Chage (%urchage) ³ ³ Routie Compile (%urcomp) ³ ³ Routie Copy (%urcopy) ³ ³ Routie Search (%urfid) ³ ³ Routie Search All (%urfad) ³ ³ Routie Delete (%urdel) ³ ³ Set Maximum No. of Backups (%urverma) ³ ³ Routie Backup Purge (%urpurge) ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Jul 05, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio M/SQL Routie Utilities 03:50PM Press <Help> For Help 8. From the M/SQL Routie Utilities meu, you may select ay optio to ivoke the correspodig utility. Whe you exit the utility, you retur to the M/SQL Routie Utilities meu. 7-6 Ope M/SQL Developer Guide

136 %urprit %urprit The %urprit utility lets you prit selected macro source routie(s) ad iclude file(s) ad sed the output to a storage file or to a specified output device. Whe called, %urprit displays the followig prompt: Routie Output Routie(s): Here you specify the routie(s) you wat to output. You may eter a sigle routie ame or a set of routie ames with or without extesios. The oly valid extesios are.mac ad.inc, which you may specify either i upper or lower case. If you do ot specify a extesio, %urprit assumes a extesio of.mac. Note %urprit does ot accept itermediate code or object code routies. Next, %urprit prompts you to eter a descriptio of the output file. Here you may eter some text that describes the file. Alteratively, you may type the carat character (^) at the Descriptio: prompt to add a auto-load header as the first record i the file. A auto-load header is a lie of executable M code that, whe executed withi a Ope M/SQL system, causes the cotets of the file to be restored automatically. A typical M statemet to execute the auto-load header is show below: OPEN <device>:() USE <device> READ <code> XECUTE <code> CLOSE <device> Selectig a Output Device After you specify the routies you wat to output, %urprit presets a vedor-specific prompt that asks you to specify a output device. You may sed output to ay valid device supported by your host M system. Pritig to the Scree If you specify your curret device as the output device, output automatically appears i paged format. At the bottom of each page, the message More appears to idicate that the report cotiues. You may cotiue the output by pressig <RETURN>, or you may abort the output by typig Q or q or ^. Ope M/SQL Developer Guide 7-7

137 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example Pritig to a Priter If you specify a output device other tha your curret device, you see the followig prompt: Priter Format? If you are directig the output to a priter, you should aswer Yes at this prompt. Aswerig Yes causes the output to appear oe page at a time i a format appropriate for a priter. Pritig to a Storage File If you specify a output device other tha your curret device, you see the followig prompt: Priter Format? If you are directig the output to a storage file i a directory or o tape so that it may be restored later usig the %urload utility, you should aswer No at this prompt. Aswerig No causes the output to appear i a format useful for backig up the routie, icludig the appedig of a self-loadig header record to the begiig of the output file. I the example below, %urprit outputs the files ABC.INC ad ABC.MAC to a storage file called /usr/msql/abc.rt : > do ^%urprit Routie Iput Routie(s): ABC.* Descriptio: ^ (autoload header added) Output routies to Device: /usr/msql/abc.rt Parameters: "WNS"=> <RETURN> Priter Format? No => <RETURN> ABC.INC ABC.MAC > You ca ow restore these files usig the %urload utility. 7-8 Ope M/SQL Developer Guide

138 %urload %urload The %urload utility lets you load macro source routies ad iclude files that have bee output to a storage file i a directory or o tape via the %urprit utility. %urload prompts you to specify a iput device, routies to load, ad whether or ot to compile loaded macro source routies. Whe called, %urload displays the followig prompt: Eter iput device: Device: Here you must specify the ame of a storage device to which routies ad iclude files were output by %urprit. Routie Iput Optios After you specify the iput device, %urload displays the followig prompt: Routie Iput Optio: (A)ll ==> This prompt asks you to specify which routies from the iput device to load. Type? to see a list of the load optios. The table below lists ad describes the load optios: Table 7-2: Load Optios for Routie Iput Usig %urload Optio (A)ll (S)elect (E)ter Meaig Loads all files o the iput device, the prompts you to specify whether or ot you wat to compile the macro source routies, as follows: Compile macro source routies? No=> All is the default optio. Prompts you to specify whether or ot you wat to compile the macro source routies, as follows: Compile macro source routies? No=> The, prompts you file-by-file to specify whether or ot to load each file o the iput device, as follows: OK to load? No ==> Lets you maually specify the list of files to be loaded. Whe you select this optio, you see the followig prompt: Routie(s) To Load: Ope M/SQL Developer Guide 7-9

139 Chapter 7 Ope M/SQL Routie Maagemet Utilities Table 7-2: Load Optios for Routie Iput Usig %urload (Cotiued) Optio (L)ist (Q)uit Meaig Lists all files o the iput device, the redisplays the Routie Iput Optio: prompt. Quits %urload. To select a optio, type its first letter, ad press <RETURN>. Compile Macro Source Routies Example Whe you select oe of the load optios All, Select, or Eter, %urload displays the followig prompt: Compile macro source routies? No ==> to determie whether or ot you wat Ope M/SQL to compile all macro source routies as they are loaded. No is the default respose. I the example below, %urload loads all files from the storage file abc.rt ito the curret directory ad compiles them: >do ^%urload Eter iput device: Device: abc.rt Parameters: "R"=> <RETURN> Routie Iput Optio: (A)ll ==> <RETURN> Compile macro source routies? No ==> Yes ABC.INC (loaded) compilig... ABC.MAC (loaded) compilig... > %urload displays a list of all macro source routies ad iclude files from the iput device to the scree. It orgaizes the files i alphabetical order. Beside every file that it loads, it displays the message (loaded). Beside every file that it does ot load, it displays the message (skipped). Beside every macro source routie that it compiles, it displays the message compilig Ope M/SQL Developer Guide

140 %urdir %urdir The %urdir utility lists routies i the curret directory. Note O ISM systems the %urdir utility is also kow as %RD. The %urdir utility lets you do all of the followig: List the routies i aother directory. Specify ay set of.mac,.int,.inc, or.obj routies to display usig the wildcard sytax. Select the short or log display form. The short form displays the routie ames, extesios, ad versio umbers. The log form displays, i additio to the short form iformatio, the date ad time whe routies were last saved, the size i bytes of each routie, ad the block(s) that object code routies occupy. Specify the selectio coditio of a rage of dates durig which the routies were last modified. First, you see the followig prompt: Routie(s) Here you specify the routies that you wat to iclude i the output list. %urdir supports remote directory sytax, which lets you select routies from a directory other tha the curret directory. To do this, you must type the ame of the source directory iside brackets ad withi quotatio marks [ ], as show below: Routie(s): [ /us/mgr/tasks ]ABC.MAC After you specify the routie(s) you wat to list, %urdir displays the followig prompt: Log or Short form (L or S)? S=> Here, you select a display format for outputtig the routie list. You may chose betwee Short Form ad Log Form. Short Form lists each routie with its extesio ad versio. Log Form orgaizes the output ito tabular format ad provides additioal iformatio, icludig date ad time last modified, total umber of bytes, ad total umber of blocks. Short Form is the default choice. Ope M/SQL Developer Guide 7-11

141 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example 1 Next, you see the followig prompt: Fid routies last modified sice date: ad o or before date: This is a optioal feature that lets you limit the output list to those routies that were modified withi a specified date rage. Eter a start-of-rage date ad a ed-of-rage date, as follows: 1/31/95 I the example below, %urdir uses the Short Form to display of all versios of all macro source routies begiig with the letter ' Y ' i the curret directory: >do ^%urdir Routie(s): Y*.MAC Routie(s): <RETURN> Log or Short form (L or S)? S=> <RETURN> Fid routies last modified sice date: <RETURN> ad o or before date: <RETURN> Display o Device: <RETURN> Right margi: 80=> <RETURN> Short Listig of Selected Routie/Iclude Files Directory: /usr/msql 10 Jul 95 01:24PM Page 1 YAAA --.MAC -- YAAA --.MAC.2 -- YAAA --.MAC.3 -- YAAA --.MAC.4 -- YBBB --.MAC -- YCCC --.MAC -- YDDD --.MAC -- > 7-12 Ope M/SQL Developer Guide

142 %urdir Example 2 I the example below, %urdir uses the Short Form to display all versios of all macro source ad itermediate code routies that reside i the curret directory, begi with the letter Y, ad were modified betwee Jauary 21, 1995 ad the curret date: >do ^%urdir Routie(s): Y*.MAC Routie(s): Y*.INT Routie(s): <RETURN> Log or Short form (L or S)? S=> <RETURN> Fid routies last modified sice date: 1/21/95 ad o or before date: t Display o Device: <RETURN> Right margi: 80=> <RETURN> Short Listig of Selected Routie/Iclude Files Modified Betwee 1 July 95 ad 10 July 95 Directory: /usr/msql 10 Jul 95 01:24PM Page 1 YAAA --.MAC -- YAAA --.MAC.2 -- YAAA --.MAC.3 -- YBBB --.MAC -- YDDD --.MAC -- YAAA --.INT -- YCCC --.INT -- > Whe the Short Form display exteds across multiple screes, %urdir pauses o each scree ad displays the message --more-- at the bottom of the scree. You may press <RETURN> to move ahead to the ext scree. Ope M/SQL Developer Guide 7-13

143 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example 3 I the example below, %urdir uses the Log Form to display of all versios of the macro source, itermediate code, ad object code routies ad iclude files called abc located i the curret directory: >do ^%urdir Routie(s): abc.* Routie(s): <RETURN> Log or Short form (L or S)? S=> L Fid routies last modified sice date: <RETURN> ad o or before date: <RETURN> Display o Device: <RETURN> Right Margi: 80=> <RETURN> Log Listig of Selected Routies/iclude Files Directory /user/documetatio 10 Jul 95 01:25PM Page 1 NAME.EXT.VER DATE/TIME #BYTES BLOCKS abc.mac.1 10 Apr 91 10:35AM 1234 abc.mac.2 15 May 91 02:30PM 1255 abc.mac.3 25 Ju 91 08:45AM 1196 abc.int 25 Ju 91 08:48AM 1268 abc.obj 25 Ju 91 09:00AM Total for Directory: /user/documetatio --.MAC INT OBJ > Whe the Log Form display exteds across multiple screes, %urdir pauses o each scree ad displays the message --more-- at the bottom of the scree. You may press <RETURN> to move ahead to the ext scree Ope M/SQL Developer Guide

144 %urchage %urchage The %urchage utility chages all occurreces of a specified strig or strigs i macro source routies, itermediate code routies, ad iclude files to a ew value. The ew value may be the ull strig. Note O ISM systems the %urchage utility is also kow as %RCHANGE. Whe you ivoke %urchage, the utility prompts you to specify a search strig ad a replace strig. You may specify multiple search strigs with a correspodig replace strig for each. Next, the utility prompts you to specify the routies you wat to chage. Note %urchage does ot support remote directory sytax. This meas that you caot make chages to routies that reside outside your curret directory. I additio to searchig for ad replacig strigs, the %urchage utility ca also perform several auxiliary fuctios o modified routies, icludig: Geerate a backup copy for each chaged routie Recompile each chaged routie Display a cofirmatio prompt for each chage before it is made Aswer Yes at the appropriate prompt to eable ay of these optios. By default, %urchage recompiles all chaged routies but does ot geerate backups or ask you to cofirm each chage. If you aswer Yes to the Verify Each Chage? prompt, %urchage displays a Okay to chage? cofirmatio prompt each time it reaches a lie that cotais a strig to be chaged. %urchage automatically stamps the date ad time whe it modifies itermediate code routies. Ope M/SQL Developer Guide 7-15

145 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example I the example below, %urchage chages every occurrece of the global ^ABD to ^ABC i all routies that begi with the letter Z ad are located i the curret directory. >do ^%urchage This routie chages all occurreces of a strig i routies/iclude files. 1. Chage every: ^ABD to: ^ABC 2. Chage every: Routie(s): Z* Routie(s): <RETURN> Geerate backups? No=> <RETURN> Recompile? Yes=> <RETURN> Verify Each Chage? No=> <RETURN> Display chages o Device: <RETURN> Right Margi: 80=> <RETURN> Chagig "^ABD" to "^ABC" %urchag Ja :42 PM ZRR.INC ZRR+3 ZAA.INT ZAA+3 ZBB.INT ZBB+5 ZBB.MAC ZBB+5 if ^ABC(0)=41250 set id=x1 set ^ABC(0)=100 set ^ABC(0)=41250 set ^ABC(0)=41250 > The utility outputs the routie ame, the text of the chage, ad the lies cotaiig the chaged strig Ope M/SQL Developer Guide

146 %urcomp %urcomp The %urcomp utility compiles macro source ad itermediate code routies. Note O ISM systems the %urcomp utility is also kow as %RCOMPILE. If you ivoke %urcomp at the macro source level, it produces both itermediate ad object code for the routie. Specifically, the macro preprocessor phase of the Compiler produces itermediate code, the the mai Compiler produces the object code. If you ivoke %urcomp at the itermediate source code level, it directly produces object code. Whe macro source routies iclude embedded SQL statemets or make use of iclude files that cotai embedded SQL statemets, %urcomp commets out the SQL code. Thus, the itermediate code produced for a compiled macro source routie that cotais embedded SQL statemets cosists of pure M source code with SQL statemets as commets. You should ever compile routies that cotai embedded SQL from the itermediate code level. If you attempt to do this, the Compiler issues a error message ad aborts the compilatio without modifyig the routie. If a routie cotais embedded SQL statemets, you must compile it at the macro source level. Note %urcomp does ot support remote directory sytax. This meas that you caot compile routies that reside outside your curret directory. Ope M/SQL Developer Guide 7-17

147 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example I the example below, %urcomp compiles the macro source routie EMPLIST. >do ^%urcomp Routie(s): EMPLIST.MAC Routie(s): <RETURN> Display o Device: <RETURN> Right margi: 80=><RETURN> EMPLIST.MAC ****** DECLARE deptcurs CURSOR FOR SELECT Departmet,Name ****** INTO :deptid,:deptame ****** FROM Departmet ***** WHERE (%ALPHAUP (Name) %STARTSWITH :ame) ****** DECLARE empcurs CURSOR FOR SELECT Name,Phoe, HireDate ****** INTO :empame,:empphoe,:empdate ****** FROM Employee WHERE (Departmet=:deptid) ****** SELECT Departmet,Name,COUNT(Departmet) ****** INTO :deptid,:deptame,:deptcout ****** FROM Departmet ****** WHERE %ALPHAUP(Name) %STARTSWITH :ame ****** OPEN deptcurs ****** FETCH deptcurs ****** CLOSE deptcurs ****** OPEN empcurs ****** FETCH empcurs ****** CLOSE empcurs ****** CLOSE deptcurs > For the full text of the macro source routie EMPLIST, see Chapter 8, Embedded SQL Ope M/SQL Developer Guide

148 %urcopy %urcopy The %urcopy utility lets you copy existig routies ad iclude files. Note O ISM systems the %urcopy utility is also kow as %RCOPY. You may use the %urcopy utility to do all of the followig: Copy macro source routies, itermediate code routies, ad iclude files withi the curret directory to other routie ames ad other extesio ames; Copy macro source routies, itermediate code routies, ad iclude files from a foreig directory ito the curret directory; Note: Sice the routie maagemet utilities do ot permit you to alter foreig directories, %urcopy does ot allow you to copy routies from the curret directory ito a foreig directory. Compile macro source ad itermediate code routies i the curret directory; Geerate backup versios of macro source routies ad iclude files; Copy itermediate code routies to the macro source level i order to develop macro source code from routies that were created as pure M routies. This feature is particularly useful for users who are covertig to Ope M/SQL from earlier M versios; Whe you ivoke the %urcopy utility, you see the followig prompt: Copy routie(s): Here you specify the ame of the routie or iclude file you wat to copy. Note %urcopy supports remote directory sytax, which eables you to copy a routie from a directory other tha the curret directory. To do this, type the ame of the source directory iside brackets ad withi quotatio marks [ ], for example: Copy routie(s): [ /us/mgr/tasks ]ABC.MAC If you wish to agai referece the same outside directory, you may simply type the carat character eclosed i brackets [^] at the ext appearace of the Copy Routie(s) prompt. This recalls the ame of the last explicitly refereced directory. Ope M/SQL Developer Guide 7-19

149 Chapter 7 Ope M/SQL Routie Maagemet Utilities After you specify the routie/iclude file you wat to copy, press <RETURN>. You see the followig prompt: To: Here you specify the ame to be give to the copied routie/iclude file. You may give the routie/iclude file ay ame (a ew ame or a ame that already exists i the curret directory) ad ay of the followig extesios:.mac.int.inc You may copy as may routies/iclude files as you wat. After specifyig the routies/iclude files to copy ad the ew ames for the copied versios, %urcopy prompts you for the followig auxiliary optios: Geerate backups for each copied routie Recompile each copied routie Display errors ecoutered durig compilatio Overwrite existig routies with idetical ames Aswer Yes at the appropriate prompt to eable ay of these optios. By default, %urcopy recompiles all copied routies, displays all compilatio errors, ad overwrites existig routies with idetical ames. It does ot geerate backups by default. Fially, %urcopy asks you to specify the device to which the routie ames ad status iformatio should be output as the routies are copied. Note You ca compile a routie usig the %urcopy utility by copyig it to itself with the compile optio eabled Ope M/SQL Developer Guide

150 %urcopy Example 1 I the example below, %urcopy copies all macro source routies begiig with the letter A located i directory /USER/MSQL ito the curret directory. >do ^%urcopy Copy routie(s): ["/USER/MSQL"]A*.MAC Copy routie(s): <RETURN> To: A*.MAC Geerate backups? No=> <RETURN> Compile? Yes=> N Display Errors? Yes=> <RETURN> Overwrite Existig Routies? Yes=> <RETURN> Display routie ames o Device: <RETURN> Right margi: 80=> <RETURN> AAA.MAC -> AAA.MAC ABC.MAC -> ABC.MAC ACC.MAC -> ACC.MAC AFG.MAC -> AFG.MAC > I this example, %urcopy does ot compile the copied routies ad does ot geerates backups for them. No routies are overwritte because the copied routies did ot previously exist i the curret directory. Ope M/SQL Developer Guide 7-21

151 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example 2 I this example, %urcopy copies the itermediate code routie PRQ to the itermediate code routie called PZZ ad compiles the copied routie. >do ^%urcopy Copy routie(s): PRQ.INT Copy routie(s): <RETURN> To: PZZ.INT Geerate backups? No=> <RETURN> Compile? Yes=> <RETURN> Display Errors? Yes=> <RETURN> Overwrite Existig Routies? Yes=> <RETURN> Display routie ames o Device: <RETURN> Right margi: 79=> <RETURN> PRQ.INT -> * PZZ.INT COMPILED > This operatio effectively replaces the previous cotets of PZZ with the curret cotets of PRQ. The asterisk show i the output lie of this example idicates that the copied routie has overwritte the previous cotets of the target routie. The output lie also displays the message COMPILED to idicate that the ew routie has bee compiled Ope M/SQL Developer Guide

152 %urfid %urfid The %urfid utility searches through macro source routies, itermediate code routies, ad iclude files ad returs all routie lies that cotai at least oe occurrece of ay search strig i a list of search strigs. This cotrasts with %urfad, which returs ay routie lies that cotai occurreces of all search strigs i the list of search strigs. %urfid does ot operate at the object code level. Note O ISM systems the %urfid utility is also kow as %RFIND. Whe you ivoke %urfid, the utility prompts you to specify a search strig. You may specify as may search strigs as you wat. After specifyig the search strigs, %urfid displays the followig prompt: Exact Upper/Lowercase Match? Yes=> Here you may aswer Yes or No to idicate whether or ot you wat the search to be case-sesitive. Yes (case-sesitive) is the default respose. Next, the utility prompts you to specify the routies through which you wat to search. Ope M/SQL Developer Guide 7-23

153 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example I the example below, %urfid searches for occurreces of the strigs Hello ad Goodbye i all macro source ad itermediate code routies located i the curret directory whose ames begi with the letter A. >do ^%urfid Fid routie lies that cotai at least oe of a set of strigs. 1. Search for: Hello 2. Search for: Goodbye 3. Search for: <RETURN> Exact Upper/Lowercase Match? Yes=> N Routie(s): A*.MAC Routie(s): A*.INT Routie(s): <RETURN> Display results o Device: <RETURN> Right Margi: 80=> <RETURN> ABC.INT ABC+4 S ^ABC(x) = "Hello" AQQ.INTAYY.INT AZZ.INT AZZ+6 S ^ABC(z) = "Goodbye" ABC.MAC ABC+4 S ^ABC(x) = "Hello" AQQ.MACAYY.MAC AZZ.MAC AZZ+6 S ^ABC(z) = "Goodbye" > The utility outputs the ames of all routies through which it searches. Whe it fids oe of the specified search strigs, it outputs the tag umbers ad lies i which the strig is located Ope M/SQL Developer Guide

154 %urfad %urfad The %urfad utility searches through macro source routies, itermediate code routies, ad iclude files ad returs routie lies that cotai occurreces of all search strigs i a list of search strigs. This cotrasts with %urfid, which returs ay routie lies that cotai a occurrece of at least oe search strig i the list of search strigs. %urfad does ot operate at the object code level. Note O ISM systems the %urfad utility is also kow as %RFAND. Whe you ivoke %urfad, the utility prompts you to specify a search strig. You may specify as may search strigs as you wat. After specifyig the search strigs, %urfid displays the followig prompt: Exact Upper/Lowercase Match? Yes=> Here you may aswer Yes or No to idicate whether or ot you wat the search to be case-sesitive. Yes (case-sesitive) is the default respose. Next, the utility prompts you to specify the routies through which you wat to search. Ope M/SQL Developer Guide 7-25

155 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example I the example below, %urfad searches for occurreces of the strigs Hello ad Goodbye i all macro source ad itermediate code routies located i the curret directory whose ames begi with the letter A. >do ^%urfad Fid routie lies that cotai all of a set of strigs. 1. Search for: ^ABC 2. Ad Search for: Hello 3. Ad Search for: <RETURN> Exact Upper/Lowercase match? Y=> N Routie(s): A*.MAC Routie(s): A*.INT Routie(s): <RETURN> Display results Device: <RETURN> Right Margi: 80=> <RETURN> ABC.INT ABC+4 S ^ABC(z) = "Hello" AQQ.INT AYY.INT AZZ.INT ABC.MAC ABC+4 S ^ABC(z) = "Hello" AQQ.MAC AYY.MAC AZZ.MAC > The utility outputs the ames of all routies that it searches. Whe it fids all of the specified search strigs i oe lie of a routie, it outputs the tag umbers ad lie i which the strigs are located Ope M/SQL Developer Guide

156 %urdel %urdel You may use the %urdel utility to delete macro source routies, iclude files, itermediate code routies, ad object code routies from the curret directory ad output a list of the deleted routies to a specified device. Note O ISM systems the %urdel utility is also kow as %RDELETE. Whe you ivoke %urdel, the utility prompts you to specify the routies you wat to delete. Note %urdel does ot support remote directory sytax. This meas you caot delete routies/iclude files that reside outside your curret directory. Whe %urdel deletes oe versio of a routie, it shuffles the remaiig versios forward. For example, suppose you maitai three versios of the macro source routie ABC.MAC. Whe you delete versio ABC.MAC.1, the first backup versio (previously called ABC.MAC.2 ) is reamed to ABC.MAC.1 ad becomes the curret versio, ad the secod backup versio is reamed to ABC.MAC.2, while the secod backup versio ceases to exist. Example I the example below, %urdel deletes all versios of all routies (.MAC,.INT,.INC,.OBJ) located i the curret directory that begi with the letter Y. >do ^%urdel Delete routies/iclude files. WARNING: Whe.MAC.1 is deleted, backups are shuffled forward, UNCOMPILED. Routie(s): Y*.*.* Routie(s): <RETURN> Output o Device: <RETURN> Right margi: 80=> <RETURN> > DELETE SELECTED ROUTINES/INCLUDE FILES Jul :32 PM DIRECTORY: /DUA0/MARGARET YAZ.MAC.1 YPP.MAC.1 YZZ.MAC.1 YAZ.MAC.2 YPP.MAC.2 YZZ.MAC.2 Y1.INC Y2.INC Y3.INC YAZ.INT YPP.INT YZZ.INT YAZ.OBJ YPP.OBJ YZZ.OBJ Ope M/SQL Developer Guide 7-27

157 Chapter 7 Ope M/SQL Routie Maagemet Utilities %urverma The %urverma utility lets you set the maximum umber of backup versios maitaied by the curret directory for macro source routies ad iclude files. Note O ISM systems the %urverma utility is also kow as %RVERMAX. The default umber of versios to maitai is four (oe curret versio ad three backups). The maximum umber of versios that Ope M/SQL ca maitai is ie (oe curret versio ad eight backups). Ope M/SQL maitais backups for macro source routies ad iclude files oly. It does ot maitai backups for itermediate code or object code routies; their versio umbers are always.1. Example I the example below, %urverma is used to chage the umber of backup versios maitaied for macro source routies ad iclude files from the default value of 4 to the maximum value of 9. >do ^%urverma Number of versios to keep for.mac: 4=> 9 Number of versio to keep for.inc: 4=> 9 > 7-28 Ope M/SQL Developer Guide

158 %urpurge %urpurge The %urpurge utility deletes backup versios of macro source routies ad iclude files ad outputs a list of purged routies ad their versio umbers to a specified device. Note O ISM systems the %urpurge utility is also kow as %RPURGE. Whe you ivoke %urpurge, the utility prompts you to specify the umber of backup versios to be maitaied after the purge. The default umber of versios to be maitaied is 1, the curret versio oly. If you wish to keep ay backup versios, you must chage the default. Next, the utility prompts you to specify the routies whose backups you wat to purge. Example I the example below, %urpurge purges all backup versios of the macro source routies TEST ad MATT i the curret directory. >do ^%urpurge Purge backups, keepig how may versios: 1=> <RETURN> Routie(s): TEST.MAC Routie(s): MATT*.MAC Device: <RETURN> Right margi: 80=> <RETURN> PURGE SELECTED ROUTINES/INCLUDE FILES RETAINING 1 VERSION Jul :22 PM DIRECTORY: /USER/MSQL TEST.MAC.2 TEST.MAC.3 MATT1.INC.2 MATT1.INC.3 MATT1.INC.4 MATT2.INC.2 MATT2.INC.3 MATT3.INC.3 8 routies Purged. > %urpurge outputs a list of all routies ad iclude files that it purges. Ope M/SQL Developer Guide 7-29

159 Chapter 7 Ope M/SQL Routie Maagemet Utilities %urset The %urset utility is used by the other Ope M/SQL routie utilities to select routies. You will likely ever call this utility directly from the Ope M/SQL programmer mode prompt. You may, however, fid it useful to make calls to %urset i order to select routies from withi a program. Note O ISM systems the %urset utility is also kow as %RSETN. The Global ^mtemp Routies selected usig %urset are stored i the ^mtemp global. The ^mtemp global has the followig structure: ^mtemp(%msub,system@directory,extesio,versio,ame)= The first subscript of the ^mtemp global is %msub, which is the variable retured by %urset. The table below lists ad describes the additioal subscripts to the ^mtemp global: Table 7-3: Subscripts of the ^mtemp Global Subscript system@directory extesio versio ame Meaig System ad directory where the routie resides. Extesio of the routie (MAC, INC, INT, or OBJ). Versio umber of the routie. Name of the routie Ope M/SQL Developer Guide

160 %urset Parameters of %urset The %urset utility has the followig sytax: ^%urset(prompt,access,extesios,sort) The followig table lists ad describes the four parameters accepted by %urset: Table 7-4: Parameters of %urset Parameter prompt access extesios sort Meaig This parameter specifies the prompt used to ask for routies. The default prompt is Routie(s):. If this parameter is ull, %urset uses the default prompt. Note: If your program uses a two-colum format (like the format used by the %urcopy utility, with the Copy From: prompt i oe colum ad the Copy To: prompt i a secod colum), you may use the delimiter $C(1) to separate the first ad secod pieces of the prompt. This parameter specifies the type of access that is permitted for selectig routies. It may have the followig three values: D permits selectig of routies across directories o the same system. S permits selectig of routies across directories ad systems. Null permits selectig of routies i the curret directory oly. This parameter specifies the routie extesios that are accepted as valid. You may eter a list of the routie extesios, separated by commas. If this parameter is ull, oly routies with the extesios.mac ad.int are accepted as valid. This parameter specifies the order i which selected routies are sorted. It may have either of the followig two values: DEVN sorts routies accordig to Directory/System, Extesio, Versio, ad Name. DNEV sorts routies accordig to Directory/System, Name, Extesio, ad Versio. DEVN is the default sort order. Ope M/SQL Developer Guide 7-31

161 Chapter 7 Ope M/SQL Routie Maagemet Utilities Example I the example below, %urset is called with the followig parameters: The prompt to be displayed for selectig routies is defied as: Routie Names: A ull value is passed to the access parameter, meaig that access to routies across directories ad systems is prohibited A value of INT is passed to the extesio parameter to specify that.int is the oly extesio accepted as valid for selectig routies A value of DEVN is passed to the sort order parameter to specify that the selected routies will be sorted by ame >do ^%urset( Routie Names:,, INT, DEVN ) Routie Names: AAA.INT Routie Names: BBB.INT Routie Names: CCC.INT >D ^%G Global ^mtemp(%msub) ^mtemp(163,"@","int",1,"aaa")= "BBB")= "CCC")= > 7-32 Ope M/SQL Developer Guide

162 PART SQL Laguage Implemetatio III Chapter 8 Embedded SQL Chapter 9 Ope M/QSL Implemetatio of SQL Chapter 10 Geeratig Queries

163

164 CHAPTER Embedded SQL 8 Ope M/SQL supports the embeddig of SQL statemets i macro source code. This chapter describes the rules ad sytax for usig embedded SQL i Ope M/SQL applicatios. Specifically, it covers the followig topics: Preprocessor Sytax Delimits Embedded SQL Ope M/SQL Supports Two Kids of Embedded SQL Referecig Macros i Embedded SQL Iteral ad Exteral Values Multi-lie Values Reserved Tag ad Variable Names Portability Detailed Example Ope M/SQL Developer Guide 8-1

165 Chapter 8 Embedded SQL Preprocessor Sytax Delimits Embedded SQL To embed SQL i Ope M/SQL macro source code, you must delimit each SQL statemet usig the Ope M/SQL preprocessor fuctio &sql(...) or, alteratively, ##sql(...), for example: &sql(delete * FROM Employees WHERE TermiatioDate < 1/1/80) The letters sql may be upper or lower case. Ope M/SQL Supports Two Kids of Embedded SQL Ope M/SQL supports the followig two kids of embedded SQL statemets: No-cursor-based SQL Cursor-based SQL No-cursor-based SQL cosists of idividual SELECT, INSERT, UPDATE, ad DELETE statemets. Cursor-based SQL is used for operatios i which a program retrieves multiple rows from a table. To do this, the program declares ad opes a cursor o the table, specifyig oe or more coditios o the rows to be retrieved. It the performs a series of fetches o the cursor, retrievig oe row each time, util all the matchig rows have bee read. No-Cursor-Based SQL A o-cursor-based embedded SQL SELECT statemet query always returs a sigle row of data. No-cursor-based SELECT statemet queries are appropriate whe you kow that a sigle row of data matches the WHERE clause. If a ocursor-based SELECT statemet query matches more tha oe row, the query retrieves oly the first of the matchig rows ad oe of the rest, although it computes ay aggregate fuctios i the SELECT list over all the matchig rows. 8-2 Ope M/SQL Developer Guide

166 Ope M/SQL Supports Two Kids of Embedded SQL Use the INTO Clause to Pass Retrieved Values to M Variables A o-cursor-based SELECT statemet query embedded i a M program always commuicates its retrieved values to the program by usig a INTO clause to read the values ito M variables. For example: &sql(select Name,Telephoe INTO :ame,:tel FROM Employees WHERE SocSec=:ss) This example returs iformatio about the employee whose social security umber equals the value of the M variable ss. If there is o such row, the query sets the local M variable SQLCODE to 100. If there is a matchig row, the values of Name ad Telephoe are copied ito the M variables ame ad tel. The ames ame, tel, ad ss i the above query are prefixed by colos, which idicates to the preprocessor that they are M variables. The followig example shows a embedded INSERT statemet that adds a sigle row to the Employee table: &sql(insert INTO Employee (Name,SocSec,Telephoe) VALUES( Boswell, , )) UPDATE ad DELETE Statemets Ca Operate o Multiple Rows No-cursor-based UPDATE ad DELETE statemet queries ca operate o multiple rows, for example: &sql(update Employee SET AgeStatus= MINOR WHERE Age<21) which sets AgeStatus to MINOR for every Employee row whose Age is less tha 21, ad: &sql(delete FROM Products WHERE Supplier = :sup) which deletes all Products rows whose Supplier field equals the variable sup. For iformatio o how to isert, update, ad retrieve rows usig arrays, see Chapter 9, Ope M/SQL Implemetatio of SQL. Ope M/SQL Developer Guide 8-3

167 Chapter 8 Embedded SQL Cursor-Based SQL Whe your applicatio eeds to access multiple rows of data, you must use a cursor. A cursor acts like a poiter it focuses o accessig ad processig oe row at a time, the moves from that row to the ext i the sequece. Declarig a Cursor Cursor-based SQL ivolves declarig oe or more cursors o oe or more base tables or views. Note You may declare two or more cursors o the same base table ad positio them idepedetly. A cursor ame may cosist of ay umber of alphaumeric characters, though oly the first six are sigificat. The first character must be alphabetic. All cursor operatios for a give cursor ame must reside i a sigle M routie. To declare a cursor, you use the SQL DECLARE statemet. Sice DECLARE statemets are ot executable, IterSystems recommeds for the sake of clarity that you place them at the begiig of a routie. Oce it has bee declared, a cursor ca be used by oe or more OPEN, FETCH, ad CLOSE statemets. The DECLARE statemet for a cursor must precede ay other statemets ivolvig that cursor. Below is a example of a DECLARE statemet: &sql(declare PatCur CURSOR FOR SELECT Name,Telephoe FROM Patiets WHERE Name= Boswell ) This example declares a cursor PatCur that retrieves the ames ad telephoe umbers of all rows i the Patiets table with the ame Boswell. The DECLARE statemet does ot itself execute ay code. Opeig a Cursor Before usig a cursor i a program, you must ope it, as follows: &sql(open PatCur) Depedig o the particular query, the amout of code executed by a cursor OPEN ca be very small or very large. Whe you fiish usig a cursor i a program, you should close it, as follows: &sql(close PatCur) 8-4 Ope M/SQL Developer Guide

168 Ope M/SQL Supports Two Kids of Embedded SQL Use FETCH to Retrieve Iformatio ito a Cursor You use FETCH statemets to retrieve iformatio ito a cursor. For example, the statemet: &sql(fetch PatCur INTO :ame, :tel) fetches the ext row as selected by the DECLARE statemet for PatCur ito the variables ame ad tel. Note that the SELECT statemet has already bee specified as part of the DECLARE statemet. Use the INTO Clause to Pass Retrieved Values to M Variables As i the o-cursor-based versio, you must use a INTO clause to get values from the query ito the program. I cursor-based SQL, you may specify the INTO clause as part of the DECLARE statemet for a cursor, for example: &sql(declare PatCur CURSOR FOR SELECT Name, Telephoe INTO :ame, :tel FROM Patiets WHERE Name= Boswell )... &sql(fetch PatCur) I this example, the FETCH statemet retrieves values ito the variables ame ad tel. Or, you may specify the INTO clause as part of each FETCH statemet that uses the cursor, for example: &sql(declare PatCur CURSOR FOR SELECT Name, Telephoe FROM Patiets WHERE Name= Boswell )... &sql(fetch PatCur INTO :ame, :tel) The ability to use the INTO clause i a FETCH statemet is provided by ANSI- Stadard SQL. The ability to use the INTO clause i a DECLARE statemet is a IterSystems extesio. For more iformatio o INTO clauses, see Chapter 9, Ope M/SQL Implemetatio of SQL. Ope M/SQL Developer Guide 8-5

169 Chapter 8 Embedded SQL You may also use a INTO clause i a FETCH statemet to override the INTO clause i the correspodig DECLARE statemet, for example: &sql(declare PatCur CURSOR FOR SELECT Name, Telephoe INTO :ame, :tel FROM Patiets WHERE Name= Boswell )... &sql(fetch PatCur INTO :1, :t1) Warig Do ot specify %val as the host variable i the INTO clause for a SQL FETCH statemet this causes the FETCH statemet to produce empty values. You may specify other % variables. INSERT, UPDATE, ad DELETE Operatios Follow ANSI-Stadard Cursor-based INSERT, UPDATE, ad DELETE operatios follow ANSI-Staadard SQL, for example: &sql(delete FROM Patiets WHERE CURRENT OF PatCur) which deletes the row that was last FETCH d usig the cursor PatCur. 8-6 Ope M/SQL Developer Guide

170 Referecig Macros i Embedded SQL Referecig Macros i Embedded SQL Embedded SQL text may cotai macro refereces. The Ope M/SQL macro preprocessor expads these macro refereces before it traslates the SQL text. Therefore, you may use macros to geerate parts of the SQL text. The followig example shows a series of macro defiitios followed by a SQL statemet that refereces the macros: #defie TABLE Patiets #defie FIELDS Name,Phoe #defie VARS :,:p #defie COND Name %STARTSWITH JO... &sql(select $$$FIELDS INTO $$$VARS FROM $$$TABLE WHERE $$$COND) Coversely, you may use a macro referece to isert the &sql preprocessor fuctio, as i the followig example: #defie GETNEXT &sql(fetch xcurs INTO :a,:y)... for i=1:1 $$$GETNEXT quit:sqlcode=100 do ^process Whe expadig the last lie, the macro preprocessor first replaces the macro referece $$$GETNEXT with &sql(fetch...) ad the expads the embedded SQL expressio. Ope M/SQL Developer Guide 8-7

171 Chapter 8 Embedded SQL Iteral ad Exteral Values Every value retured by a embedded SELECT query cosists of the iteral value (the value as stored i the database) plus a optioal exteral value (if the Data Dictioary specifies iteral-to-exteral coversio for the specific field). If a value has a exteral value, it is separated from the iteral value by the delimiter character $c(1). Therefore, every value retured by a embedded SQL query has oe of two formats: or iteral iteral_$c(1)_exteral For a complete descriptio of iteral ad exteral field values, see Chapter 9, Ope M/SQL Implemetatio of SQL. Multi-Lie Values Whe a INTO clause retrieves a multi-lie (repeatig) field ito a variable, it puts the cout of lies i the variable ode ad the value of each lie i a umbered ode uder the variable. For example, a two-lie field value is stored as follows i the variable x: x=2 x(1)=first lie x(2)=secod lie For a complete descriptio of multi-lie fields, see Chapter 9, Ope M/SQL Implemetatio of SQL. 8-8 Ope M/SQL Developer Guide

172 Reserved Tag ad Variable Names Reserved Tag ad Variable Names Whe Ope M/SQL geerates itermediate code for a macro source routie that cotais embedded SQL, it automatically geerates tag ad variable ames. For o-cursor-based SQL statemets, all of the geerated tag ames begi with %0, ad all of the geerated variable ames begi with %mmmsql. For cursor-based SQL statemets (suppose that operatios are performed o a cursor called PatCur ), all of the geerated tag ames begi with either %Pat- Cur or %0, ad all of the geerated variable ames begi with either %PatCur or %mmmsql. Therefore, to avoid coflict with geerated tag ad variable ames, macro source routies cotaiig embedded SQL should ot begi ay tag ames with %0 or ay variable ames with %mmmsql. They should also ot begi tag or variable ames with %PatCur, where PatCur is ay cursor ame used i the program. Portability If a macro source routie cotais embedded SQL statemets, you must compile the routie i the directory that cotais the Data Dictioary defiitios of all base tables refereced by the SQL statemets. After compilig a macro source routie that cotais embedded SQL SELECT statemets, you may copy the itermediate code ad object code versios of the routie to aother directory or system ad ru there without copyig ay other routies or globals, assumig the directory to which you copy uses a compatible database structure. Note You caot copy the itermediate code ad object code versios of a macro source routie that cotais ay o-select statemet embedded SQL queries, i.e., you caot copy routies that cotai INSERT, UPDATE, or DELETE statemets. Ope M/SQL Developer Guide 8-9

173 Chapter 8 Embedded SQL Detailed Example The macro source routie show below lists the employees i a compay departmet. It asks the user to specify the first few characters of the departmet ame. If there are o departmet matches with the characters provided by the user, the routie prits a error message ad asks agai. If there is oe match, it lists the employees for that departmet. If there is more tha oe match, it uses cursor-based SELECT/FETCH operatios to cycle through the departmet matches, askig the user which match is desired. EMPLIST ;List the employees i a give departmet ; ;Defie macro CAPITAL to covert a strig to uppercase ad remove ;puctuatio. Calls the etry poit alphaup^yraz as a ;fuctio: ; #defie CAPITALS(%a) $$alphaup^yraz(%a) ; ;Defie macro EXTERNAL to get the exteral value of a retured ;field: ; #defie EXTERNAL(%a) $piece(%a,$c(1),2) ; ;Declare cursor for accessig Departmet table. Selects fields ; Departmet ad Name from Departmet table ad puts them ito ;M variables deptid ad deptame: ; &sql(declare dcurs CURSOR FOR SELECT Departmet,Name INTO :deptid,:deptame FROM Departmet WHERE (%ALPHAUP(Name) %STARTSWITH :ame)) ; ;Declare cursor for accessig Employee table. Selects fields Name ;, Phoe, ad Hiredate ito M variables empame, empphoe, ;ad empdate: ; &sql(declare ecurs CURSOR FOR SELECT Name,Phoe,HireDate INTO :empame,:empphoe,:empdate FROM Employee WHERE (Departmet=:deptid)) ; ;For formattig: ; kill set spaces= ; ;Prompt user to select a departmet: ; askd write!, Departmet ame starts with: read ame quit:ame= set ame=$$$capitals(ame); to compare with %ALPHAUP(Name) below ; ;No-cursor-based SELECT to get COUNT of Departmet rows whose ;ame field begis with the value of the M variable ame. ;COUNT goes ito M variable deptcout, to be used below. ;Get the field values, too, i case COUNT is oe: ; &sql(select Departmet,Name,COUNT(Departmet) INTO :deptid,:deptame,:deptct FROM Departmet WHERE %ALPHAUP(Name) %STARTSWITH :ame) go:+deptct=0 omatch ;say +deptct because it might be ull ; 8-10 Ope M/SQL Developer Guide

174 Detailed Example dloop gotd eloop ; If there is oly oe, go to gotd ad list the employees: ; go:deptct=1 gotd ; ; Otherwise, loop through the matchig ; departmets, askig the user which oe to use: ; &sql(open dcurs) &sql(fetch dcurs) if SQLCODE'=0 &sql(close dcurs) go omatch write!, Do you wat the _deptame_ departmet? read aswer go:aswer= dloop go: Yy '[$extract(aswer) dloop &sql(close dcurs) ; &sql(open ecurs) write!,!, Employees i the _deptame_ departmet: write!, NAME PHONE HIRE DATE write!, ; &sql(fetch ecurs) ;get values for the ext employee i this dept if SQLCODE'=0 &sql(close ecurs) go askd write!, _empame_$e(spaces,1,39-$1egth(empame)) write empphoe_$e(spaces,1,14-$legth(empphoe)) write $$$EXTERNAL(empdate) ;Exteral value of ;hire date (MM/DD/YY) go eloop ;---- omatch write No matchig departmets. go askd Ope M/SQL Developer Guide 8-11

175 Chapter 8 Embedded SQL 8-12 Ope M/SQL Developer Guide

176 CHAPTER Ope M/SQL Implemetatio of SQL 9 This chapter describes extesios to ANSI-Stadard SQL that have bee icorporated ito Ope M/SQL. It assumes that you are already familiar with stadard SQL sytax ad usage. Specifically, it covers the followig topics: Summary of Extesios Jois Aggregate Extesios Duplicate Rows Embedded SQL Usig the INTO Clause Usig the INTO Clause with Arrays VALUES Extesio for INSERT ad UPDATE Queries Multi-Lie Fields Iteral ad Exteral Values %INTERNAL ad %EXTERNAL Fuctios M Operators Extesios to SQL Operators %STARTSWITH LIKE Predicate Collatio Sequece %NOCHECK SQL Trasactio Processig Privilege Operators Usig Subqueries Query-Based Views Ope M/SQL Developer Guide 9-1

177 Chapter 9 Ope M/SQL Implemetatio of SQL Summary of Extesios Ope M/SQL s implemetatio of Structured Query Laguage (SQL), referred to throughout this chapter ad this guide as IterSystems SQL, provides a variety of useful extesios to the ANSI-Stadard SQL Data Maipulatio Laguage (DML). These extesios ehace the power of SQL itself ad help to itegrate SQL with M. The followig list summarizes IterSystems extesios to ANSI-Stadard SQL: Oe-way outer joi (=* operator) Implicit joi (-> arrow sytax) Aggregate extesios (%FOREACH, %AFTERHAVING, DISTINCT BY) Embedded SQL Use of the INTO clause i cursor declaratio SELECT INTO usig mixed variables Array INSERT ad UPDATE VALUES extesio for INSERT ad UPDATE queries Multi-lie fields Iteral ad exteral values %INTERNAL ad %EXTERNAL fuctios M operators LIKE predicate Starts-with operator (%STARTSWITH) Collatio sequece fuctios (%ALPHAUP,%UPPER,%EXACT) %NOCHECK keyword SQL Trasactio processig keywords (%BEGTRANS, %INTRANS) Privilege operators (GRANT, REVOKE, %CHECKPRIV) Subqueries Query-based view operators (CREATE VIEW, ALTER VIEW, DROP VIEW) 9-2 Ope M/SQL Developer Guide

178 Summary of Extesios Added Keywords ad Symbols Keywords that represet IterSystems extesios to SQL begi with the percet sig (%). These keywords iclude: %AFTERHAVING %ALPHAUP %ALTER %BEGTRANS %CHECKPRIV %EXACT %EXTERNAL %FOREACH %FORM %INTERNAL %INTRANS %MENU %MEUNOBJ %NOCHECK %QUERY %REPORT %ROWCOUNT %STARTSWITH %THRESHOLD %UPPER Note The keywords listed above are all Ope M/SQL reserved words. To see a complete list of reserved words, refer to Appedix B of this guide. Ope M/SQL Developer Guide 9-3

179 Chapter 9 Ope M/SQL Implemetatio of SQL The symbols show i the followig table also represet IterSystems extesios to SQL: Table 9-1: SQL Extesio Symbols Symbol Meaig =* Oe-way outer joi -> Implicit joi _ # M scalar operators? [ M compariso operators &! M AND ad OR ] M follows operator IterSystems SQL permits the use of the double quote characters (... ) to delimit literal values, i additio to the apostrophe character (... ) used by ANSI- Stadard SQL. IterSystems SQL allows you to egate the compariso ad logical operators by prefixig them with ot or NOT, for example: ot= (equivalet to < >) ot< (equivalet to >=) ot> (equivalet to <=) ot? ot& ot[ ot] ot! Note The sytax!= is equivalet to NOT=. 9-4 Ope M/SQL Developer Guide

180 Jois Jois Jois provide the meas of likig data i oe table with data i aother table ad are frequetly used i defiig reports ad queries. A joi is a operatio that combies two tables to produce a third, subject to a restrictive coditio. Every row of the ew table must satisfy the restrictive coditio. Oe-Way Outer Jois With stadard ier jois, whe rows of oe table are liked with rows of a secod table, a row i the first table that fids o correspodig row i the secod table is excluded from the output table. With oe-way outer jois, all rows from the first table are icluded i the output table eve if there is o match i the secod table. With oe-way outer jois, the first table pulls relevat iformatio out of the secod table but ever sacrifices its ow rows for lack of a match i the secod table. Whe specifyig a oe-way outer joi, the order i which you ame the tables i the FROM clause is very importat. The first table you specify is the source table for the joi. You specify a outer joi by usig the symbol =* i place of = i the WHERE clause of the SQL query. As a illustratio of the differece betwee a regular joi ad a oe-way outer joi, cosider the query: SELECT Patiet.PName,Doctor.DName FROM Patiet,Doctor WHERE Patiet.Doctor = Doctor.Doctor This query returs oe row for each row of the Patiet table that has a o-ull Doctor field. By cotrast, examie the query: SELECT Patiet.PName,Doctor.DName FROM Patiet,Doctor WHERE Patiet.Doctor =* Doctor.Doctor Though it differs oly i the =* operator, this query returs all the rows of the previous query plus the rows of the Patiet table that have ull value for the Patiet.Doctor field. For such rows, Doctor.Name is retured as ull. This is kow as ull paddig Ope M/SQL automatically performs ull paddig. Ope M/SQL Developer Guide 9-5

181 Chapter 9 Ope M/SQL Implemetatio of SQL Implicit Jois The oe-way outer joi coditio expressed by the followig sytax: A.x =* B.y specifies that every row i A be retured. For each A row retured, if there is a B row such that A.x=B.y, all of the correspodig B values are also retured. If there is o B row such that A.x=B.y, ull paddig causes all B values for that A row to retur as ull. Oe-way outer joi coditios, icludig the ecessary ull paddig, are applied before other coditios. Therefore, a coditio i the WHERE clause that caot be satisfied by a ull-padded value (for example, a rage or equality coditio o a field i B) effectively coverts the oe-way outer joi of A ad B ito a regular joi. For example, if you add the clause AND Doctor.Age < 45 to the two Patiet table queries above, it makes them equivalet. However, if you add the clause AND Doctor.Age < 45 or Doctor.Age is ull, it preserves the differece betwee the two queries. Implicit jois are pre-defied jois betwee tables which you specify i the Data Dictioary. They allow you to defie queries without specifyig the WHERE coditio that is used to joi tables. O a iteral level, a implicit joi causes a additioal joi coditio to be implicitly added (ANDed) to the WHERE clause ad the joied table to be implicitly added to the FROM clause of the SQL query. By defiitio, the implicit joi is a oe-way outer joi. However, coditios o fields of the joi table may cause the joi to act as a regular joi (as explaied above). Ope M/SQL supports two types of implicit jois, desigative refereces ad characteristic relatioships. Characteristic relatioships ca be either child-toparet refereces or paret-to-child refereces. Note You may oly defie desigative ad characteristic relatioships amog tables that reside withi a sigle database. 9-6 Ope M/SQL Developer Guide

182 Jois Arrow Sytax Specifies Implicit Jois You use arrow sytax to specify implicit jois betwee tables. Arrow sytax appears as a dash followed by a greater-tha symbol ( -> ). I Ope M/SQL, you may use arrow sytax i the followig three cases: 1. To sigify Desigative Refereces betwee tables 2. To sigify Child-to-Paret Refereces betwee tables 3. To sigify Paret-to-Child Refereces betwee tables Note Refereces to arrow sytax fields (such as a->b->c) may appear i the SELECT clause of a geeral view defiitio without the use of a AS clause. This holds true also for the SELECT clause of a subquery ested withi the FROM clause of aother query. For example, the followig sytax is valid i Ope M/SQL: SELECT c FROM (SELECT a->b->c FROM d) Desigative Refereces A desigative referece is a may-to-oe lik betwee tables i which oe field of the desigatig table cotais the Row IDs of all rows i the desigated table. A desigative referece is said to be a o-depedet lik because rows i the refereced table exist idepedetly of rows i the desigatig table. I relatioal database termiology, the desigatig table has a foreig key o the refereced table. I M termiology, the desigatig table has a poiter to the refereced table. I Ope M/SQL, a field that desigates aother table is called a desigative referece field. The value of a desigative referece field is the Row ID of a row i the desigated table. Desigative refereces provide a meas of accessig iformatio from a row of the desigated table ad usig that iformatio together with the associated row of the desigatig table. If the field A.b is a desigative referece field that desigates table B ad x is a field i B, the referece: A.b->x poits to the value of x i the row of table B that correspods to A.b. It is iterpreted as a referece to B.x with B added implicitly to the FROM clause ad a additioal oe-way outer joi coditio added implicitly to the WHERE clause, of the form: A.b =* B.RowID Ope M/SQL Developer Guide 9-7

183 Chapter 9 Ope M/SQL Implemetatio of SQL For example, the followig query is equivalet to the secod query o page 9-4: SELECT Patiet.PName,Patiet.Doctor->DName FROM Patiet The followig query retrieves patiet's ame ad patiet's doctor's ame for every patiet who lives i Bosto: SELECT Patiet.PName,Patiet.Doctor->DName FROM Patiet WHERE Patiet.City = Bosto Assumig that Patiet.Doctor is a desigative referece to the Doctor table, this query is equivalet to: SELECT Patiet.PName,Doctor.DName FROM Patiet,Doctor WHERE Patiet.City = Bosto AND Patiet.Doctor =* Doctor.Doctor As aother example, cosider the query: SELECT Patiet.PName,Patiet.Doc1->DName,Patiet.Doc2-> DName FROM Patiet WHERE Patiet.City = Bosto This query is equivalet to: SELECT Patiet.PName,DoctorX.DName,DoctorY.DName FROM Patiet,DoctorX,DoctorY WHERE City = Bosto AND Doc1 =* DoctorX.Doctor AND Doc2 =* DoctorY.Doctor Note If it does ot create ambiguity, A.b->x may be abbreviated as b->x. 9-8 Ope M/SQL Developer Guide

184 Jois Characteristic Relatioships I the Data Dictioary, you ca create tables that are characteristic of other tables. This type of relatioship is appropriate whe oe or more rows i the child table correspod to a sigle row i the paret table. For example, a paret table Ivoices might have a child table LieItems cotaiig oe or more lie items for each ivoice. The child table cotais a paret referece field, which is similar to a desigative referece but poits to the paret table. A child table always desigates its paret table. For this reaso, a characteristic relatioship ca be thought of as a kid of desigative referece. However, a characteristic relatioship is more restrictive tha a desigative referece sice the joi coditio specifies that all rows of the child table must desigate the same paret table row. I this way, a characteristic relatioship satisfies the relatioal defiitio of a ier joi. Child-to-Paret Refereces If table P is the paret of table C ad x is a field i P, the implicit joi sytax: C.ParetRef->x for a give C row refers to the value of x i that row's paret row. It is iterpreted as a referece to P.x with P added implicitly to the FROM clause ad a additioal oe-way outer joi coditio added implicitly to the WHERE clause, of the form: C.ParetRef =* P.RowID For example, give a paret table Customer with child table Ivoice, the query: SELECT Customer->Name FROM Ivoice WHERE Number = is equivalet to: SELECT Customer.Name FROM Ivoice,Customer WHERE Ivoice.Number = AND Ivoice.Customer =* Customer.Customer This query returs the ame of the customer to whom ivoice umber belogs. Ope M/SQL Developer Guide 9-9

185 Chapter 9 Ope M/SQL Implemetatio of SQL Paret-to-Child Refereces If P is the paret of C ad x is a field i C, the implicit joi sytax: P.C->x for a give row i P refers to the value of x i a child row of that row. It is iterpreted as a referece to C.x with C added implicitly to the FROM clause ad a additioal oe-way outer joi coditio added to the WHERE clause, of the form: P.RowID =* C.ParetRef Sice there ca be may childre for a give paret, each child causes the query to produce aother row. For example, if you have a paret table Customer with child table Ivoice, the query: SELECT Ivoice->Number FROM Customer WHERE Name = Smith is equivalet to: SELECT Ivoice.Number FROM Customer,Ivoice WHERE Customer.Name = Smith AND Customer.Customer =* Ivoice.Customer This query returs the umbers of all ivoices for all customers with the ame Smith Ope M/SQL Developer Guide

186 Aggregate Extesios Aggregate Extesios IterSystems provides extesios to the SQL aggregate fuctios AVG, COUNT, MAX, MIN, ad SUM to make them more powerful ad more flexible. These extesios simplify the relatioship of the SQL aggregate fuctios with the GROUP BY ad DISTINCT operators, effectively makig aggregates, groupig, ad duplicate elimiatio three orthogoal compoets of the SQL laguage. Ope M/SQL s aggregate fuctio extesios are: Aggregates alogside fields i SELECT ad HAVING clauses %FOREACH %AFTERHAVING DISTINCT BY i aggregates SELECT DISTINCT BY Aggregates as Query Colums The first extesio allows aggregates to appear i a SELECT list or HAVING clause alogside field values. I ANSI-Stadard SQL, if a query cotais a aggregate, the SELECT ad HAVING clauses caot cotai ay field values outside of aggregates (uless they are listed i the GROUP BY clause). For example, the query: SELECT Salary,AVG(Salary) FROM Employee is ivalid i ANSI-Stadard SQL because it selects both a aggregate ad a field value. IterSystems SQL treats a aggregate simply as aother colum i each retured row, just as it treats a field or a expressio composed of fields. I IterSystems SQL, the above example returs oe row of output for each row cotaied i the Employee table. The first colum of each retured row is the salary of the correspodig employee. The secod colum is the value of the aggregate AVG(Salary), which is the same for each row ad is the average salary for all employees. This feature is also useful i cojuctio with the %FOREACH extesio (see below). The followig query: SELECT Name,Salary,AVG(Salary) FROM Employee HAVING Salary>AVG(Salary) lists the ame, salary ad average salary for all employees whose salary is greater tha the average salary. ANSI-Stadard SQL does ot accept such a query. Ope M/SQL Developer Guide 9-11

187 Chapter 9 Ope M/SQL Implemetatio of SQL %FOREACH If the SELECT list cosists oly of aggregates ad either %FOREACH or GROUP BY is used (i which case, the SELECT list is acceptable to ANSI-Stadard SQL), Ope M/SQL adds a implicit DISTINCT to the query so that it returs oly oe row. This is doe because the value of the aggregate is the same for each selected row. For example, the query: SELECT AVG(Salary) FROM Employee WHERE Departmet = SALES returs the same value of AVG(Salary) for each Employee row, amely the average salary for all employees i the sales departmet. Therefore, Ope M/SQL adds a implicit DISTINCT to the query, as follows: SELECT DISTINCT AVG(Salary) FROM Employee WHERE Departmet = SALES This reduces the output to a sigle row cosistig of the average salary i the sales departmet. Two additioal extesios geeralize aggregates ad make them more powerful. The %FOREACH keyword allows queries to produce differet aggregate values for differet groups of retured rows, ad the DISTINCT BY feature provides a high degree of cotrol over duplicate elimiatio. Obtaiig aggregate results alog with data is especially useful whe combied with the IterSystems extesio keyword %FOREACH, which ca appear oly iside a aggregate. The %FOREACH keyword divides the rows retured by a query ito groups ad calculates a separate aggregate value for each group. %FOREACH uses the followig sytax: Aggregate (expr1 %FOREACH (expr2,expr3,...)) where a list of oe or more arbitrary expressios follows the %FOREACH keyword. For example, the query: SELECT Name,Divisio,Departmet, AVG(Salary %FOREACH(Divisio,Departmet)) FROM Employee returs four colums of iformatio for each row i the Employee database Ope M/SQL Developer Guide

188 Aggregate Extesios The output colums for this query are show i the table below: Colum Value 1 Employee's ame 2 Employee's divisio (call it DV) 3 Employee's departmet (call it DP) 4 Average salary for employees i divisio DV ad departmet DP ANSI-Stadard SQL uses the keyword GROUP BY for a similar purpose. Whereas GROUP BY operates o a etire query, %FOREACH is more flexible because it oly affects the value of a particular aggregate. Therefore, although Ope M/SQL also supports ANSI-Stadard SQL s implemetatio of GROUP BY, IterSystems recommeds that you use %FOREACH ad DISTINCT i all cases. For aother example of %FOREACH, the query: SELECT PName,Ward,Age,AVG(Age %FOREACH(Ward)),Sex, AVG(Age %FOREACH(Sex)) FROM Patiet returs, for each patiet, the average age of all patiets i that patiet s ward ad the average age of all patiets of that patiet s sex: The output colums for this query are show i the table below: PName Ward Age AVG(Age) By Ward Sex AVG(Age) By Sex Smith F 59 Joes M 29 Clark M 29 Baker F 59 Mulligatawy F 59 Ope M/SQL Developer Guide 9-13

189 Chapter 9 Ope M/SQL Implemetatio of SQL %AFTERHAVING The %AFTERHAVING keyword is aother IterSystems extesio that ca appear iside aggregates withi a SELECT clause. %AFTERHAVING uses the followig sytax: Aggregate (... %AFTERHAVING) Whe Ope M/SQL ecouters a aggregate with %AFTERHAVING, it computes the aggregate oly for those rows that satisfy the query s HAVING clause. For example, the query: SELECT Name,Salary,AVG(Salary),AVG(Salary %AFTERHAVING) FROM Employee WHERE City = Bosto HAVING Salary > AVG(Salary) computes two differet salary averages. The aggregate AVG(Salary) computes the average salary for all Bosto employees. The aggregate AVG(Salary %AFTERHAVING) computes the average salary for those Bosto employees whose salary is greater tha the average of all salaries for Bosto employees. Note Sice IterSystems SQL allows aggregates ad fields to appear together i SELECT ad HAVING clauses, you may compare the field Salary with the aggregate AVG(Salary) i the HAVING clause. DISTINCT BY IterSystems SQL follows ANSI-Stadard SQL by permittig the use of the keyword DISTINCT i a SELECT clause to remove duplicate rows from the output of a query. For example, the query: SELECT DISTINCT Ward FROM Patiet returs oe row for each distict value of the field Patiet.Ward. IterSystems SQL also follows ANSI-Stadard SQL by permittig the use of DISTINCT for aggregates i a SELECT clause, thus elimiatig duplicate values from those used to compute the aggregate. For example, the query: SELECT COUNT(DISTINCT City) FROM Patiet returs the umber of distict values i Patiet.City. IterSystems SQL provides a extesio that allows you to elimiate just the rows that have duplicate values for specific expressios Ope M/SQL Developer Guide

190 Aggregate Extesios This extesio is the use of DISTINCT followed by the keyword BY ad a parethesized list of expressios, specifyig which fields ad expressios should be distict i the retured rows. Rather tha elimiatig rows that are duplicates i their etirety, it elimiates rows that have duplicate values for these expressios. DISTINCT BY uses the followig sytax: DISTINCT BY (expr1, expr2,...) For example, the query: SELECT DISTINCT BY(City) Mayor,Phoe FROM Precicts returs the Mayor ad Phoe of oe of the rows for each value of City. Note that the value of City itself is ot selected by this query. A example of DISTINCT BY with a aggregate fuctio is: SELECT SUM(DISTINCT BY(Name) Isurace) FROM Employee This query returs the sum of values for Employee.Isurace, icludig i the sum oly oe isurace value for each employee ame. The followig is a example of DISTINCT BY usig a expressio: SELECT DISTINCT BY(Salary + Commissio) Salary,Commissio FROM Employee This query returs oe salary ad commissio for each value of salary + commissio. Ope M/SQL Developer Guide 9-15

191 Chapter 9 Ope M/SQL Implemetatio of SQL Duplicate Rows ANSI-Stadard SQL allows tables to cotai multiple idetical rows, i.e. rows that have the same values for all fields. IterSystems SQL, however, does ot permit idetical rows. I accordace with most relatioal models, IterSystems SQL requires that each table have a uique RowID field. This extesio elimiates potetial problems with queryig tables. Duplicate rows ca cause otherwise well-defied queries ad aggregates to retur varyig results depedig o the order of the SQL clauses. The fuctioality of duplicate rows is essetially preserved i Ope M/SQL by a table desig that allows rows to be idetical except for a uique Row ID field that is automatically geerated by the system (ad may be custom-defied). This approach allows the creatio of duplicate rows for otherwise uique fields such as social security umbers or compay ames, as they may be eeded for lookups, while still preservig the uique row cocept of the relatioal model Ope M/SQL Developer Guide

192 Embedded SQL Embedded SQL Ope M/SQL allows the embeddig of SQL statemets i M programs. This feature replaces ad ehaces the Module Laguage (ML) of ANSI-Stadard SQL. You may embed SQL at the macro source code level oly. To embed SQL i Ope M/SQL macro source code, you must delimit each SQL statemet usig the Ope M/SQL preprocessor fuctio &sql(...) or, alteratively, ##sql(...) Refereces to M variables withi embedded SQL must begi with a colo. Embedded SQL commuicates retrieved iformatio to M programs by usig a INTO clause to read the values ito M variables. For example, the embedded SQL query: &sql(select PName, Phoe INTO :ame,:tel FROM Patiet WHERE SSN=:um) uses the M variable um as iput for the WHERE clause ad the M variables ame ad tel to retrieve the output of the query. For a complete descriptio of how embedded SQL uses the INTO keyword to read query values ito M variables, refer to Chapter 8, Embedded SQL. A INTO clause may iclude both subscripted ad usubscripted M local variables as well as a mixture of both. Embedded SQL statemets ca modify the M if-switch. Keep this i mid whe embeddig SQL iside a #if statemet. Ope M/SQL Developer Guide 9-17

193 Chapter 9 Ope M/SQL Implemetatio of SQL Usig the INTO Clause Both ANSI-Stadard SQL ad IterSystems SQL permit the use of the INTO keyword i queries. I o-cursor-based SQL queries, you may use the INTO clause with the SELECT statemet, for example: &sql(select Name, Age INTO :,:a FROM Employee WHERE SocSec = ) selects a row from the Employee table ad puts the values of the Name ad Age fields ito the M variables ad a. Note Sice this is a o-cursor-based embedded SQL query, it ca retrieve oly oe row, eve if more tha oe row matches the WHERE clause. I cursor-based SQL queries, you may use the INTO clause with the FETCH statemet, for example: &sql(fetch c INTO :x,:y,:z) where c is a cursor ame. By usig its ow INTO clause each FETCH ca read the same cursor ito differet sets of variables. You May Use INTO i Cursor Declaratio A IterSystems SQL extesio permits the use of the INTO clause i the cursor declaratio statemet, for example: &sql(declare c CURSOR FOR SELECT Date, Time, Result INTO :d, :t, :r FROM Tests)... &sql(fetch cursor) Puttig the INTO clause i the DECLARE statemet (rather tha the FETCH statemet) produces slightly faster code ad prevets havig to repeat the INTO clause i each FETCH. However, you must be careful ot to modify the variables refereced i the INTO clause while the cursor is ope. If you put a INTO clause i the DECLARE statemet, you may override it with a INTO clause i a FETCH statemet Ope M/SQL Developer Guide

194 Usig INTO with Arrays Usig INTO with Arrays IterSystems SQL allows you to use the INTO clause with M arrays to do all of the followig: Retrieve values from a SELECT query ito a array INSERT values from a array ito a table UPDATE a table with values stored i a array SELECT INTO Usig Arrays IterSystems SQL allows the INTO clause i a SELECT statemet to retrieve values ito a array. This applies oly to queries where all of the fields i the SELECT clause yield from a sigle table specified i the FROM clause. To do this, the INTO clause must retrieve values ito a subscripted M variable, ad you must leave the last subscript of the M variable uspecified, for example: INTO :a() puts each retrieved field value ito the array elemet: a(col) where col is the field s colum umber i the base table, as defied i the Data Dictioary. Similarly, the INTO clause: INTO :a("foo",) puts each retrieved field value ito the array elemet: a( foo,col) For example, if the Employee table has the followig fields: Colum Name 1 Employees (RowID) 2 Name 3 Address (multi-lie) 4 Departmet 5 Locatio 6 Telephoe Ope M/SQL Developer Guide 9-19

195 Chapter 9 Ope M/SQL Implemetatio of SQL the followig embedded SQL query: &sql(select * INTO :emp() FROM Employee WHERE Name = "Smith") reads the Employees field ito emp(1), Name ito emp(2), etc. Sice Address is a multi-lie field, emp(3) is set to the umber of address lies, emp(3,1) is set to the first lie of Address, emp(3,2) to the secod, ad so o. Cautio Ope M/SQL does ot support use of the INTO clause to retrieve fields from a view ito a local array. It oly supports use of the INTO clause to retrieve fields from a base table ito a local array. SELECT INTO Usig Mixed Variables You ca also mix subscripted ad usubscripted variables i the INTO clause of a SQL SELECT query. This allows you to use the array otatio i a query ivolvig expressios ad/or fields from other tables. I this case, you must iclude additioal scalar variables i the INTO clause to retrieve the values of expressios ad fields from other tables. Whe combiig a array with other variables i a INTO clause, the array referece must always appear first. The array receives all values for fields from the table specified i the FROM clause. The remaiig variables i the INTO list match up oe-by-oe with the expressios ad fields from refereced tables i the SELECT clause. For example, the query: SELECT PName, Doctor->DName, Sex, AVG(Age) INTO :p( items,),:x,:y FROM Patiet where PName is colum 2 i Patiet ad Sex is colum 5 i the Patiet table, returs the followig values: p( items,2)=pname p( items,5)=sex x=doctor->dname y=avg(age) 9-20 Ope M/SQL Developer Guide

196 Usig INTO with Arrays INSERT ad UPDATE INTO Usig Arrays IterSystems SQL allows you to use a variable referece with uspecified last subscript to pass a array of values ito a embedded SQL INSERT or UPDATE query. For example, the embedded SQL query: &sql(insert INTO Employee VALUES :emp( profile,)) causes each field i the iserted Employee row to be set to: emp( profile,col) where col is the field s colum umber i the Employee table, as defied i the Data Dictioary. Note that whereas ANSI-Stadard SQL requires the table ame to be followed by a list of field ames, as i: INSERT INTO Employee (Name,Telephoe) VALUES (:ame,:tel) IterSystems SQL does ot require that you provide a list of field ames after the table ame whe you use a array referece. The presece ad absece of array elemets determies the fields ito which the query iserts values. This eables the cotets of the array to dictate which fields receive isert values. Usig a Array Referece with a INSERT Query ForINSERT queries, if a array etry is missig (udefied as opposed to ull) ad the correspodig field has a explicitly defied default value, the default value becomes the value of that field. However, if a array etry is explicitly defied as ull, the default value does ot override the ull settig. I the emp( profile ) example above, if the Employee table has the followig fields with correspodig default values as defied i the Data Dictioary: Colum Name Default 1 Employee (Row ID) 2 Name 3 Address 4 Departmet S 5 Locatio 6 Telephoe Ope M/SQL Developer Guide 9-21

197 Chapter 9 Ope M/SQL Implemetatio of SQL ad the array values defied are: emp( profile,2)= Smith emp( profile,3)=2 emp( profile,3,1)= 1441 Mai St. emp( profile,3,2)= Cableto, IL emp( profile,5)= emp( profile,7)=25 emp( profile, ext )= F the iserted Employee row has Name set to Smith, Address set to a two-lie value, Departmet set to the default S, ad Locatio set to ull. The default value for Locatio is ot used sice the correspodig array elemet is defied with a ull value. The array elemets 7 ad ext do ot correspod to colum umbers i the Employee table, therefore the query igores them. Usig a Array Referece with a UPDATE Query A UPDATE query ca also referece a array with uspecified last subscript. Whereas INSERT uses the presece ad absece of array elemets to assig values ad default values to a ewly created row, UPDATE uses the presece of a array elemet to idicate that the correspodig field should be updated. For example, cosider the followig embedded SQL statemet: &sql(update Employee VALUES :emp( profile,) WHERE Employee = 379) Give the above defiitios ad array values, this statemet will update the values of the Name ad Locatio fields of the Employee row for which Row ID = 379. You may also use a array referece with a UPDATE query that targets multiple rows, for example: &sql(update Employee VALUES :emp( profile,) WHERE Type = PART-TIME ) As with INSERT, the cotets of the array dictate which fields receive update values Ope M/SQL Developer Guide

198 VALUES Extesio for INSERT ad UPDATE Queries VALUES Extesio for INSERT ad UPDATE Queries Typically, INSERT queries use the followig sytax: INSERT INTO <tableame> (<fieldame>,<fieldame>,...) VALUES (...,...) ad UPDATE queries use the followig sytax: UPDATE <tableame> (<fieldame>,<fieldame>,...) VALUES (...,...) where the elemets i the VALUES clause correspod i sequece to the fields specified after the table ame. Note If there is oly oe value elemet specified i the VALUES clause, it is ot ecessary to eclose the elemet i paretheses. IterSystems SQL allows INSERT ad UPDATE queries to use either sytax above without requirig you to explicitly specify a list of field ames after the table ame. I order to skip the step of specifyig a list of field ames after the table ame, your query must meet the followig two criteria: 1. The umber of values specified i the VALUES clause is the same as the umber of fields i the table. 2. The values i the VALUES clause are listed i order of the iteral colum umbers of the fields. For example, the query: INSERT INTO tabl1 VALUES (5, Joh ) is equivalet to the query: INSERT INTO tabl1 (age,ame) VALUES (5, Joh ) if the table tabl1 has exactly two fields. I this example, the value 5 is assiged to the field with the lower colum umber, ad the value Joh is assiged to the other field. Ope M/SQL Developer Guide 9-23

199 Chapter 9 Ope M/SQL Implemetatio of SQL Multi-Lie Fields Ope M/SQL exteds the relatioal database model by permittig the creatio of multi-valued fields, commoly called multi-lie fields by M programmers. Such fields are useful for storig iformatio about a sigle etity where that iformatio spas several lies. A typical multi-lie field might be used for a address or a block of commet text. While such structures are useful, they violate the First Normal Form relatioal precept ad, therefore, are ot relatioally correct. The user should be aware that SQL cotais o operators for maipulatig multi-lie fields, ad that it is impossible to perform comparisos or row orderig with multi-lie fields. IterSystems SQL allows you to use multi-lie fields i both output queries (SELECT) ad iput queries (INSERT ad UPDATE). Usig Multi-Lie Fields i SELECT Queries I SELECT queries, you may referece multi-lie fields i the SELECT statemet by usig a INTO clause to copy the cotets of the field ito a variable. Note You may ot use multi-lie fields with compariso operators i the WHERE clause or i ay of the row orderig clauses. If you attempt to use a multi-lie field i a WHERE clause or i a row orderig clause, Ope M/SQL returs a error message whe it tries to process the query. Whe a INTO clause copies a multi-lie field ito a variable, it creates a array by puttig the cout of lies i the variable ode ad the value of each lie i a descedat ode uder the variable. For example, if the field Patiet.Address for patiet row 758 cotais the followig three lies: 426 Suday Drive Apt. 12C Roberta, CA the embedded query: &sql(select Address INTO :a FROM Patiet WHERE Patiet = 758) places the followig values i a : a=3 a(1)= 426 Suday Drive a(2)= Apt. 12C a(3)= Roberta, CA Ope M/SQL Developer Guide

200 Multi-Lie Fields Similarly, the query: &sql(select Address INTO :b( addr ) FROM Patiet WHERE Patiet = 758) places the followig values i b : b( addr )=3 b( addr,1)= 426 Suday Drive b( addr,2)= Apt. 12C b( addr,3)= Roberta, CA Usig Multi-Lie Fields i INSERT ad UPDATE Queries You may also target multi-lie fields with INSERT ad UPDATE queries by usig a array i the VALUES clause as iput to the INSERT or UPDATE statemet. For example, the query: &sql(update Doctors(Address) VALUES :b( addr ) WHERE Doctors = :doc) which uses the b values listed above as iput to the multi-lie field Doctors.Address. Sice Doctors.Address is a multi-lie field i this example, the variable b( addr ) must cotai a multi-lie value as above. If, however, the iput value is ot a variable (for example, if it is a costat), it is used as the first lie of a multi-lie value. For example, the query: &sql(update Doctors(Address) VALUES Mai Street WHERE Doctors = :doc) sets Doctors.Address to a oe-lie value whose first lie is Mai Street. Ope M/SQL Developer Guide 9-25

201 Chapter 9 Ope M/SQL Implemetatio of SQL Iteral ad Exteral Values The cocept of iteral ad exteral values pertais to fields that are defied i the Data Dictioary to have Exteral-to-Iteral ad/or Iteral-to-Exteral Coversio Code. The iteral value is the value that is stored i the database. The exteral value is a pritable or user-readable form. By default, the followig Ope M/SQL field types have coversio code ad maitai both iteral ad exteral values: Number Date Time Yes/No Ad, the followig field type has the optio to geerate coversio code for maitaiig both iteral ad exteral values. Multiple Choice For example, the iteral value for a field of data type Date has the M format of $H ad the exteral value is a prited represetatio that depeds o which of six date formats the applicatio developer chooses for that field. Furthermore, you ca explicitly specify additioal coversio code by isertig M code. I SQL queries, the followig rules apply cocerig iteral ad exteral values: 1. For a give field, the iteral value is the first piece of $c(1) ad the exteral value is the secod piece of $C(1), as follows: Iteral_$c(1)_Exteral 2. Variables ad costats are either iteral or exteral ad have o data types. Their use depeds o cotext. Whe comparig a field with a variable, the variable should cotai a value suitable for compariso with the field s iteral value. 3. As a exceptio to rule 2, costats are treated specially i coditios such as: or Field <Op> Costat Costat <Op> Field where <Op> is ay compariso operator or where <Op> specifies iput to a field i a INSERT or UPDATE statemet Ope M/SQL Developer Guide

202 Iteral ad Exteral Values I this cotext, the field s exteral-to-iteral coversio code is applied to the costat. This allows a compariso such as: StartDate > 06/01/86 to test whether or ot the iteral value of the field StartDate is greater tha the iteral represetatio of 06/01/86, i.e. whether StartDate is after 06/01/ Variables are also treated specially i the same two coditios, amely: or Field <Op> Variable Variable <Op> Field where <Op> is ay compariso operator or where <Op> specifies iput to a field i a INSERT or UPDATE statemet. I this cotext, the variable ca optioally be give a iteral ad exteral value by usig the delimiter character $c(1). If the variable s value is: Iteral_$c(1)_Exteral or simply: Iteral where Iteral has a o-ull value, Iteral is take as the iteral value for either compariso with a field or iput to a field. If the value is: $c(1)_exteral the field s exteral-to-iteral coversio is applied to Exteral to produce a iteral value. 5. For all fields that have iteral-to-exteral coversio code defied i the Data Dictioary, each value retured by a embedded SELECT query also takes the form: Iteral_$c(1)_Exteral If there is o iteral-to-exteral coversio code defied i the Data Dictioary, the value retured is simply Iteral I either case, the iteral value is: $piece(value,$c(1),1) Ope M/SQL Developer Guide 9-27

203 Chapter 9 Ope M/SQL Implemetatio of SQL The followig example uses both iteral ad exteral values retured by a query: &sql(select HireDate INTO :hiredate FROM Employee WHERE SocSec = ) set itdate=$piece(hiredate,$c(1)) set extdate=$piece(hiredate,$c(1),2) if itdate>$h write!, Not hired util,extdate 6. Each value retured by a o-embedded SELECT query is the result of applyig ay applicable iteral-to-exteral coversio code Ope M/SQL Developer Guide

204 %INTERNAL ad %EXTERNAL Fuctios %INTERNAL ad %EXTERNAL Fuctios IterSystems SQL supports the followig two SQL uary fuctios: %EXTERNAL %INTERNAL Whe applied to a field for which Iteral-to-Exteral coversio code is defied, %EXTERNAL returs the exteral value for that field. Whe applied to a field for which Iteral-to-Exteral coversio code is defied, %INTERNAL returs the iteral value for that field. You may referece the %EXTERNAL ad %INTERNAL keywords i the SELECT, WHERE, ad ORDER BY clauses of a SQL query, usig the followig sytax: SELECT %EXTERNAL(FieldName) Or, you may specify the field by its colum umber, as follows: SELECT %EXTERNAL(FieldColumNumber) For example: SELECT %INTERNAL(FieldName),... FROM Table WHERE %INTERNAL(FieldName) = 'some value'... ORDER BY %INTERNAL(FieldName) %EXTERNAL eables you to retrieve ad maipulate the exteral value of a field. For example, you might defie coditios based o the exteral value of a field, or you might defie a field to sort by its exteral value. This is especially useful for Multiple Choice fields, where the iteral value is a umber, but you eed to test or sort by the exteral value. %INTERNAL eables you to retrieve ad maipulate the iteral value of a field. For example, you might defie coditios based o the iteral value of a field, or you might defie a field to sort by its iteral value. This is especially useful for Multiple Choice fields, where the exteral value is a umber, but you eed to test or sort by the iteral value. If the field does ot have a separate exteral value (i.e., Iteral-to-Exteral coversio code is ot defied), %INTERNAL ad %EXTERNAL both retur the field s iteral value. This makes it possible to use these keywords eve whe you do ot kow whether or ot a field has Iteral-to-Exteral coversio code defied for it. Ope M/SQL Developer Guide 9-29

205 Chapter 9 Ope M/SQL Implemetatio of SQL M Operators IterSystems has exteded SQL to support several M operators. This icreases the expressive power of SQL ad helps to better itegrate the two laguages. The table below lists ad describes the M operators supported by IterSystems SQL: Table 9-2: M Operators Supported By IterSystems SQL Operator _ (space followed by uderscore) &!? # / \ [ ] Usage Cocateates two strigs wherever it is ot part of a idetifier. You must use a space to prevet ambiguity. The expressio: A_B is the ame A_B cotaiig a uderscore. While the expressio: A _B is the cocateatio of A with B. For compatibility with the M laguage, IterSystems SQL allows & as a syoym for AND ad! as a syoym for OR. IterSystems SQL also recogizes the followig M operators:? patter match # modulo (remaider) / divisio \ iteger divisio [ strig cotais ] follows = IterSystems SQL implemets the equals sig i accordace with the M covetio rather tha the ANSI-Stadard SQL covetio for comparig text strigs of uequal legth. Whereas ANSI-Stadard SQL pads the shorter text strig with blak spaces, IterSystems SQL does ot. Therefore, ( a = a ) is false Ope M/SQL Developer Guide

206 M Operators Table 9-2: M Operators Supported By IterSystems SQL (Cotiued) Operator NOT or ot Usage You may egate compariso ad boolea operators by prefixig them with the word ot or NOT (without iterveig spaces). You may also use the word ot as a prefix for a etire coditio. The expressios: WHERE NOT Age < 5 ad WHERE Age NOT < 5 are syoymous. Note: You caot use the M apostrophe ( ) to sigify NOT because SQL uses the apostrophe to sigify quotatio marks for literal strigs.!= IterSystems implemetatio of SQL supports the sytax!=. This sytax is equivalet to NOT=. Patter Match Operator Ca Test Variables IterSystems SQL allows you to use the patter match operator (?) agaist userdefied variables. To do this, you must prefix the variable ame with the idirectio For example, suppose you set the variable amevar to a patter match coditio, as follows: S amevar= 1.10A1, 1.5A You could use the patter match operator to referece this patter match coditio i the WHERE caluse of a query, as follows: SELECT Name FROM Employees WHERE Name? :@amevar This query retrieves ames from the Employees table for all rows where the Name field has the form: such as: but ot: <1-10 alphabetic characters>,<1-5 alphabetic characters> Smith,Joh Washigto,George Ope M/SQL Developer Guide 9-31

207 Chapter 9 Ope M/SQL Implemetatio of SQL Extesios to SQL Operators [NOT] IN Operator Ope M/SQL provides extesios to several SQL operators, as described below. IterSystems SQL supports the use of the [NOT] IN operator with fields of data type Date ad Time i WHERE clause coditios. The [NOT] IN operator tests whether or ot a date or time falls withi a specified date/time rage. For Date fields, the [NOT] IN operator uses the followig sytax: Date_Field [NOT] IN (Start_Date,Ed_Date) where Start_Date is a start date i exteral format, ad Ed_Date is a ed date i exteral format. For Time fields, the [NOT] IN operator uses the followig sytax: Time_Field [NOT] IN (Start_Time,Ed_Time) where Start_Time is a start time i exteral format, ad Ed_Time is a ed time i exteral format. For example: Cocateatio Operator SELECT * FROM Table WHERE Date_Field IN ('10/25/1994','01/26/93') AND Time_Field IN ('10:25PM','11:35AM') IterSystems SQL supports the use of the SQL cocateatio operator ( ). For example, if the fields F1 ad F2 have the followig values: F1 = Part Oe, F2 = Part Two the query: SELECT F1,F2,F1 & F2 INTO :val1,:val2,:val3 FROM Table WHERE F1 & F2= Part Oe & Part Two yields the followig results: val1 = Part Oe val2 = Part Two val3 = Part Oe & Part Two 9-32 Ope M/SQL Developer Guide

208 %STARTSWITH %STARTSWITH IterSystems SQL provides the extesio keyword %STARTSWITH. %STARTSWITH is a compariso operator that tests to determie whether oe character strig is a prefix of aother. %STARTSWITH uses the followig sytax: expr1 %STARTSWITH expr2 where the expressios ca be ay valid SQL expressios. For example, a query that cotais the WHERE clause: WHERE ProductCode %STARTSWITH S returs all rows where the value of the ProductCode field starts with the character S. %STARTSWITH treats fields of data type Name somewhat differetly. With fields of data type Name, %STARTSWITH ca match both the last ame ad first ame strigs o either side of the comma. For example, if EmpName is a field of data type Name, the a query that cotais the WHERE clause: WHERE EmpName %STARTSWITH SM,J returs all rows for which $PIECE(EmpName,,,1) starts with SM ad $PIECE(EmpName,,,2) starts with J. For example: EmpName = SMITH,JANE EmpName = SMOOT,JERRY but ot: EmpName = SMITH,HERMIONE The %STARTSWITH operator ad other compariso operators are modified by collatio sequeces as described i the sectio etitled Collatio Sequece o page Ope M/SQL Developer Guide 9-33

209 Chapter 9 Ope M/SQL Implemetatio of SQL LIKE Predicate Ope M/SQL supports the ANSI Stadard SQL-2 LIKE predicate for performig compariso tests o two values. The LIKE predicate uses the followig sytax: <match value> [NOT] LIKE <search patter> [ESCAPE <escape character>] Where the sytax elemets have the followig meaigs: 1. The value for <match value> may be a field or a literal strig. If it is a literal strig, it must be eclosed i sigle quotes. 2. The value for <search patter> ca be either a literal strig or a host variable. If it is a literal strig, it must be eclosed i sigle quotes. Literal strigs may referece the special patter matchig characters % ad _. 3. If the ESCAPE clause is specified, the value for <escape character> must be oe ad oly oe character. Also, if the escape character is preset i the search patter strig, the the character followig the escape character withi the patter strig must be oe of the special patter matchig characters, either % or _. Below is a sample SQL query that uses the LIKE predicate i the WHERE clause: SELECT FieldA, FieldB, FieldC FROM Table WHERE FieldA LIKE abc% This query retrieves FieldA, FieldB, ad FieldC from Table for all rows where FieldA starts with the character strig abc ad has ay umber of characters i legth. Note Note By default, the LIKE predicate always uses the exteral value of a field for compariso purposes. The LIKE predicate uses the collatio fuctio (EXCAT, ALPHAUP, UPPER) used by the match value o the left side of the equatio to perform the compariso test. Special Patter Matchig Characters The LIKE predicate supports the followig two special patter matchig characters: _ (uderscore symbol) % (percet sig) 9-34 Ope M/SQL Developer Guide

210 LIKE Predicate These special patter matchig characters are defied as follows: _ You may use this special character i the search patter strig to match ay sigle character i the same positio i the match value strig. Examples iclude: >Match This LIKE _Match This >>Match This LIKE _Match This Match This LIKE _Match This (Match) (No Match) (No Match) % You may use this special character i the search patter strig to match ay umber of characters (zero or more) betwee the last exact matchig character ad the ext exact matchig character i the match value strig. Examples iclude: >Match This LIKE %Match This >>Match This LIKE %Match This Match This LIKE %Match This Match This! LIKE %Match This Match??? This!!! LIKE Match% This% (Match) (Match) (Match) (No Match) (Match) Specifyig a Host Variable as the Search Patter ESCAPE Qualifier The search patter you specify after the LIKE predicate does ot always have to be a strig literal. You may also specify a search patter that refereces a host variable, for example: Match This LIKE :hostvar Ope M/SQL's implemetatio of the LIKE predicate supports the ESCAPE qualifier. The ESCAPE qualifier lets you suppress the meaig of the special characters % ad _ i the search patter strig ad treat them istead as literal characters. For example, the followig SQL statemet: Match This LIKE $_Match This ESCAPE $ evaluates to the followig M code: Match This?1 _Match This which is ot true. Ope M/SQL Developer Guide 9-35

211 Chapter 9 Ope M/SQL Implemetatio of SQL Error Hadlig However, the followig SQL statemet: Match_This LIKE Match$_This ESCAPE $ evaluates to the followig M code: Match_This?1 Match_This which is true. If the sytax of the LIKE predicate cotais a mistake, Ope M/SQL returs the error code SQLCODE=-63, ad you see the followig error message: Data Exceptio - ivalid escape character 9-36 Ope M/SQL Developer Guide

212 Collatio Sequece Collatio Sequece EXACT Collatio sequece is the orderig of character strigs. Ope M/SQL supports six collatio sequece fuctios: EXACT ALPHAUP UPPER Plus (+) Mius (-) Space ( ) These collatio sequece fuctios determie the orderig of the output values produced by SELECT queries as well as the behavior of compariso operatios. The EXACT collatio sequece orders pure umeric values (values for which x=+x) i umeric order first, followed by all other characters i strig order. EXACT uses the same collatio sequece for strigs as the ANSI-Stadard ASCII collatio sequece. Accordig to the ASCII collatio sequece, digits are collated before uppercase alphabetic characters ad uppercase alphabetic characters are collated before lowercase alphabetic characters. Puctuatio characters occur at several places i the sequece. Note Numbers that are ot caoic (e.g., 02 or 1.30) collate as strigs rather tha umbers. The followig example shows several strigs listed i EXACT collatio sequece: Strig A'Ha ARNOLD Adams a'choo aaroso Note that (apostrophe) collates before A. EXACT is the default collatio sequece fuctio. If you prefer aother collatio sequece, you may choose oe of the collatio sequeces described below. Ope M/SQL Developer Guide 9-37

213 Chapter 9 Ope M/SQL Implemetatio of SQL ALPHAUP The ALPHAUP collatio sequece fuctio coverts all strigs to ALPHAUP format ad the collates or compares accordig to the EXACT collatio sequece. ALPHAUP format removes all puctuatio (o-alphaumeric) characters except commas ad questio marks ad coverts all alphabetic characters to uppercase. The followig example shows the same strigs as above listed i ALPHAUP collatio sequece: Strig aaroso a Choo Adams A Ha ARNOLD Compared As AARONSON ACHOO ADAMS AHA ARNOLD UPPER The UPPER collatio sequece fuctio coverts all strigs to UPPER format ad the collates or compares accordig to the EXACT collatio sequece. UPPER format coverts all alphabetic characters to uppercase but leaves puctuatio characters itact. The followig example shows the same strigs as above listed i UPPER collatio sequece: Strig a Choo A Ha aaroso Adams ARNOLD Compared As A CHOO A HA AARONSON ADAMS ARNOLD 9-38 Ope M/SQL Developer Guide

214 Collatio Sequece Plus, Mius, ad Space The Plus, Mius, ad Space collatio sequece fuctios are directed towards the collatio of umeric values. The table below describes the Plus, Mius, ad Space collatio sequece fuctios: Table 9-3: Plus, Mius, ad Space Collatio Sequece Fuctios Fuctio Effect O Collatio Sequece Idex Map Sytax Plus (+) Mius (-) Space ( ) Deletes leadig character zeros so that umeric values with leadig character zeros collate as umbers rather tha as character strigs. Reverses the collatio sequece for umeric values. This causes umeric values to collate i descedig order (highest to lowest) istead of ascedig order (lowest to highest). Forces all values to collate as character strigs. This causes all umeric values to collate after all character strigs. +{field} -{field} _{field} Field Collatio Sequece I Ope M/SQL, all fields of data type Name ad Text use oe of the six collatio sequece fuctios described above (EXACT, ALPHAUP, UPPER, Plus, Mius, or Space). Wheever you defie a base table field i the Data Dictioary of data type Name or Text, you assig a collatio sequece fuctio to it. The default collatio sequece for all Name ad Text fields is EXACT. The collatio sequece fuctio you assig to a field affects the results of SQL ORDER BY clauses ivolvig that field. Choice of collatio sequece also affects comparisos o that field usig ay of the compariso operators, listed below: < > = >= <=!= ot> ot< %STARTSWITH Ope M/SQL Developer Guide 9-39

215 Chapter 9 Ope M/SQL Implemetatio of SQL Collatio Sequece ad ORDER BY Whe a SQL query has a ORDER BY clause that ames oe field with a data type of Text or Name, as i: SELECT EmpName... ORDER BY EmpName the query uses the collatio sequece fuctio defied for the order-by field to determie the order i which it returs matchig rows. If a query has a ORDER BY clause that ames ay other field or expressio, as i: SELECT DateEd-DateStart... ORDER BY 1 the query collates its output accordig to the EXACT collatio sequece fuctio. If the field EmpName uses the ALPHAUP collatio sequece fuctio, the example: SELECT DateEd-DateStart,EmpName... ORDER BY 1,2 orders the retured rows first by DateEd-DateStart i EXACT collatio order, ad withi that by EmpName i ALPHAUP order. Collatio Sequece ad Comparisos Whe performig comparisos of character strig values, Ope M/SQL typically uses the EXACT collatio sequece fuctio. If either side of a compariso operator is a field of data type of Name or Text, Ope M/SQL uses the collatio sequece fuctio defied for the field i the Data Dictioary. For example, if EmpName is defied to use the ALPHAUP collatio sequece fuctio, the compariso: EmpName > jo tests EmpName i ALPHAUP format to determie whether it is greater tha (follows i collatio sequece) the strig JO. I effect, Ope M/SQL implicitly applies the ALPHAUP fuctio (see %ALPHAUP below) to both sides of the compariso to covert each side to ALPHAUP format. After the coversio, it performs the compariso based o the EXACT collatio sequece Ope M/SQL Developer Guide

216 Collatio Sequece If both sides of a compariso are fields of data type Name or Text, Ope M/SQL uses precedece order to choose the collatio sequece for the compariso. The precedece order is: 1. ALPHAUP (highest) 2. UPPER 3. EXACT (lowest) Ope M/SQL chooses the collatio sequece with the higher precedece. %ALPHAUP, %UPPER, ad %EXACT IterSystems SQL supports three extesio fuctios to force the coversio of a value to ALPHAUP, UPPER, or EXACT format, as described above. These extesio fuctios are: %ALPHAUP %UPPER %EXACT Suppose that the field EmpName is defied to use the ALPHAUP collatio sequece. The example: %ALPHAUP(EmpName) > jo compares EmpName coverted to ALPHAUP format with the lowercase strig jo. Sice %ALPHAUP(EmpName) is a expressio rather tha a field, Ope M/SQL uses the EXACT collatio sequece to perform the compariso. Similarly, the example: %EXACT(EmpName) > jo compares the EXACT value of EmpName with the lowercase strig jo. I other cotexts, the %ALPHAUP ad %UPPER fuctios simply covert idividual values. The SELECT clause: SELECT %ALPHAUP(EmpName)_ -- _Phoe returs a value cosistig of the EmpName field coverted to ALPHAUP format cocateated with the costat -- cocateated with the EXACT value of the Phoe field, for example: RADCLIFF,CHRIS Ope M/SQL Developer Guide 9-41

217 Chapter 9 Ope M/SQL Implemetatio of SQL Chagig the Default Collatio Sequece Uder some circumstaces, you may wat to chage the default M collatio sequece to be somethig other tha EXACT. Though it is possible, you should do this oly with extreme cautio. Three possible reasos for chagig the EXACT collatig sequece are: 1. To hadle global data that was created previously with a particular collatio sequece. 2. To build a applicatio that uses a atioal character set differet from the default character set. 3. To build a applicatio requirig o-stadard orderig of strigs cotaiig umbers. Chagig Collatio Sequece o ISM Systems Collatio sequece cosists of two compoets: 1. Character set This is a strig of ASCII character codes that gives the members of the set ad their collatio order. 2. Strig collatio switch If ON, the collatio order applies to all strigs icludig umbers. If OFF (default), caoic umeric strigs (x=+x) are collated first i umeric order followed by all other strigs i collatio order. You ca chage these two compoets idepedetly, as follows: For a particular process, the $ZU(23) fuctio chages the character set ad strig collatio switch for the M variable ] ( follows ) operator ad for $ORDER o local variables. For a particular global, you may use the %GCREATE utility to create M global with a revised character set ad strig collatio switch. You caot chage this agai later for the created global. You may use the System Maager s Modify System Parameters (MSP) utility to defie the iitial $ZU(23) settig for processes ad to defie the character set ad strig collatio switch associated with a particular directory. The character set ad strig collatio switch of a directory are used as the default values for ewly created globals i the directory. Also, whe a process switches to a ew directory usig $ZU(5), the $ZU(23) settig for the process is set to the ew directory s character set ad strig collatio switch. You may also use the MSP utility to defie a system-wide default for the character set ad strig collatio switch Ope M/SQL Developer Guide

218 Collatio Sequece To avoid icosistet results from SQL queries o a database, you must defie the collatio sequeces for all of the globals i the database as well as $ZU(23) to be idetical. Chagig Collatio Sequece o No-ISM Systems If you are ruig Ope M/SQL o a o-ism host M system, please cosult your M vedor's system maagemet guide for iformatio o chagig the M collatig sequece. Ope M/SQL Developer Guide 9-43

219 Chapter 9 Ope M/SQL Implemetatio of SQL %NOCHECK IterSystems SQL supports the use of the %NOCHECK keyword i SQL INSERT, UPDATE, ad DELETE statemets to suppress the followig validatio checkig: Field Validatio Code Base Table Validatio Code Checkig for required fields Checkig for field uiqueess %NOCHECK does ot suppress Exteral-to-Iteral Coversio Code or does it suppress the executio of filig triggers whe appropriate. The sytax for usig the %NOCHECK keyword is: INSERT %NOCHECK... UPDATE %NOCHECK... DELETE %NOCHECK... Use of the %NOCHECK keyword is appropriate i a applicatio that reads rows from oe table ad writes them directly to aother. If the validatio ad coversio code is the same for both tables, there is o eed to check a row that is read from the first table before filig it to the secod. Similarly, you may wat a applicatio to do its ow validatio checkig ad coversio, ad bypass the code built ito the Data Dictioary to avoid redudat checkig Ope M/SQL Developer Guide

220 SQL Trasactio Processig SQL Trasactio Processig ANSI-Stadard SQL supports two trasactio processig statemets, COMMIT ad ROLLBACK. I ANSI-Stadard SQL, ulike Ope M/SQL, every operatio (SELECT, UPDATE, etc.) automatically begis a trasactio if oe is ot already i progress. IterSystems SQL gives explicit cotrol of trasactios to the applicatio programmer ad provides two extesio keywords for this purpose: %BEGTRANS begis a trasactio %INTRANS sets the variable SQLCODE to oe of the followig values: Retur Value Meaig 0 Trasactio ot i progress -1 Trasactio i progress (but jourallig was ot eabled whe the trasactio started) >0 Trasactio i progress (ad jourallig was eabled whe the trasactio started) I order to perform a ROLLBACK operatio, jourallig must be eabled for the system (i.e., %INTRANS must retur a o-egative value) as well as for every global whose modificatios are to be cosidered part of the trasactio (i.e., whose modificatios eed to be rolled back as part of the ROLLBACK operatio). The followig example of embedded SQL uses the %INTRANS keyword to determie whether a trasactio is i progress ad, if ot, begis oe: ew oldtras &sql(%intrans) set oldtras=sqlcode if 'oldtras &sql(%begtrans)... if failed &sql(rollback) go doe... if 'oldtras go doe &sql(commit) doe... If a trasactio was ot previously i progress, this code begis a ew oe ad commits it at the ed. If a trasactio already was i progress, this code does ot commit it. If a error occurs durig processig, the code performs a rollback istead of a commit. Ope M/SQL Developer Guide 9-45

221 Chapter 9 Ope M/SQL Implemetatio of SQL Trasactios iclude ot oly SQL modificatios but also ay direct global sets ad kills performed by a M program. Ope M/SQL supports SQL trasactio processig oly o those platforms that support M trasactio processig. Curretly, Ope M/SQL supports trasactio processig whe ruig o the followig host M systems: ISM DSM 9-46 Ope M/SQL Developer Guide

222 Privilege Operators Privilege Operators IterSystems SQL supports the SQL keyword USER i accordace with ANSI- Stadard SQL. IterSystems SQL also supports the SQL GRANT ad REVOKE statemets, as defied i ANSI-Stadard SQL, with several extesios specific to Ope M/SQL. ANSI-Stadard SQL permits the gratig ad revokig of privileges oly o base tables. IterSystems SQL exteds ANSI-Stadard by allowig the gratig ad revokig of privileges o all of the followig objects: Base Tables Views Forms Meu Objects Meus (Old-Style) Reports Queries GRANT You may use the SQL GRANT statemet to grat access privileges o specified objects to Ope M/SQL users. The GRANT statemet has a optio to allow the user to grat access to other users. Note The ower of a object automatically holds all privileges o that object. The GRANT statemet uses the followig sytax: GRANT <list of actios> ON [<object type>]<object ame> TO <gratees> [WITH GRANT OPTION] For example: GRANT %ALTER, SELECT, INSERT ON Patiets TO Chris WITH GRANT OPTION Ope M/SQL Developer Guide 9-47

223 Chapter 9 Ope M/SQL Implemetatio of SQL The table below describes the elemets of the GRANT statemet sytax: Table 9-4: GRANT Statemet Sytax Elemets Sytax Elemet <list of actios> <object type> <object ame> <gratees> [WITH GRANT OPTION] Meaig Here you specify a list of Ope M/SQL privileges actios, delimited by commas. You may specify a asterisk (*) or ALL PRIVILEGES to idicate privileges o all actios, or you may list oe or more of the privilege actios show i the table below. Here you specify the type of object o which you wat to grat privileges. The default object type is base table. Omit this parameter to specify base table as the object type. Alteratively, you may specify ay of the followig object types: %FORM %MENUOBJECT %MENU %REPORT %QUERY You may grat privileges oly o oe object type at a time. Note: A view is also a valid object type o which privileges may be grated. SQL treats views as tables. Specify the ame(s) of the specific object(s) o which you wat to grat privileges, or a asterisk (*) to idicate all object ames of the specified object type. If you specify a list of idividual objects, you must delimit the object ames by commas. You may grat privileges o multiple objects at oce (though they must all be the same object type). Specify IDs for the user(s) to whom you wish to grat privileges. These IDs may be ay of the followig: Role ame(s) UserName(s) of user(s) registered i the User table UserName(s) of user(s) ot registered i the User table You may also eter a asterisk (*) or _PUBLIC to grat privileges to all users. Whe you do this, Ope M/SQL assigs the privileges to the UserName _PUBLIC, which meas urestricted access for all users. You may optioally specify the WITH GRANT OPTION keyword to allow the user(s) to whom you are gratig these privileges to grat the same privileges to other users Ope M/SQL Developer Guide

224 Privilege Operators The table below lists ad describes the privilege actios you ca grat to or revoke from Ope M/SQL users o Ope M/SQL objects: Table 9-5: Ope M/SQL Privilege Actios Privilege Actio %ALTER SELECT INSERT UPDATE DELETE REFERENCES Meaig Privileges to modify the defiitio of a object Privileges to retrieve iformatio from a base table or view, or to ru a object such as a form Privileges to isert a row Privileges to update a existig row Privileges to delete a existig row Privileges to create desigative refereces to a table REVOKE You may use the SQL REVOKE statemet to revoke access privileges o specified objects from Ope M/SQL users. Oly the grator of privileges has the authority to revoke those privileges. The SQL REVOKE statemet uses the followig sytax: REVOKE [GRANT OPTION FOR] <list of actios> ON [<object type>] <object ame> FROM <gratees> [CASCADE] For example: REVOKE %ALTER, SELECT, INSERT ON %FORM PatietIfo FROM Chris CASCADE The <list of actios>, <object type>, <object ame>, ad <gratees> sytax elemets have the same meaig i the REVOKE statemet as they do i the GRANT statemet. Ope M/SQL Developer Guide 9-49

225 Chapter 9 Ope M/SQL Implemetatio of SQL The table below describes the two optioal keywords supported by the REVOKE statemet: Table 9-6: REVOKE Statemet Sytax Elemets Keyword [GRANT OPTION FOR] [CASCADE] Meaig You may optioally specify this keyword to revoke oly the GRANT optio (the user s ability to grat the privileges to other users) for the specified privileges ad ot the privileges themselves. You may optioally specify this keyword to strip the privileges o the specified object from all users who received them from the revokee (or via the revokee). For example, if you revoke privileges from user A, ad user A had previously grated those same privileges to user B, the uder the Cascade optio you also revoke those privileges from user B (as well as from ay users to whom user B may have grated the privileges). %CHECKPRIV Keyword The %CHECKPRIV keyword is a IterSystems SQL extesio that allows a Ope M/SQL user to check whether or ot s/he holds a specified privilege o a specified Ope M/SQL object. The sytax for usig %CHECKPRIV is: %CHECKPRIV [GRANT OPTION FOR] <actio> ON <object type> <object ame> For example: %CHECKPRIV %ALTER ON %FORM PatietIformatio If the user holds the specified privilege, the query returs a SQLCODE value of 0 (success). If the user does ot hold the specified privilege, the query returs a SQLCODE value of 100. %CHECKPRIV may check oly oe actio o oly oe object at a time. The <actio>, <object type>, ad <object ame> sytax elemets have the same meaig i the %CHECKPRIV statemet as they do i the GRANT ad REVOKE statemets. The GRANT OPTION FOR keyword is optioal. If you specify this keyword, the query checks whether or ot the user holds the GRANT privilege o the specified privilege ot whether or ot the user holds the specified privilege itself Ope M/SQL Developer Guide

226 Privilege Operators I order to ru a %CHECKPRIV query, you must esure that a Authorizatio ID is established prior to executig the query. You ca establish a Authorizatio i ay of the followig ways: By executig the query from ay of the followig locatios withi Ope M/SQL: Iteractive Query Editor A meu optio of actio type SQL A trigger item of actio type SQL Whe Ope M/SQL is ruig, the Authorizatio ID is always defied. By issuig a M commad with the followig sytax prior to ruig the query: > do setaid^%msql( <UserName> ) where <UserName> is a UserName that is registered i the User Table. For example: > do setaid^%msql( Zeus ) SQLCODE Values After a %CHECKPRIV query, the SQLCODE variable has the value 0 if the user holds the tested privilege, or 100 if the user does ot hold the tested privilege. GRANT ad REVOKE queries set the SQLCODE variable to 0 whe they successfully complete the iteded operatio. If a GRANT or REVOKE query is iapplicable because a user already held (or did ot hold i the case of REVOKE) the specified privileges, the query sets SQLCODE to 100. For a complete listig of other SQL error messages ad their meaigs, refer to Appedix A: SQL Error Messages. Ope M/SQL Developer Guide 9-51

227 Chapter 9 Ope M/SQL Implemetatio of SQL Usig Subqueries IterSystems SQL allows the use of subqueries i accordace with ANSI-Stadard SQL. A subquery is a SQL SELECT statemet query embedded withi aother SQL SELECT statemet query. Accordig to ANSI-Stadard SQL, a subquery must be embedded withi a WHERE clause or a FROM clause. Whe embedded withi a WHERE clause, the result of the subquery must be a atomic data value (oe colum, aggregate, or expressio) or a truth value. Whe embedded withi a FROM clause, the result of the subquery is a virtual table that may cosist of may colums ad may rows. I additio to permittig subqueries i WHERE clauses ad FROM clause, Iter- Systems SQL also permits subqueries to be embedded withi the SELECT clauses. You may est all subqueries may to ay umber of levels. Subqueries ormally appear as complete queries eclosed withi paretheses i a WHERE clause. A SQL query that has the form: SELECT... FROM... WHERE... may cotai a subquery i the WHERE clause, thus the form: SELECT... FROM... WHERE... (SELECT... FROM... WHERE...) Usig a Subquery i a WHERE Clause The set of rows yielded by a subquery is used to restrict the outside query. Below are some examples of various ways to use subqueries i logical coditios withi WHERE clauses. Note Curretly, Ope M/SQL supports oly correlated subqueries queries i which the result of the subquery depeds o the value of the specific row of the outer query. No-correlated subqueries, i which the outer ad ier queries are completely idepedet, are ot supported at this time Ope M/SQL Developer Guide

228 Usig Subqueries Expressio Matches Some Value i Subquery Output I the example: WHERE <expr> IN (SELECT... FROM... WHERE...) the subquery retrieves oe colum for some set of rows, ad the predicate is the truth value of <expr> beig equal to the data value of the colum for ay of the retrieved rows. Expressio Does Not Match Ay Value i Subquery Output I the example: WHERE <expr> NOT IN (SELECT... FROM... WHERE...) the subquery retrieves oe colum from some set of rows, ad the predicate is the truth value of <expr> NOT beig equal to the data value of the colum for ay of the retrieved rows. Subquery Retrieves At Least Oe Row I the example: WHERE EXISTS (SELECT... FROM... WHERE...) the predicate tests for the existece of oe or more rows specified by the subquery. Typically, the subquery takes the form: SELECT * FROM... WHERE... Expressio Compares With Values i Subquery Output I the example: WHERE <expr> <Compar-op> (SELECT... FROM... WHERE...) the subquery must retrieve a atomic value (oe colum or aggregate), ad the predicate is the truth value of the compariso operatio of <expr> with rows from the subquery output. Ope M/SQL Developer Guide 9-53

229 Chapter 9 Ope M/SQL Implemetatio of SQL Expressio Compares with Some Values i Subquery Output I the example: WHERE <expr> <Compar-op> SOME (SELECT... FROM... WHERE...) the subquery retrieves some set of rows, ad the predicate tests the truth value of the compariso operatio of <expr> with ay row from the subquery output. Expressio Compares with All Values i Subquery Output I the example: WHERE <expr> <Compar-op> ALL (SELECT... FROM... WHERE...) the subquery retrieves some set of rows, ad the predicate tests the truth value of the compariso operatio of <expr> with all rows from the subquery output. Usig a Subquery i a FROM clause Whe you use a subquery i a FROM clause, the results of the subquery defie the virtual table o which the outer query is based. This virtual table may cosist of may colums ad may rows. You must observe the followig restrictios whe defiig subqueries i the FROM clause: 1. You may ot put aythig else i the FROM clause of the outer query the subquery must be aloe 2. The subquery may ot have a subquery i its FROM clause. However, it may have subqueries aywhere else (i its WHERE clause or i its SELECT clause), ad those subqueries may have subqueries aywhere (icludig i their FROM clauses). 3. The subquery may ot cotai aggregates or DISTINCT. Note The use of query-based views i a FROM clause is equivalet to specifyig the view s query as a subquery i the FROM clause. Therefore, the above restrictios also apply to query-based views. For more iformatio o query-based views, see the sectio of this chapter etitled Query-Based Views o page Ope M/SQL Developer Guide

230 Usig Subqueries Ope M/SQL Subquery Extesios IterSystems SQL provides two extesios to the ANSI-Stadard SQL specificatios for subqueries: 1. While ANSI-Stadard SQL permits subqueries to be embedded oly withi WHERE clauses, Ope M/SQL adds the ability to embed subqueries withi SELECT clauses, i the form show below: SELECT (SELECT... FROM... WHERE...) FROM... WHERE IterSystems SQL supports two logical operators, FOR SOME ad FOR ALL, which eable you to ivoke subqueries more succictly. Subquery Embedded i SELECT Clause Subqueries embedded withi a SELECT clause are scalar subqueries they always retur oe scalar value. The followig SQL query cotais a scalar subquery embedded i the SELECT clause: SELECT Sum,Same,Scity,(SELECT Cout(Pum) FROM Parts WHERE Suppliers.Scity=Parts.Pcity) FROM Suppliers This query yields the followig output table: Sum Same Scity Cout S1 Klei Provo 1 S2 James Daytoa S3 Travers Bosto 1 S4 Marti Provo 1 I the followig examples, ote the use of the patietum field, which is the Row ID of the Patiets table ad the paret referece withi the child table Tests. Ope M/SQL Developer Guide 9-55

231 Chapter 9 Ope M/SQL Implemetatio of SQL FOR ALL Operator The FOR ALL logical operator tests whether every value of oe expressio satisfies the coditio(s) of a secod embedded expressio. Essetially, FOR ALL provides a shorthad versio of a subquery. FOR ALL uses the followig sytax: FOR ALL expr1(expr2) For example, the followig query uses the FOR ALL operator: &sql(select PatietName,Age FROM Patiets WHERE FOR ALL tests (tests.result= Positive AND patiets.patietum=tests.patietum)) ad is equivalet to: &sql(select PatietName,Age FROM Patiets WHERE NOT EXISTS (SELECT * FROM Tests WHERE NOT (tests.result = Positive AND patiets.patietum = test.patietum))) FOR SOME Operator The FOR SOME logical operator tests whether at least oe value of oe expressio satisfies the coditio(s) of a secod embedded expressio. Essetially, FOR SOME provides a shorthad versio of a subquery. FOR SOME uses the followig sytax: FOR SOME expr1(expr2) For example, the followig query uses the FOR SOME operator: &sql(select PatietName,Age FROM Patiets WHERE FOR SOME Tests (Tests.patietum=Tests.patietum AND Tests.Result= Positive )) ad is equivalet to: &sql(select PatietName,Age FROM Patiets WHERE patietum =SOME (SELECT patietum FROM Tests WHERE Tests.Result= Positive )) 9-56 Ope M/SQL Developer Guide

232 Query-Based Views Query-Based Views IterSystems SQL supports the followig SQL DDL statemets for use i creatig, editig, ad deletig query-based views: CREATE VIEW ALTER VIEW DROP VIEW Whe you create a query-based view, you are explicitly defiig the query that jois the base table i the view. You may issue SQL queries usig these DDL statemets i either of two places: Via the Iteractive Query Editor As embedded SQL i M macro source code CREATE VIEW ALTER VIEW You may compile these SQL statemets i ay directory with the same result. Ope M/SQL performs o referetial itegrity checkig o these SQL statemets at compile time. It checks referetial itegrity oly at ru time. The CREATE VIEW statemet uses the followig sytax: CREATE VIEW <viewame> AS SELECT...FROM...WHERE... For example: CREATE VIEW Outstadig_Charges AS SELECT Patiet_Name, Date, Amout_Due FROM Billig WHERE (Billig.Lab_Charges!= Paid OR (Billig.Office_Visit_Charges!= Paid ) The ALTER VIEW statemet uses the followig sytax: ALTER VIEW <viewame> AS SELECT...FROM...WHERE... ALTER VIEW uses exactly the same sytax as CREATE VIEW. Whe you use ALTER VIEW, you delete ad recreate the etire view, retaiig the same view ame ad iteral view umber. Ope M/SQL Developer Guide 9-57

233 Chapter 9 Ope M/SQL Implemetatio of SQL DROP VIEW The DROP VIEW statemet uses the followig sytax: DROP VIEW <viewame> Restrictios o Defiig Query-Based Views You must observe the followig restrictios whe defiig query-based views: The query may ot cotai aggregates or DISTINCT. The query may ot itself referece aother query-based view. You May Name Query-Based Views i FROM Clause IterSystems SQL allows you to ame query-based views i the FROM clause of SQL SELECT statemet queries. However, a query that ames a query-based view i its FROM clause caot ame ay additioal items i the FROM clause. Furthermore, a query-based view caot appear i the FROM clause of a query as report data source Ope M/SQL Developer Guide

234 CHAPTER Query Geeratio ad Processig 10 Ope M/SQL provides two facilities for creatig SQL queries o a ad hoc basis, the Query Geerator ad the Iteractive Query Editor. This chapter describes how to use these query geeratio facilities to create, ru save, ad copy queries. Specifically, it covers the followig topics: Facilities for Creatig SQL Queries Usig the Query Geerator Usig the Iteractive Query Editor Ruig Queries ASCII-Delimited Output for Queries Copyig Queries List Queries Report Detailed Query Listig Report Ope M/SQL Developer Guide 10-1

235 Chapter 10 Query Geeratio ad Processig Facilities for Creatig SQL Queries The table below summarizes the capabilities ad relative advatages of the two Ope M/SQL query geeratio facilities: Table 10-1: Query Geeratio Facilities Facility Descriptio Advatages Query Geerator Iteractive Query Editor Provides a easy-to-use template of SQL SELECT statemet sytax equipped with fields for the appropriate SQL clauses, icludig SELECT, FROM, WHERE, ORDER BY, GROUP BY, ad HAVING. Provides a free-form SQL editor eviromet (similar to the Full Scree Editor) where you ca create ad ru ay valid SQL query. Provides full scree editig capabilities. You ca defie a SELECT query by simply fillig i the template. You do ot eed to kow SQL sytax rules. You ca defie ay valid SQL query, makig the Iteractive Query Editor more flexible tha the Query Geerator. Both the Query Geerator ad the Iteractive Query Editor ca compile the fiished query ad execute it o your commad. The output of SELECT-statemet queries appears i stadard tabular report format. You may prit this output i ay of the followig ways: To your scree To a hard copy priter To a file i ASCII-delimited output format Accessig the Query Geeratio Facilities The Ope M/SQL query geeratio facilities (Query Geerator ad Iteractive Query Editor) as well as several query maagemet utilities are available as optios o the SQL meu. Procedure To access the SQL meu: 1. At the M programmer prompt, type the followig commad to eter Ope M/SQL: > do ^%msql 10-2 Ope M/SQL Developer Guide

236 Facilities for Creatig SQL Queries You see the Ope M/SQL Mai Meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄOpe M/SQL MeuÄÄÄ ³ ³ ³ Data Dictioary ³ ³ Forms ³ ³ Reports ³ ³ Queries ³ ³ Meu Geerator ³ ³ System Maagemet ³ ³ Privileges ³ ³ Developer Utilities ³ ³ User Utilities ³ ³ Server Maagemet ³ ³ Relatioal Gateway ³ ³ Help Optios ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Jul 05, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio Ope M/SQL Meu 03:50PM Press <Help> For Help 2. From the Ope M/SQL Mai Meu, select the Queries optio. Note: You may type q to select this optio it is a memoic accelerator. You see the SQL Meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄÄÄÄÄÄÄÄÄSQLÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Defie Queries ³ ³ Iteractive SQL Queries ³ ³ Ru Existig Queries ³ ³ Copy Query ³ ³ List Queries ³ ³ Detailed Query Listig ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Friday Jul 14, :14PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio SQL 01:14PM Press <Help> For Help The table below lists ad describes the optios o the SQL meu: Ope M/SQL Developer Guide 10-3

237 Chapter 10 Query Geeratio ad Processig Table 10-2: Optios o SQL Meu Optio Defie Queries Iteractive SQL Queries Ru Existig Queries Copy Query List Queries Detailed Query Listig Descriptio Select this optio to access the Query Geerator, which provides a template for defiig SQL SELECT statemet queries. Select this optio to access the Iteractive Query Editor, which provides a full scree editig eviromet for creatig ad executig SQL statemets usig ay valid sytax. Select this optio to access the Ru Existig Queries utility, which allows you to select ay query defied via the Query Geerator or Iteractive Query Editor ad ru it. Select this optio to access the Copy Query utility, which allows you to select ay query defied via the Query Geerator or Iteractive Query Editor ad copy its defiitio to create a ew query. Select this optio to prit the List Queries report, which displays a alphabetical listig of all queries defied withi the curret database. Select this optio to prit the Detailed Query Listig report, which displays various iformatio about oe or more specified queries Ope M/SQL Developer Guide

238 Usig the Query Geerator Usig the Query Geerator The Query Geerator provides a easy-to-use template for defiig SQL SELECT statemet queries. The template is equipped with fields for the appropriate SQL clauses, icludig SELECT, FROM, WHERE, ORDER BY, GROUP BY, ad HAVING. This eables you to create a SELECT query by simply fillig i the template. The Query Geerator automatically geerates your query as a cursor-based SELECT statemet query, meaig it ca retrieve multiple data rows ito the output table. Sice the Query Geerator automatically geerates the cursor-based SELECT statemet sytax, you do ot eed to use ay of the followig SQL commads: DECLARE CURSOR OPEN CURSOR FETCH CURSOR CLOSE CURSOR INTO Procedure To defie a SELECT statemet query usig the Query Geerator: 1. From the SQL Meu, select the Defie Queries optio. You see the Query Defiitio lookup widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄQuery DefiitioÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ ³ ³ ³ ³ Query Name Descriptio ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Query Defiitio Selectig Press <Help> For Help 2. At the Query Name field i the Query Defiitio lookup widow, eter a query ame, ad press <RETURN>. Ope M/SQL Developer Guide 10-5

239 Chapter 10 Query Geeratio ad Processig 3. At the Query Descriptio field, eter a query descriptio, ad press <RETURN>. You ca retrieve a existig query to edit or create a ew oe. a. To retrieve a existig query, eter a complete or partial query ame i the Query Name field ad/or a complete or partial query descriptio i the Query Descriptio field, ad press <RETURN>. You see a lookup box that lists all matchig etries. To see a lookup box that lists all queries defied i the curret database, leave the Query Name ad Query Descriptio fields blak ad press the <SEARCH CURRENT TABLE> key. Use the cursor positioig keys to avigate withi the lookup box, ad press <RETURN> to select a etry. b. To create a ew query, eter a ew query ame (it must ot match the ame of ay existig query) i the Query Name field, optioally eter a query descriptio i the Query Descriptio field, ad press <RETURN>. You see the IS THIS A NEW QUERY? dialog box, as show below:. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄQuery DefiitioÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ ³ ³ ³ ³ Query Name patiets1 Descriptio Average Age By Ward, Sex ³ ³ ³ ³ ³ ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ IS THIS A NEW QUERY? ³ ³ ³ ³ ³ ³ ³ ³ < Yes > < No > ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Query Defiitio Selectig Press <Help> For Help Here, you may create a ew query by pressig <RETURN> o the <Yes> actio field Ope M/SQL Developer Guide

240 Usig the Query Geerator Whe you have etered a query ame (either ew or existig), the Query Defiitio widow fills out with the full template for defiig a SELECT statemet query:. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄQuery DefiitioÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Display Fields from Tables Advaced Features Compile & Ru ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ Query Name patiets1 Descriptio Average Age By Ward, Sex ³ ³ ³ ³ Select ³ ³ (00/1) ³ ³ ³ ³ From (oe table ame per lie)³ ³ ³ ³ ³ ³ Where ³ ³ (00/1) ³ ³ ³ ³ Order By Group By ³ ³ (00/1) (00/1) ³ ³ ³ ³ Havig ³ ³ (01/1) ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Query Defiitio Press <Help> For Help The table below lists ad describes the fields located o the Query Defiitio widow s SELECT statemet template: Table 10-3: Fields o Query Defiitio Widow Field Query Name Query Descriptio SELECT Descriptio This is the ame that idetifies the query. The ame may rage from 1 to 30 characters i legth ad may iclude ay alphaumeric characters, icludig the uderscore character. The ame must always begi with a alphabetic character. This is a required field. Here you may eter a brief descriptio for the query. The descriptio may be up to 60 characters i legth ad may iclude ay alphaumeric characters, icludig uderscores ad blak spaces. Here you may eter oe or more expressios, separated by commas, that specify the data colums to appear i the query output. The expressios may cotai field ames, aggregate fuctios, ad the IterSystems SQL extesio keywords %FOREACH, %AFTERHAV- ING, ad DISTINCT BY. (For more iformatio o these ad other SQL extesios, see Chapter 9, Ope M/SQL Implemetatio of SQL). The SELECT clause may also cotai subqueries. All field ames specified i the SELECT clause must origiate i a base table or view that is listed i the From clause. Each lie of this field scrolls to right ad ca accommodate up to 250 characters. If you cotiue the expressio oto the ext lie, you must ed the previous lie with a comma. Ope M/SQL Developer Guide 10-7

241 Chapter 10 Query Geeratio ad Processig Table 10-3: Fields o Query Defiitio Widow (Cotiued) Field FROM WHERE ORDER BY GROUP BY Descriptio Here you may specify the data source of the query. You may specify oe or more base tables or views as the data source, or you may specify oe query-based view. You may select oly base tables/views that are defied i the curret database. To see a list of all base tables/views defied i the curret database, you may press the <LIST CHOICES> key. Each ew base table or view ame you eter must occupy a separate lie. After a base table ame you may optioally specify a alias for the base table, separated by a space from the base table ame. Here you may eter oe or more coditioal expressio(s) that qualifies or disqualifies specific rows from the query output. You must lik multiple expressios together by AND or OR. Use this clause to restrict the query's data capture to very specific sets of iformatio. The WHERE clause accepts all compariso operators ad the BETWEEN, LIKE, NULL, IN, EXISTS, FOR ALL, ad FOR SOME predicates, but may ot cotai ay aggregate fuctios. You may also embed subqueries i the WHERE clause. Here you may specify oe or more field(s) or expressio(s), separated by commas, to desigate the sort order for rows i the query output. You may specify field(s) ad/or expressio(s) that do ot appear i the SELECT clause, as well as those that do. You may referece a field either by ame or by its ordial umber i the SELECT clause, if it appears there. If you specify multiple items, each successive item has lesser precedece i the sort evaluatio. Sorts may be performed i ascedig (the default) or descedig order, as specified Note: If you eter oe ORDER BY field ame per lie, it is ot ecessary to eter a comma at the ed of each lie. Here you may specify oe or more fields, separated by commas, that will be used to break up the fial query output ito groups. For each distict group, the query will retur oly oe row. For example, if you group by the field sex, ad sex cotais oly the two values Male ad Female, the query will discer two groups ad output oly oe row for each of them. I such case, a ame field listed i the SELECT clause is redered ot meaigful, as the query will output oly oe ame correspodig to each value of sex. The GROUP BY clause is coceptually similar to the Ope M/SQL extesio %FOREACH, but GROUP BY operates o a etire query, while %FOREACH allows selectio of aggregates o sub-populatios without restrictig the etire query populatio. Note: If you eter oe GROUP BY field ame per lie, it is ot ecessary to eter a comma at the ed of each lie Ope M/SQL Developer Guide

242 Usig the Query Geerator Table 10-3: Fields o Query Defiitio Widow (Cotiued) Field HAVING Descriptio Here you may eter a coditioal expressio that determies whether or ot a give group should be icluded i the query output. This field eables you to set restrictios o data groups. The HAVING clause operates o groups of data i much the same fashio as the WHERE clause operates o idividual rows of data. By specifyig the HAVING clause, you ca effectively isolate very specific sets of iformatio. Ulike the WHERE clause, the HAVING clause may cotai aggregate fuctios. 4. Eter the appropriate text ito the fields of the Query Defiitio template to defie a SELECT-statemet query that queries the database for the iformatio you are seekig. 5. Whe you have fiished defiig your query, press the <PROCEED> key to save your query defiitio ad exit the Query Defiitio template. You retur to a blak Query Defiitio lookup widow, where you may create or select aother query. 6. To retur to the SQL meu, press the <PREVIOUS> key. Example Below is a sample query defied i the Query Defiitio template:. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄQuery DefiitioÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Display Fields from Tables Advaced Features Compile & Ru ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ Query Name patiets1 Descriptio Average Age By Ward, Sex ³ ³ ³ ³ Select ward,sex,avg(age) ³ ³ (00/1) ³ ³ ³ ³ From Patiets (oe table ame per lie)³ ³ ³ ³ ³ ³ Where ³ ³ (00/1) ³ ³ ³ ³ Order By ward,sex Group By ward,sex ³ ³ (00/1) (00/1) ³ ³ ³ ³ Havig AVG(age) < 62 ³ ³ (01/1) ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Query Defiitio Press <Help> For Help Ope M/SQL Developer Guide 10-9

243 Chapter 10 Query Geeratio ad Processig This query cosiders all patiets i the Patiets table. It yields groups that correspod to each sex withi each ward where the average age of that group is less tha 62. It orders the output rows first by ward, the by sex. The query show i the Query Defiitio template above ca be writte out as follows: SELECT ward,sex,avg(age) FROM Patiets GROUP BY ward,sex ORDER BY ward,sex HAVING AVG(age) < 62 The followig table shows a sample output for this query. Each colum represets a SELECT clause expressio, ad each row represets a distict GROUP BY row: Table 10-4: Sample Query Output Ward Sex Average Age 1 F M F M F F M This example omits wards 3 ad 5 because both sex groups withi each ward fail to satisfy the coditio i the HAVING clause, i.e. the average age of each group is greater tha 62. The table omits the row correspodig to Male i ward 4 for the same reaso. Note ANSI-Stadard SQL does ot support colum title cotrol ad other output formattig features. Therefore, query output will ot appear as eatly formatted as show i the above example. To query the database ad produce eatly formatted reports, you should the Ope M/SQL M/PACT report writer tool Ope M/SQL Developer Guide

244 Usig the Query Geerator Query Defiitio Meu Bar Located at the top of the Query Defiitio template is the Query Defiitio meu bar, which cotais optios that provide additioal fuctioality to the Query Geerator eviromet. To access the Query Defiitio meu bar, press the <ENHANCE> key twice from withi the Query Defiitio mai widow. To select a optio from the Query Defiitio meu bar, use the <RIGHT ARROW> ad <LEFT ARROW> keys to positio the select bar o a desired optio ad press <RETURN>, or type the highlighted letter i the ame of a desired optio. The table below lists ad describes the three optios o the Query Defiitio meu bar: Table 10-5: Optios o Query Defiitio Meu Bar Name Display Fields from Tables Advaced Features Compile & Ru Descriptio Select this optio to see a list that displays all fields located o all base tables ad views specified i the FROM clause of the query Select this optio to access the Query Defiitio Advaced Features widow, which displays various iformatio about the query ad allows you to defie parameters for pritig the query i ASCII-delimited output format. Select this optio to compile ad ru the query Displayig Fields From Tables ad Views You may use the Display Fields from Tables optio o the Query Defiitio meu bar to see a list of all fields located o all base tables ad views specified i the query s FROM clause. The list displays all fields located o the table/view specified o the first lie of the FROM clause followed by all fields o the table/view specified o the secod lie of the FROM clause, ad so o. This list may help you idetify which fields are available for use i other clauses of the query. The list is for iformatioal purposes oly; you caot select items from it. Ope M/SQL Developer Guide 10-11

245 Chapter 10 Query Geeratio ad Processig Procedure To display a list of all fields located o the base tables/views specified i the FROM clause: 1. From the Query Defiitio mai widow, press the <ENHANCE> key twice to access the Query Defiitio meu bar. 2. From the Query Defiitio meu bar, press <RETURN> to select the Display Fields from Tables optio. You see a display similar to the followig: Field Name Descriptio Relatio ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄ ³ address1 Home Address Patiets ³ ³ address2 Work Address Patiets ³ ³ admit Admittace Date Patiets ³ ³ age Age Patiets ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄmoreÙ 3. Use the <UP ARROW> ad <DOWN ARROW> keys to scroll up or dow i order to see more field ames. The tag more appears i the bottom right-had corer of the display box to idicate the presece of more fields below ad i the upper right-had corer of the display box to idicate the presece of more fields above. Note: This optio does ot list fields from desigated tables that are poited to by Desigative Referece fields withi the listed base tables. You may, however, referece such fields withi the query usig proper joi (arrow) sytax. For more iformatio o how to do this, refer to the sectio etitled Implicit Jois i Chapter 9, Ope M/SQL Implemetatio of SQL. 4. Press the <PREVIOUS> key to retur to the Query Defiitio meu bar Ope M/SQL Developer Guide

246 Usig the Query Geerator Query Defiitio Advaced Features You may use the Advaced Features optio o the Query Defiitio meu bar to access the Query Defiitio Advaced Features widow. The Query Defiitio Advaced Features widow displays the followig iformatio about your query: Ower (this value is read-oly) Ru-Time Measure (this value is read-oly) Routie Name (this value is modifiable) The Query Defiitio Advaced Features widow also lets you defie parameters for pritig your query i ASCII-delimited output format. Ope M/SQL supports the output of queries to ASCII-Delimited text files, which are formatted for import ito may PC software packages. Procedure To access ad use the Query Defiitio Advaced Features widow: 1. From the Query Defiitio mai widow, press the <ENHANCE> key twice to access the Query Defiitio meu bar. 2. From the Query Defiitio meu bar, type a to select the Advaced Features optio. You see the Query Defiitio Advaced Features widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄQuery DefiitioÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Display Fields from Tables Advaced Features Compile & Ru ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ Query Name patiets1 DescÚÄÄÄÄÄÄÄÄÄÄÄAdvaced FeaturesÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ ³ Select ward,sex,avg(age) ³ Query Ower Ru Time Measure ³ ³ (00/1) ³ _SYSTEM 1195 ³ ³ ³ ³ ³ From Patiets ³ Routie Name mq9 ³ ³ ³ ³ ³ ³ ASCII-Delimited Files Oly? No ³ ³ Where ³ ³ ³ (00/1) ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ ³Order By ward,sex ³ Quote Character ³ ³ (00/1) ³ ³ ³ ³ Ed Of Field Delimiter, ³ ³ Havig AVG(age) < 62 ³ ³ ³ (00/1) ³ Ed Of Record Delimiter 13,10 ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Advaced Features Press <Help> For Help Ope M/SQL Developer Guide 10-13

247 Chapter 10 Query Geeratio ad Processig The followig table lists ad describes the fields located o the Query Defiitio Advaced Features widow: Table 10-6: Fields o Query Defiitio Advaced Features Widow Field Query Ower Ru Time Measure Routie Name ASCII-Delimited Files Oly? Quote Character Descriptio This field shows the UserName of the user who created (ad therefore ows) the query. You caot edit this field. This field provides a relative measure of the system cost associated with ruig the query. The umber show is based o the complexity of both the query ad the database. Typically, the larger the umber, the more slowly the query executes. Ope M/SQL calculates the ru-time measure whe you compile the query ad recalculates it every time you recompile. This value is read-oly ad caot be altered i ay way. This field displays the prefix for all routie ames geerated by the query. Ope M/SQL assigs a default prefix, such as mq9 i the above example. You may optioally override the default prefix by replacig it with a strig of 1 to 7 alphaumeric characters (first character must be alphabetic) to serve as the override prefix. All routies geerated for the query cosist of this prefix followed by a sigle character (1-9, the A-Z, the a-z), which is appeded by the compiler. Specifyig your ow routie prefix may help you to remember it whe attemptig to call the query directly from M usig the query call sytax, as described i the sectio of this chapter etitled Ruig a Query from M Code o page Here you may specify ASCII-Delimited as the oly allowable output format for the query, i.e. o prited format is allowed. Aswer Yes to specify ASCII-Delimited as the oly allowable output format for the query. This eables you to dowload a ulimited umber of fields to the ASCII-Delimited file. Aswer No to ot restrict output of the query to ASCII-delimited format oly. If you aswer No, you ca still sed query output to a ASCII-Delimited file, but the umber of fields you may select is limited to the umber of fields supported by a stadard prited query. No is the default respose. For more iformatio o sedig query output to ASCII-delimited files, see the sectio of this chapter etitled ASCII-Delimited Output for Queries o page Here you may specify the character(s) used to eclose field values whe usig ASCII-delimited output format. You may specify ay text of te characters or less. The default is the double quote character ( ) Ope M/SQL Developer Guide

248 Usig the Query Geerator Table 10-6: Fields o Query Defiitio Advaced Features Widow Field Ed of Field Delimiter Ed of Record Delimiter Descriptio Here you may specify the character(s) used to act as the separator betwee field values whe usig ASCII-delimited output format. You may specify ay text of te characters or less. The default is the comma character (,). Here you may specify the character(s) used to act as the separator betwee records (rows) whe usig ASCII-delimited output format. You may specify a list of ASCII values (umbers) separated by commas. The default value is the ASCII sequece 13,10 (same as <CR><LF>). 3. At the Routie Name field, you may optioally replace the default routie prefix assiged to your query by Ope M/SQL with a override routie prefix. The routie prefix may be 1 to 7 characters i legth ad may iclude ay alphaumeric characters, except for the first character, which must be alphabetic. 4. At the ASCII-Delimited Files Oly? field, aswer Yes or No to idicate whether or ot you wat to restrict the query to ASCII-Delimited output format oly. No is the default respose. 5. At the Quote Character field, specify the character(s) used to eclose field values whe usig ASCII-delimited output format. The default is the double quote character ( ). 6. At the Ed of Field Delimiter field, specify the character(s) used to act as the separator betwee field values whe usig ASCII-delimited output format. The default is the comma character (,). 7. At the Ed of Record Delimiter Field, specify the character(s) used to act as the separator betwee records (rows) whe usig ASCII-delimited output format. The default value is the ASCII sequece 13,10 (same as <CR><LF>). 8. Whe you complete your work i the Query Defiitio Advaced Features widow, press the <PROCEED> key to save your defiitios ad exit. Ope M/SQL Developer Guide 10-15

249 Chapter 10 Query Geeratio ad Processig Compile ad Ru the Query You may use the Compile & Ru optio o the Query Defiitio meu bar to compile ad ru your query. Whe you select this optio, you see the followig prompt at the bottom of the scree: Parse, Optimize ad Compile i the Backgroud? No Press <RETURN> at this prompt to compile the query i the foregroud. Compilig i the foregroud meas that you see compiler messages as they scroll oto the scree. It also meas that Ope M/SQL automatically propmts you to ru the query after it has bee compiled. To compile the query i the backgroud, delete the default No respose, replace it with Yes, ad press <RETURN>. If you elect to compile the query i the backgroud, you retur to the Query Defiitio template ad may cotiue workig while Ope M/SQL compiles the query udereath. Ope M/SQL does ot prompt you to ru the query after it has bee compiled. Note IterSystems recommeds that you always compile i the foregroud. If you elect to compile the query i the foregroud, a series of iformatioal messages will scroll oto the scree as the Compiler moves through its sequece of operatios. These messages iclude a list of the ames of the M routies ito which the query is beig compiled. Whe the compilatio is complete, the Compiler will briefly display the message...done. After compilig the query (i the foregroud), Ope M/SQL displays the device selectio script to request iformatio about where to sed the query output. You may press the <PREVIOUS> key to back out ad ot ru the query at this time, or you may provide device selectio iformatio ad proceed with ruig the query. For more iformatio o ruig queries, see the sectio of this chapter etitled Ruig Queries o page After compilig the query (if you back out before ruig it) or after ruig the query, you retur to the Query Defiitio template Ope M/SQL Developer Guide

250 Usig the Iteractive Query Editor Usig the Iteractive Query Editor Query Types The Iteractive Query Editor provides a alterative, less restrictive way to specify SQL queries. Ulike the Query Geerator, the Iteractive Query Editor does ot limit you to SELECT-oly queries or does it place you withi a prescribed template for query defiitio. Rather, it provides a free-form SQL editor eviromet (similar to the Full Scree Editor) where you ca create ad ru ay sytactically valid SQL query. Like the Query Geerator, the Query Editor lets you save query defiitios for future reuse ad save a compiled versio of the query to be ru at a later time. The table below lists ad describes the types of SQL queries supported by Ope M/SQL. You may issue queries of ay of these statemet types via the Iteractive Query Editor: Table 10-7: Query Types Supported By Ope M/SQL Statemet Type ALTER VIEW %CHECKPRIV CREATE VIEW DELETE DROP VIEW GRANT INSERT REVOKE Descriptio Alters the defiitio of a query-based view. ALTER VIEW queries essetially delete ad recreate a existig query-based view, while retaiig the same view ame ad iteral view umber. This query type is a IterSystems SQL extesio. Allows a user to check whether or ot s/he holds a specified privilege o a specified Ope M/SQL object. If the specified privilege exists, the query returs a SQLCODE value of 0 (success). If the privilege does ot exist, the query returs a SQLCODE value of 100 (failure). For more iformatio o %CHECKPRIV, see Chapter 9, Ope M/SQL Implemetatio of SQL. Creates a query-based view. Deletes rows from a base table. Note: DELETE operates o the etire table, uless a WHERE clause is specified to restrict the scope of the delete. Deletes a query-based view. Grats access privileges o specified objects (base table, view, form, meu object, meu, report, query) to Ope M/SQL users with a optio to allow the user to grat access to other users. Iserts ew rows ito a base table. Revokes access privileges o specified objects (base table, view, form, meu object, meu, report, query) from Ope M/SQL users. Oly the grator of privileges has the authority to revoke those privileges. Ope M/SQL Developer Guide 10-17

251 Chapter 10 Query Geeratio ad Processig Table 10-7: Query Types Supported By Ope M/SQL (Cotiued) Statemet Type SELECT UPDATE Descriptio Retrieves a row or multiple rows from a table ad outputs them i stadard tabular format. There are two types of SELECT-statemet queries: No-cursor-based queries (retrieve a sigle row of data) Cursor-based queries (retrieve multiple rows of data) The Query Editor automatically coverts the sytax of your SELECT statemet ito a cursor-based SELECT (with all the required SQL DECLARE, OPEN, FETCH, ad CLOSE statemets). Note: You may also use the Query Geerator to create cursorbased SELECT statemet queries. Updates colum values for oe or more existig base table rows. Note: UPDATE operates o the etire base table, uless a WHERE clause is specified to restrict the scope of the UPDATE. Note With the exceptio of %CHECKPRIV, Ope M/SQL implemets all of these query statemet types accordig to ANSI-Stadard SQL. For iformatio about Ope M/SQL-specific extesios ad limitatios to the sytax for these statemets, see Chapter 9, Ope M/SQL Implemetatio of SQL. Creatig a Query i the Iteractive Query Editor Usig the Iteractive Query Editor you may create queries of ay statemet type supported by Ope M/SQL. You must give each query you create a query defiitio ame for idetificatio purposes. Each query defiitio may cosist of oly oe SQL statemet. Procedure To create a query usig the Iteractive Query Editor: 1. From the SQL meu, select the Iteractive SQL Queries optio Ope M/SQL Developer Guide

252 Usig the Iteractive Query Editor You see the Query Editor lookup widow, as show below: ÚÄÄÄÄSelect Iteractive QueryÄÄÄÄ ³ ³ ³ Query Name ³ ³ ³ ³ ³ ³ Descriptio ³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Select Query Selectig Press <Help> For Help 2. At the Query Name field i the Query Editor lookup widow, eter a query ame, ad press <RETURN>. 3. At the Descriptio field, you may optioally eter a brief descriptio for the query, ad press <RETURN>. You ca retrieve a existig query to edit or create a ew oe. a. To retrieve a existig query, eter a complete or partial query ame i the Query Name field ad/or a complete or partial query descriptio i the Descriptio field, ad press <RETURN>. You see a lookup box that lists all matchig etries. To see a lookup box that lists all queries defied i the curret database, leave the Query Name ad Descriptio fields blak ad press the <SEARCH CURRENT TABLE> key. Use the cursor positioig keys to avigate withi the lookup box, ad press <RETURN> to select a etry. b. To create a ew query, eter a ew query ame (it must ot match the ame of ay existig query) i the Query Name field, optioally eter a query descriptio i the Descriptio field, ad press <RETURN>. Ope M/SQL Developer Guide 10-19

253 Chapter 10 Query Geeratio ad Processig You see the IS THIS A NEW QUERY? dialog box, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ IS THIS A NEW QUERY? ³ ³ ³ ³ < Yes > < No > ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ³ Descriptio ³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Select Query Selectig Press <Help> For Help Here, you may create a ew query by pressig <RETURN> o the <Yes> actio field. Whe you have etered a query ame (either ew or existig), you see the Select Query widow, as show below:: ÚÄÄÄÄÄÄÄÄÄÄSelect QueryÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Query Name ³ ³ tstq1 ³ ³ ³ ³ Descriptio ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Select Query Selectig Press <Help> For Help Ope M/SQL Developer Guide

254 Usig the Iteractive Query Editor The table below lists ad describes the fields located o the Select Query widow: Table 10-8: Fields o Select Query Widow Field Query Name Descriptio Descriptio This is the ame that idetifies the query. The ame may rage from 1 to 30 characters i legth ad may iclude ay alphaumeric characters, icludig the uderscore character. The ame must always begi with a alphabetic character. This is a required field. Here you may eter a brief descriptio for the query. The descriptio may be up to 60 characters i legth ad may iclude ay alphaumeric characters, icludig uderscores ad blak spaces. 4. Press the <PROCEED> key to ivoke the Iteractive Query Editor. The Iteractive Query Editor appears as a blak scree, ito which you may type your SQL statemet.: INTERACTIVE SQL Help Save Compile Advaced & Ru Optios QUERY::tstq1 At the bottom of the Query Editor Scree is a status lie. O the far right, the status lie displays the ame of the query you are creatig. Below the status lie is the Query Editor horizotal optios meu. See below for more iformatio about the optios o this meu. 5. Type i your SQL code without ay preprocessor sytax. SQL commads ad idetifiers are ot case-sesitive, meaig that you may eter them i upper or lower case, or i a mixture of both. You may eter oly oe SQL statemet per query defiitio. Ope M/SQL Developer Guide 10-21

255 Chapter 10 Query Geeratio ad Processig The example below shows a UPDATE-statemet query called tstq1 etered via the Query Editor: UPDATE %NOCHECK patiets set age_status= Seior where age > 64 INTERACTIVE SQL Help Save Compile Advaced & Ru Optios Note: You may type the query all o oe lie, or break it up ito ay umber of lies. 6. To save your query defiitio, press the <GO TO BOTTOM MENU> key to access the Query Editor horizotal optios meu, ad select the Save optio from this meu. 7. To exit the curret query defiitio, press the <PREVIOUS> key. Be sure to save the query defiitio before exitig. If there are usaved chages i your query defiitio whe you attempt to exit, the Query Editor displays the followig prompt: Quit Without Savig Chages? Type Y (to quit) or N (to retur to the Editor), ad press <RETURN>. QUERY::tstq1 Whe you exit the Query Editor, you retur to the Query Editor lookup widow, where you may create or retrieve aother query defiitio. 8. From the Query Editor lookup widow, press the <PREVIOUS> key agai to retur to the SQL meu Ope M/SQL Developer Guide

256 Usig the Iteractive Query Editor Editig Commads The table below lists ad describes the editig capabilities supported by the Iteractive Query Editor: Table 10-9: Editig Capabilities Supported by the Iteractive Query Editor Fuctio Descriptio Keystrokes to Use Select Selects a block of text for cuttig ad pastig. Press the <LIST CHOICES> key, or <CTRL-E> <S> Cut Deletes a block of selected text. Press the <REMOVE> key, or <CTRL-E> <C> Paste Pastes a block of selected text at the poit where the cursor is located. Press the <INSERT> key, or <CTRL-E> <C> Query Editor Horizotal Optios Meu Located at the bottom of the Query Editor display scree is the Query Editor horizotal optios meu, which cotais optios that provide additioal fuctioality to the Query Editor eviromet. To access the Query Editor horizotal optios meu, press the <GO TO BOTTOM MENU KEY> key from withi the Query Editor. To select a optio from the Query Editor horizotal optios meu, use the <RIGHT ARROW> ad <LEFT ARROW> keys to positio the select bar o a desired optio ad press <RETURN>, or type the first letter i the ame of a desired optio to positio the select bar, ad press <RETURN>. The table below lists ad describes the optios o the Query Editor horizotal optios meu: Table 10-10: Optios o Query Editor Horizotal Optios Meu Optios Help Save Compile & Ru Advaced Optios Descriptio Select this optio to ivoke a submeu of o-lie help optios Select this optio to save your query defiitio i its curret form. After savig, this optio returs you to the Query Editor to cotiue workig. Select this optio to compile ad ru the query. Select this optio to access the Query Defiitio Advaced Features widow, which displays various iformatio about the query ad allows you to defie parameters for pritig the query i ASCII-delimited output format. Note: Output formattig is applicable to SELECT-statemet queries oly. Ope M/SQL Developer Guide 10-23

257 Chapter 10 Query Geeratio ad Processig Usig O-lie Help The Iteractive Query Editor provides a Help submeu for accessig o-lie help o ay of the followig topics: Procedure Geeral Help SQL Sytax Select Isert Update Delete Grat & Revoke %CHECKPRIV To access the Help submeu: 1. From the Query Editor scree, press the <GO TO BOTTOM MENU> key. The Help submeu replaces the top-level Query Editor horizotal optios meu at the bottom of the scree, as show below: UPDATE %NOCHECK patiets set age_status= Seior where age > 64 INTERACTIVE SQL 2. To select a optio from the Help submeu, use the <RIGHT ARROW> ad <LEFT ARROW> keys to positio the select bar o a desired optio ad press <RETURN>, or type the first letter i the ame of a desired optio to positio the select bar, ad press <RETURN>. This displays a series of o-lie help screes that provide detailed iformatio o the selected topic. 3. To exit a o-lie help scree, press the <PREVIOUS> key. QUERY::tstq1 Geeral SQL Select Isert Update Delete Grat & %CHECKPRIV Help Sytax Revoke Ope M/SQL Developer Guide

258 Usig the Iteractive Query Editor Query Editor Advaced Optios You may use the Advaced Optios optio o the Query Editor horizotal optios meu to access the Query Editor Advaced Optios widow. The Query Editor Advaced Optios widow displays the followig iformatio about your query: Ower (this value is read-oly) Ru-Time Measure (this value is read-oly) Routie Name (this value is modifiable) The Query Editor Advaced Optios widow also lets you defie parameters for pritig your query i ASCII-delimited output format. Ope M/SQL supports the output of SELECT-statemet queries to ASCII- Delimited text files, which are formatted for import ito may PC software packages. Procedure To access ad use the Query Editor Advaced Optios widow: 1. From the Query Editor scree, press the <GO TO BOTTOM MENU> key to access the Query Editor horizotal optios meu. 2. From the Query Editor horizotal optios meu, select the Advaced Optios optio. You see the Query Editor Advaced Optios widow, as show below. UPDATE %NOCHECK patiets set age_status= Seior where age > 64 ÚÄÄÄÄÄÄÄÄÄÄÄAdvaced OptiosÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Query Ower _SYSTEM ³ ³ ³ ³ Routie Name mq11 ³ ³ ³ ³ ASCII-Delimited Files Oly? No ³ ³ ³ ³ Quote Character ³ ³ ³ ³ Ed Of Field Delimiter, ³ ³ ³ ³ Ed Of Record Delimiter 13,10 ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Advaced Features Press <Help> For Help Ope M/SQL Developer Guide 10-25

259 Chapter 10 Query Geeratio ad Processig The followig table lists ad describes the fields located o the Query Editor Advaced Optios widow: Table 10-11: Fields o Query Editor Advaced Optios Widow Field Query Ower Ru Time Measure Routie Name ASCII-Delimited Files Oly? Quote Character Descriptio This field shows the UserName of the user who created (ad therefore ows) the query. You caot edit this field. This field provides a relative measure of the system cost associated with ruig the query. The umber show is based o the complexity of both the query ad the database. Typically, the larger the umber, the more slowly the query executes. Ope M/SQL calculates the ru-time measure whe you compile the query ad recalculates it every time you recompile. This value is read-oly ad caot be altered i ay way. This field displays the prefix for all routie ames geerated by the query. Ope M/SQL assigs a default prefix, such as mq11 i the above example. You may optioally override the default prefix by replacig it with a strig of 1 to 7 alphaumeric characters (first character must be alphabetic) to serve as the override prefix. All routies geerated for the query cosist of this prefix followed by a sigle character (1-9, the A-Z, the a-z), which is appeded by the compiler. Specifyig your ow routie prefix may help you to remember it whe attemptig to call the query directly from M usig the query call sytax, as described i the sectio of this chapter etitled Ruig a Query from M Code o page Here you may specify ASCII-Delimited as the oly allowable output format for the query, i.e. o prited format is allowed. Aswer Yes to specify ASCII-Delimited as the oly allowable output format for the query. This eables you to dowload a ulimited umber of fields to the ASCII-Delimited file. Aswer No to ot restrict output of the query to ASCII-delimited format oly. If you aswer No, you ca still sed query output to a ASCII-Delimited file, but the umber of fields you may select is limited to the umber of fields supported by a stadard prited query. No is the default respose. Note: Output formattig is applicable to SELECT-statemet queries oly. For more iformatio o sedig query output to ASCII-delimited files, see the sectio of this chapter etitled ASCII-Delimited Output for Queries o page Here you may specify the character(s) used to eclose field values whe usig ASCII-delimited output format. You may specify ay text of te characters or less. The default is the double quote character ( ) Ope M/SQL Developer Guide

260 Usig the Iteractive Query Editor Table 10-11: Fields o Query Editor Advaced Optios Widow (Cotiued) Field Ed of Field Delimiter Ed of Record Delimiter Descriptio Here you may specify the character(s) used to act as the separator betwee field values whe usig ASCII-delimited output format. You may specify ay text of te characters or less. The default is the comma character (,). Here you may specify the character(s) used to act as the separator betwee records (rows) whe usig ASCII-delimited output format. You may specify a list of ASCII values (umbers) separated by commas. The default value is the ASCII sequece 13,10 (same as <CR><LF>). 3. At the Routie Name field, you may optioally replace the default routie prefix assiged to your query by Ope M/SQL with a override routie prefix. The routie prefix may be 1 to 7 characters i legth ad may iclude ay alphaumeric characters, except for the first character, which must be alphabetic. 4. At the ASCII-Delimited Files Oly? field, aswer Yes or No to idicate whether or ot you wat to restrict the query to ASCII-Delimited output format oly. No is the default respose. 5. At the Quote Character field, specify the character(s) used to eclose field values whe usig ASCII-delimited output format. The default is the double quote character ( ). 6. At the Ed of Field Delimiter field, specify the character(s) used to act as the separator betwee field values whe usig ASCII-delimited output format. The default is the comma character (,). 7. At the Ed of Record Delimiter Field, specify the character(s) used to act as the separator betwee records (rows) whe usig ASCII-delimited output format. The default value is the ASCII sequece 13,10 (same as <CR><LF>). 8. Whe you complete your work i the Query Editor Advaced Optios widow, press the <PROCEED> key to save your defiitios ad exit. Ope M/SQL Developer Guide 10-27

261 Chapter 10 Query Geeratio ad Processig Compile ad Ru the Query You may use the Compile & Ru optio o the Query Defiitio meu bar to compile ad ru your query. Whe you select this optio, Ope M/SQL automatically (re)compiles the query. As the Compiler moves through its sequece of operatios, iformatioal messages will scroll oto the scree. These messages iclude a list of the ames of the M routies ito which the query is beig compiled. Whe the compilatio is complete, the Compiler will briefly display the message...done. After compilig the query, Ope M/SQL rus it. INSERT, UPDATE, DELETE, GRANT, REVOKE, CREATE VIEW, ALTER VIEW, ad DROP VIEW statemet queries produce o examiable output. Whe you ru a query of ay of these types, Ope M/SQL returs a success message (if the query has completed successfully) or a error message (if the query has failed) to your scree, for example: tstq1 Query Successfully Completed %CHECKPRIV queries retur a message to the scree that idicates the existece/oexistece of the queried privilege, for example: The Requested Privilege Exists SELECT-statemet queries geerate examiable output that must be directed to a specified destiatio. Ope M/SQL displays a device selectio script to request iformatio about where to sed the query output. You may press the <PREVIOUS> key to back out ad ot ru the query at this time, or you may provide device selectio iformatio ad proceed with ruig the query. For more iformatio o ruig SELECT-statemet queries (output device selectio ad output formattig), see the sectio of this chapter etitled Ruig Queries o page After compilig the query (if you back out before ruig it) or after ruig the query, you retur to the Query Editor scree Ope M/SQL Developer Guide

262 Ruig Queries Ruig Queries You ca ru a query from ay of three locatios: From withi its defiitio eviromet (Query Geerator or Query Editor) Usig the Ru Existig Queries utility o the SQL meu From M code Privileges Required to Ru Queries I order to ru ay query, you must hold SELECT privileges o the query defiitio. Furthermore, i order to ru certai query types you must hold certai privileges o the base tables amed i the query, as described i the table below: Table 10-12: Privileges Required to Ru Query Types Query Type SELECT INSERT UPDATE DELETE Privileges Required Must have SELECT privileges o each of the base tables amed i the query. Must have INSERT privileges o each of the base tables amed i the query. Must have %ALTER privileges o each of the base tables amed i the query. Must have DELETE privileges o each of the base tables amed i the query. Ruig a Query From its Defiitio Eviromet You ca ru queries directly from the Query Geerator or the Query Editor. Procedure To ru a query from withi the Query Geerator: 1. From the Query Defiitio template, press the <ENHANCE> key twice to access the Query Defiitio meu bar. 2. From the Query Defiitio meu bar, type c to select the Compile & Ru optio. Ope M/SQL automatically (re)compiles the query, ad the displays a device selectio script to request iformatio about where to sed the query output (see below for a discussio of the Device Selectio widow). Remember that all queries defied usig the Query Geerator are SELECT-statemet queries, ad therefore produce examiable output. Ope M/SQL Developer Guide 10-29

263 Chapter 10 Query Geeratio ad Processig Procedure To ru a query from withi the Query Editor: 1. From the Query Editor scree, press the <GO TO BOTTOM MENU> key to access the horizotal optios meu. 2. Select the Compile & Ru optio from the Horizotal Optios meu ad press <RETURN>. Ope M/SQL automatically (re)compiles the query ad the rus it. If it is a UPDATE, INSERT, DELETE, GRANT, REVOKE, %CHECK- PRIV, CREATE VIEW, ALTER VIEW, or DROP VIEW statemet query, the query returs a success/fail message to the scree whe it fiishes. If it is a SELECT statemet query, Ope M/SQL displays a device selectio script to request iformatio about where to sed the query output (see below for a discussio of the Device Selectio widow). Usig the Ru Existig Queries Utility You ca use the Ru Existig Queries utility to select ay query defied via the Query Geerator or Query Editor ad ru it. Procedure To use the Ru Existig Queries utility: 1. From the SQL meu, select the Ru Existig Queries optio. You see the Ru Query lookup widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄRu QueryÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Query Name Descriptio ³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Ru Query Selectig Press <Help> For Help 2. To select a query, eter a complete or partial query ame i the Query Name field ad/or a complete or partial query descriptio i the Descriptio field, ad press <RETURN> Ope M/SQL Developer Guide

264 Ruig Queries You see a lookup box that lists all matchig etries. To see a lookup box that lists all queries defied i the curret database, leave the Query Name ad Descriptio fields blak ad press the <SEARCH CURRENT TABLE> key. 3. Use the <UP ARROW> ad <DOWN ARROW> keys to avigate withi the lookup box, ad press <RETURN> to select a etry. 4. Whe your have selected a query, press the <PROCEED> key to execute it. If the query has ot bee recompiled sice chages were last saved, Ope M/SQL will automatically recompile the query before executig it. Ruig a Query from M Code It is also possible to ru a query by callig it directly from M code. To do this, you use the M query call sytax. You may use this etry poit to ivoke a query i ay of the followig ways: From a trigger item of actio type M Code From meu optio of actio type M code From withi a M routie From the M programmer prompt The M query call sytax is as follows: do query^%msql(queryame,user,device,format,batchsw) The followig table lists ad describes the parameters associated with the M query call sytax: Table 10-13: Parameters Associated with M Query Call Sytax Parameter queryame user device Meaig The ame of the query you wat to ru. This is a required parameter. This is a moot parameter; Ope M/SQL o loger uses this iformatio. Eter the ull idicator ( ) to skip this parameter. The optioal ame of a output device. Ope M/SQL Developer Guide 10-31

265 Chapter 10 Query Geeratio ad Processig Table 10-13: Parameters Associated with M Query Call Sytax (Cotiued) Parameter format batchsw Meaig The optioal ame of a device format. A optioal flag that specifies whether to ru the query i the foregroud or i the backgroud. Set to 1 display the query results i the backgroud. Set to 0 to display the results i the foregroud. 0 is the default settig Ope M/SQL Developer Guide

266 Ruig Queries Selectig a Output Device Whe you ru a SELECT-statemet query, Ope M/SQL ivokes a device selectio script to request iformatio about where to sed the query output. You must specify a output device as well as prit format parameters for the device. The appearace of device selectio script differs across the various M systems supported by Ope M/SQL. Whe you ru Ope M/SQL o top of a DSM, DTM, or Microetics MSM host M system, Ope M/SQL calls out to the device hadlig routie supported by your M system. Refer to your implemetatio-specific M programmig maual for iformatio o how your device hadlig routie works. Procedure To select a output device for a SELECT-statemet query: 1. Ru a SELECT-statemet query. If you are ruig Ope M/SQL o a ISM system, you see the Device Selectio widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄRu QueryÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Query Name Descriptio ³ ³ patiets2 Patiets with ame S ³ ³ ÚÄÄÄÄÄÄÄÄDevice SelectioÄÄÄÄÄÄÄÄ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄij Device ³ ³ /dev/ttyp6 ³ ³ ³ ³ Descriptio ³ ³ dpv 15 Dec 94 ³ ³ ³ ³ Prit Format ³ ³ Normal ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Device Selectio Exit Without selectig Press <Help> For Help Ope M/SQL Developer Guide 10-33

267 Chapter 10 Query Geeratio ad Processig The followig table lists ad describes the fields located o the Ope M/SQL for ISM Device Selectio widow: Table 10-14: Fields o Ope M/SQL for ISM Device Selectio Widow Field Device Descriptio Prit Format Descriptio This field always defaults to your curret device (the curret value of $IO). You may chage the default to ay valid output device to which your device is liked. This field reflects the descriptio give to the specified device i the device table. Here you may select ay prit format defied for the specified device. 2. I the Device field, eter the ame of the device to which you wat to sed the query. You ca sed the query to ay valid output device that is liked to your curret device. The default device is your curret device. To sed the query to your scree, press the <PROCEED> key. To sed the query to aother device (such as a priter), delete the ame of the default device at the Device prompt, eter the ame of the ew target device, adjust the Prit Format parameter as appropriate, ad press the <PROCEED> key. 3. Whe you have etered a device ame ad the appropriate prit format parameters, press the <PROCEED> key. This executes the query Ope M/SQL Developer Guide

268 Ruig Queries The example below shows sample output for the followig query: SELECT ame,sex,age,avg(age %FOREACH(sex)) FROM Patiets WHERE ame %STARTSWITH S ORDER BY ame Name Sex Age expressio Salisbury, Harvey Male Saderso, George Male Sawyer, Eleaor Female Schmidt, Mitchell Male Scott, Deise Female Scott, Michael Male Shapiro, Oscar Male Silva, Louise Female Simmos, Virgiia Female Smith, Charlotte Female Smith, Joe Male Smith, Timothy Male Syder, Estelle Female Sprig, Joatho Male Steves, Charles Male Steves, Theresa Female Stewart, Frederick Male Stoe, Julia Female Sulliva, Betty Female Sulliva, Waye Male Sweeey, Terrece Male Press <Retur> to cotiue, <Optios> to scroll, <Exit> to Exit Note: Whe output to the scree, the query displays oe scree at a time ad prompts you to press <RETURN> to scroll ahead to the ext scree. Device Selectio for ASCII-Delimited Output Format To prit a query i ASCII-Delimited output format, eter ASCII-Delimited at the Prit Format field. If you desigated the query for ASCII-Delimited output oly (this optio is located i the Advaced Optios widow), the Prit Format field i the Device Selectio widow automatically defaults to ASCII-Delimited ad caot be chaged. Note that Ope M/SQL does ot require that you specify a file as the output device i order to geerate ASCII-Delimited output. You may fid it useful to sed ASCII-Delimited records to a termial device, such as a asychroous commuicatios lie, or to a spooler device. Ope M/SQL Developer Guide 10-35

269 Chapter 10 Query Geeratio ad Processig ASCII-Delimited Output for Queries Ope M/SQL supports the ability to direct the output from SELECT-statemet queries defied via the Query Geerator or Iteractive Query Editor to ASCII- Delimited text files. These files are formatted for import ito may PC software packages. Cotets of a ASCII-Delimited File I a ASCII-Delimited file, each record cosists of oe or more field(s) eclosed i a user-defied quotatio character ad delimited by a user-defied delimiter character. A user-defied ed-of-record sequece follows each record. A sample record might appear as follows: 3, Smith,Joh, 12345, Male, 675.2,,, Fractured Tibia <CR><LF> where the Quote Character is ( ), the Ed of Field Delimiter is (,), ad the Ed of Record Delimiter is (<CR><LF>). All occurreces of the Quote Character will be stripped from your data prior to the formattig of output records. For each detail lie output, Ope M/SQL geerates a sequetial record idetifier, which may be used as a key field to idetify the record withi your applicatio. The first field of each record will always be the record idetifier. All other fields are output i the order they were specified i the query defiitio. If a SELECT statemet query was used, the output colums are ordered by table colum umber. Ope M/SQL does ot restrict the maximum legth for ASCII-Delimited output records. However, you should be aware of ay record legth limitatios imposed by the applicatio importig the ASCII-Delimited file. Queries Support Dual Output Formats I Ope M/SQL, a sigle query defiitio ca produce both stadard prited output ad ASCII-Delimited file output. For stadard prited queries, Ope M/SQL curretly restricts the maximum umber of fields that ca you ca select. To surmout this limitatio you may desigate the query for ASCII-Delimited output oly. By choosig this optio you reliquish all formattig cotrol over the output, but gai the privilege of icludig a ulimited umber of fields i the ASCII-Delimited output file. This choice is also reversible, i.e., you may iitially desigate a query for ASCII-Delimited output oly ad later modify it to allow both types of output. However, if you do this you may eed to reduce the umber of query fields i order to permit prited output Ope M/SQL Developer Guide

270 Copyig Queries Copyig Queries You may use the Copy Query utility to make a copy of a query defiitio. This utility creates a copied query that is virtually idetical to the source query. As soo as the copy is made, the copied query reliquishes all ties to its source query. You may use the copied query i all the same ways you use a regular query. Specifically, you may: Edit it Ru it Use it as the data source of a view or report Use it i the FROM clause of aother query You may copy ay query, regardless of whether or ot you hold privileges o it. However, i order to ru a copied query, you must hold SELECT privileges o the source query. Ad i order to edit a copied query, you must hold %ALTER privileges o the source query. Procedure To copy a query: 1. From the SQL meu, select the Copy Query optio. You see the Copy Query Selectio lookup widow, as show below: ÚÄÄÄÄÄÄCopy Query Selectio WidowÄÄÄÄÄÄ ³ ³ ³ Copy Query ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Copy Query Selectio Widow Selectig Press <Help> For Help 2. At the Copy Query field, eter the ame of the source query (the query you wat to copy), ad press <RETURN>. Ope M/SQL Developer Guide 10-37

271 Chapter 10 Query Geeratio ad Processig You may select ay query defied via the Query Geerator or the Query Editor. To select a query, eter the complete or partial ame of a existig query, ad press <RETURN>. You see a lookup box that lists all matchig etries. To see a lookup box that lists all queries defied i the curret database, leave the Copy Query field blak ad press the <SEARCH CURRENT TABLE> key. 3. Use the cursor positioig keys to avigate withi the lookup box, ad press <RETURN> to select a etry. The Copy Query Selectio widow fills out with its complete set of fields, as show below: ÚÄÄÄÄÄÄCopy Query Selectio WidowÄÄÄÄÄÄ ³ ³ ³ Copy Query ³ ³ patiets1 ³ ³ ³ ³ To Query ³ ³ ³ ³ ³ ³ Ru New Query Yes_ ³ ³ ³ ³ ³ ³ Query Type Is Form Defied ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Copy Query Selectio Widow Press <Help> For Help 4. At the To Query field, eter the ame of the ew query to be created. A query ame may rage from 1 to 30 characters i legth ad may iclude ay alphaumeric characters, icludig the uderscore character. The ame must always begi with a alphabetic character. This ame must ot already be i use by aother query. 5. At the Ru New Query? field, aswer Yes or No to idicate whether or ot you wat to compile ad ru the ew query as soo as it is copied. Aswer Yes to compile ad ru the ew query immediately after creatig it. No is the default respose Ope M/SQL Developer Guide

272 Copyig Queries The Query Type Is field shows the type of query that you have specified as the source query. This field may have either of the followig two values: Iteractive (defied i the Query Editor) Form-Defied (defied usig the Query Geerator) 6. Press the <PROCEED> key to copy the query. Whe the copy is complete, Ope M/SQL displays the followig message at the bottom of the scree: Query Copy Successful If you typed No i the Ru New Query? field, you retur to the SQL meu. If you typed Yes i the Ru New Query? field to request Ope M/SQL to compile ad ru the query immediately after creatig it, you see the followig message at the bottom of the scree: Compilig ad ruig Query <query ame> After compilig the query, Ope M/SQL displays the appropriate device selectio script for your M system to request iformatio about where to sed the query output. 7. Eter a device ame ad appropriate prit format parameters, the press the <PROCEED> key to execute the query. Ope M/SQL Developer Guide 10-39

273 Chapter 10 Query Geeratio ad Processig List Queries Report The List Queries utility lets you geerate a scree or hard copy report that lists all queries defied i the curret database (via the Query Geerator ad Iteractive Query Editor) ad provides the followig iformatio about each oe. Query Name Name of the query (queries are listed i alphabetical order) Query Descriptio Descriptio give to the query Procedure To ru the List Queries report: 1. From the SQL meu, select the List Queries optio. You see the device selectio script ative to your host M system. If you are ruig Ope M/SQL o a ISM system, you see the Device Selectio widow. 2. Eter the ame of the output device to which you wat to sed this report ad specify the appropriate prit format parameters. 3. Whe you have etered a device ame ad the appropriate prit format parameters, press the <PROCEED> key. This executes the report. Below is a sample List Queries report: Query Query Name Descriptio ages Cesus1994 Cesus for year 1994 CesusMay95 Cout Patiets for May 95 Cout_Admissios Total Number of Admissios CoutPatiets Cout of Number of Patiets ListMRN List Curret Medical Rec. #s Males65 List Males over 65 Occupacy Calculate Occupacy oldpats Patiet_Cout Cout of Patiet Etries patiets1 Average Age by Ward, Sex patiets2 Patiets with ame S PatStates persoel Reveue1994 Reveue for Year 1994 ReveueMay94 Reveue for May 1994 States tstq1 Test Query Press <Retur> to Exit Note: Whe output to the scree, this report displays oe scree at a time ad prompts you to press <RETURN> to scroll ahead to the ext scree. 4. Press the <PREVIOUS> key to exit the List Queries report ad retur to the SQL meu Ope M/SQL Developer Guide

274 Detailed Query Listig Report Detailed Query Listig Report The Detailed Query Listig utility lets you geerate a scree or hard copy report that lists a specific query, all queries, or a rage of queries whose query ames begi with a similar character strig. The Detailed Query Listig Report provides the followig iformatio about each query: Query Name Name of the query (queries are listed i alphabetical order) Query Descriptio Descriptio give to the query Query Ower UserName of the user who created the query Routie Prefix Name of the routie prefix used by all routies geerated for the query by Ope M/SQL SQL Text Text of the query All queries defied i the curret database (via the Query Geerator ad Iteractive Query Editor) are available to this report. Procedure To ru the Detailed Query Listig report: 1. From the SQL meu, select the Detailed Query Listig optio. You see the device selectio script ative to your host M system. If you are ruig Ope M/SQL o a ISM system, you see the Device Selectio widow. 2. Eter the ame of the output device to which you wat to sed this report ad specify the appropriate prit format parameters. 3. Whe you have etered a device ame ad the appropriate prit format parameters, press the <PROCEED> key. Ope M/SQL Developer Guide 10-41

275 Chapter 10 Query Geeratio ad Processig You see the Detailed Query Listig Ru-Time Coditios widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄ ³ Ru Time Coditios ³ ³ For Report: Detailed Query Listig ³ ³ ³ ³ QueryName Starts With ³ ³ ³ ³ ( From table: Query with descriptio Query Name ) ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Ru Time Coditios Press <Help> For Help 4. I the Starts With field specify the query or queries you wat to list i the report. To specify all queries defied i the curret database, leave the Starts With field blak. To specify just the patiets1 query, type the literal strig patiets1. To specify all queries that begi with the letter P, type the letter P. 5. Press the <PROCEED> key to execute the report Ope M/SQL Developer Guide

276 Detailed Query Listig Report Below is a sample Detailed Query Listig report for all queries that begi with the letter P : IterSystems Corporatio Detailed Query Listig ============================================ Date: 17 Jul 95 Page: 1 Query: patiets1 Descriptio: Average Age By Ward, Sex Ower: _SYSTEM Routie: mq9 SQL: SELECT ward,sex,avg(age) FROM Patiets GROUP BY ward,sex ORDER BY ward,sex HAVING AVG(age) < 62 -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Query: patiets2 Descriptio: Patiets with ame S Ower: _SYSTEM Routie: mq10 SQL: SELECT ame,sex,age,avg(age %FOREACH(sex)) FROM Patiets WHERE Name %STARTSWITH S ORDER BY ame Press <Retur> to cotiue, <Optios> to scroll, <Exit> to Exit Note: Whe output to the scree, this report displays oe scree at a time ad prompts you to press <RETURN> to scroll ahead to the ext scree. 6. Press the <PREVIOUS> key to exit the Detailed Query Listig report ad retur to the SQL meu. Ope M/SQL Developer Guide 10-43

277 PART Applicatio Programmig IV Chapter 11 Programmer Iterface to Applicatios Chapter 12 Ope M/SQL Developer Utilities

278

279 CHAPTER Programmer Iterface to Applicatios 11 I Ope M/SQL, you ca isert M ad SQL code at desigated locatios withi object defiitio widows to customize forms, reports, ad the uderlyig base table operatios of lookup ad filig to your precise specificatios. Specifically, this iserted code ca customize base table ad widow triggers, lookup queries, filig routies, ad operatios that calculate, validate, ad covert data fields. I each case, the iserted code must observe specific covetios for commuicatig with the applicatio that calls it. Ope M/SQL supplies etry poits that eable you to call forms, reports, queries, ad meus from routies as well as from the M programmer prompt. Other utility etry poits perform fuctios that emulate forms. All etry poits observe specific covetios for parameter passig. Embedded SQL provides a way for a M program to operate the machiery of retrieval ad filig withi Ope M/SQL base tables. This chapter discusses the followig topics: Ope M/SQL Variables Etry Poits to the %msql Routie Ope M/SQL Globals Isertig Code ito Ope M/SQL Applicatios Callig Ope M/SQL Objects from M Programs Emulatig Form Behavior from M Programs Establishig Authorizatio ID from Programmer Mode Itermixig Ope M/SQL Objects with User-Defied M Routies Cotets of Applicatios Ope M/SQL Developer Guide 11-1

280 Chapter 11 Programmer Iterface to Applicatios Ope M/SQL Variables All local variables used by Ope M/SQL begi with the percet sig (%) ad have all-lowercase ames. A list of these variable ames appears below. Do ot use these ames for ay other purpose tha what is documeted. IterSystems reserves the right to add to this list of percet variables i future releases, ad therefore strogly advises that you do ot use ay user-defied variables that begi with the percet sig. Ope M/SQL uses variables with lowercase ames to ru forms ad reports. To avoid the possibility of coflict, IterSystems recommeds that you do ot use all-lowercase variable ames i ay M code you isert ito your Ope M/SQL applicatios or i ay routies called by your applicatios. Embedded SQL uses its ow percet variables without protectig them by a NEW commad. These variables all begi with the prefix %mmm ad thus do ot ru a high risk of coflict. Whe defiig variables i a program cotaiig embedded SQL, make sure your variables do ot begi with %mmm. List of Ope M/SQL Percet (%) Variables The followig table lists ad describes the percet variables used by Ope M/SQL to commuicate with applicatios, or used by programs that call applicatios. You will ote that some of these percet variables are eclosed i curly braces, such as {%actio}. The curly brace sytax idicates that these are ot raw M variables, but rather Ope M/SQL iterpreted variables. Variables of this sytax remai the same eve whe the ames of the uderlyig variables they represet chage. Table 11-1: Ope M/SQL Percet (%) Variables %variable Fuctio Where Used %msql %is() array %mode() array %val %ok Stores the curret UserName ad Termial Type, as well as other user prefereces. Stores termial-specific commad strigs to be executed by routies. Stores termial-specific appearace attributes to be writte by routies. Stores the data value of a field for use i exteral-to-iteral ad iteral-toexteral coversio ad user-defied additioal validatio code. Flag that ca be set to 0 to disallow the filig of a ivalid field value. Geeral Geeral Geeral Data Dictioary & Form Geerator Data Dictioary & Form Geerator 11-2 Ope M/SQL Developer Guide

281 Ope M/SQL Variables Table 11-1: Ope M/SQL Percet (%) Variables (Cotiued) %variable Fuctio Where Used %msg %data(icol) %edit(icol) %ew %ewext %old %oldext {%paret_referece} {%caller} Stores text message retured by validatio code whe rejectig a ivalid field value. Stores the data value of the curret field of the curret row, whether saved or usaved. Stores the disk value of the curret field of the curret row whe that field has bee edited but ot saved. Uless %data(icol) is usaved, %edit is udefied. Stores the ew value of a edited field. This variable is used to allow validatio code to examie the ew field value. Stores the ew exteral value of a edited field. This variable is used to allow validatio code to examie this value. Stores the old value of a edited field. This variable is used to allow validatio code to examie the old field value. Stores the old exteral value of a edited field. This variable is used to allow validatio code to examie this value. For forms based o child tables, {%paret_referece} holds the paret referece ID (the RowID of the curret row i the paret table). For forms ot based o child tables, the value of {%paret_referece} is. Stores the curret value of the Caller ID. Data Dictioary & Form Geerator Form Geerator Form Geerator (for database fields oly) Form Geerator Form Geerator Form Geerator Form Geerator Form Geerator Specifically: All form trigger locatios Variable Widow Placemet Form-oly Field Compute Code Form Geerator Specifically: All form trigger locatios Variable Widow Placemet Meu Object Defiitio Ope M/SQL Developer Guide 11-3

282 Chapter 11 Programmer Iterface to Applicatios Table 11-1: Ope M/SQL Percet (%) Variables (Cotiued) %variable Fuctio Where Used {%actio} {%filetype} {%presave} {%savedata} {%timeout} Stores the last keyboard actio etered by the user. It ca have ay of the followig values: PROCEED PREVIOUS GETOUT GETOUTALL Up Arrow Dow Arrow Retur Tab Stores the type of filig curretly i effect. Possible values are: Update idicates that the curret form is i data etry mode. Iquiry idicates iquiry mode. Isert idicates that you have just cofirmed isertio of a row. Flag that idicates whether or ot data ha bee saved withi the curret form. If %savedata is 1, data has bee saved. If it is 0, o data has bee saved. Flag that idicates whether or ot the curret form cotais usaved data. If %savedata is 1, there is usaved data withi the curret form. If it is 0, there is o usaved data. Flag that idicates whether or ot the form was exited as the result of a timeout actio. If %timeout is 1, the form did time out, If it is 0, the form did ot time out. Form Geerator Specifically: Post-Form triggers Post-Field triggers Post-Widow triggers Form Geerator Specifically: Post-Form triggers Post-Widow triggers Post-Field triggers Pre-Row triggers Post-Row triggers Variable Widow Placemet Form Geerator Specifically: Post-Form triggers Post-Widow triggers Post-Field triggers Variable Widow Placemet Form Geerator Specifically: Post-Form triggers Post-Widow triggers Post-Field triggers Variable Widow Placemet Form Geerator Specifically: All form trigger locatios 11-4 Ope M/SQL Developer Guide

283 Ope M/SQL Variables Table 11-1: Ope M/SQL Percet (%) Variables (Cotiued) %variable Fuctio Where Used {%retur_actio} {%retur_filetype} {%retur_presave} {%retur_savedata} {%retur_timeout} {%iquiry_mode} {%lieum} Stores the value of %actio from the form that was last exited. It ca have ay of the followig values: PROCEED PREVIOUS GETOUT GETOUTALL Up Arrow Dow Arrow Retur Tab Stores the value of %filetype from the form that was last exited. Stores the value of %presave from the form that was last exited. Stores the value of %savedata from the form that was last exited. Stores the value of %timeout from the form that was last exited. Flag that idicates whether or ot the form is curretly i iquiry-oly mode. I %iquiry is 1, the form is i iquiryoly mode. I it is 0, the form is ot i iquiry-oly mode. Stores the lie umber of the curret lie i a multi-lie field. Form Geerator Specifically: All form trigger locatios Form Geerator Specifically: All form trigger locatios Form Geerator Specifically: All form trigger locatios Form Geerator Specifically: All form trigger locatios except Pre-Row triggers Form Geerator Specifically: All form trigger locatios Form Geerator Specifically: All form trigger locatios Meu Object Defiitio Form Geerator Specifically: Field Defiitio for multi-lie fields Ope M/SQL Developer Guide 11-5

284 Chapter 11 Programmer Iterface to Applicatios Table 11-1: Ope M/SQL Percet (%) Variables (Cotiued) %variable Fuctio Where Used {%retrieved} {%meubar} {%meuid} {%meutype} {%cellar_tuple} {%date} {%time} {%agg} {%pageum} {%ewpage} Flag that is set to 1 if ay rows are retrieved whe a multi-row form is ru, 0 otherwise. This variable applies to multi-row forms oly. Stores the ame of the curretly active meu bar. Stores the iteral idetificatio umber of curretly active meu bar. Stores the type of the curretly active meu object. Its value is either meu bar or pop-up meu. Flag that is set to 1 whe the user of a multi-row form iserts a row at the bottom of the form. Stores the curret date i a M/PACT report. Stores the curret time i a M/PACT report. Stores the calculatio for the aggregate fuctio you have specified. Stores the curret page umber i a M/PACT report. Forces a page feed i a M/PACT report. Form Geerator Specifically: All form trigger locatios except Pre-Form ad Pre-Widow triggers Form Geerator Specifically: All form trigger locatios except Pre-Row ad Post-Row triggers Meu Object Defiitio Form Geerator Specifically: All form trigger locatios except Pre-Row ad Post-Row triggers Meu Object Defiitio Form Geerator Specifically: Meu Object Defiitio Form Geerator Specifically: Pre-Row triggers M/PACT M/PACT M/PACT M/PACT M/PACT 11-6 Ope M/SQL Developer Guide

285 Ope M/SQL Variables Table 11-1: Ope M/SQL Percet (%) Variables (Cotiued) %variable Fuctio Where Used {%report-ed} {%backgroud} Flag to idicate whether or ot a report ra to completio. If user exits report before completio by pressig the <PREVIOUS> key, {%report-ed} is set to user abort. If the report ra to completio, it is set to NULL ( ). Flag to idicate whether or ot a report is beig ru i the foregroud. If the report is beig ru i the foregroud, {%backgroud} is set to 0. If a report is beig ru i the backgroud, it is set to a umber greater tha 0. M/PACT Specifically: Post-Report triggers M/PACT Specifically: Pre-Report triggers Post-Report triggers Ope M/SQL Developer Guide 11-7

286 Chapter 11 Programmer Iterface to Applicatios Etry Poits to the %msql Routie The %msql routie supports several utility etry poits, which you may use i M programs to perform the followig fuctios: Call Ope M/SQL objects Emulate various aspects of form behavior Establish a Authorizatio ID The followig tables list ad briefly describe these utility etry poits to %msql. Use the followig etry poits to call Ope M/SQL objects from a M program: Table 11-2: Etry Poits For Callig Ope M/SQL Objects Etry Poit orm^%msql meu^%msql query^%msql report^%msql Fuctio Calls a form Calls a old-style meu Calls a pre-defied query Calls a report Use the followig etry poits to emulate various aspects of form behavior: Table 11-3: Etry Poits For Emulatig Form Behavior Etry Poit help^%msql write^%msql $$read^%msql widcl^%msql Fuctio Displays scrollig help text Writes a message o the scree Reads a data value Cleas up scree by erasig the residual display of widows after they have bee exited Use the followig etry poit to establish a Authorizatio ID (idetify a user to Ope M/SQL): Table 11-4: Etry Poit for Establishig a Authorizatio ID Etry Poit setaid^%msql Fuctio Establishes a Authorizatio ID (idetifies a user to Ope M/SQL) For more iformatio about these etry poits, refer to the sectios foud later i this chapter etitled Callig Ope M/SQL Objects from M Programs o page 11-27, Emulatig Form Behavior from M Programs o page 11-34, ad Establishig Authorizatio ID from Programmer Mode o page Ope M/SQL Developer Guide

287 Ope M/SQL Globals Ope M/SQL Globals There are two groups of globals used by Ope M/SQL, object defiitio globals ad percet (%) globals. Object Defiitio Globals The object defiitio globals are located i each developmet directory/uci/amespace. Cautio Do ot delete these globals. Doig so will delete your object defiitios. Most of the object defiitio globals begi with the letter m. Note IterSystems reserves the sytax ^m* for its ow use. The followig table lists the Ope M/SQL object defiitio globals ad briefly describes the iformatio stored i each: Table 11-5: Ope M/SQL Object Defiitio Globals Global ^ROUTINE ^mroutie ^UTILITY ^mcompd ^mcov ^mdd ^mddc ^mexpew ^mexport ^mform ^mformc ^mhelp ^mlock ^mmeu ^mmisc Cotets Macro source ad itermediate code routies (for Ope M/SQL o ISM systems oly) Macro source ad temporary itermediate code routies (for Ope M/SQL o ISM systems oly) Scratch iformatio for utilities (for Ope M/SQL o ISM systems oly) Object compile driver cofiguratio defiitios Iformatio about which coversio programs have bee ru o the major objects i this directory Base table defiitios ad view defiitios Iformatio for compiled base tables Export/import defiitios (for the ew-style Export/Import utility) Export/import defiitios (for the old-style Export/Import utility) Form defiitios Iformatio for compiled forms Iformatio for the Ope M/SQL Help Meu Lockig iformatio for rows Old-style meu defiitios Routie ame prefixes Ope M/SQL Developer Guide 11-9

288 Chapter 11 Programmer Iterface to Applicatios Table 11-5: Ope M/SQL Object Defiitio Globals (Cotiued) Global ^mobject ^mpriv ^mql ^mreport ^mreportc ^mtemp* ^mterm ^mutil ^mxdd ^mxform ^mxreport ^mxql ^mxmeu ^mxmeob ^mxdoc ^mxhtop Cotets Meu object defiitios, help documet defiitios, help topic defiitios, ad video attribute defiitios Privilege allocatio defiitios for Ope M/SQL objects Pre-defied query defiitios M/PACT report defiitios Iformatio for compiled M/PACT reports Miscellaeous ru-time iformatio Saved termial specificatios to be restored upo exitig Ope M/SQL Miscellaeous utility defiitios Base table defiitios queued for export usig the Export/Import utility Form defiitios queued for export usig the Export/Import utility Report defiitios queued for export usig the Export/Import utility Query defiitios queued for export usig the Export/Import utility Old-style meu defiitios queued for export usig the Export/Import utility Meu object defiitios queued for export usig the Export/Import utility Help documet defiitios queued for export usig the Export/Import utility Help topic defiitios queued for export usig the Export/Import utility Ope M/SQL Developer Guide

289 Ope M/SQL Globals Object Defiitio Globals Located i Commo Directory The followig object defiitio globals are also located i the commo directory/uci/amespace (/usr/msql/commo): ^mdd ^mddc ^mform ^mformc ^mhelp ^mmeu ^mmisc ^mobject ^mpriv ^mreport ^mreportc If you are usig the Ope M/SQL Relatioal Server, you will also fid the followig globals i the commo directory/uci/amespace (/usr/msql/commo): ^mroutie ^mtemp Cautio Do ot delete these globals from the commo directory uder ay circumstaces. If you do so, you will have to reistall Ope M/SQL. Ope M/SQL Developer Guide 11-11

290 Chapter 11 Programmer Iterface to Applicatios Ope M/SQL Percet (%) Globals The percet (%) globals are located i the Ope M/SQL System Maager s directory. Cautio Do ot delete these globals from the System Maager s directory. If you do so, you may have to reistall Ope M/SQL. Also, do ot chage the default global protectio status of these globals, ad do ot edit these globals by had (with the exceptio of %rakeys). The followig table lists the Ope M/SQL percet (%) globals ad briefly describes the iformatio stored i each: Table 11-6: Ope M/SQL Percet (%) Globals Global ^%RDE ^%dafmlog ^%mmsg ^%mobject ^%msql ^%muser ^%omc ^%oms ^%qarmisc ^%rakey ^%rakeys ^%rde ^%rekey ^%sys ^%task Cotets Full Scree Editor iformatio Results of FileMa->Ope M/SQL liks ad updates Iformatio for the Message of the Day System help objects Miscellaeous Ope M/SQL iformatio Ope M/SQL UserName defiitios. Default protectio status allows users to read/write/delete this global. To edit the cotets of this global, use the User Security Defiitio widow Relatioal Gateway iformatio Ope M/SQL Server cofiguratio iformatio.the System Maager ca edit the cotets of this global by editig Server cofiguratio parameters Miscellaeous M/PACT iformatio Ope M/SQL keyboard defiitio iformatio Ope M/SQL keyboard defiitio iformatio. Default protectio status allows users to read/write/delete this global. This is the oly % global that you might have occasio to edit by had (see the Ope M/SQL Database Admiistrator s Guide for more iformatio). Full Scree Editor iformatio Ope M/SQL keyboard defiitio iformatio Ope M/SQL system iformatio Ope M/SQL Task Maager iformatio. Default protectio status allows users to read/write/delete this global. To edit the cotets of this global, use the M/SQL Task Queue widow Ope M/SQL Developer Guide

291 Isertig Code ito Ope M/SQL Applicatios Isertig Code ito Ope M/SQL Applicatios Ope M/SQL provides a variety of locatios where you may directly isert M code or SQL code ito a applicatio. This eables you to customize the applicatio to your exact specificatios. The followig table lists the locatios withi the Ope M/SQL applicatio developmet eviromet where iserted code is supported ad shows what type of code you ca isert: Table 11-7: Locatios Where M/SQL Permits Iserted Code Locatio Triggers i base tables (Actio Types: M Code, SQL Code, Routie) Triggers i forms (Actio Types: M Code, SQL Code, Routie, Set Field) Triggers reports (Actio Types: M Code, Routie) Override queries for base table ad form lookups Computed fields i base tables, forms, ad reports Iteral-to-Exteral ad Exteral-to-Iteral Coversio Code i base tables ad forms Additioal Validatio Code i base tables ad forms Coditios for Required-Maybe fields i base tables ad forms Coditios for executig variable widow placemet Expressios for map subscripts ad pieces NEXT Subroutie i maps Coditios for coditioal maps Geeral Mappig Meu object optios (Actio Types: M Code, SQL Code, Routie) Code to use memoic as accelerator i stad-aloe meu bar attributes Coditios for exitig meu bar after ivokig meu optio Coditios for settig the Active flag for a meu optio Coditios for suppressig display of a meu optio Type of Code M code lies SQL statemet M code lies SQL statemet M code lies SQL WHERE ad ORDER BY statemets M code lies M IF coditios M code lies M code lies M IF coditios M IF coditios M expressios M code lies M IF coditios M code lies M code lies SQL statemet M expressios M expressio M expressio M expressio Ope M/SQL Developer Guide 11-13

292 Chapter 11 Programmer Iterface to Applicatios Table 11-7: Locatios Where M/SQL Permits Iserted Code (Cotiued) Locatio Defiig the Caller ID for a meu actio Coditios for executig variable meu placemet (for meu objects oly) Code to clear the scree before meu optio ivocatio ad restore the scree after optio ivocatio Coditios for exitig the Pop-Up Meu after ivocatio of a meu optio Coditios for collapsig all Pop-Up Meus, or the curret Pop-Up Meu after the meu optio is ivoked Meu optios (for old-style meus) Actio types: M Code, Routie Specificatio for Row ID for the form to call (whe the target form is a sigle-row form) Specificatio for the paret referece (whe the source table of the target form is a child table with a kow paret) Type of Code M expressio M IF coditios M expressio M expressio M expressio M code lies M expressio M expressio The types of iserted code refereced i the Type of Code colum i the precedig table have the followig meaigs: M code cosists of oe or more lies of valid M commads ad argumets, without tags. M expressio M code that cotais o commads ad evaluates to a value. M IF coditio oe or more M expressios separated by commas, as would follow a M IF commad. SQL statemet SQL code that performs a sigle operatio, e.g. SELECT, INSERT, UPDATE, DELETE, etc. Iserted Code Ca Referece Fields Iserted M code ca referece sigle-lie as well as multi-lie fields i the curret base table. To referece sigle-lie fields, use the curly brace sytax, as follows: {fieldame} To referece multi-lie fields, use the followig sytax: {fieldame(expressio)} Ope M/SQL Developer Guide

293 Isertig Code ito Ope M/SQL Applicatios This sytax requires that you specify a expressio to idicate which lie of the multi-lie field you are targetig. For example, the followig code: SET AddLie2={Address(2)} sets the variable AddLie2 to the secod lie of the Address field. The expressio caot cotai ay of the followig: Other fields The wildcard character * Curly braces Ope M/SQL does ot check the expressio for correctess. A icorrect expressio may cause the code to fail. Iserted Code Ca Referece Variables ad Globals Iserted M code ca referece local variables ad globals. For each type of iserted code, certai percet (%) variables are uiquely applicable, while others are ot applicable. This topic is discussed i more depth i the followig sectios. To avoid potetial coflicts with system code, your iserted M code should ot referece variables with all-lowercase ames, uless the iserted code is a trigger actio (ad therefore called as a subroutie) ad protects its variables with a NEW commad. Aywhere you ca isert M code you ca also isert macro source code. Ope M/SQL Performs Sytax Checkig o Iserted M Code Ope M/SQL automatically performs sytax checkig o all iserted M code throughout the Ope M/SQL eviromet, with the exceptio of the Geeral Mappig facility i the Data Dictioary (where you may defie a customized physical structure for a base table). Wheever you exit a lie of iserted M code, Ope M/SQL checks it for proper sytax ad reports ay errors at the bottom of the scree. Ope M/SQL does ot check SQL code for proper sytax. Note Ope M/SQL supports sytax checkig for ISM systems oly. Ope M/SQL Developer Guide 11-15

294 Chapter 11 Programmer Iterface to Applicatios Triggers Triggers are sequeces of actios that you may defie to automatically take place at various poits durig the executio of a Ope M/SQL applicatio. You may defie triggers at the followig levels withi the Ope M/SQL applicatio developmet eviromet: Base table Form Report Trigger Actio Types A trigger may cosist of oe trigger item or a sequece of multiple trigger items. Each trigger item must have a actio type, which specifies the kid of actio the trigger item will execute. The set of actio types available to a trigger defiitio depeds o where i the Ope M/SQL eviromet the trigger is located. For each trigger item, you may defie a associated coditio i the form of a M IF expressio to cotrol its executio. Whe the coditio associated with a trigger item evaluates to TRUE, the specified trigger actio executes. Whe the coditio associated with a trigger item evaluates to FALSE, the specified trigger actio does ot execute. Base Table Triggers Base table triggers are defied i the Data Dictioary. They are sequeces of database actios iitiated by a INSERT, UPDATE, or DELETE actio performed o a base table. These triggers help to maitai itegrity costraits ad other data depedecies. There are six types of base table triggers, icludig: Pre-filig INSERT Triggers Pre-filig UPDATE Triggers Pre-filig DELETE Triggers Post-filig INSERT Triggers Post-filig UPDATE Triggers Post-filig DELETE Triggers Ope M/SQL Developer Guide

295 Isertig Code ito Ope M/SQL Applicatios Base Table Trigger Actio Types Base table triggers support the followig actio types: M Code Routie SQL code Each of these actio types permits you to isert your ow code. Form Triggers Form triggers exted the covetioal otio of triggers to form, widow, ad field iteractio. They are defied i the Form Geerator to perform various operatios tailored to the eeds of the applicatio ed-user. Form triggers ca execute at the form, widow, ad field levels of a applicatio ad are ofte used to defie the cotrol structure for applicatio processig. There are ie types of form triggers, icludig: Pre-Form Triggers (oe per form) Post-Retrieval Triggers (oe per form) Post-Form Triggers (oe per form) Pre-Row Triggers (oe per form, for multi-row forms oly) Post-Row Triggers (oe per form, for multi-row forms oly) Pre-Widow Triggers (oe per widow) Post-Widow Triggers (oe per widow) Pre-Field Triggers (oe per field) Post-Field Triggers (oe per field) Whe used to file data, a form ivokes the filig operatios of base tables, thus causig base table triggers to be pulled. Form Trigger Actio Types Form triggers support a very log list of actio types, may of which emulate very specific programmig fuctios (e.g., ivoke a specified form, widow, or meu). Most form trigger actio types do ot permit you to isert your ow code. For a complete list of all actio types supported by form triggers, see the Ope M/SQL User Iterface Programmig Guide. Ope M/SQL Developer Guide 11-17

296 Chapter 11 Programmer Iterface to Applicatios The form trigger actio types that permit you to isert your ow code iclude: M Code SQL Code Routie Set Field (which lets you set a specified field equal to a M expressio). Report Triggers Report triggers are defied i M/PACT. They may be used to execute lies of M code, call pre-defied M routies, or ivoke forms either before or after the executio of a report, with the resultat actio usually depedig o the evaluatio of some M/PACT percet (%) variable. There are two types of report triggers: Pre-Report Triggers Post-Report Triggers Pre-Report triggers are pulled before the report rus, but after the report output device is opeed ad used. Ay output from a Pre-Report trigger is set to the output device for that ru of the report. Post-Report triggers are pulled after the report rus, but before the device has bee closed, so that output from a Post-Report trigger is also set to the output device for that ru of the report. Report Trigger Actio Types Report triggers support the followig actio types: M Code Routie Form The M Code ad Routie actio types permit you to isert your ow code. You should oly the Form actio type if you ited to sed the report to a termial Ope M/SQL Developer Guide

297 Isertig Code ito Ope M/SQL Applicatios Referecig Fields i a Trigger Whe defiig triggers, you may referece ay fields associated with the curret base table i the followig places: M IF coditio expressio associated with ay trigger item M Code widow for a trigger item of actio type M Code Set Field widow for a trigger item of actio type Set Field Parameters to the routie specified for a trigger item of actio type Routie To referece a field, eclose the field ame i curly braces, for example: SET NAME={Name} sets the M local variable NAME equal to the (iteral) value of the Name field i the curret base table. Note The sytax {Table.Field} is ot allowed i triggers. Referecig Ope M/SQL Percet (%) Variables i Triggers Whe defiig triggers, you may referece Ope M/SQL percet (%) variables i the followig places: M IF coditio expressio of ay trigger item M Code widow of a trigger item of actio type M Code The Ope M/SQL percet (%) variables store iformatio about system mode ad recet user actios. You may use them to set up executio coditios for avigatio actios or other programmer-defied operatios. For a complete list of the Ope M/SQL percet (%) variables, see Table 12-1, Ope M/SQL Percet (%) Variables. May percet variables appear eclosed i curly braces, a sytax used to deote iterally stored system iformatio. These variables are iterpreted by Ope M/SQL at ru time. Ope M/SQL Developer Guide 11-19

298 Chapter 11 Programmer Iterface to Applicatios A few of the percet variables you may fid most useful whe defiig triggers are: {%actio} {%filetype} {%presave} {%savedata} {%timeout} {%caller} {%iquiry_mode} {%retrieved} {%paret_referece} For example, the M IF coditio expressio of a trigger item might test the value of the {%presave} variable, which is 1 if the curret row has bee filed, 0 otherwise. Ope M/SQL also supports the a list of retur prefix percet variables that correspod to certai o-prefixed percet variables, as show i the table below: Table 11-8: Retur Prefix Percet Variables Percet Variable {%actio} {%filetype} {%presave} {%savedata} {%timeout} Retur Prefix Percet Variable {%retur_actio} {%retur_filetype} {%retur_presave} {%retur_savedata} {%retur_timeout} Whereas the o-prefixed percet variables store curret values, the retur prefix percet variables store the same values for the form that was last exited (i.e., the values that were active at the time of the last Post-Form Trigger). Triggers ca also make use of other Ope M/SQL variables for a variety of purposes. For more iformatio o defiig triggers, see the Ope M/SQL Data Dictioary Guide (base table triggers) or the Ope M/SQL User Iterface Programmig Guide (form triggers) Ope M/SQL Developer Guide

299 Isertig Code ito Ope M/SQL Applicatios Usig SQL Code i a Trigger A trigger item of actio type SQL Code may cotai a sigle SQL statemet, occupyig oe or more lies. The SQL statemet ca be ay of the followig: SELECT INSERT UPDATE DELETE GRANT REVOKE %CHECKPRIV CREATE VIEW ALTER VIEW DROP VIEW A example of a trigger item of actio type SQL Code occurs i the pre-filig delete trigger for a paret table. This trigger item deletes all child rows belogig to a paret row whe the paret row is deleted. It uses the followig SQL sytax: DELETE FROM ChildTable WHERE ChildTable.ParetRef = :parid where parid is a variable set to the Row ID of the paret table curretly beig deleted. This trigger item esures referetial itegrity by makig sure that there are o orpha child rows. Note Whe eterig SQL code for a trigger item, you must isert a space character betwee cosecutive lies that should be separated by a space. The SQL Code defiitio widow does ot embed a space whe it wraps from oe lie to the ext. Usig M Code i a Trigger A trigger item of actio type M Code may cotai oe or more lies of M code. Each lie may be up to 255 characters i legth. The M code lies you defie are called as a subroutie. Therefore: You may use a QUIT statemet to exit the trigger item ad move o to evaluate the ext item (if oe exists) i the sequece. You may use a NEW statemet to protect local variables refereced i the trigger so that they do ot affect the caller. The M Code defied i triggers may cotai DO statemets ad may therefore call user-defied M routies. Ope M/SQL Developer Guide 11-21

300 Chapter 11 Programmer Iterface to Applicatios Override Queries for Lookups Ope M/SQL lets you defie lookup specificatios at both the base table ad form levels. Whe you defie lookup specificatios, Ope M/SQL automatically geerates a default SQL query for each lookup query you defie. You ca optioally modify this default SQL query to customize lookup selectio logic to your exact specificatios. Specifically, you ca modify the WHERE ad ORDER BY clauses of each geerated lookup query. Whe you modify a geerated lookup query you create a override lookup query. You must always use valid SQL sytax whe modifyig a geerated lookup query. You ca modify a geerated lookup query to do the followig: Chage a exact match lookup query to a partial match, or vice versa, Use a differet trasformatio fuctio from the stadard for a give data type (ALPHAUP, UPPER, or your ow fuctio), Make a lookup query more restrictive by excludig rows that do ot satisfy some set of criteria, Modify the order i which the rows are displayed i the lookup box. Computed Fields A computed field is a field whose value is calculated by oe or more lies of M statemets. The M statemets may referece other fields withi the curret base table usig the curly brace sytax, ad may use M $ fuctios. Computed fields may also iclude embedded SQL statemets delimited by the ##sql preprocessor fuctio. Ope M/SQL lets you defie computed fields for base tables, forms, ad reports. A computed field must always set itself equal to the value of the calculatio specified i the M statemet(s). You may referece the computed field itself by eclosig a asterisk i curly braces, {*}. For example: SET {*}={Qty}*{Price} SET {*}=$SELECT({City}= Dallas : LOCAL,1: REMOTE ) You may also defie IF coditios associated with the computed field that cause the field to produce a NULL result. A IF coditio cosists of oe or more M expressios separated by commas ad ca cotai field ames i curly braces. Whe a IF coditio evaluates to true, the computed field is NULL Ope M/SQL Developer Guide

301 Isertig Code ito Ope M/SQL Applicatios Iteral/Exteral Coversio Code You may defie exteral-to-iteral ad iteral-to-exteral coversio code for fields. This code coverts field values betwee exteral display format ad iteral storage format. It cosists of M statemets that modify the value of %val. Exteral-to-Iteral Coversio Code Exteral-to-iteral coversio code fids the exteral value of a field i %val ad sets %val to a iteral value. I additio, if it detects a problem with the exteral value, it ca set %ok to zero ad %msg to a error message, as described below i the sectio etitled Additioal Validatio Code. For example, the followig coversio code traslates a date from exteral format to iteral ($H) format: SET %DS=%val do INT^%DATE SET %val=%dn IF %val=-1 set %ok=0,%msg= Ivalid date the etry poit INT^%DATE receives iput from the variable %DS ad seds output to the variable %DN. Iteral-to-Exteral Coversio Code Iteral-to-exteral coversio code fids the iteral value of a field i %val ad sets %val to the exteral value. The followig code traslates a date from iteral format to exteral format: set %val=$zd(%val) The variable %ok has o effect i iteral-to-exteral coversio code. Other Coversio Code Variables Coversio code ca also referece the followig variables: %old iteral value of a field as it existed whe last retrieved from the base table. %oldext exteral value of a field as it existed whe last retrieved from the base table. %ew iteral value of a field as it curretly appears. %ewext exteral value of a field as it curretly appears. For example, to prevet the field WasSee from beig chaged from Yes to No, the coversio code for WasSee might iclude the followig lie: IF %oldext[ Y,%ewext[ N set %ok=0,%msg= Ca't... Ope M/SQL Developer Guide 11-23

302 Chapter 11 Programmer Iterface to Applicatios Additioal Validatio Code Ope M/SQL automatically performs some validatio checkig of base table ad form-oly fields based o the specified data type ad iformatio associated with the data type. For example, Ope M/SQL tests a date for valid sytax. It also tests date fields to make sure that a etry is ot earlier tha the earliest allowable date, as madatorily specified i Date Field Defiitio widow. The author of a base table or form ca specify additioal validatio code to further refie the scope of allowable etries. Additioal validatio code cosists of M statemets that may optioally referece field ames usig the curly brace sytax. The iteral value of a field resides i the variable %val. Additioal validatio code ca be used to reject a ivalid value for %val by settig %ok to zero ad %msg to a text error message, as follows: IF %val>$h SET %ok=0,%msg= No future dates please. Additioal validatio code ca referece the variables %old, %oldext, %ew, ad %ewext, as described above i the sectio etitled Iteral/Exteral Coversio. Required-Maybe Fields Required-Maybe is a optio for base table ad form-oly fields that allows you to specify a M coditio that determies whether or ot the field is required. Whe the M coditio you specify evaluates to TRUE, the field becomes required. Whe the M coditio you specify evaluates to FALSE, the field becomes ot required. The M coditio ca be ay sequece of M expressios separated by commas. It ca also cotai field ames usig curly brace sytax. For example, suppose you wat the base table field Employees.LiceseNumber to become required wheever the field Employees.ParkigSpot is ot ull. To do this, you ca make Employees.LiceseNumber a Required-Maybe field based o the status of the Employees.ParkigSpot field, by specifyig the followig Required-Maybe coditio: {Employees.ParkigSpot} = This coditio evaluates to TRUE uless Employees.ParkigSpot is ull or cotais a ull iteral ad exteral value separated by $C(1) Ope M/SQL Developer Guide

303 Isertig Code ito Ope M/SQL Applicatios Map Subscripts ad Pieces I the Ope M/SQL Geeral Mappig facility where you map base tables to uderlyig global structures, you ca specify subscripts ad pieces i base table maps as M expressios. These M expressios may cotai field ames i curly braces. For example, a costat subscript DATA is specified as: DATA A subscript cosistig of the value of the Dept field i the base table is specified as: {Dept} NEXT Subroutie A subscript ca also be a expressio, such as: $select({dept}= SALES : MARKETING,1:{Dept}) Ope M/SQL also allows master map subscripts to be expressios. I master map subscripts, fields i curly braces {} are limited to the RowID ad fields o which the RowID is based. See the Ope M/SQL Data Dictioary Guide for more iformatio o master map subscripts. If you wat a particular map subscript to be traversed by M code other tha the default $ORDER o the subscript value, you ca defie a override NEXT subroutie for that subscript. A NEXT subroutie cosists of oe or more lies of M code that set the value of: {Li} where i is the umber of the subscript. You ca skip a subscript value by executig a GOTO the label NEXT. For example, the followig NEXT subroutie for subscript 2: SET {L2}=$ORDER(^({L2})) GOTO NEXT:{L2}#100=0 skips values that are multiples of 100. Sice a ull subscript value idicates that there are o more rows, you should ot use a ull coditio for the NEXT test. Also, do ot use a IF commad to perform the test. Ope M/SQL Developer Guide 11-25

304 Chapter 11 Programmer Iterface to Applicatios Coditioal Map The NEXT subroutie ca execute a QUIT statemet ad use a NEW statemet to protect ay local variables that it uses. A coditioal map is a map that Ope M/SQL applies to base table data if a specified M coditio evaluates to true. The M coditio cosists of oe or more M expressios separated by commas ad ca cotai field ames i curly braces. For example, suppose you wated to create a idex of female patiets oly. You might defie a IF coditio for a coditioal map, as follows: IF {Patiets.Sex}= F Ope M/SQL Developer Guide

305 Callig Ope M/SQL Objects from M Programs Callig Ope M/SQL Objects from M Programs The followig sectios describe how to call forms, reports, queries, meu objects, ad old-style meus from withi a M program or directly from the M programmer prompt usig the M call sytax. The M call sytax lets you ivoke Ope M/SQL objects from ay of the followig locatios: From a trigger of actio type M Code From meu optio of actio type M Code From withi a M routie From the M programmer prompt Callig Forms Programmer-defied M code, icludig routies ad iserted M code, ca ivoke Ope M/SQL forms usig the M form call sytax. There are two ways to use the form call sytax: Usig the form s ame or iteral idetificatio umber Usig the form s routie prefix Whe callig forms that are compiled as NEW, you may use either sytax. Whe callig forms that are compiled as OLD, you must use the ame/id# sytax. Callig a Form By Its Name/ID# To call a form by its form ame or iteral idetificatio umber, use the followig sytax: do form^%msql(form,user,rowid,paretid,iquiry,oloop, update,callerid,default_array,currret_array, edit_array,scroll) where form is the ame or iteral idetificatio umber of the form you wat to ivoke. It is the oly required parameter Ope M/SQL Developer Guide 11-27

306 Chapter 11 Programmer Iterface to Applicatios Callig a Form By Its Routie Prefix To call a form by its routie prefix, use the followig sytax: do ^<routie_prefix>1(rowid,user,paretid,iquiry, oloop,update,callerid,default_array,currret_array, edit_array,scroll) where <routie_prefix> is the routie prefix associated with the form you wat to ivoke ad 1 is the system supplied idetifier appeded to the prefix of the etry poit routie. Note You may fid a form s routie prefix i the Routie Prefix field of the form-level Advaced Features widow for that form. Form Call Sytax Parameters Both versios of the form call sytax use approximately the same parameter list. The oly differece is the order of the rowid ad user parameters, which is switched. The parameters are positio-sesitive, which meas that you must assig some value to the first parameter before you ca assig a value to the secod parameter, ad to the secod parameter before you ca assig a value to the third parameter, etc. A ull value will mark a place. You may close the paretheses after the last positively defied parameter, ad Ope M/SQL will assume ull values for all remaiig parameters. The etire parameters list is optioal. You may type empty paretheses () to skip the etire list. The followig table lists ad describes the parameters associated with the M form call sytax: Table 11-9: Parameters Associated with M Form Call Sytax Parameter rowid user Meaig The Row ID of a row i the form's base table. This causes the form to ivoke the specified row. If ull, the row selectio widow will appear (for sigle-row forms). This is a o-meaigful parameter; Ope M/SQL o loger uses this iformatio. Eter the ull value ( ) to skip this parameter. Note: Ope M/SQL stores UserName iformatio i the %msql variable Ope M/SQL Developer Guide

307 Callig Ope M/SQL Objects from M Programs Table 11-9: Parameters Associated with M Form Call Sytax (Cotiued) Parameter paretid iquiry oloop updatestatus callerid default_array curret_array edit_array scroll Meaig If the target form is associated with a child table ad the form is desiged to be called from a kow paret, this parameter must reflect the Row ID of a row i the paret table. Otherwise, it is igored. Set this flag to 1 to specify that the form is to be ru i iquiry mode. Set to 0 for data etry mode. 0 is the default. Set this flag to 1 to tur form loopig OFF. Set to 0 to tur form loopig ON. 0 is the default. This parameter applies to sigle-row database forms oly. You may set this flag as follows: u forces a update of a sigle row. If set to u, you must specify the RowID of a curret row or a paret referece usig the rowid or paretid parameters (parameters 2, 4). i forces row isert. If set to i, the rowid parameter is optioal, ad Ope M/SQL will assig it if oe is specified. d displays a form. If set to d, you must specify the RowID or paret referece of the row you wat to display, uless the form is a form-oly form. Set this flag to the ame of a caller to activate specificatios for variable widow placemet or other uses of the {%caller} variable. Here you may specify a array (actual ame is your choice) to pass i field defaults. For database forms, this applies exclusively to database fields. For o-database forms, it applies to form-oly fields. Here you may specify a array (actual ame is your choice) that will hold curret field values o file after the form is exited. For database forms, this applies exclusively to database fields. For o-database forms, it applies to form-oly fields but oly whe the o-database form files data. Here you may specify a array (actual ame is your choice) that will hold the origial values of fields that were edited. For database forms, this applies exclusively to database fields. For o-database forms, it applies to form-oly fields but oly whe the odatabase form trasacts filig. Set this flag to 1 to activate roll-ad-scroll mode, 0 or NULL for ormal widowig mode. You ca oly activate roll-ad-scroll mode if it is eabled for the curret form i the form-level Advaced Features widow. Ope M/SQL Developer Guide 11-29

308 Chapter 11 Programmer Iterface to Applicatios Callig Reports Programmer-defied M code, icludig routies ad iserted M code, ca ivoke M/PACT reports usig the M report call sytax, as show below: do report^%msql(report_ame,user,device,format,batchsw) where report_ame is the oly required parameter. The parameters are positio-sesitive, which meas that you must assig some value to the first parameter before you ca assig a value to the secod parameter, ad to the secod parameter before you ca assig a value to the third parameter, etc. A ull value will mark a place. You may close the paretheses after the last positively defied parameter, ad Ope M/SQL will assume ull values for all remaiig parameters. The table below lists ad describes the parameters associated with the M report call sytax: Table 11-10: Parameters Associated with M Report Call Sytax Parameter report_ame user device format batchsw Meaig Specify the ame or iteral report idetificatio umber of the report you wat to ru. This is a o-meaigful parameter; Ope M/SQL o loger uses this iformatio. Eter the ull value ( ) to skip this parameter. Note: Ope M/SQL stores UserName iformatio i the %msql variable. Here you may optioally specify the ame of ay valid output device to which your system is liked. Here you may optioally specify the ame of a output format for the specified device. Set this flag to 1 to specify that the report is to be ru i the backgroud. Set to 0 to specify that the report is to be ru i the foregroud. The default is Ope M/SQL Developer Guide

309 Callig Ope M/SQL Objects from M Programs Callig Queries Programmer-defied M code, icludig routies ad iserted M code, ca ivoke Ope M/SQL queries usig the M query call sytax, as show below: do query^%msql(query_ame,user,device,format,batchsw) where query_ame is the oly required parameter. The parameters are positio-sesitive, which meas that you must assig some value to the first parameter before you ca assig a value to the secod parameter, ad to the secod parameter before you ca assig a value to the third parameter, etc. A ull value will mark a place. You may close the paretheses after the last positively defied parameter, ad Ope M/SQL will assume ull values for all remaiig parameters. The table below lists ad describes the parameters associated with the M query call sytax: Table 11-11: Parameters Associated with M Query Call Sytax Parameter query_ame user device format batchsw Meaig Specify the ame or iteral report idetificatio umber of the query you wat to ru. This is a o-meaigful parameter; Ope M/SQL o loger uses this iformatio. Eter the ull value ( ) to skip this parameter. Note: Ope M/SQL stores UserName iformatio i the %msql variable. Here you may optioally specify the ame of ay valid output device to which your system is liked. Here you may optioally specify the ame of a output format for the specified device. Set this flag to 1 to specify that the query is to be ru i the backgroud. Set to 0 to specify that the query is to be ru i the foregroud. The default is 0. Ope M/SQL Developer Guide 11-31

310 Chapter 11 Programmer Iterface to Applicatios Callig Old-Style Meus Programmer-defied M code, icludig routies ad iserted M code, ca ivoke old-style meus usig the M meu (old-style) call sytax, as show below: do meu^%msql(meu_ame,user,logisw,callerid) where meu_ame is the oly required parameter. The parameters are positio-sesitive, which meas that you must assig some value to the first parameter before you ca assig a value to the secod parameter, ad to the secod parameter before you ca assig a value to the third parameter, etc. A ull value will mark a place. You may close the paretheses after the last positively defied parameter, ad Ope M/SQL will assume ull values for all remaiig parameters. The table below lists ad describes the parameters associated with the M meu call sytax: Table 11-12: Parameters Associated with M Meu Call Sytax Parameter meu_ame user logisw callerid Defiitio Specify the ame or iteral report idetificatio umber of the old-style meu you wat to ivoke. This is a o-meaigful parameter; Ope M/SQL o loger uses this iformatio. Eter the ull value ( ) to skip this parameter. Note: Ope M/SQL stores UserName iformatio i the %msql variable. This is a optioal flag that cotrols the appearace of the User Idetificatio widow. Set this flag to 1 to ivoke the User Idetificatio widow before ruig the meu. Set it to 0 to skip the User Idetificatio widow. The default is 0. You may optioally set this parameter to a particular CallerID to activate ay coditios associated with the meu that are based o a certai value beig held by the {%caller} variable. Callig Meu Objects Programmer-defied M code, icludig routies ad iserted M code, ca ivoke meu objects i either of two ways: Usig a meu call etry poit Usig the meu object s routie ame Ope M/SQL Developer Guide

311 Callig Ope M/SQL Objects from M Programs Callig Meu Objects Usig a Meu Call Etry Poit The meu call etry poit uses the followig sytax: do meuobj^razm3(im,fmtype,tmtype) The followig table lists ad describes the parameters associated with the meu call etry poit: Table 11-13: Parameters Associated with the Meu Call Etry Poit Parameter im fmtype tmtype Meaig This parameter is required. Eter either the iteral idetificatio umber or the ame of the meu object you wat to ivoke. Note: If you idetify the meu object by its ame, you must use quotatio marks to delimit the strig. This is a optioal parameter that you may use to declare the type of meu from which the meu you are callig is beig called. You may eter the followig: 0 or NULL Pop-Up Meu 1 Meu Bar This is useful whe you have programmed a meu to respod i certai ways depedig o the meu type of its callig meu, a value which is stored i the {%meutype} system variable. This is a optioal parameter that you may use to declare the mode i which you wat to ivoke this meu. You may eter the followig: 0 or NULL Pop-Up Meu 1 Meu Bar Callig a Meu Object By Its Routie Name Alteratively, you may call a meu object directly from M code usig its routie ame. To do so, you must kow the routie prefix for the meu object (the routie ame is formed by the cocateatio of the routie prefix ad the umber 1.) Whe you call a meu object by its routie ame, you may optioally pass i a value for the Caller ID. To call a meu object by its routie ame, use the followig sytax. do ^<routie_prefix>1(callerid) For example, if your pop-up meu prefix is mp1, ad you wat to pass i a Caller ID of Admissios, you would issue the followig: > do ^mp11( Admissios ) Ope M/SQL Developer Guide 11-33

312 Chapter 11 Programmer Iterface to Applicatios Emulatig Form Behavior from M Programs Ope M/SQL provides several utility etry poits to the Ope M/SQL routie %msql that allow programmer-defied M code to emulate the behavior of Ope M/SQL forms. The table below lists ad describes these etry poits to %msql: Table 11-14: Etry Poits For Emulatig Form Behavior Etry Poit help^%msql write^%msql $$read^%msql widcl^%msql Fuctio Displays scrollig help text i a box. Writes a message o the scree. Reads a data value. Cleas up scree by erasig the residual display of widows after they have bee exited. Like the etry poits for ivokig Ope M/SQL objects, these utility etry poits allow you to pass certai required ad o-required parameters. I all cases, the parameters are positio-sesitive, which meas that you must assig some value to the first parameter before you ca assig a value to the secod parameter, ad to the secod parameter before you ca assig a value to the third parameter, etc. A ull value will mark a place. You may close the paretheses after the last positively defied parameter, ad Ope M/SQL will assume ull values for all remaiig parameters. Displayig Help Text i a Help Text Box You may use the help^%msql utility etry poit to display oe or more lies of help text i a bordered box at a specified locatio o the scree. This etry poit uses the followig sytax: do help^%msql(helpref,x,y) where helpref is the oly required parameter Ope M/SQL Developer Guide

313 Emulatig Form Behavior from M Programs The table below lists ad describes the parameters associated with the help^%msql utility: Table 11-15: Parameters Associated with help^%msql Utility Parameter helpref x,y Meaig Here you must specify a referece to the variable or global ode that cotais the lies of help text you wat to display. Here you may optioally specify the coordiates for drawig the upper left corer of the help box. The value of x ca rage from 1 to 80, ad the value of y ca rage from 1 to 24. The upper left corer of the scree is represeted by the coordiates (1,1). The x ad y coordiates must both be o-ull, or they must both be ull. If they are both ull, the utility uses the curret cursor positio, as reflected i the variables $x ad $y, i.e. x=$x+1, y=$y+1. The help^%msql utility automatically draws a box that is large eough to accommodate all the help text that you provide, uless there is isufficiet space o the scree below the startig positio of the box to accommodate the help text. If there is isufficiet space, the help text will scroll. I a scrollig help text box, users may use the <UP ARROW> ad <DOWN ARROW> as well as <PREVIOUS SCREEN> ad <NEXT SCREEN> keystrokes to avigate the help text lies. For example, the followig call to help^%msql: >do help^%msql( ^rh(12,6),20,10) displays help text lies as follows: ^rh(12,6,1)=first lie ^rh(12,6,2)=secod lie... i as large a box as ecessary with its upper left corer at scree positio (20,10). Writig Message Text The write^%msql utility etry poit writes a message to the scree usig the same covetios for timeout ad erase as used by Ope M/SQL forms. This etry poit uses the followig sytax: do write^%msql(message,timeoutsec,erasesw,x,y) where message is the oly required parameter. Ope M/SQL Developer Guide 11-35

314 Chapter 11 Programmer Iterface to Applicatios The table below lists ad describes the parameters associated with the write^%msql utility: Table 11-16: Parameters Associated with write^%msql Utility Parameter message timeoutsec erasesw x,y Meaig Here you must specify the text of the message you wat to write to the scree. You must eclose the message text i quotatio marks. Here you may optioally specify a umber of secods to wait for a read after the message is prited. If you set the timeout to a umber greater tha 0, the cursor will pause for the specified umber of secods (or util the user presses a key), ad the retur. If you set the timeout to 0 or ull, the cursor will retur immediately after pritig the message. Here you may set a flag to specify whether the utility should erase the message before returig. Set this flag to 1 to erase the message before returig. Note: You should use this parameter i cojuctio with a timeoutsec value greater tha 0. Here you may optioally specify the coordiates for the cursor positio at which to start the message. The value of x ca rage from 1 to 80, ad the value of y ca rage from 1 to 24. The upper left corer of the scree is represeted by the coordiates (1,1). The x ad y coordiates must both be o-ull, or they must both be ull. If they are both ull, the utility uses the curret cursor positio, as reflected i the variables $x ad $y, i.e. x=$x+1, y=$y+1. Readig Fields The $$read^%msql utility etry poit mimics the behavior of a field o a Ope M/SQL form. This fuctio displays a text captio ad a data etry slot of defiable legth to the scree at specified coordiates. It the reads i the data value iput by the user. It supports both editig ad horizotal scrollig capabilities. This etry poit uses the followig sytax: set <glv>=$$read^%msql(prompt,x,y,scrle,maxle,default) where <glv> is a global or variable ame ad prompt is the oly required parameter. The table below lists ad describes the parameters associated with the $$read^%msql utility: Ope M/SQL Developer Guide

315 Emulatig Form Behavior from M Programs Table 11-17: Parameters Associated with $$read^%msql Utility Parameter prompt x,y scrle maxle default Meaig Here you may specify the text of the captio that precedes the field s data etry slot. This is a required parameter, though you may set it to ull to ot display a captio. Note: Ope M/SQL automatically draws the data etry slot usig uderscores. Here you may optioally specify the coordiates for the cursor positio at which to start displayig the captio text. The value of x ca rage from 1 to 80, ad the value of y ca rage from 1 to 24. The upper left corer of the scree is represeted by the coordiates (1,1). The data etry slot begis oe space after the prompt or, if prompt is ull, at the specified (x,y) coordiates. The x ad y coordiates must both be o-ull, or they must both be ull. If they are both ull, the utility uses the curret cursor positio, as reflected i the variables $x ad $y, i.e. x=$x+1, y=$y+1. Here you may optioally specify the legth of the field s data etry slot o the scree. This value caot exceed the value for the maxle parameter. It also caot exceed the value of 80 mius the legth of the prompt parameter. If this value is less tha the value for the maxle parameter, the field allows horizotal scrollig. If this value is ull, maxle is assumed to be ull also. Here you may optioally specify the maximum legth for a field value. Here you may specify a optioal default value for the field. Ope M/SQL Developer Guide 11-37

316 Chapter 11 Programmer Iterface to Applicatios Cleaig Up Widows You ca use the Widow Cleaup fuctio (widcl^%msql) to erase widows from the scree after they have bee exited. This fuctio helps to resolve problems related to the residual display of widow graphics after a widow has bee exited. I Ope M/SQL, wheever a user exits a widow, the system schedules the widow to be erased at the ext opportue momet. Opportue momets ormally occur before a ew widow is paited, or whe the cursor is sittig o a prompt waitig for user iput. While this is sufficiet i most situatios, sometimes it causes the erasure of widows to be delayed. This ca be especially troublig if you are usig M code or routies as a itermediary betwee Ope M/SQL objects. For example, suppose a meu object calls a M routie, ad i tur the M routie makes calls to various form routies. As each of the forms is exited, it is possible for residual istructios that erase widows o the form to be left uresolved util such time as aother form is called. This ca cause strage behavior, such as widows trasietly flashig o the scree, or portios of widows from the previously called form remaiig uerased. The Widow Cleaup fuctio erases all widow graphics associated with ay object that has bee exited ad is, therefore, waitig i the erase queue. The Widow Cleaup fuctio uses the followig sytax: do widcl^%msql There are two cases after a widow/meu object is exited where the Widow Cleaup fuctio does ot have ay effect: 1. The widow/meu object is set to ot erase upo exit 2. A user exits via the GETOUTALL actio I these cases, Ope M/SQL does ot schedule ay widows for erasure, therefore the Widow Cleaup actio has o effect. Note Wheever you call a form or meu object directly from M code, you should always check the value of the %r variable upo returig to the M routie. If %r>103, this idicates that the user exited via a GETOUTALL actio, i which case the M routie should quit immediately. This is importat because whe a user exits via a GETOUTALL actio, Ope M/SQL does ot schedule ay widows to be erased. Therefore, if the M routie calls aother form or meu object, it may ecouter uerased scree clutter from the previous form/meu object Ope M/SQL Developer Guide

317 Establishig Authorizatio ID from Programmer Mode Establishig Authorizatio ID from Programmer Mode Ope M/SQL requires that each user have a Ope M/SQL Authorizatio ID i order to use the system. The Authorizatio ID is a character strig that idetifies the curret user to Ope M/SQL ad recalls the Ope M/SQL privileges ad setup parameters assiged to that user. All Ope M/SQL security is based o the Authorizatio ID. Ope M/SQL stores the Authorizatio ID of the curret user i the %msql variable. Typically, users establish their Authorizatio IDs by eterig a UserName ad Password ito the User Idetificatio widow, which Ope M/SQL displays durig logi. However, users may also establish their Authorizatio IDs by settig %msql directly from M. To pass the Authorizatio ID directly ito %msql, issue a commad usig the followig sytax at the M prompt before eterig Ope M/SQL: > do setaid^%msql( <UserName> ) where <UserName> is a UserName that is registered i the User Table. For example: > do setaid^%msql( Zeus ) Note Whe settig the Authorizatio ID this way, you do ot eed to specify a password. After issuig this commad, user Zeus ca log i to Ope M/SQL by typig the followig commad: > do ^%msql If the value passed ito %msql correspods to a valid UserName, Ope M/SQL ackowledges all developmet eviromet access privileges ad object-level privileges assiged to that user. If the value passed ito %msql does ot correspod to a valid UserName, Ope M/SQL gives the user a Authorizatio ID of ukow. Users classified as ukow are limited to miimal developmet eviromet access privileges (basically, ru-time access oly) ad have object privileges oly for those objects o which privileges are grated to user _PUBLIC. If a user passes his/her Authorizatio ID directly ito %msql, Ope M/SQL does ot display the User Idetificatio widow at user logi. Ope M/SQL Developer Guide 11-39

318 Chapter 11 Programmer Iterface to Applicatios Itermixig Ope M/SQL Objects with User-Defied M Routies Ope M/SQL provides a programmer utility called %msqlutl that helps to prevet potetial coflicts betwee user-defied M routies ad critical Ope M/SQL variables. Curretly, %msqlutl supports three fuctios called by the followig etry poits: pushvars^%msqlutl popvars^%msqlutl $$msqlvars^%msqlutl pushvars^%msqlutl The pushvars^%msqlutl fuctio protects critical Ope M/SQL variables by pushig them out oto a stack. You should use this etry poit prior to ivokig ay user-defied M code that might potetially kill or overwrite some of these variables. You ca call this etry poit i either of two modes: 1. Local Variables mode I Local Variables mode, pushvars^%msqlutl pushes oly those variables which are local to specific Ope M/SQL objects, while leavig itact Ope M/SQL global variables, which are eeded to commuicate betwee various Ope M/SQL objects. To call pushvars^%msqlutl i Local Variables mode, use the followig sytax: do pushvars^%msqlutl(0) Or, whe ruig Ope M/SQL o a DTM system, use the followig sytax: do pushvars^%msqlutl(0) You may wat to use this mode whe your applicatio is executig some combiatio of user-defied routies ad Ope M/SQL objects, as for example i the followig sequece of evets: User Routie --> Meu Object --> User Routie --> Form Ope M/SQL Developer Guide

319 Itermixig Ope M/SQL Objects with User-Defied M Routies popvars^%msqlutl 2. All Variables mode I All Variables mode, pushvars^%msqlutl pushes ot oly the local Ope M/SQL variables but the global variables as well. To call pushvars^%msqlutl i All Variables mode, use the followig sytax: do pushvars^%msqlutl(1) Or, whe ruig Ope M/SQL o a DTM system, use the followig sytax: do pushvars^%msqlutl(1) You may wat to use this mode whe your applicatio is callig from a Ope M/SQL object ito a user-defied routie ad does ot ivoke ay other Ope M/SQL objects, as for example i the followig sequece of evets: Meu Object -> UserRt1 -> UserRt2 -> UserRt3 The popvars^%msqlutl fuctio reistates the Ope M/SQL variables which have bee pushed out oto a stack. You should use this etry poit whe returig from user-defied code after a previous call to pushvars^%msqlutl. popvars^%msqlutl accepts o argumets. To call popvars^%msqlutl, use the followig sytax: do popvars^%msqlutl Or, whe ruig Ope M/SQL o a DTM system, use the followig sytax: do popvars^%msqlutl Ope M/SQL Developer Guide 11-41

320 Chapter 11 Programmer Iterface to Applicatios $$msqlvars^%msqlutl The $$msqlvars^%msqlutl fuctio displays a list of critical Ope M/SQL global variables which must ever be killed or overwritte by user-defied M code. You might use this fuctio as a argumet for a exclusive kill list, for example: SET list=$$msqlvars^%msqlutl KILL(list) The list of critical Ope M/SQL variables stored by the $$msqlvars^%msqlutl fuctio icludes the followig: db,%dir,%dir,fro,h,kt,%is,lag,%mode,%msql,%mstack,%mw, %mwo,%r,%rdsm,repait,%tras,%volset,%wa,%wbvats,%we, %wft,%wh,%wipe,%wmb,%wr,%ws Ope M/SQL Developer Guide

321 Cotets of Applicatios Cotets of Applicatios Routie Names The remaider of this chapter describes the routies ad globals that comprise base tables, forms, meu objects, old-style meus, reports, ad queries. Each form, meu object, report, or pre-defied query must be compiled before it ca be ru. Note Old-style meus do ot require compilatio. Furthermore, each base table associated with a form, report, or query must be compiled before the form, report, or query ca be compiled. Compilatio geerates a set of executable routies. These routies perform fuctios such as lookup ad filig for a base table, drawig widows for a form, ad pritig output ad calculatig totals for a report. Machie requiremets limit the maximum size of a sigle routie. If more code is eeded tha ca fit i a sigle routie, Ope M/SQL geerates multiple routies. To esure compatibility across implemetatios, IterSystems recommeds that you limit the maximum size of a sigle routie to 8KB, though this limit is ot uiversal. Each base table, form, meu object, report, ad query has a routie prefix used to produce the ames of all of its associated routies whe it is compiled. The routie prefix is a alphaumeric ame (leadig character alphabetic) with a maximum legth of 7 characters. Whe defiig a object, you have the optio of specifyig a customized routie prefix or acceptig the default routie prefix. Ope M/SQL creates full routie ames by appedig a sigle character to this prefix. The followig table shows the default routie ame prefixes for all compilable objects: Table 11-18: Default Routie Name Prefixes Object Table Form Meu Bar Pop-Up Meu Report Query Default Prefix mt mw mb mp mr mq where is a oe-character uique idetifier appeded by the compiler. Ope M/SQL Developer Guide 11-43

322 Chapter 11 Programmer Iterface to Applicatios The compiler geerates the oe-character uique idetifier i the sequece 1-9, followed by uppercase A-Z, followed by lowercase a-z. This amouts to a maximum of 61 distict routie ames that ca be associated with a particular base table, form, meu object, query, or report. For example, give a base table with the routie prefix rtame, the compiler geerates the followig cosecutive routie ames: rtame1... rtame9 rtamea... rtamez rtamea... rtamez If you chage the routie prefix of a base table, form, meu object, report, or query, you must be sure that the routie ames geerated from the ew routie prefix do ot cause coflicts with ay existig user-defied routie ames. Ope M/SQL will ot detect these coflicts. For example, you should ot assig the routie prefix rdf to ay object i a directory that cotais user-defied routie ames such as rdf1, rdff, or rdfx, etc. You may, however, assig the routie prefix rdf to a object i a directory that cotais a user-defied routie called rdf11, sice the compiler geerates routie ames by appedig oly oe character to the routie prefix. Note Whe you chage a routie prefix, Ope M/SQL does NOT delete the routies with ames that begi with the old prefix. Cotets of Base Table Routies The compiled routies for a Ope M/SQL base table cotai all of the followig: Filig code for INSERT, UPDATE, ad DELETE operatios, icludig data type ad other validatio checkig ad iteral/exteral coversio code. A compiled SQL query for retrievig the old values for a row, which is used durig UPDATE operatios to determie which values have chaged. This query is called the Update Query for the base table. A compiled SQL query for each base table field specified as Uique i the base table defiitio, which is used to determie whether aother row exists with a idetical value. This query is called the Uiqueess Query for a base table field Ope M/SQL Developer Guide

323 Cotets of Applicatios Compiled SQL queries for default lookup specificatios (row selectio criteria), which are used by forms to select rows from the base table. Compiled M code or a SQL statemet for each base table trigger item. Etry Poits to Primary Base Table Routie The first compiled routie for a base table, whose ame is the table s routie prefix cocateated with 1, cotais three etry poits to the filig operatios for the base table (isert, update, ad delete). These filig etry poits operate o base table rows by callig the associated SQL statemet, e.g. INSERT, UPDATE, or DELETE. You should ot call these etry poits directly from the M programmer prompt. The tags for the three filig etry poits are: Table 11-19: Filig Etry Poits to Primary Base Table Routie Etry Poit isert update delete Fuctio M code that validates ad the iserts a ew row ito the base table. M code that validates ad the updates a base table row. M code that validates ad the deletes a row from the base table. Base Table Defiitio Globals Ope M/SQL stores additioal iformatio about base tables i the ^mdd ad ^mddc globals, as described i the followig table: Table 11-20: Storage of Base Table Iformatio Global ^mdd(1,ir) ^mddc(1,ir) Cotets Stores base table iformatio, where ir is a uique idetifyig umber for the base table. Stores iformatio about the compiled base table routies. Ope M/SQL Developer Guide 11-45

324 Chapter 11 Programmer Iterface to Applicatios Cotets of Form Routies The compiled routies for a Ope M/SQL form cotai all code ecessary to ru the form, icludig the followig: Code to draw each widow i the form ad hadle user iteractio with data etry fields. Compiled SQL queries for lookup specificatios (row selectio criteria) to select rows from the base table associated with the form. Compiled M code or a SQL statemet for each form, widow, ad field trigger. Form Defiitio Globals Ope M/SQL stores additioal iformatio about forms i the ^mform ad ^mformc globals, as described i the followig table: Table 11-21: Storage Of Form Iformatio Global ^mform(iform) ^mformc(iform) Cotets Stores form, widow, ad form field iformatio for the form, where iform is a uique form idetifier. Stores iformatio about the compiled form routies. Cotets of Meu Object Routies The compiled routies for a Ope M/SQL meu object cotai the followig: Code to draw meu bars or pop-up meus ad hadle user iteractio with data etry fields. Meu Object Defiitio Globals Ope M/SQL stores additioal iformatio about meu objects i the ^mobject global, as described i the followig table: Table 11-22: Storage Of Meu Object Iformatio Global ^mobject( object, meu,im) Cotets Stores iformatio about the compiled meu object routies Ope M/SQL Developer Guide

325 Cotets of Applicatios Cotets of Old-Style Meu Routies Old-style meus do ot require compilatio; therefore Ope M/SQL does ot geerate ay compiled routies for them. Ope M/SQL stores all iformatio about old-style meus i the global ^mmeu(imeu), where imeu is a uique meu idetifier. Cotets of Report Routies The compiled routies for a M/PACT report cotai compiled SQL queries ad the ecessary code to calculate subtotals, totals, ad all user-defied code (e.g. computed fields) ad to prit headers, trailers, ad all data. Report Defiitio Globals Ope M/SQL stores additioal iformatio about reports i the ^mreport ad ^mreportc globals, as described i the followig table: Table 11-23: Storage Of Report Iformatio Global ^mreport(ireport) ^mreportc(0,ireport) Cotets Stores report iformatio where ireport is a uique report idetifier. Stores iformatio about the compiled report routies. Cotets of Query Routies The compiled routies for a pre-defied query created via the Query Geerator or Iteractive Query Editor cotai compiled SQL queries ad the ecessary code to prit the query results. Ope M/SQL stores additioal iformatio about the query i the global ^mql(iquery), where iquery is a uique query idetifier. Ope M/SQL Developer Guide 11-47

326 Chapter 11 Programmer Iterface to Applicatios Ope M/SQL Developer Guide

327 CHAPTER Ope M/SQL Developer Utilities 12 Ope M/SQL provides a group of utilities to help applicatio programmers maage their Ope M/SQL applicatios. These utilities are available o the Developer Utilities meu, which is accessible via a optio o the Ope M/SQL Mai Meu. This chapter describes how to use each of the utilities o this meu. Specifically, it covers the followig topics: Accessig the Developer Utilities Meu Usig the Object Compile Driver Utility Checkig the Itegrity of Ope M/SQL Objects Searchig for Strigs i Ope M/SQL Objects Ivokig Macro Source Routie Utilities Queryig Objects by Routie Prefix Natioal Laguage Reports Ope M/SQL Developer Guide 12-1

328 Chapter 12 Ope M/SQL Developer Utilities Accessig the Developer Utilities Meu The Developer Utilities meu cotais utilities that ca help you maage your Ope M/SQL applicatios. Procedure To access the Developer Utilities meu: 1. At the M programmer prompt, type the followig commad to eter Ope M/SQL: > do ^%msql You see the Ope M/SQL Mai Meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄOpe M/SQL MeuÄÄÄ ³ ³ ³ Data Dictioary ³ ³ Forms ³ ³ Reports ³ ³ Queries ³ ³ Meu Geerator ³ ³ System Maagemet ³ ³ Privileges ³ ³ Developer Utilities ³ ³ User Utilities ³ ³ Server Maagemet ³ ³ Relatioal Gateway ³ ³ Help Optios ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Jul 05, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio Ope M/SQL Meu 03:50PM Press <Help> For Help 2. From the Ope M/SQL Mai Meu, select the Developer Utilities optio. Note: You may type v to select this optio it is a memoic accelerator Ope M/SQL Developer Guide

329 Accessig the Developer Utilities Meu You see the Developer Utilities meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄÄM/SQL Developer UtilitiesÄÄÄÄ ³ ³ ³ Export/Import Optios ³ ³ Object Compile Driver ³ ³ M/SQL Object Itegrity Checkig ³ ³ Object Strig Search Utility ³ ³ Full Scree Editor ³ ³ Macro Routie Utilities ³ ³ Query Object By Routie Prefix ³ ³ Natioal Laguage Reports ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Jul 05, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio M/SQL Developer Utilities 03:50PM Press <Help> For Help Note: The Database Admiistrator ca restrict users from accessig the Developer Utilities meu by disablig the Developer Utilities optio i the User Security Defiitio form. The followig table lists ad describes the optios located o the Developer Utilities meu: Table 12-1: Optios o Developer Utilities meu Optio Export/Import Optios Object Compile Driver utility Object Itegrity Checker utility Descriptio Select this optio to use the Export/Import utility (EIU), a automated, widow-based utility that allows you to port Ope M/SQL object defiitios betwee differet directories ad differet computers. We do ot documet the use of the Export/Import utility i this guide. For complete documetatio o how to use this utility, see the Ope M/SQL Database Admiistrator s Guide. Select this optio to use the Object Compile Driver utility, which allows you to defie compilatio cofiguratios for groups of multiple objects or etire applicatios. Whe you ru a compilatio cofiguratio, it batch-compiles the code for all icluded objects. Select this optio to use the Object Itegrity Checker utility. This utility checks the itegrity of specified object defiitios or groups of object defiitios i the curret directory ad geerates a report of all itegrity errors that it fids. You ca also set the Itegrity Checker to automatically correct some of the itegrity errors it fids. Ope M/SQL Developer Guide 12-3

330 Chapter 12 Ope M/SQL Developer Utilities Table 12-1: Optios o Developer Utilities meu (Cotiued) Optio Object Strig Search utility Full Scree Editor Macro Routie Utilities Query Object By Routie Prefix Natioal Laguage Reports Descriptio Select this optio to use the Object Strig Search utility. This utility searches through specified object defiitios for a specified text strig. Select this optio to eter the Full Scree Editor eviromet, where you may create ad edit routies. Whe you exit the Full Scree Editor, you retur to the Developer Utilities meu. Selectig this optio ivokes a submeu called Routie Utilities. The Routie Utilities submeu displays a list of Ope M/SQL routie utilities. You may select ay optio o the Routie Utilities submeu to ivoke ad use the correspodig routie utility. Whe you exit the routie utility, you retur to the Routie Utilities meu. Select this optio to access the Object Routie Prefix utility. This utility lets you look up ay Ope M/SQL routie prefix to obtai iformatio about where the routie is beig used. Select this optio to prit the Natioal Laguage Report, which displays the traslatios provided for all system-geerated messages, key labels, meu titles, ad meu optio text throughout the Ope M/SQL eviromet Ope M/SQL Developer Guide

331 Usig the Object Compile Driver Utility Usig the Object Compile Driver Utility The Object Compile Driver utility lets you defie ad store lists of Ope M/SQL objects for serial compilatio. Usig this utility, you ca recompile large sectios of your applicatio or all of your applicatio, with a sigle commad. To use the Object Compile Driver utility, you create ad store compilatio cofiguratios. Each compilatio cofiguratio ca iclude multiple objects of all of the followig types: Base Tables Forms Meu Objects Reports Queries Routies Whe you compile a Object Compile Driver cofiguratio, you batch-compile all icluded objects. The Object Compile Driver utility is available as a optio o the Developer Utilities meu. Procedure To use the Object Compile Driver utility: 1. From the Developer Utilities meu, select the Object Compile Driver optio. You see the Object Compile Driver lookup widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile DriverÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ ³ ³ ³ ³ Cofiguratio Name ³ ³ ³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÙ Ope M/SQL Developer Guide 12-5

332 Chapter 12 Ope M/SQL Developer Utilities Object Compile Driver Selectig Press <Help> For Help 2. At the Cofiguratio Name field i the Object Compile Driver lookup widow, eter a cofiguratio ame, ad press <RETURN>. You ca retrieve a existig compilatio cofiguratio to edit or create a ew oe. To retrieve a existig compilatio cofiguratio, eter a complete or partial ame, ad press <RETURN>. You see a lookup box that lists all matchig etries. To see a lookup box that lists all existig etries, leave the Cofiguratio Name field blak ad press the <SEARCH CURRENT TABLE> key. Use the cursor positioig keys to avigate withi the lookup box, ad press <RETURN> to select a etry. To create a ew compilatio cofiguratio, eter a ew cofiguratio ame (it must ot match the ame of ay existig compilatio cofiguratio). You see the Is this a NEW Object Compilatio Cofiguratio? dialog box, as show below:. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile DriverÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ ³ ³ ³ ³ Cofiguratio Name Sample Cofiguratio ³ ³ ³ ³ ³ ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄij Is this a NEW Object Compilatio Cofiguratio? ³ÄÄÄÄÄÄÄÄÄÄÄÄÙ ³ ³ ³ < Yes > < No > ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Object Compile Driver Selectig Press <Help> For Help Here, you may create a ew compilatio cofiguratio by pressig <RETURN> o the <Yes> actio field Ope M/SQL Developer Guide

333 Usig the Object Compile Driver Utility Whe you have etered a cofiguratio ame (either ew or existig), the Object Compile Driver widow fills out with its complete set of fields, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile DriverÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Set Compilatio Optio Defaults ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ Cofiguratio Name Sample Cofiguratio ³ ³ ³ ³ < Edit Cofiguratio > < Compile Cofiguratio > < Last Compile Results >³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Object Compile Driver Usaved Data Press <Help> for Help The table below lists ad describes the fields located o the Object Compile Driver widow: Table 12-2: Fields o Object Compile Driver widow Field Cofiguratio Name <Edit Cofiguratio> <Compile Cofiguratio> <Last Compile Results> Descriptio Here you may edit the ame specified for compilatio cofiguratio i the lookup widow. Names may rage from 1 to 40 characters i legth ad may cotai ay alphaumeric or puctuatio characters, icludig uderscores ad blak spaces. This is a required field. Press <RETURN> o this actio field to access the Object Compile Driver Items widow, where you may defie the cotets of your compilatio cofiguratio. Press <RETURN> o this actio field to ru the compilatio cofiguratio. Press <RETURN> o this actio field to access the Object Compile Driver Results widow, where you review the results from the last time the curret compilatio cofiguratio was compiled. Ope M/SQL Developer Guide 12-7

334 Chapter 12 Ope M/SQL Developer Utilities Settig Compilatio Optio Defaults For each compilatio cofiguratio you create, you may set up a series of compilatio optio defaults to cotrol how Ope M/SQL compiles the various objects i the list. These compilatio optio defaults operate o a cofiguratio-wide basis, i.e., they affect either all objects defied i the etire compilatio list or all objects of a certai object type defied i the list. You ca edit these compilatio optio defaults at ay time. Procedure To set defaults for compilatio optios: 1. From the Object Compile Driver widow, press the <ENHANCE><ENHANCE> keystroke sequece to access the Object Compile Driver meu bar. 2. From the Object Compile Driver meu bar, select the Set Compilatio Optio Defaults optio. Note: This is the oly optio o the Object Compile Driver meu bar. You see the Compilatio Optios widow, as show below: ÚÄÄÄÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄCompilatio OptiosÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄ ³ Se³ ³ ³ ³ÄÄij Cofiguratio Wide Settigs ³ÄÄÄij ³ ³ ³ ³ ³ ³ Compile for Vedor IterSystems ³ ³ ³ ³ ³ ³ ³ <³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Äijts >³ ³ ³ Form Compilatio Default Optios ³ ³ ÀÄÄij ³ Compile Usig Local Storage? Same as Last Compile ³ ³ Compile Tied Meu Objects? Same as Last Compile ³ ³ÄÄÄÄÙ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Äij ³ Meu Object Compilatio Default Optios ³ ³ ³ ³ Meu Object Compile Type? Same as Last Compile ³ ³ Compile Usig Local Storage? Yes_ ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Äij ³ Routie Compilatio Default Optios ³ ³ ³ ³ Check Routie's Sytax? Yes_ ³ ³ File Routie's Object Code? Yes_ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÙ Eter the vedor to compile the objects for. Press <CHOICE> for list Ope M/SQL Developer Guide

335 Usig the Object Compile Driver Utility The followig table lists ad describes the fields o the Compilatio Optios widow: Table 12-3: Fields o Compilatio Optios Widow Field Compile for Vedor Compile Usig Local Storage? Defiitio Here you specify the ame of the M implemetatio for which you wat to compile the objects i your compilatio list. You may choose amog the followig M implemetatios: DSM DTM IterSystems MSM The host M system o which you are curretly ruig is the default respose. Whe you ru a compilatio cofiguratio, Ope M/SQL geerates itermediate code for the M implemetatio you specify here. This optio gives you the ability to compile the objects i your compilatio list for a M implemetatio other tha the oe you are curretly usig. You ca use this optio to geerate itermediate code for a applicatio before movig it to a ru-time eviromet o aother M system. For example, you might wat to develop your applicatio o a IterSystems UNIX platform ad ru your applicatio o a PC with DTM. To do this, you could build a compilatio cofiguratio for the complete applicatio ad compile it for DTM, the move the globals ad the.int code for the compiled routies from the UNIX machie to the PC. The Local Storage optio is desiged to help you avoid situatios where <STORE> errors occur durig the compilatio of a form due to the buildig of large queries. If you aswer No to this field, Ope M/SQL compiles all forms icluded i the compilatio list usig globals ad ot i local storage. This protects agaist <STORE> errors but slows compilatio time. If you aswer Yes to this field, Ope M/SQL compiles all forms icluded i the compilatio list usig local arrays. This makes the compilatio faster. Whe the forms you are compilig are ot uusually large or complex, you ca safely capitalize o the speed advatages of usig local storage. If, however, you ecouter a <STORE> error while compilig i local storage, you should chage your respose to No. If you aswer Same as Last Compile, Ope M/SQL compiles every form the same way it was last compiled. Same as Last Compile is the default respose. Objects Affected All objects i list Forms oly Ope M/SQL Developer Guide 12-9

336 Chapter 12 Ope M/SQL Developer Utilities Table 12-3: Fields o Compilatio Optios Widow (Cotiued) Field Defiitio Objects Affected Compile Tied Meu Objects? Here you may aswer Yes, No, or Same as Last Compile to idicate whether or ot you wat Ope M/SQL to recompile meu objects that are tied to the forms i your compilatio list. I order to be recompiled uder this optio, a meu object must be explicitly tied to the form, ot just attached to it. Note: This optio oly applies to forms that are compiled as NEW. Same as Last Compile is the default respose. Forms oly Meu Object Compile Type Here you may specify how you wat Ope M/SQL to compile the meu objects i your compilatio list. Press the <LIST CHOICES> key to see a list of the meu object compilatio optios from which you may choose. They iclude: Pop-Up Meu Compile all meu objects as pop-up meus. Meu Bar Compile all meu objects as meu bars. Both Pop-Ups ad Meu Bars Compile all meu objects as both pop-up meus ad meu bars. Same as Last Compile Compile all meu objects the same way as they were last compiled. The default optio is Same as Last Compile. Meu Objects oly Compile Usig Local Storage? Here you may aswer Yes or No to idicate whether or ot you wat to compile the meu objects icluded i your compilatio list usig local storage. Aswer Yes to compile meu objects usig local arrays. This makes the compilatio faster but may cause <STORE> errors to occur. Aswer No to compile meu objects usig globals. This prevets space allocatio errors but makes the compilatio slower. Yes is the default respose. Meu Objects oly Check Routie s Sytax? Aswer Yes or No to specify whether or ot you wat Ope M/SQL to perform sytax checkig o the routies icluded i your compilatio list. Yes is the default respose. Routies oly File Routie s Object Code? Aswer Yes or No to specify whether or ot you wat Ope M/SQL to file the object code geerated by compilig the routies icluded i your compilatio list. Yes is the default respose. Routies oly Ope M/SQL Developer Guide

337 Usig the Object Compile Driver Utility 3. I the Compile for Vedor field, specify the ame of the M implemetatio for which you wat to compile the objects i your compilatio list. The host M system o which you are curretly ruig is the default respose. Note: You may compile for a M implemetatio other tha the oe you are curretly usig. 4. At the Use Local Storage Durig Compile field, aswer Yes, No, or Same as Last Compile to idicate whether you wat to compile the forms icluded i your compilatio list usig local arrays or globals. This field applies oly to forms beig compiled as NEW. Same as Last Compile is the default respose. 5. At the Recompile Ay Tied Meu Objects? field, aswer Yes, No, or Same as Last Compile to recompile meu objects that are explicitly tied to the forms i your compilatio list. Same as Last Compile is the default respose. 6. At the Meu Object Compile Type field, select a optio to idicate how you wat Ope M/SQL to compile the meu objects icluded i your compilatio cofiguratio. You may press the <LIST CHOICES> key to see a lookup box that lists the meu object compilatio optios from which you may choose. They iclude: Pop-Up Meu Meu Bar Both Pop-Ups ad Meu Bars Same as Last Compile Same as Last Compile is the default respose. 7. At the Compile Usig Local Storage? field, aswer Yes or No to idicate whether you wat to compile the meu objects icluded i your compilatio list usig local arrays or globals. Yes is the default respose. 8. At the Check Routie Sytax? field, Aswer Yes or No to specify whether or ot you wat Ope M/SQL to perform sytax checkig o the routies icluded i your compilatio list. Yes is the default respose. Ope M/SQL Developer Guide 12-11

338 Chapter 12 Ope M/SQL Developer Utilities 9. At the File Routie s Object Code? field, Aswer Yes or No to specify whether or ot you wat Ope M/SQL to file the object code geerated by compilig the routies icluded i your compilatio list. Yes is the default respose. 10. Whe you fiish defiig the compilatio optios for your compilatio cofiguratio, press the <PROCEED> key to save your defiitios ad exit the Compilatio Optios widow. Defiig the Cotets of a Compilatio Cofiguratio Your compilatio cofiguratio ca iclude multiple objects the followig types: Base Tables Forms Meu Objects Reports Queries Routies You may add as may objects to your compilatio cofiguratio as you wish. You do ot eed to have privileges o a object to iclude it i your compilatio cofiguratio. Procedure To defie the cotets of a compilatio cofiguratio: 1. From the Object Compile Driver widow, press <RETURN> o the <Edit Cofiguratio> actio field Ope M/SQL Developer Guide

339 Usig the Object Compile Driver Utility You see the Object Compile Driver Items widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile DriverÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Set Compilatio Optio Defaults ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ Cofiguratio Name Sample Cofiguratio ³ ³ ³ ³ < Edit Cofiguratio > < Compile Cofiguratio > < Last Compile Results >³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile Driver ItemsÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Object Type Object Name Compile? ³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÄÙ Object Compile Driver Items Press <Help> For Help The table below lists ad describes the fields located o the Object Compile Driver Items widow: Table 12-4: Fields o Object Compile Driver Items widow Field Object Type Object Name Descriptio Here you specify the type of the object you wat to add to the compilatio list. Press the <LIST CHOICES> key to see a list of the object types from which you may choose. They iclude: Base Tables Forms Meu Objects Reports Queries Routies Here you specify the ame of the particular object you wat to add to your compilatio list. Press the <LIST CHOICES> key to see a list of all objects (of the specified object type) defied i the curret database. Note: Whe specifyig the ame of a routie, you must explicitly specify a routie extesio, either.mac or.int. Ope M/SQL Developer Guide 12-13

340 Chapter 12 Ope M/SQL Developer Utilities Table 12-4: Fields o Object Compile Driver Items widow (Cotiued) Field Compile? <Advaced Opts> <Edit> Descriptio Here you may eter Yes or No to idicate whether or ot you wat to compile the curret object whe you ru the compilatio cofiguratio. Eter Yes to compile it, No to ot compile it. Yes is the default respose. You ca chage the settig of this switch back ad forth to selectively iclude or exclude objects from the compilatio list. This field is oly accessible if the object you are specifyig is a form, meu object, or routie. For all other objects, the cursor caot lad o this field. Whe specifyig a form, meu object, or routie, you may press <RETURN> o this actio field to access a small popup widow that lets you defie several compilatio optios associated with the curret object. These optios override ay default optios specified i the cofiguratio-wide Compilatio Optios widow. Press <RETURN> o this actio field to access the object defiitio form for the curret object. Withi the object defiitio form, you may edit the defiitio of the curret object however you wish. Whe you exit the object defiitio form, you retur to the Object Compile Driver Items widow. Note: To skip ahead to the ext field o the Object Compile Driver Items widow, use the <TAB> key or the <RIGHT ARROW> key. To move back to the previous field, use the <LEFT ARROW> key. 2. At the Object Type field, specify the type of the object you wat to add to the compilatio list. You may press the <LIST CHOICES> key to see a lookup box that lists all object types from which you may choose. 3. At the Object Name field, specify the ame of the particular object you wat to add to the compilatio list. You may press the <LIST CHOICES> key to see a list of all objects (of the specified object type) defied i the curret database. Note: Whe specifyig the ame of a routie, you must explicitly specify a routie extesio, either.mac or.int. 4. At the Compile? field, eter Yes or No to idicate whether or ot you wat the curret object to be compiled whe you ru the compilatio cofiguratio. Yes is the default respose Ope M/SQL Developer Guide

341 Usig the Object Compile Driver Utility 5. If the object you are curretly eterig is a form or meu object, you may press <RETURN> o the <Advaced Opts> actio field to access a small popup widow that lets you specify compilatio optios specifically associated with the specific object (see Advaced Optios for Compilatio List Items below). 6. You may press <RETURN> o the <Edit> actio field to activate a direct lik ito the curret object s defiitio form, where you may view or edit the defiitio (see Editig a Object Defiitio below). 7. Cotiue eterig additioal objects to the compilatio list i the same way as described above. 8. Whe you have etered all objects that you wat to be icluded i your compilatio cofiguratio, press the <PROCEED> key to save your defiitios ad exit the Object Compile Driver Items widow. Advaced Optios for Compilatio List Items The <Advaced Optios> actio field o the Object Compile Driver Items widow is oly accessible if the object you are curretly defiig is a form, a meu object, or a routie. For all other objects, this field is skipped. For forms, meu objects, ad routies, you may use this optio to access a widow that lets you specify compilatio optios specifically associated with the curret object. Note The optios you specify i this widow override the cofiguratio-wide compilatio optios specified i the Compilatio Optios widow (accessed via the Object Compile Driver meu bar). Ope M/SQL Developer Guide 12-15

342 Chapter 12 Ope M/SQL Developer Utilities Advaced Optios for Forms Whe addig a form to the compilatio list, you may press <RETURN> o the <Advaced Optios> actio field to access the Form Advaced Optios popup widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile DriverÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Set Compilatio Optio Defaults ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ Cofiguratio Name Sample Cofiguratio ³ ³ ³ ³ < Edit Cofiguratio > < Compile Cofiguratio > < Last Compile Results >³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile Driver ItemsÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Object Type Object Name Compile? ³ ³ Base Table_ Doctor Yes_ <Advaced Opts> <Edit>³ ³ Form Doctors Yes_ <Advaced Opts> <Edit>³ ³ Query Sort_Query Yes_ <Advaced Opts> <Edit>³ ³ Report Residets Yes_ <Advaced Opts> <Edit>³ ³ Meu Object Doctors Meu Yes_ <Advaced Opts> <Edit>³ ³ Form Patiets Yes_ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄForm Advaced OptiosÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³Compile Type NEW Use Local Storage?No Compile Tied Meu Objects Yes_ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Form Advaced Optios Press <Help> For Help The table below lists ad describes the optios located o the Form Advaced Optios widow: Table 12-5: Optios o Form Advaced Optios widow Field Compile Type Use Local Storage? Descriptio This is a output-oly field that shows the type of the last compilatio, i.e., the versio of the Forms Compiler last used to compile the form. This field ca have either of the followig two values: NEW (post-vesrio D versio of the Forms Compiler) OLD (pre-versio E versio of the Forms Compiler) The cursor caot lad o this field. Here you may aswer Yes or No to idicate whether or ot you wat to compile the curret form usig local storage. Aswer Yes to compile the form usig local arrays. This makes the compilatio faster but may cause <STORE> errors to occur. Aswer No to compile the form usig globals. This prevets space allocatio errors but makes the compilatio slower. No is the default respose Ope M/SQL Developer Guide

343 Usig the Object Compile Driver Utility Table 12-5: Optios o Form Advaced Optios widow (Cotiued) Field Compile Tied Meu Objects? Descriptio Here you may aswer Yes or No to idicate whether or ot you wat Ope M/SQL to recompile ay meu objects that are tied to the curret form. I order to be recompiled uder this optio, a meu object must be explicitly tied to the form, ot just attached to it. Note: This optio oly applies to forms that are compiled as NEW. Yes is the default respose. Whe you fiish specifyig compilatio istructios o the Form Advaced Optios widow, press the <PROCEED> key to save your defiitios ad exit the widow. Advaced Optios for Meu Objects Whe addig a meu object to the compilatio list, you may press <RETURN> o the <Advaced Optios> actio field to access the Meu Object Advaced Optios popup widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile DriverÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Set Compilatio Optio Defaults ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ Cofiguratio Name Sample Cofiguratio ³ ³ ³ ³ < Edit Cofiguratio > < Compile Cofiguratio > < Last Compile Results >³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile Driver ItemsÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Object Type Object Name Compile? ³ ³ Base Table_ Doctor Yes_ <Advaced Opts> <Edit>³ ³ Form Doctors Yes_ <Advaced Opts> <Edit>³ ³ Query Sort_Query Yes_ <Advaced Opts> <Edit>³ ³ Report Residets Yes_ <Advaced Opts> <Edit>³ ³ Meu Object Doctors Meu Yes_ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄMeu Object Advaced OptiosÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Compile Type? Both Pop-Ups ad Meu Bars Use Local Storage? Yes_ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Form Advaced Optios Press <Help> For Help Ope M/SQL Developer Guide 12-17

344 Chapter 12 Ope M/SQL Developer Utilities The table below lists ad describes the optios located o the Meu Object Advaced Optios widow: Table 12-6: Optios o Meu Object Advaced Optios widow Field Compile Type Use Local Storage? Descriptio Here you may specify how you wat Ope M/SQL to compile the curret meu object. Press the <LIST CHOICES> key to see a list of the meu object compilatio optios from which you may choose. They iclude: Pop-Up Meu Compile all meu objects as pop-up meus. Meu Bar Compile all meu objects as meu bars. Both Pop-Ups ad Meu Bars Compile all meu objects as both pop-up meus ad meu bars. The default optio is Both Pop-Ups ad Meu Bars. Here you may aswer Yes or No to idicate whether or ot you wat to compile the curret meu object usig local storage. Aswer Yes to compile the meu object usig local arrays. This makes the compilatio faster but may cause <STORE> errors to occur. Aswer No to compile the meu object usig globals. This prevets space allocatio errors but makes the compilatio slower. Yes is the default respose. Whe you fiish specifyig compilatio istructios o the Meu Object Advaced Optios widow, press the <PROCEED> key to save your defiitios ad exit the widow Ope M/SQL Developer Guide

345 Usig the Object Compile Driver Utility Advaced Optios for Routies Whe addig a routie to the compilatio list, you may press <RETURN> o the <Advaced Optios> actio field to access the Routie Advaced Optios popup widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile DriverÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Set Compilatio Optio Defaults ³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄij ³ ³ ³ Cofiguratio Name Sample Cofiguratio ³ ³ ³ ³ < Edit Cofiguratio > < Compile Cofiguratio > < Last Compile Results >³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compile Driver ItemsÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Object Type Object Name Compile? ³ ³ Base Table_ Doctor Yes_ <Advaced Opts> <Edit>³ ³ Form Doctors Yes_ <Advaced Opts> <Edit>³ ³ Query Sort_Query Yes_ <Advaced Opts> <Edit>³ ³ Report Residets Yes_ <Advaced Opts> <Edit>³ ³ Meu Object Doctors Meu Yes_ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ³ <Advaced Opts> <Edit>³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄRoutie Advaced OptiosÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ Check Routie s Sytax? Yes_ File this Routie s Object Code? Yes_ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Form Advaced Optios Press <Help> For Help The table below lists ad describes the optios located o the Routie Advaced Optios widow: Table 12-7: Optios o Routie Advaced Optios widow Field Check Routie s Sytax File this Routie s Object Code Descriptio Here you may aswer Yes or No to idicate whether or ot you wat Ope M/SQL to perform sytax checkig o this routie whe it is compiled. Aswer Yes perform sytax checkig. Aswer No to skip sytax checkig. Yes is the default respose. Here you may aswer Yes or No to idicate whether or ot you wat to file the object code associated withthis routie whe it is compiled. Aswer Yes to geerate ad file the object code for the routie. Aswer No to geerate oly itermediate (.INT) code for the routie. Yes is the default respose. Ope M/SQL Developer Guide 12-19

346 Chapter 12 Ope M/SQL Developer Utilities Whe you fiish specifyig compilatio istructios o the Routie Advaced Optios widow, press the <PROCEED> key to save your defiitios ad exit the widow Ope M/SQL Developer Guide

347 Usig the Object Compile Driver Utility Editig a Object Defiitio The Object Compile Driver utility lets you directly view or edit the defiitio of ay object you iclude i the compilatio cofiguratio. By pressig <RETURN> o the <Edit> actio field you activate a direct lik ito the curret object s defiitio form. Oce you have accessed the object defiitio form, you may view or edit the defiitio. Importat You must have %ALTER privileges o a object i order to activate the direct lik ito its object defiitio form Whe you exit a lik-accessed object defiitio form, you retur to the Object Compile Driver Items widow, exactly where you activated the lik. For example, if you iclude the form Doctors i the compilatio cofiguratio ad the you press <retur> o the <Edit> actio field, you see the Form Defiitio form for the Doctors form, as show below:: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄForm DefiitioÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Form Name Doctors ³ ³ ³ ³ ³ ³ Data Source Doctor ³ ³ ³ ³ Form Type Sigle Row_ ³ ³ ³ ³ ³ ³ < Widows > ³ ³ < Lookups > ³ ³ < Filig Code > ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÙ Form Defiitio Press <Help> For Help Create/Edit Pre Form Post Retrieval Post Form Advaced Field Trigger Trigger Trigger Features Ope M/SQL Developer Guide 12-21

348 Chapter 12 Ope M/SQL Developer Utilities Compilig the Cofiguratio To compile a compilatio cofiguratio, press <RETURN> o the <Compile Cofiguratio> actio field. Ope M/SQL sequetially compiles each object i the list. While the compilatio is happeig, you see a compilatio moitor widow. For each object beig compiled, the compilatio moitor widow displays the followig iformatio: Object Type Object Name Compilato results message (either Compiled Successfully or Compiled with Errors ) Whe all objects i the list have bee compiled, the compilatio moitor widow prompts you to press <RETURN>. A sample compilatio moitor widow is show below: Compilig Table: Doctor... Compiled Successfully Compilig Form: Doctors... Compiled With Errors Compilig Query: Sort_Doctors... Compiled Successfully Compilig Report: Residets... Compiled Successfully Compilig Meu Object: Doctors Meu... Compiled Successfully Compilig Form: Patiets... Compiled Successfully Compilig Table: Patiet... Compiled Successfully Press <RETURN> to Cotiue Press <RETURN> to retur to the Object Compile Driver mai widow Ope M/SQL Developer Guide

349 Usig the Object Compile Driver Utility Viewig the Results of the Last Compilatio The <Last Compile Results> optio o the Object Compile Driver mai widow lets you view the results from the last time the curret compilatio cofiguratio was compiled. Press <RETURN> o the <Last Compile Results> actio field to access the Object Compilatio Driver Results widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compilatio Driver ResultsÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Compilatio ³ ³ Object Type Object Name Status ³ ³ Base Table Doctor Success <View Err>³ ³ Form Doctors Failure <View Err>³ ³ Query Sort_Doctors Success <View Err>³ ³ Report Residets Success <View Err>³ ³ Meu Object Doctors Meu Success <View Err>³ ³ Form Patiets Success <View Err>³ ³ Base Table Patiet Success <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄCompilatio Error MessageÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Object Compilatio Driver Results Iquiry Press <Help> For Help The Object Compile Results widow lists all objects i the compilatio list by object type ad object ame ad display a message i the Compilatio Status colum to idicate the results of compilatio. This message ca be either Success or Failure. Compilatio Error Messages For objects whose Compilatio Status message is Failure, you may view the error message associated with the failure of the compilatio. To do this, use the <UP ARROW> ad <DOWN ARROW> keys to positio the cursor o the <View Err> field correspodig to the failed object. Ope M/SQL Developer Guide 12-23

350 Chapter 12 Ope M/SQL Developer Utilities The error message displays the Compilatio Error Messages widow at the bottom of the scree, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Compilatio Driver ResultsÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Compilatio ³ ³ Object Type Object Name Status ³ ³ Base Table Doctor Success <View Err>³ ³ Form Doctors Failure <View Err>³ ³ Query Sort_Doctors Success <View Err>³ ³ Report Residets Success <View Err>³ ³ Meu Object Doctors Meu Success <View Err>³ ³ Form Patiets Success <View Err>³ ³ Base Table Patiet Success <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ³ <View Err>³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄCompilatio Error MessageÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ STORE ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÄÄÄÄÄÄÄÄÄÙ Object Compilatio Driver Results Iquiry Press <Help> For Help See your system guide for a explaatio of Ope M/SQL error messages. Press the <PREVIOUS> key to retur to the Object Compile Driver mai widow. Compilig a Compilatio Cofiguratio from M Program Code You ca ru predefied compilatio cofiguratios directly from M program code usig the objcd etry poit to the %mcompil utility. To do this, use the followig sytax: do objcd^%mcompil(ocd_idetifier) where Ocd_Idetifier is the ame or ID# of a compilatio cofiguratio Ope M/SQL Developer Guide

351 Checkig the Itegrity of Ope M/SQL Objects Checkig the Itegrity of Ope M/SQL Objects The Object Itegrity Checker utility checks the itegrity of various object defiitios i the curret directory ad prepares a report of all itegrity errors that it fids. This utility eables applicatio developers to easily idetify ad repair itegrity errors i their applicatios. IterSystems recommeds that you ru the Itegrity Checker utility o your applicatios at a regular iterval, such as oce a week. You also should ru it before exportig objects to a ew database. You ca use the Object Itegrity Checker to check ay of the followig objects: All Objects Base Tables Views Forms Reports Meu Objects Triggers It checks all objects of the specified type that reside i the curret directory ad geerates a report of itegrity errors. You ca sed this report to a flat file or priter. You ca set the Object Itegrity Checker to automatically correct some of the itegrity errors it fids. Whe it corrects a error, it reports the correctio i the Itegrity Check Results report. The Itegrity Checker caot fix all errors it fids. Whe it ecouters a error that it caot fix, it also reports this i the Itegrity Check Results report. Whe correctig object itegrity problems, the Object Itegrity Checker does ot check privileges o the objects it modifies. It assumes that the Database Admiistrator is ruig the utility. The followig sectios list the checks made by the Itegrity Checker o each supported object. Ope M/SQL Developer Guide 12-25

352 Chapter 12 Ope M/SQL Developer Utilities Checks o Base Tables For base tables, the Itegrity Checker makes sure that: The base table has a ame The field defiitio for each field i the base table is itact The base table does ot have ay poiters to o-existet triggers Ay Desigative Referece fields i the base table poit to a desigated table that exists All fields that are refereced i the computatio code for computed fields are valid All fields that are part of the Computatio produces a NULL result IF code for computed fields are valid All fields that are refereced i the Update field whe followig field chages list are valid The base table defiitio stores a list of all views the base table is defied o. The Itegrity Checker makes sure all the views i this list actually exist. The base table defiitio stores a list of all forms for which it serves as the data source. The Itegrity Checker makes sure all the forms i this list actually exist. The if idex is defied for each field i the base table All base tables defied i the m idex exist All base tables defied i the rv idex exist All idexed fields defied i the if idex exist All idexed fields defied i the field ame idex exist Checks o Views For views, the Itegrity Checker makes sure that: The view s startig table is valid (it must be a base table or view) All table liks i the ^mdd(3,iv,10) tree are valid (Note: These liks are ot mapped; they are set up i %daview.) All fields i the view are valid base table fields. All view lik tables are valid The view field liks idex ( f1 idex ) are valid base table fields All fields i the view have field ames Ope M/SQL Developer Guide

353 Checkig the Itegrity of Ope M/SQL Objects Checks o Forms For forms, the Itegrity Checker makes sure that: The form s data source is valid (if the form has a data source) All database fields exist All form-oly fields exist The form does ot have ay poiters to o-existet triggers All Desigative Display fields have valid field ames. All form-oly fields have field ames that do ot duplicate the field ames of database fields o the same form. All fields i the widow-order list exist (if the form is a widow-ordered form) All fields that are refereced i the computatio code for computed fields are valid All fields that are part of the Computatio produces a NULL result IF code for computed fields are valid All fields that are refereced i the Update field whe followig field chages list are valid Checks o Reports For reports, the Itegrity Checker makes sure that: The report s data source is valid (the data source may be base table, view, or query) Each report colum is a valid field (base table, view, report, or query field) Each report sort field is a valid field (base table, view, report, or query field) Each sort trailer field is a valid field (base table, view, report, or query field) All report summary computed fields are valid fields. Checks the FieldName, Withi, ad ForEach fields (base table, view, report, or query fields) Report data selectio coditios referece valid fields Checks FieldName ad CompField fields (base table, view, report, or query fields.) Report header, report trailer, page header, ad page trailer fields are valid fields (base table, view, report, or query fields.) All field refereces i the M code lies for report computed fields are valid. If it is a report chai, all members of the chai are valid reports Ope M/SQL Developer Guide 12-27

354 Chapter 12 Ope M/SQL Developer Utilities Checks o Meu Objects For meu objects, the Itegrity Checker utility makes sure that: The meu object has a ame If the meu object is tied to a form, the paret form exists The meu object has at least oe optio Checks o Meu Object Optios For meu object optios, the Itegrity Checker utility makes sure that: The optio text is ot ull The optio has a actio type The optio has a actio ame (if required) If the meu object optio actio calls aother object, the Itegrity Checker makes the followig checks: Table 12-8: Itegrity Checks Made Whe a Meu Optio Calls Aother Object If the called object is a... Make sure that... Form Report Query Pop-Up Meu Meu Bar Meu Help Topic The form exists The report exists The query exists The meu object exists The meu object exists The help topic exists Widow It is a tied form The form the meu is tied to is the same as the meu the widow is o The widow exists o the form Ope M/SQL Developer Guide

355 Checkig the Itegrity of Ope M/SQL Objects Checks o Triggers The Itegrity Checker checks all triggers to make sure that: All base table trigger poiters exist All form trigger poiters exist All report trigger poiters exist All trigger defiitios are valid All trigger items are valid Base Table Trigger Checks For all base tables, the Itegrity Checker checks the validity of: All Pre-Filig INSERT, UPDATE, ad DELETE triggers All Post-Filig INSERT, UPDATE, ad DELETE triggers Form Trigger Checks For all forms, the Itegrity Checker checks the validity of: All Pre-Form triggers All Post-Retrieval triggers All Post-Form triggers All Pre-Row triggers (for multi-row forms oly) All Post-Row triggers (for multi-row forms oly) All Pre-Widow triggers All Post-Widow triggers All Pre-Field triggers All Post-Field triggers Report Trigger Checks For all reports, the Itegrity Checker checks the validity of: All Pre-Report triggers All Post-Report triggers Ope M/SQL Developer Guide 12-29

356 Chapter 12 Ope M/SQL Developer Utilities Trigger Defiitio Checks For all trigger defiitios, the Itegrity Checker checks to make sure: The trigger defiitio is valid Itegrity from trigger defiitios back to their host objects is valid If the trigger callig type is a form, the form exists. If the trigger callig type is a base table, the base table exists. If the trigger callig type is a report, the report exists Trigger Items The Itegrity Checker makes the followig checks o the validity of form trigger items: Table 12-9: Trigger Items Verified by the Itegrity Checker If the trigger actio type is... The Itegrity Checker checks the existece of... Meu Form Query Widow Go To Field Set Field Erase Form Erase Widow Display Widow Display Form Pop-up Meu Meu Bar The meu The form The query The widow The target field The target field The target form The target widow The target widow The target form The target meu object The target meu object Ope M/SQL Developer Guide

357 Checkig the Itegrity of Ope M/SQL Objects Ruig the Itegrity Checker Utility Whe ruig the Itegrity Checker utility, your Ope M/SQL database must be perfectly idle. No activity that affects the Ope M/SQL objects beig checked is allowed to occur. To esure that this is the case, the Itegrity Checker will ot ru if it detects that the ^mlock global is defied. The presece of the ^mlock global idicates that Ope M/SQL objects are i use. Al users must exit Ope M/SQL before you ca ru this utility. Oce the Itegrity Checker starts, users may ot eter Ope M/SQL or ru ay Ope M/SQL objects. Whe correctig object itegrity problems, the Object Itegrity Checker does ot check privileges o the objects it modifies. It assumes that the Database Admiistrator is ruig the utility. Procedure To ru the Ope M/SQL Itegrity Checker utility: 1. From the Developer Utilities meu, select the M/SQL Object Itegrity Checkig optio. You see the M/SQL Itegrity Check Utility meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄM/SQL Itegrity Check UtilityÄÄ ³ ³ ³ All M/SQL Objects ³ ³ Base Tables ³ ³ Views ³ ³ Forms ³ ³ Reports ³ ³ Meu Objects ³ ³ Triggers ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Moday Aug 21, :19AM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio M/SQL Itegrity Check Utility 12:19AM Press <Help> For Help Ope M/SQL Developer Guide 12-31

358 Chapter 12 Ope M/SQL Developer Utilities Note: If your Ope M/SQL database is ot completely idle, you see the followig message: The ^mlock global is defied i this database which idicates OPEN M/SQL is i use. Please ru the OPEN M/SQL itegrity checkers whe the OPEN M/SQL objects are ot i use i this database. You caot ru the Itegrity Checker utility while there are users i Ope M/SQL. 2. From the M/SQL Itegrity Check Utility meu, select the appropriate optio for the objects you wat to check. If you selected Trigger Defiitios, you see followig widow: THIS UTILITY WILL CHECK FOR INCONSISTENCIES IN ALL OPEN M/SQL TRIGGER DEFINITIONS. YOU HAVE THE OPTION OF JUST PRINTING THE ERRORS, OR HAVING OPEN M/SQL FIX THE PROBLEMS IT CAN AUTOMATICALLY. Do You Wat The Itegrity Checker To Fix Errors? 3. Aswer Yes or No at the prompt Do You Wat The Itegrity Checker To Fix Errors? to idicate whether or ot you wat the Itegrity Checker to correct some of the itegrity errors it fids. Note: You may type Q or ^ to exit the Itegrity Checker utility. The Object Itegrity Checker ca correct some but ot all of the itegrity errors it fids. Whe it corrects a error, it reports the correctio i the Itegrity Check Results report. Whe it ecouters a error that it caot fix, it also reports this i the Itegrity Check Results report. You must correct these errors maually Ope M/SQL Developer Guide

359 Checkig the Itegrity of Ope M/SQL Objects If you aswer Yes at the Do You Wat The Itegrity Checker To Fix Errors? prompt, you see the followig prompt askig you to specify which error fixig mode you wat the Itegrity Checker to use: Select Error Fixig Mode: 1 - Fix all errors without promptig 2 - Prompt for permissio to fix each error Select Error Fixig Mode: Type 1 to specify Fix without promptig mode, where the Itegrity Checker automatically fixes ay errors that it ca fix. Type 2 to specify Prompt before fixig mode, where the Itegrity Checker displays each error, idicates whether or ot it ca be fixed automatically, ad prompts the user with to cofirm before fixig it. Note: Whe correctig object itegrity problems, the Object Itegrity Checker does ot check privileges o the objects it modifies. It assumes that the Database Admiistrator is ruig the utility. If you aswer No at the Do You Wat The Itegrity Checker To Fix Errors? prompt, the Itegrity Checker will ot correct ay errors that it fids, though it still reports all errors i the Itegrity Check Results report. You see the Device Selectio widow, as show below: ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ÚÄÄÄÄÄÄÄÄDevice SelectioÄÄÄÄÄÄÄÄ ³ Device ³ ³ /dev/tty07 ³ ³ ³ ³ Descriptio ³ ³ Laser Priter ³ ³ ³ ³ Prit Format ³ ³ Normal Format ³ Device Selectio Press <Help> For Help Ope M/SQL Developer Guide 12-33

360 Chapter 12 Ope M/SQL Developer Utilities The followig table lists ad describes the fields located o the Device Selectio widow: Table 12-10: Fields o Device Selectio Widow Field Device Descriptio Prit Format Descriptio This field always defaults to your curret device (the curret value of $IO). You may chage the default to ay valid output device to which your device is liked. This field reflects the descriptio give to the specified device i the device table. Here you may select ay prit format defied for the specified device. 4. I the Device field, eter the ame of the device to which you wat to sed this report. You ca sed the report to ay valid output device that is liked to your curret device. The default device is your curret device. To sed the report to your scree, press the <PROCEED> key. To sed the report to aother device (such as a priter), delete the ame of the default device at the Device prompt, eter the ame of the ew target device, adjust the Prit Format parameter as appropriate, ad press the <PROCEED> key. 5. Whe you have etered a device ame ad the appropriate prit format parameters, press the <PROCEED> key. This executes the Itegrity Check Results report. Below is a sample Itegrity Check Results report for Trigger Defiitios: TYP OBJ NAME TRIG# ITEM ERROR frm Doctors FORM Trigger calls a udefied form. Trigger Locatio - PostFld Trig: field3 This must be fixed maually. frm Big Test POPUP MENU Trigger calls a udefied meu object. Trigger Locatio - PostFld Trig: BigPopUpTest This must be fixed maually.??? ReportTriggers 225 Pre-Report Trigger ot called from report. Trigger Locatio - Pre-Report??? ReportTriggers 226 Post-Report Trigger ot called from report. Trigger Locatio - Post-Report frm JLD FORM Trigger calls a udefied form. Trigger Locatio - PostFld Trig: GlucoseTest This must be fixed maually. MORE ('^' or 'Q' to quit) > Ope M/SQL Developer Guide

361 Checkig the Itegrity of Ope M/SQL Objects Note: Whe output to the scree, the report displays oe scree of errors at a time ad prompts you to press <RETURN> to scroll ahead to the ext scree. The Itegrity Check Results report for Trigger Defiitios provides the followig iformatio about each itegrity error it fids: Object Type type of object to which the trigger belogs. It may be a form (frm), a base Table (tbl), or a Report (rpt). Sometimes, the object to which the trigger belogs is ot kow (???) Object Name ame of the specific object to which the trigger belogs (if the object is kow) Trigger # iteral idetificatio umber of the trigger i which the itegrity error was foud Trigger Item # umber of the particular item i the trigger item sequece i which the itegrity error was foud Error Message message that describes the itegrity error 6. Press the <PREVIOUS> key to exit the report. Ope M/SQL Developer Guide 12-35

362 Chapter 12 Ope M/SQL Developer Utilities Error Fixig Mode If you have eabled error fixig, the Itegrity Checker ca automatically correct some of the errors it fids. Error fixig has two modes: 1. Fix errors without promptig 2. Prompt before fixig errors The behavior of the Itegrity Checker depeds o which of these modes you select. Fix Errors Without Promptig I this mode, the Itegrity Checker displays oe error per scree ad automatically fixes all errors that it ca fix. If it fixes the error, you see the message: Fixed If it caot fix the error, you see the message: This error must be maually fixed Prompt Before Fixig Errors I this mode, the Itegrity Checker displays oe error per scree ad prompts the user to cofirm a fix before it fixes a error. If it ca fix the error, you see the message: OK to fix this error? If it caot fix the error, you see the message: This error must be maually fixed Ope M/SQL Developer Guide

363 Searchig for Strigs i Ope M/SQL Objects Searchig for Strigs i Ope M/SQL Objects The Object Strig Search utility searches through Ope M/SQL object defiitios for specified text strigs. The Object Strig Search utility ca search ay of the followig object types: Base Tables Views Queries Reports Forms Meus (Old Style) Meu Objects Help Topics Help Documets The utility ca search through all objects i the curret directory, or it ca search through selected objects. You may select objects by object type, ad you may further select objects by specific object ame withi a certai object type. The utility ca search for oe strig or may differet strigs. Procedure To use the Object Strig Search utility: 1. From the Developer Utilities meu, select the M/SQL Object Itegrity Checkig optio. You see the Device Selectio widow, as show below: ÚÄÄÄÄÄÄÄÄDevice SelectioÄÄÄÄÄÄÄÄ ³ Device ³ ³ /dev/tty07 ³ ³ ³ ³ Descriptio ³ ³ Laser Priter ³ ³ ³ ³ Prit Format ³ ³ Normal Format ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Device Selectio Press <Help> For Help Ope M/SQL Developer Guide 12-37

364 Chapter 12 Ope M/SQL Developer Utilities 2. I the Device field, eter the ame of the device to which you wat to sed this report. You ca sed the report to ay valid output device that is liked to your curret device. The default device is your curret device. To sed the report to your scree, press the <PROCEED> key. To sed the report to aother device (such as a priter), delete the ame of the default device at the Device prompt, eter the ame of the ew target device, adjust the Prit Format parameter as appropriate, ad press the <PROCEED> key. 3. Whe you have etered a device ame ad the appropriate prit format parameters, press the <PROCEED> key. 4. You see the followig prompt: Search Strig #1 (^to quit): Here, you may eter the text of the first search strig, ad press <RETURN>. You may eter ay umber of search strigs. Note: The list of search strigs is a iclusive OR list, which meas that if the utility fids ANY oe of the specified search strigs withi a object defiitio, it returs a strig foud message. Each time you eter a ew search strig, you see the followig prompt: EXACT MATCH? No==> 5. At the EXACT MATCH prompt, press <RETURN> to accept the No default, or type Y ad press <RETURN>. Aswer Yes to idicate that you wat the Object Strig Search utility to search for a EXACT match (case sesitive) of the specified strig. Aswer No to idicate that you wat the Object Strig Search utility to search for a ALPHAUP match (case isesitive) of the specified strig. The utility cotiues to prompt you to eter additioal search strigs. 6. Whe you have fiished eterig search strigs, press <RETURN> at the Search Strig prompt. You see the followig prompt: Object Type To Search (^to quit,? for list): 7. At the Object Type To Search prompt, you may specify the object type(s) you wat to search Ope M/SQL Developer Guide

365 Searchig for Strigs i Ope M/SQL Objects To search all object types, eter *. Otherwise, eter a umber from 1 to 9 to represet the object type you wat to search. Type? to see a list of the object type choices ad their umbers. The table below shows the umber that correspods to each object type: Object Type # Base Tables 1 Views 2 Queries 3 Reports 4 Forms 5 Meus (old-style) 6 Meu Objects 7 Help Topics 8 Help Documets 9 All object types * You may specify oe object type or all object types. Whe you select a object type, you see the followig prompt: <Object Type> (eter ame or * for all) 8. At the Object Name prompt, you may eter the ames of the specific objects you wat the utility to search. For example, if you specified Base Tables as the object type, you may eter ay umber of specific base table ames. Or, to search through all objects of the specified type, you may type * at this prompt. Whe selectig object ames, you may type the first few characters of a object ame, the press the <SEARCH CURRENT TABLE> key to see a lookup box that lists all matchig etries for the specified object type. Note: If you are searchig through all object types, the utility automatically searches through all object ames withi each object type. You caot restrict this search. Ope M/SQL Developer Guide 12-39

366 Chapter 12 Ope M/SQL Developer Utilities 9. Whe you have fiished eterig object ames, press <RETURN> at the Object Name prompt. The utility seds output to the specified device. The Object Strig Search utility outputs a header page that lists each search strig ad all of its criteria, icludig the strig matchig criteria ([EXACT] or [ANY]). A sample of the Ope M/SQL Object Text Search header page is show below: OPEN M/SQL OBJECT TEXT SEARCH PRINTOUT Search Criteria: 1) [ ANY ] leo <PRESS RETURN> 10. Press <RETURN> to view the Strig Search report. Followig the header page, the utility outputs a detailed listig of all matches foud. For each match, the report provides the followig iformatio: Object Type Object Name Sub-object Type (whe applicable) Sub-object Name (whe applicable) Locatio (attribute) where the match was foud Text strig i which the match was foud Ope M/SQL Developer Guide

367 Searchig for Strigs i Ope M/SQL Objects For example, you might see the followig etry for a EXACT match o strig ^ABC foud i the INSERT Validatio Code for Base Table Patiets : Base Table - 'Patiets' LOCATION: Isert Validatio Code TEXT: i {Status}= s %ok=0 d ^ABC({Patiet}) Typically, the report idetifies the exact locatio of the matchig text strig. For example, if it fids a match withi Additioal Validatio Code for a field (which ca have ay umber of text lies defied), the report prits oly the matchig text lies. I the case of idividual trigger actios ad idividual lookup specificatios, the report prits the etire trigger actio specificatio or etire lookup specificatio, i order to provide a meaigful cotext for the text match. Below is a sample of the Strig Search report: Base Table: 'jld087' LOCATION = Base Table Name TEXT = jld087 Base Table: 'jld087' LOCATION = Base Table Descriptio TEXT = jld087 Test (ir = 1) Base Table: 'jld087' - Field: 'jld087' LOCATION = Field Name TEXT = jld087 Base Table: 'jld087' - Field: 'jld087' LOCATION = Field Descriptio TEXT = jld087 Row ID Base Table: 'jld087' - Map: 'Data Master Map' - Access Level: L3 LOCATION = Map Access Level Expressio TEXT = {jld087} MORE ('^' or 'Q' to quit) > 11. Press the <PREVIOUS> key to exit the report. Ope M/SQL Developer Guide 12-41

368 Chapter 12 Ope M/SQL Developer Utilities Ivokig Macro Source Routie Utilities Ope M/SQL provides a umber of utilities for examiig ad maipulatig M macro source code routies ad iclude files. These utilities are useful for both developig ad maitaiig Ope M/SQL applicatios. The Ope M/SQL routie utilities iclude: Routie Output (%urprit) Routie Iput (%urload) Routie Directory (%urdir) Routie Chage (%urchage) Routie Compile (%urcomp) Routie Copy (%urcopy) Routie Search (%urfid) Routie Search All (%urfad) Routie Delete (%urdel) Set Maximum Number of Backups (%urverma) Routie Backup Purge (%urpurge) You may ivoke ad use these utilities via the Developer Utilities meu. Procedure To ru macro source routie utilities from the Developer Utilities meu: 1. From the Developer Utilities meu, select the Macro Routie Utilities optio. You see the M/SQL Routie Utilities meu, as show below: ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ OPEN M/SQL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÚÄÄÄÄÄÄÄÄM/SQL Routie UtilitiesÄÄÄÄÄÄÄÄ ³ ³ ³ Routie Output (%urprit) ³ ³ Routie Iput (%urload) ³ ³ Routie Directory (%urdir) ³ ³ Routie Chage (%urchage) ³ ³ Routie Compile (%urcomp) ³ ³ Routie Copy (%urcopy) ³ ³ Routie Search (%urfid) ³ ³ Routie Search All (%urfad) ³ ³ Routie Delete (%urdel) ³ ³ Set Maximum No. of Backups (%urverma) ³ ³ Routie Backup Purge (%urpurge) ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ Wedesday Aug 09, :50PM Directory: /us/lad/ Licesed to Developmet Testig. Copyright (c) IterSystems Corporatio M/SQL Routie Utilities 03:50PM Press <Help> For Help Ope M/SQL Developer Guide

369 Ivokig Macro Source Routie Utilities 2. From the M/SQL Routie Utilities meu, select the routie that you wat to ru. Ope M/SQL rus the selected routie utility i a widow. For example, if you selected the Routie Search utility (%urfid), you would see the followig scree: This routie chages all occurreces of a strig i routies/iclude files. 1. Chage every: 3. Aswer all prompts as appropriate. Note: For complete iformatio o how to use all of the Ope M/SQL routie utilities, see Chapter 7, Ope M/SQL Routie Maagemet Utilities. Whe you exit the selected routie utility, you retur to the Routie Utilities meu. Ope M/SQL Developer Guide 12-43

370 Chapter 12 Ope M/SQL Developer Utilities Queryig Objects by Routie Prefix The Object Routie Prefix utility lets you look up ay routie prefix that is associated with a Ope M/SQL object i the curret directory. Whe you look up a routie prefix, the utility displays iformatio about where that routie is beig used. Specifically, it provides the followig iformatio: Routie Prefix Object Type Object Idetificatio # Object Name Whe compilig large applicatios, you may receive warig ad error messages that cite routie ames. These messages do ot always specify which object the routie belogs to. For example, the message Sytax error i mp3261 does ot provide ay iformatio about routie mrp3261. I order to correct this error, you eed to fid out where this routie is located. The Object Routie Prefix utility eables you to do this. This utility is also useful whe deletig routies to clea up your directory Procedure To use the Object Routie Prefix utility: 1. From the Developer Utilities meu, select the Query Object By Routie Prefix optio. You see the Object Lookup by Routie Prefix lookup widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Lookup By Routie PrefixÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Routie Prefix ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ÄÄÙ Ope M/SQL Developer Guide

371 Queryig Objects by Routie Prefix Object Routie Prefix Selectig Press <Help> For Help 2. At the Routie Prefix field, eter the ame of the routie prefix you wat to look up. You may perform both uqualified ad qualified lookups o the directory of routie prefix ames. To perform a uqualified lookup, press the <SEARCH CURRENT TABLE> key with the Routie Prefix field blak. You see a lookup box that lists all routie prefixes. To perform a qualified lookup, eter the first oe or more characters of the routie prefix you wat to fid, ad press the <SEARCH CURRENT TABLE> key. You see a lookup box that lists all matchig etries. 3. Withi the lookup box, use the <UP ARROW> ad <DOWN ARROW> keys to positio the cursor o the routie prefix you wat to examie, ad press <RETURN> to select it. You see the Object Routie Prefix widow, as show below: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄObject Routie PrefixÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ³ ³ ³ Routie Prefix mt1 ³ ³ ³ ³ Object Type table ³ ³ Object Id 1 ³ ³ Object Name Doctor ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ< proceed >Ù Object Routie Prefix Press <Help> For Help The Object Routie Prefix widow displays iformatio about the routie prefix you selected. All fields o this widow are read-oly. 4. To exit the Object Routie Prefix widow, press <RETURN>. Ope M/SQL Developer Guide 12-45

372 Chapter 12 Ope M/SQL Developer Utilities You retur to a empty Object Lookup By Routie Prefix widow, where you may select aother routie prefix to examie Ope M/SQL Developer Guide

373 Natioal Laguage Reports Natioal Laguage Reports The Natioal Laguage Reports utility lets you geerate a scree or hard copy report that displays the traslatios provided for all system-geerated messages, key labels, meu titles, ad meu optio text throughout the Ope M/SQL eviromet. The report is orgaized alphabetically by message. For each message, the report provides the followig iformatio: The Eglish text for the message, key label, meu title, or meu optio text The maximum traslatio legth (based o the legth of the Eglish text) List of supported laguages with the appropriate traslatio of the message (if supplied) Procedure To prit the Natioal Laguage report: 1. From the Developer Utilities meu, select the Natioal Laguage Reports optio. You see the Device Selectio widow. 2. I the Device field, eter the ame of the device to which you wat to sed this report. You ca sed the report to ay valid output device that is liked to your curret device. The default device is your curret device. To sed the report to your scree, press the <PROCEED> key. To sed the report to aother device (such as a priter), delete the ame of the default device at the Device prompt, eter the ame of the ew target device, adjust the Prit Format parameter as appropriate, ad press the <PROCEED> key. 3. Whe you have etered a device ame ad the appropriate prit format parameters, press the <PROCEED> key. This executes the Natioal Laguage report. Ope M/SQL Developer Guide 12-47

374 Chapter 12 Ope M/SQL Developer Utilities Below is a sample page from the Natioal Laguage Report: Eter Traslatios For System MPage: 3 WARNING: Esure that legth of traslatios for system messages does ot exceed the legth of the Eglish text beig traslated. Call IterSystems if this limitatio is uacceptable. Also, if o Eglish text is provided, it is ot ecessary to eter traslatios. MESSAGE CONTEXT: ALTER Eglish Message: %ALTER Maximum Legth: 15 Eter Traslatios: Dask (Daish) - Deutsch (Germa) - %ALTER Dutch (Netherlads) - Espaol (Spaish) - Fiska (Fiish) - Fracais (Frech) - %ALTER Italiao (Italia) - %Altera Norsk (Norwegia) - %Foradere Portuguese - Altere Sveska (Swedish) - %Adra Press <Retur> to cotiue, <Optios> to scroll, <Exit> to Exit Note: Whe output to the scree, this report displays oe scree at a time ad prompts you to press <RETURN> to scroll ahead to the ext scree. 4. You may press the <PREVIOUS> key at ay time to exit the Natioal Laguage Report ad retur to the Developer Utilities meu Ope M/SQL Developer Guide

375 APPENDIX SQL Error Messages A Wheever you issue a SQL statemet, it returs a o-descriptive umerical message to the variable SQLCODE. The message idicates oe of the followig: Successful completio Error The tables i this Appedix list all message codes that ca be retured to the SQLCODE variable ad describes the meaig of each code. Ope M/SQL Developer Guide A-1

376 Appedix A SQL Error Messages Successful Completio Messages The followig table lists the codes for successful completio: Table A-1: Codes Retured o Successful Completio Error Code Number Meaig 0 Query completed successfully 100 Query completed successfully, but o row was foud to satisfy the query A-2 Ope M/SQL Developer Guide

377 Error Messages Error Messages The followig table lists the codes for errors foud durig parsig: Table A-2: SQL Error Messages Error Code Number Fuctio -1 Ivalid SQL statemet -2 Expoet digits missig after 'E' -3 Closig quote (") missig -4 A term expected, begiig with either of: idetifier, costat, aggregate, %ALPHAUP,%UPPER, %EXACT, $$, :, +, -, (, NOT, or EXISTS -5 Colum-umber specified i ORDER does ot match the SELECT list -6 ORDER must specify colum umber, ot ames, whe after UNION -7 ORDER colum is ot i SELECT list -9 Icompatible SELECT lists used i UNION -10 The SELECT list of the query must have exactly oe item -11 A scalar expressio expected, ot a coditio -12 A term expected, begiig with either of: idetifier, costat, aggregate, $$, (, :, +, -, or %ALPHAUP, %UPPER, or %EXACT -13 A expressio other tha a subquery expected here -14 A compariso operator is required here -15 A coditio expected after NOT -16 A qualifier SOME or ALL expected after the FOR i the for-expressio -17 A for-coditio expected after the ( i the for-expressio -18 IS (IS NOT) NULL predicate ca be applied oly to a field -19 A aggregate fuctio caot be used i a WHERE clause -20 Name coflict i the FROM list over label <label> -22 ORDER must specify colum ames, ot umbers, whe after 'SELECT *' -23 Label <label> is ot listed i FROM -25 Iput (<toke>) ecoutered after ed of query -26 Missig FROM clause -27 Ambiguous labels for field <ame> -28 Host variable ame must begi with either % or a letter, ot <symbol> -30 Table <tableame> ot foud Ope M/SQL Developer Guide A-3

378 Appedix A SQL Error Messages Table A-2: SQL Error Messages (Cotiued) Error Code Number Fuctio -31 Field <fieldame> ot foud i table(s) <tableame> -32 Outer joi symbol (=*) must be betwee two fields -33 No fields foud for table <tableame> -34 Cotradictory coditios: 'f is NULL' vs. 'f=costat' -35 Cotradictory coditios: 'f IS NULL' vs. 'f i rage' -36 Cotradictory coditios: 'f IS NULL' vs. 'f=expressio' -37 Cotradictory coditios: costats should satisfy <coditio> -38 No master map for table <tableame> 39 No Row ID field for table <tableame> -41 A extrisic fuctio call must have the form $$tag^rou( Closig quotes ( " ) missig followig patter match -51 A SQL statemet expected, <toke> foud -52 Cursor <cursorame> already DECLAREd or ot DECLAREd -53 Costat or variable expected as ew value -54 Array desigator (last subscript omitted) expected after VALUES -55 Ivalid GRANT <role> to or revoke <role> from -56 Actio ot applicable to a object of this type -58 Object type ot foud -59 Caot have more tha oe field -60 A actio (%ALTEr, SELECT, UPDATE, etc.) expected -61 Cursor ot updatable -62 Additioal ew values expected for INSERT/UPDATE -63 Data exceptio - ivalid escape character -70 Icorrectly defied RowID -99 Privilege violatio -101 OPEN attempted o a cursor that is already ope -102 Cursor operatio (FETCH, CLOSE, UPDATE, DELETE) attempted o a uopeed cursor -103 Positioed UPDATE or DELETE attempted but the cursor is ot positioed o ay row -104 Field validatio failed i INSERT A-4 Ope M/SQL Developer Guide

379 Error Messages Table A-2: SQL Error Messages (Cotiued) Error Code Number Fuctio -105 Field validatio failed i UPDATE -106 Row to DELETE ot foud -107 Table validatio failed -108 Required field missig; INSERT or UPDATE ot allowed -109 Caot fid the row desigated for UPDATE -110 Lockig coflict i filig -111 Operatio ot licesed o this system -112 Access violatio -113 %THRESHOLD violatio -201 Table or view ame ot uique -212 Urecogized or ivalid iput device -213 Keyword ON expected -214 Left parethesis expected -215 Right parethesis expected -216 Comma expected -217 Uexpected Ed-of-Field -218 Uexpected Ed-of-Query -219 Icorrect or missig field ame -220 Icorrect or missig data type -221 Ivalid legth/scale specificatio -222 Default value exceed field legth -223 Datatype/qualifier mismatch -224 Urecogized or coflictig qualifiers -225 Multiple primary key specificatio -226 Icomplete primary fields specificatio -227 Missig quote itroducig or edig descriptio -228 Missig or illegal global ame -229 Query rejected -230 Bad colum costrait Ope M/SQL Developer Guide A-5

380 Appedix A SQL Error Messages Table A-2: SQL Error Messages (Cotiued) Error Code Number Fuctio -231 SQL reserved word ot allowed Note: For a list of Ope M/SQL reserved words, see Appedix B Sigle quotatio expected istead of double quotatio -233 Repeated key defiitio or coflict costraits -234 Bad default value -235 Repeated idex defiitio -236 Data type error -237 More tha oe idex defied at the same time here -238 More tha oe CREATE TABLE statemet i oe SQL macro -239 More tha oe DROP TABLE statemet i oe SQL macro -240 The field is required ad ca t have NULL value -242 Geeral DDL parsig error -243 Scales with character data types -244 Scales with iteger data types -245 Specifyig legth for this data type ot allowed -246 Decimal part with iteger default value -248 Default value is ot allowed for this data type Maximum ope cursors exceeded Note: Up to 255 cursors are permitted for a give coectio Ivalid cursor Fetch out of sequece No statemet parsed Bid variable does ot exist Variable ot i select list Not all variables boud Not logged o User requested cacellatio of curret operatio Ivalid user ame/password Ivalid data type i obdrv, obdr, or odefi call Isufficiet privileges Warig: Fetched colum value is NULL A-6 Ope M/SQL Developer Guide

381 Error Messages Table A-2: SQL Error Messages (Cotiued) Error Code Number Fuctio Warig: Fetched colum value was trucated Caot covert select item value to umeric data type Value overflows specified iteger data type Ivalid legth specified for variable character strig Ivalid legth for DATE or NUMBER bid variable Note Error codes used by the Ope M/SQL Relatioal Cliet ad Server are documeted i the Ope M/SQL Relatioal Cliet User Guide. Ope M/SQL Developer Guide A-7

382 Appedix A SQL Error Messages A-8 Ope M/SQL Developer Guide

383 APPENDIX Ope M/SQL Reserved Words B Ope M/SQL reserves certai keywords for its ow use. This meas that you caot use these words as idetifiers (ames of database objects such as base tables, forms, fields, etc.). The followig table lists the Ope M/SQL reserved words: Table B-1: Ope M/SQL Reserved Words %AFTERHAVING %ALPHAUP %ALTER %BEGTRANS %CATALOG %CHECKPRIV %EXACT %EXTERNAL %FOREACH %FORM %INTALL %INTERNAL %INTOBUILD %INTRANS %LEVEL %MENU %MENUOBJ %NOCHECK %QUERY %REPORT %ROWCOUNT %STARTSWITH %THRESHOLD %UPPER ADMIN ALL ALTER AND ANY AS ASC AUTHORIZATION AVG BEGIN BETWEEN BY CASCADE CHAR CHARACTER CHECK CLOSE COBOL COMMIT CONSTRAINT CONTINUE COUNT CREATE CURRENT CURSOR DATE DEC Ope M/SQL Developer Guide B-1

384 Appedix B Ope M/SQL Reserved Words Table B-1: Ope M/SQL Reserved Words (Cotiued) DECIMAL DECLARE DELETE DESC DISTINCT DOUBLE DROP END ESCAPE EXEC EXISTS FETCH FILE FLOAT FOR FOREIGN FORTRAN FOUND FROM GO GOTO GRANT GROUP HAVING IN INDEX INDICATOR INSERT INT INTEGER INTO IS LANGUAGE LIKE MAX MIN MODULE NOT NULL NUMERIC OF ON OPEN OPTION OR ORDER PASCAL PLI PRECISION PRIMARY PRIVILEGES PROCEDURE PUBLIC REAL REFERENCES RELATION REVOKE ROLE ROLLBACK SCHEMA SECTION SELECT SET SMALLINT SOME SQL SQLCODE SQLERROR SOME TABLE TIME TO UNION UNIQUE UPDATE USER VALUES VARCHAR VARYING VIEW WHENEVER WHERE WITH WORK Note Some of these reserved words are used for the SQL Data Defiitio Laguage (DDL), which is curretly uder implemetatio by IterSystems. B-2 Ope M/SQL Developer Guide

385 APPENDIX Ope M/SQL Supported Termial Types C Ope M/SQL supports the followig termial types: Table C-1: Ope M/SQL Supported Termial Types Type Name Descriptio Video ALTOS 5 Altos 5 Termial Video ANSI ANSI Termial Video ANSI Color ANSI Color Termial Video CIT-500 CIT-500 (Emulates VT 132) Video COBRA COBRA Termial Video D200 Geeral Dasher Termial D214 & D215 Video D200 Ge/Perfect Dasher Termial D214 & D215 Video D470C Dasher Termial DG mode Video DTM PC (Supported for Ope M/SQL o DTM) DTM PC Cosole Video DTM PC Color DTM PC Color Cosole Video FALCO Falco Emulatig a VT 220 Video Geeric Pure Roll-ad-Scroll Video IBM 3151 IBM 3151 ASCII Display Statio Video IBM 6091 IBM Termial Video LANSI Log ANSI Termial Video MSM PC (Supported for Ope M/SQL o MSM) MSM PC Cosole Video MSM PC Color MSM PC Color Cosole Ope M/SQL Developer Guide C-1

386 Appedix C Ope M/SQL Supported Termial Types Table C-1: Ope M/SQL Supported Termial Types (Cotiued) Type Name Descriptio Video PC IBM PC Termial Video PC Color IBM PC Termial With Wired Color Video QUME QUME Termial Video SUN SUN Termial Video TV9320 TeleVideo 9320 Termial Video Video Video Video VT100 (Supported for Ope M/SQL o DSM & MSM) VT220 (Supported for Ope M/SQL o DSM & MSM) VT240 (Supported for Ope M/SQL o DSM & MSM) VT420 (Supported for Ope M/SQL o DSM & MSM) DEC VT 100 Termial DEC VT 220 Termial DEC VT 240 Termial (Regis-md) DEC VT 420 Termial Video WYSE30 WYSE30 Video WYSE60 (D210) WYSE60 (Emulatig Dasher D210) Video WYSE60N WYSE60 Native Mode Termial Video WYSE85 C-WYSE-85 (DEC VT 220 Emulatio) Hard Copy Video DEC Priter HPIII Hewlett-Packard LaserJet III Priter LASER Geeric Laser Priter Priter LN03 Digital LN03 Priter LT100 DEC Letterpriter 100 Priter SQ Suquest PostScript Priter Priter TI Texas Istrumets Priter C-2 Ope M/SQL Developer Guide

387 Ope M/SQL for DSM Ope M/SQL supports the followig termial types for use i the DSM eviromet: DEC VT 100 ad compatibles DEC VT 220 ad compatibles Ope M/SQL for DTM Ope M/SQL supports the DTM-PC Cosole termial type for use i the DTM eviromet. The Cosole device should always use this termial type. Ope M/SQL also supports dumb termials i the DTM eviromet. If you ivoke DTM i multi-user mode, you ca log o to a dumb termial. The default termial type for a dumb termial is VT100, though you may select ay supported termial type at the Termial Type prompt. Ope M/SQL for MSM Eviromet Ope M/SQL supports the followig termial types for use i the MSM eviromet: DEC VT 100 ad compatibles DEC VT 220 ad compatibles DEC VT 240 ad compatibles DEC VT 420 ad compatibles FALCO GENERIC MSM PC Cosole WYSE85 Ope M/SQL supports the MSM PC Cosole termial type for use i the Ope M/SQL MSM-PC/386 eviromet. I order to coect termials other tha the MSM PC cosole, you must use a serial port, a Aret or other board, or a LAT. The MSM-PC/386 eviromet supports oly keyboards whose fuctio keys geerate the DEC VT escape sequeces. It may be possible to use persoal computers coected to a serial port, provided that they use VT termial emulatio software that supports the fuctio keys ad geerates the correct escape sequeces. Some dumb termials may also work if they support a VT100 or VT220 emulatio mode. You should cosult with idividual hardware vedors to ascertai this. Ope M/SQL Developer Guide C-3

388 Appedix C Ope M/SQL Supported Termial Types C-4 Ope M/SQL Developer Guide

389 APPENDIX Full Scree Editor Keyboard Actios D The followig tables show the key mappig scheme for usig the Full Scree Editor o the keyboards associated with the termial types supported by Ope M/SQL. The tables below cotai the followig iformatio: The first colum, Editor Actio, lists the actios supported by the Full Scree Editor eviromet. The secod colum, Key(s) To Press, lists the primary keystroke or keystroke sequece used to ivoke each actio. Altos Table D-1: Altos Keyboard Mappig for the Full Scree Editor Editor Actio Help Meu Begiig of Area Bottom Bottom of Widow Buffer Optios Copy Cut or Paste Delete Back Character Key(s) To Press <F13><F15> <F13><Left Arrow> <F13><B> <F13><SCRN Next> <F13><Dow Arrow> <CTRL-E><B> <CTRL-E><CTRL-B> <CTRL-E><D> <CTRL-E><CTRL-D> <CTRL-E><C> <CTRL-E><CTRL-C> <DEL> Ope M/SQL Developer Guide D-1

390 Appedix D Full Scree Editor Keyboard Actios Table D-1: Altos Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Delete Character Delete Word Do Editor Actio Dow Arrow Ed of Area Ehace Erase Area Fid Geeral Help Goto Tag Elarge Curret Widow Field Help Last Buffer Left Arrow Make Buffer Mark Optios Next Fid Next Scree Next Word Key(s) To Press <CTRL-D> <DEL Char> <CTRL-W> <CTRL-\> <CTRL-E><A> <CTRL-E><\> <CTRL-J> <Dow Arrow> <F13><CTRL-K> <F13><Right Arrow> <CTRL-G> <F13> <CTRL-L> <F13><Del> <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-Y> <CTRL-Z> <F13><Y> <F13><Z> <CTRL-E><?> <CTRL-E><G> <CTRL-E><CTRL-G> <CTRL-E><+> <F14> <CTRL-E><L> <CTRL-E><CTRL-L> <Left Arrow> <CTRL-H> <CTRL-E><=> <CTRL-E><[> <CTRL-E><M> <CTRL-E><CTRL-M> <CTRL-E><N> <CTRL-E><CTRL-N> <SCRN NEXT> <CTRL-F> D-2 Ope M/SQL Developer Guide

391 Altos Table D-1: Altos Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Oe Widow Other Optios Previous Previous Fid Previous Scree Previous Word Query Replace Redraw Scree Retur Right Arrow Save ad Compile Buffer Show Curret Time Switch To Other Widow Tab Toggle Select Top Top of Widow Two Widows Up Arrow Use Buffer Widow Optios Word Capitalize Key(s) To Press <CTRL-E><1> <CTRL-E><O> <CTRL-E><CTRL-O> <F16> <CTRL-E><P> <CTRL-E><CTRL-P> <SCRN Prev> <CTRL-B> <CTRL-E><Q> <CTRL-E><R> <CTRL-E><CTRL-Q> <CTRL-E><CTRL-R> <CTRL-E></> <RETN> <CTRL-K> <Right Arrow> <F12> <CTRL-E><F12> <CTRL-E><T> <CTRL-E><CTRL-T> <CTRL-E><W> <CTRL-E><CTRL-W> <Tab> <CTRL-E><S> <CTRL-E><CTRL-S> <F13><SCRN Prev> <F13><T> <F13><Up Arrow> <CTRL-E><2> <Up Arrow> <CTRL-E><U> <CTRL-E><CTRL-U> <F15> <CTRL-E><-> Ope M/SQL Developer Guide D-3

392 Appedix D Full Scree Editor Keyboard Actios Table D-1: Altos Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Word Lowercase Word Uppercase Key(s) To Press <CTRL-E><_> <CTRL-E><^> ANSI Table D-2: ANSI Keyboard Mappig for the Full Scree Editor Editor Actio Help Meu Advace Begiig of Area Bottom Bottom of Widow Break Buffer Optios Copy Cut or Paste Keys(s) To Press <F1><F3> <CTRL-A> <F1><A> <F1><Left Arrow> <CTRL-V> <F1><Page Dow> <F1><V> <F1><CTRL-J> <F1><Dow Arrow> <CTRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> <CTRL-E><D> <CTRL-E><CTRL-D> <CTRL-E><C> <CTRL-E><CTRL-C> Delete Back Character < <- > <Delete> Delete Character Delete Word <CTRL-D> <F1><D> <CTRL-W> <F1-W> D-4 Ope M/SQL Developer Guide

393 ANSI Table D-2: ANSI Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Do Editor Actio Dow Arrow Ed of Area Ehace Erase Area Erase to Begiig Fid Geeral Help Goto Tag Elarge Curret Widow Field Help Last Buffer Left Arrow Macro Defiitio Make Buffer Mark Optios Next Error i Buffer Next Fid Next Tag Keys(s) To Press <CTRL-^> <CTRL-E><A> <CTRL-E><CTRL-A> <CTRL-J> <Dow Arrow> <F1><CTRL-K> <F1><Right Arrow> <CTRL-G> <F1> <CTRL-L> <F1>< <- > <F1><Delete Key> <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-Y> <CTRL-Z> <F1><Y> <F1><Z> <CTRL-E><?> <CTRL-E><G> <CTRL-E><CTRL-G> <CTRL-E><+> <F2> <CTRL-E><L> <CTRL-E><CTRL-L> <Left Arrow> <F1><K> <CTRL-E><=> <CTRL-E><[> <CTRL-E><M> <CTRL-E><CTRL-M> <CTRL-E><E> <CTRL-E><CTRL-E> <F6> <CTRL-E><N> <CTRL-E><CTRL-N> <CTRL-N> <F1><N> Ope M/SQL Developer Guide D-5

394 Appedix D Full Scree Editor Keyboard Actios Table D-2: ANSI Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Next Scree Next Word Oe Widow Other Optios Paste Previous Fid Previous Scree Previous Tag Previous Word Query Replace Redraw Scree Retreat Retur Right Arrow Save Optios Save ad Compile Buffer Show Curret Time Switch To Other Widow Tab Toggle Select Toggle Sytax Checkig Top Keys(s) To Press <Page Dow> <CTRL-F> <F1><F> <CTRL-E><1> <CTRL-E><O> <Isert> <CTRL-E><P> <CTRL-E><CTRL-P> <Page Up> <CTRL-P> <F1><P> <CTRL-B> <F1><B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <CTRL-R> <F1><R> <RETURN> <CTRL-K> <Right Arrow> <F4> <F5> <CTRL-E><T> <CTRL-E><CTRL-T> <CTRL-E><W> <CTRL-E><CTRL-W> <F1><I> <Tab> <CTRL-E><S> <CTRL-E><@> <CTRL-T> <F1><Page Up> <F1><T> D-6 Ope M/SQL Developer Guide

395 CIT-500 Table D-2: ANSI Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Top of Widow Two Widows Udo Up Arrow Use Buffer View Itermediate Source Widow Optios Word Capitalize Word Lowercase Word Uppercase Keys(s) To Press <F1><CTRL-U> <F1><Up Arrow> <CTRL-E><2> <CTRL-X> <F1><X> <CTRL-U> <Up Arrow> <CTRL-E><U> <CTRL-E><CTRL-U> <CTRL-E><V> <CTRL-E><CTRL-V> <F3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> CIT-500 Table D-3: CIT-500 Keyboard Mappig for the Full Scree Editor Editor Actio Help Meu Advace Begi Select Begiig of Area Bottom Bottom of Widow Keys(s) To Press <F15> <CTRL-A> <PF1><A> <Home> <PF1><CTRL-H> <PF1><Left Arrow> <PF1><B> <PF1><Ceter> <PF1><CTRL-J> <PF1><Dow Arrow> Ope M/SQL Developer Guide D-7

396 Appedix D Full Scree Editor Keyboard Actios Table D-3: CIT-500 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Break Buffer Optios Copy Cut Cut or Paste Delete Back Character Delete Character Delete Word Do Editor Actio Dow Arrow Ed Select Ed of Area Ehace Erase Area Erase to Begiig Fid Geeral Help GETOUTALL Goto Tag Elarge Curret Widow Keys(s) To Press <CTRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> <CTRL-E><D> <CTRL-E><CTRL-D> <Uderscore> <CTRL-E><C> <CTRL-E><CTRL-C> <Delete> <CTRL-D> <CTRL-W> <PF1><W> <CTRL-^> <CTRL-E><CTRL-A> <CTRL-E><a> <PF1><^> <CTRL-J> <Dow Arrow> <PF1><Home> <PF1><CTRL-K> <PF1><Right Arrow> <CTRL-G> <PF1> <CTRL-L> <PF1><Delete> <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-Z> <PF1><Y> <PF1><Z> <CTRL-E><?> <CTRL-E><F15> <PF1><F20> <PF1><PF4> <CTRL-E><G> <CTRL-E><CTRL-G> <CTRL-E><+> D-8 Ope M/SQL Developer Guide

397 CIT-500 Table D-3: CIT-500 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Field Help Last Buffer Left Arrow List Buffers Macro Defiitio Make Buffer Mark Optios Next Fid Next Scree Next Tag Next Word Oe Widow Oly Save Buffer Other Optios Paste Previous Fid Previous Scree Previous Tag Previous Word Query Replace Redraw Scree Keys(s) To Press <PF2> <CTRL-E><L> <CTRL-E><CTRL-L> <CTRL-H> <Left Arrow> <CTRL-E><F9> <PF1><K> <PF1><F16> <CTRL-E><=> <CTRL-E><[> <CTRL-E><M> <CTRL-E><CTRL-M> <F9> <PF1><PF2> <CTRL-E><N> <CTRL-E><CTRL-N> <Ceter> <PF1><N> <CTRL-N> <PF1><N> <CTRL-F> <CTRL-E><1> <F19> <CTRL-E><O> <EOL> <PF1><EOL> <CTRL-E><P> <CTRL-E><CTRL-P> <EOP> <PF1><P> <PF1><P> <CTRL-B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> Ope M/SQL Developer Guide D-9

398 Appedix D Full Scree Editor Keyboard Actios Table D-3: CIT-500 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Retreat Retur Right Arrow Save Optios Save ad Compile Buffer Show Curret Time Switch To Other Widow Tab Toggle Select Top Top of Widow Two Widows Udo Up Arrow Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Keys(s) To Press <CTRL-R> <PF1><R> <RETURN> <CTRL-K> <Right Arrow> <F20> <PF4> <F16> <CTRL-E><F16> <CTRL-E><T> <CTRL-E><CTRL-T> <CTRL-E><W> <CTRL-E><CTRL-W> <PF1><I> <PF1><Tab> <Tab> <CTRL-E><S> <PF1><EOP> <PF1><T> <PF1><CTRL-U> <PF1><Up Arrow> <CTRL-E><2> <CTRL-X> <PF1><Uderscore> <PF1><X> <CTRL-U> <Up Arrow> <CTRL-E><U> <CTRL-E><CTRL-U> <PF3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> D-10 Ope M/SQL Developer Guide

399 Dasher Dasher Table D-4: Dasher Keyboard Mappig for the Full Scree Editor Editor Actio Help Meu Begiig of Area Bottom Bottom of Widow Break Buffer Optios Copy Cut or Paste Delete Back Character Delete Character Delete Word Do Editor Actio Dow Arrow Ed of Area Ed Select Ehace Elarge Curret Widow Erase Area Erase to Begiig Field Help Fid Geeral Help Keys(s) To Press <F10> <C1><Left Arrow> <C1><B> <C1><F12> <C1><Dow Arrow> <CTRL-C> <CTRL-E><CTRL-B> <CTRL-E><B> <CTRL-E><CTRL-D> <CTRL-E><D> <CTRL-E><CTRL-C> <CTRL-E><C> <Delete> <CTRL-D> <CTRL-K> <CTRL-E><CTRL-A> <CTRL-E><A> <Dow Arrow> <C1><Right Arrow> <CTRL-E><B> <C1> <CTRL-G> <CTRL-E><+> <CTRL-L> <Erase Page> <C1><Delete> <C2> <F11> <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-E><?> Ope M/SQL Developer Guide D-11

400 Appedix D Full Scree Editor Keyboard Actios Table D-4: Dasher Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio GETOUTALL Goto Tag Last Buffer Left Arrow Make Buffer Mark Optios Next Fid Next Scree Next Word Oe Widow Other Optios Previous Previous Fid Previous Scree Previous Tag Previous Word Query Replace Redraw Scree Retur Right Arrow Show Curret Time Switch to Other Widow Tab Toggle Select Keys(s) To Press <C1><C4> <CTRL-E><CTRL-G> <CTRL-E><G> <CTRL-E><CTRL-L> <CTRL-E><L> <Left Arrow> <CTRL-E><=> <CTRL-E><[> <CTRL-E><CTRL-M> <CTRL-E><M> <CTRL-E><CTRL-N> <CTRL-E><N> <F12> <CTRL-F> <CTRL-E><1> <CTRL-E><O> <C4> <CTRL-E><CTRL-P> <CTRL-E><P> <F13> <CTRL-P> <CTRL-B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <New Lie> <Right Arrow> <CTRL-E><CTRL-T> <CTRL-T> <CTRL-E><CTRL-W> <CTRL-E><W> <C1><I> <C1><Tab> <Tab> <CTRL-E><S> D-12 Ope M/SQL Developer Guide

401 IBM 3151 ASCII Display Statio Table D-4: Dasher Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Top Top of Widow Two Widows Udo Up Arrow Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Keys(s) To Press <C1><F13> <C1><T> <C1><Up Arrow> <CTRL-E><2> <C1><X> <Up Arrow> <CTRL-E><CTRL-U> <CTRL-E><U> <C3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> IBM 3151 ASCII Display Statio Table D-5: IBM 3151 Key Mappig for the Full Scree Editor Editor Actio Advace Begi Select Begiig of Area Bottom Bottom of Widow Break Buffer Optios Key(s) To Press <F1><A> <CTRL-A> <F8> <F1><Left Arrow> <F1><B> <CTRL-V> <F1><Dow Arrow> <F1><CTRL-J> <CTRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> Ope M/SQL Developer Guide D-13

402 Appedix D Full Scree Editor Keyboard Actios Table D-5: IBM 3151 Key Mappig for the Full Scree Editor (Cotiued) Editor Actio Copy Cut Cut or Paste Delete Back Character Delete Character Delete Word Do Editor Actio Dow Arrow Ed of Area Ehace Erase Area Erase to Begiig Field Help Fid Geeral Help Get Out All Goto Tag Elarge Curret Widow Last Buffer Key(s) To Press <CTRL-E><D> <CTRL-E><CTRL-D> <F7> <CTRL-E><C> <CTRL-E><CTRL-C> <Backspace> <CTRL-D> <CTRL-W> <F1><W> <CTRL-^> <CTRL-E><A> <CTRL-A> <F1><^> <CTRL-J> <Dow Arrow> <F1><CTRL-K> <F1><Right Arrow> <CTRL-G> <F1> <CTRL-L> <F1><Backspace> <F2> <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-Z> <CTRL-E><Help> <CTRL-E><?> <F1><Y> <F1><Z> <F1><F4> <F12> <CTRL-E><G> <CTRL-E><CTRL-G> <CTRL-E><+> <CTRL-E><L> <CTRL-E><CTRL-L> <F1><L> D-14 Ope M/SQL Developer Guide

403 IBM 3151 ASCII Display Statio Table D-5: IBM 3151 Key Mappig for the Full Scree Editor (Cotiued) Editor Actio Left Arrow List Buffers Macro Defiitio Make Buffer Mark Optios Next Fid Next Tag Next Word Oe Widow Oly Save Buffer Other Optios Paste Previous Fid Previous Scree Previous Tag Previous Word Query Replace Redraw Scree Retreat Retur Right Arrow Save ad Compile Buffer Key(s) To Press <Left Arrow> <CTRL-E><Fid> <F1><K> <CTRL-E><=> <CTRL-E><[> <F1><F12> <CTRL-E><M> <CTRL-E><CTRL-M> <CTRL-E><N> <CTRL-E><CTRL-N> <F9> <CTRL-N> <F1><N> <CTRL-F> <CTRL-E><1> <F11> <CTRL-E><O> <F6> <CTRL-E><P> <CTRL-E><CTRL-P> <Home> <CTRL-P> <F1><P> <CTRL-B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <CTRL-R> <F1><R> <RETURN> <CTRL-K> <Right Arrow> <F1><F> <F10> <CTRL-E><Do> Ope M/SQL Developer Guide D-15

404 Appedix D Full Scree Editor Keyboard Actios Table D-5: IBM 3151 Key Mappig for the Full Scree Editor (Cotiued) Editor Actio Save Optios Show Curret Time Switch To Other Widow Tab Toggle Select Top Top of Widow Two Widows Udo Up Arrow Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Key(s) To Press <F4> <F1><S> <CTRL-E><T> <CTRL-E><CTRL-T> <CTRL-E><W> <CTRL-W> <F1><I> <Tab> <CTRL-E><S> <CTRL-T> <F1><T> <F1><Home> <F1><CTRL-U> <F1><Up Arrow> <CTRL-E><2> <CTRL-X> <F1><F7> <F1><X> <CTRL-U> <Up Arrow> <CTRL-E><U> <CTRL-E><CTRL-U> <F3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> D-16 Ope M/SQL Developer Guide

405 IBM PC IBM PC Table D-6: IBM PC Keyboard Mappig for the Full Scree Editor Editor Actio Advace Help Meu Begiig of Area Bottom Bottom of Widow Break Buffer Optios Copy Cut Cut or Paste Delete Back Character Delete Character Delete Word Do Editor Actio Dow Arrow Ed of Area Key(s) To Press <F1><A> <CTRL-A> <F1><F3> <F1><Left Arrow> <F1><Ed> <F1><V> <F1><Page Dow> <F1><CTRL-J> <F1><CTRL-V> <F1><Dow Arrow> <Ed> <CTRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> <CTRL-E><D> <CTRL-E><CTRL-D> <F1><Del> <CTRL-E><C> <CTRL-E><CTRL-C> <Backspace> <CTRL-H> <Delete> <CTRL-D> <F1><D> <DEL> <CTRL-W> <F1><W> <CTRL-^> <CTRL-E><A> <CTRL-E><CTRL-A> <CTRL-J> <CTRL-V> <Dow Arrow> <F1><CTRL-K> <F1><Right Arrow> Ope M/SQL Developer Guide D-17

406 Appedix D Full Scree Editor Keyboard Actios Table D-6: IBM PC Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Ed Select Ehace Erase Area Erase to Begiig Fid Geeral Help Get Out All Goto Tag Elarge Curret Widow Field Help Last Buffer Left Arrow Macro Defiitio Make Buffer Mark Optios Next Fid Next Scree Next Tag Next Word Oe Widow Key(s) To Press <CTRL-E><E> <CTRL-G> <F1> <CTRL-L> <F1><Backspace> <F1><CTRL-H> <F1><Delete> <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-Y> <CTRL-Z> <F1><Y> <F1><Z> <CTRL-E><?> <F1><F4> <CTRL-E><G> <CTRL-E><CTRL-G> <CTRL-E><+> <F2> <F1><F2> <CTRL-E><L> <CTRL-E><CTRL-L> <Left Arrow> <F1><K> <CTRL-E><=> <CTRL-E><[> <CTRL-E><M> <CTRL-E><CTRL-M> <CTRL-E><N> <CTRL-E><CTRL-N> <F6> <PgD> <CTRL-N> <F1><N> <CTRL-F> <F1><F> <CTRL-E><1> D-18 Ope M/SQL Developer Guide

407 IBM PC Table D-6: IBM PC Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Other Optios Paste Previous Fid Previous Scree Previous Tag Previous Word Query Replace Redraw Scree Retreat Retur Right Arrow Save ad Compile Buffer Save Optios Show Curret Time Switch To Other Widow Tab Toggle Select Top Top of Widow Two Widows Udo Key(s) To Press <CTRL-E><O> <Is> <CTRL-E><P> <CTRL-E><CTRL-P> <PgUp> <CTRL-P> <F1><P> <F1><B> <CTRL-B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <CTRL-R> <F1><R> <Eter> <CTRL-K> <Right Arrow> <F1><F10> <F5> <F10> <F4> <CTRL-E><T> <CTRL-E><CTRL-T> <CTRL-E><W> <CTRL-E><CTRL-W> <F1><I> <Tab> <CTRL-E><S> <CTRL-T> <F1><T> <F1><Home> <F1><PgUp> <F1><Up Arrow> <F1><CTRL-U> <CTRL-E><2> <CTRL-X> <F1><X> Ope M/SQL Developer Guide D-19

408 Appedix D Full Scree Editor Keyboard Actios Table D-6: IBM PC Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Up Arrow Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Key(s) To Press <Up Arrow> <CTRL-U> <CTRL-E><U> <CTRL-E><CTRL-U> <F3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> QUME Table D-7: QUME Keyboard Mappig for the Full Scree Editor Editor Actio Help Meu Advace Begiig of Area Bottom of Widow Bottom Break Buffer Optios Copy Cut or Paste Delete Back Character Delete Word Key(s) To Press <PF1><PF3> <CTRL-A> <PF1><A> <PF1><CTRL-H> <PF1><CTRL-J> <PF1><V> <CTRL-V> <CTRL-C> <CTRL-E><CTRL-B> <CTRL-E><B> <CTRL-E><CTRL-D> <CTRL-E><D> <CTRL-E><CTRL-C> <CTRL-E><C> <CTRL-J> <PF1><W> <CTRL-W> D-20 Ope M/SQL Developer Guide

409 QUME Table D-7: QUME Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Delete Character Do Editor Actio Dow Arrow Ed Select Ed of Area Ehace Elarge Curret Widow Exchage Poit ad Mark Fid Geeral Help GETOUTALL Goto Tag Last Buffer Left Arrow Make Buffer Mark Optios Next Fid Next Tag Next Word Next Tag Oe Widow Other Optios Key(s) To Press <PF1><D> <CTRL-D> <CTRL-E><CTRL-A> <CTRL-E><A> <CTRL-^> <CTRL-L> <CTRL-E><D> <PF1><CTRL-K> <PF1><CTRL-L> <CTRL-G> <PF1> <CTRL-E><+> <PF4> <CTRL-E><CTRL-F> <CTRL-E><F> <CTRL-E><?> <PF4> <CTRL-E><CTRL-G> <CTRL-E><G> <CTRL-E><CTRL-L> <CTRL-E><L> <CTRL-H> <CTRL-E><=> <CTRL-E><[> <CTRL-E><CTRL-M> <CTRL-E><M> <CTRL-E><CTRL-N> <CTRL-E><N> <CTRL-N> <PF1><F> <CTRL-F> <PF1><N> <CTRL-E><1> <CTRL-E><O> Ope M/SQL Developer Guide D-21

410 Appedix D Full Scree Editor Keyboard Actios Table D-7: QUME Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Previous Tag Previous Fid Previous Word Query Replace Redraw Scree Retreat Retur Right Arrow Show Curret Time Switch to Other Widow Tab Toggle Select Top of Widow Top Two Widows Udo Up Arrow Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Key(s) To Press <PF1><P> <CTRL-P> <CTRL-E><CTRL-P> <CTRL-E><P> <PF1><B> <CTRL-B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <PF1><R> <CTRL-R> <CTRL-M> <CTRL-K> <CTRL-E><CTRL-T> <CTRL-E><T> <CTRL-E><CTRL-W> <CTRL-E><W> <PF1><I> <CTRL-I> <CTRL-E><S> <PF1><CTRL-U> <PF1><T> <CTRL-T> <CTRL-E><2> <PF1><X> <CTRL-X> <CTRL-U> <CTRL-E><CTRL-U> <CTRL-E><U> <PF3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> D-22 Ope M/SQL Developer Guide

411 Su Su Table D-8: Su Keyboard Mappig for the Full Scree Editor Editor Actio Advace Begi Select Begiig of Area Bottom Bottom of Widow Break Buffer Optios Copy Cut or Paste Delete Back Character Delete Character Delete Word Do Editor Actio Dow Arrow Ed of Area Ed Select Ehace Erase Area Erase to Begiig Key(s) To Press <CTRL-A> <F1><A> <F7> <F1><Left Arrow> <F1><Page Dow> <F1><Ed> <Ed> <F1><Dow Arrow> <CRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> <CTRL-E><D> <CTRL-E><CTRL-D> <CTRL-E><C> <CTRL-E><CTRL-C> <Delete> <Backspace> <Del> <CTRL-D> <CTRL-W> <CTRL-\> <CTRL-E><A> <CTRL-E><\> <Dow Arrow> <CTRL-J> <F1><Right Arrow> <F1><CTRL-K> <F1><F7> <F1> <CTRL-G> <CTRL-L> <F1><Del> <F1><Delete> Ope M/SQL Developer Guide D-23

412 Appedix D Full Scree Editor Keyboard Actios Table D-8: Su Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Fid Geeral Help GETOUTALL Goto Tag Help Meu Elarge Curret Widow Field Help Last Buffer Left Arrow List Buffers Macro Defiitio Make Buffer Mark Optios Next Error i Buffer Next Fid Next Scree Next Word Next Tag Oe Widow Other Optios Oly Save Buffer Key(s) To Press <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-Y> <CTRL-E><?> <F10> <F1><F10> <F1><F4> <CTRL-E><G> <CTRL-E><CTRL-G> <Help> <F1><F3> <CTRL-E><+> <F2> <CTRL-E><L> <CTRL-E><CTRL-L> <Left Arrow> <CTRL-H> <CRTL-E><F6> <F1><K> <CTRL-E><=> <CTRL-E><[> <CTRL-E><M> <CTRL-E><CTRL-M> <CTRL-E><E> <CTRL-E><CTRL-E> <F6> <CTRL-E><N> <CTRL-E><CTRL-N> <Page Dow> <F1><N> <CTRL-F> <CTRL-N> <CTRL-E><1> <CTRL-E><O> <F9> D-24 Ope M/SQL Developer Guide

413 Su Table D-8: Su Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Paste Previous Fid Previous Scree Previous Word Previous Tag Query Replace Redraw Scree RETURN Retreat Right Arrow Save Optios Save ad Compile Buffer Show Curret Time Switch To Other Widow TAB Toggle Select Toggle Sytax Checkig Top Top of Widow Two Widows Up Arrow Key(s) To Press <Isert> <F1><Isert> <CTRL-E><P> <CTRL-E><CTRL-P> <Page Up> <F1><P> <CTRL-B> <F1><B> <CTRL-P> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <RETURN> <CTRL-R> <Right Arrow> <CTRL><K> <F4> <F5> <F1><F> <CTRL-E><T> <CTRL-E><CTRL-T> <CTRL-E><W> <CTRL-E><CTRL-W> <Tab> <F1><I> <CTRL-E><S> <CTRL-E><CTRL-S> <F1><Page Up> <F1><Home> <CTRL><T> <F1><Up Arrow> <Home> <F1><CTRL-U> <CTRL-E><2> <Up Arrow> <CTRL-U> Ope M/SQL Developer Guide D-25

414 Appedix D Full Scree Editor Keyboard Actios Table D-8: Su Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Udo View Itermediate Source Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Key(s) To Press <CTRL-X> <CTRL-E><V> <CTRL-E><CTRL-V> <CTRL-E><U> <CTRL-E><CTRL-U> <F3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> Televideo 905 Table D-9: Televideo 905 Key Mappig for Full Scree Editor Editor Actio Advace Begiig of Area Bottom Bottom of Widow Break Buffer Optios Copy Cut or Paste Delete Back Character Delete Character Key(s) To Press <CTRL-A> <F1><A> <F1><Left Arrow> <F1><V> <F1><Dow Arrow> <CTRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> <CTRL-E><D> <CTRL-E><CTRL-D> <CTRL-E><C> <CTRL-E><CTRL-C> <Del> <CTRL-D> <F1><D> D-26 Ope M/SQL Developer Guide

415 Televideo 905 Table D-9: Televideo 905 Key Mappig for Full Scree Editor (Cotiued) Editor Actio Delete Word Do Editor Actio Dow Arrow Ed of Area Ehace Erase Area Erase to Begiig Erase to Ed Fid Geeral Help GETOUTALL Goto Tag Help Meu Elarge Curret Widow Field Help Left Arrow Make Buffer Next Scree Next Word Next Tag Oe Widow Other Optios Paste PREVIOUS Previous Scree Key(s) To Press <CTRL-W> <F1><W> <CTRL><^> <CTRL-E><a> <CTRL-E><CTRL-A> <Dow Arrow> <CTRL-v> <F1><Right Arrow> <F1> <CTRL-G> <Lie Erase> <F1><Del> <CTRL-U> <CTRL-E><F> <CTRL-E><CTRL-F> <F2> <F1><F4> <CTRL-E><G> <CTRL-E><CTRL-G> <F1><F3> <CTRL-E><+> <PF2> <Left Arrow> <CTRL-E><=> <CTRL-E><[> <F1><N> <CTRL-F> <F1><F> <CTRL-N> <CTRL-E><1> <CTRL-E><O> <Lie Isert> <F4> <F1><P> Ope M/SQL Developer Guide D-27

416 Appedix D Full Scree Editor Keyboard Actios Table D-9: Televideo 905 Key Mappig for Full Scree Editor (Cotiued) Editor Actio Previous Word Previous Tag Query Replace Redraw Scree RETURN Retreat Right Arrow Save Optios Save ad Compile Buffer TAB Toggle Select Top Top of Widow Two Widows Up Arrow Udo Widow Optios Word Capitalize Word Lowercase Word Uppercase Key(s) To Press <CTRL-B> <F1><B> <CTRL-F> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <RETURN> <CTRL-R> <F1><R> <Right Arrow> <F1><F> <Esc><Esc> <Tab> <F1><I> <CTRL-E><S> <F1><T> <CTRL-T> <F1><Up Arrow> <CTRL-E><2> <Up Arrow> <CTRL-K> <CTRL-X> <F1><X> <F3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> D-28 Ope M/SQL Developer Guide

417 DEC VT 100 DEC VT 100 Table D-10: VT100 Key Mappig for the Full Scree Editor Editor Actio Help Meu Advace Begiig of Area Bottom Bottom of Widow Break Buffer Optios Copy Cut or Paste Delete Back Character Delete Character Delete Word Do Editor Actio Dow Arrow Ed of Area Ed Select Ehace Elarge Curret Widow Erase Area Erase to Begiig Field Help Key(s) To Press <PF1><PF3> <CTRL-A> <PF1> <PF1><Left Arrow> <PF1><CTRL-H> <PF1><B> <PF1><Dow Arrow> <PF1><CTRL-J> <CTRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> <CTRL-E><CTRL-D> <CTRL-E><D> <CTRL-E><CTRL-C> <CTRL-E><C> <DELETE> <CTRL-D> <CTRL-W> <CTRL-^> <CTRL-E><CTRL-A> <CTRL-E><A> <CTRL-J> <Dow Arrow> <PF1><Right Arrow> PF1><CTRL-K> <CTRL-E><E> <CTRL-G> <PF1> <CTRL-E><+> <CTRL-L> <PF1><Del> <PF2> Ope M/SQL Developer Guide D-29

418 Appedix D Full Scree Editor Keyboard Actios Table D-10: VT100 Key Mappig for the Full Scree Editor (Cotiued) Editor Actio Fid Geeral Help Get Out All Goto Tag Last Buffer Left Arrow Make Buffer Mark Optios Next Fid Next Tag Next Word Oe Widow Other Optios Previous Fid Previous Tag Previous Word Query Replace Redraw Scree Retreat Retur Key(s) To Press <CTRL-E><CTRL-F> <CTRL-E><F> <CTRL-Z> <PF1><K> <PF1><Y> <PF1><Z> <CTRL-E><?> <PF1><PF4> <CTRL-E><CTRL-G> <CTRL-E><G> <CTRL-E><CTRL-L> <CTRL-E><L> <CRTL-H> <Left Arrow> <PF1><PF2> <CTRL-E><=> <CTRL-E><[> <CTRL-E><CTRL-M> <CTRL-E><M> <CTRL-E><CTRL-N> <CTRL-E><N> <PF1><N> <CTRL-N> <CTRL-F> <CTRL-E><1> <CTRL-E><O> <CTRL-E><CTRL-P> <CTRL-E><P> <PF1><P> <CTRL-B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <CTRL-R> <PF1><R> <RETURN> D-30 Ope M/SQL Developer Guide

419 DEC VT 100 Table D-10: VT100 Key Mappig for the Full Scree Editor (Cotiued) Editor Actio Right Arrow Save Optios Show Curret Time Switch to Other Widow Tab Toggle Select Top Top of Widow Two Widows Udo Up Arrow Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Key(s) To Press <CTRL-K> <Right Arrow> <PF1><S> <PF4> <CTRL-E><CTRL-T> <CTRL-E><T> <CTRL-E><CTRL-W> <CTRL-E><W> <PF1><I> <PF1><Tab> <Tab> <CTRL-E><S> <PF1><T> <PF1><Up Arrow> <PF1><U> <CTRL-E><2> <PF1><X> <CTRL-U> <Up Arrow> <CTRL-E><CTRL-U> <CTRL-E><U> <PF3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> Ope M/SQL Developer Guide D-31

420 Appedix D Full Scree Editor Keyboard Actios DEC VT 200 Table D-11: VT200 Keyboard Mappig for the Full Scree Editor Editor Actio Advace Help Meu Begi Select Begiig of Area Bottom Bottom of Widow Break Buffer Optios Copy Cut Cut or Paste Delete Back Character Delete Character Delete Word Do Editor Actio Dow Arrow Ed Select Ed of Area Key(s) To Press <CTRL-A> <PF1><A> <Help> <Select> <PF1><CTRL-H> <PF1><Left Arrow> <PF1><B> <PF1><Next Scree> <PF1><CTRL-J> <PF1><Dow Arrow> <CTRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> <CTRL-E><D> <CTRL-E><CTRL-D> <Remove> <CTRL-E><C> <CTRL-E><CTRL-C> <Delete> <CTRL-D> <CTRL-W> <PF1><W> <CTRL-\> <CTRL-^> <PF1><^> <CTRL-E><CTRL-A> <CTRL-E><A> <CTRL-J> <Dow Arrow> <PF1><Select> <PF1><CTRL-K> <PF1><Right Arrow> D-32 Ope M/SQL Developer Guide

421 DEC VT 200 Table D-11: VT200 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Ehace Erase Area Erase to Begiig Fid Geeral Help Get Out All Goto Tag Elarge Curret Widow Help Last Buffer Left Arrow List Buffers Macro Defiitio Make Buffer Mark Optios Next Fid Next Scree Next Tag Next Word Key(s) To Press <CTRL-G> <PF1> <CTRL-L> <PF1><Delete> <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-Z> <PF1><Y> <PF1><Z> <CTRL-E><?> <CTRL-E><Help> <PF1><F20> <PF1><PF4> <CTRL-E><G> <CTRL-E><CTRL-G> <CTRL-E><+> <PF2> <CTRL-E><L> <CTRL-E><CTRL-L> <CTRL-H> <Left Arrow> <CTRL-E><Fid> <PF1><K> <PF1><Do> <CTRL-E><=> <CTRL-E><[> <CTRL-E><M> <CTRL-E><CTRL-M> <Fid> <PF1><PF2> <CTRL-E><N> <CTRL-E><CTRL-N> <Next Scree> <PF1><N> <CTRL-N> <PF1><N> <CTRL-F> Ope M/SQL Developer Guide D-33

422 Appedix D Full Scree Editor Keyboard Actios Table D-11: VT200 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Oe Widow Oly Save Buffer Other Optios Paste Previous Fid Previous Scree Previous Tag Previous Word Query Replace Redraw Scree Retreat Retur Right Arrow Save Optios Save ad Compile Buffer Show Curret Time Switch To Other Widow Tab Toggle Select Top Top of Widow Two Widows Key(s) To Press <CTRL-E><1> <F19> <CTRL-E><O> <Isert Here> <PF1><Isert Here> <CTRL-E><P> <CTRL-E><CTRL-P> <PF1><P> <Prev Scree> <PF1><P> <CTRL-B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <CTRL-R> <PF1><R> <RETURN> <CTRL-K> <Right Arrow> <F20> <PF4> <Do> <CTRL-E><Do> <CTRL-E><T> <CTRL-E><CTRL-T> <CTRL-E><W> <CTRL-E><CTRL-W> <PF1><I> <PF1><Tab> <Tab> <CTRL-E><S> <PF1><Prev Scree> <PF1><T> <PF1><CTRL-U> <PF1><Up Arrow> <CTRL-E><2> D-34 Ope M/SQL Developer Guide

423 DEC VT 220 Table D-11: VT200 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Udo Up Arrow Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Key(s) To Press <CTRL-X> <PF1><Remove> <PF1><X> <CTRL-U> <Up Arrow> <CTRL-E><U> <CTRL-E><CTRL-U> <PF3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> DEC VT 220 Table D-12: VT220 Keyboard Mappig for the Full Scree Editor Editor Actio Advace Help Meu Begi Select Begiig of Area Bottom Bottom of Widow Break Buffer Optios Key(s) To Press <PF1><A> <CTRL-A> <Help> <Select> <PF1><CTRL-H> <PF1><Left Arrow> <PF1><B> <PF1><Next Scree> <PF1><CTRL-J> <PF1><Dow Arrow> <CTRL-C> <CTRL-E><B> <CTRL-E><CTRL-B> Ope M/SQL Developer Guide D-35

424 Appedix D Full Scree Editor Keyboard Actios Table D-12: VT220 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Copy Cut Cut or Paste Delete Back Character Delete Character Delete Word Do Editor Actio Dow Arrow Ed of Area Ed Select Ehace Erase Area Erase to Begiig Field Help Fid Geeral Help GETOUTALL Goto Tag Elarge Curret Widow Last Buffer Key(s) To Press <CTRL-E><D> <CTRL-E><CTRL-D> <Remove> <CTRL-E><C> <CTRL-E><CTRL-C> <DEL> <CTRL-D> <CTRL-W> <PF1><W> <CTRL-^> <PF1><^> <CTRL-E><A> <CTRL-E><CTRL-A> <CTRL-J> <Dow Arrow> <PF1><CTRL-K> <PF1><Right Arrow> <PF1><Select> <CTRL-G> <PF1> <CTRL-L> <PF1><Delete> <PF2> <CTRL-E><F> <CTRL-E><CTRL-F> <CTRL-Z> <CTRL-E><Help> <CTRL-E><?> <PF1><Y> <PF1><Z> <PF1><PF4> <CTRL-E><G> <CTRL-E><CTRL-G> <CTRL-E><+> <CTRL-E><L> <CTRL-E><CTRL-L> <PF1><L> D-36 Ope M/SQL Developer Guide

425 DEC VT 220 Table D-12: VT220 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Left Arrow List Buffers Macro Defiitio Make Buffer Mark Optios Next Fid Next Tag Next Scree Next Word Oe Widow Oly Save Buffer Other Optios Paste Previous Fid Previous Scree Previous Tag Previous Word Query Replace Redraw Scree Retreat Retur Key(s) To Press <Left Arrow> <CTRL-H> <CTRL-E><Fid> <PF1><K> <PF1><Do> <CTRL-E><[> <CTRL-E><=> <CTRL-E><M> <CTRL-E><CTRL-M> <CTRL-E><N> <CTRL-E><CTRL-N> <Fid> <PF1><PF2> <CTRL-N> <PF1><N> <PF1><N> <Next Scree> <CTRL-F> <CTRL-E><1> <F19> <CTRL-E><O> <Isert Here> <PF1><Isert Here> <CTRL-E><P> <CTRL-E><CTRL-P> <PF1><P> <Prev Scree> <PF1><P> <CTRL-B> <CTRL-E><R> <CTRL-E><CTRL-R> <CTRL-E></> <CTRL-R> <PF1><R> <RETURN> Ope M/SQL Developer Guide D-37

426 Appedix D Full Scree Editor Keyboard Actios Table D-12: VT220 Keyboard Mappig for the Full Scree Editor (Cotiued) Editor Actio Right Arrow Save ad Compile Buffer Save Optios Show Curret Time Switch To Other Widow Tab Toggle Select Top Top of Widow Two Widows Udo Up Arrow Use Buffer Widow Optios Word Capitalize Word Lowercase Word Uppercase Key(s) To Press <CTRL-K> <Right Arrow> <Do> <CTRL-E><Do> <PF1><F> <PF4> <PF1><S> <CTRL-E><T> <CTRL-E><CTRL-T> <CTRL-E><W> <CTRL-E><CTRL-W> <Tab> <PF1><Tab> <PF1><I> <CTRL-E><S> <PF1><T> <PF1><Prev Scree> <PF1><CTRL-U> <PF1><Up Arrow> <CTRL-E><2> <CTRL-X> <PF1><Remove> <PF1><X> <Up Arrow> <CTRL-U> <CTRL-E><U> <CTRL-E><CTRL-U> <PF3> <CTRL-E><-> <CTRL-E><_> <CTRL-E><^> D-38 Ope M/SQL Developer Guide

427 WYSE-60 (Native Mode) WYSE-60 (Native Mode) Table D-13: WYSE-60 Key Mappig for the Full Scree Editor Editor Actio Primary Key Alterate Key(s) Advace <Ehace><A> <CTRL-A> Begiig of Area <Ehace><Left Arrow> <Ehace><CTRL-H> <Backspace> Bottom of List <Ehace><Page Dow> <Ehace>-V <Ed> Bottom of Widow <Ehace><Dow Arrow> <Ehace><CTRL-J> Break <CTRL-C> Buffer Optios <CTRL-E>/B <CTRL-E><CTRL-B> Copy <CTRL-E>/D <CTRL-E><CTRL-D> Cut <Delete> Cut or Paste <CTRL-E>/C <CTRL-E><CTRL-C> Delete Word Delete Previous Character Delete Character <CTRL-W> <Del> <CTRL-D> Do Editor Actio <Is> <Ehace>-^ Dow Arrow <Dow Arrow> <CTRL-J> Ed of Area Ed Select <Ehace><Right Arrow> <CTRL-E>/E Ehace <PF1> <CTRL-G> Erase Area <PF12> <CTRL-U> Erase to Begiig Explai <Ehace><Del> <PF2> Fid <CTRL-E>/F <CTRL-E><CTRL-F> GETOUT <PF10> <Ehace><F> GETOUTALL <Ehace><PF10> <Ehace><PF4> Geeral Help <Ehace><K> <CTRL-Z> Goto Tag <CTRL-E>/G <CTRL-E><CTRL-G> Grow Curret Widow <CTRL-E>/+ Ope M/SQL Developer Guide D-39

428 Appedix D Full Scree Editor Keyboard Actios Table D-13: WYSE-60 Key Mappig for the Full Scree Editor (Cotiued) Editor Actio Primary Key Alterate Key(s) Help Meu <Ehace><PF3> Isert/Typeover Toggle <Is> <Ehace><Is> Key Help <Ehace><PF2> Last Buffer <CTRL-E>/L <CTRL-E><CTRL-L> Left Arrow <Left Arrow> <CTRL-H> <Backspace> Make Buffer <CTRL-E> = <CTRL-E> [ Mark Optios <CTRL-E> M <CTRL-E><CTRL-M> Next Fid <PF6> <CTRL-E> <N> Next Scree <Page Dow> Next Tag <CTRL-N> <Ehace><N> Next Word Other Optios <CTRL-F> <CTRL-E> O Oe Widow <CTRL-E> 1 Paste <Isert> <Ehace><Isert> <Ehace><G> Previous Fid <CTRL-E> P <CTRL-E><CTRL-P> Previous Scree Previous Tag Previous Word <Page Up> <Ehace><P> <CTRL-B> Query Replace <CTRL-E> R <CTRL-E><CTRL-R> Redraw Scree <CTRL-E> / Retreat <CTRL-R> <Ehace><R> RETURN <Retur> Right Arrow <Right Arrow> <CTRL-L> SAVE Optios <PF4> <PF9 <>Ehace><S> Save ad Compile Buffer <PF5> <Esc><Esc> Show Curret Time <CTRL-E> <T> <CTRL-E><CTRL-T> Switch to Other Widow <CTRL-E> <W> <CTRL-E> <CTRL-W> Tab Toggle Select <Tab> <CTRL-E> <Y> D-40 Ope M/SQL Developer Guide

429 WYSE-60 (Native Mode) Table D-13: WYSE-60 Key Mappig for the Full Scree Editor (Cotiued) Editor Actio Primary Key Alterate Key(s) Top of Widow <Ehace><Up Arrow> <Ehace>-<CTRL-K> Top <Ehace><Page Up> <Ehace><T> Two Widows <CTRL-E> <2> Udo <CTRL-X> <Ehace>-<CTRL-X> Up Arrow <Up Arrow> <CTRL-K> Use Buffer <CTRL-E> U <CTRL-E><CTRL-U> Widow Optios <PF3> Word Capitalize <CTRL-E> - Word Lowercase Word Uppercase <CTRL-E> _ <CTRL-E> ^ Ope M/SQL Developer Guide D-41

430 Appedix D Full Scree Editor Keyboard Actios D-42 Ope M/SQL Developer Guide

431 Glossary of Terms Applicatio A set of forms, reports, ad other objects ad programs liked together by meus to form a structure that provides a workig user iterface to a database. Applicatio Help Facility Applicatio Mode A suite of help features ad utilities that allows you to develop ad deploy a cotext-sesitive o-lie help system for your Ope M/SQL applicatios. The mode i which applicatio ed-users iteract with a database usig forms ad widows desiged by the applicatio developer. I applicatio mode, users eter the applicatio directly from the operatig system prompt ad ever see the M prompt. Navigatio is typically guided by a meu structure desiged by the applicatio developer. Applicatio Program Iterface (API) Auxiliary Widow Software o your cliet machie that hadles the iterface betwee a applicatio tool or C applicatio ad the server, ad maages commuicatios with the server. The Relatioal Cliet supports two APIs, the ORACLE Call Iterface (OCI) ad Microsoft s Ope Database Coectivity (ODBC). Ay widow defied for a form that is either the form s master widow or its row selectio widow, i.e., ay widow i a form that is ot the first widow to appear whe the form is ivoked. Forms may have multiple auxiliary widows. Ope M/SQL Developer Guide Glossary-1

432 Glossary Base Table Brachig Field Caller ID Cascadig Meus A collectio of data represeted i a simple 2-dimesioal format cosistig of oe or more rows with oe or more colums. Each row has at most oe value for each colum, ad each row is uique, meaig that it differs by at least oe colum value from every other row. Base tables are mapped directly to physical storage structures. A form-oly field of data type Brachig whose sole purpose is to serve as a mask for a uderlyig trigger actio, which typically braches to aother widow withi the curret form or to the master widow of aother form. Brachig fields ca also ivoke other actios besides a widow brach. O a widow, brachig fields are represeted by their captios, which always appear eclosed i brackets. Idetifier that allows each meu item or form trigger that calls a form, widow, or meu to idetify itself to the called object. The Caller ID is stored i the {%caller} exteral referece variable. Term used to describe the style of presetatio for a pop-up meu that is called by aother pop-up meu. Multiple pop-up meus called i successio cascade o the scree so as ot to overlap. Characteristic Relatioship Child Form A programmer-defied joi betwee base tables i which rows i a child table are existece-depedet o rows i a paret table i a may-to-oe maer a sigle paret row ca have may child rows. A form whose data source is a child table. Child forms may be sigle-row or multi-row ad may access rows with the paret kow or ot kow. If the paret is kow, rows are called from the RowID i the paret table, which limits row selectio to childre of the paret table RowID. If the paret is ot kow, all child table rows are selected. Glossary-2 Ope M/SQL Developer Guide

433 Glossary Child Table Code Geeratio Colum A base table that is existece-depedet o aother table (its paret) i a characteristic relatioship. Rows i a child table must have a poiter to a row i the paret table. The process by which the Ope M/SQL compiler geerates executable M routies from programmer specificatios. This happes whe you compile a Ope M/SQL base table, form, meu object, or report. See Field. Commuicatios Protocol Compilatio Computed Field Coversio Code A set of covetios that defies how data is trasferred betwee computers o a etwork. More specifically, it is the software that determies how a message packet is formatted. Commuicatio protocols are used to talk to a etwork iterface device. More tha oe commuicatio protocol ca share the same physical iterface device. The Ope M/SQL Relatioal Cliet curretly supports the followig commuicatio protocols: TCP/IP, DECet (for VAX/VMS systems oly), ad Memory-to-Memory (for DTM systems oly). The process i which programmer specificatios are traslated by the Ope M/SQL compiler ito macro source code ad stored as.mac routies. The macro preprocessor uses macro source code routies to produce itermediate code, which is the saved as executable M code (called object code). A field whose value is derived from a calculatio defied i M code. The M code ca referece other fields i the associated base table as well as M fuctios ad special variables. M code used by Ope M/SQL to covert field data values from exteral iput formats to iteral storage formats ad from iteral storage formats to exteral display formats. Ope M/SQL Developer Guide Glossary-3

434 Glossary Cursor Cursor-Based SQL Database Data Dictioary Database Field Database Form Data Source A idetifier for a SQL request. Oce a cliet applicatio has established a coectio with the server, it creates a cursor. Whe the cliet applicatio wats to sed a SQL request to the server, it associates the request with a cursor. A applicatio ca have multiple cursors active withi a coectio. Oly oe SQL request is associated with a cursor at a give poit i time. Oce the applicatio receives the server s respose to a request, however, it ca reuse the cursor for aother request. A type of embedded SQL query that opes a cursor to process the query. Whe your applicatio eeds to access multiple rows of data, you must use a cursor. A cursor acts like a poiter it focuses o accessig ad processig oe row at a time, the moves from that row to the ext i the sequece. A collectio of related data. A compoet of Ope M/SQL used to describe the elemets of the relatioal database, icludig both its coceptual cotet ad the mappig of its logical data defiitios to physical data structures i the global database. A field that is defied i a Data Dictioary base table. A form has access to all database fields defied for its associated base table. You ca eve modify certai display characteristics of the field at the form level. Ay form that uses a Data Dictioary base table as its data source. The Data Dictioary base table from which a database form retrieves its data. A form may have oly oe data source. No-database forms do ot have ay data source. Forms caot use views as their data source. Glossary-4 Ope M/SQL Developer Guide

435 Glossary Desigated Table The Data Dictioary base table that is refereced (poited to) by a Desigative Referece field ad accessed by Desigative Display fields i a cross-table referece form. Desigative Display Field A form-oly field based o a Desigated Referece field (defied i the associated base table) that retrieves data from (ad optioally adds data to) a specified field i the desigated table. Desigative Display fields are the vehicles of crosstable referecig. You may create Desigative Display fields for ay fields i the desigated table, ad you may place them o widows i the form. Desigative Referece Developer Device Directory DTM Embedded SQL A programmer-defied joi betwee two base tables i which oe field of the desigatig table cotais the Row IDs of all rows i the refereced table. I relatioal database termiology, the desigatig table has a foreig key o the refereced table. A compoet of Ope M/SQL that allows applicatio developers to use both program-level code ad applicatio geerator techology to create relatioal database applicatios. A piece of hardware that is part of a computer system, such as a termial, priter, disk drive, or magetic tape drive. A ame for a locatio o a disk where files ca be stored. IterSystems implemetatio of the M programmig laguage desiged to ru o IBM-compatible PCs based o Itel ad higher microprocessors. SQL statemets that are directly embedded withi M routies at the macro source code level. These statemets are prefixed by the M bidig sytax, &sql. Ope M/SQL Developer Guide Glossary-5

436 Glossary Export/Import Utility Exteral Value Fields Field Captio Foreig Key Forms Form Geerator Form-Oly Field A widow-based utility that allows you to port Ope M/SQL objects (base tables, views, forms, reports, queries, meus, meu objects, help topics, ad help documets) betwee differet directories ad differet computers. The value of a field i its exteral display format, i.e., after it has passed through iteral-to-exteral coversio code. A field may have both a iteral ad a exteral value. A amed uit of data i a base table row, usually represetig a real world etity, such as a ame, social security umber, or date of birth for that row. Also called colum or attribute. The descriptive text attached to a field o a widow. See Desigative Referece. A collectio of oe or more associated widows that either displays iformatio or prompts the user to eter iformatio, or both. A applicatio geerator compoet of Ope M/SQL that allows applicatio developers to desig highly sophisticated widow-based forms that iteract with the Relatioal Data Dictioary (or optioally a alterative data source) to add, update, retrieve, ad delete database iformatio. A field that is created for a form ad exists oly at the form level, idepedet of the Data Dictioary. Form-oly fields may appear o a form but caot file data to the Data Dictioary. All fields o a o-database form are form-oly. Glossary-6 Ope M/SQL Developer Guide

437 Glossary Form-Oly Form Full Scree Editor Global Global Database Help Documet A o-database form that does ot file data to ay data structure. A ISM (IterSystems origial implemetatio of M) utility that allows you to create, edit, ad view macro source code routies, itermediate code routies, ad iclude files. A disk-based data storage uit specified by the M programmig laguage stadard. Also called global variables, these are commoly implemeted usig balaced-tree techology. A database i which all data is stored i a system of multiply-subscripted arrays called globals. This is the uderlyig logical ad physical data storage structure of a Ope M/SQL database. Relatioal tables are mapped to the global database through the Ope M/SQL Relatioal Data Dictioary. A user documetatio maual for your applicatio based o the help defiitios you have already created. You create help documets usig the Help Documet Creatio facility. A help documet cosists of chapter umbers ad titles, paragraph/sectio headigs ad umbers, scree images of meus, scree images of forms, scree images of idividual widows, log ad short help messages for meu optios ad fields, help topic text, ad optioally a automatically geerated table of cotets ad idex. Help Documet Creatio Facility A extesio to the Applicatio Help facility that allows you to create a prited documetatio maual for your applicatio based o the help defiitios you have already created. Help Text Etry Facility A extesio to the Applicatio Help facility that cetralizes access to the help attributes associated with forms ad meu objects ad provides a easy-to-use iterface for creatig help text defiitios ad deployig them throughout a applicatio. Ope M/SQL Developer Guide Glossary-7

438 Glossary Help Topic Horizotal Meu Implicit Joi Iclude File Idex Map A block of programmer-defied help text which you ca make available to edusers i a cotext-sesitive fashio at various poits i a applicatio by attachig it to base tables, forms, widows, meu objects, ad meu object choices or by eablig it via triggers. A type of old-style meu that is tied to a widow o a form ad displays its list of optios horizotally across the bottom of the scree just below the status lie of the widow to which it is tied. A programmer-defied joi betwee related tables defied i the Data Dictioary that allows you to query multiple tables without specifyig data access restrictios i the WHERE clause. Implicit jois ca desigate characteristic relatioships or desigative refereces. Files cotaiig defiitios that ca be used i the preprocessor phase of compilatio to expad macro source routies ad determie whether optioal lies of code should be icluded. Iclude files ca also be used to iclude a commo block of code i several routies, savig the overhead of calls to a commo subroutie. A map for oe or more database fields that cotais the Row ID of each row i a base table. Idex maps speed up access to rows looked up by values for the idex fields ad allow rapid retrieval of rows sorted by oe or more idex fields. The Ope M/SQL Data Dictioary automatically geerates idex maps for all fields specified as lookup fields i the lookup specificatios for a base table (whe default physical structure is used). Itegrity Costraits Programmer-defied costraits o data isert, update, ad delete operatios that esure the accuracy ad completeess of the applicatio ad the uderlyig database. Glossary-8 Ope M/SQL Developer Guide

439 Glossary Iteractive Query Editor Ope M/SQL facility for defiig ad ruig ad hoc queries. The Iteractive Query Editor provides a free-form SQL editor eviromet (similar to the Full Scree Editor) that eables users to defie ad ru ay sytactically valid SQL query. The Iteractive Query Editor also provides full scree editig capabilities. Itermediate Source Code Iteral Value Joi The stadard 3GL M source code available i all M implemetatios. Itermediate code is produced from macro source code by the Ope M/SQL compiler. At the itermediate code level, all preprocessor sytax, icludig embedded SQL, is resolved, ad the routie cotais oly pure M source code. You ca write M routies directly at the itermediate code level, but you caot use embedded SQL or other preprocessor sytax, such as macros. The value of a field as stored iterally by Ope M/SQL, i.e., after it has passed through exteral-to-iteral coversio code. A field may have both a iteral ad a exteral value. A lik betwee base tables that defies the relatioship betwee the data i those tables. Lear-As-You-Go (LAYGO) Licese Logi The ability for a form to add ew rows to a foreig base table at ru time. A agreemet betwee IterSystems ad its customer that defies the compoets of Ope M software available to the customer ad the umber of users who ca use each compoet. A customer must be licesed i order to ru Ope M. Licese iformatio is distributed i a Product Activatio Key ad stored o your system i a file amed MSQL.KEY. The act of sigig o to a system. Database admiistrators ad applicatio developers log i to Ope M/SQL by typig do ^%msql at the M prompt ad the providig UserName ad Password iformatio at the Ope M/SQL User Idetificatio widow. Ope M/SQL Developer Guide Glossary-9

440 Glossary Log Help Message A multiple-lie programmer-defied help text message associated with a field or meu object choice that displays to the scree i a ru-time widow whe the user presses the <EXPLAIN> key twice i successio from a field or meu object choice. For fields, you may defie triggers to automatically display the log help message based o certai ru-time circumstaces. Lookup Display Field Lookup Field Field or combiatio of fields whose values are displayed i the lookup box that lists all matchig etries retrieved by the lookup query i row selectio for sigle-row forms. The iformatio displayed by these fields helps the user select the appropriate row. Field or combiatio of fields used by sigle-row forms to select rows from the database. Whe a form is ru, the user eters lookup iformatio ito the lookup field(s), ad the system rus a lookup query to match the user iput agaist actual database values. Lookup Specificatios Lookup Query M Laguage M Database The complete set of all lookup queries, icludig their lookup fields ad lookup display fields, defied to perform row selectio for a sigle-row form. A set of lookup fields ad lookup display fields defied to perform row selectio for a sigle-row form. A Sigle-row form may have multiple lookup queries. A ANSI-Stadard procedural programmig laguage specifically desiged for database applicatios. M is the foudatio techology of IterSystems etire Ope M product lie. A MUMPS.DAT file ad, o server systems that support multivolume databases, from 0 through 7 MUMPS.EXT files. Glossary-10 Ope M/SQL Developer Guide

441 Glossary Macro Preprocessor Macro Source Code Map Master Map Master Widow Meu Meu Geerator Phase of the Ope M/SQL Compiler that coverts macro source code, which may iclude macro costructs ad embedded SQL, ito itermediate code, which is pure M source code. The macro preprocessor resolves macros ad code-geerates embedded SQL. The highest, most flexible ad permissive level of code at which routies ca be writte. Macro source code permits the defiitio of macros ad embedded SQL statemets usig a combiatio of ANSI-Stadard M sytax, special macro preprocessor commads, ad ANSI-Stadard SQL. A map describes the relatioship of the logical structure of a base table to the physical structure of the uderlyig global database. The Ope M/SQL Relatioal Data Dictioary uses maps to describe a M global database i relatioal terms. Each base table has exactly oe master map. The master map defies the global structure for all of the data fields i the base table. I M termiology, the master map defies the upright file. The itroductory widow of ay form. Every form must have a master widow i order to be compiled ad ru. No form ca have more tha oe master widow. A list of oe or more choices, each of which ivokes a actio that performs a specific task. Meus ca display their optios vertically (top to bottom) or horizotally (left to right). Meus are typically used to uite various compoets of a applicatio ad provide access to them from a cetral locatio. A applicatio geerator compoet of Ope M/SQL that allows applicatio developers to desig ad maitai meus for a applicatio. Meus uite the various compoets of a applicatio i a logical ad visually sophisticated maer ad structure a applicatio by defiig how it is orgaized ad how it is preseted to users. You ca desig meu objects or old-style meus. Ope M/SQL Developer Guide Glossary-11

442 Glossary Meu Object Meu Bar M/PACT MSQL.KEY File Multi-Row Form MUMPS.DAT File MUMPS.EXT File A list of oe or more choices, each of which ivokes a actio that performs a specific task. A meu object ca be ru as either a meu bar or a pop-up meu. Meu objects emulate the style of a graphical user iterface (GUI) eviromet by providig pull-dow meu bar ad pop-up meu capabilities. Oe of the two ru-time modes for a meu object, a meu bar displays its optios horizotally across the scree. Meu bars ca be attached to widows (i which case they appear at the top of the widow), they ca be attached to forms (i which case they appear at the top of the scree for all widows i the form), or they ca be ru as stad-aloe objects (i which case they ca be positioed aywhere o the scree). The report writer compoet of Ope M/SQL. M/PACT lets you create ad ru sophisticated ed-user data reportig applicatios that iteract with the Ope M/SQL Relatioal Data Dictioary. The file ito which you must eter the ecoded versio of your Ope M licese i order to activate the licese. A form that simultaeously presets multiple rows of data from its associated base table. The master widow of a multi-row form displays its set of fields i repeatig uits, each uit correspodig to oe database row. Multi-row forms must always have a Data Dictioary data source they ca ever be o-database forms. The primary or oly volume i a M database. It cotais M globals ad routies. A secodary volume i a M database. O Server systems that support multivolume databases, a M database ca cotai from 0 through 7 MUMPS.EXT files, i additio to oe MUMPS.DAT file. A MUMPS.EXT file cotais M globals ad routies, but caot be refereced directly except whe the SYSMGR or MIS utility is used to add it to the database. Glossary-12 Ope M/SQL Developer Guide

443 Glossary Natioal Laguage Idepedece Network A Ope M/SQL iteratioalizatio feature that allows you to provide laguage traslatios for most applicatio text, icludig help ad error messages, display captios, ad system-geerated ru-time messages. Ope M/SQL supports eleve ru-time laguages. A collectio of computers ad coectios that allows users ad programs o oe computer to commuicate with users ad programs o other computers i the etwork. Network Cofiguratio Node 1. A descriptio of the locatio of data withi a etwork, ad of the relatioships amog various compoets i the etwork. The combied etries i the Hardware Descriptio Table, the Directory Set Locatio Table, ad the DSM-DDR Volume Set Traslatio Table form this descriptio. Although multiple cofiguratios may be defied ad stored i M/NET, oly oe at a time ca be active. 2. The actual etwork compoets ad relatioships. Oe computer i a etwork. No-Cursor-Based SQL A type of embedded SQL query that cosists of idividual SELECT, INSERT, UPDATE, ad DELETE statemets. A o-cursor-based SQL query must always retur a sigle row of data. No-cursor-based SELECT statemet queries are appropriate whe you kow that a sigle row of data matches the WHERE clause. No-Database Form A form that is ot associated with a base table i the Data Dictioary. No-database forms may be form-oly forms (o data source at all), or they may be alterative data source forms (iteract with a data structure other tha the Ope M/SQL Data Dictioary). Ope M/SQL Developer Guide Glossary-13

444 Glossary Object Object Code I Ope M/SQL, a object is a structural etity that has idetity ad behavioral properties. Objects costitute both the structure of the databse ad the structure of applicatios. Objects ca iteract with other objects. Ope M/SQL object types iclude: base tables, views, forms, widows, fields, stad-aloe captios, lie objects, meu objects, meus (old-style), reports, queries, help topics, ad help documets. The lowest level of code produced by the Ope M/SQL compiler. This is the code that is actually iterpreted ad executed. You caot write routies at the object code level. Object Compile Driver Utility Ope M/SQL utility that allows applicatio developers to defie ad store lists of Ope M/SQL objects for serial compilatio. A compilatio list may iclude multiple objects or etire applicatios. Whe ru, the utility batch-compiles the code for all objects icluded i the specified compilatio cofiguratio. Object Itegrity Checker Utility Old-style Meu Ope M Ope M/SQL utility that checks the itegrity of specified object defiitios or groups of object defiitios i the curret directory ad geerates a report of all itegrity errors that it fids. The Itegrity Checker utility ca also automatically correct some of the itegrity errors it fids. This utility eables applicatio developers to easily idetify ad repair itegrity errors i their applicatios. The traditioal Ope M/SQL horizotal ad vertical meus. The Meu Geerator supports the creatio ad deploymet of both meu objects ad old-style meus. For ew applicatios, IterSystems recommeds that you create meus usig the more flexible ad sophisticated meu object geeratio eviromet. Name of IterSystems complete lie of products, of which the foudatio techology is M. Ope M refers to the foudatio software o top of which Ope M/SQL rus. Glossary-14 Ope M/SQL Developer Guide

445 Glossary Ope M/SQL Ope M/SQL is the RDBMS (Relatioal Database Maagemet System) compoet of Ope M it icludes a developmet eviromet for creatig advaced relatioal database applicatios, a maagemet system for maitaiig them, ad a ru-time eviromet for executig them. Ope M/SQL features a itegrated developmet eviromet cosistig of a advaced relatioal database maagemet system, applicatio geerator, report geerator, ad procedural programmig laguage. It combies the SQL relatioal query laguage with the M database-orieted procedural programmig laguage. Ope M/SQL Relatioal Database A M database that is orgaized i a relatioal structure by creatio i or mappig to the Ope M/SQL Relatioal Data Dictioary. Oe-Way Outer Joi Paret ID Pop-Up Meu Primary Key A programmer-defied joi specified by usig the symbol =* i place of = i the WHERE clause of a SQL query. This type of joi desigates the first table specified i the joi coditio as the source table ad icludes all rows from the source table i the output table, eve if there is o match i the secod table. The source table pulls relevat iformatio out of the secod table but ever sacrifices its ow rows for lack of a match i the secod table. Field automatically created by the Ope M/SQL Relatioal Data Dictioary to specify the Row ID i a child table whe you defie a characteristic relatioship betwee tables. The Paret ID acts like a desigative referece from the child table to the paret table ad has the same ame as the paret table. Oe of the two ru-time modes for a meu object, a pop-up meu displays its optios i a vertical list. Pop-up meus ca be ru as stad-aloe objects, they ca be pulled dow from meu bars, they ca be called from other pop-up meus (i which case they display i cascadig style), or they ca be called from withi forms. A field or combiatio of fields used to uiquely idetify each row of a base table. I Ope M/SQL, the fuctio of the primary key is performed by the Row ID. Ope M/SQL Developer Guide Glossary-15

446 Glossary Privilege The authority of a user to perform a actio o a object. The ower of a object has the resposibility for gratig ad revokig privileges to users ad groups of users o that object. Process A etity scheduled by the system software, which provides a cotext i which a image executes. A process is associated with certai hardware ad software ad uses a address space. Product Activatio Key Programmer Mode Prompt Pull-Dow Meu Query A paper key that arrives with your software distributio o which is prited a ecoded versio of your Ope M/SQL licese. You must eter this iformatio ito a file called MSQL.KEY i order to activate the licese. The mode i which all program developmet activity takes place. I programmer mode, you iitiate programs from the M prompt, ad the M prompt reappears at the coclusio of every program you ru. Programmer mode ecompasses the M eviromet ad all programs that ca be called from it, icludig the Ope M/SQL developmet eviromet ad ru time eviromet. I programmer mode, you ca create applicatios that users subsequetly ru i applicatio mode. A system-geerated sigal requestig some user respose. Term used to describe the style of presetatio for a pop-up meu that is called from a meu bar. A SQL laguage costruct that allows you to extract ad maipulate the data i a relatioal database. I the Ope M/SQL relatioal eviromet, queries ca be embedded directly withi M code, or they ca be writte iteractively usig the Iteractive Query Editor or the Query Geerator (for SELECT-statemet queries oly). Glossary-16 Ope M/SQL Developer Guide

447 Glossary Query-Based View Query Geerator Referetial Itegrity Relatio A view that is based o the output of a SELECT-statemet query. You may create query-based views usig the CREAE VIEW statemet. Ope M/SQL facility for defiig ad ruig ad hoc queries. The Query Geerator provides a easy-to-use template of SQL SELECT statemet sytax equipped with fields for the appropriate SQL clauses, icludig SELECT, FROM, WHERE, ORDER BY, GROUP BY, ad HAVING. This eables users to create SELECT queries by simply fillig i the template. The Query Geerator automatically geerates all queries as a cursor-based SELECT statemet queries, which meas they ca retrieve multiple data rows ito the output table. Referetial itegrity costraits esure that database isert, update, ad delete operatios that apply to tables liked by implicit jois do ot compromise the accuracy ad completeess of the database. A lik betwee base tables. See Characteristic Relatioship ad Desigative Referece. Relatioal Database A collectio of related data that is orgaized accordig to the relatioal model. Relatioal Eviromet Relatioal Gateway Eviromet i which you defie the database i relatioal terms ad use Ope M/SQL s applicatio geerator tools to create, modify, ad execute advaced relatioal database applicatios. The Ope M/SQL relatioal eviromet combies two ANSI-stadard laguages M ad SQL. A compoet of Ope M/SQL which provides a fuctio call-based iterface that eables M applicatios to coect with exteral database servers. The exteral database servers ca be M-based relatioal databases or o-m-based ( foreig ) relatioal databases, such as Oracle. M applicatios act as cliets to these exteral database servers ad issue SQL requests to retrieve data. Ope M/SQL Developer Guide Glossary-17

448 Glossary Relatioal Model Relatioal Cliet Relatioal Server Report Required Field Row Row ID The model for database maagemet i which all data is orgaized i relatioal tables. The SQL laguage is based o the relatioal model, as is the Ope M/SQL Relatioal Data Dictioary. A set of drivers that resides o a cliet system ad allows you to coect from a exteral applicatio program to a Ope M/SQL relatioal database usig the Ope M/SQL Relatioal Server. A compoet of Ope M/SQL that makes data stored i Ope M/SQL relatioal databases available to applicatios developed i certai Widows-based tools such as Microsoft Excel, Microsoft Access, ad Pilot LightShip, as well as applicatios developed i C or C++. A program defied usig the M/PACT report writer that retrieves ad displays data from the relatioal Data Dictioary. A field i a base table or o a form that must cotai a valid o-ull value before the row ca be filed. A group of related field values that describes a etity i the domai of a relatioal table. For example, i a Customers table, a row describes a sigle customer. Also called a record i traditioal data processig termiology, or a tuple i relatioal database termiology. I a base table defied i the Ope M/SQL Relatioal Data Dictioary, the RowID is a field (or combiatio of fields) whose value uiquely idetifies each row i the base table. A RowID field must always have a uique value. I relatioal termiology, the Row ID is the same as the primary key. Glossary-18 Ope M/SQL Developer Guide

449 Glossary Row Selectio SELECT List Item Server Server Master Server Process The process of selectig a row to be retrieved from the database for a sigle-row form. The programmer defies lookup queries to perform row selectio, ad the user rus a lookup query by providig the requisite lookup iformatio. A elemet i a SELECT statemet that tells the server what data to retrieve. It ca be either a colum ame or a expressio. 1. The system o which the Ope M/SQL Relatioal Server ad your Ope M/SQL relatioal database resides. 2. A M process o the Relatioal Server system that commuicates with the cliet API. A compoet of the server software that listes for coectio attempts from cliets coected via TCP, ad spaws server processes to service those coectios. Each server master is a M process. A JOBbed process o the server that services a sigle cliet coectio. A server master creates a server process for this purpose. Short Help Message Sig-o A oe-lie programmer-defied help text message associated with a field or meu object choice that displays at the bottom of the scree just below the status lie whe the user presses the <EXPLAIN> key from a field or meu object choice. For fields, you may defie triggers to automatically display the short help message based o certai ru-time circumstaces, or you may eable automatic display of the short help message for all fields o a form. The act of eterig Ope M/SQL, i order to use M, Developer, or a Ope M/SQL applicatio. See also logi. Ope M/SQL Developer Guide Glossary-19

450 Glossary Sigle-Row Form A form that presets data from its associated base table oe row at a time. The users selects a row from the row selectio widow. SQL (Structured Query Laguage) Stads for Structured Query Laguage; SQL is the ANSI-Stadard 4GL programmig laguage desiged specifically for accessig ad maitaiig relatioal databases. Stad-Aloe Captio Subquery Descriptive text that appears o a widow but is ot attached directly to a field. Ofte used i the capacity of a widow header. A subquery is a SQL SELECT statemet query that is embedded withi aother SQL SELECT statemet query. Ope M/SQL permits the embeddig of subqueries withi the SELECT, FROM, ad WHERE clauses of the outer query. Ope M/SQL also permits the estig of subqueries to ay umber of levels. System Maager s Directory Trasactio Trigger The directory where the Ope M/SQL database resides. This directory cotais system globals, system routies, ad %-utilities. You must create this directory at the DOS level. Your Ope M system automatically places the Ope M/SQL database i this directory durig istallatio. A set of operatios that forms a uit. A sequece of actios defied by the developer to execute at various poits durig a Ope M/SQL applicatio. I Ope M/SQL, you ca associate triggers with base tables ad with forms. Base table triggers are database actios iitiated by INSERT, UPDATE, or DELETE actios performed o a base table. These triggers help maitai itegrity costraits ad other data depedecies. Form triggers ca execute at the form, widow, ad field levels of a applicatio ad provide umerous applicatio avigatio ad processig fuctios, such as trasferrig cotrol to differet parts of a applicatio. Glossary-20 Ope M/SQL Developer Guide

451 Glossary Validatio Code Variable M code used by Ope M/SQL to validate field values by specifyig validity costraits o field data values. A symbolic ame that is used to referece a data value. Variables ca be local or global. Local variables reside i the local symbol table associated with a give partitio. All Ope M/SQL local variables begi with the percet sig (%). Global variables reside o disk. Some global variables i Ope M/SQL also begi with the percet sig (%). Variable Widow Placemet Vertical Meu View Virtual Field Virtual Table The ability to display a widow at differet positios o the scree depedig o the cotext i which it is called. Variable widow placemet allows you to defie alterative placemets for a widow by specifyig multiple sets of X ad Y axis coordiates, each associated with a M coditio that govers its executio. A type of old-style meu that rus i stad-aloe fashio ad displays its optios vertically i a list. Vertical meus typically serve as cotrol flow maps for a applicatio. The Ope M/SQL Mai Meu is a example of a vertical meu. A virtual table created usig the fields from a base table or set of base tables liked by implicit jois. Views are coceptual widows through which data from oe or more base tables ca be viewed. A field that does ot correspod directly to a sigle stored value but istead is composed of several stored values. For example, the Row ID field for a child table is sometimes composed of two stored values the Row ID of the paret ad a subscript correspodig to a particular child row. A amed table derived from oe or more base tables that is ot directly represeted i physical storage. Views ad query output are examples of virtual tables. Ope M/SQL Developer Guide Glossary-21

452 Glossary Widow A set of fields, text captios, ad lie objects displayed together o the scree as part of a form. Every form must have at least oe widow, its master widow. Word-Processig Field A multi-lie field of data type Text that has word-processig capabilities, icludig automatic lie wrappig, ehaced field avigatio, ad the ability for users to search for a strig. Glossary-22 Ope M/SQL Developer Guide

453 Idex A {%actio} 11-4, Additioal validatio code %AFTERHAVING 9-3, 9-14 {%agg} 11-6 Aggregate fuctios (i SQL) 9-11 %AFTERHAVING 9-14 as query colums 9-11 DISTINCT 9-14 DISTINCT BY 9-15 %FOREACH 9-12 %ALPHAUP 9-3, 9-41 ALPHAUP 9-38 %ALTER privilege 9-3, 9-49 ALTER VIEW statemet 9-57, Applicatio Help facility G-1 Applicatio mode G-1 Applicatio Programmig Iterface (API) G-1 Applicatios G-1 automatic geeratio of 1-4 cotets of defiig the data structure 1-4 desigig 3-4 developig forms ad reports 1-5 had-codig i M 1-6 isertig M code ad SQL code 1-15, mappig the fuctioal specificatios 1-4 mixig automatic geeratio ad hadcodig 1-7 portable acrros M systems 1-14 programmer iterface to 11-1 programmig methods 3-2 strategies for developig 1-4 system-geerated routies tyig together the various compoets 1-6 Arrays usig the INTO clause to pass iformatio ito M arrays 9-19 Arrow sytax 2-19, 9-7 ASCII-Delimited format (for queries) cotets of file queries created via the Query Editor queries created via the Query Geerator selectig a output device Authorizatio ID establishig from M code stored i %msql local variable Auxiliary widows G-1 B {%backgroud} 11-7 Backups (for routies) 6-5, 6-12 deletig 6-14, 7-29 Ope M/SQL Developer Guide Idex-1

454 Idex geerated by the Full Scree Editor 6-13 restorig backup versios 6-13 settig # of backup versios to be maitaied 7-28 shufflig ad reumberig of backups 6-12 Base table triggers actio types Base tables 2-3, G-2 characteristic relatioships 2-17, 9-9 checks made by Object Itegrity Checker utility compiled routies of desigative refereces 2-16, 9-7 filig etry poits to compiled routies First Normal Form 2-2 storage globals triggers %BEGTRANS 9-3, 9-45 Brachig fields G-2 Buffers (i the Full Scree Editor) 4-16 creatig 4-16 displayig i widows 4-18 loadig routies ito 4-17 selectig 4-16 settig marks i 4-19 C Caller ID G-2 {%caller} 11-3, Cartesia product operatio 2-7 CASCADE optio (for revokig privileges) 9-50 Cascadig meus G-2 {%cellar_tuple} 11-6 Characteristic relatioships 2-17, 9-9, G-2 child-to-paret relatioship 2-20, 9-9 paret-to-child relatioship 2-20, 9-10 specifyig implict joi sytax i queries 2-20, 9-9, 9-10 Charactersistic relatioships specifyig implict joi sytax i queries 2-20 %CHECKPRIV 9-3, 9-50, Child forms G-2 Child tables 2-17, 9-9, G-3 CLOSE statemet 8-4 Code geeratio G-3 Collatio sequece 9-37 ALPHAUP fuctio 9-38 chagig the default collatio sequece 9-42 EXACT fuctio 9-37 field-level collatio 9-39 i comparisos 9-40 Mius fuctio 9-39 Plus fuctio 9-39 Space fuctio 9-39 UPPER fuctio 9-38 usig ORDER BY clause 9-40 Colums 2-2, G-3 Commet lies i macro source code 5-15 COMMIT 9-45 Commo directory Commuicatios protocol G-3 Compilatio G-3 compilig Ope M/SQL objects serially 12-5 of objects of routies 6-11 Compilatio Optios widow 12-8 optios defied 12-9 Compiler 1-11, 5-2, 6-11 geeratig routies for applicatios Computed fields G-3 isertig code Cocateatio operator (SQL) 9-32 Coditioal maps Idex-2 Ope M/SQL Developer Guide

455 Idex Cofiguratio Network G-13 Coversio code 9-26, G-3 exteral-to-iteral iteral-to-exteral referecig variables Copy Query utility Copyig queries CREATE VIEW statemet 9-57, Curly brace sytax 11-2, Cursor-based SQL 8-4, G-4 declarig a cursor 8-4 opeig a cursor 8-4 passig iformatio ito M variables 8-5 retrievig iformatio ito a cursor 8-5 usig the INTO clause 9-18 Cursors 8-4, G-4 declarig 8-4 opeig 8-4 passig iformatio ito variables 8-5 retrievig iformatio 8-5 D ^%dafmlog Data Dictioary 1-3, 1-10, 2-5, 3-4, G-4 accessig data from 2-6 defiig data structures 1-4 Data source G-4 %data(icol) 11-3 Database 1-10, 2-1, G-4 for o-ism systems 2-4 M G-10 Ope M/SQL G-15 relatioal 2-2 relatioal model G-17 Database forms G-4 {%date} 11-6 DECLARE statemet 8-4 #defie 5-7 DELETE privilege 9-49 DELETE queries i o-cursor-based SQL 8-3 Desigated table 2-16, 9-7, G-5 Desigative display fields G-5 Desigative refereces 2-16, 9-7, G-5 specifyig implict joi sytax i queries 2-19 Detailed Query Listig utility sample report Developer 1-3, G-5 Developer Utilities meu 12-1 accessig 12-2 Export/Import Optios 12-3 ivokig routie maagemet utilities 7-3 ivokig routie magemet utilities ivokig the Full Scree Editor 4-4, 12-4 Natioal Laguage Reports Object Compile Driver utility 12-5 Object Itegrity Checker utility Object Routie Prefix utility Object Strig Search utility optios defied 12-3 Device G-5 Device selectio (for queries) ASCII-delimited output format selectig a device selectig a prit format Device Selectio widow fields defied selectig a device selectig a prit format Directory G-5 DISTINCT 9-14 DISTINCT BY 9-15 Distributed Cache Protocol (DCP) 1-13 Distributed data processig 1-19 DROP VIEW statemet 9-58, DSM 1-14 DT Network 1-13 list of database protocols 1-13 Ope M/SQL Developer Guide Idex-3

456 Idex DTM 1-14, G-5 Duplicate rows (i SQL queries) 9-16 E %edit(icol) 11-3 #else, 5-11 #elseif, 5-11 Embedded SQL 1-15, 9-17, G-5 cursor-based 1-15, 8-4, G-4 example 8-10 hadlig iteral ad exteral values 8-8 hadlig multi-lie fields 8-8 macro refereces 8-7 o-cursor-based 1-15, 8-2, G-13 portability 8-9 reserved tag ad variable vames 8-9 #edif 5-11 Equijois 2-11 Error messages (for SQL queries) A-3 %EXACT 9-3, 9-41 EXACT 9-37 Export/Import utility G-6 accessig via Developer Utilities meu 12-3 Extesios (for routies) 6-3 %EXTERNAL 9-3, 9-29 Exteral values G-6 i SQL queries 9-26 Exteral-to-iteral coversio code 9-26, F FETCH statemet 8-4 retrievig iformatio ito a cursor 8-5 Field captios G-6 Fields G-6 computed database G-4 readig referecig i M code referecig withi triggers required {%filetype} 11-4, %first 4-6 First Normal Form 2-2 FOR ALL operator 9-56 FOR SOME operator 9-56 %FOREACH 9-3, 9-12 Foreig key 2-16, 9-7, G-6 %FORM 9-3 Form call sytax (from M) callig forms by ame/id# callig forms by routie prefix parameters defied Form Geerator 1-3, 1-12, 3-4, G-6 creatig forms 1-5 Form triggers actio types Form-oly fields G-6 Form-oly forms G-7 Forms 1-5, 1-12, G-6 checks made by Object Itegrity Checker utility child forms G-2 compiled routies of emulatig form behavior i M programs erasig widows from scree form-oly forms G-7 ivokig from M code o-database forms G-13 sigle-row G-20 storage globals triggers FROM clause 10-8 Full Scree Editor 1-18, 3-2, 4-1, 12-4, G-7 automatic date ad time stamps 4-24 automatic sytax checkig 4-23 Buffers Meu optios described 4-11 cotrol key editig commads 4-20 creatig a ew buffer 4-16 creatig routies 4-7 cursor positioig keys 4-13 Idex-4 Ope M/SQL Developer Guide

457 Idex G cuttig ad pastig 4-15 deletig text 4-14 displayig multiple buffers 4-18 edit field 4-8 editig multiple copies of a routie 4-16 editig operatios 4-13 exitig 4-23 geeratig backup versios for routies 6-13 gettig help 4-22 Help Meu optios described 4-22 horizotal optios meu 4-9 isertig text 4-14 ivokig from Developer Utilities meu 4-4 ivokig from M programmer prompt 4-3 keyboard actios D-1 loadig a routie ito the curret buffer 4-17 loadig existig routies 4-6 loadig routies automatically 4-6 lockout mechaism 4-7 Mark Meu optios described 4-12 avigatig the meu system 4-10 Other Meu optios described 4-12 overview 4-2 prevetig overwrites 4-7 Primary Meu optios described 4-10 replacig strigs 4-20 routie types 4-2 Save Meu optios described 4-23 savig routies 4-23 scree display 4-8 searchig for text strigs 4-20 selectig a existig buffer 4-16 settig a mark i the curret buffer 4-19 Status Lie 4-9 Widows Meu optios described 4-11 Global database 1-9, G-7 accessig 1-16 Globals 11-9, G-7 base table defiitio form defiitio implicit 1-19 meu object defiitio object defiitio globals 11-9 old-style meu defiitio percet globals query defiitio referecig withi iserted code report defiitio Grat optio (for privileges) gratig 9-48 Revokig 9-50 GRANT statemet 9-47, WITH GRANT OPTION 9-48 GROUP BY clause 10-8 H HAVING clause 10-9 Help Documet Creatio facility G-7 Help documets G-7 Help text displayig i help text box writig messages Help Text Etry facility G-7 Help topics G-8 help^%msql fuctio parameters defied Horizotal meus 1-12, G-8 I #if, 5-11 #ifdef, 5-11 #ifudef, 5-11 Implicit globals 1-19 Implicit jois 2-15, 9-6, G-8 arrow sytax 2-19, 9-7 as characteristic relatioships 2-17, 9-9 as desigative refereces 2-16, 9-7 itegrity costraits 2-21 sytax for specifyig child-to-paret refereces 2-20, 9-9 sytax for specifyig desigative refereces 2-19 Ope M/SQL Developer Guide Idex-5

458 Idex sytax for specifyig paret-to-child refereces 2-20, 9-10 #iclude 5-13 Iclude files 1-11, 5-3, G-8 advatages of usig 5-14 creatig 5-2 editig 4-2 extesios 6-3 maitaiig backup versios 6-5 amig 5-3 Idex map G-8 Ier jois 2-11 {%iquiry_mode} 11-5, INSERT privilege 9-49 INSERT queries hadlig mutli-lie fields 9-25 i o-cursor-based SQL 8-3 passig iformatio ito M arrays 9-21 with VALUES clause 8-3, 9-23 Iserted code 1-15, referecig fields referecig globals referecig variables summary of isert locatios sytax checkig types of code withi additioal validatio code withi computed fields withi coditioal maps withi iteral/exteral coversio code withi map subscripts ad pieces withi NEXT subroutie withi override lookup queries withi required-maybe fields withi triggers Itegrity checkig see Object Itegrity Checker utility Itegrity costraits G-8 Iteractive Query Editor see Query Editor Itermediate code routies 1-17, 3-2 covertig to macro source code 6-2 creatig 3-3 editig (usig Full Scree Editor) 4-2 editig (usig the Routie Lie Editor) 3-3 extesios 6-3 maitaiig backup versios 6-5 Itermediate source code 1-11, G-9 %INTERNAL 9-3, 9-29 Iteral values G-9 i SQL queries 9-26 Iteral-to-exteral coversio code 9-26, INTO clause 9-18 passig iformatio ito M arrays 9-19 passig iformatio ito mixed variables 9-20 usig i cursor declaratio 9-18 with cursor-based SQL 8-5 with INSERT queries 9-21 with o-cursor-based SQL 8-3 with SELECT queries 9-19 with UPDATE queries 9-22 %INTRANS 9-3, 9-45 %is 11-2 ISM 1-14 J Joi operatio 2-11 Jois 9-5, G-9 equijoi 2-11 implicit jois 2-15, 9-6, G-8 ier jois 2-11 oe-way outer jois 2-14, 9-5, G-15 K Keyboards key mappig for Full Scree Editor fuctio keys D-1 Keys Full Scree Editor fuctio keys mapped to your termial type D-1 Keywords (i SQL) 9-3 reserved words B-1 Idex-6 Ope M/SQL Developer Guide

459 Idex L Laguage report o laguage traslatios Lear-As-You-Go (LAYGO) G-9 Licese G-9 LIKE predicate 9-34 error hadlig 9-36 ESCAPE qualifier 9-35 patter matchig characters 9-34 usig host variables for search patter 9-35 {%lieum} 11-5 List Queries utility sample report Logi G-9 Log help messages G-10 Lookup display fields G-10 Lookup fields G-10 Lookup queries G-10 isertig code withi override lookup queries Lookup specificatios G-10 M M G-10 database G-10 vedor-idepedece 1-14 M code 1-10 callig forms callig meu objects callig old-style meus callig queries 10-31, callig reports cleaig up widows compilig a object compilatio cofiguratio displayig help text i a help text box embedded SQL 8-1 establishig Authorizatio ID isertig ito applicatios isertig ito triggers protectig critical Ope M/SQL variables readig fields writig message text M database for o-ism systems 2-4 M directory as schema 2-4 M operators summary of 9-30 M programmig laguage 1-2, 1-15 global refereces to the database 1-16 laguage processor i Ope M/SQL 1-9 procedural programmig 1-6 M/NET 1-13 list of database protocols 1-13 M/PACT 1-3, 1-12, G-12 geeratig reports 1-5 M/SQL Itegrity Check Utility meu Macro preprocessor 5-2, 5-4, G-11 commads 5-4, 5-7 fuctios 5-5, 5-16 macro refereces 5-5 Macro routie utilities see routie maagemet utilities Macro source code 1-11, 5-2, G-11 advatages of usig iclude files 5-14 #defie statemets 5-7 #else statemets 5-11 #elseif statemets 5-11 embeddig SQL 5-16, 8-1 #edif statemets 5-11 #if statemets 5-11 #ifdef statemets 5-11 #ifudef statemets 5-11 #iclude statemets 5-13 idicatig commet lies 5-15 macro refereces 5-5 makig code iter-vedor portable 5-17 estig macros 5-9 #oshow statemets 5-14 preprocessor commads 5-4 preprocessor fuctios 5-5 referecig iclude files 5-3 Ope M/SQL Developer Guide Idex-7

460 Idex #show statemets 5-14 ##sql preprocessor fuctio 5-16, 8-2 &sql preprocessor fuctio 5-16, 8-2 summary of preprocessor commads 5-7 summary of preprocessor fuctios 5-16 #udef statemets 5-9 ##vedor preprocessor fuctio 5-17 Macro source routies 1-17, 3-2, 5-1, 6-2 compilig 5-2 creatig 5-2 editig 4-2 extesios 6-3 i vedor-idepedet eviromet 1-14 macro preprocessor 5-4 maitaiig backup versios 6-5 amig 5-3 portability across directories 8-9 portability across M systems 5-3 Macros 5-5 ested expasio 5-9 referecig i embedded SQL 8-7 Maps G-11 isertig code for coditioal isertig code for NEXT subroutie isertig code for subscripts ad pieces Master map G-11 Master widow G-11 ^mcompd 11-9 ^mcov 11-9 ^mdd 11-9, ^mddc 11-9, %MENU 9-3 Meu bars 1-12, G-12 Meu call sytax (for old-style meus) parameters defied Meu Geerator 1-6, 1-12, G-11 Meu object call sytax callig meu objects by routie prefix callig meu objects with meu call etry poit Meu objects 1-12, G-12 checks made by Object Itegrity Checker utility compiled routies of horizotal meus 1-12 ivokig from M code meu bars 1-12 pop-up meus 1-12 storage globals vertical meus 1-12 {%meubar} 11-6 {%meuid} 11-6 Meus G-11 cascadig G-2 Meus (old-style) 1-12, G-14 ivokig from M code storage globals {%meutype} 11-6 %MEUNOBJ 9-3 ^mexpew 11-9 ^mexport 11-9 ^mform 11-9, ^mformc 11-9, ^mhelp 11-9 Mius collatio sequece fuctio 9-39 ^mlock 11-9 ^mmeu 11-9, ^mmisc 11-9 ^%mmsg %mobject ^%mobject %mode 11-2 ^mpriv ^mql 11-10, ^mreport 11-10, 11-46, ^mreportc 11-10, ^mroutie 11-9 %msg 11-3 Idex-8 Ope M/SQL Developer Guide

461 Idex MSM 1-14 %msql 11-2 etry poit for callig forms etry poit for callig old-style meus etry poit for callig queries etry poit for callig reports etry poit for cleaig up widows etry poit for displayig help text i a help text box etry poit for establishig Authorizatio ID etry poit for readig fields etry poit for writig message text list of etry poits 11-8 ^%msql MSQL.KEY file G-12 %msqlutl utility displayig list of critical Ope M/SQL variables pushig Ope M/SQL variables oto a stack reistatig variables from stack $$msqlvars^%msqlutl fuctio ^mtemp 7-30, ^mterm Multi-lie fields 2-21 i INSERT queries 9-25 i SELECT queries 9-24 i UPDATE queries 9-25 retrievig values i SQL 8-8, 9-24 Multi-row forms G-12 MUMPS.DAT file G-12 MUMPS.EXT file G-12 ^%muser ^mutil ^mxdd ^mxdoc ^mxform ^mxhtop ^mxmeob ^mxmeu ^mxql ^mxreport N Natioal laguage idepedece G-13 report o laguage traslatios Natioal Laguage Reports utility sample report Network G-13 Cofiguratio G-13 DT Network 1-13 M/NET 1-13 %ew 11-3 %ewext 11-3 {%ewpage} 11-6 NEXT subroutie %NOCHECK 9-3, 9-44 Node G-13 No-cursor-based SQL 8-2, G-13 passig iformatio ito M variables 8-3 usig the INTO clause 9-18 No-database forms G-13 #oshow 5-14 NOT IN operator 9-32 O Object code 1-11, G-14 Object code routies 1-18, 5-2 extesios 6-3 maitaiig backup versios 6-5 Object Compilatio Driver Results widow viewig error messages Object Compile Driver Items widow advaced optios for forms 12-15, advaced optios for routies fields defied Ope M/SQL Developer Guide Idex-9

462 Idex Object Compile Driver utility 12-5, G-14 advaced optios compilatio error messages compilig a cofiguratio compilig a cofiguratio from withi a M program defiig the cotets of a compilatio cofiguratio editig object defiitios settig defaults for compilatio optios 12-8 usig 12-5 viewig the results of a compilatio Object Compile Driver widow 12-7 fields defied 12-7 Object defiitio globals 11-9 list of 11-9 located i commo directory Object defiitios checkig itegrity of lookig up routie prefix for searchig for strigs i Object Itegrity Checker utility 12-23, G-14 automatic error fixig checks made o base tables checks made o forms checks made o meu objects checks made o reports checks made o triggers checks made o views eablig error fixig mode ruig sample report Object Routie Prefix utility sample display usig Object Strig Search utility sample report usig Objects G-14 stored i globals 11-9 %ok 11-2 %old 11-3 %oldext 11-3 ^%omc ^%oms Oe-way outer jois 2-14, 9-5, G-15 Ope M G-14 Relatioal eviromet G-17 Ope M/SQL 1-2, G-15 accessig the relatioal database 2-6 applicatio developmet strategies 1-4 applicatios portable across M systems 1-14 commo directory compiler 1-11 defiig a database 1-10 developmet eviromet 1-10, 3-4 distributed data processig 1-19 extesios to relatioal model 2-14 global database 1-9, 1-16 globals 11-9 had-coded programmig 1-11 hardware ad operatig system eviromets 1-8 implemetatio of SQL 9-1 i a vedor-idepedet host M eviromet 1-14 itegratio of M ad SQL 1-15 keyboard mappig for supported termial types D-1 list of reserved words B-1 list of supported termial types C-1 M laguage processor 1-9 memory eviromet 1-9 etworkig 1-13 ope systems architecture 1-2 percet variables 11-2 program structure 1-17 programmig methods 3-2 query optimizer 1-12 Relatioal Data Dictioary 2-5 relatioal database 2-1, G-15 schemas 2-4 SQL laguage processor 1-9 supported M systems 1-14 system-geerated routies Ope M/SQL Developer 1-3 Idex-10 Ope M/SQL Developer Guide

463 Idex Ope M/SQL for DSM 1-14 termial types supported for C-3 Ope M/SQL for DTM 1-14 termial types supported for C-3 Ope M/SQL for MSM 1-14 termial types supported for C-3 Ope M/SQL Mai Meu 12-2 OPEN statemet 8-4 Ope systems 1-2 ORDER BY clause 10-8 Override lookup queries isertig code P {%pageum} 11-6 Paret ID G-15 Paret tables 2-17, 9-9 {%paret_referece} 11-3, Percet globals list of Percet variables 11-2 eclosed i curly braces 11-2 list of 11-2 referecig withi triggers retur prefix Plus collatio sequece fuctio 9-39 Pop-up meus 1-12, G-15 cascadig G-2 pulled dow from meu bar G-16 popvars^%msqlutl fuctio Preprocessor commads 5-4 #; 5-15 #defie 5-7 #else 5-11 #elseif 5-11 #edif 5-11 #if 5-11 #ifdef 5-11 #ifudef 5-11 #iclude 5-13 #oshow 5-14 #show 5-14 summary of 5-7 #udef 5-9 #udefie 5-7 Preprocessor fuctios 5-5 ##sql 5-16, 8-2 &sql 5-16, 8-2 summary of 5-16 ##vedor 5-17 {%presave} 11-4, Primary key 2-3, G-15 Privilege operators 9-47 Privileges G-16 for ruig queries gratig 9-47 revokig 9-49 summary of 9-49 suppressig checks 9-50 Processes G-16 Product Activatio Key G-16 Programmer mode G-16 Project operatio 2-9 Prompt G-16 _PUBLIC (UserName) 9-48 Pull-dow meus G-16 pushvars^%msqlutl fuctio Q ^%qarmisc Queries 2-6, 10-1, G-16 ALTER VIEW 9-57, ASCII-delimited output format 10-14, 10-26, %CHECKPRIV 9-50, compiled routies of copyig CREATE VIEW 9-57, creatig via the Iteractive Query Editor creatig via the Query Geerator 10-5 DELETE DROP VIEW 9-58, Ope M/SQL Developer Guide Idex-11

464 Idex embedded i M macro source code 8-1, 9-17 formattig output for import by other products geeratio facilities 10-2 GRANT 9-47, INSERT ivokig from M code listig (detailed) listig (short) privileges eeded to ru query ower 10-14, REVOKE 9-49, routie prefix of 10-14, ruig ruig from M code ru-time measure 10-14, SELECT selectig a output device storage globals UPDATE %QUERY 9-3 Query call sytax (from M) 10-31, parameters defied 10-31, Query Defiitio Advaced Features widow fields described Query Defiitio widow 10-7 advaced features optio fields described 10-7 meu bar optios described Query Editor 10-17, G-9 accessig 10-2 compilig queries copyig queries creatig queries editig commads horizotal optios meu ruig queries 10-28, scree display supported query types usig o-lie help Query Editor Advaced Optios widow fields described Query Editor horizotal optios meu optios described Query Geerator 10-5, G-17 accessig 10-2 compilig queries copyig queries creatig SELECT-statemet queries 10-5 displayig list of fields from tables amed i FROM clause ruig queries 10-16, Query optimizer 1-12 Query-based views G-17 alterig 9-57 creatig 9-57 deletig 9-58 amig i FROM clause 9-58 restrictios o defiig 9-58 Queryig the database 2-6 R ^%rakey ^%rakeys ^%RDE ^%rde $$read^%msql fuctio parameters defied REFERENCES privilege 9-49 Referetial itegrity G-17 ^%rekey Relatio G-17 Relatioal Cliet G-18 Relatioal Data Dictioary 2-5, 3-4 accessig data from 2-6 Relatioal database G-17 accessig data from 2-6 characteristics 2-2 fields 2-2 First Normal Form 2-2 for o-ism systems 2-4 overview 2-1 queryig via SQL 2-6 Idex-12 Ope M/SQL Developer Guide

465 Idex structure of 2-2 tables 2-3 Relatioal eviromet G-17 Relatioal Gateway G-17 Relatioal model 2-1, G-18 First Normal Form 2-2 implicit jois 2-15, 9-6 IterSystems extesios to 2-14 oe-way outer jois 2-14, 9-5 schemas 2-4 support for multi-lie fields 2-21 Relatioal operatios 2-7 cartesia product 2-7 jois 2-11, 9-5 project 2-9 restrict 2-10 Relatioal Server 1-3, G-18 Remote directory sytax (for routies) 6-8 restrictios 6-9 %REPORT 9-3 Report call sytax (from M) parameters defied Report triggers actio types {%report-ed} 11-7 Reports 1-5, 1-12, G-18 checks made by Object Itegrity Checker utility compiled routies of Detailed Query Listig report ivokig from M code List Queries report storage globals triggers Required fields G-18 coditioally required fields Reserved words B-1 Restrict operatio 2-10 {%retrieved} 11-6, Retur prefix percet variables {%retur_actio} 11-5, {%retur_filetype} 11-5, {%retur_presave} 11-5, {%retur_savedata} 11-5, {%retur_timeout} 11-5, REVOKE statemet 9-49, CASCADE optio 9-50 GRANT OPTION FOR keyword 9-50 ROLLBACK 9-45 ^ROUTINE 11-9 Routie Lie Editor 3-3, 4-2 Routie maagemet utilities 3-3, 7-1 for o-ism systems 1-18 ivokig from Developer Utilities meu 7-3 ivokig from M programmer prompt 7-3 ivokig from the Developer Utilities meu summary of 7-2 Routie prefix callig forms by routie prefix callig meu objects by routie prefix default ames for all objects usig the Object Routie Prefix utility to fid origi of Routie prefix (for queries) created via the Query Editor created via the Query Geerator Routie sets 6-10 creatig 6-10 usig 6-10 Routies 1-17 automatic sytax checkig 4-23 compilig 6-11, 7-17 covertig itermediate code to macro source code 6-2 copyig 7-19 creatig 6-2 creatig i the FSE 4-7 deletig 6-14, 7-27 deletig backup versios 6-14, 7-29 extesios 6-3 Ope M/SQL Developer Guide Idex-13

466 Idex geerated for base tables geerated for forms geerated for meu objects geerated for queries geerated for reports itermediate code routies 1-17 keepig routie levels sychroized 6-15 listig routies i curret directory 7-11 load from file 7-9 loadig automatically ito FSE 4-6 loadig ito the FSE 4-6 macro source routies 1-17, 5-1, 5-2, 6-2 maitaiig backup versios 6-5 maagemet utilities 1-18, 7-1 ames of system-geerated routies amig 6-3 object code routies 1-18 output to file 7-7 producig backup versios 6-12 referecig routies i other directories/ computers 6-8 restorig backup versios 6-13 routie sets 6-10 search for all i a set of text strigs 7-25 search for ad replace text strigs 7-15 search for oe i a set of text strigs 7-23 set # of backup versios 7-28 shufflig ad reumberig backup versios 6-12 usig wildcard symbols to specify 6-6 utility for selectig routies 7-30 writig 6-2 Row selectio G-19 %ROWCOUNT 9-3 RowID 2-3, G-18 Rows 2-2, G-18 Ru Existig Queries utility S {%savedata} 11-4, Schema 2-4 SELECT clause 10-7 SELECT list item G-19 SELECT privilege 9-49 SELECT queries ASCII-delimited output format creatig via Query Geerator 10-5 hadlig multi-lie fields 9-24 i o-cursor-based embedded SQL 8-2 passig iformatio ito M arrays 9-19 selectig a output device template for defiig 10-7 Server G-19 Server masters G-19 Server processes G-19 setaid^%msql fuctio Short help messages G-19 #show 5-14 Sig-o G-19 Sigle-row forms G-20 Space collatio sequece fuctio 9-39 SQL 1-2, 1-15, 2-6, G-20 accepts multi-lie fields 2-21 accessig the relatioal database 1-16 aggregate fuctio extesios 9-11 collatig output values 9-37 creatig queries via the Iteractive Query Editor creatig queries via the Query Geerator 10-5 cursor-based 1-15, 8-4, G-4 embedded i M macro source code 1-15, 8-1, 9-17 extesios to SQL operators 9-32 extesios, summary of 9-2 hadlig duplicate rows 9-16 hadlig iteral ad exteral values for fields 9-26, 9-29 hadlig multi-lie fields 9-24 hadlig of subqueries 9-52 isertig SQL code ito triggers IterSystems extesios to 2-14 jois 9-5 keyword extesios 9-3 laguage processor i Ope M/SQL 1-9 list of error messages A-1 list of reserved words B-1 Idex-14 Ope M/SQL Developer Guide

467 Idex o-cursor-based 1-15, 8-2, G-13 privilege operators 9-47 programmig methods 3-2 query geeratio facilities 10-2 queryig the relatioal database 2-6 relatioal operatios 2-7 summary of supported M operators 9-30 symbol extesios 9-4 trasactio processig 9-45 usig the INTO clause 9-18 ##sql 5-16, 8-2 &sql 5-5, 5-16, 8-2 SQL code isertig ito applicatios SQL Meu 10-3 optios described 10-4 SQL operators Cocateatio operator 9-32 LIKE predicate 9-34 NOT IN operator 9-32 %STARTSWITH 9-33 SQLCODE variable 9-51, A-1 Stad-aloe captios G-20 %STARTSWITH 9-3, 9-33 Subqueries 9-52, G-20 extesios to 9-55 FOR ALL operator 9-56 FOR SOME operator 9-56 sytax 9-52 usig i FROM clauses 9-54 usig i SELECT clauses 9-55 usig i WHERE clauses 9-52 Symbols (i SQL) 9-4 ^%sys System maager s directory G-20 T Tables 2-2 see also base tables, child table, paret tables, virtual tables, views ^%task Termial types i Ope M/SQL for DSM eviromet C-3 i Ope M/SQL for DTM eviromet C-3 i Ope M/SQL for MSM eviromet C-3 list of supported termial types C-1 %THRESHOLD 9-3 {%time} 11-6 {%timeout} 11-4, Trasactio G-20 Trasactio processig 9-45 %BEGTRANS 9-45 %INTRANS 9-45 Traslatios (for system-geerated messages ad meus) reports o Triggers 1-5, G-20 actio types base table checks made by Object Itegrity Checker utility form isertig M code 11-16, isertig SQL code 11-16, referecig fields referecig Ope M/SQL percet variables report U #udef 5-7, 5-9 UPDATE privilege 9-49 UPDATE queries hadlig multi-lie fields 9-25 i o-cursor-based SQL 8-3 passig iformatio ito M arrays 9-22 with VALUES clause 9-23 %UPPER 9-3, 9-41 UPPER 9-38 Ope M/SQL Developer Guide Idex-15

468 Idex %urchage 7-15 compilig routies 6-11 producig backup versios 6-12 %urcomp 6-11, 7-17 producig backup versios 6-12 %urcopy 7-19 compilig routies 6-11 producig backup versios 6-12 restorig backup versios 6-13 %urdel 6-14, 7-27 %urdir 7-11 log form display 7-14 short form display 7-12, 7-13 %urfad 7-25 %urfid 7-23 %urload 7-9 compilig routies 7-10 load optios 7-9 %urprit 7-7 output to file 7-8 output to priter 7-8 output to scree 7-7 %urpurge 6-14, 7-29 %urset 7-30 parameters described 7-31 %urverma 6-12, 7-28 UserName establishig from M code stored i %msql local variable Utilities Copy Query Detailed Query Listig List Queries %msqlutl Natioal Laguage Reports Object Compile Driver 12-5, G-14 Object Itegrity Checker 12-23, G-14 Object Routie Prefix Object Strig Search program ad object maagemet 3-4 routie maagemet 3-3, 7-2 Ru Existig Queries ^UTILITY 11-9 V %val 11-2 Validatio code 11-24, G-21 VALUES clause 8-3, 9-23 Variable widow placemet G-21 Variables G-21 displayig list of critical variables list of percet variables 11-2 amig covetios 11-2 percet (%) variables 11-2 pushig oto a stack referecig withi iserted code referecig withi triggers reistatig from stack ##vedor 5-17 Versios (for routies) 6-5 Vertical meus 1-12, G-21 Views 1-10, G-21 checks made by Object Itegrity Checker utility query-based 9-57, G-17 Virtual fields G-21 Virtual tables 1-10, 2-3, G-21 W WHERE clause 10-8 Wildcard symbols for routie extesios 6-7 for routie ames 6-6 for versio umbers 6-7 widcl^%msql fuctio Widow cleaup fuctio Widows G-22 erasig from scree Widows (i the Full Scree Editor) 4-18 Word-processig fields G-22 write^%msql fuctio parameters defied Idex-16 Ope M/SQL Developer Guide