PROGRESS

OPENEDGE 10

OpenEdge Development: ABL Reference

2009 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.

These materials and all Progress software products are copyrighted and all rights are reserved by Progress Software Corporation. The information in these materials is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein. The references in these materials to specific platforms supported are subject to change. Actional, Apama, Apama (and Design), Artix, Business Empowerment, DataDirect (and design), DataDirect Connect, DataDirect Connect64, DataDirect Technologies, DataDirect XML Converters, DataDirect XQuery, DataXtend, Dynamic Routing Architecture, EdgeXtend, Empowerment Center, Fathom, IntelliStream, IONA, IONA (and design), Making Software Work Together, Mindreef, ObjectStore, OpenEdge, Orbix, PeerDirect, POSSENET, Powered by Progress, PowerTier, Progress, Progress DataXtend, Progress Dynamics, Progress Business Empowerment, Progress Empowerment Center, Progress Empowerment Program, Progress OpenEdge, Progress Profiles, Progress Results, Progress Software Developers Network, Progress Sonic, ProVision, PS Select, SequeLink, Shadow, SOAPscope, SOAPStation, Sonic, Sonic ESB, SonicMQ, Sonic Orchestration Server, SonicSynergy, SpeedScript, Stylus Studio, Technical Empowerment, WebSpeed, Xcalia (and design), and Your Software, Our TechnologyExperience the Connection are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, Apama Dashboard Studio, Apama Event Manager, Apama Event Modeler, Apama Event Store, Apama Risk Firewall, AppsAlive, AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Business Making Progress, Cache-Forward, DataDirect Spy, DataDirect SupportLink, Fuse, Fuse Mediation Router, Fuse Message Broker, Fuse Services Framework, Future Proof, GVAC, High Performance Integration, ObjectStore Inspector, ObjectStore Performance Expert, OpenAccess, Orbacus, Pantero, POSSE, ProDataSet, Progress ESP Event Manager, Progress ESP Event Modeler, Progress Event Engine, Progress RFID, Progress Software Business Making Progress, PSE Pro, SectorAlliance, SeeThinkAct, Shadow z/Services, Shadow z/Direct, Shadow z/Events, Shadow z/Presentation, Shadow Studio, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, Sonic Business Integration Suite, Sonic Process Manager, Sonic Collaboration Server, Sonic Continuous Availability Architecture, Sonic Database Service, Sonic Workbench, Sonic XML Server, StormGlass, The Brains Behind BAM, WebClient, Who Makes Progress, and Your World. Your SOA. are trademarks or service marks of Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and other countries. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Any other trademarks contained herein are the property of their respective owners. Third party acknowledgements See the Third party acknowledgements section on page Preface11.

December 2009

Last updated with new content: Release 10.2B

Product Code: 4496; R10.2B

For the latest documentation updates see OpenEdge Product Documentation on PSDN (http://communities.progress.com/ pcom/docs/DOC-16074).

ContentsPreface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Preface1 ABL Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Widget Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143 Handle Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189 Handle Attributes and Methods Reference . . . . . . . . . . . . . . . . . . . . . . . 1271 Handle-based Object Events Reference. . . . . . . . . . . . . . . . . . . . . . . . . . 1827 Class and Interface Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851 Class Properties and Methods Reference . . . . . . . . . . . . . . . . . . . . . . . . 1889 Class Events Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953 Keyword Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1971 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index1

Contents

Contents2

Preface

This Preface contains the following sections: Purpose Audience Organization Using this manual Typographical conventions Examples of syntax descriptions Example procedures OpenEdge messages Third party acknowledgements

Preface

PurposeThis book describes ABL (Advanced Business Language), which is the OpenEdge programming language for building business applications. It covers all ABL statements, functions, phrases, operators, preprocessor directives, special symbols, widgets, handles, classes, interfaces, attributes, methods, properties, and events.

AudienceThis book is intended for programmers who develop applications using ABL and for anyone who needs to read and understand ABL code.

OrganizationThis book consists of the following sections: A dictionary of ABL statements, functions, phrases, operators, preprocessors, and special symbols. A dictionary of ABL widgets. A dictionary of ABL handles. A dictionary of ABL attributes and methods (for handles). A dictionary of ABL handle-based object events. A dictionary of ABL classes and interfaces. A dictionary of ABL properties and methods (for classes). A dictionary of ABL class events and event methods An index of ABL keywords.

Using this manualOpenEdge provides a special purpose programming language for building business applications. In the documentation, the formal name for this language is ABL (Advanced Business Language). With few exceptions, all keywords of the language appear in all UPPERCASE, using a font that is appropriate to the context. All other alphabetic language content appears in mixed case. For the latest documentation updates see the OpenEdge Product Documentation Overview page on PSDN: http://communities.progress.com/pcom/docs/DOC-16074.

Preface2

Preface

References to ABL compiler and run-time featuresABL is both a compiled and an interpreted language that executes in a run-time engine. The documentation refers to this run-time engine as the ABL Virtual Machine (AVM). When the documentation refers to ABL source code compilation, it specifies ABL or the compiler as the actor that manages compile-time features of the language. When the documentation refers to run-time behavior in an executing ABL program, it specifies the AVM as the actor that manages the specified run-time behavior in the program. For example, these sentences refer to the ABL compilers allowance for parameter passing and the AVMs possible response to that parameter passing at run time: ABL allows you to pass a dynamic temp-table handle as a static temp-table parameter of a method. However, if at run time the passed dynamic temp-table schema does not match the schema of the static temp-table parameter, the AVM raises an error. The following sentence refers to run-time actions that the AVM can perform using a particular ABL feature: The ABL socket object handle allows the AVM to connect with other ABL and non-ABL sessions using TCP/IP sockets.

References to ABL data typesABL provides built-in data types, built-in class data types, and user-defined class data types. References to built-in data types follow these rules: Like most other keywords, references to specific built-in data types appear in all using a font that is appropriate to the context. No uppercase reference ever includes or implies any data type other than itself. Wherever integer appears, this is a reference to the INTEGER or INT64 data type. Wherever character appears, this is a reference to the CHARACTER, LONGCHAR, or CLOB data type. Wherever decimal appears, this is a reference to the DECIMAL data type. Wherever numeric appears, this is a reference to the INTEGER, INT64, or DECIMAL data type.

UPPERCASE,

References to built-in class data types appear in mixed case with initial caps, for example, References to user-defined class data types appear in mixed case, as specified for a given application example.Progress.Lang.Object.

Structure of reference entriesEach ABL element reference description includes some subset of the following information: Platform-restriction notations A purpose or description of the language element Block properties for all block statements Data-movement diagrams for all data-handling statements The syntax for the language element The options and arguments you can use with the language element Preface3

Preface One or more examples that illustrate the use of the language element Notes that highlight special cases or provide hints on using the language element A See Also section that lists related language elements

Platform-restriction notesSome language elements and features of ABL do not apply to all software platformsoperating systems, user interfaces, and database management systemsthat OpenEdge supports. The documentation tries to note each such platform restriction with the language element title. Some language elements apply to SpeedScript programming and some do not; the documentation indicates which language elements do not apply with a note in the language element description. You can consider a language element as supported for all interfaces, on all operating systems, and for SpeedScript unless otherwise indicated in the language element description. The platform restriction notes that appear in the documentation include the following: AppServer only The element or feature applies only to the OpenEdge AppServer. Character interfaces only The element or feature applies only to the character interfaces that OpenEdge supports. Graphical interfaces only The element or feature applies only to the graphical interfaces that OpenEdge supports. NT and UNIX only The element or feature applies only to the Windows and UNIX versions that OpenEdge supports. ORACLE only The element or feature applies only to the ORACLE versions that OpenEdge supports. UNIX only The element or feature applies only to the UNIX versions that OpenEdge supports. Windows only The element or feature applies only to the Windows versions that OpenEdge supports. Windows only; Graphical interfaces only The element or feature applies only to the graphical interfaces of the traditional OpenEdge GUI for the Windows versions that OpenEdge supports. Windows only; GUI for .NET only The element or feature applies only to the .NET forms, controls, or other .NET objects for the Windows versions that OpenEdge supports. Preface4

Preface For a complete list of the software platforms that OpenEdge supports, see OpenEdge Getting Started: Installation and Configuration.

Typographical conventionsThis manual uses the following typographical conventions:

Convention Bold ItalicSMALL, BOLD CAPITAL LETTERS KEY1+KEY2

Description Bold typeface indicates commands or characters the user types, provides emphasis, or the names of user interface elements. Italic typeface indicates the title of a document, or signifies new terms. Small, bold capital letters indicate OpenEdge key functions and generic keyboard keys; for example, GET and CTRL. A plus sign between key names indicates a simultaneous key sequence: you press and hold down the first key while pressing the second key. For example, CTRL+X. A space between key names indicates a sequential key sequence: you press and release the first key, then press another key. For example, ESCAPE H.

KEY1 KEY2

Syntax:Fixed width

A fixed-width font is used in syntax statements, code examples, system output, and filenames. Fixed-width italics indicate variables in syntax statements. Fixed-width bold indicates variables with special emphasis. Uppercase words are ABL keywords. Although these are always shown in uppercase, you can type them in either uppercase or lowercase in a procedure. This icon (three arrows) introduces a multi-step procedure. This icon (one arrow) introduces a single-step procedure.

Fixed-width italics Fixed-width bold UPPERCASE fixed width

Period (.) or colon (:)

All statements except DO, FOR, FUNCTION, PROCEDURE, and REPEAT end with a period. DO, FOR, FUNCTION, PROCEDURE, and REPEAT statements can end with either a period or a colon. Large brackets indicate the items within them are optional. Small brackets are part of ABL. Large braces indicate the items within them are required. They are used to simplify complex syntax diagrams.

[][]

{}

Preface5

Preface

Convention {}

Description Small braces are part of ABL. For example, a called external procedure must use braces when referencing arguments passed by a calling procedure. A vertical bar indicates a choice. Ellipses indicate repetition: you can choose one or more of the preceding items.

| ...

Examples of syntax descriptionsIn this example, ACCUM is a keyword, and aggregate and expression are variables: SyntaxACCUM aggregate expression FOR

is one of the statements that can end with either a period or a colon, as in this example:

FOR EACH Customer: DISPLAY Name. END.

In this example, STREAM stream, UNLESS-HIDDEN, and NO-ERROR are optional: SyntaxDISPLAY

[

STREAM stream

] [

UNLESS-HIDDEN

] [

NO-ERROR

]

In this example, the outer (small) brackets are part of the language, and the inner (large) brackets denote an optional item: SyntaxINITIAL [ constant

[

, constant

]

]

A called external procedure must use braces when referencing compile-time arguments passed by a calling procedure, as shown in this example: Syntax{ &argument-name }

Preface6

Preface In this example, EACH, FIRST, and LAST are optional, but you can choose only one of them: SyntaxPRESELECT

[

EACH

|

FIRST

|

LAST

]

record-phrase

In this example, you must include two expressions, and optionally you can include more. Multiple expressions are separated by commas: SyntaxMAXIMUM ( expression , expression

[

, expression

] ...

)

In this example, you must specify MESSAGE and at least one expression or SKIP [ (n) any number of additional expression or SKIP [ ( n ) SyntaxMESSAGE

], and

] is allowed:

{

expression

|

SKIP

[

( n )

] } ...

In this example, you must specify {include-file, then optionally any number of argument or &argument-name = "argument-value", and then terminate with }: Syntax{ include-file

[

argument

|

&argument-name = "argument-value"

] ...

}

Long syntax descriptions split across linesSome syntax descriptions are too long to fit on one line. When syntax descriptions are split across multiple lines, groups of optional and groups of required items are kept together in the required order. In this example, WITH is followed by six optional items: SyntaxWITH

[

ACCUM max-length

] [

expression DOWN

[ [

CENTERED STREAM-IO

] [ ]

n COLUMNS

] [

SIDE-LABELS

] ]

Preface7

Preface

Complex syntax descriptions with both required and optional elementsSome syntax descriptions are too complex to distinguish required and optional elements by bracketing only the optional elements. For such syntax, the descriptions include both braces (for required elements) and brackets (for optional elements). In this example, ASSIGN requires either one or more field entries or one record. Options available with field or record are grouped with braces and brackets: SyntaxASSIGN

{ [ FRAME frame ] { field [ = expression ] } [ WHEN expression ] } ... | { record [ EXCEPT field ... ] }

Example proceduresThis manual provides numerous example procedures that illustrate syntax and concepts. You can access the example files and details for installing the examples from the following locations: The Documentation and Samples located in the doc_samples directory on the OpenEdge Product DVD The OpenEdge Product Documentation Overview page on PSDN:

http://communities.progress.com/pcom/docs/DOC-16074

Once installed, you can locate the example files for this manual in the following OpenEdge installation directory path:

src\prodoc\langref

Preface8

Preface

OpenEdge messagesOpenEdge displays several types of messages to inform you of routine and unusual occurrences: Execution messages inform you of errors encountered while OpenEdge is running a procedure; for example, if OpenEdge cannot find a record with a specified index field value. Compile messages inform you of errors found while OpenEdge is reading and analyzing a procedure before running it; for example, if a procedure references a table name that is not defined in the database. Startup messages inform you of unusual conditions detected while OpenEdge is getting ready to execute; for example, if you entered an invalid startup parameter.

After displaying a message, OpenEdge proceeds in one of several ways: Continues execution, subject to the error-processing actions that you specify or that are assumed as part of the procedure. This is the most common action taken after execution messages. Returns to the Procedure Editor, so you can correct an error in a procedure. This is the usual action taken after compiler messages. Halts processing of a procedure and returns immediately to the Procedure Editor. This does not happen often. Terminates the current session.

OpenEdge messages end with a message number in parentheses. In this example, the message number is 200:

** Unknown table name table. (200)

If you encounter an error that terminates OpenEdge, note the message number before restarting.

Obtaining more information about OpenEdge messagesIn Windows platforms, use OpenEdge online help to obtain more information about OpenEdge messages. Many OpenEdge tools include the following Help menu options to provide information about messages: Choose Help Recent Messages to display detailed descriptions of the most recent OpenEdge message and all other messages returned in the current session. Choose Help Messages and then type the message number to display a description of a specific OpenEdge message. In the Procedure Editor, press the HELP key or F1.

On UNIX platforms, use the OpenEdge pro command to start a single-user mode character OpenEdge client session and view a brief description of a message by providing its number.

Preface9

Preface

To use the pro command to obtain a message description by message number: 1. Start the Procedure Editor:

OpenEdge-install-dir/bin/pro

2. 3. 4.

Press F3 to access the menu bar, then choose Help Messages. Type the message number and press ENTER. Details about that message number appear. Press F4 to close the message, press F3 to access the Procedure Editor menu, and choose File Exit.

Preface10

Preface

Third party acknowledgementsOpenEdge includes AdventNet - Agent Toolkit licensed from AdventNet, Inc. http://www.adventnet.com. All rights to such copyright material rest with AdventNet. OpenEdge includes ANTLR (Another Tool for Language Recognition) software Copyright 2003-2006, Terence Parr All rights reserved. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. Software distributed on an AS IS basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License agreement that accompanies the product. OpenEdge includes software developed by the Apache Software Foundation (http://www.apache.org/). Copyright 1999 The Apache Software Foundation. All rights reserved (Xerces C++ Parser (XML) and Xerces2 Java Parser (XML)); Copyright 1999-2002 The Apache Software Foundation. All rights reserved (Xerces Parser (XML); and Copyright 2000-2003 The Apache Software Foundation. All rights reserved (Ant). The names Apache, Xerces, ANT, and Apache Software Foundation must not be used to endorse or promote products derived from this software without prior written permission. Products derived from this software may not be called Apache, nor may Apache appear in their name, without prior written permission of the Apache Software Foundation. For written permission, please contact apache@apache.org. Software distributed on an AS IS basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License agreement that accompanies the product. OpenEdge includes Concurrent Java software Copyright 1994-2000 Sun Microsystems, Inc. All Rights Reserved. -Neither the name of or trademarks of Sun may be used to endorse or promote products including or derived from the Java Software technology without specific prior written permission; and Redistributions of source or binary code must contain the above copyright notice, this notice and the following disclaimers: This software is provided "AS IS," without a warranty of any kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC. AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN MICROSYSTEMS, INC. OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN MICROSYSTEMS, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. OpenEdge includes DataDirect software Copyright 1991-2007 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved. (DataDirect Connect for JDBC Type 4 driver); Copyright 1993-2009 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved. (DataDirect Connect for JDBC); Copyright 1988-2007 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved. (DataDirect Connect for ODBC); and Copyright 1988-2007 Progress Software

Preface11

Preface Corporation and/or its subsidiaries or affiliates. All Rights Reserved. (DataDirect Connect64 for ODBC). OpenEdge includes DataDirect Connect for ODBC and DataDirect Connect64 for ODBC software, which include ICU software 1.8 and later - Copyright 1995-2003 International Business Machines Corporation and others All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. OpenEdge includes DataDirect Connect for ODBC and DataDirect Connect64 for ODBC software, which include software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http:/www.openssl.org/). Copyright 1998-2006 The OpenSSL Project. All rights reserved. And Copyright 1995-1998 Eric Young (eay@cryptsoft.com). All rights reserved. OpenEdge includes DataDirect products for the Microsoft SQL Server database which contain a licensed implementation of the Microsoft TDS Protocol. OpenEdge includes software authored by David M. Gay. Copyright 1991, 2000, 2001 by Lucent Technologies (dtoa.c); Copyright 1991, 1996 by Lucent Technologies (g_fmt.c); and Copyright 1991 by Lucent Technologies (rnd_prod.s). Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software. THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. OpenEdge includes software authored by David M. Gay. Copyright 1998-2001 by Lucent Technologies All Rights Reserved (decstrtod.c; strtodg.c); Copyright 1998, 2000 by Lucent Technologies All Rights Reserved (decstrtof.c; strtord.c); Copyright 1998 by Lucent Technologies All Rights Reserved (dmisc.c; gdtoa.h; gethex.c; gmisc.c; sum.c); Copyright 1998, 1999 by Lucent Technologies All Rights Reserved (gdtoa.c; misc.c; smisc.c; ulp.c); Copyright 1998-2000 by Lucent Technologies All Rights Reserved (gdtoaimp.h); Copyright 2000 by Lucent Technologies All Rights Reserved (hd_init.c). Full copies of these licenses can be found in the installation directory, in the c:/OpenEdge/licenses folder. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that the copyright notice and this permission notice and warranty disclaimer appear in supporting documentation, and that the name of Lucent or any of its entities not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Preface12

Preface OpenEdge includes http package software developed by the World Wide Web Consortium. Copyright 1994-2002 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All rights reserved. This work is distributed under the W3C Software License [http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231] in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. OpenEdge includes ICU software 1.8 and later - Copyright 1995-2003 International Business Machines Corporation and others All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. OpenEdge includes Imaging Technology copyrighted by Snowbound Software 1993-2003. www.snowbound.com. OpenEdge includes Infragistics NetAdvantage for .NET v2009 Vol 2 Copyright 1996-2009 Infragistics, Inc. All rights reserved. OpenEdge includes JSTL software Copyright 1994-2006 Sun Microsystems, Inc. All Rights Reserved. Software distributed on an AS IS basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License agreement that accompanies the product. OpenEdge includes OpenSSL software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). Copyright 1998-2007 The OpenSSL Project. All rights reserved. This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com). Copyright 1995-1998 Eric Young (eay@cryptsoft.com) All rights reserved. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact openssl-core@openssl.org. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project. Software distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License agreement that accompanies the product. OpenEdge includes Quartz Enterprise Job Scheduler software Copyright 2001-2003 James House. All rights reserved. Software distributed on an AS IS basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License agreement that accompanies the product. This product uses and includes within its distribution, software developed by the Apache Software Foundation (http://www.apache.org/). OpenEdge includes code licensed from RSA Security, Inc. Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/. OpenEdge includes the RSA Data Security, Inc. MD5 Message-Digest Algorithm. Copyright 1991-2, RSA Data Security, Inc. Created 1991. All rights reserved.

Preface13

Preface OpenEdge includes Sonic software, which includes software developed by Apache Software Foundation (http://www.apache.org/). Copyright 1999-2000 The Apache Software Foundation. All rights reserved. The names Ant, Axis, Xalan, FOP, The Jakarta Project, Tomcat, Xerces and/or Apache Software Foundation must not be used to endorse or promote products derived from the Product without prior written permission. Any product derived from the Product may not be called Apache, nor may Apache appear in their name, without prior written permission. For written permission, please contact apache@apache.org. OpenEdge includes Sonic software, which includes software Copyright 1999 CERN European Organization for Nuclear Research. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. CERN makes no representations about the suitability of this software for any purpose. It is provided "as is" without expressed or implied warranty. OpenEdge includes Sonic software, which includes software developed by ExoLab Project (http://www.exolab.org/). Copyright 2000 Intalio Inc. All rights reserved. The names Castor and/or ExoLab must not be used to endorse or promote products derived from the Products without prior written permission. For written permission, please contact info@exolab.org. Exolab, Castor and Intalio are trademarks of Intalio Inc. OpenEdge includes Sonic software, which includes software developed by IBM. Copyright 1995-2003 International Business Machines Corporation and others. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. Software distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License agreement that accompanies the product. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. OpenEdge includes Sonic software, which includes the JMX Technology from Sun Microsystems, Inc. Use and Distribution is subject to the Sun Community Source License available at http://sun.com/software/communitysource. OpenEdge includes Sonic software, which includes software developed by the ModelObjects Group (http://www.modelobjects.com). Copyright 2000-2001 ModelObjects Group. All rights reserved. The name ModelObjects must not be used to endorse or promote products derived from this software without prior written permission. Products derived from this software may not be called ModelObjects, nor may ModelObjects appear in their name, without prior written permission. For written permission, please contact djacobs@modelobjects.com. OpenEdge includes Sonic software, which includes code licensed from Mort Bay Consulting Pty. Ltd. The Jetty Package is Copyright 1998 Mort Bay Consulting Pty. Ltd. (Australia) and others.

Preface14

Preface OpenEdge includes Sonic software, which includes files that are subject to the Netscape Public License Version 1.1 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/NPL/. Software distributed under the License is distributed on an AS IS basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. The Original Code is Mozilla Communicator client code, released March 31, 1998. The Initial Developer of the Original Code is Netscape Communications Corporation. Portions created by Netscape are Copyright 1998-1999 Netscape Communications Corporation. All Rights Reserved. OpenEdge includes Sonic software, which includes software developed by the University Corporation for Advanced Internet Development http://www.ucaid.edu Internet2 Project. Copyright 2002 University Corporation for Advanced Internet Development, Inc. All rights reserved. Neither the name of OpenSAML nor the names of its contributors, nor Internet2, nor the University Corporation for Advanced Internet Development, Inc., nor UCAID may be used to endorse or promote products derived from this software and products derived from this software may not be called OpenSAML, Internet2, UCAID, or the University Corporation for Advanced Internet Development, nor may OpenSAML appear in their name without prior written permission of the University Corporation for Advanced Internet Development. For written permission, please contact opensaml@opensaml.org. OpenEdge includes the UnixWare platform of Perl Runtime authored by Kiem-Phong Vo and David Korn. Copyright 1991, 1996 by AT&T Labs. Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software. THIS SOFTWARE IS BEING PROVIDED AS IS, WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T LABS MAKE ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. OpenEdge includes Vermont Views Terminal Handling Package software developed by Vermont Creative Software. Copyright 1988-1991 by Vermont Creative Software. OpenEdge includes XML Tools, which includes versions 8.9 of the Saxon XSLT and XQuery Processor from Saxonica Limited (http://www.saxonica.com/) which are available from SourceForge (http://sourceforge.net/projects/saxon/). The Original Code of Saxon comprises all those components which are not explicitly attributed to other parties. The Initial Developer of the Original Code is Michael Kay. Until February 2001 Michael Kay was an employee of International Computers Limited (now part of Fujitsu Limited), and original code developed during that time was released under this license by permission from International Computers Limited. From February 2001 until February 2004 Michael Kay was an employee of Software AG, and code developed during that time was released under this license by permission from Software AG, acting as a "Contributor". Subsequent code has been developed by Saxonica Limited, of which Michael Kay is a Director, again acting as a "Contributor". A small number of modules, or enhancements to modules, have been developed by other individuals (either written especially for Saxon, or incorporated into Saxon having initially been released as part of another open source product). Such contributions are acknowledged individually in comments attached to the relevant code modules. All Rights Reserved. The contents of the Saxon files are subject to the Mozilla Public License Version 1.0 (the "License"); you may not use these files except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/ and a copy of the license can also be found in the

Preface15

Preface installation directory, in the c:/OpenEdge/licenses folder. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. OpenEdge includes XML Tools, which includes Xs3P v1.1.3. The contents of this file are subject to the DSTC Public License (DPL) Version 1.1 (the "License"); you may not use this file except in compliance with the License. A copy of the license can be found in the installation directory, in the c:/OpenEdge/licenses folder. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. The Original Code is xs3p. The Initial Developer of the Original Code is DSTC. Portions created by DSTC are Copyright 2001, 2002 DSTC Pty Ltd. All rights reserved. OpenEdge includes YAJL software Copyright 2007, Lloyd Hilaiel. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of Lloyd Hilaiel nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Preface16

ABL Reference

This section contains reference entries that describe the syntax of ABL. They begin with descriptions of the language punctuation and special characters. The remaining entries contain descriptions of the ABL statements, functions, phrases, preprocessor directives, and miscellaneous other language elements. You can consider a language element as supported for all interfaces, on all operating systems, and for SpeedScript unless otherwise indicated in each language element description. These descriptions refer to both compile-time and run-time behavior, features that the language generally supports and determines at compile time and actions directed by using these features at run time. When describing compile-time features or actions, this section references ABL or the ABL compiler. When describing ABL-directed actions taken at run time, this section references the ABL Virtual Machine (AVM).

: PunctuationThe colon (:) symbol ends block labels and block header statements like DO, FOR, and REPEAT. It also serves as a separator between: A handle reference and an attribute or method, for example ttCust:PRIVATE-DATA or where ttCust is a handle to a temp-table

ttCust:CLEAR( ),

An object or static type-name reference and a class-based property, method, or event, for example, rObj:ToString( ), rObj:NEXT-SIBLING, or Progress.Lang.Class:GetClass( "Progress.Data.BindingSource" ), where rObj is an object reference to a Progress.Lang.Object instance A character string literal and one of its options, for example, "City/State/Zip":U

It also follows the EDITING keyword in an EDITING phrase and is a device delimiter in Windows.

:: Punctuation See :: Punctuation for rules to help you decide whether to use period, colon, or double colon syntax. See also :: Punctuation, . Punctuation, " "Character-string literal, Class-based object reference, Type-name syntax

:: PunctuationThe double colon (::) is a short-hand syntax for referencing constant named members of database object containers, for example dynamic ProDataSets, queries, temp-tables, and buffers. The following rules will help you to decide whether to use dot, colon, or double colon syntax: Use a dot between two names when the left-hand side name is the actual name of a database or table, known at compile time, and is not a handle or reference of any kind. For example, Customer.CustNum or Sports2000.Customer or Sports2000.Customer.CustNum. Use a colon between two character strings when the left-hand side is a handle or reference, and is not the actual name of a database or table, and the right-hand side is an attribute or method for the left-hand-side handle or reference. For example, hBuff:NUM-FIELDS, or hDset:NUM-BUFFERS or hBuff:FIND-FIRST. Use a double colon between two character strings when the left-hand side name is a handle to a container object of some kind (buffer, table or ProDataSet) and the right-hand side is not an attribute or method, but instead is a named member of the left-hand side. For example, hBuff::CustNum or hDset::Customer or hDSet::Customer::CustNum.

For example, if hBuff is a HANDLE to the Customer table, then hBuff:NAME returns the string "Customer", but hBuff::NAME returns the value of the NAME field for the current record in the hBuff Buffer, e.g. "Lift Line Skiing". See also : Punctuation, . Punctuation

. PunctuationThe period (.) symbol ends all statements, including block header statements. The DO, FOR, and REPEAT statements can end with a period or a colon. It is also serves as a separator between: A filename and a filename extension (suffix) in most operating system platforms, for example, Letter.txt The elements of a qualified database table or buffer field name, for example, or Sports2000.Customer or Sports2000.Customer.CustNum The elements of an ABL package name or .NET namespace, for example, Progress.Lang, or System.Collections

Customer.CustNum

Progress.Windows,

2

; Punctuation An ABL package or .NET namespace and the name of a class or interface defined in that package or namespace, for example, Progress.Lang.Error, Progress.Windows.Form, orSystem.Collections.SortedList

See :: Punctuation for rules to help you decide whether to use period, colon, or double colon syntax. See also : Punctuation, :: Punctuation, Type-name syntax

; PunctuationIn Progress Version 6.0 or later, the ANSI SQL (-Q) startup parameter allows you to redefine the semicolon as a terminator. This startup parameter enforces strict ANSI SQL conformance and allows you to terminate SQL statements with a semicolon. The ANSI SQL (-Q) parameter allows OpenEdge to run standard SQL statements and scripts built with other products. The ANSI SQL (-Q) parameter disables the use of the semicolon within UNIX escapes.

UNIX SMBL=foo; export SMBL

As a general rule, use the period (.) as a terminator for ABL statements even when you specify the ANSI SQL (-Q) parameter for an ABL session.

, PunctuationThe comma (,) symbol separates multiple file specifications (used in FOR statements, FOR phrases of DO and REPEAT statements, and PRESELECT phrases), branching statements (used in UNDO statements and phrases), and multiple arguments of a function.

; Special characterThis special character is supported only for backward compatibility. The semicolon (;), when combined with a second character in the Procedure Editor, provides alternative representations of special characters as follows:

Special Character Alternative Representation

@ ;&

[ ;

^ ;*

' ;'

{ ;(

| ;%

} ;)

~ ;?

To suppress the semicolons interpretation as a special character, precede it with a tilde (~). For example, to enter the string ;< in the Procedure Editor and not have ABL interpret it as an open bracket, type ~;= GT or > LE or = operator, GT or > operator, IF...THEN...ELSE statement, LE or < = operator, LT or < operator, NE or operator

\ Special characterThe backslash (\) is an escape character on UNIX platforms only. It is a directory path separator in Windows platforms only.

~ Special characterThe tilde (~) is an escape character that causes the AVM to read the following character literally. A tilde followed by three octal digits represents a single character. Use it as a lead-in to enter the special characters shown in Table 2. In a procedure, a tilde followed by something other than the items in Table 2 is ignored. For example, "~abc" is treated as "abc". (This may not work as expected when passing parameters to an include file.) The items in Table 2 are case sensitive. Table 2: Sequence ~" ~ ~~ ~\ ~{ ~nnn ~t ~r ~n ~E ~b ~f " ~ \ { A single character Tab character Carriage return New line / Line feed Escape Backspace Form feed Entering special characters in the Procedure Editor Interpreted as Comment Use within quoted strings as an alternative to two quotes (""). Use within quoted strings as an alternative to two apostrophes (). Where nnn is an octal value between 000 and 377. All three digits are required. Octal 011 Octal 015 Octal 012 Octal 033 Octal 010 Octal 014

5

" Special character

" Special characterThe double quote (") encloses character constants or strings. To use quotes within a quoted character string, you must use two double quotes (""), which compile to a single double quote ("), or you must put a tilde (~) in front of any quotes within the quoted character string. (This does not work when passing parameters to an include file.) See also " "Character-string literal

' Special characterThe function of the single quote (') is the same as the double quote. But, if you use single and double quotes in a statement, the compiler checks the outermost quotes first, giving them precedence over the innermost quotes. For example, DISPLAY '"test"' shows up as "test", (ABL reads the double quotes literally), and DISPLAY "'test2'" shows up as 'test2'. See also " "Character-string literal

/ Special characterThe slash (/) symbol is a directory path separator (UNIX). It is also used for date fields (99/99/99). See also " "Character-string literal

( ) Expression precedenceParentheses raise expression precedence. Also, some functions require you to enclose arguments in parentheses. See also / Division operator, Expression

[ ] Array referenceSquare brackets ([ ]) enclose array subscripts ([1], [2], etc.) or ranges (such as, [1 FOR 4]). In a range, you can use a variable for the first element, but the second element must be a constant. The specification [1 FOR 4] causes ABL to start with the first array element and to work with that and the next three elements. Square brackets are also used when specifying initial values for an array. For example, if you define an array variable of extent 3, you might specify initial values as INITIAL [0, 1, 2].

= Special characterSee the EQ or = operator, Assignment (=) statement. 6

< Special character

< Special characterSee the LT or < operator.

< = Special characterSee the LE or < = operator.

< > Special characterSee the NE or operator.

> Special characterSee the GT or > operator.

> = Special characterSee the GE or >= operator.

" "Character-string literalSpecifies a literal character-string value. Syntax"characters"

[

:

[

R

|

L

|

C

|

T

] [

U

] [

max-length

] ]

characters

The literal contents of the character string.R | L | C | T

Specifies the justification of the string within its maximum length: right, left, centered, or trimmed, respectively. The default justification depends on how the string is used. If the string is displayed with side labels, the default is right justification. If column labels are used, the defaults are left justification for character fields and right justification for numeric fields. Strings used in expressions are trimmed by default. R means right justified and padded on the left with spaces: "Hello":R10 = "Hello".

L means left justified and padded on the right with spaces: "Hello":L10 = "Hello ".

7

{ } Argument reference C means centered within the string and padded on both the right and left as needed:"Hello":C10 = " Hello ".

T means trimmed of leading and trailing blanks (although storage space and screen space is still allocated for the maximum number of characters): " Hello":T10 = "Hello" (but screen and storage space is still reserved for 10 characters).

U

Specifies that the string is untranslatable. This means that the string will not be processed by the OpenEdge Translation Manager. If you do not specify U, then the string is assumed to be translatable.max-length

The number of characters reserved for the string contents in the text segment. The default is the length of the string itself. You might want to specify a longer length if you expect a translation of the string to be longer. The longest length you can specify is 5120 characters. Note If you include the colon (:) after the quoted string, you must supply at least one option. Otherwise, ABL treats the colon as a statement separator.

{ } Argument referenceReferences the value of an argument that a procedure passes to a called external procedure file or to an include file. ABL converts each argument to a character format. This conversion removes the surrounding double-quotes if the parameter was specified as a character string constant in the RUN statement or include file reference. When one procedure is called from another and arguments are used, ABL recompiles the called procedure, substituting the arguments that the calling procedure passes, and then runs the called procedure. Syntax{

{

n

|

&argument-name

}

}

Enter the braces ({}) as shown; they do not represent syntax notation in this description.n

The number of the argument being referred to. If n = 0, ABL substitutes the name of the current procedure (the name you used when you called it, not the full pathname) as the argument. If n = *, ABL substitutes all arguments that the calling procedure passes (but not the name {0}). If you refer to the nth parameter and the calling procedure does not supply it, {n} is ignored.&argument-name

The name of the argument being referred to. If you refer to an argument-name and the calling procedure does not supply it, ABL ignores {&argument-name}.

8

{ } Argument reference If argument-name is an asterisk (*), ABL substitutes all arguments that the calling procedure passes. It also adds quotation marks to each parameter, so you can pass the named argument list through multiple levels of include files. Note: It is invalid to pass both numbered and named arguments within a single pair of braces. Although this will not cause a compile-time or run-time error, the arguments will not be passed correctly.

Examples

The procedure r-arg.p runs procedure r-arg2.p, passing the arguments customer and name to r-arg2.p. ABL substitutes these arguments for {1} and {2} in the r-arg2.p procedure. r-arg.pRUN r-arg2.p "customer" "name"

r-arg2.pFOR EACH {1}: DISPLAY {2}. END.

The r-inc.p procedure defines the variables txt and num, and assigns the values "Progress VERSION" and "7" to them. The r-inc.p procedure includes the r-inc.ifile and passes the &int and &str arguments to the include file. Because the parameters are named, their order is unimportant. The called procedure can find each argument, regardless of placement. The r-inc.i include file displays a message that consists of the passed arguments. The asterisk argument displays all the parameters as they are listed in the r-inc.p procedure. r-inc.pDEFINE VARIABLE cTxt AS CHARACTER NO-UNDO. DEFINE VARIABLE iNum AS INTEGER NO-UNDO. ASSIGN cTxt = "Progress VERSION" iNum = 7. {r-inc.i &int=iNum &str=cTxt}

r-inc.iMESSAGE {&str} {&int}. /* the &str named argument */ /* the &int named argument */

MESSAGE "An asterisk displays all the arguments:" {*} /* all the arguments passed by the calling procedure */

Notes

If you pass {} arguments using the RUN statement, you cannot precompile the called procedure. When ABL compiles a procedure, it must have all the values the procedure needs. So, if you pass arguments to a procedure you are calling with the RUN statement, the AVM evaluates those arguments when the calling procedure is run, not when it is compiled.

9

{ } Include file reference You can use the name of an include file as an argument to another include file. For example, a reference to {{1}} in an included procedure causes ABL to include the statements from the file with the name that passed as the first argument. Use DEFINE PARAMETER to define a run-time parameter in a called subprocedure. Each parameter requires its own DEFINE statement. The parameters must be specified in the RUN statement in the same order as defined with DEFINE statements. ABL disregards an empty pair of braces ({}). The maximum length of the arguments you can pass to an include file is determined by the Input Characters (-inp) startup parameter. An argument argument-name behaves like a scoped preprocessor name. Thus, if you define a preprocessor name, argument-name, its value replaces the value of any argument argument-name passed to the same file at the point where the preprocessor name, argument-name, is defined.

See also

; Special character, { } Include file reference, { } Preprocessor name reference, COMPILE statement, DEFINE PARAMETER statement, RUN statement

{ } Include file referenceCauses ABL to retrieve the statements in a file and compile them as part of the main procedure if it encounters the files name inside braces ({}) when compiling the procedure. You can name arguments you want substituted in the file before compilation. Syntax{ include-file

[

argument

... | {

&argument-name = "argument-value"

} ... ]

}

Enter the braces ({}) as shown; they do not represent syntax notation in this description.include-file

The name of an external operating system file that contains statements you want included during the compilation of a main procedure. This filename follows normal operating system naming conventions and is case sensitive on UNIX. If the file you name has an unqualified path name, ABL searches directories based on the PROPATH environment variable. When ABL compiles the main procedure (the procedure containing the { } include file reference), it copies the contents of include-file into that procedure, substituting any arguments. So, you can use included procedures with arguments even when you precompile a procedure.argument

A value used by include-file, as a positional argument. With positional arguments, the first argument replaces {1} in the included file, the second argument replaces {2}, and so on.

10

{ } Include file reference&argument-name = "argument-value"

A name/value pair used by include-file as a named argument. The argument-name is the name of the argument you want to pass to the include file. You can use variable names, field names, and reserved words as argument names. The argument-value is the value of the argument you pass to the include file. Enclose the argument-value in quotation marks, as shown. With named arguments, argument-value replaces {&argument-name} in the included file. Examples The r-inc1.p procedure uses externally defined and maintained files (r-fcust.i and r-dcust.i) for the layout and display of a customer report. You can use these same include files in many procedures. r-inc1.pFOR EACH Customer NO-LOCK: {r-fcust.i} {r-dcust.i} END.

r-fcust.iFORM Customer.CustNum Customer.Name LABEL "Customer Name" Customer.Phone FORMAT "999-999-9999".

r-dcust.iDISPLAY Customer.CustNum Customer.Name Customer.Phone.

The r-incl2.p example references an include file (r-show.i) that can take up to five arguments, and the main routine passes four arguments. r-incl2.pDEFINE VARIABLE var1 AS INTEGER NO-UNDO INITIAL 9. DEFINE VARIABLE var2 AS DECIMAL NO-UNDO INITIAL 6.43. DEFINE VARIABLE var3 AS LOGICAL NO-UNDO INITIAL TRUE. /* any statements */ {r-show.i point-A var1 var2 var3} /* any statements */

r-show.iMESSAGE "At" "{1}" "{2}" {2} "{3}" {3} "{4}" {4} "{5}" {5}.

When the main procedure is compiled, the line referencing the r-show.i include file is replaced by the following line:

MESSAGE At point-A var1 9 var2 6.43 var3 yes

11

{ } Include file reference This example shows how you can use include files to extend ABL. The main procedure uses a new statement, r-show.i, to display the values of fields or variables at various points in a procedure. The include file in this example can handle up to five passed arguments. The main procedure only passes four (point-A, var1, var2, and var3). The r-custin.p procedure displays a frame for each customer that you can update with customer information. The procedure includes r-cstord.i and passes the named argument &frame-options, and the value of the argument (CENTERED ROW 3 NO-LABEL) to the include file. When the include file references the &frame-options argument, it uses the value of the argument, and therefore displays the OVERLAY frame cust-ord as a centered frame at row 3 without a label. r-custin.pFOR EACH Customer: {r-cstord.i &frame-options = "CENTERED ROW 3 NO-LABEL"}. UPDATE Customer.CustNum Customer.Name Customer.Address Customer.Address2 Customer.City Customer.State Customer.PostalCode Customer.Phone Customer.CreditLimit WITH FRAME cust-ord. END.

r-cstord.iFORM "Cust #" AT 1 Customer.CustNum AT 10 SKIP(1) Customer.Name AT 10 customer.Address AT 10 customer.Address2 AT 10 customer.City AT 10 Customer.State Customer.PostalCode SKIP(1) "Phone " AT 1 Customer.Phone FORMAT "999/999-9999" AT 10 "Max Crd" AT 1 Customer.CreditLimit AT 10 WITH FRAME cust-ord OVERLAY {&frame-options}.

Include files are particularly useful for using form layouts in multiple procedures, especially if you do not include the keyword FORM or the closing period (.) of the FORM statement. Thus, the following r-incl3.p procedure includes the r-cust.f file as the definition of a FORM statement. r-incl3.pFORM {r-cust.f}.

r-cust.fCustomer.CustNum Customer.Name SKIP(2) Customer.State

The r-incl4.p procedure uses the same include file as a layout for a DISPLAY statement: r-incl4.pFOR EACH Customer NO-LOCK: DISPLAY {r-cust.f} WITH 3 DOWN. END.

12

{ } Include file reference Notes You can pass a series of positional arguments or a series of named arguments to an include file, but you cannot pass a combination of positional and named arguments to an include file. When you use braces to include one procedure in another, ABL does not include the second procedure until it compiles the first one. This technique has the same effect as using the Editor to copy statements into the main procedure. At times, separate include files are easier to maintain. You can nest include files. (They can contain references to other include files.) The number of nested include files is limited by the number of file descriptors available on the system. If you have many nested include files and you are running on a Sequent machine, use Maximum Files (-Mv) startup parameter to control the number of files you can open simultaneously. When you have a base procedure and want to make several copies of it, changing it slightly each time, use include files with parameters. For example, at times you might only want to change the name of some files or fields used by the procedure. If you define a preprocessor name and later pass a compile-time argument with the same name, but a different value, to a procedure or include file, the value of the initial preprocessor name remains unchanged. Thus, a compile-time argument is scoped to the file to which it is passed. Instead of maintaining duplicate source files, create a single include file with the variable portions (such as the names of files and fields) replaced by {1}, {2}, etc. Then each procedure you write can use that include file, passing file and field names as arguments. You can use the name of an include file as an argument to another include file. For example, a reference to {{1}} in an include file causes ABL to include the statements from the file with the name that passed as the first argument. ABL disregards an empty pair of braces ({}). If you use double quotes ( ) around arguments in an argument list, ABL removes them. However, if you use single quotes ( ), ABL passes them. To pass one set of double quotes, you must use four sets of double quotes. When ABL reads an include file into the source, it appends a space character to the end of an include file. For example, the following include file r-string.i contains data that is used by r-incstr.p. r-string.iabcde

r-incstr.pDISPLAY LENGTH("{r-string.i}").

Although r-string.i contains five letters, when you run r-incstr.p, it returns the value 6 because ABL appends a space character to the end of r-string.i. 13

{ } Preprocessor name reference The maximum length of the arguments you can pass to an include file is determined by the Input Characters (-inp) startup parameter.

See also

{ } Argument reference, { } Preprocessor name reference, COMPILE statement, DEFINE PARAMETER statement, RUN statement

{ } Preprocessor name referenceReferences the value of a preprocessor name in any ABL or preprocessor expression. Syntax{ &preprocessor-name }

Enter the braces ({}) as shown; they do not represent syntax notation in this description.&preprocessor-name

Expands the name, preprocessor-name, to its defined value. You can define preprocessor names using either the &GLOBAL-DEFINE preprocessor directive or the &SCOPED-DEFINE preprocessor directive. ABL also provides a set of built-in preprocessor names that you can reference for a variety of session information. Table 3 lists each built-in preprocessor name with its description. Table 3: Built-in preprocessor names (1 of 2)

The preprocessor name . . . BATCH-MODE FILE-NAME

Expands to an unquoted string . . . Equal to "yes" if the Batch (-b) startup parameter was used to start the client session. Otherwise, it expands to "no". That contains the name of the file being compiled.1 If you want only the name of the file as specified in the { } Include File Reference, the RUN statement, or the COMPILE statement, use the argument reference {0}. That contains the current line number in the file being compiled. If you place this reference in an include file, the line number is calculated from the beginning of the include file. That contains the name of the operating system on which the file is being compiled. The OPSYS name can have the same values as the OPSYS function. The possible values are UNIX and WIN32".2

LINE-NUMBER

OPSYS

14

{ } Preprocessor name reference Table 3: Built-in preprocessor names (2 of 2)

The preprocessor name . . . SEQUENCE

Expands to an unquoted string . . . Representing a unique integer value that is sequentially generated each time the SEQUENCE preprocessor name is referenced. When a compilation begins, the value of {&SEQUENCE} is 0; each time {&SEQUENCE} is referenced, the value increases by 1. To store the value of a reference to SEQUENCE, you must define another preprocessor name as {&SEQUENCE} at the point in your code you want the value retained. That contains the name of the windowing system in which the file is being compiled. The possible values include "MS-WINDOWS", "MS-WIN95", "MS-WINXP", and "TTY".3

WINDOW-SYSTEM

1. When running the source code of a procedure file loaded into the Procedure Editor or the AppBuilder, {&FILE-NAME} expands to a temporary filename, not the name of the file under which the source code might be saved. 2. ABL supports an override option that enables applications that need to return the value of MS-DOS for all Microsoft operating systems to do so. For example, if you do not want the value WIN32 to be returned when either Windows 95 or Windows NT operating systems are recognized, you can override this return value by defining the Opsys key in the Startup section of the current environment, which can be in the registry or in an initialization file. If the Opsys key is located, the OPSYS function returns the value associated with the Opsys key on all platforms. 3. ABL supports an override option for the &WINDOW-SYSTEM preprocessor name that provides backward compatibility. This option enables applications that need the WINDOW-SYSTEM preprocessor name to return the value of MS-WINDOWS for all Microsoft operating systems to do so. To establish this override value, define the WindowSystem key in the Startup section of the current environment, which can be in the registry or in an initialization file. If the WindowSystem key is located, the WINDOW-SYSTEM preprocessor name returns the value associated with the WindowSystem key on all platforms.

Table 4 lists the additional built-in preprocessor names that apply to SpeedScript. Table 4: SpeedScript built-in preprocessor names

The preprocessor name . . . DISPLAY OUT OUT-FMT OUT-LONG WEBSTREAM Examples

Expands to an unquoted string . . . DISPLAY {&WEBSTREAM} PUT {&WEBSTREAM} UNFORMATTED PUT {&WEBSTREAM} FORMATTED EXPORT {&WEBSTREAM} STREAM WebStream

The r-prprc1.p procedure shows how you can reference a built-in preprocessor name and include it in a character string. r-prprc1.pMESSAGE "The current operating system is" "{&OPSYS}." VIEW-AS ALERT-BOX.

15

{ } Preprocessor name reference The procedure r-prprc2.p shows how to capture the value of a {&SEQUENCE} reference. In this example, {&SEQUENCE} is referenced three times, once each to assign its value to wvar (0) and xvar (1) at run time. The third reference defines the preprocessor name Last-Value with the value 3. As shown, Last-Value is assigned unchanged to both yvar and zvar, each of which take the value 3 at run time. r-prprc2.pDEFINE DEFINE DEFINE DEFINE VARIABLE VARIABLE VARIABLE VARIABLE wvar xvar yvar zvar AS AS AS AS INTEGER INTEGER INTEGER INTEGER NO-UNDO. NO-UNDO. NO-UNDO. NO-UNDO.

ASSIGN wvar = {&SEQUENCE} xvar = {&SEQUENCE}. &GLOBAL-DEFINE Last-Value {&SEQUENCE} ASSIGN yvar = {&Last-Value} zvar = {&Last-Value}. MESSAGE "wvar =" wvar SKIP "xvar =" xvar SKIP "yvar =" yvar SKIP "zvar =" zvar VIEW-AS ALERT-BOX.

The procedure r-prprc3.p shows how preprocessor names override compile-time arguments. In this example, r-prprc3.p defines the preprocessor name My-Name as "Daniel". It then passes the compile-time argument My-Name, with the value "David", to the include file r-prprc3.i, which in turn defines a preprocessor name My-Name as "Donald". r-prprc3.p&SCOPED-DEFINE My-Name "Daniel" {r-prprc3.i &My-Name = "David"} MESSAGE "My-Name preprocessed in r-prprc3.p is" {&My-Name} + "." VIEW-AS ALERT-BOX.

r-prprc3.iMESSAGE "My-Name argument in r-prprc3.i is" "{&My-Name}" + "." VIEW-AS ALERT-BOX. &SCOPED-DEFINE My-Name "Donald" MESSAGE "My-Name preprocessed in r-prprc3.i is" {&My-Name} + "." VIEW-AS ALERT-BOX

During execution, the first message included by r-prprc3.i displays the value of the My-Name argument, "David". The second message included by r-prprc3.i displays the value of the following My-Name preprocessor name, defined as "Donald", permanently overriding "David" passed by the My-Name argument. Finally, the message in r-prprc3.p displays the value of the My-Name preprocessor name that was initially defined there, "Daniel", because the value from My-Name established in r-prprc3.i ("Donald") went out of scope during compilation. Note also that the reference to the My-Name compile-time argument in r-prprc3.i is inside double-quotes, because ABL passes string constant values for compile-time arguments without the surrounding double-quotes.

16

&GLOBAL-DEFINE preprocessor directive You can encounter compilation problems mixing preprocessor names with compile-time argument names. The following example, a variation of r-prprc3.i, does not compile, even when passed a My-Name argument as an include file. This is because the preprocessor My-Name value overrides the argument My-Name value, as shown:

&SCOPED-DEFINE My-Name "Donald" MESSAGE "My-Name preprocessed in r-prprc3.i is" {&My-Name} + "." VIEW-AS ALERT-BOX. MESSAGE "My-Name argument in r-prprc3.i is" "{&My-Name}" + "." VIEW-AS ALERT-BOX.

Because the preprocessor My-Name defines a quoted "Donald" value, ABL replaces "{&My-Name}" in the fourth line with ""Donald"". This appears to the compiler as two empty strings and an unknown variable reference (Donald). Although you can do it with care, in general, avoid using the same names for compile-time arguments and preprocessor names. Notes ABL expands preprocessor names wherever and in whatever context it finds them, including inside quoted character strings. If you define a preprocessor name in the same file and with the same name as a compile-time argument passed to the file, the value of the preprocessor name takes precedence over the value of the argument name from the point where the preprocessor name is defined.

See also

&GLOBAL-DEFINE preprocessor directive, &SCOPED-DEFINE preprocessor directive, { } Argument reference, { } Include file reference, ; Special character

&GLOBAL-DEFINE preprocessor directiveGlobally defines a compile-time constant (preprocessor name). Syntax&GLOBAL-DEFINE preprocessor-name definition

preprocessor-name

The preprocessor name (compile-time constant) that you supply. ABL reserved keywords are allowed, but cannot be used in preprocessor expressions.definition

A string of characters (or preprocessor references that evaluate to a string of characters) whose content the preprocessor substitutes for preprocessor-name during compilation. If the definition is longer than one line, a tilde (~) at the end of a line indicates continuation to the next line. Examples In this example, the preprocessor name MAX-EXPENSE is defined as the text string "5000":

&GLOBAL-DEFINE MAX-EXPENSE 5000

17

&IF, &THEN, &ELSEIF, &ELSE, and &ENDIF preprocessor directives Wherever the reference {&MAX-EXPENSE} appears in the source code, the preprocessor substitutes the text string 5000". For example, the preprocessor changes this line of code:

IF tot-amount (Order.PromiseDate + 7) THEN DO: FIND Customer OF Order NO-LOCK. DISPLAY Order.OrderNum Order.CustNum Customer.Name Order.PromiseDate Customer.Terms. END. END.

Notes

To add a specific number of days and a specific number of milliseconds to a DATETIME, use the DATETIME function. For example:

new-datetime = DATETIME( DATE(old-datetime) + days, MTIME(old-datetime) + milliseconds ).

The DATETIME function ensures that the time portion remains within the valid range, by adding day(s) to the date part when the time part goes over the number of milliseconds in a day. To add a specific number of days and milliseconds to a DATETIME-TZ, use the DATETIME-TZ function. For example:

new-datetime-tz = DATETIME-TZ( DATE(old-datetime-tz) + days, MTIME (old-datetime-tz) + milliseconds, TIMEZONE(old-dateime-tz) ).

The DATETIME-TZ function ensures that the time portion remains within the valid range, by adding day(s) to the date portion when the time part goes over the number of milliseconds in a day. See also Date subtraction operator, + Datetime addition operator, ADD-INTERVAL function, DATE function

+ Datetime addition operatorAdds a number of milliseconds to a DATETIME or a DATETIME-TZ to produce another DATETIME or DATETIME-TZ. Syntaxdatetime + milliseconds

26

+ Datetime addition operator

datetime-tz + milliseconds

datetime

An expression that evaluates to a DATETIME value.milliseconds

An expression that evaluates to an integer value specifying a number of milliseconds.datetime-tz

An expression that evaluates to a DATETIME-TZ value. Example This example returns the date and time exactly 24 hours later (dtTime) by calculating and adding the number of milliseconds in 24 hours to the present date and time (NOW function) and displays the result:

DEFINE VARIABLE dtTime AS DATETIME NO-UNDO. DEFINE VARIABLE iHour AS INTEGER NO-UNDO INITIAL 3600000. dtTime = NOW + (24 * iHour). MESSAGE "A day later: " dtTime VIEW-AS ALERT-BOX.

Notes

To add a specific number of days and a specific number of milliseconds to a DATETIME, use the DATETIME function. For example:

new-datetime = DATETIME( DATE(old-datetime) + days, MTIME(old-datetime) + milliseconds ).

The DATETIME function ensures that the time portion remains within the valid range, by adding day(s) to the date part when the time part goes over the number of milliseconds in a day. To add a specific number of days and milliseconds to a DATETIME-TZ, use the DATETIME-TZ function. For example:

new-datetime-tz = DATETIME-TZ( DATE(old-datetime-tz) + days, MTIME (old-datetime-tz) + milliseconds, TIMEZONE(old-dateime-tz) ).

The DATETIME-TZ function ensures that the time portion remains within the valid range, by adding day(s) to the date portion when the time part goes over the number of milliseconds in a day. See also + Date addition operator, Datetime subtraction operator, ADD-INTERVAL function, DATETIME function, DATETIME-TZ function

27

Unary negative operator

Unary negative operatorReverses the sign of a numeric expression. Do not confuse this operator with the subtraction operator that subtracts one expression from another. Syntax- expression

expression

An expression whose value is numeric. Example If you supply a negative value for the variable fx, the r-uneg.p procedure uses the unary negative operator (-) to reverse the sign of fx, producing the absolute value of fx (fabs-x). r-uneg.pDEFINE VARIABLE fx AS DECIMAL NO-UNDO LABEL "X". DEFINE VARIABLE fabs-x AS DECIMAL NO-UNDO LABEL "ABS(X)". REPEAT: SET fx. IF fx < 0 THEN fabs-x = -fx. ELSE fabs-x = fx. DISPLAY fabs-x. END.

See also

+ Unary positive operator

Subtraction operatorSubtracts one numeric expression from another numeric expression. Syntaxexpression - expression

expression

An expression with a numeric value. Example The r-subt.p procedure determines the amount of inventory available by subtracting the amount allocated from the total on hand. r-subt.pDEFINE VARIABLE free-stock NO-UNDO LIKE on-hand LABEL "Free Stock". FOR EACH Item NO-LOCK: free-stock = Item.OnHand - Item.Allocated. DISPLAY Item.ItemNum Item.ItemName Item.OnHand Item.Allocated free-stock. END.

28

Date subtraction operator Note Subtracting one decimal expression from another produces a DECIMAL value. Subtracting one INTEGER expression from another produces an INTEGER. Subtracting an integer expression (INTEGER or INT64) from a decimal expression (or subtracting a decimal expression from an integer expression) produces a DECIMAL value. Subtracting a mix of INTEGER and INT64 expressions produces an INT64 value. + Addition operator

See also

Date subtraction operatorSubtracts a number of days from a date to produce a date result, or subtracts one date from another to produce an INTEGER result that represents the number of days between the two dates. Syntaxdate -

{

days

|

date

}

date

An expression that evaluates to a DATE value.days

An expression with a value of the number of days you want to subtract from date. Example This procedure finds all unshipped orders. If the promised date is more than one week ago, the procedure finds the customers who placed the order and displays the order and customer data. r-dsub.pDISPLAY "ORDERS SCHEDULED TO SHIP MORE THAN ONE WEEK LATE". FOR EACH Order NO-LOCK WHERE Order.ShipDate = ?: IF (TODAY - 7) > Order.PromiseDate THEN DISPLAY Order.OrderNum Order.CustNum Order.PromiseDate (TODAY - Order.PromiseDate) LABEL "Days Late". END.

See also

+ Date addition operator, Datetime subtraction operator, ADD-INTERVAL function, DATE function, INTERVAL function

Datetime subtraction operatorSubtracts a number of milliseconds from a DATETIME or a DATETIME-TZ to produce another DATETIME or DATETIME-TZ, or subtracts one DATETIME or DATETIME-TZ from another to produce an INT64 result in milliseconds. Syntaxdatetime -

{

milliseconds

|

datetime

}

29

Datetime subtraction operator

datetime-tz -

{

milliseconds

|

datetime-tz

}

datetime

An expression that evaluates to a DATETIME value.milliseconds

An expression that evaluates to an integer value specifying a number of milliseconds.datetime-tz

An expression that evaluates to a DATETIME-TZ value. Example This example returns the date and time exactly 24 hours ago (dtTime). It then recalculates the number of hours (iHours) from the number of milliseconds (iMsec) since then and displays the result:

DEFINE DEFINE DEFINE DEFINE

VARIABLE VARIABLE VARIABLE VARIABLE

dtTime iMsec iHour fHours

AS AS AS AS

DATETIME INT64 INTEGER DECIMAL

NO-UNDO. NO-UNDO. NO-UNDO INITIAL 3600000. NO-UNDO.

ASSIGN dtTime = NOW - (24 * iHour) iMsec = NOW - DATETIME-TZ(dtTime) fHours = iMsec / iHour. MESSAGE "A day earlier: " dtTime " " "Current hours since then: " fHours VIEW-AS ALERT-BOX.

Notes

To get the number of days between two DATETIME or DATETIME-TZ variable values, use the DATE function. For example:

num-days = DATE(dt2) - DATE(dt1)

This operation does not take the time portion into account. To ensure the correct result when working with two DATETIME-TZ values, convert one of the values to the time zone of the other. For example:

ASSIGN temp-dttz = dt1 TIMEZONE(temp-dttz) = TIMEZONE(dt2) num-days = DATE(dt2) DATE(temp-dttz).

To subtract a specific number of days and milliseconds from a DATETIME, use the DATETIME function. For example:

new-datetime = DATETIME( DATE(old-datetime) - days, MTIME (old-datetime) - milliseconds ).

30

* Multiplication operator The DATETIME function ensures the time portion remains within a valid range by borrowing a day from the date portion, when necessary. To subtract a specific number of days and milliseconds from a DATETIME-TZ, use the DATETIME-TZ function. For example:

new-datetime-tz = DATETIME-TZ( DATE(old-datetime-tz) - days, MTIME (old-datetime-tz) milliseconds, TIMEZONE(old-dateime-tz) ).

The DATETIME-TZ function ensures the time portion remains within a valid range by borrowing a day from the date portion, when necessary. See also Date subtraction operator, + Datetime addition operator, ADD-INTERVAL function, DATETIME function, DATETIME-TZ function, INTERVAL function

* Multiplication operatorMultiplies two numeric expressions. Syntaxexpression * expression

expression

An expression with a numeric value. Example This procedure computes the value of the on-hand inventory for each item. If the on-hand inventory is negative, the procedure sets the inventory value to 0. r-mult.pDEFINE VARIABLE inv-value AS DECIMAL NO-UNDO LABEL "VALUE". FOR EACH Item NO-LOCK: inv-value = Item.OnHand * Item.Price. IF inv-value < 0 THEN inv-value = 0. DISPLAY Item.ItemNum Item.ItemName Item.OnHand Item.Price inv-value. END.

Note

Multiplying two decimal expressions produces a DECIMAL value. Multiplying two INTEGER expressions produces an INTEGER value. Multiplying two INT64 expressions produces an INT64 value. Multiplying an integer expression (INTEGER or INT64) and a decimal expression produces a DECIMAL value. Multiplying an INTEGER expression and an INT64 expression produces an INT64 value. / Division operator

See also

31

/ Division operator

/ Division operatorDivides one numeric expression by another numeric expression, producing a decimal result. This is the case for both INTEGER and INT64 expressions. Syntaxexpression / expression

expression

An expression that evaluates to a numeric value. Example This procedure divides the number of items allocated by the number of items on hand, producing a decimal value. The multiplication operator (*) converts that decimal value to a percentage. r-div.pDISPLAY "INVENTORY COMMITMENTS AS A PERCENT OF UNITS ON HAND". FOR EACH Item NO-LOCK: DISPLAY Item.ItemNum Item.ItemName Item.Allocated Item.OnHand (Item.Allocated / Item.OnHand) * 100 FORMAT ">>9" LABEL "PCT". END.

Notes

ABL always performs division as a decimal operation (the product of 5 / 2 is 2.5, not 2). If you assign the result to an integer field, ABL rounds the decimal to make the assignment. When you want ABL to truncate a quotient to an integer, use the TRUNCATE function (TRUNCATE(5 / 2, 0) is 2). The result of dividing a number by 0 is the Unknown value (?), and the AVM does not display an error message.

See also

* Multiplication operator

ABSOLUTE functionReturns the absolute value of a numeric value. SyntaxABSOLUTE ( n )

n

An integer or decimal expression. The return value is the same format as n. Example This procedure calculates the number of miles you drive between highway exit ramps.

32

ACCUM function r-abs.pDEFINE VARIABLE mark-start AS DECIMAL NO-UNDO. DEFINE VARIABLE mark-finish AS DECIMAL NO-UNDO. DEFINE VARIABLE units AS LOGICAL NO-UNDO FORMAT "miles/kilometers". FORM mark-start LABEL "Mile marker for highway on-ramp" SKIP mark-finish LABEL "Mile marker next to your exit" SKIP(1) units LABEL "Measure in iles or ilometers" SKIP(1) WITH FRAME question SIDE-LABELS TITLE "This program calculates distance driven.". UPDATE mark-start mark-finish units WITH FRAME question. DISPLAY "You have driven" ABSOLUTE(mark-start - mark-finish) units WITH NO-LABELS FRAME answer.

ACCUM functionReturns the value of an aggregate expression that is calculated by an ACCUMULATE or aggregate phrase of a DISPLAY statement. SyntaxACCUM aggregate-phrase expression

aggregate-phrase

A phrase that identifies the aggregate value it should return. This is the syntax for aggregate-phrase: Syntax

{

AVERAGE

|

COUNT

|

MAXIMUM

|

MINIMUM

|

TOTAL

|

SUB-MAXIMUM

|

SUB-MINIMUM

|

SUB-TOTAL

| SUB-AVERAGE | SUB-COUNT } [ BY break-group ]

For more information on aggregate items, see the Aggregate phrase reference entry.expression

An expression that was used in an earlier ACCUMULATE or DISPLAY statement. The expression you use in the ACCUMULATE or DISPLAY statement and the expression you use in the ACCUM function must be in exactly the same form. (For example, on-hand * cost and cost * on-hand are not in exactly the same form.) For the AVERAGE, SUB-AVERAGE, TOTAL, and SUB-TOTAL aggregate phrases, expression must be numeric. Example This procedure shows a total for the extended price of each item on an order. The running total of the order is displayed as well as the order total and grand total for all orders. This procedure accumulates totals at three levels.

33

ACCUMULATE statement r-accum.pFOR EACH Order NO-LOCK: DISPLAY Order.OrderNum Order.CustNum Order.OrderDate Order.PromiseDate Order.ShipDate. FOR EACH OrderLine OF Order NO-UNDO: DISPLAY OrderLine.LineNum OrderLine.ItemNum OrderLine.Qty OrderLine.Price (OrderLine.Qty * OrderLine.Price) LABEL "Ext Price". ACCUMULATE OrderLine.Qty * OrderLine.Price (TOTAL). DISPLAY (ACCUM TOTAL OrderLine.Qty * OrderLine.Price) LABEL "Accum Total". END. DISPLAY (ACCUM TOTAL OrderLine.Qty * OrderLine.Price) LABEL "Total". END. DISPLAY (ACCUM TOTAL OrderLine.Qty * OrderLine.Price) LABEL "Grand Total" WITH ROW 1.

See also

ACCUMULATE statement, DISPLAY statement

ACCUMULATE statementCalculates one or more aggregate values of an expression during the iterations of a block. Use the ACCUM function to access the result of this accumulation. SyntaxACCUMULATE

{

expression ( aggregate-phrase )

} ...

expression

An expression for which you want to calculate the aggregate value. The expression you use in the ACCUMULATE statement and the expression you use in the ACCUM function (when using the result of the ACCUMULATE statement) must be in exactly the same form. (For example, A * B and B * A are not in exactly the same form.)aggregate-phrase

Identifies one or more values to calculate based on a change in expression or a break group. This is the syntax for aggregate-phrase: Syntax

{

| MINIMUM | TOTAL | SUB-AVERAGE | SUB-COUNT | SUB-MAXIMUM | SUB-MINIMUM | SUB-TOTAL } ... [ BY break-group ] ...AVERAGE COUNT MAXIMUM

|

|

For more information, see the Aggregate phrase reference entry. Examples This procedure calculates and displays statistics for all customers, but does not show the detail for each customer.

34

ACCUMULATE statement r-acmlt.pFOR EACH Customer NO-LOCK: ACCUMULATE Customer.CreditLimit (AVERAGE COUNT MAXIMUM). END. DISPLAY "MAX-CREDIT STATISTICS FOR ALL CUSTOMERS:" SKIP(2) "AVERAGE =" (ACCUM AVERAGE Customer.CreditLimit) SKIP(1) "MAXIMUM =" (ACCUM MAXIMUM Customer.CreditLimit) SKIP(1) "NUMBER OF CUSTOMERS =" (ACCUM COUNT Customer.CreditLimit) SKIP(1) WITH NO-LABELS.

The following procedure lists each item with its inventory value and lists that value as a percentage of the total inventory value of all items; it sorts items by highest value. r-acmlt2.pFOR EACH Item NO-LOCK: ACCUMULATE Item.OnHand * Item.Price (TOTAL). END. FOR EACH Item NO-LOCK BY Item.OnHand * Item.Price DESCENDING: DISPLAY Item.ItemNum Item.OnHand Item.Price Item.OnHand * Item.Price LABEL "Value" 100 * (Item.OnHand * Item.Price) / (ACCUM TOTAL Item.OnHand * Item.Price) LABEL "Value %". END.

The follo