Copyright: ©1994 Clarion Software
Citation: ©1994  Clarion Software


Clarion for Windows

   Language Reference

   Users Guide

   File Drivers

   New for Beta3

   Future Enhancements


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

The Language Reference Manual

Reference Item Format

Conventions and Symbols

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

Statement Format

Declaration and Statement Labels

Structure Termination

Reserved Words

Special Characters

Program Format

PROGRAM  (declare a program)

MEMBER  (identify member source file)

MAP  (declare PROCEDURE and/or FUNCTION prototypes)

MODULE  (specify MEMBER source file)

PROCEDURE  (declare a procedure)

FUNCTION  (declare a function)

CODE  (begin executable statements)

ROUTINE  (declare local subroutine)

END  (terminate a structure)

Statement Execution Sequence

PROCEDURE and FUNCTION Calls

Prototyping Procedures

FUNCTION and PROCEDURE Prototypes

FUNCTION Return Types

Parameter Passing

Passing Parameters of Unspecified Data Type

Passing Arrays as Parameters

Program Structure Compiler Directives

BEGIN  (define code structure)

COMPILE  (specify source to be compiled)

EJECT  (start new listing page)

EMBED  (embedded source code section)

INCLUDE  (compile code in another file)

OMIT  (specify source not to be compiled)

SECTION  (specify source code section)

SUBTITLE  (print MODULE subtitle)

TITLE  (print MODULE title)

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

Variable Declaration Statements

BYTE  (one-byte unsigned integer)

SHORT  (two-byte signed integer)

USHORT  (two-byte unsigned integer)

LONG  (four-byte signed integer)

ULONG  (four-byte unsigned integer)

SREAL  (four-byte signed floating point)

REAL  (eight-byte signed floating point)

BFLOAT4  (four-byte signed floating point)

BFLOAT8  (eight-byte signed floating point)

DECIMAL  (fixed-length signed packed decimal)

PDECIMAL  (fixed-length signed packed decimal)

STRING  (fixed-length string)

CSTRING  (fixed-length null terminated string)

PSTRING  (embedded length-byte string)

DATE  (four-byte date)

TIME  (four-byte time)

GROUP  (compound data structure)

LIKE  (user-defined data types)

Implicit Variables

Reference Variables

Attributes of Variables

PRE  (set group label prefix)

DIM  (set array dimensions)

EXTERNAL  (set variable defined externally)

NAME  (set variable's external name)

OVER  (set shared memory location)

STATIC  (set local variable static)

THREAD  (set thread-specific static variable)

BINDABLE  (set dynamic expression string variables)

Data Declarations amd Memory Allocation

Global, Local, Static, and Dynamic

Data Declaration Sections

Picture Tokens

Numeric and Currency Pictures

Scientific Notation Pictures

Date Pictures

Time Pictures

Pattern Pictures

Key-in Template Pictures

String Pictures

Compiler Directives

EQUATE  (assign label)

SIZE  (memory size in bytes)

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

Expressions

Expression Evaluation

Arithmetic Operators

Logical Operators

Numeric Constants

Numeric Expressions

String Constants

The Concatenation Operator

String Expressions

Logical Expressions

Runtime Expression Strings

BIND  (declare runtime expression string variable)

UNBIND  (free runtime expression string variable)

EVALUATE  (return runtime expression string result)

Assignment Statements

Simple Assignment Statements

Operating Assignment Statements

Deep Assignment Statements

Reference Assignment Statements

CLEAR  (clear a variable)

Data Structure Property Assignments

Property Expressions

Property Equates

Undeclared Properties

Data Conversion Rules

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

Control Structures

CASE  (conditional execution structure)

EXECUTE  (statement selection structure)

IF  (conditional execution structure)

LOOP  (iteration structure)

Control Statements

BREAK  (immediately leave loop)

CHAIN  (execute another program)

CYCLE  (go to top of loop)

DO  (call a ROUTINE)

EXIT  (leave a ROUTINE)

GOTO  (go to a label)

HALT  (exit program)

IDLE  (arm periodic procedure)

NOTIFY  (critical error handling)

RETURN  (return to caller)

RUN  (execute command)

STOP  (suspend program execution)

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

Clarion Windows

Window Overview

Control Fields and Input Focus

Field Equate Labels

Window Structures

APPLICATION  (declare an MDI frame window)

WINDOW  (declare a dialog window)

APPLICATION and WINDOW Attributes

ALRT  (set window "hot" keys)

AT  (set window position and size)

CENTER  (set position and size)

CURSOR  (set mouse cursor type)

DOUBLE, NOFRAME, RESIZE  (set window border)

FONT  (set window default font)

GRAY  (set 3-D look background)

HLP  (set window's on-line help identifier)

HSCROLL, VSCROLL, HVSCROLL  (set window scroll bars)

ICON  (set window icon)

ICONIZE  (set window open as icon)

MASK  (set pattern editing data entry)

MAX  (set maximize control)

MAXIMIZE  (set window open maximized)

MDI  (set Multiple Document Interface)

MODAL  (set system modal window)

MSG  (set window status bar message)

PALETTE  (set number of hardware colors)

STATUS  (set status bar)

SYSTEM  (set system menu)

THOUS, MM, POINTS  (set screen coordinate measure)

TOOLBOX  (set toolbox window behavior)

TIMER  (set periodic event)

MENUBAR and TOOLBAR Structures

MENUBAR  (declare a pulldown menu)

TOOLBAR  (declare a tool bar)

MENUBAR and TOOLBAR Attributes

CURSOR  (set toolbar mouse cursor type)

FONT  (set toolbar default font)

NOMERGE  (set merging behavior)

MENUBAR Controls

MENU  (declare a menu box)

ITEM  (declare a menu item)

TOOLBAR and WINDOW Control Fields

BOX  (declare a window box control)

BUTTON  (declare a pushbutton control)

CHECK  (declare a window checkbox control)

COMBO  (declare an entry/list control)

CUSTOM  (declare a window .VBX custom control)

ELLIPSE  (declare a window ellipse control)

ENTRY  (declare a data entry control)

GROUP  (declare a group of window controls)

IMAGE  (declare a window graphic image control)

LINE  (declare a window line control)

LIST  (declare a window list control)

OPTION  (declare a group of window RADIO controls)

PROMPT  (declare a prompt control)

RADIO  (declare a window radio button control)

REGION  (declare a window region control)

SPIN  (declare a spinning list control)

STRING  (declare a window string control)

TEXT  (declare a multi-line data entry control)

Control Field Attributes

ALRT  (set control "hot" keys)

AT  (set control position and size in window)

BOXED  (set window controls group border)

CAP, UPR  (set display case)

CHECK  (set on/off ITEM)

CLASS  (set .VBX custom control class)

COLOR  (set control display color)

COLUMN  (set list box highlight bar)

CURSOR  (set control mouse cursor type)

DEFAULT  (set enter key button)

DISABLE  (set control dimmed at open)

DROP  (set list box behavior)

DRAGID  (set drag-and-drop host signatures)

DROPID  (set drag-and-drop target signatures)

FILL  (set display fill color)

FIRST, LAST  (set MENU or ITEM position)

FONT  (set control font)

FORMAT  (set LIST or COMBO layout)

FROM  (set window listbox data source)

FULL  (set full-screen)

HIDE  (set control hidden at open)

HLP  (set control's on-line help identifier)

HSCROLL, VSCROLL, HVSCROLL  (set control scroll bars)

ICON  (set control icon)

IMM  (set immediate event notification)

INS, OVR  (set typing mode)

KEY  (set control execution keycode)

LEFT, RIGHT, CENTER, DECIMAL  (set display justification)

MARK  (set multiple selection mode)

MSG  (set control status bar message)

NOBAR  (set no highlight bar)

PASSWORD  (set data non-display)

RANGE  (set SPIN range limits)

READONLY  (set display-only)

REQ  (set required entry)

RIGHT  (set MENU position)

ROUND  (set round-cornered window BOX)

SCROLL  (set scrolling control)

SEPARATOR  (set separator line ITEM)

SKIP  (set Tab key skip)

STD  (set standard behavior)

STEP  (set SPIN increment)

TRN  (set transparent window string)

USE  (set control variable or equate label)

VCR  (set VCR control)

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

Event Processing

Event-driven programming

ACCEPT  (the event processor)

ALERT  (set event generation key)

EVENT  (return event number)

POST  (post user-defined event)

YIELD  (allow event processing)

Multi-Threaded Applications

Multi-Threading and MDI

Multi-Threading vs. Multi-Tasking

START  (return new execution thread)

THREAD  (return current execution thread)

Window Procedures

CHANGE  (change control field value)

CLOSE  (close window)

CREATE  (create new control)

DISABLE  (dim a control)

DISPLAY  (write USE variables to screen)

ENABLE  (re-activate dimmed control)

ERASE  (clear screen control and USE variables)

GETFONT  (get font information)

GETPOSITION  (get control position)

HELP  (help window access)

HIDE  (blank a control)

OPEN  (open window for processing)

SELECT  (select next control to process)

SET3DLOOK  (set 3D window look)

SETCURSOR  (set temporary mouse cursor)

SETFONT  (specify font)

SETPOSITION  (specify new control position)

SETTARGET  (set current window or report)

UNHIDE  (show hidden control)

UPDATE  (write from screen to USE variables)

Window Functions

ACCEPTED  (return control just completed)

CHOICE  (return relative item position)

CONTENTS  (return contents of USE variable)

FIELD  (return control with focus)

FIRSTFIELD  (return first window control)

FOCUS  (return control with focus)

INCOMPLETE  (return empty REQ control)

LASTFIELD  (return last window control)

MESSAGE  (return message box response)

MOUSEX  (return mouse horizontal position)

MOUSEY  (return mouse vertical position)

SELECTED  (return control that has received focus)

Keyboard Procedures

ASK  (get one keystroke)

PRESS  (put characters in the buffer)

PRESSKEY  (put a keystroke in the buffer)

SETKEYCODE  (specify keycode)

Keyboard Functions

KEYBOARD  (return keystroke waiting)

KEYCHAR  (return ASCII code)

KEYCODE  (return last keycode)

Windows Standard Dialog Functions

COLORDIALOG  (return chosen color)

FILEDIALOG  (return chosen file)

FONTDIALOG  (return chosen font)

PRINTERDIALOG  (return chosen printer)

Drag and Drop Processing

CLIPBOARD  (return windows clipboard contents)

DRAGID  (return matching drag-and-drop signature)

DROPID  (return drag-and-drop string)

SETCLIPBOARD  (set windows clipboard contents)

SETDROPID  (set DROPID return string)

Maintaining INI Files

GETINI  (return INI file entry)

PUTINI  (set INI file entry)

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

Reports in Windows

Page Overflow

Report Structure

REPORT  (declare a report structure)

AT  (set detail print area)

FONT  (set report default font)

PRE  (set report label prefix)

PREVIEW  (set report output to metafiles)

LANDSCAPE  (set page orientation)

THOUS, MM, POINTS  (set report coordinate measure)

Print Structures

BREAK  (declare group break structure)

DETAIL  (report detail line structure)

FOOTER  (page or group footer structure)

FORM  (page layout structure)

HEADER  (page or group header structure)

Print Structure Attributes

ABSOLUTE  (set fixed-position printing)

ALONE  (set to print without page header, footer, or form)

AT  (set print structure position and size)

FONT  (set print structure default font)

PAGEAFTER  (set page break after)

PAGEBEFORE  (set page break first)

USE  (set structure equate label)

WITHNEXT  (set widow elimination)

WITHPRIOR  (set orphan elimination)

Report Controls

BOX  (declare a report box control)

CHECK  (declare a report checkbox control)

CUSTOM  (declare a report .VBX custom control)

ELLIPSE  (declare a report ellipse control)

GROUP  (declare a group of report controls)

IMAGE  (declare a report graphic image control)

LINE  (declare a report line control)

LIST  (declare a report list control)

OPTION  (declare a group of report RADIO controls)

RADIO  (declare a report radio button control)

STRING  (declare a report string control)

TEXT  (declare a multi-line text control)

Control Attributes

AT  (set control position and size in report)

AVE  (set total average)

BOXED  (set report controls group border)

CAP, UPR  (set print case)

CNT  (set total count)

COLOR  (set color)

FILL  (set print fill color)

FONT  (set default font)

FORMAT  (set LIST print format)

FROM  (set report listbox data source)

HIDE  (set control non-print)

LEFT, RIGHT, CENTER, DECIMAL  (set print justification)

MAX  (set total maximum)

META  (set .VBX to print as .WMF)

MIN  (set total minimum)

PAGE  (set page total reset)

PAGENO  (set page number print)

RESET  (set total reset)

ROUND  (set round-cornered report BOX)

SUM  (set total)

TRN  (set transparent report string)

USE  (set code reference name)

Report Procedures

CLOSE  (close an active report structure)

ENDPAGE  (force page overflow)

OPEN  (open a report structure for processing)

PRINT  (print a report structure)

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

Graphics Overview

The Current Target

Graphics Coordinates

Graphics Procedures

ARC  (draw an arc of an ellipse)

BLANK  (erase graphics)

BOX  (draw a rectangle)

CHORD  (draw a section of an ellipse)

ELLIPSE  (draw an ellipse)

IMAGE  (draw a graphic image)

LINE  (draw a straight line)

PIE  (draw a pie chart)

POLYGON  (draw a multi-sided figure)

ROUNDBOX  (draw a box with round corners)

SETPENCOLOR  (set line draw color)

SETPENSTYLE  (set line draw style)

SETPENWIDTH  (set line draw thickness)

SHOW  (write to screen)

TYPE  (write string to screen)

Graphics Functions

PENCOLOR  (return line draw color)

PENSTYLE  (return line draw style)

PENWIDTH  (return line draw thickness)

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

Data File Structures

FILE  (declare a data file structure)

CREATE  (allow data file creation)

DRIVER  (specify data file type)

NAME  (set filename)

ENCRYPT  (encrypt data file)

OWNER  (declare password for data encryption)

RECLAIM  (reuse deleted record space)

PRE  (set file label prefix)

BINDABLE  (set runtime expression string RECORD variables)

File Structure Statements

INDEX  (declare static file access index)

KEY  (declare dynamic file access index)

MEMO  (declare a text field)

RECORD  (declare record structure)

INDEX, KEY and MEMO Attributes

BINARY  (MEMO contains binary data)

DUP  (allow duplicate KEY entries)

NOCASE  (case insensitive KEY or INDEX)

OPT  (exclude null KEY or INDEX entries)

NAME  (set external key name)

File Commands

BUILD  (build keys and indexes)

CLOSE  (close a data file)

COPY  (copy a data file)

CREATE  (create an empty data file)

EMPTY  (empty a data file)

FLUSH  (flush DOS buffers)

LOCK  (exclusive file access)

OPEN  (open a data file)

PACK  (remove deleted records)

REMOVE  (erase the data file)

RENAME  (change data file directory name)

SHARE  (open a data file)

STREAM  (enable DOS buffering)

UNLOCK  (unlock a locked data file)

Record Access Commands

ADD  (add a new file record)

APPEND  (add a new file record)

DELETE  (delete a file record)

GET  (read a file record by direct access)

HOLD  (exclusive file record access)

NEXT  (read next file record in sequence)

NOMEMO  (read file record without reading memo)

PREVIOUS  (read previous file record in sequence)

PUT  (write record back to file)

RELEASE  (release a held file record)

REGET  (reget file record)

RESET  (reset file record sequence position)

SET  (initiate sequential file processing)

SKIP  (bypass file records in sequence)

WATCH  (automatic file concurrency check)

File Functions

BOF  (beginning of file function)

BYTES  (return size in bytes)

DUPLICATE  (check for duplicate file key entries)

EOF  (end of file function)

POINTER  (return relative record position)

POSITION  (return file record sequence position)

RECORDS  (return number of file or key records)

SEND  (send message to file driver)

Transaction Processing

COMMIT  (terminate successful transaction)

LOGOUT  (begin transaction)

ROLLBACK  (terminate unsuccessful transaction)

Null Data Processing

NULL  (return null file field)

SETNULL  (set file field null)

SETNONNULL  (set file field non-null)

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

View Structures

VIEW  (declare a "virtual" file)

PRE  (set view label prefix)

FILTER  (set view filter expression)

BINDABLE  (set runtime expression string variables)

FROM  (set field data origination)

JOIN  (declare a "join" operation)

View Commands

CLOSE  (close a VIEW)

OPEN  (open a VIEW)

SHARE  (open a VIEW)

View Access Commands

ADD  (add a new view record)

APPEND  (add a new view record)

DELETE  (delete a view record)

GET  (read a view record by direct access)

HOLD  (exclusive view record access)

LOAD  (load view from current primary record)

NEXT  (read next view record in sequence)

NOMEMO  (read view record without reading memo)

PREVIOUS  (read previous view record in sequence)

PUT  (write record back to VIEW)

RELEASE  (release a held view record)

REGET  (reget view record)

RESET  (reset view record sequence position)

SET  (initiate sequential VIEW processing)

SKIP  (bypass view records in sequence)

WATCH  (automatic view concurrency check)

View Functions

DUPLICATE  (check for duplicate key entries)

POSITION  (return view record sequence position)

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

Queue Structure

QUEUE  (declare a memory QUEUE structure)

PRE  (set label prefix)

STATIC  (set local queue static)

THREAD  (set thread-specific static queue)

NAME  (set external queue name)

Queue Procedures

ADD  (add an entry)

DELETE  (delete an entry)

FREE  (delete all entries)

GET  (read an entry)

PUT  (write an entry)

SORT  (sort entries)

Queue Functions

POINTER  (return last entry position)

RECORDS  (return number of entries)

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

Mathematical Functions

ABS  (return absolute value)

INRANGE  (check number within range)

INT  (truncate fraction)

LOGE  (return natural logarithm)

LOG10  (return base 10 logarithm)

RANDOM  (return random number)

ROUND  (return rounded number)

SQRT  (return square root)

Trigonometric Functions

SIN  (return sine)

COS  (return cosine)

TAN  (return tangent)

ASIN  (return arcsine)

ACOS  (return arccosine)

ATAN  (return arctangent)

String Functions

ALL  (return repeated characters)

CENTER  (return centered string)

CHR  (return character from ASCII)

CLIP  (return string without trailing spaces)

DEFORMAT  (remove formatting from numeric string)

FORMAT  (format numbers into a picture)

INLIST  (search for entry in list)

INSTRING  (search for substring)

LEFT  (return left justified string)

LEN  (return length of string)

LOWER  (return lower case)

NUMERIC  (check numeric string)

RIGHT  (return right justified string)

SUB  (return substring of string)

UPPER  (return upper case)

VAL  (return ASCII value)

Bit Manipulation Functions

BAND  (return bitwise AND)

BOR  (return bitwise OR)

BXOR  (return bitwise exclusive OR)

BSHIFT  (return shifted bits)

Date / Time Procedures and Functions

Standard Date

Standard Time

TODAY  (return system date)

SETTODAY  (set system date)

CLOCK  (return system time)

SETCLOCK  (set system time)

DATE  (return standard date)

DAY  (return day of month)

MONTH  (return month of date)

YEAR  (return year of date)

AGE  (return age from base date)

Dos Procedures and Functions

COMMAND  (return command line)

MEMORY  (return available memory)

PATH  (return current DOS directory)

RUNCODE  (return DOS exit code)

SETCOMMAND  (set command line parameters)

SETPATH  (change current drive and directory)

Other Miscellaneous Procedures and Functions

ADDRESS  (return a memory address)

BEEP  (sound tone on speaker)

ERROR  (return error message)

ERRORCODE  (return error code number)

ERRORFILE  (return error filename)

FILEERROR  (return file driver error message)

FILEERRORCODE  (return file driver error code number)

MAXIMUM  (return maximum subscript value)

NAME  (return DOS file or device name)

OMITTED  (check omitted parameters)

 DDE Library Reference

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 Memory Queues

 DDE Library Reference

Dynamic Data Exchange

Overview

DDE Events

DDE Functions

DDESERVER  (return DDE server channel)

DDECLIENT  (return DDE client channel)

DDEQUERY  (return registered DDE servers)

DDECHANNEL  (return DDE channel number)

DDEAPP  (return server application)

DDEITEM  (return server item)

DDETOPIC  (return server topic)

DDE Procedures

DDEREAD  (get data from DDE server)

DDEWRITE  (provide data to DDE client)

DDEEXECUTE  (send command to DDE server)

DDECLOSE  (terminate DDE server link)

 Keycodes


Language Reference

 Introduction

 Program Source Code Format

 Declaring Variables

 Expressions and Assignments

 Control Statements

 Window Structures

 Window Commands

 Reports

 Graphics Commands

 Data Files

 File Views

 Memory Queues

 Miscellaneous Procedures and Functions

 DDE Library Reference

 Keycodes

Clarion Keycodes

Windows Keycode Mapping Format

KEYCODES.CLW


USER'S GUIDE
Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

Introduction

Welcome to the Clarion IDE

What Youll Find in this Reference

Where to Look for Other Information

Documentation Conventions

Typeface Conventions:

Keyboard Conventions:

Product Registration

Technical Support

Clarion FaxBack System

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

Application Development Flow

Clarion Programming

Template Driven

A Walk Through the IDEs Functional Parts

The Data Dictionary

The Application Generator

The Window Formatter

The Report Formatter

The Text Editor

The Expression Generator

The Project System

The Debugger

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

Using the Data Dictionary

What a Data Dictionary Is

Overview: Creating a Data Dictionary

Designing Your Database

Normalization

Keys

Relational Operations

Clarion

Opening the Dictionary Editor

Adding Files to the Dictionary

New File Properties

Adding File Aliases to the Dictionary

Adding a File View to the Dictionary

Adding  or Modifying Fields

Field Properties

Validity Checks

Screen Controls

Report Controls

Adding or Modifying Keys

New Key Properties

Key Components

Adding or Modifying Relations

Referential Integrity Constraints

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

Using the Application Generator

Creating the .APP File

Overview: Creating Your Application

Specifying Global Settings

Global Data Variables

.INI File Support

Other Global Settings

Adding a Procedure To Your Application

Defining the Procedure Type

The Procedure Properties Dialog

Adding a File Schematic

Adding Data

Adding Embedded Source Code

Adding Expressions...

Maintaining the Application Tree

Using the Edit Menu Commands

Using the View Menu Commands

Setting Template Registry Options

Maintaining Your Templates

Opening the Registry

Registry Maintenance

Customizing Procedure Templates

Adding WINDOWs or REPORTs

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

Procedures &Code Templates

Procedure Templates

Adding a Browse Procedure

Adding an External Procedure

Adding a Form Procedure

Adding an Application Frame

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

Using the Window Formatter

Overview: Creating Your Applications Windows

Opening the Window Formatter from the Editor

Choosing a Window Type

Window

Window with OK & Cancel

System Modal

MDI Child

MDI Parent Frame

To Customize Your Applications Windows

Using The Window Properties Dialog

Title

Label

Frame Type

Initial Size

Options

Position

Font

Setting More >>> Window Properties

Icon

Cursor

Help ID

Status Widths

Message

Alert

Timer

Entry Patterns

To Place Controls In a Window

Toolbox

Using the File Menu

VBX Registry

Exit

Using the Edit Menu

Undo

Redo

Properties...

Delete

Duplicate

Set Order

Using the Control Menu

Using the Alignment Menu

Using the Menu Menu

Using the Toolbar Menu

Using the Options Menu

Test

Show Toolbox

Show Alignbox

Grid Settings

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

Creating Menus and Toolbars

Calling the Menu Editor

Creating Your Apps Menu

First Command

Adding Commands

Add a Menu

Final Steps

Menu Editor Commands and Options

Menu

Item

Separator

Delete

Name

Use

MSG

Stdid

Flags

Position Options

Creating MDI Menus

Adding a Toolbar

First Button

Button Group

Final Steps

MDI Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

Setting Control Properties

Overview: Types of Controls

Setting Common Control Attributes

USE( )

AT( )

KEY( )

ALRT( )

FONT( )

Button or Action Controls

Push Button

Option Buttons

Choice Controls

Radio Buttons

Check Box

List Box

Combo Box

Spin Box

Entry Controls

Entry Box

Text

Static Controls

String

Variable String

Prompt

Group Box

Ellipse

Image (Icon)

Box

Region

Line

Custom Control Properties

Registering Your .VBX Custom Control Libraries

Adding a Custom Control to a Window

Setting and Retrieving Visual Basic Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

Using the Report Formatter

Overview: Report Processing

Smart Processing

Order

Flexibility

Report Preparation

Opening the Report Formatter

The Database

An Overview of the Report Formatter

Page Oriented Printing

Band View

REPORT Structures

Variable String Controls

Total Fields

Graphics

Page Layout and Preview

Designing Your Report

Design Basics

Margins

Report Types

Positioning And Alignment

Placing Structures

Header

Footer

Detail

Form

Group Breaks

Page Breaks

PAGEAFTER

PAGEBEFORE

WITHNEXT

WITHPRIOR

Adding Text Labels and Fields

Strings

Variable Strings

Multi-Line Text

Adding Graphic Controls

Images

Line

Box

Ellipse

Adding Specialized Controls

List

Option

Radio

Check

Group

Custom

Adding Graphs

Graph .VBX

Sample Report Designs

Miscellaneous Report Design Tips

Arranging Controls

Arranging Groups

Adding Default Report Structures

TXT Files

Print Preview

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

Using the Text Editor

Opening the Editor

Managing Source Code Windows

Using the Edit Menu

Undo

Cut

Copy

Paste

Select All

Goto Line

Goto Next Error

Goto Previous Error

Set Tabstop

Set Right Margin

Reformat Paragraph

Format Structure

Extended Functions

Using The Search Menu

Repeat Last Find

Repeat Backwards

Find Marked Text

Customizing the Editor

Line Formatting Options

Tabs

Block Replace

Remove Block

Colors

Editing Errors

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

Using the Project System

A Simple Project File Walkthrough

Project File Procedures

Adding Source Code Files

Adding Standard Libraries

Adding External Resources

Adding Other Projects

Setting the Target File

.EXE Files and CDDWRUN.DLL

.LIB Files

.DLL Files

Setting Project File Options

Project Global Options

Object File Compile Options

Target File Link Options

Editing the Redirection File

Project System Menu Commands

The Project Menu

Other IDE Commands

Calling the Windows API

 Using the Debugger

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

Using the Debugger

Preparing Your Projects for Debugging

Starting the Debugger

Launching

Loading the Source File(s)

Overview: The Debugger Windows

Default Windows

Other Windows

Setting Breakpoints

Unconditional Breakpoints

Conditional Breakpoints

Go!

Working with Source Code

Editing Watch Expressions

Editing Variables

Setting Debugger Options

Debugger Setup Options

Additional Debugger Commands

 Windows Design

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

Windows Design

Overview: Windows Design

Design Principles

User Control

Event Driven Programming

Windows and Window Elements

Application Window

MDI

Dialog Boxes

Buttons

Check Boxes

Radio Buttons

List Boxes

Combo Boxes

Drop-Down Boxes

Text Boxes

Spin Boxes

Static Text

Group Boxes

Control Labels

Cursors

Menus

File Menu

Edit Menu

Help Menu

View Menu

Window Menu

Accelerator Keys

Color

 Setting List Properties


Users Guide

 Introduction

 Application Development Flow

 Using the Data Dictionary

 Using the Application Generator

 Procedures &Code Templates

 Using the Window Formatter

 Creating Menus and Toolbars

 Setting Control Properties

 Using the Report Formatter

 Using the Text Editor

 Using the Project System

 Using the Debugger

 Windows Design

 Setting List Properties

Setting List Properties

Setting Listbox Item Properties

Setting Listbox Column Properties


New Features for Beta3
New for Beta 3

•	The most important addition to Clarion for  Windows Beta 3 is the Application Generator. The Application Generator can now create complete applications using the preliminary templates we've included. .

•	Beta 3 also introduces Code Templates. You can use the Code Templates to automatically add executable code at embedded source code points. A dialog box prompts you with entry fields and lists, then creates the code for you. This could be the end of hand-coding as we know it!

•	We've included the new TopSpeed file driver. This driver reads and writes our new proprietary file format very, very fast. We're not ready to release benchmarks yet, but we think you'll be impressed. The Topspeed driver can store multiple data files, keys and indexes in the same DOS file -- allowing you to open multiple files using a single DOS file handle.

•	Almost all the connections between parts of the IDE are now functional. For example, when you specify a picture for a field with the data dictionary, the Application Generator automatically adds the correct attributes for the controls you place in dialog boxes while using the Window Formatter.

•	The User's Guide includes an illustration showing the connections between IDE components. See the "Application Development Flowchart" on page 19. That chapter provides a brief "walkthrough" outlining the steps for creating an application. The User's Guide is all new, and represents a new "Task-Oriented" approach to Clarion documentation.

•	The on-line help includes the entire Clarion for Windows Language Reference, and the text of the User's Guide. We've provided a hard copy of the Table of Contents for the Language Reference, to make finding what you need easier.

Clarion for Windows Language Changes

Clarion for Windows Beta-2 to Beta-3 Language Changes


Clarion for Windows Beta-2 to Beta-3 Language Changes

For those of you who have previously received the Beta-1 or Beta-2 releases, many changes have been made to the Clarion for Windows language between the second and third Beta releases.

The following language statements have been removed between Beta-2 and Beta-3:

Beta-2 Name	Reason

SETMESSAGETEXT	Replaced (see Data Structure Property Assignments).

SETSTATUSBAR	Replaced (see Data Structure Property Assignments).

MESSAGETEXT	Replaced (see Data Structure Property Assignments).

LOCK	Does not apply to VIEW (still valid for FILE).

UNLOCK	Does not apply to VIEW (still valid for FILE).

The following language statements or attributes have been added between Beta-2 and Beta-3:

WINDOW Attributes

PALETTE

TOOLBOX

LIST or REGION Attribute

DRAGID

Attribute for most window controls

DROPID

Window Functions & Procedures

POST

YIELD

THREAD

MESSAGE

CLIPBOARD

DRAGID

DROPID

SETCLIPBOARD

SETDROPID

GETINI

PUTINI

Report Custom control attribute

META

View Procedure

LOAD

File Driver Error Functions

FILEERROR

FILEERRORCODE

DDE Functions & Procedures

DDESERVER

DDECLIENT

DDEQUERY

DDECHANNEL

DDEAPP

DDEITEM

DDETOPIC

DDEREAD

DDEWRITE

DDEEXECUTE

DDECLOSE


Clarion for Windows Language Changes

For those of you who have not previously received the Beta-1 or Beta-2 releases, there are many fundamental differences in the Clarion for Windows language of which you should be aware.  These are statements that have changed from CDD version 3, or have been added to the language.  The following is a list of items, by their section in the Language Reference (available in on-line Help), that you should see:

Program Source Code Format

FUNCTION

Declaring Variables

Variable Declaration Statements:

CSTRING

PSTRING

STRING

Reference Variables

Attributes of Variables:

OVER

THREAD

BINDABLE

Expressions

Runtime Expression Strings:

BIND

UNBIND

EVALUATE

Assignment Statements

Deep Assignment Statements

Reference Assignment Statements

Window Structures 	(The entire chapter)

Window Structures

Window Commands	(The entire chapter)

Window Commands

Reports	(The entire chapter)

Reports

Graphics Commands	(The entire chapter)

Graphics Commands

Data Files

Data File Structures

BINDABLE

Record Access Commands:

REGET

WATCH

File Views	(The entire chapter)

File Views

Memory Queues

QUEUE

STATIC

THREAD

Miscellaneous Procedures and Functions

FILEERROR

FILEERRORCODE

DDE LIbrary Reference 	(The entire chapter)

DDE Library Reference


Syntax

ABS  (return absolute value)

ACCEPT  (the event processor)

ACCEPTED  (return control just completed)

ACOS  (return arccosine)

ADD  (add a new file record)

ADD  (add a new view record)

ADD  (add an entry)

ADDRESS  (return a memory address)

AGE  (return age from base date)

ALERT  (set event generation key)

ALL  (return repeated characters)

APPEND  (add a new file record)

APPEND  (add a new view record)

ARC  (draw an arc of an ellipse)

ASIN  (return arcsine)

ASK  (get one keystroke)

Assignment Statements

ATAN  (return arctangent)

BAND  (return bitwise AND)

BEEP  (sound tone on speaker)

BEGIN  (define code structure)

BIND  (declare runtime expression string variable)

BLANK  (erase graphics)

BOF  (beginning of file function)

BOR  (return bitwise OR)

BOX  (draw a rectangle)

BREAK  (immediately leave loop)

BSHIFT  (return shifted bits)

BUILD  (build keys and indexes)

BXOR  (return bitwise exclusive OR)

BYTES  (return size in bytes)

CASE  (conditional execution structure)

CENTER  (return centered string)

CHAIN  (execute another program)

CHANGE  (change control field value)

CHOICE  (return relative item position)

CHORD  (draw a section of an ellipse)

CHR  (return character from ASCII)

CLIP  (return string without trailing spaces)

CLIPBOARD  (return windows clipboard contents)

CLOCK  (return system time)

CLOSE  (close a data file)

CLOSE  (close a VIEW)

CLOSE  (close an active report structure)

CLOSE  (close window)

CODE  (begin executable statements)

COLORDIALOG  (return chosen color)

COMMAND  (return command line)

COMMIT  (terminate successful transaction)

COMPILE  (specify source to be compiled)

CONTENTS  (return contents of USE variable)

COPY  (copy a data file)

COS  (return cosine)

CREATE  (create an empty data file)

CREATE  (create new control)

CYCLE  (go to top of loop)

DATE  (return standard date)

DAY  (return day of month)

DDEAPP  (return server application)

DDECHANNEL  (return DDE channel number)

DDECLIENT  (return DDE client channel)

DDECLOSE  (terminate DDE server link)

DDEEXECUTE  (send command to DDE server)

DDEITEM  (return server item)

DDEQUERY  (return registered DDE servers)

DDEREAD  (get data from DDE server)

DDESERVER  (return DDE server channel)

DDETOPIC  (return server topic)

DDEWRITE  (provide data to DDE client)

DEFORMAT  (remove formatting from numeric string)

DELETE  (delete a file record)

DELETE  (delete a view record)

DELETE  (delete an entry)

DISABLE  (dim a control)

DISPLAY  (write USE variables to screen)

DO  (call a ROUTINE)

DRAGID  (return matching drag-and-drop signature)

DROPID  (return drag-and-drop string)

DUPLICATE  (check for duplicate key entries)

DUPLICATE  (check for duplicate key entries)

EJECT  (start new listing page)

ELLIPSE  (draw an ellipse)

EMBED  (embedded source code section)

EMPTY  (empty a data file)

ENABLE  (re-activate dimmed control)

END  (terminate a structure)

ENDPAGE  (force page overflow)

EOF  (end of file function)

ERASE  (clear screen control and USE variables)

ERROR  (return error message)

ERRORCODE  (return error code number)

ERRORFILE  (return error filename)

EVALUATE  (return runtime expression string result)

EVENT  (return event number)

EXECUTE  (statement selection structure)

EXIT  (leave a ROUTINE)

FIELD  (return control with focus)

FILEDIALOG  (return chosen file)

FILEERROR  (return file driver error message)

FILEERRORCODE  (return file driver error code number)

FIRSTFIELD  (return first window control)

FLUSH  (flush DOS buffers)

FOCUS  (return control with focus)

FONTDIALOG  (return chosen font)

FORMAT  (format numbers into a picture)

FREE  (delete all entries)

FUNCTION  (declare a function)

GET  (read a file record by direct access)

GET  (read a view record by direct access)

GET  (read an entry)

GETFONT  (get font information)

GETINI  (return INI file entry)

GETPOSITION  (get control position)

GOTO  (go to a label)

HALT  (exit program)

HELP  (help window access)

HIDE  (blank a control)

HOLD  (exclusive file record access)

HOLD  (exclusive view record access)

IDLE  (arm periodic procedure)

IF  (conditional execution structure)

IMAGE  (draw a graphic image)

INCLUDE  (compile code in another file)

INCOMPLETE  (return empty REQ control)

INLIST  (search for entry in list)

INRANGE  (check number within range)

INSTRING  (search for substring)

INT  (truncate fraction)

KEYBOARD  (return keystroke waiting)

KEYCHAR  (return ASCII code)

KEYCODE  (return last keycode)

LASTFIELD  (return last window control)

LEFT  (return left justified string)

LEN  (return length of string)

LINE  (draw a straight line)

LOAD  (load view from current primary record)

LOCK  (exclusive file access)

LOG10  (return base 10 logarithm)

LOGE  (return natural logarithm)

LOGOUT  (begin transaction)

LOOP  (iteration structure)

LOWER  (return lower case)

MAP  (declare PROCEDURE and/or FUNCTION prototypes)

MAXIMUM  (return maximum subscript value)

MEMBER  (identify member source file)

MEMORY  (return available memory)

MESSAGE  (return message box response)

MODULE  (specify MEMBER source file)

MONTH  (return month of date)

MOUSEX  (return mouse horizontal position)

MOUSEY  (return mouse vertical position)

NAME  (return DOS file or device name)

NEXT  (read next file record in sequence)

NEXT  (read next view record in sequence)

NOMEMO  (read file record without reading memo)

NOMEMO  (read view record without reading memo)

NOTIFY  (critical error handling)

NULL  (return null file field)

NUMERIC  (check numeric string)

OMIT  (specify source not to be compiled)

OMITTED  (check omitted parameters)

OPEN  (open a data file)

OPEN  (open a report structure for processing)

OPEN  (open a VIEW)

OPEN  (open window for processing)

PACK  (remove deleted records)

PATH  (return current DOS directory)

PENCOLOR  (return line draw color)

PENSTYLE  (return line draw style)

PENWIDTH  (return line draw thickness)

PIE  (draw a pie chart)

POINTER  (return last entry position)

POINTER  (return relative record position)

POLYGON  (draw a multi-sided figure)

POSITION  (return file record sequence position)

POSITION  (return view record sequence position)

POST  (post user-defined event)

PRESS  (put characters in the buffer)

PRESSKEY  (put a keystroke in the buffer)

PREVIOUS  (read previous file record in sequence)

PREVIOUS  (read previous view record in sequence)

PRINT  (print a report structure)

PRINTERDIALOG  (return chosen printer)

PROCEDURE  (declare a procedure)

PROGRAM  (declare a program)

PUT  (write an entry)

PUT  (write record back to file)

PUT  (write record back to VIEW)

PUTINI  (set INI file entry)

RANDOM  (return random number)

RECORDS  (return number of entries)

RECORDS  (return number of file or key records)

REGET  (reget file record)

REGET  (reget view record)

RELEASE  (release a held file record)

RELEASE  (release a held view record)

REMOVE  (erase the data file)

RENAME  (change data file directory name)

RESET  (reset file record sequence position)

RESET  (reset view record sequence position)

RETURN  (return to caller)

RIGHT  (return right justified string)

ROLLBACK  (terminate unsuccessful transaction)

ROUND  (return rounded number)

ROUNDBOX  (draw a box with round corners)

ROUTINE  (declare local subroutine)

RUN  (execute command)

RUNCODE  (return DOS exit code)

SECTION  (specify source code section)

SELECT  (select next control to process)

SELECTED  (return control that has received focus)

SEND  (send message to file driver)

SET  (initiate sequential file processing)

SET  (initiate sequential VIEW processing)

SET3DLOOK  (set 3D window look)

SETCLIPBOARD  (set windows clipboard contents)

SETCLOCK  (set system time)

SETCOMMAND  (set command line parameters)

SETCURSOR  (set temporary mouse cursor)

SETDROPID  (set DROPID return string)

SETFONT  (specify font)

SETKEYCODE  (specify keycode)

SETNONNULL  (set file field non-null)

SETNULL  (set file field null)

SETPATH  (change current drive and directory)

SETPENCOLOR  (set line draw color)

SETPENSTYLE  (set line draw style)

SETPENWIDTH  (set line draw thickness)

SETPOSITION  (specify new control position)

SETTARGET  (set current window or report)

SETTODAY  (set system date)

SHARE  (open a data file)

SHARE  (open a VIEW)

SHOW  (write to screen)

SIN  (return sine)

SKIP  (bypass file records in sequence)

SKIP  (bypass view records in sequence)

SORT  (sort entries)

SQRT  (return square root)

START  (return new execution thread)

STOP  (suspend program execution)

STREAM  (enable DOS buffering)

SUB  (return substring of string)

SUBTITLE  (print MODULE subtitle)

TAN  (return tangent)

THREAD  (return current execution thread)

TITLE  (print MODULE title)

TODAY  (return system date)

TYPE  (write string to screen)

UNBIND  (free runtime expression string variable)

UNHIDE  (show hidden control)

UNLOCK  (unlock a locked data file)

UPDATE  (write from screen to USE variables)

UPPER  (return upper case)

VAL  (return ASCII value)

WATCH  (automatic file concurrency check)

WATCH  (automatic view concurrency check)

YEAR  (return year of date)

YIELD  (allow event processing)


Data Attributes

ABSOLUTE  (set fixed-position printing)

ALONE  (set to print without page header, footer, or form)

ALRT  (set control "hot" keys)

ALRT  (set window "hot" keys)

APPLICATION  (declare an MDI frame window)

AT  (set control position and size in report)

AT  (set control position and size in window)

AT  (set detail print area)

AT  (set print structure position and size)

AT  (set window position and size)

AVE  (set total average)

BFLOAT4  (four-byte signed floating point)

BFLOAT8  (eight-byte signed floating point)

BINARY  (MEMO contains binary data)

BINDABLE  (set dynamic expression string variables)

BINDABLE  (set runtime expression string RECORD variables)

BINDABLE  (set runtime expression string variables)

BOX  (declare a report box control)

BOX  (declare a window box control)

BOXED  (set report controls group border)

BOXED  (set window controls group border)

BREAK  (declare group break structure)

BUTTON  (declare a pushbutton control)

BYTE  (one-byte unsigned integer)

CAP, UPR  (set display case)

CAP, UPR  (set print case)

CENTER  (set position and size)

CHECK  (declare a report checkbox control)

CHECK  (declare a window checkbox control)

CHECK  (set on/off ITEM)

CLASS  (set .VBX custom control class)

CNT  (set total count)

COLOR  (set color)

COLOR  (set control display color)

COLUMN  (set list box highlight bar)

COMBO  (declare an entry/list control)

CREATE  (allow data file creation)

CSTRING  (fixed-length null terminated string)

CURSOR  (set control mouse cursor type)

CURSOR  (set mouse cursor type)

CURSOR  (set toolbar mouse cursor type)

CUSTOM  (declare a report .VBX custom control)

CUSTOM  (declare a window .VBX custom control)

DATE  (four-byte date)

DECIMAL  (fixed-length signed packed decimal)

DEFAULT  (set enter key button)

DETAIL  (report detail line structure)

DIM  (set array dimensions)

DISABLE  (set control dimmed at open)

DOUBLE, NOFRAME, RESIZE  (set window border)

DRAGID  (set drag-and-drop host signatures)

DRIVER  (specify data file type)

DROP  (set list box behavior)

DROPID  (set drag-and-drop target signatures)

DUP  (allow duplicate KEY entries)

ELLIPSE  (declare a report ellipse control)

ELLIPSE  (declare a window ellipse control)

ENCRYPT  (encrypt data file)

ENTRY  (declare a data entry control)

EQUATE  (assign label)

EXTERNAL  (set variable defined externally)

FILE  (declare a data file structure)

FILL  (set display fill color)

FILL  (set print fill color)

FILTER  (set view filter expression)

FIRST, LAST  (set MENU or ITEM position)

FONT  (set control font)

FONT  (set default font)

FONT  (set print structure default font)

FONT  (set report default font)

FONT  (set toolbar default font)

FONT  (set window default font)

FOOTER  (page or group footer structure)

FORM  (page layout structure)

FORMAT  (set LIST or COMBO layout)

FORMAT  (set LIST print format)

FROM  (set field data origination)

FROM  (set report listbox data source)

FROM  (set window listbox data source)

FULL  (set full-screen)

GRAY  (set 3-D look background)

GROUP  (compound data structure)

GROUP  (declare a group of report controls)

GROUP  (declare a group of window controls)

HEADER  (page or group header structure)

HIDE  (set control hidden at open)

HIDE  (set control non-print)

HLP  (set control's on-line help identifier)

HLP  (set window's on-line help identifier)

HSCROLL, VSCROLL, HVSCROLL  (set control scroll bars)

HSCROLL, VSCROLL, HVSCROLL  (set window scroll bars)

ICON  (set control icon)

ICON  (set window icon)

ICONIZE  (set window open as icon)

IMAGE  (declare a report graphic image control)

IMAGE  (declare a window graphic image control)

IMM  (set immediate event notification)

INDEX  (declare static file access index)

INS, OVR  (set typing mode)

ITEM  (declare a menu item)

JOIN  (declare a "join" operation)

KEY  (declare dynamic file access index)

KEY  (set control execution keycode)

LANDSCAPE  (set page orientation)

LEFT, RIGHT, CENTER, DECIMAL  (set display justification)

LEFT, RIGHT, CENTER, DECIMAL  (set print justification)

LIKE  (user-defined data types)

LINE  (declare a report line control)

LINE  (declare a window line control)

LIST  (declare a report list control)

LIST  (declare a window list control)

LONG  (four-byte signed integer)

MARK  (set multiple selection mode)

MASK  (set pattern editing data entry)

MAX  (set maximize control)

MAX  (set total maximum)

MAXIMIZE  (set window open maximized)

MDI  (set Multiple Document Interface)

MEMO  (declare a text field)

MENU  (declare a menu box)

MENUBAR  (declare a pulldown menu)

META  (set .VBX to print as .WMF)

MIN  (set total minimum)

MODAL  (set system modal window)

MSG  (set control status bar message)

MSG  (set window status bar message)

NAME  (set external name)

NAME  (set external name)

NAME  (set filename)

NAME  (set variable's external name)

NOBAR  (set no highlight bar)

NOCASE  (case insensitive KEY or INDEX)

NOMERGE  (set merging behavior)

OPT  (exclude null KEY or INDEX entries)

OPTION  (declare a group of report RADIO controls)

OPTION  (declare a group of window RADIO controls)

OVER  (set shared memory location)

OWNER  (declare password for data encryption)

PAGE  (set page total reset)

PAGEAFTER  (set page break after)

PAGEBEFORE  (set page break first)

PAGENO  (set page number print)

PALETTE  (set number of hardware colors)

PASSWORD  (set data non-display)

PDECIMAL  (fixed-length signed packed decimal)

Picture Tokens

PRE  (set file label prefix)

PRE  (set group label prefix)

PRE  (set label prefix)

PRE  (set report label prefix)

PRE  (set view label prefix)

PREVIEW  (set report output to metafiles)

PROMPT  (declare a prompt control)

PSTRING  (embedded length-byte string)

QUEUE  (declare a memory QUEUE structure)

RADIO  (declare a report radio button control)

RADIO  (declare a window radio button control)

RANGE  (set SPIN range limits)

READONLY  (set display-only)

REAL  (eight-byte signed floating point)

RECLAIM  (reuse deleted record space)

RECORD  (declare record structure)

REGION  (declare a window region control)

REPORT  (declare a report structure)

REQ  (set required entry)

RESET  (set total reset)

RIGHT  (set MENU position)

ROUND  (set round-cornered report BOX)

ROUND  (set round-cornered window BOX)

SCROLL  (set scrolling control)

SEPARATOR  (set separator line ITEM)

SHORT  (two-byte signed integer)

SIZE  (memory size in bytes)

SKIP  (set Tab key skip)

SPIN  (declare a spinning list control)

SREAL  (four-byte signed floating point)

STATIC  (set local queue static)

STATIC  (set local variable static)

STATUS  (set status bar)

STD  (set standard behavior)

STEP  (set SPIN increment)

STRING  (declare a report string control)

STRING  (declare a window string control)

STRING  (fixed-length string)

SUM  (set total)

SYSTEM  (set system menu)

TEXT  (declare a multi-line data entry control)

TEXT  (declare a multi-line text control)

THOUS, MM, POINTS  (set report coordinate measure)

THOUS, MM, POINTS  (set screen coordinate measure)

THREAD  (set thread-specific static queue)

THREAD  (set thread-specific static variable)

TIME  (four-byte time)

TIMER  (set periodic event)

TOOLBAR  (declare a tool bar)

TOOLBOX  (set toolbox window behavior)

TRN  (set transparent report string)

TRN  (set transparent window string)

ULONG  (four-byte unsigned integer)

USE  (set code reference name)

USE  (set control variable or equate label)

USE  (set structure equate label)

USHORT  (two-byte unsigned integer)

VCR  (set VCR control)

VIEW  (declare a "virtual" file)

WINDOW  (declare a dialog window)

WITHNEXT  (set widow elimination)

WITHPRIOR  (set orphan elimination)


Introduction

Welcome to the Clarion IDE

What Youll Find in this Reference

Where to Look for Other Information

Documentation Conventions

Typeface Conventions:

Keyboard Conventions:

Product Registration

Technical Support

Clarion FaxBack System


Welcome to the Clarion IDE

Clarion for Windows provides a database-independent Integrated Development Environment (IDE) for creating high performance database applications for Microsoft Windows 3.1.

Clarion is a fourth generation, business oriented programming language suitable for all your Windows development projects. The Clarion IDE helps you create applications faster and gives you more programming power:

•	The key to the IDE is the Clarion Application Generator. The Application Generator writes your Windows code for you -- in some cases all of it. Though Microsoft Windows has a reputation of being difficult to program for, Clarion for Windows will dramatically increase your productivity with the use of Clarion templates. Produce a polished Windows application automatically by customizing pre-written standard procedures such as menus, browsers, forms, and reports.

•	The IDE seamlessly incorporates visual design tools. Place standard Windows controls such as buttons and checkboxes simply by drawing them on screen. Special controls, such as spin boxes and tabbed listboxes, which may require hours of hand-coding in other languages, are built into Clarion. You may also visually place custom controls from external .VBX files.

•	Clarion's file driver technology gives you complete database independence. The IDE makes choosing Clarion, xBase, Paradox, Btrieve (and other) support as easy as picking from a list. Your programs can access data from virtually all the popular PC database file formats.

•	The IDE automatically creates project files and displays graphical project trees. This makes adding modules and maintaining large projects easier.

•	The IDE also organizes and generates procedure call trees, allowing you to see which parts of the project are still to do, at a glance.

•	The IDE automatically makes and runs your application, using state of the art TopSpeed compiling and linking technology. You can create both Windows executables (.EXE) or dynamic link (.DLL) libraries.

The IDE also provides entry to the Windows Help system. The hypertext help appears when you press the F1 key, or choose one of the commands on the Help menu. Important: if any part of the on screen help text conflicts with the printed documentation, the on screen help takes precedence. Clarion makes every reasonable effort to ensure printed documentation is up to date. Lead-time required by printers may create a lag in the documentation; while we can update the help files that ship concurrently with a product revision, printed materials catch up later.


What Youll Find in this Reference

The User's Guide documents the Clarion environment. Besides a command reference, youll find task-oriented, step-by-step instructions to help you create applications faster and more efficiently.

Each chapter of the Users Guide describes how to use the functional areas of the IDE--the Data Dictionary, the Application Generator and so on--to create your application. The chapters appear in the order in which youll probably use each functional area.

At the beginning of each chapter, youll find a visual  guide to the chapter. These depict the most important dialog boxes for that area of the IDE, briefly describe them, and cite the page on which the full explanation begins. Youll find that creating your Windows applications with Clarion is a matter of filling in a series of dialogs.

***	The Beta 3 documentation will also advise you when something in the IDE will probably change before the final release. Any such notes will appear preceded by three asterisks.

***	Please excuse any rough edges to the Beta 3 documentation--such as hanging widows, or a section which does not yet have illustrations. These will be filled in before the final documentation is printed. If, however, you feel any important subjects are omitted, please tell us what is missing and why you feel its important.

The following lists the chapters included in the User's Guide and summarizes their content:

Introduction	This chapter welcomes you to the Clarion environment. It tells you where to look for information and summarizes document conventions. The introduction also describes product registration and technical support policies.

***	This chapter does not yet includesections on the last two subjects.

Start Here	Lists system requirements and provides installation instructions. It also describes the CORRECTS.HLP file, which covers late-breaking news, and any documentation corrections too late for press.

***	This chapter is not included in the Beta 3 documentation.

Development Flow	An introduction to Clarion, descriptions of the functional parts of the IDE, and an overview of the steps you take to create your applications.

Dictionary Editor	Introduces the concept of the data dictionary which defines the applications data files, their fields, keys, and much more. Clarion provides automatic entry options and data validity checking which saves many lines of code, via the data dictionary.

The task-help in this chapter includes these step-by-step instructions:

•	Overview: Creating a Data Dictionary

•	Designing Your Database

•	Opening the Dictionary Editor

•	Adding Files to the Dictionary

•	Adding File Aliases to the Dictionary

•	Adding a File View to the Dictionary

•	Adding or Modifying Fields

•	Adding or Modifying Keys

•	Adding or Modifying Relations

Application Generator	Describes the Application Generator, with which you can automatically design your applications procedures and functions. Use the Application Generator by choosing procedure types which most closely match your requirements, then customize them by designing pulldown menus, dialogs or reports, by defining data, or by creating formulas and embedded source.

The task-help in this chapter includes these step-by-step instructions:

•	Beginning a New Application

•	Overview: Creating Your Application

•	Specifying Global Settings

•	Adding a Procedure

•	Managing Application Views

•	Maintaining the Template Registry

•	Customizing a Template Procedure

Procedures	Describes the default procedures and code templates, both their uses and how to incorporate them into the application.

The task-help in this chapter includes these step-by-step instructions and topics:

***	For the Beta 3 documenation, this chapter is incomplete.

Window Formatter	Describes how to use the IDE to visually set the properties of your application windows, including size, appearance, menus and controls. The Window Formatter also allows you to add controls from external .VBX libraries. You can access the Window Formatter from either the Application Generator or the Editor. Two additional chapters following this one describe the menus and controls you add to your application by using the Window Formatter.

The task-help in this chapter includes these step-by-step instructions, plus descriptions of the special menu commands available only while working with the Window Formatter:

•	Overview: Creating Your Applications Windows

•	Opening the Window Formatter from a Source Code Document

•	Choosing a Window Type

•	Customizing Your Applications Windows

•	Using the Window Properties Dialog

•	Setting More>>> window Properties

•	To Place Controls in a Window

•	Window Formatter--File Menu

•	Window Formatter--Edit Menu

•	Window Formatter--Control Menu

•	Window Formatter--Alignment Menu

•	Window Formatter--Menu Menu

•	Window Formatter--Toolbar Menu

•	Window Formatter--Options Menu

Menu Editor	You access the Menu Editor through the Window Formatter. It allows you to create menus for your application. For an MDI application, it can automatically merge a menu associated with a document window into the application frame window.

The task-help in this chapter includes these step-by-step instructions:

•	Calling the Menu Editor

•	Creating Your Apps Menu

•	The Menu Editor Commands and Options

•	Creating MDI Menus

•	Adding a Toolbar

Controls	Controls are the user interface elements you place in the application using the Window Formatter. These include entry fields, push buttons and graphical elements such as bitmaps. This chapter shows you how to customize the properties of each type of control.

The task-help in this chapter includes step-by-step instructions for adding each type of control:

•	Overview: Types of Controls

•	Common Control Attributes

•	Button Controls

•	Choice Controls

•	Entry Controls

•	Static Controls

•	Custom Control Properties

Report Formatter	The Report Formatter is the main means of creating reports with the IDE. This chapter describes how to use the Report Formatter.

The task-help in this chapter includes these step-by-step instructions and topics:

•	Overview: Report Processing

•	Report Preparation

•	The Report Formatter--an Overview

•	Laying Out Your Report

•	Adding Text Labels and Fields

•	Adding Graphic Controls

•	Adding Specialized Controls

•	Adding Graphs

•	Samples

•	Miscellaneous

Text Editor	Describes how to directly edit your source code files. The Text Editor features color coded syntax highlighting, search and replace, as well as other programmer conveniences. When the text menu is active, the Edit and Search menus appear. The Edit menu provides access to the Windows clipboard, for cutting, copying and pasting. The Search menu provides you with tools for finding and replacing text in your source code files.

The task-help in this chapter includes these step-by-step instructions:

•	Opening the Editor

•	Managing Source Code Document Windows

•	Using the Edit Menu

•	Using the Search Menu

Formula Generator	Describes how you can more easily create expressions for computed and/or conditional fields.

The task-help in this chapter includes these step-by-step instructions:

•	*** The Formula Generator is not yet complete for Beta 3.

Project System	Walks you through setting up a new project and explains the components of the project tree window. For programmers new to Clarion, the project system provides more flexibility in setting compile options, and is much easier to manage than a Make file in C, for example.

The task-help in this chapter includes these step-by-step instructions:

•	A Simple Project File Walkthrough

•	Overview: Project File Procedures

•	Setting the Target File

•	Setting Project File Options

•	Editing the Redirection File

•	Project System Menu Commands

•	Calling the Windows API

Debugger	Describes how to use the Clarion  Debugger for Windows.

The task-help in this chapter includes these step-by-step instructions:

•	Overview: The Debugger Windows

•	Setting Breakpoints

•	Go!

•	Working with Source Code

•	Editing Watch Expressions

Windows Design	For experienced Clarion programmers new to Microsoft Windows, this will provide a brief introduction to some of the design standards Microsoft recommends for Windows applications.

Distributing Apps	Provides suggestions and instructions for developing Windows Help documents for your applications, information on what Clarion files must be distributed with your applications, and recommendations for your Setup program, which you may use to distribute your applications.

***	Not included in Beta 3.


Where to Look for Other Information

***	Not included in the Beta 3 release. This will be a graphical chart, showing which features are explained in which books.


Documentation Conventions

The Users Guide utilizes the typeface and keyboard conventions which appear below.


Typeface Conventions:

Italics	Emphasizes or introduces new concepts; also indicates the names of dialog boxes, and titles of books.

SMALL CAPS	Indicates keystrokes to enter at the keyboard, such as ENTER or ESCAPE.

Boldface	Indicates commands or options from a pulldown menu or text in a dialog window. Note: this style also utilizes a different typeface to match the helvetica bold face which Windows uses as the system font, with appropriate underlining to match the its appearance on screen.

LETTER GOTHIC	Used for diagrams, source code listings, to annotate examples, and for examples of the usage of source statements.


Keyboard Conventions:

F1	Indicates a keystroke. Press and release the F1 key.

X,O	Indicates two separate keystrokes. Press and release the X key; then press and release the O key.

ALT+X	Indicates a combination of keystrokes.  Hold down the ALT key and press the X key. Then release both keys.

ALT+X,O	Indicates a sequence of keystrokes. Hold down the ALT key and press X.  Release both keys; then press O.


Product Registration

***	This is not applicable to the Beta 3 release.


Technical Support

***	This is not applicable to the Beta 3 release.


Clarion FaxBack System

***	Not available for the Beta 3 release.


Application Development Flow

Clarion Programming

Template Driven

A Walk Through the IDEs Functional Parts

The Data Dictionary

The Application Generator

The Window Formatter

The Report Formatter

The Text Editor

The Expression Generator

The Project System

The Debugger

***	Beta 3 users: the final documentation will include a book called Getting Started. Much of the information in this section will be placed in that book and expanded.


Clarion Programming

Clarion is a fourth-generation, business oriented programming language specially designed for rapid application development. As implemented in Clarion for Windows, the language automatically handles the extra housekeeping, such as checking the applications message queue. Many other Windows programming languages normally require many lines of code and complicated case statements for handling such chores.

Clarion is extensible. It incorporates, for example, support for custom controls in the .VBX format. Clarion programmers can also make calls to the Windows API, or to any third party dynamic link library. Clarion for Windows also provides support for the ODBC (Open DataBase Connectivity) protocol. You may also link .OBJ and .LIB files created with any TopSpeed language (C, C++, Pascal, and Modula 2).

File driver independence is built into the language; Clarion contains dynamic link library drivers for most popular PC database formats.


Template Driven

The Application Generator is template driven. The procedures and code templates in the Clarion template provide many of the benefits of object oriented programming, especially reusability, without the overhead of learning an object oriented language.

The template registry (REGISTRY.TRF) stores pre-written executable code and data structures which can be customized and reused. You can modify the default Clarion template and store your modifications in the template registry. You may also add third party templates and use them in addition to the Clarion defaults.

A procedure is a stored series of Clarion language statements which perform a task. The PROCEDURE statement identifies the first line of executable code for the procedure, and includes a label which identifies it.

Clarion for Windows provides a rich assortment of pre-written procedures with which you can rapidly develop database applications. You identify a procedure closest to the task the program must perform, then customize it with the IDE tools. The procedures include elements such as browse windows for the end user to view groups of records, and form windows, to edit one record at a time.

The template registry is managed by the IDE. To incorporate a procedure into a new application, you select a procedure from the registry and add it to the .APP file. If the procedure is for a window with a menu, the menu actions are automatically added to the applications procedure tree, and marked To Do, as any other procedure call would be.

The usual way to customize a procedure is to call one of the formatters--the Window Formatter or Report Formatter--and add a new window, for example, or a control in a dialog box. The formatters are visual design tools; for example, to place a command button in the upper right corner of a dialog box, you pick the button tool from a toolbox, then click in the dialog box under construction to place the button.

Another way you may customize a procedure is to add embedded source code. The Application Generator displays a tree containing the main actions before, during and after the procedure, plus all the events the window or entry fields in the procedure may generate. You can pick a precise spot to execute the code, then handwrite it, or utilize code templates.

Code templates are canned executable code fragments with functionality related to the procedure. Each provides you with on screen instructions on what information to fill in to incorporate its functionality into the application.

***	Important: the term Code template is subject to change.

The Application Generator generates source code from the templates, plus any customized code (embedded source code), which the IDE then compiles and links to create the application.


A Walk Through the IDEs Functional Parts

The IDE contains seven main functional parts, all of which are accessible from the others. When using the Application Generator, buttons in the various dialogs lead to the other parts. The Application Development Flow chart at the beginning of this chapter pictures how the parts interact with each other and the template registry, with the Application Generator at the center of the whole process.

This section provides a description of each part, in the order that a typical programmer utilizing the Application Generator might encounter each. Each part of the IDE contains dialog boxes which the programmer fills out to describe the Applications functionality to the Application Generator.

Programming Clarion for Windows is in many ways a walk through a series of dialog boxes. Theres no mandatory sequence in which you must fill in the dialogs, though you do need to create some files before others. If you know which dialogs do what, it makes building your application that much quicker.


The Data Dictionary

The Data Dictionary holds a description of the database, including its files, driver(s), fields, relations, field validation rules, and referential integrity constraints. Its the first file you create when you design your application.

The other parts of the IDE look up the options you set in the dictionary to let you, for example, easily place data fields in a dialog box you design for the end user. The Application Generator creates code for all the statements that access the data files based on how you construct the Data Dictionary.

Start a new dictionary with the File [image] New command, then select Dictionary. This leads you to the Dictionary dialog.

Define your applications data files, aliases, and views in the Dictionary dialog. It also shows the relationships between files. Buttons lead to the New File Properties , the New File Alias, the New File View, and the New Relationship dialogs.

Specify the name and file driver for each data file, one by one, in the New File Properties dialog. It also allows you to set options such as encryption. Buttons lead to the New Field Properties dialog, and the New Key Properties dialog.

Define fields, their data type and size in the New Field Properties dialog. You can even pre-define control properties such as text justification. Two buttons provide shortcuts to all the properties dialogs in the Window and Report Formatters. You can also back up to the previous dialog to define keys and relationships.

Press the New button to specify keys and index files in the New Key Properties dialog. You choose options such as specifying primary or unique keys. A button press leads to the Key Components dialog.

Specify the key components in the Key Components dialog. Clarion automatically builds the key correctly even if you specify multiple field types. From here, you back up to the Dictionary dialog to define relationships.

Press the New button to define relationships in the New Relationship Properties dialog. You can also specify Referential Integrity Constraints from controls in this dialog. With the major parts of the dictionary defined, you save the dictionary and move on to the .APP file.


The Application Generator

The Application Generator generates your applications code, based on the predefined procedures you pick from the template registry. It allows you to add global memory variables, and customize the procedures with embedded source code.

The Application Generator also provides access to other parts of the IDE to customize the look and functionality of the windows, menus, reports and other user interface elements..

Start a new application with the File [image] New command, then select Application. This allows you to set the basics--application name, data dictionary name, help file and the application template--in the Application Properties dialog. This creates the .APP file and displays the Application Tree.

View and maintain the parts of your application in the Application Tree dialog. It lists all your applications procedures, and marks the ones still to be defined as To Do. A button press accesses the Select Procedure Type dialog.

Select the functionality for a To Do procedure in the Select Procedure Type dialog. Template procedures such as browse and form appear in a list. The Edit button accesses the Procedure Properties dialog.

The Procedure Properties dialog is the hub for all the other dialogs that let you customize the template procedures so that your application does the job the way you want. It leads to the Window Formatter, the Report Formatter, and the Text Editor. Choose Edit [image] Global Properties to define global memory variables, or press the Data button to define local memory variables.

Define and set the order the program initializes local memory variables in the Data dialog. Press the Insert button to define variable name, type, size etc., in a dialog box identical to the New Field Properties dialog. Back up to the Procedure Properties dialog.

Press the Files button, then select the files, aliases, and views the procedure will access in the File Schematic Definition dialog. It also sets the Access Key. Back up to the Procedure Properties dialog to set more options.

Press the Embedded button to display the Embedded Source dialog. This allows you insert custom executable code at points before, during, and after the procedure, or on window and field-specific events. Select the point and press the Edit button.

The Embedded Source dialog (*** duplicate name, different dialog) allows you to specify another procedure to execute at the embed point, accesses the Text Editor so you can write custom code, or allows you to choose a code template which prompts you to fill-the-blanks and writes the code for you.

Press the ellipsis button (...) and select a code template template, then follow the directions in the Prompts dialog, and let the code template automatically write custom code for you, taking care of complex CASE statements and more. Back up to the Procedure Properties dialog.

If the procedure supports windows, press the Windows button 1to call the Window Formatter to create or edit a window or dialog box.

If the procedure supports printed reports, press the Report button to call the Window Formatter to create or edit a window or dialog box.

After youve returned from the Window Formatter, Report Formatter and/or Text Editor, you can back up to the Application Tree and generate the code!


The Window Formatter

You visually design your applications windows and controls--everything the end user sees--in the Window Formatter. It automatically generates source code for the elements you visually design on screen.

Most likely, when using the Application Generator, youll call the Window Formatter by pressing the Window button in a Procedure Properties dialog, to customize a window or dialog box.

The Window Formatter window provides a view of the window under development. CLICK in the toolbox, then CLICK in the window to place a new control.

You can then press the Test button to see exactly how the window appears to the end user.

Each window and each control in the window has an associated property dialog that controls its appearance, and if an entry field, its contents. You select the window or anything in it, then press the Properties button. The Window Properties dialog sets basic elements such as system menus, caption, etc.

A typical control property dialog sets options such as a label, its field equate label to reference it in executable code, or if an entry box, a field or variable name to reference its contents.

Choose Populate [image] Field to call the Select Field dialog. This automatically places an user entry field with a data field or memory variable for its contents. You pick a field, then click in the window to place it. The Window Formatter reads the Data Dictionary and sets control attributes to best fit the field properties you set in the dictionary.

Choose Menu [image] New Menu to call the Menu Editor (if the window has a menu). Edit the menu text, and new menu items with the Add button, and specify menu item functionality by pressing the Actions button.

The Actions button leads back to the Embedded Source dialog. For a menu item, you associate a procedure with the Selected event, so that when the user selects the menu command, it executes the procedure you name.


The Report Formatter

***	This section will be completed when the Report Formatter is hooked into the Application Generator. Its interaction with the Application Generator will be similar to the Window Formatter.


The Text Editor

The Text Editor is a full function programmers editor in which you can handwrite source code.

Most likely, when using the Application Generator, youll call the Text Editor to create embedded executable source code to customize the way a procedure handles an event.

The Editor features color coded syntax highlighting, making it easier to identify the different parts of the Clarion language statements for editing purposes.

The Editor features full text search and replace capabilities.


The Expression Generator

***	This section will be completed when the Expression Generator is hooked into the Application Generator. The Expression Generator will be called whenever you press the Formulas button in the Procedure Properties dialogs. The Application Generator will store the expressions in the .APP file for use in generating source code.


The Project System

The Application Generator automatically creates the project file for the application. The project file contains compiler and link options, such as whether to include debug code, optimization choices, external drive files, and so on.

When working with the Application Generator, to edit the project file, choose Project [image] Edit Current Project. This displays the Project Tree. Select the components in the Tree list and press the Properties button to set specific options.

More likely, when creating an application using the Application Generator, youll just press the Make button to compile and link the application. The only Project system dialog youll encounter is the Compile Results dialog, which allows access to the Debugger. This dialog box also contains the Run button, to launch and test your new application.


The Debugger

Debugging a program usually requires running the program and repeatedly stopping it to examine the value of different variables. The Debugger consists of a number of windows which display source code, variable contents, active procedures and more.

To view a source code window, youll tell the project system to include debug information in the .EXE file, then start the Debugger by pressing the Debug button in the Compile Results dialog, or choosing Project [image] Debug. You then select the source file in the Source Files to Include dialog.

The simplest way to debug your application is to identify the part of the program that you think is producing the bug, and set a breakpoint, using the Breakpoint dialog, at that part of the code. You can then run the program, and the Debugger will suspend it at that point so that you can examine the value of the variables. This will (hopefully) help you pinpoint the error so that your application is perfect!


Using the Data Dictionary

What a Data Dictionary Is

Overview: Creating a Data Dictionary

Designing Your Database

Normalization

Keys

Relational Operations

Clarion

Opening the Dictionary Editor

Adding Files to the Dictionary

New File Properties

Adding File Aliases to the Dictionary

Adding a File View to the Dictionary

Adding  or Modifying Fields

Field Properties

Validity Checks

Screen Controls

Report Controls

Adding or Modifying Keys

New Key Properties

Key Components

Adding or Modifying Relations

Referential Integrity Constraints


What a Data Dictionary Is

The Data Dictionary is the central repository for keeping track of both where and how the file system stores your data.

The Dictionary file--.DCT--stores file names, file structure, field validity, field entry pictures and checks, keys, indexes, relations, plus miscellaneous data such as status bar help messages by field and report column titles.

The Application Generator reads the Data Dictionary to create the file declarations, which it places in the data section of the generated source code files. It also uses the dictionary to provide, for example, entry pictures when formatting entry dialogs for the end user.

Build your applications data dictionary through a series of dialogs:

•	Choose the file driver and specify the names and locations of data files in the Edit File Properties dialog.

•	Define fields and the types of data they hold in the Field Properties dialog.

•	Specify field validity checks in the Validity Checks dialog.

•	Specify keys and index files in the New Key Properties dialog. Define their components in the Key Components dialog.

•	Set file relationships in the New Relationship Properties dialog.


Overview: Creating a Data Dictionary

In less than twenty five steps, the following walks you through creating a complete data dictionary. This procedure leaves many options at their defaults. Each dialog box and option is explained more fully in the sections below.

1.	Choose File [image] New from the IDE menu, then specify Dictionary. The Dictionary dialog appears.

2.	Press the Insert button and type the Name, Prefix, choose the File Driver, and type the Full Pathname for your dictionary in the New File Properties dialog. Press OK to close the dialog.

3.	Press the Fields button to open the File Definition dialog.

4.	Press the Insert button under the Fields list. The New Field Properties dialog appears.

5.	Type in the field Name, choose the field Type, specify the length in Chars.

6.	Press the Validity Checks button, and choose an option for entry validation for the field. Press OK to return to the New Field Properties dialog.

7.	Press the Screen Controls button to specify how the field and its prompt will appear as controls in your application windows and dialogs. Press OK to return to the New Field Properties dialog.

8.	Press the Report Controls button to specify how the field will appear on a printed report. Press OK to return to the New Field Properties dialog.

9.	Press OK to return to the File Definition dialog.

10.	Repeat steps four through nine for additional fields within this file.

11.	Press the Insert button under the Keys list in the File Definition dialog to open the New Keys Properties dialog.

12.	Type the key Name.

13.	Press the Components button to open the Key Components dialog. Select a field in the Fields list, then press the Add>> button to move the field name to the Components list. Repeat for multiple component keys.

14.	Press the OK button to return to the New Keys Properties dialog.

15.	Press the OK button to return to the File Definition dialog.

16.	Repeat steps 11 though 15 for any other keys in this file.

17.	Press the Close button to return to the Dictionary dialog.

18.	Repeat steps 2 through 17 for additional files in the database.

19.	Select a file to relate to another, then press the New button on the right side of the Dictionary dialog to set up file relationships.

20.	Choose the Related File from the dropdown list.

21.	Choose the Primary Key for the original file (upper right) and the Foreign Key, for the related file (below it), from the dropdown list.

***	Referential Integrity Constraints will be described here; not currently hooked into Beta 3.

22.	Press the OK button to return to the dictionary dialog.

23.	Choose File [image] Save As to save the .DCT file.


Designing Your Database

***	Note: the Beta 3 Users Guide does not yet have all the illustrations the final documentation will have. The next few pages will have drawings to illustrate its subjects.

This section provides a quick review of relational database theory. Planning and organizing your applications database design up front can result in a more efficient application for the end user, not to mention saving hours of redesign later.

The relational model concerns itself with three aspects of data management: structure, integrity, and manipulation. For our purposes, we will discuss the three practical requirements of these aspects: data normalization, keys, and relational operations.


Normalization

At its simplest, data normalization means that a data item should be stored at only one location. To avoid duplication within the database, a good design splits data into separate files.

For instance, assume a very simple order-entry system storing the following data:

Customer Number

Customer Name

Customer Address

ShipTo Address

Order Number

Order Date

Product Number

Quantity Ordered

Unit Price

You could store all the data in each record of one file, but that would be inefficient (unless the business has no repeat customers). A second order from a customer would repeat all the Customer data, for example. To eliminate duplication, you could split the data into three files:

Customer File:	Order File:	Item File:

Customer Number	Order Number	Product Number

Customer Name	ShipTo Address	Quantity Ordered

Customer Address	Order Date	Unit Price

This organizes the data in a logical scheme and eliminates duplication. The process of relating each record to another record in another file requires adding additional fields to at least two of the files, so that the files can share common values. This will be discussed in a section below.

Strict relational theory requires specifies that:

•	The database consists of one or more tables, which, to vastly oversimplify for a moment, correspond to the files.

•	The table consists of column headings (which at the file level we refer to as fields) and zero or more rows (records).

•	Each record contains exactly one value for each field.


Keys

In the simple order-entry system above, to point the records in the customer, order and item files to one another, we could add one field each to two of the files as follows:

Customer File:	Order File:	Item File:

Customer Number	Order Number	Order Number

Customer Name	Customer Number	Product Number

Customer Address	ShipTo Address	Quantity Ordered

Order Date	Unit Price

Relational database theory states:

•	A primary key should exist for each table. A primary key is a unique field or unique combination of fields. The primary key must not accept a null value.

•	A foreign key can match the primary key in another table. If table A includes a foreign key (FK-A), that matches table Bs primary key (PK-B), then every value of PK-B in B must either be equal to the value of PK-B in a record in A or be null.

In the example above, the Customer Number is the primary key (there could be two John Smiths, but not two customer #1001s). The Customer Number field is added to the order file, as a foreign key.

You can define three types of relationships between files:

•	One-to-Many. One record in a file relates to many in another. In the example above, a single customer number may relate to many records in the Order file. In business database applications, this is the most common relationship. It is also referred to as a Parent-Child relationship.

•	One-to-One. Exactly one record in a file relates to one record in another file. This is best suited for when one file may or may not have data in some fields. If all the fields contained in one file, disk space would be wasted on empty fields.

In the example above, if the ShipTo address was rarely different than the Customer Address, you could place it in another file.

•	Many-to-Many. Multiple records in a file relate to multiple records in another. To apply it to the example, assume the Order-Entry system were made to fit a manufacturing concern which buys parts and makes products. If a part could be used in many different products, and a product could use many parts, two additional files might look like:

Parts File:	Product File:

Part Number	Product Number

Part Description	Product Description


Relational Operations

Relational database theory provides a set of operators for manipulating data. The three operations that theoreticians specify for relational database systems are Select, Project, and Join. A system does not have to explicitly support the statements as long as it supports their functionality. For theoretical purposes, a table simply consists of a set of column headings (or fields), plus zero or more rows (records) of data values.

•	A Select extracts a row subset of a given table--in other words, a subset of records which satisfy a given condition.

•	A Project extracts a column subset of a given table--in other words, a subset of specified fields, which then eliminates duplicate records (example below).

•	A relational Join takes two tables and joins them together to form a new, wider table.

Select (not the same as SQLs Select) provides the means to evaluate a table and extract a record or records. The database must have the ability to evaluate the information a single record at a time--in isolation--without looking at the other rows. In the example, extracting a record or records (spanning all files) that meet the condition Customer Number = 100 is an example of a relational select.

Project extracts unique values by field. In the example above, assuming that the Item file has many duplicates, to Project the file Item over the field Product Number yields a new table of all the products ordered by customers (not necessarily matching all products made, in the Product file). All the products sold would have one and only one listing.

Join: Going back to the example, to work with all the combinations of parts and products possible, there must be a special relationship between these two files. The solution is to define a third file, called a Join file. This file creates two One-to-Many relationships. The relationships between the three files would be defined:

Parts File:

Part Number	(Primary key)

Part Description

Parts2Prod File:

Part Number	(1st Primary key component and Foreign key)

Product Number	(2nd Primary key component and Foreign key)

Quantity Used

Product File:

Product Number	(Primary key)

Product Description

The Parts2Prod file has a multiple component Primary key and two foreign keys. The relationship between Parts and Parts2Prod is One-to-Many. The relationship between Product and Parts2Prod is also One-to-Many. This makes the Join file the middleman between two files with a Many-to-Many relationship.

Usually a Join file contains additional information. In this example, the Quantity Used logically belongs in the Parts2Prod file.


Clarion

The Clarion language supports the three aspects of data management that relational database theory concerns itself with. The Dictionary Editor is a tool for planning the structure and integrity of the database, two of the relational models rules. The Dictionary Editor also allows you to preconstruct some of the relational operations specified by database theorists; Clarion language statements handle the remaining operations.

•	The Dictionary Editor allows you to easily set up the proper database structure by defining files, fields, and relations.

•	The Dictionary Editor allows you to easily plan both primary and foreign keys for your database, as per the relational models integrity rules.

•	Additionally, the Dictionary Editor supports preconstruction of Views. The View creates a virtual file, automatically handling any necessary Joins and Projects.

*** Note: Much of the mechanics behind implementing views will change between Beta 3 and the final release.


Opening the Dictionary Editor

You generally create a data dictionary as the first step in creating an application. Therefore, you will access it first from the IDEs main menu.

•	To open the Dictionary Editor to create a new dictionary file:

1.	Choose File [image] New.

2.	Choose Dictionary from the File Type list in the New dialog.

•	To open the Dictionary Editor from the IDE to edit an existing dictionary file:

1.	Choose File [image] Open.

2.	Choose Dictionary *.DCT from the List Files of Type dropdown list in the Open dialog.

3.	Change drives or directories as necessary, and locate the dictionary file you wish to open. DOUBLECLICK on its name in the File Name list, or select it and press the OK button.

Tip:	Clarion for Windows will automatically read and convert Clarion 3.0.007 data dictionaries (and above). It will import all attributes except display size attributes for memo fields. Also, because relational model rules are more strictly enforced in Clarion for Windows, some relationships may not be complete due to stricter error checking.

You may use the same data dictionary for more than one application. An application, however, can only have one data dictionary.

•	To add a text description to the data dictionary and to set a password, press the Dictionary Properties button at the bottom of the dialog. When the Dictionary Properties dialog appears, type the description in the space provided.

The description is solely for your convenience, and has no effect on the application. Its useful for situations in which other programmers may pick up your code later, or for when you expect to return to the project after a long period of time since you last looked at it.

***	Please note that passwords are not yet enabled in Beta 3.


Adding Files to the Dictionary

The first function of the dictionary is to specify the data files for the application.  Define the files by adding them to the list on the left side of the Dictionary dialog. Any of the first three buttons to the right of the list allow you to add to the list.

•	To add a file to the data files list, press the Insert button. This displays the  New File Properties dialog.

•	To add an alias to the list, press the Add Alias button. This displays the New File Alias dialog. See the Adding a File Alias section, below.

•	To add a view to the list, press the Add View button. This displays the New View dialog. See the Adding a File View section, below.

The dialogs title bar lists the current dictionary file name. Highlight a file name on the left, then press a button to the immediate right of the list to display the appropriate dialog for the file-related task you wish.


New File Properties

Define a new file for the database in the New File Properties dialog. This dialog allows you to add a new data file to the list and specify its file driver.

Once the file appears on the list, you may declare fields, keys, set relationships, and other properties for the data file. Using the data  from this dialog, the Application Generator will write the FILE structure declaration.

Name	Type a data file name, as you wish to refer to it in your code. Specify a valid Clarion label--Clarion will automatically truncate the name if necessary. You may also specify a completely different name for the DOS file--see Full Pathname, below.

Prefix	As you enter the data file Name, Clarion automatically extracts the first three letters to use as a label prefix when referring to the file. Optionally specify up to three letters of your choice in this field.

The prefix allows your application to distinguish between similar variable names occurring in different file structures. A field called Invoice may exist in one data file called Orders and another called Sales. By establishing a unique prefix for Orders (ORD) and Sales (SAL), the application may refer to fields as ORD:INVOICE and SAL:INVOICE.

Description	Enter a string description (up to forty characters) for the file. Clarion automatically displays the descriptions in certain dialogs, allowing you to quickly recognize the file contents.

File Driver	Specify the data file type. Choose from a drop-down list including Clarion, Btrieve, (*** fill in rest as they become available). See appendix *** for a discussion of the relative advantages in different circumstances of each driver. (*** this will make it in only if time permits)

Options	Optionally type a string for an additional driver attribute. This conveys additional instructions to the file driver and corresponds to the second parameter for the DRIVER attribute, also known as a driver string.

Owner Name	Optionally type a string containing the password for access to the file. This is dependent on the file system. You must also check the Encrypt box (below). Encrypting the file means that only your application will be able to read the file. The end user may not access the data with any other file viewer. This adds the OWNER attribute to the FILE statement.

Full Pathname	Type either the path, or a fully qualified file name for the data file. If you leave the file name out, Clarion automatically uses the first eight letters of the name entered in the Name field. You may also omit the file extension--Clarion will supply the correct extension depending on the file driver chosen.

Create	Optionally specify that the application should create the data file if it does not exist at runtime. This adds the CREATE attribute to the FILE statement.

Reclaim	This option is dependent upon the file driver. It specifies that the application reuse file space formerly taken up by deleted records. Otherwise, the application adds new records to the end of the file. This adds the RECLAIM attribute to the FILE statement.

Export Fields	*** We will fully document this at a later time.

Encrypt	Optionally turn on file encryption. You must also specify an Owner Name (see above). This adds the ENCRYPT attribute to the FILE statement.

Bindable	Optionally specify that all variables in the RECORD structure are available for use in dynamic expressions at runtime. The compiler will allocate memory to hold the full Prefix:Name for each variable. It would otherwise use its own internal reference for each variable. Therefore the BINDABLE attribute increases the amount of memory necessary for the application.

To modify the file properties at a later time, highlight the file name on the Dictionary dialog list, then either DOUBLECLICK or press the Properties button.


Adding File Aliases to the Dictionary

An alias creates a second reference for a file without duplicating the file on disk. You can add an alias for a file only it its already on the Dictionary list. In the Dictionary dialog, press the Add Alias button to display the New File Alias dialog.

A file alias provides several advantages, at the cost of some system overhead:

•	It allows you to set multiple relationships between files. Strict relational database theoreticians state a file may only have a single relational link to another file at a time. Aliases allow you to legally work around this limitation.

•	It allows a second file buffer for the same file. You could use this for a second file browse, as well as entry forms and other items for each. This is particularly useful for an MDI application.

•	On the negative side, the second file buffer takes up additional memory and resources.

Any file system with external key files requires additional file handles for each alias. For example, a file with three external keys and three aliases requires sixteen file handles: one each for the first data file and its three keys, and an additional four for each of the aliases. When using aliases, we recommend choosing a file driver that stores keys internally, such as TopSpeed or Btrieve.

•	When using aliases, you must open the file in Share mode.

The New File Alias dialog includes the following fields:

Name	Type a data file name, as you wish to refer to it in your code. The name must be a valid Clarion label.

Prefix	By default, Clarion will use the first three letters of the Name for the prefix. Optionally specify up to three different letters.

Description	Enter a string description (up to forty characters) for the alias. Clarion displays the descriptions in dialogs such as the Dictionary dialog.

Alias File	Choose a file from the dropdown list. The dropdown list will show only the files previously defined using the Insert command in the Dictionary dialog.

To modify the alias properties at a later time, highlight the file name on the Dictionary dialog list, then either doubleclick or press the Properties button.


Adding a File View to the Dictionary

A VIEW is a virtual file constructed from selected fields in multiple files. The application creates no physical file, yet you may address all functions and commands to the view as if it were a real file.

Creating a view is of major advantage in a Client-Server environment because the Server (usually) does all the work. The Server processes the overhead of the relational Join and Project operations which would otherwise tie up the local machine.

***	Note: the above functionality is not implemented in Beta 3.

To add a view to the files list, press the Add View button. Fill in the New View dialog:

Name	Type a data file name, as you wish to refer to it in your code. The name must be a valid Clarion label.

Prefix	Clarion will automatically take the first three letters of the Name for the prefix. Optionally specify up to three different letters.

Bindable	Mark the checkbox to specify that all fields may be used in dynamic expressions.

Description	Type a string description (up to forty characters) for the alias. Clarion displays the descriptions in dialogs such as the Dictionary dialog.

Filter	Type an expression to choose a subset of records for the view.

Files	Select each file to be incorporated into the view (one at a time) and press the Add>> button. This displays the fields for each file in the Fields list, below.

Fields	Select each field to be incorporated into the view (one at a time) and press the Add>> button. For each, optionally type a new field name, including prefix, in the New Label field in the View Field Properties dialog which then appears. When you press the OK button, the field will move to the View list.

To modify the view properties at a later time, highlight the file name on the Dictionary dialog list, then either doubleclick or press the Properties button.


Adding  or Modifying Fields

Once you define a file, you may define its fields. Highlight the file in the Dictionary dialog window and press the Fields button. Should you highlight an alias, the IDE will automatically display the fields in the original file. Any changes will modify the original file as well as the alias.

The File Definition dialog contains two lists. The left side lists the fields. The right side lists relations, which are explained below.

•	To add a new field, press the Insert button under the Fields list.

•	To modify an existing field, highlight the field name and press the Change button under the Fields list.

•	To delete an existing field, highlight the field name and press the Delete button under the Fields list.

•	To move the selected field within the Fields list, press the ­ and ¯ buttons under the Fields list. This will reorder the field labels within the FILE structure.

To add or modify a field, use the New Field Properties or Field Properties dialogs. These appear when you press the Insert or Change buttons, respectively.


Field Properties

The New Field Properties and Field Properties dialogs allow you to set field related options and attributes.

•	To name the field, type a valid Clarion label in the Name field. Valid field names may vary slightly according to the file driver.

•	To add a text description, type it in the Description field. The description appears in the list in the Field Properties dialog.

•	To assign a field type, choose one from the Type dropdown list. Clarion supports the following field types, which specify how the data will be stored on disk by the file driver, and accessed in memory by the application. These correspond to the Clarion variable types, plus memo and picture fields.

STRING	A fixed length character string, usually up to 65,520 characters in length, depending on the file system.

MEMO	A variable length text field, up to 65,536 characters in length.

PICTURE	Provides a storage picture. Fill in the Record Picture field with the actual PICTURE.

CSTRING	A character string terminated by a null, up to 65,520 characters in length. Corresponds to the string data type in C, and the ZString field type in Btrieve.

PSTRING	A character string with a leading length indicator, up to 255 characters in length. Corresponds to the string data type in Pascal, and the LString field type in Btrieve.

BYTE	A one-byte unsigned integer, from 0 to 255.

SHORT	An integer, from -32,768 to 32,767.

USHORT	An integer, from 0 to 65,535.

LONG	An integer, from -2,147,483,648 to 2,147,483,647.

ULONG	An integer, from 0 to 4,294,967,295.

DATE	Corresponds to the Date field type in Btrieve. Clarion standard dates span January 1, 1801 through December 31, 2099.

TIME	Corresponds to the Time field type in Btrieve.

SREAL	A real number between 0 ± 1.175494535e-38 and 0 ± 3.40282347e+38. Corresponds to the Intel 8087 short real format.

REAL	A real number between 0 ± 2.225073858507201e-308 and 0 ± 1.79769313496231e+308. Corresponds to the Intel 8087 long real format.

BFLOAT4	A real number between 0 ± 5.877471754e-39 and 0 ± 1.7014118346e+38. Corresponds to the four-byte Microsoft BASIC single precision format.

BFLOAT8	A real number between 0 ± 5.877471754e-39 and 0 ± 1.7014118346e+38. Corresponds to the eight-byte Microsoft BASIC double precision format.

DECIMAL	A real number between -999,999,999,999,999 and 999,999,999,999,999; Intel 8087 variable length packed decimal format.

PDECIMAL	A real number between -999,999,999,999,999 and 999,999,999,999,999. Corresponds to the Btrieve format; IBM/EBCDIC variable length packed decimal format.

GROUP	A compound data structure.

***	We will add illustrations to the following section (all the bullets on the next two pages) to break it up and make it easier to read.

•	To assign a field length, specify a number in the Chars field. If the field holds decimal places, specify a number in the Places field.

•	To declare the field as an array, and to specify the array dimensions, type them in the Dimensions fields.

•	To specify that a memo field may hold binary data, check the Binary box.

•	To create a reference field, check the Reference box. A reference field points to another field.

•	To specify the picture for a picture field, type it in the Record Picture field.

•	To specify a screen picture, type it in the Screen Picture field. When the Application Generator creates window and report controls for the field, this will serve as the default picture for the control.

•	To lock the picture,

***	Note: the above functionality is not implemented in Beta 3.

•	To specify a default value for the field, type it in the Initial Value field.

•	To specify an external name for the field, type it in the External Name field. This covers cases where the field label within the program is different than the name of the field in the data file. Place the name of the field as it exists in the data file here.

•	To specify the default prompt string, type it in the Default Prompt field.  The Application Generator utilizes this for controls which display an on screen prompt.

•	To specify the default column title, type it in the Column Heading field. The Application Generator utilizes this for reports.

•	To declare the field as an overlay, select another field name from the Overlay dropdown list. This allows the current field to redefine the other fields location in memory. The Application Generator adds the OVER attribute.

*** Note: the Allocation field is not yet functional in Beta 3.

•	To specify the case attribute for controls referencing the field, choose from the Normal, Capitals or Uppercase radio buttons. The Application Generator adds the CAP or UPR attributes.

•	To specify the default typing mode attribute for controls referencing the field, choose from the Insert, Overwrite or As Is radio buttons. The Application Generator adds the INS or OVR attributes.

•	To specify immediate event notification for controls referencing the field, check the Immediate box. The Application Generator adds the IMM attribute.

•	To specify the data non-display attribute for controls referencing the field, check the Password box. The Application Generator adds the PASSWORD attribute.

•	To specify the display only attribute for controls referencing the field, check the Read only box. The Application Generator adds the READONLY attribute.

•	To specify justification for controls referencing the field, select from the dropdown list. The Application Generator adds the LEFT, RIGHT, CENTER or DECIMAL attribute.

•	To specify an indentation amount for controls referencing the field, specify a number in the Indent field. The Application Generator uses this setting as the parameter for the LEFT or RIGHT attribute. The  measurement unit depends on the default measurement unit for the window which will hold the control.

•	To specify a help ID for controls referencing the field, specify a help topic in the HLP field. The Application Generator will add the HLP attribute.

•	To specify a status bar message for controls referencing the field, type the message in the MSG field. The text may be up to twenty characters. The Application Generator will add the MSG attribute.

***	Note: this edit box will be changed to fit up to 40 characters. It currently holds only 20. Per 4/21 Richard/Ilka phone conversation


Validity Checks

To check an entry when the user completes the field, press the Validity Checks button in the Field Properties dialog, then choose a validation option in the Validity Checks dialog.

The Application Generator uses the information when creating fields. When the user completes the field and shifts focus to another control, the application will sound a warning beep and set focus back to the control if the data is not valid..

Tip:	When setting a validity check, provide the user with a helpful status bar message. For example, if you specify that a numeric field must hold a value between 1 and 50, place a message such as Type a number between 1 and 50 in the MSG field.

The validity checks constrain data entry to the criteria you select:

•	To disable validity checking, choose No Checks.

•	To require a user entry without specifying any other criteria, choose Cannot be Zero or Blank. The Application Generator adds the REQ attribute.

•	To specify the entry fall between two numeric values, choose Must be in Numeric Range. Then enter the two values in the Lowest and Highest fields.

•	To specify a Yes/No entry, choose Must be True or False.

•	To specify the value match a field in an external file, choose Must be in File. Choices will appear in the dropdown list if you previously related another file or files.

•	To specify the value match an entry in a list, choose Must be in List. Then type the choices in the Choices field, in the format Choice1 Choice2 Choice3. Separate the choices with a space.

Tip:	If you plan to allow the end user to choose from a list box, separate the choices with a pipe symbol ( | ).


Screen Controls

To customize the default characteristics for prompts and entry controls for a field, press the Screen Controls button in the Field Properties dialog. The Edit Screen Controls dialog appears.

Tip:	By choosing the properties for a control at this time, you can save time later. Every application you generate from the dictionary, and every procedure in the application will automatically format the control the way you want it. If you dont format it here, and if the control requires custom formatting, you will have to custom format it for each procedure and application later.

Select either the prompt or entry field from the Screen Controls list, then press the Properties button. The prompt is the label which appears next to the control. The entry field is the actual control which accepts user input.

•	To customize the default prompt, select the PROMPT line in the list box. DOUBLECLICK or press the Properties button to display the Prompt Properties dialog. See the Window Controls chapter for details.

•	To customize the default entry control, select the ENTRY line in the list box. DOUBLECLICK or press the Properties button to display the Entry Properties dialog. See the Window Controls chapter for details.

•	To convert a numeric entry field to a spin control, select the ENTRY line in the listbox and check the Spin Control box. You must have previously specified a numeric range in the Validity Checks dialog. After marking the checkbox, to customize the spin box, DOUBLECLICK or press the Properties button to customize it.

•	To convert an OPTION structure to a listbox, select the RADIO line in the listbox and mark the Drop Box Control checkbox. You must have previously defined the Must be in List choices in the Validity Checks dialog. If you plan to use a listbox, separate the choices in that list with the pipe symbol ( | ) rather than a space, for correct listbox formatting.

•	To change prompt and entry controls back to their default values, press the Reset All Controls button.

Tip:	If you specified Must be True or False in the Validity Checks dialog for a numeric value, the Screen Control will default to a checkbox. You may edit the checkbox properties.


Report Controls

To customize the default characteristics for report controls for a field, press the Report Controls button in the Field Properties dialog. The Edit Report Controls dialog appears.

•	Select the entry field from the Controls list, then press the Properties button. The Screen String Properties dialog appears. See the Using the Report Formatter chapter for details.

•	To change the default report string control to an option control, mark the Option Control checkbox. You must have previously defined the Must be in List choices in the Validity Checks dialog.

Tip:	If you specified Must be True or False in the Validity Checks dialog for a numeric value, the Report Control will default to a checkbox. You may edit the checkbox properties.


Adding or Modifying Keys

Add and edit keys and indexes for your database in the File Definition dialog. The Data Dictionary generates the correct FILE structure statement based on the choices you specify in the dialog boxes.

Keys and indexes specify sort orders for a single file. A key may reside within the file, or as an external file, depending on the file system. Keys are automatically updated whenever records are added, changed, or deleted.

Indexes usually exist as external files. Remember that a separate DOS file handle is necessary for each external key or index file. Index files do not update automatically. The BUILD statement updates an index.

A dynamic index allows you to declare an index file without specifying the field(s) in the Data Dictionary. The application must define the field(s) at runtime, as the second parameter of the BUILD statement. The application may rebuild the same index file at a later time, specifying a different field for the index key.

The basic steps for creating a key, using the file system defaults:

1.	Select a file from the list on the left side of the Dictionary dialog and press the Fields button.

2.	Select a field from the list on the left side (the Fields side) of the File Definition dialog.

3.	Press the Insert button on the right side (the Keys side) of the File Definition dialog. The New Key Properties dialog appears.

4.	Type a valid Clarion label in the Name field.

5.	Type a valid DOS filename in the Filename field. Clarion will automatically add the proper extension.

6.	Optionally type a Description. This displays in various dialog boxes, including the File Definition dialog.

7.	Press the Components button. The Key Components dialog appears.

8.	Select a field from the Fields list; press the Add>> button to transfer the field to the Components list.

9.	Press OK to close the Key Components dialog.

10.	Press OK to close the New Key Properties dialog.


New Key Properties

The following fields appear in the New Key Properties and Key Properties dialogs. They set the attributes for the key. Specify the component field for the key in the Key Components dialog, described in the next section.

Name	To specify a Claion label for the key, type a valid Clarion label in this field.

Description	To place a text description for the key in the Data Dictionary, type up to forty characters in this field. The description appears in dialogs such as the File Definition dialog. If you anticipate using many keys for your application, we recommend filling in this field.

Filename	To specify a DOS filename for an external key, type a valid DOS filename in this field.

Type	To specify a key, index file, or dynamic index file, choose an option button in the Type group. The Index and Dynamic Index options are disabled when the Unique checkbox is marked, because indexes allow duplicates.

Auto Number	To specify the Application Generator should create code to manage record sequence numbers, check this box.

Unique	To disallow multiple records with duplicate values in their key component fields, check this box. This option is valid only for keys, and is disabled for indexes.

Case Sensitive	To sort according to case, check this box. When creating or updating the key, all capital letters will precede the lower case letters, as per their positions in the ASCII table.

Exclude Nulls	To exclude records with a null or zero value in the key field from the key, check this box.

Primary Key	To establish the current key as the Primary key, mark this checkbox. The Application Generator adds the PRIMARY attribute. This may be required in certain file systems.

The primary key must be unique and exclude nulls. Checking this option has exactly the same effect as checking the other two boxes.


Key Components

Specify the composition of the keys--the field or fields--using the Key Components dialog. You may specify more than one field for a key. You may mix data types when defining a key on multiple fields. You may also specify different orders--one field ascending, one field descending--when defining a key on multiple fields. This is dependent upon the file system.

To open the Key Components dialog, enter the options you wish in the New Key Properties dialog, then press the Key Components button.

The Key Components dialog features two lists. The Fields list, on the left, shows the available fields. The Components list, on the right, shows the field or fields in the key, noting whether the sort order is ascending or descending. The buttons in the middle and the bottom control the way in which the key does the sort.

•	To add a field to the Components list, highlight a field on the left, then press the Add>> button.

•	To remove a field from the Components list, highlight a field on the right, then press the <<Remove button.

•	To specify Ascending order (the default) for a field in the Components list, highlight a field on the right, then press the ­ button below the list.

***	Note: the arrow on the button was slightly chopped off, and looks like a T. It will be fixed. We will add a screen shot when fixed.

•	To specify Descending order for a field in the Components list, highlight a field on the right, then press the Downstairs button below the list.

•	To move a field in the Components list up in the order, highlight a field on the right, then press the Move Up button below the list.

•	To move a field in the Components list down in the order, highlight a field on the right, then press the Move Down button below the list.


Adding or Modifying Relations

Set relationships between files in the New Relationship Properties dialog. The relationships appear in the list on the right side of the Dictionary dialog.

The basic steps in setting up a relationship:

1.	Select a file from the left side of the Dictionary dialog.

2.	Press the New button. The New Relationship Properties dialog appears.

3.	Select the relationship Type from the dropdown: One to Many, Many to One, or One to One.

The label for the group box immediately below will change to Child, Parent, or Link respectively.

4.	Select the Related File from the dropdown list.

5.	Select the Primary or Foreign key for the original file from the dropdown list at the top right of the dialog.

Clarion will automatically change the label for the dropdown (either Primary or Foreign) according to the relationship type.

6.	Select the Primary or Foreign key for the related file, if applicable, from the dropdown list at the top right of the dialog.

7.	Optionally press the Map by Name button to display a list of the field name correspondences in the Field Mapping lists.

8.	Optionally set Referential Integrity Constraints by choosing from the On Update and On Delete dropdown lists.

See the section below for further information on Referential Integrity Constraints.

9.	Press the OK button.

The new relation will appear in the Dictionary dialog.


Referential Integrity Constraints

By setting referential integrity constraints in the data dictionary, you can instruct the Application Generator on how to set up executable code for handling problematical situations when working with related data files.

Referential Integrity requires that a foreign key cannot contain any value which has no match in the primary key. This raises potential problems when the end user wishes to change or delete the primary key record.

The New Relationship Properties dialog allows you to specify how the executable code should handle these situations On Update and On Delete:

No Action	Instructs the Application Generator not to generate any code to maintain referential integrity.

Restrict	Instructs the Application Generator to disallow the user entry. For example, if the user attempts to change a primary key value, the generated code attempts to check for a related record with the new value, changes it back if unsuccessful, then loops back to the entry dialog so that the user can enter another value.

Cascade	Instructs the Application Generator to update or delete the foreign key record. For example, if the user changes a primary key value, the generated code changes the values in the foreign key that referenced the primary key. If the user deletes a primary key value, the code deletes the foreign key value, too.

Tip:	If the child file is also the parent of another child file (a third file), you must write the code to detect and handle the change or deletion.

Clear	Instructs the Application Generator to change the value in the foreign key to null.


Using the Application Generator

When you use the Application Generator, you create procedures for the major tasks you want your application to do, describe how the application accomplishes the tasks, and how its windows, dialogs and reports appear to the end user. The Application Generator writes the source code for the application, creating the Clarion language statements needed to do the job in the most efficient manner.

Creating the .APP File

Overview: Creating Your Application

Specifying Global Settings

Global Data Variables

.INI File Support

Other Global Settings

Adding a Procedure To Your Application

Defining the Procedure Type

The Procedure Properties Dialog

Adding a File Schematic

Adding Data

Adding Embedded Source Code

Adding Expressions...

Maintaining the Application Tree

Using the Edit Menu Commands

Using the View Menu Commands

Setting Template Registry Options

Maintaining Your Templates

Opening the Registry

Registry Maintenance

Customizing Procedure Templates

Adding WINDOWs or REPORTs


Creating the .APP File

The first step in creating a new application is to create an .APP file. The .APP file holds the procedures, data, and other properties you define for your application. Optionally create a new directory for the application.

1.	In File Manager, choose File [image] Create Directory, type a subdirectory name and press OK.

Or else, use the DOS prompt.

2.	Optionally add the new directory created in the previous step to the Redirection file; choose Setup [image] Edit Redirection File.

When the window containing the redirection file appears, add the new path to the *.* line. Be sure to save and close the redirection file (File [image] Save, then File [image] Close).

3.	Choose File [image] New.

The New file type dialog appears.

4.	Choose Application by double-clicking it in the File Type list, or highlighting it, then pressing the OK button.

The Application Properties dialog appears. This dialog allows you to define the essential files for the application.

5.	Type a name for the .APP file in the Application File field.

Type a legal DOS filename. Clarion automatically adds the .APP extension.

6.	Name the .DCT file the application will use in the Dictionary File field, or press the ellipsis (...) button to select the file in the Select Dictionary dialog.

See the previous chapter for information on creating your applications data dictionary. The Select Dictionary dialog is a standard Open File dialog.

Tip:	Use the ellipsis (...) buttons in the Application Properties dialog to change the current directory by walking the directory tree. This is convenient when you create a new directory for the application, as in step one in this list.

7.	Type a name for the applications .HLP file in the Help File field, or use the ellipsis (...) button to select the file in the Select Help File dialog.

The Application Generator does not require that the .HLP file exist at this point. You can leave the field blank for now, then fill in the field at a later time.

The Application Generator allows you to name the help topics in your application without determining that the help file exists. You are responsible for creating a .HLP file that contains the context strings and keywords that you optionally enter as HLP attributes for the various controls and dialogs.

8.	Type a name for the application template in the Application Template field, use the ellipsis (...) button to select it in the Select Application Type dialog, or accept the default.

The application template you select controls code generation.

9.	Type a name for the first procedure in the First Procedure field.

The default choice is called Main. The first procedure automatically executes when the application runs.

10.	Press the OK button.

Clarion creates the .APP file, then displays the Application Tree dialog for your new application.


Overview: Creating Your Application

Once the .APP file exists, you design your application through a series of dialogs. When create your applications menus and toolbars, it automatically adds To Do procedures to the application tree, based on the procedures you name for each selection.  You fill-in their functionality by picking from templates and/or adding embedded source code. You use the Window and Report Formatters to design how your application looks to the end user.

This is a simplified walk-through illustrating the tasks which you normally complete when building an application with the Application Generator. The Tutorial in the Getting Started book (*** not included in Beta 3) provides a more detailed grand tour.

The starting point for this walk-through is the Application Tree dialog, with only one procedure (called Main). This is where the previous section ended. The walk-through also assumes that a data dictionary already exists, and no embedded source code is necessary.

1.	Select the Main procedure and press the Edit button.

The Select Procedure Type dialog appears. This lists the procedure types available in the currently registered templates.

2.	Select a Procedure type from the Select Procedure Type dialog.

The Procedure Properties dialog appears. Normally, each procedure already contains default starting points for such elements as the application window, a basic menu structure you can add to, reports and more. These default procedures are designed with real world uses, such as a form for updating a database record, in mind. When developing an application, you can customize these procedures to fit your needs.

***	For beta 3, the Application Frame template procedure is probably the best candidate for the top level procedure. This template procedure contains an MDI application window, which includes a proto menu in it already.

3.	Press the Window button.

If the Window button already has a checkmark to its left, that means the procedure already has a WINDOW structure in it, which you can edit. If it does not, the New Structure dialog appears, and you can choose a WINDOW type from there.

4.	When the Window Formatter appears, choose Menu [image] Menu Editor to customize the applications menu.

See the Creating Menus and Toolbars chapter for details on editing the menu. For every new menu choice you add, the Application Generator adds a To Do procedure to the tree.

For procedures which utilize standard actions (for commands such as Edit [image] Copy, where the menu ITEM has the  STD attribute), no To Do is added, because Clarion automatically handles the code for the procedure in the background.

5.	Press the Close button to close the Menu Editor, saving your changes.

6.	Press the Exit button to exit the Window Formatter, saving your changes.

7.	Press the Data button to add local variables.

The Specifying Global Settings section, below, describes this in detail. Essentially, you declare each variable in much the same way you define a field in a data file.

8.	Press the Close button to close the Procedure Properties dialog.

This returns you to the Application Tree dialog.

9.	Select the first To Do procedure in the Application Tree and press the Edit button.

10.	Select a Procedure type from the Select Procedure Type dialog and press OK.

The Procedure Properties dialog appears.

11.	Press the Files button to open the File Schematic dialog.

See the File Schematic section below for detailed instructions. By adding files to the schematic, you allow the procedure to access them.

12.	Press OK to close the File Schematic dialog.

13.	Press the Window button.

Many procedures already have default Window designs defined. You can customize or add a new window. See the Using the Window Formatter chapter for details.

14.	If the dialog box is for user entry, choose Populate [image] Field, then choose a field in the Select Field dialog.

15.	Press the Select button to return to the window under construction, then click twice inside the window.

The first click sets the position for the field label. The second places the field itself.

16.	Place any additional controls as described in the Window Formatter and Setting Control Properties chapters.

17.	Press Exit, then press Yes when asked to save changes.

18.	Press the Generate button in the Application Tree dialog to generate source code.

19.	Press the Make button on the toolbar to and compile and link the application.

The Application Generator automatically creates the project file for the application.

18.	Test the application by pressing the Run button in the Compile Results dialog.


Specifying Global Settings

You can specify memory variables to be shared by the entire program in the Global Properties dialog.

Specific templates may add additional options to this dialog; the template language can add controls and options to default procedure dialogs so that they automatically walk you through all the choices necessary for supporting the functionality of the procedure.

The default APPLICATION template, for example, adds automatic support for storing global variables in your applications own private .INI file. You can also specify other settings, such as that your application restores the last screen position when it starts up.


Global Data Variables

To access the Global Properties dialog, choose Edit [image] Global Properties. Press the Data button. When the Data dialog appears:

•	To add a new variable to the list:

1.	Press the Insert button.

2.	Fill in the Field Properties dialog, then press OK.

The Field Properties dialog is exactly the same dialog as the one you see when you add a field to a database. You can set the data type and label for the variable in this dialog.

3.	Press the Close button to close the Field Properties dialog.

4.	Press the Close button to close the Data dialog.

•	To change the data type or label of a variable:

1.	Highlight the variable in the list.

2.	Press the Properties button.

3.	Make any changes necessary in the Field Properties dialog and press OK.

4.	Press the Close button to close the Data dialog.

•	To move a variable up in the list, highlight it, then press the Up button.

•	To move a variable down in the list, highlight it, then press the Down button.

Tip:	When you need to define a new variable using the contents of another, you must define the other variable first. When Clarion initializes the variables in your list, it will do so in the order they appear on the list.


.INI File Support

The template supports .INI file support. It does so by customizing the Global Properties dialog. When you utilize a procedure with .INI support:

•	To enable automatic .INI file support:

1.	Press the .INI File Settings button in the Global Properties dialog.

The .INI File Settings dialog appears.

2.	Check the Use .INI file box.

3.	Specify the .INI file name

To specify the same filename as the .EXE, with a .INI extension, choose ProgramName.INI from the dropdown list. To specify a different name, choose Other, then fill in the File Name field.

4.	Press the OK button to close the .INI File Settings dialog.

5.	Press the OK button to close the Global Properties dialog.

When the end user opens the application, the program retrieves the .INI file and place the values stored there in the global memory variables.

When your application needs to revise the value in the .INI file, use the PUTINI statement. See the Language Reference for details.

Tip:	If your application requires dozens or even hundreds of variables to store from session to session, dont put them all in a .INI file. Retrieving a variable from a .INI file is relatively slow. Also, if you need to hide the information from the end user, remember that .INI files are text files, and are easily accessible.

•	To automatically save the window position in the .INI file, so that when the end user opens the application it appears in the same place as the last time the user ran it, check the Save Window Locations box.

You do not have to add any code to the application other than checking the box.


Other Global Settings

•	To specify that your application allow shared files, check the Enable Shared Files box.

•	To specify that your application close files when not in use by a procedure, check the Close Unused Files box.

Tip:	One way in which you can design your application to be a well-behaved Windows application is not to hog system resources. One limited resource is file handles. You can give back file handles not in use with the Close Unused Files checkbox.

•	To specify how your program should behave if it doesnt find its data files, choose from the If File Not Found dropdown list.


Adding a Procedure To Your Application

A procedure is a collection of instructions--Clarion language statements--which perform a task. When the program performs the task, such as printing a report, it is executing the procedure. The first procedure your application executes is called Main by default. You can name your first procedure anything you want, but when this chapter refers to the first procedure, we will refer to Main. All other procedures branch off from Main--one procedure can call another.

The Application Tree dialog illustrates how the procedures branch from Main and from each other. This provides a schematic diagram of your programs structure.

The Application Tree shows the procedures you create when you add a menu item, toolbar command, or an embedded source procedure. Each new procedure is marked To Do. When you fill in its functionality, the Application Tree includes your description and takes away the To Do.


Defining the Procedure Type

Once the procedure appears on the Application Tree, the first step is to define its procedure type, from the choices available in the template. You must define each procedure you add to the Application Tree.

You choose the procedure type in the Select Procedure Type dialog.

•	To open the Select Procedure Type dialog, select any ToDo procedure in the Application Tree dialog, then press the Properties button, or choose Edit [image] Properties. You can also DOUBLE-CLICK on the procedure.

•	When the Select Procedure Type dialog appears, choose a procedure type from the list, then press the Select button. You can also DOUBLE-CLICK on a procedure type. The Procedure Properties dialog appears.

After you choose the procedure type, you can define the procedures properties--the files the procedure can access, its window, memory variables and more. You edit the properties in the Procedure Properties dialog, and via the dialogs and formatters that the command buttons in the dialog lead to.


The Procedure Properties Dialog

This dialog contains fields in which you can add a text description for the procedure, choose its source code module, plus command buttons which lead to the dialogs which the following sections describe.

Description	A short text description for the procedure, which appears next to the procedure name in the Application Tree dialog. Type up to fifty characters in this field.

Module Name	The source code file to hold the code for the procedure. Select from the dropdown list.

Prototype	Allows you to type a declaration for embedded source code parameters.

Parameters	Allows you to specify parameter names for your the procedure, which you will pass to it from a calling procedure. You must specify the functionality for the parameters in embedded source code.

Files	A list of files which the procedure can access. Press this button and fill in the File Schematic Definition dialog, described below.

Window	Press this button to call the Window Formatter. See the Using the Window Formatter chapter.

From the Window Formatter, you also access the Menu Editor, which creates and edits the menus for the application. See also the Creating Menus and Toolbars chapter.

Report	Press this button to call the Report Formatter. See the Using the Report Formatter chapter.

***	The above feature is not yet implemented for Beta 3.

Data	Adds or edits local variables. Press this button and fill in the Local Data dialog.

Local data consists of variables available only to the current procedure. Define the local variables in the same way in which you define global variables. See the Global Settings section, above.

Procedures	Names procedure calls made in embedded source code.

Press this button and type a procedure name in the New Procedure dialog. If procedure calls already exist, the names appear in the Extra Procedures dialog. To add another, press the Add button. To delete one, press the Delete button.

Tip:	The purpose of the Procedure button is to add procedures called in embedded source code. The normal way to add template procedures to the Application Tree is to create a menu or toolbar command, and let the Application Generator automatically add it to the tree.

Embedded	Displays the Embedded Source dialog. You can then select either a field specific event or window related action, then add executable source code to customize how the procedure will handle it.

 After you choose an embed point in the Embedded Source dialog, you choose where the code comes from. You can specify that its in another procedure, which is then added to the tree. You can write the code with the text editor. You can choose and customize a code template, which is a combination a pre-written code and prompts to fill-in-the-blanks.

Embedded source gives you complete control over all the processing in your procedures. Its one of the most powerful tools Clarion provides you. See the Adding Embedded Source section, below.

Format Strings

***	The above function is not implemented in Beta 3.


Adding a File Schematic

You define the list of files a procedure can access via the File Schematic Definition dialog. You access the dialog by pressing the Files button in the Procedures Properties dialog. The available data files and keys are the ones you define in the data dictionary.

•	To add a data file to the schematic, press the Insert button. Choose a file from the Insert File list. The first file you add to the list is always the primary file. All others are secondary.

•	To specify the sort sequence of the primary file, choose a key from the Access Key dropdown list.

•	To add a other files, such as a view to the list, select Other Files, then press the Insert button. Choose a file from the Insert File list.

•	To delete a data file from the schematic, highlight the file and press the Delete key.


Adding Data

You can create or edit memory variables local to the procedure, local to the MEMBER module, or you can create global memory variables.

•	To add a local omemory variables to a procedure:

1.	Select a procedure in the Application Tree.

2.	Press the Edit button or choose Edit [image] Properties to display the Procedure Properties dialog.

3.	Press the Data button to display the Local Data dialog.

If any variables already exist, they appear in the list.

4.	Press the Insert button.

The Field Properties dialog appears. Type in the variable name, choose the variable type, and set any additional attributes, including screen attributes. This is exactly the same dialog box procedure as the one in which you set field properties. For details, see the Using the Data Dictionary chapter.

5.	Close the Field Properties and the Local Data dialogs.

The data variables are now included in the procedure.

•	To add a memory variable to a MEMBER module:

1.	Choose View [image] Module View.

2.	Highlight a module inside the Application Tree

3.	Press the Properties button to display the Module Properties dialog.

4.	Press the Data button.

The Field Properties dialog appears. Type in the variable name, choose the variable type, and set any additional attributes, including screen attributes. This is exactly the same dialog box procedure as the one in which you set field properties. For details, see the Using the Data Dictionary chapter.

4.	Close the Field Properties, the Local Data, and the Module Properties dialogs.


Adding Embedded Source Code

As you add procedures from the template to your application, the Application Generator incorporates the procedure definitions from the registry into the .APP file. It also incorporates the customizations you make to the procedures. At code generation time, it again uses the registry, this time processing and converting the template symbols to generated executable source code, including the customizations.

The Application Generator thus handles much of the dirty-work of building procedures from groups of executable statements. Typically, you only need to embed executable statements at key points within the procedure.

By adding embedded source code to a procedure, you gain powerful customization capability. You can specify or create code to execute before, during and after the procedure. You can write your own code, or follow the code template prompts which help write the code for you. The Application Generator adds your code to the code it generates.

To choose the point to place embedded source code in a procedure:

1.	Highlight a procedure in the Application Tree dialog and press the Edit button.

2.	Press the Embedded button in the Procedure Properties dialog to display the Embedded Source dialog.

The Embedded Source dialog lists points within the procedure at which you can choose to have your custom source code execute. For example, before displaying a window, before closing it, or after closing it. It also lists all the field specific events associated with the procedure. You may create code, for example, to execute as soon as the end user moves the focus (or highlight) to a field.

The events appear in the dialog list--just select it, write a line or two of executable code, and the Application Generator automatically constructs the CASE statement that executes your code fragment.

The Application Generator embeds your executable code within the code it generates, then manages the entire compile and link process automatically.

3.	Select a point at which to embed the code and press the Edit button.

The Embedded Source dialog appears. There are three ways to create the embedded source code. You can even combine all three.

Depending on how you choose to create the embedded source code, you follow one or more of the bullet-pointed steps below:

•	To hand-code the embedded source code with the Text Editor:

1.	Select the Source radio button in the Embedded Source dialog.

***	In beta 3, both this and the previous dialog box have the same caption.

2.	Press the Editor button to display to call the Text Editor with a blank source code window.

3.	Write your custom code in the source code window.

4.	Choose File [image] Close.

5.	Choose Yes when prompted to save the Embedded Source.

The dialog asking whether to save the file will not include the file name. It will include either a line and column number, or ?,? instead.

6.	Press the OK button to close the Embedded Source dialog.

7.	Press the OK button to close the Embedded Source dialog.

•	To call another procedure:

1.	Select the Procedure radio button in the Embedded Source dialog.

2.	Type a name for the procedure in the field to the right of the button.

3.	Press the OK button to close the Embedded Source dialog.

4.	Press the OK button to close the Embedded Source dialog.

This specifies that the application calls another procedure, which automatically appears in the Application Tree as a To Do. If another procedure with the same name already exists, the Application Generator assumes you meant to call it, and does not add a new To Do.

You must fill in the functionality of the other procedure separately.

o	To use an embedded source code template to help construct the code.

1.	Select the Code template radio button in the Embedded Source dialog.

Embedded source code templates helps you construct code with minimal writing on your part. They can automatically take care of complex control structures, and property assignments. Each code template displays a dialog box with an explanation of what it does and prompts for you to fill in the information it needs in the fields inside the dialog.

2.	Press the ellipsis (...) button to display the Select a Code Template dialog.

The names of the code templates available appear. For example, the Form template includes code templates for pre-edit and post-edit field validation.

See the Templates and Code templates chapter for descriptions of the ones included in the default template.

3.	Highlight a code template and press the Select button.

This places its name in the field next to the radio button.

4.	Press the Prompts button.

This displays a Prompts for... dialog box (the title includes the name of the code template).

5.	Read the instructions and explanation in the Prompts for... dialog.

6.	Fill in or choose from the options inside the Prompts for... dialog.

7.	Press the OK button to close the Prompts for... dialog.

8.	Press the OK button to close the Embedded Source dialog.

9.	Press the OK button to close the Embedded Source dialog.

•	To use a combination of naming a procedure, writing code with the text editor and using a code template to help construct the embedded source code:

1.	Follow one set of instructions above for creating the first embedded source code item.

2.	Press the Multi button in the Embedded Source dialog.

.3.	Press the Insert button in the following dialog.

***	The temporary title of this dialog is Data Section.

The dialog title bar contains the name of the Embed Point, as taken from the embedded source list. This dialog lists any embeded source already added.

4.	When the Embedded Source dialog appears, add another procedure, code template or new code created with the Text Editor.

5.	Close the Embedded Source dialog to return to the Embed Point dialog.

6.	Optionally add another procedure, code template or new code created with the Text Editor.

This dialog also contains ­ and ¯ buttons to change the order of the multiple embedded source; execution follows the order in which they appear in the list. There are also Delete and Change buttons for maintainence.

7.	Press the OK button to close the Embedded Source dialog.

8.	Press the OK button to close the Embedded Source dialog.

When youre ready to generate code, the Application Generator generates source code from the template, arrives at the point you added the embedded source code, writes your code to the source code file, continues with the template, and then compiles the entire project once code generation is complete.


Adding Expressions...

*** not implemented yet


Maintaining the Application Tree

When the Application Tree dialog is active, it provides buttons for adding and editing procedures, as described above. It also provides buttons and menu commands for maintaining the tree, and for changing the view its organization.


Using the Edit Menu Commands

With the Application Tree dialog active, you can execute the following commands:

Insert Procedure	Equivalent to the New Procedure button. Adds a procedure a level below the currently highlighted procedure.

Insert Module	Equivalent to the New Module button. Specifies a new MODULE for generated source code. You can also specify an external .LIB or .OBJ file to add to the project.

Properties	Equivalent to the Edit button.

Delete	Equivalent to the Delete button. Deletes the currently highlighted item from the Application Tree.

Repopulate Modules	Reassigns procedures between modules, based on how they appear in the logical procedure call tree, and the default number of procedures in each module.

Renumber Modules

Delete Empty Modules

Change Template Type	Allows you to change the procedure type for the currently highlighted procedure.

Move Up	Moves the currently highlighted procedure up one step the Application Tree.

Move Down	Moves the currently highlighted procedure down one step the Application Tree.

Application Properties	Displays the Application Properties dialog for specifying changes for the .APP file.

Global Properties	Displays the Global Properties dialog.


Using the View Menu Commands

The Application Tree dialog allows you to arrange your procedures in four different views. All options appear on the View menu.

Procedure 	Displays procedure names, nesting each procedure under its calling procedure. This is the default view, and combined with the To Do legends for undefined procedures, is the best view for determining what remains to be done to complete the application.

Module 	Each procedure appears nested under the file name to which its source code generates.

Alphabetic 	Lists procedure names alphabetically. This is sometimes convenient for large projects.

Template	Lists procedures according to template procedure type.


Setting Template Registry Options

To set registry options, choose Setup [image] Template Registry Options. The Registry Options dialog appears.

Template Language code can be logically split among several files. Clarion uses the files to produce one logical template for the application. The Registry Options are mainly for programmers who produce their own template files or make modifications to the default templates.

•	To automatically re-register your templates when making a change in the Template Registry dialog, check the Re-register when changed box. This defaults to On.

•	To automatically update the Template files when making a change in the Template Registry dialog, check the Update Template Chain box.

***	The Regenerate Deleted Templates option is not enabled for Beta 3

•	To automatically back up the registry when making a registry change, check the Create Backup box.

•	To specify the default #APPLICATION template, select from the choices in the drop-down list.

•	To specify the default #PROGRAM section, which defines the beginning of the Global Section of the template, select from the choices in the drop-down list.

•	To specify the default #MODULE, select from the choices in the drop-down list.


Maintaining Your Templates

Template files (*.TPL) drive the Application Generator. Each procedure template contains generic or model code. The templates are interactive--they process the information you specify when you design the application within the IDE. Clarion evaluates the template file twice:

•	Before generating your application, Clarion pre-processes the template file and stores the information in a default REGISTRY.TRF file. Pre-processing occurs when the Application Generator detects a new or changed template.

When it pre-processes the template file, the Application Generator stores a list of all the information you must provide each procedure. It also determines the points at which you can embed your own Clarion source code to customize a procedure. The registry file contains the default windows, dialogs, menus, report designs, default data, and formulas. In the design process, you customize these defaults.

•	At code generation time, the Application Generator evaluates the information you provide in the design process--from the data dictionary, and the .APP file--then processes it along with the template language statements and symbols in the REGISTRY.TRF file. Only then does the Application Generator generate your source code.

Each template can contain multiple types of procedure templates from which you select to create the procedures in your application. Before you can use a template it must be in the Template Registry.


Opening the Registry

The Application Template Registry stores a list of all the templates (and their procedures) available to you when building an application. Before the Application Generator can create an application, you must have at least one template registered. For example, to register the default template (CW.TPL):

1.	Choose Setup [image] Template Registry.

The Template Registry dialog appears. This provides a tree view of your templates and their procedure, plus a group of command buttons to maintain the registry.

***	Beta 3 pre-registers its templates. You will not have to register the default templates.

2.	Press the Register button.

The Template File Open File dialog appears. The List Files of Type specification is *.TPL. The default template subdirectory is called Template.

3.	Select the CW.TPL file and press the OK button.

This is the default template file. The CW.TPL file contains the Template Language statements and Clarion Language source code that the application requires to create the defaults for the template.

Tip:	You MUST load SHARE to maintain the Registry. This is subject to change for the release version, but is true for the current beta.


Registry Maintenance

The Template Registry dialog provides command buttons for other file maintenance options for the registry:

UnRegister	This button deletes the currently highlighted template class.

Enable	This button enables the currently highlighted template class or procedure (if you had previously disabled it).

Disable	This button disables the currently highlighted template class or procedure, which makes it unavailable to your application.

ReGenerate	This button regenerates the .TPL file for the currently highlighted template class.

***	Warning: the Regenerate button may not work correctly for Beta 3. If you wish to test it, you may need to restore your template files from a backup. Use with extreme care!

The Template Registry is a two-way tool. Besides allowing you to add procedures to your applications, you can customize the procedures in the template. For example, you can add another default window type to the Browse template. See the following button description, Properties, for instructions on how to edit the template.

When you change the properties for the your template, the changes are stored in your REGISTRY.TRF file. The ReGenerate button reads the file, then rewrites the .TPL file which contained the original template language code. This allows you to customize a template, then give a copy of the .TPL file to another programmer to register.

Properties	This button accesses the Template Procedure dialog or Template Module dialog, according to whether you select a procedure or module in the Template Registry tree.

This allows you to customize a procedure template or module so that you can generate other applications that take advantage of the customization.

For example, (*** as of the Beta 3 release) the Browse template has four default window types. You can add a fifth by pressing the Properties button, then pressing the Insert button in the Window List dialog. You type a name for your new window in the New Window dialog, choose a structure type from the New Structure dialog, then customize the new window with the Window Formatter.

Whenever you create an application using the Browse class in the future, your new window is one of the window types available.

The Adding WINDOWs or REPORTs section below provides a step by step explanation of how to add to a template class.

View Definition	This button displays the Template code (the .TPL) in a text window. You may not edit the code in this window.

If the currently highlighted item in the Template Registry tree is a module, the text window opens to the first line of the MODULE definition. If a procedure, it opens to the first line of the PROCEDURE.

Help	Opens the template help file. When a procedure is the current selection, the Help application opens directly to the procedure help.

***	The above feature is not supported in Beta 3.

Close	Closes the Template Registry dialog.


Customizing Procedure Templates

Any customization you make to a procedure template can be stored for use in a future application. You can add new default global settings, WINDOWs, or any other procedure element. Clarion can regenerate the template based on your customizations.

You can customize any components properties in the template procedure--its global data, its structures--anything you can access in its properties dialog. All you have to do is select a procedure in the Template Registry dialog, and Edit its properties.

As an example the following presents a step-by-step process for adding a WINDOW or REPORT structure to a template procedure.

Adding WINDOWs or REPORTs


Adding WINDOWs or REPORTs

To add a WINDOW or REPORT data structure to a template procedure :

1.	Open the template registry by choosing Setup [image] Template Registry.

2.	Select a procedure within the Template list inside the Template Registry tree.

Not every procedure enables the Window or Report button, because for some procedures it wouldnt make sense.

3.	Press the Properties button to display the Template Procedure Properties dialog.

4.	Press the Window or Report button.

If it already contains a WINDOW structure, the Window List dialog appears, listing the structures already built into the template procedure. The buttons within the dialog allow you to edit an existing window, or create a new one. If not, skip the next step.

5.	Press the Insert button to create a new window or report.

6.	Choose a window or report Type from the New Structure dialog.

The choices derive from the DEFAULTS.CLW file. You can customize these as well. See Adding Default Report Structures, in Using the Report Formatter.

7.	Format the window with the Window Formatter, then Exit the Window Formatter. Or format the report with the Report Formatter, then Exit the Report Formatter.

See the chapters Using the Window Formatter, or Using the Report Formatter for instructions on creating windows and reports with these tools.

8.	Type a title for the new WINDOW or REPORT data structure in the Temporary dialog box, then press the OK button.

*** The name of the Temporary Dialog will change for the release version!

When you access the procedure from the Application Generator, the procedure lists the window or report by this title.

9.	Press OK to close the Window List dialog.

9.	Press OK to close the Template Procedure Properties dialog.


Procedures &Code Templates

Procedure Templates

Adding a Browse Procedure

Adding an External Procedure

Adding a Form Procedure

Adding an Application Frame

***	Beta 3 provides five template procedures, including To Do. Their functions are not yet complete, and template help, mentioned in the next paragraph, is not yet available.

***	For the final release documentation, this chapter will explain what each of the templates do, but also how they do it, and tricks for customizing them with embeded source and code templates. The intent will be to use the explanations as a springboard for teaching new users a little bit about the language, as well as the templates.

***	For the Beta 3 doc, this chapter serves only as a quick outline for filling in the fields in each procedure properties dialog.

The latest information on each template procedure is available through the Template Help button in the Procedure Properties dialog. The following sections provide the most up to date information at press time.

Tip:	  Clarion constantly tweaks the templates based on customer feedback, to improve their functionality. Its a good idea to check in on the CompuServe forum (GO CLARION) every so often, to find out about the latest batch releases, which often contain template improvements.


Procedure Templates

Procedure templates generally require additional information which you fill in either in dialog boxes which automatically appear, and/or in additional fields and controls in the Procedure Properties dialog. This section describes the template procedures which ship with Clarion for Windows.

Each procedure explanation contains only the options unique to the procedure. Explanations for standard buttons and options appear in the Using the Application Generator chapter.


Adding a Browse Procedure

The Browse template procedure puts data in a list box, arranging fields into columns. It automatically adds scroll bars when necessary. There are four default window types which allow you to specify whether to add update buttons and menu selections.

The Browse template automatically creates a new VIEW for each window the end user opens, which resolves operating system problems when a file is opened more than once. You must advise your end users to load SHARE if you wish to support more than one active Browse window at a time.

*** In Beta 3, th this procedure does not yet implement VIEWS.

•	To specify a Browse Procedure:

1.	Select a To Do procedure in the Application Tree dialog and press Edit.

2.	Select Browse from the Select Procedure Type dialog.

3.	Highlight a window type in the Select Window dialog and press the Select button.

•	To complete the custom fields specific to the Procedure Properties dialog for the Browse procedure:

Update Procedure	The name of a procedure the Browse procedure calls when the user updates a record. You do not need to write the source code for the procedure. You can press the Update Calls button, then check the option boxes to specify whether the application should Allow Insert, Allow Change and/or Allow Delete of a record.

Record Filter:	Optionally type a record filter expression.

Locator:	This corresponds to a field which updates a component of the primary file access key. When the user types a letter in the field, the list jumps to the record that most closely matches it.

List Expression:	Optionally type a custom LIST expression.

***	The above is subject to change.

•	To specify a range of records for the Browse, press the Range Limits button. This displays the Range Limits dialog, which helps to dynamically build the range for you:

1.	Type in the name of the Range Limit Field or press the ellipsis (...) button to choose a data file and/or field from the file schematic.

2.	Choose a Range Limit Type from the dropdown list. You may specify a Range of Values, a Single Value, or the Current Value.

3.	Fill in the Low Limit Value and High Limit Value if you specified a Range of Values

or

Fill in the upper Range Limit Value if you specified a Single Value.

•	To customize the Browse window, press the Window button. This calls the Window Formatter, in which you add fields to the list box, and otherwise edit the window. If you do not place any fields, the list box will be empty.

See the Using the Window Formatter chapter for details on customizing a window.

•	To specify a file for the Browse procedure, press the Files button, and select a file from the File Schematic.


Adding an External Procedure

The External procedure template instructs the Application Generator that you wish to use a procedure from an external source, object or library file. The Application Generator does not generate code for the procedure.

•	To specify an External Procedure:

1.	Select a To Do procedure in the Application Tree dialog and press Edit.

2.	Choose External Procedure from the Select Procedure Type dialog and press Select.

3.	Choose either an External Library Module or External Object Module from the Select Module Type dialog and press Select.

4.	In the Procedure Properties dialog, type a prototype for the external procedure.

5.	Choose an external library (*.LIB) or module (*.OBJ) from the Module Name dropdown list.


Adding a Form Procedure

The Form Procedure automatically generates a data entry dialog suitable for adding, changing, or deleting a record from a file defined in the procedures file schematic.

The Form Procedure enforces validity checks and/or referential integrity constraints (*** sorry, not  yet, Beta 3 users). It automatically uses the screen control formatting you specify in the Data Dictionary.

•	To create a Form Procedure:

1.	Select a To Do procedure in the Application Tree dialog and press Edit.

2.	Choose Form from the Select Procedure Type dialog and press Select.

•	To complete the custom fields specific to the Procedure Properties dialog for the Form procedure:

Insert Message	Places a custom message for the end user instead of the default (Record will be added).

Change Message	Places a custom message for the end user instead of the default (Record will be changed).

Delete Message	Places a custom message for the end user instead of the default (Press OK to delete).

Action After Add	The template supports multiple ADDs without closing the dialog.

To immediately return to the calling procedure after the user enters a record, choose Return to Caller.

To allow continuous ADDs without clearing the record buffer or closing the dialog, choose Retain Record. When the user presses the Add button, the record buffer contents are ADDed to the file, and the focus jumps to the first entry field.

To allow continuous ADDs and clear the record buffer and dialog fields between each ADD, choose Clear record.

•	To customize the Form dialog, press the Window button. This calls the Window Formatter, in which you can add entry controls to your window. See the  Using the Window Formatter chapter for details on customizing a window.

•	To specify the data file for the Form procedure, press the Files button, and select a file from the File Schematic.


Adding an Application Frame

The Frame procedure automatically provides an Application Frame window for an MDI application. The window already has a default menu, which includes File [image] Exit, Edit [image] Cut, Copy, and Paste.

You may only include one APPLICATION structure within an application. If your application is an MDI application, the frame includes your program icon and its default title bar.

Tip:	  To provide a Splash Screen, which is an opening window (usually system modal) which contains a bitmap and your copyright, create another procedure which opens and closes that window, then call the procedure Before Opening the Window (the Application Frame window) by pressing the Embedded button in the Procedure Properties dialog for the Frame.

There are no custom fields in the Application Procedure Properties dialog. Most likely, however, you will customize the window menu, which in turn fills in the procedure tree for your application.


Using the Window Formatter

Use the Window Formatter to visually design Window elements--windows and control --on screen. The Window Formatter automatically generates and places the language structures and source code that describe these elements in your source code document.

Overview: Creating Your Applications Windows

Opening the Window Formatter from the Editor

Choosing a Window Type

Window

Window with OK & Cancel

System Modal

MDI Child

MDI Parent Frame

To Customizing Your Applications Windows

Using The Window Properties Dialog

Title

Label

Frame Type

Initial Size

Options

Position

Font

Setting More >>> Window Properties

Icon

Cursor

Help ID

Status Widths

Message

Alert

Timer

Entry Patterns

To Place Controls In a Window

Toolbox

Using the File Menu

VBX Registry

Exit

Using the Edit Menu

Undo

Redo

Properties...

Delete

Duplicate

Set Order

Using the Control Menu

Using the Alignment Menu

Using the Menu Menu

Using the Toolbar Menu

Using the Options Menu

Test

Show Toolbox

Show Alignbox

Grid Settings


Overview: Creating Your Applications Windows

Most likely, your application will use a number of windows to display instructions, accept input, and provide data or other information to the user. Clarions template oriented nature provides you with many pre-drawn windows where all you need do is plug in your data. There will be situations in which you will wish to design a window for the user. In general, this is what you will do to put such a window on the screen:

1.	Select or create a procedure which should display the window.

2.	Within the Application Tree window, DOUBLE-CLICK the procedure name or press the Properties button. This displays the Procedure Properties dialog.

3.	Optionally tie in data or files. To do so, press the Data and the Files buttons and make your choices in the dialog boxes which appear. Return to the Procedure Properties dialog.

4.	Press the Window button. The New Structure dialog appears.

5.	Decide what type of window the procedure should display.  Specify your choice by DOUBLE-CLICKING it, or selecting a choice from the Type list, then pressing the OK button. The Window Formatter appears.

6.	Customize the window by setting its size and properties. This chapter explains how to do this.

7.	Place a menu in the window using the Menu Editor. The next chapter explains how to do this.

8.	Place controls in the window -- these might include entry boxes for editing fields from the database, command button controls, static text containing instructions for the user, and other controls to enhance the appearance of the window. The chapter called Placing Controls explains how to do this.

9.	Return to the Procedure Properties dialog.


Opening the Window Formatter from the Editor

In general, you call the Window Formatter either to create a new window, or to modify an existing window. You cannot create a control without a WINDOW structure.

To create a new window from the text editor, open a source code document, locate a blank line in the data section on which you wish to place the Clarion language STRUCTURE which creates the window, then choose Edit [image] Format Structure from the menu. You may also press the keyboard accelerator, which is CTRL + F.

To edit an existing window STRUCTURE, or to edit an existing control, open the source code file and place the cursor on any line within the structure which describes the specific window. Then choose Edit [image] Format Structure from the menu or press the keyboard accelerator (CTRL+F).

The Window Formatter will appear, containing either a new, blank window, or the window which contains the existing controls.


Choosing a Window Type

The types of windows you may create appear in the New Structure dialog. You maintain the default list in the DEFAULTS.CLW file. You may add or delete your own window and report styles. This section discusses only the defaults.


Window

To create a general purpose document window or dialog box, choose Window. The Window Formatter will generate a (non-MDI) WINDOW structure containing whichever controls you place in the window.


Window with OK & Cancel

To create a dialog box with OK and Cancel buttons, choose Window with OK & Cancel. You may add other controls. The Window Formatter generates a WINDOW structure containing  the OK and Cancel buttons, plus any additional controls you place in the window. You may also delete the OK and Cancel buttons.

At the source code level, the only difference between this choice and the previous one is that the window structure starts out with two additional statements creating the OK and Cancel buttons--there is no difference in the window type itself. Clarion provides this additional choice simply for convenience-- because these two buttons are such common elements in the windows your application will probably require.

Tip:	For most data entry windows, you will use dialog boxes. The window might appear with a single line frame, entry fields for the user to type in the data for a new record, plus the buttons. When the user presses the OK button, the application might add the record; if the user presses the Cancel button, the operation should be abandoned.


System Modal

To create a system modal window, choose System Modal Window. This means the user will not be able to do anything else -- not even switch to another application -- until the window closes. The Window Formatter will generate a WINDOW structure with the MODAL attribute.

Tip:	To signal a critical error, use a system modal window. Windows is a cooperative multitasking environment, in which the user should be in control as much as possible. A system modal window temporarily limits the users freedom, for example, to run another application. Unless your application has a compelling reason to halt all system activity -- for example, a severe file error which might result in lost data unless corrected at once -- limit your applications use of this type of window to the minimum.


MDI Child

To create a document window which will appear inside an application frame, choose MDI child window. The Window Formatter will generate a WINDOW structure with the MDI attribute.

In general, MDI--the Multiple Document Interface--provides a platform for presenting and editing more than one document within a single application. Each document appears in a child window, inside the main application window. The child window typically appears as a normal window, with frame, system menu, maximize and minimize buttons, and icon. The user should be able to manipulate it like any other window--except that the child window cannot move outside the main application window. A typical use of an MDI window might be to present a different view of your applications database.

All MDI windows must reside in separate procedures from the APPLICATION window (see below). This allows the Application Generator to use the START function for the MDI procedure, to begin a new execution thread for the MDI window. You may place more than one MDI window in the thread.

Once in the Window Formatter, any menus and toolbars you create for the MDI window will merge with the APPLICATIONs menu and toolbar when the MDI child is the active window.


MDI Parent Frame

To create the APPLICATION frame, or main window for an MDI application, choose MDI Parent Frame. This provides the outside frame in which the MDI child windows appear.

Tip:	Typically, the APPLICATION window should have a resizeable frame, plus a system menu, maximize and minimize buttons and a menu. Usually, the File menu should provide a command to open or create MDI child windows, and a Window menu should provide commands for managing the separate child windows.

The APPLICATION window should not have controls inside the window--in fact, Clarion will not allow you to place any there. MDI child windows contain all controls in an MDI application. The APPLICATION window should hold only the child windows, and optionally, a toolbar.

Place any global menu commands or toolbar controls in the APPLICATION window. Each child window inherits these, may add additional items, or enable and disable global commands anbd toolbar controls as necessary.

The APPLICATION window and its MDI children must not reside in the same procedure. This allows for a separate START function, so that the MDI child runs in a separate thread. Multiple MDI windows may run in the same thread, though not the same one as the APPLICATION.

When the APPLICATION window statement executes, Clarion hides the window until it encounters the first DISPLAY statement or ACCEPT loop. This allows your application to make any cosmetic changes to the APPLICATION window before the user sees it.


To Customizing Your Applications Windows

Once you specify the type of window to create, the Window Formatter appears. It contains three major components to help you create or edit your window.

Sample Window	The Window Formatter is a visual design tool. You always see a sample of the window youre working on, as you work on it. When you create a new window, for example, you see an empty window with a caption bar labeled Caption.

Toolbar	The Window Formatters tool bar contains important command buttons and options which allow you, amongst other options,  to view the window or control properties dialogs, or to test exactly how the window will look and act for the user.

Controls Toolbox	The Window Formatter contains a floating toolbox, similar to drawing or paintbrush programs. You may choose a control from the toolboxand click in the sample window to add it to the window youre creating or editing.

The Window Formatter lets you directly manipulate the window and the controls inside it. The initial sample window, for example, contains handles -- the small black boxes located at the corners and sides of the window. By selecting a corner and dragging the mouse, you may resize the sample window. The window the user sees when your application runs is the same size as the window you create by dragging.

When the Window Formatter generates the source code for the window, it places the data determining the size and position of the window (as you specified by dragging the mouse) in the AT attribute of the WINDOW or APPLICATION statements creating the window.

Similarly, The Window Formatter fills in the other attributes by presenting you with options, checkboxes and fields in which you specify your preferences.

The typical process for customizing a new window with the Window Formatter:

1.	Drag the handles so that the sample window is the size you wish.

2.	Optionally drag the caption bar of the sample window so that the window is in the location you wish. You may alternatively let Windows place the window at a default position when the application runs.

3.	DOUBLE-CLICK the window or press the Properties button on the Window Formatter toolbar to fill in the Window Properties dialog.

4.	Click the buttons along the right side of the Window Properties dialog to set additional properties, such as Font, and Position.

5.	Close the Window Properties dialog.

6.	Place controls in the window (covered in the next chapter).

7.	Test the window by pressing the Test button; then make any adjustments necessary while still in the Window Formatter.

8.	Press the Exit button on the Window Formatter toolbar to return to the Application Generator or editor.


Using The Window Properties Dialog

To display the Window Properties dialog you may:

•	DOUBLE-CLICK on a sample window

•	Select the sample window and press the Properties button on the Window Formatter toolbar

•	Select the sample window and choose Edit [image] Properties from the menu.

•	Select the sample window and press ENTER

Each window type choice in the New Structure dialog leads to the Window Properties dialog. Depending on the window type you select, the default values in the dialog will differ.


Title

To specify caption bar text, type a string constant in the Title field. The caption bar holds the name of the window.

Tip:	You may dynamically alter the caption bar text at runtime. The most common example is that of an application which places an open file name next to the application name on the title bar; for example, Notepad - FileName.TXT. You must reassign the title property. For example:

?MyWindowLabel{PROP:title} = StringConstant & FileNameVariable

If you create a system modal window, leave the caption bar blank. The normal Windows style for this type of window is to display the window without a caption bar.


Label

To specify the label for the window, type it in the Label field. This names the specific WINDOW in the source code. The label may contain upper or lower case letters, numerals, the underscore character or a colon. Space characters are forbidden. The first character must be a letter or the underscore character. Clarion reserved words may not serve as labels.


Frame Type

To choose the frame for your window, pick a selection from the Frame Type drop-down list. The frame defines the borders of the window. The selections are:

Single	A single pixel frame which the user cannot resize. Most suitable for dialog boxes.

Double	A thick frame, which the user cannot resize. Use this type frame for a system modal window (without a caption bar), or for a modal dialog box (with a caption bar).

Resizeable	A thick frame, which the user can resize. Choose this for application and MDI child windows.


Initial Size

To specify the initial size and state of your window, choose an option from the Initial Size drop-down list. The choices are:

Normal	Display the window at the default size which either you specifically set, or Windows sets if you dont.

Maximized	The window fills the desktop, if an application window, or the window frame, if an MDI child window.

Iconized	The window appears in iconized state--as a 32 by 32 pixel window at the bottom of the desktop (application window) or at the inside bottom of the application frame (MDI child window).

Tip:	If you choose the iconized selection, be sure to specify  a file name in the Icon field. If not, your window may not receive a Restore command on its system menu, which means it always will remain iconized. Specifying a file name also adds a minimize button to the window, allowing the user to iconize the window again, after restoring it.


Options

Various toggle choices appear at the bottom of the Window Properties dialog:

System Menu	To place a system menu in your window, mark the System Menu checkbox. Every application window should have a system menu. For users on a system without a mouse, the system menu provides the only means of minimizing, maximizing or re-sizing the application window.

Tip:	Even if you plan that the window should NOT have a system menu when the application is complete, its good practice to place a system menu on your application while its under development. By DOUBLE-CLICKING the system menu, or choosing Close, you can close your application should your normal exit procedure not yet work.

Tip:	Even if not absolutely necessary, a system menu serves as an added convenience for dialog boxes. Many users automatically DOUBLE-CLICK on the system menu box to close a dialog--since it always resides in a standard location, its sometimes easier to find than a Cancel button.

Maximize Box	To place a maximize button in your window, mark the Maximize Box checkbox. In general, you should place a maximize button only on application windows and MDI child document windows.

3d Look	To provide the gray window background, chiseled control look for your application, mark the 3d Look checkbox. This is clearly a style consideration, but will go a long way in giving your application a professional look.

The gray background is not visible when you design your window with the Window Formatter. It is, however, visible in test mode, and when your application runs.

Status Bar	To provide a message bar at the bottom of your window, mark the Status Bar checkbox.

Tip:	A status bar in an application window is an excellent way to increase user feedback in your application. Clarion makes it simple to post messages on the status bar advising the user of what your application is doing as it does it. Increasing user feedback makes the user feel more in control. This allows the user to feel more confident and be more efficient when using your application.

Modal Window	To specify a system modal window, mark the Modal Window checkbox. This option will appear checked when you choose System Modal Window from the New Structure dialog.

A system modal window prevents all other tasks--even in applications other than your own--from executing until the window is closed.

MDI Child	To specify an MDI child window, mark the MDI Child checkbox. The child window cannot move outside the main application window. A typical use of an MDI window might be to present a different arrangement of the data in your applications database.

Horizontal Scroll	To add a horizontal scroll bar to your window, mark the Horizontal checkbox.

Vertical Scroll	To add a vertical scroll bar to your window, check the Vertical checkbox.


Position

The Position button displays the Position dialog, which allows you to specify the AT() attribute for your window. Filling in the AT attribute manually is optional -- you may set your window size visually, dragging with the mouse in the Window Formatter.

To set a precise screen location or size for your window, specify fixed coordinates via this dialog. To set the window location and size:

Default	This instructs Windows to set the X and/or Y positions of the upper left corner of the window to a default value which will depend on the users system and how many other applications are running.

Tip:	To give your application the standard look of other Windows applications, where possible specify the Default setting for any windows with resizable frames.

Center	Places the window in the middle of the desktop. You may choose horizontal or vertical centering, or both.

Fixed	To set a specific position and size, first mark the Fixed choices for the X and Y coordinates. This sets the upper left corner of the window, relative to the desktop. Then, check the Fixed choices for Width and Height, which define the width and height of your window.

The default measurement units for these boxes are dialog units. Specifying a number without a measurement type indicates the measure is in dialog units. These are the possible measurement units:

Dialog Units	These provide a relative screen measure. Dialog units are a relative measure based on the default system font character size. Windows automatically repositions the control proportionally at different screen resolutions.

Thousandths Inches	These provide a relative screen measure based on the logical screen measurement. Directly dependent upon the screen driver; the default is 72 pixels = one inch when the current system font is the VGA font. The default is 96 pixels = one inch when the system font is from the 8514/a set.

Millimeters	These are also based on the logical screen measurement. The default is 28.3 pixels = one centimeter (VGA system font) or 37.8 pixels = one centimeter (8514/a system font).

Points	These provide a relative screen measure based on the logical screen measurement. One point = 1/72nd  logical screen inch.

Full Width	Specifies the application should fill the desktop or application frames horizontal dimension.

Full Height	Specifies the application should fill the desktop or applications vertical dimension.


Font

To set the default font for all controls appearing in the window, press the Font button. You may override the default by setting a different font in the Properties dialog for any specific control.

When you press the Font button, the Select Font dialog appears. Make your choices within this dialog; the Window Formatter places your choice in the FONT attribute of the WINDOW.

The Select Font dialog is the standard windows dialog. Select a typeface by choosing from the Font list. Select a style by choosing from the Font Style list. Select a point size from the Size list. Select Strikeout or Underline effects from the Effects box. Choose a text color from the Color drop-down list.


Setting More >>> Window Properties

To unfold the Window Properties dialog to display more choices, press the More >>> button. This allows you to set additional attributes for the WINDOW.


Icon

To associate an icon with the window, specify an icon in this field. You may type in a file name or an EQUATE. You may also press the ellipsis button (...), then select an icon file name using the standard Open File dialog.

You should always specify an icon for an application window, and for an MDI child window. Specifying an icon name automatically places a minimize button on the caption bar of your application or MDI child window.


Cursor

To specify a cursor for the window, choose a cursor from the dropdown list, or type in the name of a .CUR file. When the user passes the mouse over the window, the cursor takes the shape you specify. Controls within the window automatically inherit the same cursor unless you choose to override it.

Tip:	See the Windows Design chapter for tips on when to use each cursor.


Help ID

To associate a Help ID with the window, fill in a keyword or context string, (preface the context string with a tilde ~ character), in the Help ID field. This fills in the HLP attribute for the window.

When the user calls Windows Help while the window is active, it opens to the associated topic. Should you set a Help ID for individual controls within the window, they override the windows Help ID while the control has the focus.

Note:	You must author your windows help file using a separate tool such as Microsoft Word for Windows™. You must compile the help file with the Windows Help Compiler, which is available from Microsoft.


Status Widths

To set the width of the status bar zone(s), type a value or list of values in the Status Widths field. You must also check the Status Bar box in the top part of the Window Properties dialog to display a status bar. The values you enter in this field fill the STATUS() attribute parameters.

The zones are the areas within the status bar marked off by the 3D shaded boxes. The first zone on the left, by default, displays MSG attribute text. This is useful for specifying short help instructions or other information to the user. If your application has only one zone for the status bar, you may omit this field. For more than one zone, enter a series of comma separated values. The default measurement unit is dialog units.

You may set a minimum value for a zone width by typing a negative number. This creates a zone with a minimum width, but is expandable by resizing the window. Use the runtime property assignment syntax to place text in any zone. To place a string in the second zone, for example: {PROP:StatusText} = ?array.

Tip:	A multi-zone status bar can give your application a professional look. You may display help text in zone one, and when editing a record, the current record number in zone two, for example.


Message

To display a string in zone one of the status bar when the window is active, type the string in the Message field. The fills in the MSG attribute for the window. You may override the message by filling in the field for any individual fields within the window.


Alert

To specify a hot key active when the window has focus, press the Alert... button. The Select Alert Keys dialog appears.

When the ALRT attribute is set, the window generates an EVENT:AlertKey if the user presses the Alert key while the window has the focus. A window has focus when it is the active window.

To specify the first Alert key, choose a Key from the drop-down list, add a modifier, if applicable, by checking Ctrl, Alt and/or Shift, then press the Add button. The key combination appears in the List.

Repeat for any additional Alert keys. To delete an Alert, highlight the key combination in the List, then press the Remove button.


Timer

To specify the window receive Timer Event messages from Windows, fill in the Timer field. Specify the timer interval in hundredths of seconds.

For example, if you specify 100 in the field, the window will automatically receive an EVENT:Timer once every second (100/100s seconds). This might be appropriate for adding a clock to a status bar.

Tip:	There is an important limitation on the use of timers: Windows only allows a maximum of sixteen timers to be active at one time. This includes those in use by other applications. Therefore, use timers sparingly.


Entry Patterns

To specify an entry mask for all the controls in the window, check the Entry Patterns box.

*** this is not working correctly in Beta 3.


To Place Controls In a Window

This explains how to place a control in a window. The Setting Control Properties chapter explains how to customize the controls you place in your windows.

Toolbox

Using the File Menu

VBX Registry

Exit

Using the Edit Menu

Undo

Redo

Properties...

Delete

Duplicate

Set Order

Using the Control Menu

Using the Alignment Menu

Using the Menu Menu

Using the Toolbar Menu

Using the Options Menu

Test

Show Toolbox

Show Alignbox

Grid Settings


Toolbox

The Toolbox appears when you start the Window Formatter. It works exactly like a palette of drawing tools, such as the toolbox in the Windows Paintbrush accessory. To place a control:

1.	CLICK on an icon in the toolbox. Each control has its own icon.

2.	CLICK inside the window you wish to add the control to. The place where you click will be the upper left hand corner of the control.

3.	If necessary, drag on a control handle to resize the control. You may also drag the inside of the control to move it.


Using the File Menu

When you use the Window Formatter, the IDE menus change. The revised File menu allows you to access the .VBX custom control registry, and to exit the Windows Formatter.


VBX Registry

To add a custom control library to the registry, choose the VBX Custom Control Registry command. Press the Add button in the VBX Custom Control Registry dialog. Then DOUBLECLICK on the .VBX file name.

This enables the Window Formatter to place controls from the library in your window (see following chapter). To remove a registration, press the Remove button.


Exit

To exit the Window Formatter, choose the Exit command.


Using the Edit Menu

The Edit menu allows you to manipulate the controls in the window.


Undo

To reverse the last editing action, choose the Undo command. Not all actions may be reversed.


Redo

To re-do the un-done action, choose the Redo command. Not all actions may be re-done.


Properties...

To edit control or window properties, select a control or window, and choose the Properties... command. You may also double-click a control or window, or select it and press the Properties button on the Window Formatter toolbar, or select it and press enter.

This chapter details the properties you may edit for a window. The following chapter details the properties you may edit for a control.


Delete

To delete a control or window, select it and choose the Delete command, or select it and press the delete key.


Duplicate

To place another copy of a control in the same window, select the original and choose the Duplicate command. The copy will appear next to the original.


Set Order

To set the tab key order, choose the SetOrder command, then indicate the order by clicking on the controls.

The tab key order refers to the order in which each control will receive the focus (or become active) as the user presses the TAB key. In general, it is best to design the order from left to right, top to bottom, because that is the way that most people read.

When you execute the command, number boxes appear next to each control. CLICK on the controls in the order you wish the tab sequence to occur. The numbers update themselves to reflect the order as you CLICK.


Using the Control Menu

The Control menu lists the controls that appear in the Toolbox. Executing a command from the Control menu is identical to clicking on a tool. The menu serves as a convenience.

For a list of toolbox controls, see above.


Using the Alignment Menu

The Alignment menu provides commands for spacing and sizing the controls within the window. You may place two or more controls so that their edges match up with each other. You may also spread the controls out, or make all of them the same size.

To do so, first select two or more controls. Select the first by clicking on it. Select the second and susequent controls by pressing the SHIFT key, then clicking on the second control while the shift key remains pressed.

The choices on the menu allow you to align the controls along the Left, Right, Top and Bottom edges. You may also center the controls along the center, on either the Horizontal or Vertical axes.

You may also spread out the controls. To do so, select the controls, then choose Spread Horizontally, or Spread Vertically.

Finally, you may automatically resize the controls so that they are all the same size. To do so, select the controls, then choose Make Same Size. Note: the control with the red handles is the master alignment key.


Using the Menu Menu

The Menu menu provides a menu editor to provide a user menu for your window.

Specify a menu for your application window, or for MDI child windows. Clarion automatically merges the application window menu with the MDI child menu when an MDI child window has the focus. This saves you the trouble of enabling, disabling, inserting and replacing various menus dependent on which window has the focus.

Please see the next chapter for directions on how to create menus and toolbars for your application.


Using the Toolbar Menu

The Toolbar menu provides a toolbar editor to provide a toolbar for your window.

Specify a menu for your application window, or for MDI child windows. Clarion automatically merges the application window menu with the MDI child menu when an MDI child window has the focus. This saves you the trouble of enabling, disabling, inserting and replacing various menus dependent on which window has the focus.

Please see the next chapter for directions on how to create menus and toolbars for your application.


Using the Options Menu

The Options menu allows you to change the formatting options, plus enter testing mode, which allows you to see precisely how your formatting will look to the user.


Test

To display an active window identical to the one that your user will see, choose the Test command. The only difference is that it wont contain live data, and command buttons wont execute commands.

Tip:	You should always test your windows and dialog boxes. Though the Window Formatter is visual, it does not show you how 3D shading will affect the look of your window, nor does it actually hide a hidden control. Additionally, you may test the tab order while in Test mode to verify the current order makes sense.

The Test command works exactly the same as the Test button on the toolbar.


Show Toolbox

To toggle the toolbox display on and off, choose the Show Toolbox command.

When designing large windows, it may be useful to hide the toolbox, gaining additional room for the window. You may still access all the control tools by choosing them from the Control menu.


Show Alignbox

To toggle the Alignbox on and off, choose the Show Alignbox command.

This is a matter of individual preference. You may still access all the alignment commands by choosing them from the Alignment menu.


Grid Settings

To turn on grid snap, as well as setting the grid values, choose the Grid Settings command.

Grid snap forces the upper left corner of new controls to align with a dot grid in the window. The user does not see the grid. To turn grid snap on, check the Snap to Grid box.

Tip:	Aligning the controls in your dialog boxes and windows will give your application a more professional look. See the appendix on Windows Design for specific suggestions on how to align different types of controls.

To set the width and height spacing between the grid dots, enter values in the Width and Height fields in the Grid Settings dialog. The values must be in dialog units.


Creating Menus and Toolbars

To create a menu for your application, use the Menu Editor. Access to the Menu Editor is through the Window Formatter. You may also create a toolbar for your application using the Window Formatter. You may place any type of control on your toolbar, though you will probably prefer to use 3D buttons.

Calling the Menu Editor

Creating Your Apps Menu

First Command

Adding Commands

Add a Menu

Final Steps

Menu Editor Commands and Options

Menu

Item

Separator

Delete

Name

Use

MSG

Stdid

Flags

Position Options

Creating MDI Menus

Adding a Toolbar

First Button

Button Group

Final Steps

MDI Toolbars


Calling the Menu Editor

To call the menu editor from within the Window Formatter, choose Menu [image] New Menu. To call the menu editor to edit an existing menu, select the window, and choose Menu [image] Menu Editor.

The Menu Editor dialog displays a menu tree structure on the left. Command buttons to add or delete menu items appear at the upper right. The right hand side also contains fields to type the titles of your menu items, and to link them to executable code.

The menu tree format (on the left) looks like simplified Clarion language syntax:

•	A temporary label (MainMenu) at the top. You may not change the label while in the Menu Editor.

*** last item subject to change

•	A MENU statement followed by a menu name.

•	An ITEM statement followed by a command name.

•	Optionally, additional ITEM statements.

•	Optionally, a nested MENU statement. Following a MENU statement, but coming before an END statement, this produces a cascading menu when the user highlights the ITEM preceding it.

•	An END statement for the first MENU.

•	Optionally, any additional MENUs.

•	An END statement for the temporary label.

The next section provides you with a step by step summary procedure for creating a menu. Following that are sections detailing the Menu Editor Commands and Options, and a discussion of considerations to keep in mind when creating MDI application menus.


Creating Your Apps Menu

Here are the steps for creating a menu starting from a fresh window within the Window Formatter.


First Command

This covers starting the Menu Editor and creating a single menu command.

1.	Choose the Menu [image] New Menu command.

The Menu Editor dialog appears, with the first menu title highlighted. The first menus temporary menu title is &Menu.

The ampersand before the menu name signifies that the letter following the ampersand should be the accelerator key, which appears underlined to the user.

2..	Click on the first Item line in the left hand side of the dialog, below the first Menu line. This selects the first menu command for editing.

This first Item occupies the bottom command positon on the rightmost menu of the application. The Menu Editor adds new items above the current selection. This means you may save mouse clicks by creating your menu last to first.

***	The above is subject to change

3.	Type a string in the Name field at the right side of the dialog box.

This will be the command as it appears to the user. Be sure to indicate the accelerator key by using the ampersand.

4.	Type a field equate label in the Use field.

This will be how the source code refers to the command. For example, assume a field equate of ?MyFileNew. Within the ACCEPT loop, the OF ?MyFileNew statement will branch program execution when the menu command is executed.

Alternatively, type in a variable name. If you check the Toggle checkbox for the ITEM, you may reference a numeric value. The Menu Editor adds the CHECK attribute.

When the user toggles the command on, the variables value will be 1. When off, the variables value will be 0. You may then add the source code to execute depending on the state of the variable.

5.	Type the MSG attribute contents in the MSG field.

This text displays in the status bar (if enabled) when the user highlights the menu command.

6.	Type a Standard ID, if applicable, in the Stdid field.

There are STDs available for twelve common menu commands. Using a standard command action saves the trouble of coding it. Clarion will automatically implement the action for you. The standard commands available are: Edit/Undo, Cut, Copy, Paste and Clear; Window/Tile, Cascade, Arrange Icons and the Window list; Help/Contents, Index and Help on Help.

The format for entering a standard command is STD:Copy, for example. You may omit the USE field if you never intend to disable the command.

7.	Set optional Flags.

These allow you to enable or disable the command, plus add or subtract a checkmark next to the command. You will usually check or uncheck these boxes when creating MDI child window menus. See the section on MDI menus below.

8.	Set an optional Position.

This allows you to define a specific item as First or Last when merging this menu, as in, for example, an MDI application frame menu and an MDI child window menu.


Adding Commands

This covers adding additonal commands to the same menu.

1.	Press the Item button.

This inserts a new item above the previous one. This will appear above the last item when the user sees the menu, )which is why this step-by-step procedure is in the order of last command to first).

2.	Repeat steps 3 through 9 above to add additional commands.

3.	Optionally add a Separator bar.

Press the Separator button to add a separator above the current command item. This is useful to provide the user a visual cue that a group of commands on the menu, separated from other commands, perform related functions.


Add a Menu

This covers adding an additional menu.

1.	Press the Menu button.

This inserts a new menu line.

2.	Type a string in the Name field at the right side of the dialog box.

This is the menu name as it appears to the user. Be sure to indicate the accelerator by using the ampersand.

3.	Type a field equate label in the Use field.

This is how the source code refers to the menu.

4.	Type the MSG attribute contents in the MSG field.

This text displays in the status bar (if enabled) when the user highlights the menu command.

3.	Optionally choose a menu Positon.

This allows you to define a specific menu as First or Last when merging with another menu, as in, for example, an MDI application frame menu and an MDI child window menu.


Final Steps

This adds the last items to the menu and covers testing its appearance.

1.	Press the Item button.

This inserts an item above the previous menu. This item takes the last place on the menu whose MENU statement appears above it.

2.	Fill in the fields associated with the Item.

3.	Highlight the MENU statement on the line above. Type the appropriate information in the associated fields.

4.	Press the Close button.

This returns you to the Window Formatter.

5.	Press the Test button on the Window Formatter Toolbar.

This makes the window, including menu, appear as it would to the user. Test the menu by pulling down its options. Press ESCAPE when done testing.

6.	Press the Exit button if the menu is satisfactory. If not, choose Menu [image] Menu Editor to edit the menu.


Menu Editor Commands and Options

The command buttons and fields on the right side of the dialog act on the currently highlighted line on the left. The following commands and fields are available:


Menu

To add a new menu above the highlighted line, press the Menu button. This inserts a MENU and END statement, ready for editing.

Tip:	Work backwards when creating your menu -- from the last menu command to the first menu title. Each new menu or menu item pushes the previous entries down the list. To add an entry below the last entry you typed, you must first move the highlight bar to the line below the last entry. If, however, you enter all your menus and commands from last to first, it will save changing the highlight.

***	The way the Menu Editor inserts above the current line will change as soon as possible.


Item

To add a new menu command above the currently highlighted line, press the Item button. This inserts an ITEM statement, ready for editing.


Separator

To add a separator bar above the currently selected line, press the Separator button. These are the lines which divide sections of a pulldown menu.

Tip:	When you design your menu, group similar commands together. If more than one group appears on the same menu, place a separator between them.


Delete

To delete the currently highlighted menu or menu command, press the Delete button. Should you delete a MENU statement, it will also remove any nested ITEMs and the END statement.


Name

To specify the text which will appear on the menu or menu command, type it in the Name field.

To create an accelerator key and automatically enable support for it, place an ampersand (&) before the letter you wish. Remember not to duplicate mnemonic keys within the menu titles, nor within the pulldown menu items.


Use

To specify the field equate label, by which you will reference the menu selection in your source code, type it in the Use field.


MSG

To specify text to appear in zone one of the status bar when the menu is highlighted, type it in the MSG box. This can be very helpful to the user who may be new to your application.


Stdid

To specify a standard action for your menu item, enter one of the equates (listed below) in the Stdid box. Clarion will automatically implement the command in the background; you do not need any other support for it in your code.

The following standard actions are available. Type the label in the left column in the Stdid field to implement it:

Edit Menu

STD:Undo	Reverses the last editing action.

STD:Cut	Deletes selection, copies to clipboard.

STD:Copy	Copies selection to clipboard.

STD:Paste	Pastes clipboard contents at the insertion point.

STD:Clear	Deletes selection.

Window Menu

STD:TileWindow	Arranges child windows edge to edge.

STD:CascadeWindow	Arranges child windows so all title bars are visible.

STD:ArrangeIcons	Arranges iconized child windows.

STD:WindowList	Adds child window names to menu.

Help Menu

STD:Help	Opens .HLP file to the contents page.

STD:HelpIndex	Opens .HLP file to the index

STD:HelpOnHelp	Opens Microsofts .HLP file for the Windows Help system.


Flags

The Flags group provides options for modifying menu or command behavior.

Enabled	To enable the menu (make it available to the user), check the Enabled box. This is the default.

Disabled	To disable the menu (gray the text and make it unavailable to the user), check the Disabled box. This adds the DISABLE attribute to the MENU or ITEM statement.

Tip:	The Disabled box is handy when creating menus for child MDI windows. If you incorporate modality into the program -- when one type of child window does not support commands another type does -- build a separate menu structure for each MDI child type. For the type that doesnt support the command, rather than deleting the command from that menu, disable it. This will avoid disconcerting the user with disappearing menu commands which reappear when another window is clicked.

Toggle	Check the Toggle box to add an on/off checkmark next to the command item when it appears on the menu. This adds the CHECK attribute to the MENU or ITEM statement.

When using the Toggle box, you must place a variable name in the USE field. At runtime, when the variable is set to 0, the checkmark will not appear on the menu. When set to 1, a checkmark will appear next to the command.

No Merge	To add the NOMERGE attribute to the menu, mark the checkbox. Specifies that the MDI child menu should not merge with the parent menu, and should replace it, instead. See the Creating MDI Menus section, below.


Position Options

The Positions options allows you to specify menu layout when merging menus.

Normal	For normal menu ordering. The default is from first to last, left to right.

First	To force the menu or command to the top position when merging menus, check the First box. This adds the FIRST attribute to the MENU or ITEM statement.

Last	To force the menu or command to the bottom position when merging menus, check the Last box. This adds the LAST attribute to the MENU or ITEM statement.


Creating MDI Menus

Multiple Document Interface applications make special demands upon a program. Often, the program may support a variety of document windows, each of which has a slightly different set of commands from which the user may select.

Normally in this situation, the programmer writes code to monitor which window is active, then changes the menu and toolbar to reflect the options available to the user. Clarion does this automatically.

To create menus for MDI applications:

1.	Create a master menu for the application frame window. Most likely, this would include only a File and a Help menu, since these are usually the only two menus available even when no document windows are open.

Be sure to check the FIRST attribute for the File menu, and the LAST attribute for the Help menu. This ensures that when Clarion merges the child window menus, they will keep their correct positions.

2.	Exit the Menu Editor and save the menu.

3.	Plan the additional menus for the child windows. Can they all share the same menu titles? Do they share many of the same commands?

Ideally, most of the menus and commands can be active in all the child windows. If there are only a few commands specific to certain windows, plan on allowing the user to see the command all the time, disabled in windows which dont support it, enabled in those which do.

4.	Create the first menu for the first child window. Start with the document-specific menus the application frame lacks -- such as Edit, Insert, etc.

5.	Add commands to the menu. If any command should not be available when this type of  window is active, check the Disabled box.

6.	Repeat the last two steps for other child window menus.

7.	Add the Window menu to the child window menu.

In many cases standard IDs (Stdids) can implement the entire menu. This includes an automatic document list. This lists all open child windows, easily allowing the user to switch between them.

8.	Does the child window require additional commands on the File menu?

For example, adding the Close command might be apropriate. If so, add the File menu to the first child window. Include all the commands on the application frame window, plus additional commands (such as Close) you may have left off it.

Do the additional child windows require additional menus? If so add them. If not, re-create the same menu as the other child window(s). Enable commands appropriate to this window which were disabled in other windows. Disable commands which should not be available in this window.

9.	Exit the Menu Editor and save the menu.

At run time, when you create a child window, it will add its menus to the application frame.


Adding a Toolbar

You may add a toolbar to any window with a simple command in the Window Formatter. You may place any control on a toolbar, though the ones you will probably add the most are check boxes with the ICON attribute, radio buttons with a 3D look, command buttons, and drop-down list boxes.

MDI child window toolbars merge with the application frame toolbar in exactly the same way as MDI child window menus merge with the application frame menu.

The following chapter provides more information on Control Properties dialogs; this section will only discuss them as they relate to toolbox controls.


First Button

The following describes how to add an toolbar to a window, beginning with the first button. The starting point is the Window Formatter, open to a fresh window:

1.	From the Toolbar menu, choose New Toolbar.

A rectangular area appears at the top of the window. This is the toolbar. At runtime, it will appear dark gray.

2.	Optionally check the Grid snap box on the Window Formatter toolbar. This makes sizing and placing the controls easier.

3.	To place a latched button (which stays depressed when clicked), CLICK on the Check Box control icon in the toolbox, then CLICK on the left side of the toolbar under construction-- approximately where the first button should appear.

The Check Box Properties dialog appears. A button created from a check box control has two modes: on or off.

4.	Type in the name of a numeric variable in the Use field.

When the checkbox is on (it appears pushed in to the user), the value of the variable will be one. When off, it will be zero.

5.	Choose an icon for the button.

This will provide a 3D look for the button as well as supplying a bitmap. Open the drop-down list for the Icon field. This provides standard bitmaps for such commands as File [image] New. Choose one, or type in the name of an external icon file.

6.	Press the OK button.

The button is complete; you need only adjust the position by dragging its center, if necessary.


Button Group

A button group provides the user with mutually exclusive choices. In, for example, a group of three buttons, only one can be depressed. If button number two is currently depressed, push in button number one, and button number two pops out. A group of buttons can provide controls, for example, for left, right and center text justification--only one option can be active at a time.

To create a button group, use radio button controls.

1.	To begin placing the button group, click on the Radio button control icon in the toolbox, then click to the right of the button previously placed.

The Option Properties dialog appears. A group box--an OPTION structure--must always surround the radio button choices. The Window Formatter automatically prompts you to create this. The group box will not appear on the toolbar, because you will hide it.

2.	Uncheck the Boxed check box.

This hides the group box from the user. It appears on the screen while youre still in layout mode, but will not appear when youre in test mode.

3.	Type a variable name in the Use field.

The Use field (the USE attribute) takes the label of a string variable to receive the users selection--the string you type in the Button Text field for each radio button.

4.	Press the OK button.

The Radio Button Properties dialog appears immediately.

5.	Type a string signifying the choice in the Button Text field.

When the user selects a button, this string will fill the USE variable.

6.	Choose an icon for the button.

This provides a 3D look for the button as well as supplying a bitmap. Open the drop-down list for the Icon field. This provides standard bitmaps for such commands as File [image] New. Choose one, or type in the name of an external icon file.

7.	Press the OK button.

The button is complete; you need only adjust the position by dragging its center, if necessary.

8.	Click on the Radio button control icon in the toolbox again, then click to the right of the button previously placed.

The Radio Button Properties dialog appears again. Repeat all entries as for the previous button. Repeat this procedure for as many icons as you wish for this group.


Final Steps

This covers testing the toolbars appearance.

1.	Press the Test button on the Window Formatters Toolbar.

This makes the window, including the toolbar, appear as it would to the user. The toolbar buttons now appear against a gray background. Test the toolbar by pushing buttons. Press ESCAPE when done testing.

2.	Press the Exit button if the toolbar is satisfactory.


MDI Toolbars

When you specify a toolbar for an MDI child window, it merges the application frames toolbar at runtime. This will allow you to enable, disable, or replace controls as different MDI child windows get the focus.

***	This section will be completed at a later date.


Setting Control Properties

Overview: Types of Controls

Setting Common Control Attributes

USE( )

AT( )

KEY( )

ALRT( )

FONT( )

Button or Action Controls

Push Button

Option Buttons

Choice Controls

Radio Buttons

Check Box

List Box

Combo Box

Spin Box

Entry Controls

Entry Box

Text

Static Controls

String

Variable String

Prompt

Group Box

Ellipse

Image (Icon)

Box

Region

Line

Custom Control Properties

Registering Your .VBX Custom Control Libraries

Adding a Custom Control to a Window

Setting and Retrieving Visual Basic Control Properties


Overview: Types of Controls

For the Clarion programmer, controls generally fall into these categories:

•	Action controls--BUTTON--lead to an instantaneous result. This might involve closing a dialog box and completing the operations contained in it. Clarion also supports associating a continuous action with a button. For the user, this means pressing the button and holding it down is the same as clicking the button repeatedly.

•	User Choice controls--RADIO and LIST--allow data entry, such as choosing from a group of possible alternatives, without requiring keyboard input from the user.

•	Entry controls--ENTRY--allow data entry from the keyboard. Clarion controls provide extensive options for automatically checking user data entry.

•	Static controls--such as PROMPT--dont perform an action, but instead guide the user to other controls. They can take the form of a group box, which visually relates other controls, or they may be graphical, such as lines or images.

•	Custom controls--.VBX controls--are add-in controls from third party vendors. These may perform a very wide variety of tasks.


Setting Common Control Attributes

The attributes you add to a control determine how the control will look and act. Different controls support different functions, and so require different attributes. All Clarion controls allow you to set two common attributes: USE and AT. Additionally, most controls allow you to set KEY, ALRT, and FONT attributes. This section will explain how to set these common properties.

You will find the Use field in the main portion of all the control properties dialogs. You may see the others by pressing the More>>> button in the control property dialog, then pressing the individual button in the expanded portion of the dialog.


USE( )

The compiler references each control by number. Certain Clarion language statements allow you to reference individual controls by this reference. To make it easier for you to identify the control, rather than find the number, you may define a USE variable for each control.

We suggest using a meaningful string for the USE variable, such as LastNameEntry, OvertimeCheckBox, or HourlyWageSpinBox. To enter the variable, type it in the Use: field in the properties dialog:

Once you define the USE variable, you may refer to the control in executable code. Within a statement, a question mark (?) precedes the reference; in this form it is called a Field Equate Label. For example, you may want to DISABLE an entry control in situations when it should be unavailable to the user. For example, if a user chooses an option box that identifies an employee as managerial level, you may wish to disable the OvertimeCheckBox:

DISABLE(?OvertimeCheckBox)


AT( )

The Windows Formatter allows you to visually set the position and size of each control simply by dragging it wherever you want. You may also specify position by manually typing coordinates in a dialog box. This allows you to exactly line up a control, for example, halfway down a dialog box.

To set the AT() attribute, which defines the controls position, find and press the Position button.

1.	Press the More button.

The Properties dialogs usually contain a More>>> button.  This unfolds the dialog box, allowing you to set additional attributes.

2.	Press the Position button.

This displays the Position dialog, which allows you to specify the AT() attribute for your control.

3. Specify coordinates for the top left corner of the control.

Type in an X (horizontal) and Y (vertical) coordinate. This places the top left corner of the control relative to the top left corner of the window. One reason to specify coordinates manually is to specify positioning in a measure other than the default dialog units. The possible position options are:

Dialog Units	These provide a relative screen measure based on the logical screen measurement. Directly dependent upon the screen driver; the default is 72 pixels = one inch when the current system font is the VGA font. The default is 96 pixels = one inch when the system font is from the 8514/a set.

Thousandths Inches	Provides a relative screen measure based on the logical screen measurement. Directly dependent upon the screen driver; the default is 72 pixels = one inch at VGA, 96 pixels = one inch at 8514/a.

Millimeters	These are also based on the logical screen measurement. The default is 28.3 pixels = one centimeter (VGA system font) or 37.8 pixels = one centimeter (8514/a system font).

Points	Provides a relative screen measure based on the logical screen measurement. One point = 1/72nd  logical screen inch.

3. Specify Width and Height options

Clarion will automatically resize the control to adjust to whatever screen resolution the user runs. This is the Default choice for Width and Height. If you wish to turn off automatic re-sizing, choose the Fixed choice and type in X and Y values for the control.

*** The above is subject to change

You may also specify that the control fills the dialog box or window by choosing the Full options.

Tip:	You can provide your users a full window text editor for MEMO fields. Create a window and place a TEXT control in it. Optionally change the cursor to an I-Beam, and set the Width and Height of the TEXT control to Full.

The Position dialog also allows you to set the following attributes:

Skip	Instructs the Windows Formatter to omit the control from the Tab Order. When the user Tabs from field to field in the dialog box, Windows will not give the control focus. This is useful for seldom-used data fields. The Window Formatter will place the SKIP attribute on the control.

Disable	Disables or grays-out the control when your program initially displays it. Use the ENABLE statement to allow the user access to the control. The Window Formatter will place the DISABLE attribute on the control.

Hide	Makes the control invisible at the time Windows would initially display it. Windows actually creates the control -- it just doesnt display it on screen. The Window Formatter will place the HIDE attribute on the control. Use the UNHIDE attribute to display the control.

Scroll	Specifies whether the control should move with the window when the user scrolls the window. By default, (unchecked), the control moves with the window. Leave the Scroll box unchecked to create a control that stays fixed when the user scrolls the window. The Window Formatter will place the SCROLL attribute on the control when checked.


KEY( )

The KEY attribute applies to any control which may receive focus. It specifies a hot key(s) which will give immediate focus to the control. For an action control, such as a command button, the hot key will initiate the action. To set the KEY attribute, find and press the Key... button.

1.	Press the More button.

The Properties dialogs usually contain a More>>> button.  This unfolds the dialog box, allowing you to set additional attributes.

2.	Press the Key... button.

This displays the Choose Key dialog, which allows you to specify the KEY() attribute for your control.

3.	Specify the key combination.

Select the checkboxes for the CONTROL, ALT and SHIFT keys if applicable, and select a key from the dropdown list.

Tip:	 avoid using ALT plus letter combinations as shortcut keys. These are reserved for mnemonic access to menus.


ALRT( )

The ALRT() attribute applies to any control which may receive focus. It specifies a hot key(s) which is enabled when the control has focus. When the user presses an Alert, it generates an EVENT:AlertKey. This allows you to execute an action while the user is still in the entry field. For example, you may set an ALRT() to display additional information to the user upon a function key press. To set the ALRT() attribute, find and press the Alert... button.

1.	Press the More button.

The Properties dialogs usually contain a More>>> button.  This unfolds the dialog box, allowing you to set additional attributes.

2.	Press the Alert... button.

This displays the Select Alert Keys dialog, which allows you to specify the key(s). The dialog is similar to the Choose Key dialog. There is an additional list of previously selected ALRT keys -- you may set multiple ALRT keys for a single field.


FONT( )

You may specify specific fonts for any control which utilizes text. Select a font, size, and style attributes from the standard Font dialog. To do so:

1.	Press the More button.

The Properties dialogs usually contain a More>>> button.  This unfolds the dialog box, allowing you to set additional attributes.

2.	Press the Font... button.

This displays the Fonts dialog.

Select a typeface from the list, then choose size, style, and optional effects.

Tip:	Be sure the font you pick is present on the users system. If not, Windows will try to substitute an equivalent font; however, since you have no control over the substitution, you cannot be sure that the result will look the way you wanted it to. The standard TrueType fonts, which Microsoft ships with Windows 3.1, are: Arial, Courier New, Symbol, Times New Roman, and Wingdings. If you choose from these, you can be reasonably sure your users will have the font available.


Button or Action Controls

The button is a basic Windows control which performs an action when the user presses it. The Windows Formatter allows you to set the following properties:

•	Button text, or a bitmap icon to appear in lieu of text

•	Whether the button should be the default or not

•	The cursor which should appear when the user positions the mouse over the button

•	A Help ID associated with the button

•	A message which will appear on the status bar when the button has focus

•	A key combination to immediately give focus to the button

•	An alert key to generate a field-specific event (active only when the button has focus)


Push Button

A push button is a rectangular area containing text or picture. When the user presses the button, it should execute a command described by the text or picture.

To specify button properties, select or place a button in a window, then press the Properties button on the toolbar. The Button Properties dialog appears. It helps you to specify the attributes for the BUTTON statement.

1.	In the Button Text field, type the text that you wish to appear on the button.

The text in the Button Text field is a string constant. Place an ampersand (&) before the single character to set the accelerator key or mnemonic access character for the button -- this will appear underlined on the button.

Tip:	Microsoft recommends you do not place a mnemonic on buttons labeled OK, or Cancel.

 2.	In the Use field, type a field equate label with a leading question mark (?).

The field equate label references the button in program statements.

 3.	In the Icon field, select a standard icon or icon file.

This will display a small bitmap on the button face instead of text (clipping or centering the bitmap as necessary). To select a standard icon, choose one of the named items in the drop-down list. To select an icon file (whose extension must be .ICO), choose Select File from the drop-down list, then pick the file using the standard file dialog.

4.	Select the appropriate flags.

There are three button flags which you may toggle on or off independently.

Default	(the DEFAULT attribute), presses the button when the user presses the ENTER key. A heavy border will appear around the button to signal the default button to the user. In general, place the DEFAULT attribute on a button if it represents the most likely action the user will wish to carry out.

Required	(the REQ attribute) specifies that when pressed, your program automatically checks that all ENTRY controls with the REQ attribute are neither blank nor zero. A button with this attribute is a required fields check button. Specify this type of button when a window also contains an ENTRY or TEXT control field with the REQ attribute (or else use the INCOMPLETE function to test the ENTRY controls).  When the user presses a button with the REQ attribute and an ENTRY field is blank or zero, the first required control which is blank or zero receives the focus.

Immediate	(the IMM attribute) allows you to create a button control which repeats the executable action continuously, for as long as the user holds the button down. Normally, buttons generate an event only after the user presses and releases the mouse.

5.	Press the More>>> button.

The Button Properties dialog contains a More>>> button.  This unfolds the dialog box, allowing you to set additional BUTTON attributes.

6.	Optionally select a custom cursor.

The Cursor field (the CURSOR attribute) allows you to specify an alternate shape for the cursor when the user passes the mouse over the button. The drop-down list provides standard cursor choices such as I-Beam and Crosshair. To select an external cursor file (whose extension must be .CUR), choose Select File from the drop-down list, then pick the file using the standard file dialog.

7.	In the Help ID field, type either a help keyword or a context string present in a .HLP file.

The Help ID field (the HLP attribute) takes a string constant specifying the key for accessing a specific topic in the Help document.  This may be either a Help keyword or a context string.

A Help keyword is a word or phrase indexed so that the user may search for it in the Help Search dialog. When authoring a Windows Help file, you indicate a keyword with the K footnote. A Help context string is the arbitrary string which uniquely identifies each topic page for the Windows Help Compiler. When creating the Help file, the # footnote marks a context string.

When you fill in the HLP attribute for a button, when the user presses F1, the help file opens to the referenced topic. If more than one topic matches a keyword, the search dialog appears.

When referencing a context string in the Help ID field, you must identify it with a leading tilde (~).

8.	In the Message field, type the text to display in the status bar.

The Message field (the MSG attribute) allows you to specify text to display in the first zone of the status bar when the control has focus.

9.	Optionally press the Font button and select Font (FONT) attributes.

The Font button provides access to the standard Font dialog.

10.	Optionally select  a KEY attribute.

Press the Key button to display the Choose Key dialog, which allows you  to specify a KEY attribute.

11.	Optionally select Alert key attributes.

Press the Alert button to display the Select Alert Keys dialog.

12.	Optionally press the Position button.

This displays the Layout Properties dialog, which allows you to specify the AT() attribute for your control.

13.	Press the OK button.

This completes the Button Properties dialog.


Option Buttons

Option buttons are especially useful on a toolbar, or a tool palette. They may perform an action, such as making selected text bold, for example. Or they may immediately set a global option, such as placing the application in Print Preview mode.

Option buttons are modified forms of the radio button and checkbox controls. You should generally place a picture or icon on the button. See the sections below for details on creating each of these controls.


Choice Controls

User choice controls allow user input without keyboard entry. They create streamlined user entry, as it is usually faster to pick an item from a list than to type in a name of an item.

•	Use choice controls to allow the user a single choice among a mutually exclusive group.

•	Also use choice controls to allow the user independent yes/no choices via individual controls.

•	You can specialize a choice control for use as a toolbar button. Clarion allows you to create 3D or latched controls which provide a pushed in effect when the user activates the control. Toolbar buttons can function either as command shortcuts, or they can turn on and turn off options.

•	Clarion also allows you to easily incorporate multiple selections from lists. The Listbox Formatter allows you to design simple listboxes, or multi-column, multi-selection listbox controls.


Radio Buttons

A Radio Button, also called an option button, provides the user a set of mutually exclusive choices. By default, a filled-in circle represents the current selection.

A group box -- an OPTION structure -- must always surround the radio button choices. The Window Formatter automatically prompts you to create this if you try to place a radio button outside an option box. When the user selects a choice, the control fills the USE variable with the Radio text, minus the ampersand indicating the accelerator key.

Clarion offers three distinct radio button styles: the default Windows circle; the 3D diamond, or a 3D latched button. The latter looks like its namesake, the old style car radio buttons.

This example places a set of radio buttons in a blank dialog window, to force the creation of the OPTION STRUCTURE. When you activate the Radio Button tool, or choose Radio Button from the Control menu, then click in the window, the Option Properties dialog appears.

1.	Type the Group Box label in the Caption Text field.

The Caption Text field requires a string constant containing the prompt for the group of controls.  This may contain an ampersand (&) to indicate the mnemonic key for the prompt. When the user presses the mnemonic, the first radio button receives the focus.

Tip:	Though the OPTION STRUCTURE must be present, it does not have to appear on screen. You may hide it from the user by un-checking the Boxed checkbox in this dialog.

2.	Type the label of a string variable in the Use field.

The Use field (the USE attribute) takes the label of a string variable to receive the users selection--the string you will enter in the Button Text field for each radio button.

Note: no radio button selected is also a valid option.  This occurs only when the OPTION structures USE variable does not contain a value duplicated in a Radio text parameter.  This condition lasts until the user selects one of the Radio Buttons.

3.	Add optional attributes to the OPTION box by pressing the More button.

The optional attributes are identical to those available for the BUTTON control. Select a custom CURSOR active when the user passes the mouse over the group box (whether visible or not). Specify a Help ID (HLP attribute) specifying a Help document topic. Add a string for the Message field (MSG attribute) for display on the status bar when the user passes the mouse over the group box. You may also set the FONT, KEY, ALRT and AT attributes.

4.	Press the OK button to finish setting attributes for the OPTION box.

The OPTION box appears in the window. If you un-checked the Boxed option, it will be visible in layout mode, but will become invisible in Test mode.

5.	Type the Button Text string for the first radio button.

The Radio Button Properties dialog appears immediately after you finish setting attributes for the OPTION STRUCTURE to create a RADIO control. Type a string for the Button Text (the label which appears next to the radio button). When the user selects the radio button, then closes the control, the string will be placed in the variable referenced by the USE field of the OPTION control.

You determine whether the radio button will be the normal 2D circle with text to the right or a 3D diamond radio button in the Window Properties dialog for the Window you place the control in. The default is the 2D circle; for the 3D diamond, mark the 3d Look checkbox.

6.	Type a field equate in the Use field.

This string will be the field equate label for this radio button.

7.	Optionally create a 3D button look by choosing an icon.

To select a standard icon, choose one of the named items in the drop-down list. To select an icon file (whose extension must be .ICO), choose Select File from the drop-down list, then pick the file using the standard file dialog.

Tip:	When you require a set of buttons for the toolbar, only one of which can be active, set the icon attribute of each. For example, text justification controls are candidates for a mutually exclusive toolbar button set. A user can push left, center, right, or justified buttons, but not more than one at the same time.

8.	Select whether the radio button prompt should appear on the left or the right of the control.

Select one of the options to make your choice.

Tip:	When you create a 3D button, no prompt appears. To create one, you must add a PROMPT control manually.

9.	Add optional attributes to the radio button by pressing the More button.

The optional attributes are identical to those available for the BUTTON control. Select a custom Cursor active when the user passes the mouse over the radio button. Specify a Help ID (HLP attribute) specifying a Help document topic. Add a string for the Message field (MSG attribute) for display on the status bar when the user passes the mouse over the radio button. You may also set the FONT, KEY, ALRT and AT attributes.

10.	Press the OK button to finish setting attributes for the radio button.

The Radio Button is now complete. Add additional radio buttons by placing more RADIOs inside the OPTION structure.

Tip:	To create professional looking radio button groups, turn the Grid control on. The Grid checkbox appears on the Window Formatters toolbar. This will allow you to easily line up your radio buttons.


Check Box

A check box holds an individual choice that the user may turn on or off.

When you activate the Check Box tool, or choose Check Box from the Control menu, then click in the window, the Check Box Properties dialog appears.

1.	In the Box Text field, type in the text for the check box.

The Box Text field takes a string constant. The string will appear next to the check box. You may indicate an accelerator key by placing an ampersand (&) before a character.

2.	Specify a numeric variable in the Use field.

The check box places a value of 1 in the numeric variable if the user turns on the check box, zero if off.

3.	Optionally create a 3D latched look by choosing an icon.

To select a standard icon, choose one of the named items in the drop-down list. To select an icon file (whose extension must be .ICO), choose Select File from the drop-down list, then pick the file using the standard file dialog.

Tip:	When you require an independent toolbar button for the toolbar, set the icon attribute. The latched button automatically updates the icon to provide a depressed and normal look as the user toggles the button.

4.	Select whether the check box prompt should appear on the left or the right of the checkbox.

Select one of the options to make your choice.

Tip:	When you create a latched check box, no prompt appears. To create one, you must add a STRING control manually.

5.	Add optional attributes to the check box by pressing the More >>> button.

The optional attributes are identical to those available for the BUTTON control. Select a custom Cursor active when the user passes the mouse over the radio button (whether visible or not). Specify a Help ID (HLP attribute) specifying a Help document topic. Add a string for the Message field (MSG attribute) for display on the status bar when the user passes the mouse over the check box. You may also set the FONT, KEY, ALRT and AT attributes.

6.	Press the OK button to finish setting attributes for the check box.

The Check Box Properties dialog is now complete.


List Box

***	The Listbox Formatter will change drastically before the final release. For Beta 3, please refer to the appendix for instructions on using the current listbox formatter.


Combo Box

The Combo Box combines an entry box with a list box. It is useful for when you expect string data which usually should be a member of the list, but which also might not be. The Window Formatter allows you to create either a normal combo box, or a drop-down combo box.

When you activate the Combo box tool, or choose Combo Box from the Control menu, then click in the window, the Combo List Properties dialog appears.

1.	Fill in the data for the list.

Fill the From field with the origin of the list data. Generally, this is the label of a QUEUE structure.

2.	Place a variable or field equate label in the Use field.

You may specify the variable which will receive the value that the user selects. Or, a field equate label to reference the combo box in program statements.

3.	Specify whether this should be a regular or drop-down combo box.

Place a zero in the Drop field for a normal combo box. For a drop-down combo box, type the number of drop-down elements you wish to be visible.

4.	Specify whether the list should have scroll bars.

Check the scroll bar components you wish.

5.	Optionally set the Listbox format options

Press the Format button to run the Listbox Format Editor. This will allow you to customize the listboxs appearance, including creating a multi-column list box. See the previous section for instructions for using this tool.

***	The Listbox Formatter will change drastically before the final release. For Beta 3, please refer to the temporary appendix for instructions on using the current listbox formatter.

6.	Set Entry Properties

Press the Entry button to view the Combo List Properties dialog. This will allow you to set attributes for the text field portion of the combo box. It allows you to set the case and entry flags, plus picture and mask attributes. Like an ENTRY field, you may type the name of a variable in the Use field; the variable will receive the value that the user enters in the control.

7.	Add optional attributes to the combo box by pressing the More >>> button.

The optional attributes include those available for the BUTTON control. Select a custom Cursor active when the user passes the mouse over the radio button (whether visible or not). Specify a Help ID (HLP attribute) specifying a Help document topic. Add a string for the Message field (MSG attribute) for display on the status bar when the user passes the mouse over the combo box. You may also set the FONT, KEY, ALRT and AT attributes.

10.	Optionally enable multiple item selection.

Type in the name of a QUEUE, field or array in the Mark field if you wish to allow the user to select more than one item from the list. The QUEUE, field or array will flag the selected items.

11.	Optionally enable column selection in a multi-column listbox

Check the Columns box if you wish to allow the user to highlight a multi-column listbox field by field (rather than one row at a time).

12.	Optionally provide VCR controls.

Check the VCR checkbox to provide VCR style controls for the list box. Optionally type the name of an entry field to the right of the checkbox. When the user presses the Locator button, the focus will shift to that field. The user may type in data, then press TAB to scroll the LIST to the closest matching entry.

13.	Press the OK button.

The Combo List Properties dialog is now complete.


Spin Box

Spin Boxes are specialized entry boxes that only accept values in a predefined range. They also provide the user with increase and decrease buttons, which many people like because they can use the mouse to change the value. The user can also type a value directly into the control.

When you activate the Spin Box  tool, then click in the window, the Spin Properties dialog appears.

1.	Specify a Picture.

The Picture field takes a display picture token that specifies input format. You may press the ellipsis (...) button next to the field to pick a display picture from a list.

2.	Optionally fill in the From attribute.

The From attribute is useful for values that progress in an irregular increment. You may also wish to provide the user with strings formatted as Spin Box choices when the choices are a natural progression such as the days of the week or the months of the year. Specify a QUEUE in the From field. This and the Range limits are mutually exclusive.

You may also specify a string constant as the source. Separate the individual elements with a vertical bar ( | ).

3.	Place a vaiable or field equate label in the Use field.

You may specify the variable which will receive the value that the user selects. Or, the field equate label references the spin box in program statements.

4.	Specify the upper and lower Range limits, and the Step value.

Place the highest value which the control should return in the Range Upper field. The value should match the Picture field.  Place the lowest acceptable value in the Lower field. Place the Step value--the amount by which each press of the increase or decrease buttons should change the spin box value--in the Step field.

5.	Press the More button.

The Spin Properties dialog contains a More>>> button. This unfolds the dialog box, allowing you to set additional SPIN attributes.

5.	Optionally select a Justification style for the Entry component of the Spin box.

The Justification field allows the following styles:

Default	specifies no justification. The system default is left-justified.

Left Justified	(the LEFT attribute) specifies left justification.

Right Justified	(the RIGHT attribute) specifies right justification.

Centered	(the CENTER attribute) centers data as the user types it within the control.

Decimal	(the DECIMAL attribute) specifies data alignment with the decimal point. Enter an offset in inches.

6.	 Set additional optional attributes.

The optional attributes work identically with those available for the BUTTON control. Optionally specify a custom Cursor (CURSOR attribute). Specify a Help ID (HLP attribute) specifying a Help document topic. Add a string for the Message field (MSG attribute) for display on the status bar when the user passes the mouse over the spin box. You may also set the FONT, KEY, ALRT and AT attributes.

7.	Press the OK button.

The Spin Properties window is now complete.


Entry Controls

Entry controls allow the use to enter data from the keyboard. Clarion provides extensive options for automatically checking user entry.

•	You may specify a picture for the field, automatically formatting a default variable, or the data the user enters.

•	You may validate the data the user enters either at the time its typed, or when the focus changes to another control.


Entry Box

An entry box allows you to process data input from the user. The data entry control is a specialized form of Windows edit box. It can help you automatically validate data as the user enters it in a dialog box.

When you activate the Entry Box tool, or choose Entry from the Control menu, then click in the window, the Entry Properties dialog appears.

1.	Specify a Picture.

The Picture field is a display picture token that specifies the input format for the data entered into the control. For example, you may specify a string of 20 characters as @s20. You may press the ellipsis (...) button next to the field to pick a display picture from the picture formatter.

*** The above feature is not implemented yet; subject to change

You may check the user entry against the picture at two points: as the user types the data in, or when the user closes the dialog box. Checking the data as the user types it incurs a slight performance penalty. To do so, check the Entry Patterns (*** control name subject to change!!!) box in the Window Properties dialog for the window in which the entry box resides. This turns the MASK attribute on for all controls in the window.

If the MASK attribute is off, entry checking takes place when the user moves the focus to another control (for example, by tabbing to another field).

If the user types in data in a format different from the  picture, the program will attempt to determine the format, then convert it to match the picture (if no MASK was specified).  For example, if the user types January 1, 1995  and the picture is @D1, the program formats the input to 1/1/95. If the program cannot determine the entry format, it will not update the USE() variable.  The user will receive an audible prompt (beep), and the focus will return to the entry control, ready for additional input.

2	Specify a Use attribute.

Type the name of the variable to receive the value that the user will enter in the control.

3.	Specify case attributes for the entry field.

The entry box can automatically convert character from one case to another as the user types. Uppercase (UPR) automatically converts to all caps. Capitals (CAP) is equivalent to Proper Name (the first letter of each word will appear in caps). Normal (no attribute) accepts input in the case the user types it.

4.	Set the Entry flags.

There are four entry flags you may toggle on or off independently.

Required	(the REQ attribute) specifies that the control may not be left blank or zero.

Password	(the PASSWORD attribute), specifies password mode; asterisks appear for each character the user types.

Read Only	(the READONLY attribute) prevents data entry in this control. Use this to declare display-only data.

Immediate	(the IMM attribute) specifies immediate event generation whenever the user presses any key.

5.	Press the More button.

The Entry Properties dialog contains a More>>> button. This unfolds the dialog box, allowing you to set additional ENTRY attributes.

6.	Optionally select a Justification style and offset.

The Justification field allows you to choose Default, Left Justified, Right Justified, Centered, or Decimal. You may also set the offset value.

7.	Optionally select a custom Cursor.

The Cursor field (CURSOR attribute) allows you to specify an alternate shape for the cursor when the user passes the mouse over the entry field. The drop-down list specifies available choices.

Tip:	The I-Beam, which signals text entry, is an excellent choice for the active cursor for an entry control.

8.	 Set additional optional attributes.

The optional attributes work identically with those available for the BUTTON control. Specify a Help ID (HLP attribute) specifying a Help document topic. Add a string for the Message field (MSG attribute) for display on the status bar when the user passes the mouse over the group box. You may also set the FONT, KEY, ALRT and AT attributes.

10.	Optionally specify an Entry Mode.

Choose either Insert (the INS attribute) or Overwrite (the OVR attribute).  The Entry Mode applies only for windows with the MASK attribute set.

11.	Press the OK button.

The Entry Properties window is now complete.


Text

The Text control provides a multi-line data entry field. This control is especially suitable for holding a long string.

When you activate the Text tool, or choose Text from the Control menu, then click in the window, the Text Properties dialog appears.

1.	Specify a Use attribute.

Type the name of the variable to receive the value that the user enters in the control. When using multi-line controls, be sure the variable is large enough to hold the amount of data you expect your users to enter in the control.

2.	Specify case attributes for the entry field.

The entry box can automatically convert character from one case to another as the user types. Uppercase (UPR) automatically converts to all caps. Normal (no attribute) accepts input in the case the user types it.

3.	Set the Entry flags.

There are two entry flags you may toggle on or off independently.

Required	(the REQ attribute) specifies that the control may not be left blank or zero.

Password	(the PASSWORD attribute), specifies password mode; asterisks appear for each character the user types.

4.	Press the More button.

The Entry Properties dialog contains a More>>> button. This unfolds the dialog box, allowing you to set additional TEXT attributes.

5.	Optionally select a Justification style.

The Justification field allows you to choose Default, Left Justified, Right Justified, Centered, or Decimal. See the Spin Box section for details. You may also set the offset value.

6.	Optionally select a custom Cursor.

The Cursor field (CURSOR attribute) allows you to specify an alternate shape for the cursor when the user passes the mouse over the text field. The drop-down list specifies available choices.

Tip:	The I-Beam, which signals text entry, is the standard choice for the active cursor for a text control.

7.	 Set additional optional attributes.

The optional attributes work identically with those available for the BUTTON control. Specify a Help ID (HLP attribute) specifying a Help document topic. Add a string for the Message field (MSG attribute) for display on the status bar when the user passes the mouse over the text field. You may also set the FONT, KEY, ALRT and AT attributes.

8.	Press the OK button.

The Entry Properties window is now complete.


Static Controls

Static controls do not accept data, but instead guide the user either via text or graphics. For example:

•	A string in a dialog box can provide directions for filling out the data field.

•	One of the simplest graphic elements--a box--can visually associate a group of controls, signalling the user that the entries all relate to the same thing.

•	An image or graphic can do more than embellish a dialog. It can convey meaning to a process that might take many, many words otherwise.


String

The String control allows you to place a string constant on screen.

When you activate the String tool, or choose String from the Control menu, then click in the window, the String Properties dialog appears.

1.	Specify the string constant.

Type the string in the String Text field.

2.	Specify a Use attribute.

Type either a field equate label to reference the control in executable code.

3.	Optionally select a Justification style and offset.

The Justification field allows you to choose Default, Left Justified, Right Justified, Centered, or Decimal. You may also set the offset value.

4.	Specify whether you wish the control background to be Transparent.

This will instruct Windows to suppress the rectangular region around the text -- the background. Normally, Windows will paint this the same uniform color as the window below the control,

Tip:	When you place text on top of an IMAGE, or a colored graphic such as a BOX, turn the TRN attribute on, so that the text doesnt obscure the graphic.

5.	 Set additional optional attributes.

You may set the FONT, or AT attributes for the STRING.

6.	Press the OK button.

The String Properties dialog is now complete.


Variable String

The Variable String control allows you to place a string variable on screen. It provides the same functionality as a STRING control with a display picture token in the String Text field and a variable name in the Use field. The separate tool functions as a Display Only control for variables.

When you activate the String with USE tool, or choose Variable String from the Control menu, then click in the window, the Screen String Properties dialog appears.

1.	Specify the Picture.

Type a display picture token to format a variable you may specify in the Use field.

All other options are identical to the String Properties dialog. See the previous section for details.


Prompt

The Prompt control allows you to place a specialized string object on screen which will automatically provide an accelerator or  mnemonic access key to the next control following the prompt.

When you activate the Prompt tool, or choose Prompt from the Control menu, then click in the window, the Prompt Properties dialog appears.

1.	Specify the Prompt Text.

Type a string for the prompt, placing an ampersand (&) before the character you wish to serve as the mnemonic.

All other options are identical to the String Properties dialog.


Group Box

A Group control places a box around two or more controls. It visually associates the controls for the user, and allows you to address all the controls as one entity -- making it easy, for example, to disable all at once.

When you activate the Group box tool, or choose Group Box from the Control menu, then click in the window, the Group Properties dialog appears.

1.	Specify a string constant for the Caption Text.

Type the string in the Caption Text field, placing an ampersand (&) before the character you wish to serve as the accelerator key.

2.	Specify a Use attribute.

Type a field equate label to reference the control in executable code.

3.	Optionally specify that the group box should be invisible

By un-checking the Boxed check box, you may make the group box invisible to the user. The group box will be visible in the Window Formatter, but invisible when in Test mode.

4.	 Set additional optional attributes.

The optional attributes work identically with those available for the BUTTON control. Optionally choose a custom cursor from the drop-down list. Specify a Help ID (HLP attribute) specifying a Help document topic. Add a string for the Message field (MSG attribute) for display on the status bar when the user passes the mouse over the group box. You may also set the FONT, KEY, ALRT and AT attributes.

5.	Press the OK button.

The Group Properties window is now complete.


Ellipse

The ellipse control allows you to place a circle or ellipse in your windows. You may fill the ellipse with a color, and specify a border color.

The ellipse control cannot receive focus, nor can it generate events.

When you activate the Ellipse tool, or choose Ellipse from the Control menu, then click in the window, the Ellipse Properties dialog appears.

1.	Specify the Fill and Border colors.

Check the Fill and Border checkboxes first--unless you wish either of these elements to be transparent. Then press the Fill Color... or Border Color... buttons. The standard Color dialog appears. Select a color by clicking on the color sample square, or add a custom color.

2.	Place a field equate label in the Use field.

The field equate label references the ellipse in program statements.

3.	Optionally set Position attributes

Press the Position button to specify AT attributes, plus DISABLE, SKIP, HIDE or SCROLL.

Tip:	While you can set the size of the ellipse and other graphic controls by manually typing in coordinates, it is much easier to draw it directly in the Windows Formatter.

4.	Press the OK button.

The Ellipse Properties dialog is now complete.


Image (Icon)

The Image (or icon) control allows you to place a bitmapped image, such as a .BMP or .ICO file, or a vector graphic (.WMF format) in a window. An icon file differs from a .BMP file in that it may have a transparent background, and its dimensions are usually 32 x 32.

 The Image control cannot receive focus, nor can it generate events.

When you activate the Image tool, or choose Icon from the Control menu, then click in the window, the Image Properties dialog appears.

1.	Select a graphics file.

Type in a file name, or press the ... button to the right of the File field to select a graphics file using the standard File Open dialog.

2.	Place a field equate label in the Use field.

The field equate label references the ellipse in program statements.

3.	Optionally add scroll bars.

By checking the Horizontal and/or Vertical checkboxes, you may specify that you wish the control to automatically add scroll bars if the image is larger than the control size.

4.	Optionally set Position attributes

Press the Position button to specify AT attributes, plus DISABLE, SKIP, HIDE or SCROLL.

Tip:	When specifying an image control which will place different bitmap images in the control at different times, determine whether the bitmaps will all be the same size. If they are, set the Width and Height of the control to Fixed, at exactly that size.

5.	Press the OK button.

The Image Properties dialog is now complete.


Box

The box control allows you to place a square or rectangle in your windows. You may fill the box with a color, and specify a border color. You may also specify it should have rounded corners.

The box control cannot receive focus, nor can it generate events.

When you activate the Box tool, or choose Box from the Control menu, then click in the window, the Box Properties dialog appears.

1.	Specify the Fill and Border colors.

Check the Fill and Border checkboxes first--unless you wish either of these elements to be transparent. Then press the Fill Color... or Border Color... buttons. The standard Color dialog appears. Select a color by CLICKING on the color sample square, or add a custom color.

2.	Place a field equate label in the Use field.

The field equate label references the box in program statements.

3.	Optionally specify the box should appear as a rounded rectangle by marking the checkbox.

The corners of the box will be rounded.

4.	Optionally set Position attributes

Press the Position button to specify AT attributes, plus DISABLE, SKIP, HIDE or SCROLL.

5.	Press the OK button.

The Box Properties dialog is now complete.


Region

A Region control is simply a rectangular area of the screen. Its main purpose is to provide a reference to test whether a given event--such as a mouse event --occurred within that region.

You may give a region control color, or provide for a cursor change when the user passes the mouse over the region.

The fields in the Region Properties dialog are identical to the Box Properties dialog with addition of the cursor change option and one other. You may add the IMM attribute to the Region control by checking the Immediate checkbox. This allows you to monitor whenever the user passes the mouse over the region; however, it incurs much overhead at runtime, so should be used sparingly.


Line

The line control allows you to place a straight line in your windows. You may choose a line color.

The line control cannot receive focus, nor can it generate events.

When you activate the Line tool, then CLICK in the window, the Line Properties dialog appears.

1.	Specify the Line Color.

Press the Line Color... button. The standard Color dialog will appear. Select a color by clicking on the color sample square, or add a custom color.

2.	Place a field equate label in the Use field.

The field equate label references the line in program statements.

3.	Optionally set Position attributes

Press the Position button to specify AT attributes, plus DISABLE, SKIP, HIDE or SCROLL.

4.	Press the OK button.

The Line Properties dialog is now complete.


Custom Control Properties

Custom controls are add-in controls sold by many third party vendors. These perform a very wide variety of tasks, from sliders and gauge controls to TWAIN image capture add-ins. The Window Formatter allows you to directly place these controls once you register the external libraries.

The specific custom control library Clarion supports is the Microsoft Visual Basic control format, normally given the .VBX extension. There are two important limitations:

•	Clarion supports .VBX libraries that contain one control only. This in not a severe limitation, since vendors normally package each control in a separate .VBX file, so that programmers may distribute only those controls that the application requrires.

•	Clarion supports .VBX properties compatible with Microsoft Visual Basic 1.0. Custom control properties which require VB 2.0 or higher are incompatible. This is in line with other non Visual Basic platforms, such as the Microsoft Foundation Classes v. 2.0.

Custom control libraries usually require a license file (*.LIC) before you can add the control to your applications. The library vendor provides the file when you buy the library. When you distribute the application to your end users, you distribute the .VBX file only, not the license file.


Registering Your .VBX Custom Control Libraries

Before you can place a custom control in a window, you must register the .VBX file which contains it. To do so:

1.	Choose Setup [image] VBX Custom Control Registry within the IDE.

2.	Press the Add button in the VBX Custom Control Registry dialog box.

3.	Select the .VBX file within the VBX Custom Control Open File dialog, and press OK.

4.	Press OK to close the VBX Custom Control Registry dialog.


Adding a Custom Control to a Window

When you activate the Custom tool, or choose Custom from the Control menu, then click in the window, the Select Custom Control dialog appears.

1.	Select the type of control you want from the Control Name list and press the OK button.

When you select a control, if the Sample checkbox is marked, the dialog box will display a copy of the control in its default settings.

2.	Optionally type a label for the control in the Text field.

If the control supports a label, it will appear as part of the control. In practice, most controls will require you to specify a title label as a Visual Basic Control property, explained below.

3.	Type a variable name in the Use field.

The variable will nominally receive the value of the control. If the control accepts user entry, you will more likely retrieve the value entered by the user by accessing a Visual Basic Control property, explained below.

4.	Set startup properties for the control.

The Custom Properties list appears at the left of the dialog. It displays the Visual Basic Control properties and their default values.If you enter a startup value in the dialog, the Window Formatter will automatically add it to the Clarion language statement that places the control in the window.

When you highlight a Visual Basic Control property in the list, either an edit box. or a drop-down list appears at the lower left corner of the dialog. Type a value or variable in the edit box, or choose from the drop-down.

The documentation from the .VBX library vendor will describe the Visual Basic Control properties you may set. See below to find out how to change them in executable code, or how to retrieve user-entry from the custom control.

5.	Press the More>>> button to set optional properties.

These include CURSOR, FONT, POSITION. and others.

6.	Press the OK button.

The Custom Control Properties dialog is complete.


Setting and Retrieving Visual Basic Control Properties

The Visual Basic Control properties are a message map. The .VBX file acts as an external library. When the application loads it into memory, you can exchange information between the application and the custom control via the properties. The documentation from the .VBX library vendor lists the Visual Basic Control properties you may set for each control.

Tip:	The Visual Basic Control properties are usually documented with a leading dot. Drop the dot when accessing it from the Clarion application.

The section above notes how to set the startup properties for a control with the Window Formatter. At other times youll want to alter the properties in executable code, and of course, retrieve a value from a property after user entry.

•	To alter properties in executable code, use the property expression syntax. Access the custom controls Visual Basic Control properties by referring to the specific property in quotes:

?vbxVariable { 'VBProperty' } = value

•	To retrieve the current value of a Visual Basic Control property, use the property expression syntax again:

value = ?vbxVariable { 'VBProperty' }


Using the Report Formatter

Using the Report Formatter, you visually lay out your applications reports. The Report Formatter automatically generates and places the language structures for the report elements in the REPORT data structure.

The Report Formatter is a two-way tool.  You can move back and forth between the Report Formatter and the Text Editor, modifying your report with either tool, anytime you wish.

Overview: Report Processing

Smart Processing

Order

Flexibility

Report Preparation

Opening the Report Formatter

The Database

An Overview of the Report Formatter

Page Oriented Printing

Band View

REPORT Structures

Variable String Controls

Total Fields

Graphics

Page Layout and Preview

Designing Your Report

Design Basics

Margins

Report Types

Positioning And Alignment

Placing Structures

Header

Footer

Detail

Form

Group Breaks

Page Breaks

PAGEAFTER

PAGEBEFORE

WITHNEXT

WITHPRIOR

Adding Text Labels and Fields

Strings

Variable Strings

Multi-Line Text

Adding Graphic Controls

Images

Line

Box

Ellipse

Adding Specialized Controls

List

Option

Radio

Check

Group

Custom

Adding Graphs

Graph .VBX

Sample Report Designs

Miscellaneous Report Design Tips

Arranging Controls

Arranging Groups

Adding Default Report Structures

TXT Files

Print Preview


Overview: Report Processing

***	Special Note for Beta 3: The Report Formatter and the Application Generator are not yet integrated. For example, the control attributes specified in the data dictionary will not be tied into the default report controls for the fields.

Before learning how to create a report using the Report Formatter, its important to understand how Clarion executes a report--in other words, the division of labor between the print engine and your source code, and the order in which Clarion processes all the sections of your report. Each section of the report is a data structure, and each in turn is contained in the REPORT structure.


Smart Processing

The REPORT data structure contains all the information necessary for formatting and printing each page. It automatically handles page overflow management, including widow and orphan control. This frees you from worrying about the mechanics.

This means that the Clarion executable code to print a report is simple and clean. The following example shows how a total of six lines of executable code can access the file and print a fully-formatted listing of all Customers. Since the Report Formatter writes the entire REPORT data structure, this is all the code the programmer has to write.

CODE

OPEN(CustReport)	!Open report for processing

SET(Cus:NameKey)	!Top of file, alpha order

LOOP	!Process the entire file

NEXT(CustomerFile)	!one record at a time

IF ERRORCODE() THEN BREAK.	!Check for errors

PRINT(Rpt:Detail)	!PRINT tells the REPORT !structure to do the work.

END

In this example, the PRINT statement prints a DETAIL structure for each record in the file retrieved with the NEXT statement inside the LOOP .

The REPORT data structure contains the items that belong on the page, plus the attributes that determine how they appear there. Since you visually design these in the Report Formatter, the code example above really is all you have to do to print the report.

The PRINT statement automatically initiates the page overflow handling. This means that when the LOOP goes through enough records to fill up the page, it automatically generates any other structures on the page--the FOOTER, for example. Then it sends the entire page to the print spooler.


Order

The parts are wholly contained and managed within the REPORT data structure. The parts of the data structure are the FORM, page HEADER, DETAIL, and page FOOTER; their functions are fully described below. The REPORT data structure may also contain group BREAK structures. Each group BREAK structure can contain its own group HEADER, DETAIL, and FOOTER.

Normally, you want to design reports with only one DETAIL. When you generate reports using the Application Generator, they will probably have only one. This usually is the one inside the group BREAK structure .The Report Formatter adds a DETAIL for each BREAK, for flexibility. You can delete the ones not used.

Once you know the order in which the parts generate at print time, you can understand how to use them better. For the following example, assume a report utilizing all the parts listed above, containing one group structure, with a DETAIL inside. Immediately upon the PRINT command:

1.	The print engine composes the FORM, but does not send it to the print spooler yet. The FORM generates only once; the application repeats the FORM and does not recompose it for additional pages.

2.	The print engine composes the page HEADER.

3.	The print engine processes the group HEADER.

4.	The application generates the DETAIL section (within the BREAK) for as many times as will fill the first page, continuously checking for group BREAKs.

If a BREAK occurs on the page:

5.	The print engine composes the group FOOTER for the first group.

6.	The print engine composes the group HEADER for the next group.

7.	The application generates the DETAIL section for the next group of records, continuously checking for further group BREAKs.

At the bottom of the page:

8.	The print engine checks for widows, increments the page count, and checks the next page for orphans.

9.	The print engine composes the page FOOTER.

10.	The print engine sends the entire first page to the print spooler.

11.	For page two, since the FORM was composed already, it does not get regenerated, though it will print on the page. The application proceeds directly to the page HEADER.

12.	The application repeats the procedures above for this and any additional pages.


Flexibility

The page-oriented nature of the Report Formatter is the key to its flexibility. Clarion composes each page in its entirety before sending it to the printer. This means you may arrange the parts of the report into any page layout you wish.

You can place the FORM, page HEADER,  and page FOOTER structures anywhere on the page, within certain limitations. Their placement does not affect the order that the application generates the parts.

That means you can physically place a page FOOTER above a page HEADER. Since the FOOTER generates only after the report processes all the records on the page, this allows you, for example, to place a page total above the records on the page.

You set the position and size of the DETAIL structure as an offset vs. the last DETAIL printed. The print engine prints each DETAIL from page top to page bottom. If the DETAIL is narrow enough so that more than one fits across the width of the page, they print in order left to right, top to bottom.

Group BREAK structures--group HEADER, group DETAIL and group FOOTER--all print as offsets within the DETAIL area, one after the other.

You can do some fancy footwork in cooperation with the print engine. For example, because the DETAIL structure must be printed with the PRINT statement, you can utilize embedded source to place conditional statements within your executable code, to print one DETAIL upon one condition, and another upon a different condition.

As long as you remember the order in which the application generates each section, which determines the current record and the values of the totals, tallies and other operations on the fields in each structure, you can build in a great deal of flexibility within the REPORT data structure, and let the print engine worry about fitting it all onto the page at runtime.


Report Preparation

This section describes how to open the Report Formatter, from both the Application Generator and from source code. It also discusses how to set up your database beforehand, insuring, for example, that group data prints in the right order.


Opening the Report Formatter

In general, you call the Report Formatter either to create a new report, or edit--add or modify controls in--an existing report. The Report Formatter allows you to visually place your report elements on the page. It then automatically generates the REPORT data structure. You can access the Report Formatter from the Application Generator or from source code.

•	To open the Report Formatter from the Application Generator:

1.	Select or create a procedure to run the report. Not all templates support REPORT structures.

2.	Within the Application Tree window, DOUBLE-CLICK on the procedure name or press the Properties button. The Procedure Properties dialog appears.

3.	Optionally define local data. Press the Data button and make your choices in the dialog boxes which appear. Return to the Procedure Properties dialog.

4.	Declare data files the report will use. Press the Files button and make your choices in the dialog boxes which appear. Return to the Procedure Properties dialog.

5.	Press the Report button.

6.	Youre now ready to customize the report by section, specify headers and footers, and add controls.

•	To create a new report from the Text Editor:

1.	Open a source code document

2.	Locate a blank line in the data section and place the cursor there. This is where the Report Formatter places the Clarion language statement which creates the report.

3.	Choose Edit [image] Format Structure from the menu. You may also press the keyboard accelerator, CTRL+F.

4.	When the New Structure dialog appears, choose Report.

5.	Youre now ready to customize the report by section. Specify headers and footers, and add controls.

••To add a control or otherwise edit an existing report from the Text Editor:

1.	Open the source code file and place the cursor on any line within the structure which describes the report--from the REPORT statement through its END statement.

2.	Choose Edit [image] Format Structure from the menu, or press the keyboard accelerator (CTRL+F).

The Report Formatter appears, containing either a new, blank report, or the report which contains the existing controls.


The Database

Every report has a data context. The report fills in all its data--whether in the DETAIL or another section--according to the current order of the database.

When the report prints, it goes through each record one by one, taking the information required for the report fields. When it has enough data to fill a page, it composes the page and prints it.

The simplest and easiest thing to do is to LOOP through an entire file, as in the example code above. You can do so either through source code or the application generator. You may also set up the query or filter, specify a range of records, or change the current key before printing the report.

When using the Application Generator, from the Procedure Properties dialog for the procedure which contains the report:

1.

***	Not functional in Beta 3


An Overview of the Report Formatter

Design your report visually--by placing text, variables, graphics--on a representation of a page. Rulers and grid snap allow you to place these items exactly.


Page Oriented Printing

By Page Oriented, we mean that Clarion print engine composes everything on the page, and only after everything is processed does it send the page it to the printer. This may be a radical change for programmers switching from DOS report writers, which send output to the printer line by line.

This provides these benefits:

•	You can place totals anywhere on the page. If the total is in a page FOOTER, you can move the FOOTER anywhere.

•	You can easily print graphic elements.

•	You can place a preprinted graphic form in the FORM structure, then format the report so that data prints out inside the areas specified for each data element.

•	Clarion handles page breaks and group breaks automatically, even allowing you to specify how to handle widow and orphan lines.

•	You can easily build in a Print Preview command in your applications.


Band View

When you first open the Report Formatter, your report appears in Band View, divided into sections. Each section appears in a separate pane inside the window.

Band View features WYSIWYG editing one section at a time. You may specify that sections print side by side or even overlap on the page, but in band view, each section appears in separate pane, and each appears in its proper hierarchical order.

•	To quickly determine each sections position, look at the ruler. Each pane has its own ruler, set according to your default measurement units (see below). The rulers show the measurements vs. the upper left corner of the page.

•	To identify a panes contents, look at its mini caption bar. This is particularly useful when you add group breaks--the name of the variable the group breaks on appears on the sections caption.

•	To control the panes display, use its restore button. This appears at the right side of the caption bar, and toggles the pane open and closed. The panes caption bar always appears.

•	To close all the panes at once, press the Tree button on the toolbar.

Place controls in the panes you wish. The controls may contain data strings, other data controls, and graphic elements.

•	To select the type of control to place, choose it from the Control menu.

•	To place the control, click inside the pane representing the section in which you wish it to print.

•	To modify the control, double-click on it, or select it and press the Properties button on the toolbar.


REPORT Structures

Each report contains sections, which are also Clarion data structures. Clarion provides complete flexibility in placing the FORM, page HEADER, DETAIL and page FOOTER structures at any position on the page.

•	The FORM structure prints as a background layer. Typically, you may display overlays such as graphics and field labels in the FORM layer, then print the actual data in the DETAIL. The FORM remains constant from page to page.

•	The HEADER structure traditionally prints at the top of each page of the report. Typically, you place the report title, graphics and other introductory elements in the HEADER.

•	The DETAIL structure is the body of the report. It contains the basic data, either in table or record format.

•	The FOOTER structure traditionally prints at the bottom of the report. Typically, you may place a page number, or totals in the FOOTER.

•	A Group BREAK structure can contain its own HEADER, DETAIL, FOOTER structures, plus nested BREAK structures with their own HEADER, DETAIL, FOOTER structures.

The application composes these sections whenever the group BREAK variable changes. The group HEADER and FOOTER print inside the DETAIL section, at an offset vs. the last DETAIL to print.


Variable String Controls

Variable string controls are the are the basic unit for printing data on the page. The Report Formatter places a STRING control with its USE attribute set to a variable in the REPORT data structure.

Via naming the variable--via the USE attribute--the application accesses the data you want to print at runtime. This may be a memory variable, or a specific field in a data file or view. The Report Formatter formats the data according to the picture you specify.

The process of creating the report DETAIL relies on placing variable string controls that reference the data you want. You may place the controls left to right, top to bottom, or in whatever layout you wish.

At print time, you may have the report print the data records arranged as a table comprised rows, automatically handling the page breaks, or you may print a record per page, or even just a summary page.

You may place other types of controls on the report page--but you will probably find that variable strings are the basic building blocks.


Total Fields

A total field is a variable string control (with a variable or data file or view field in its USE variable), with the SUM attribute added. The AVE, CNT, MAX and MIN attributes similarly create averages, counts, maximum and minimum fields.

In general, you place total fields in a page or group FOOTER, so that it can total the records since the beginning of the report, the records on the page, or the records since the last BREAK. You can also place a total field in a DETAIL structure to provide a running subtotal. A tally (CNT) field in the DETAIL can number the records as they appear on the report.

To specify a total field, DOUBLE-CLICK on a variable string field, then press the Use button. Check the Sum box in the Use Attributes dialog. Optionally choose to reset the total to zero each page to provide a page total. The last applies to footers only.


Graphics

A simple graphic element such as a line can visually set off the different parts of a report, making its printed content much easier for the reader to understand.

For example, drawing a line in a group FOOTER prints a line separating each new group from the last. Drawing a shaded box around (and underneath) a group of controls can link them together visually, just as a box filled with color can link screen elements together. Placing your company logo in the HEADER of the report is a simple way to make a report more professional looking.

To place these types of graphics in your report, you choose them from the Controls menu, then draw a box on the page to set the graphics size.


Page Layout and Preview

You can edit your report only in Band View. You may view your report as it appears on the printed page by choosing View [image] Page Layout View, or View [image] Page Preview. Page Layout additionally allows you to move and resize the HEADER, FOOTER, DETAIL, and FORM sections by their handles.


Designing Your Report

Before you can place data elements, you must set up the basics. New reports default to portrait mode--in which the longest sides of the paper align vertically. Setting up the page orientation and the default measurement unit are the first steps.

You must set up the page margins by specifying the DETAIL print area. The default margins are one inch from the left, and two and one half inches from the top. The default DETAIL print width is six inches, and the default height is six inches.

***	The above is subject to change.

Because the Report Formatter gives you total freedom to design the report sections anywhere you wish, plan the type of report you wish to design.


Design Basics

To change the page orientation to landscape, choose Edit [image] Report Properties. When the Report Properties dialog appears, check the Landscape checkbox. New reports default to portrait mode.

To change the default measurement units, from the same measurement box, select from dialog units, thousandths of inches, millimeters, or points.


Margins

The default margins for the DETAIL print area are one inch from the left, and two and one half inches from the top (this allows for the page HEADER). Specify the margins in the Report Properties box by typing in a measurement in the AT Properties dialog:

•	To specify the left margin, enter a value in the Y pos box.

•	To specify the top margin, enter a value in the X pos box.

The units for the margin values depend on the default measurement units you specify in the Report Properties dialog:

•	To set the report dimensions, type the height and width in the AT Properties dialog:

•	To specify the height, enter a value in the Height box.

•	To specify the top width, enter a value in the Width box.

•	To specify the margins for the page HEADER section, you must be in Layout View (choose View [image] Page Layout View). You may directly adjust the page HEADER margin by selecting the section, then dragging to resize it. You may also DOUBLE-CLICK inside the HEADER pane, or CLICK inside, then press the Properties button.

This displays the Page Header Properties dialog. Press the Position button, then specify the margins by entering the values for the X and Y positions.


Report Types

*** The final doc will illustrate these report types

•	A tabular report prints each section consecutively, below the previous. When placing data elements, lay them endtoend horizontally across the page.

•	In a FORM report, which is generally best for printing a single record to a page, you usually create one column of field labels, and one column of data elements next to it. You may optionally place the labels in the FORM layer and embellish it with graphic elements such as lines and boxes, creating a template inside which the data prints.

•	For a label report, for example a three-across format, you create a DETAIL placing the data for the label row-by-row. The width of the DETAIL should be one third the width of the print area.

When the print engine prints the DETAIL, if it is less than the page width, it automatically prints from left to right, top to bottom, on a best-fit basis.

•	For a mailmerge document, you usually place the name and address fields in the HEADER, then reserve the DETAIL for a multi-line text control. This provides word-wrap.

Should you have conditional text, you can create a group DETAIL for each one, then edit the executable code to PRINT the proper DETAIL dependent on a variable associated with the record.


Positioning And Alignment

You can set a specific position for the DETAIL, as an offset vs. the last DETAIL printed. This allows you to exactly place, to the thousandth of an inch, the body of the report. By additionally setting the grid spacing, you can exercise precise control over every object in the report.

To set the position for the Detail, click inside the DETAIL band, and press the Properties button, or DOUBLE-CLICK in the Detail band. When the Detail Properties dialog appears, press the Position button.

When the AT Properties dialog appears, you enter new coordinates. The position is an offset vs. the top of the DETAIL print area. Enter the left margin (X pos), top margin (Y pos), report height and width in thousandths of inches, or your default measurement unit.

Tip:	Use the AT Properties dialog to precisely position Detail structures. When you position a structure on screen, the smallest unit you can move it is usually 1/96 inch. The dialog box allows you to position by thousandths of inches.

To set grid spacing for the entire report, choose Option [image] Grid Size. In the Grid Size dialog, enter the space between each dot in thousandths of inches or your default measurement unit. You may enter a separate value for the X and Y axes.

To turn grid snap on and off, choose Option [image] Snap to Grid. Grid snap forces the handles of newly created objects to align themselves along the dot grid on screen. By default, grid snap is on.


Placing Structures

Lay out your report structure by structure: HEADER, FOOTER, DETAIL, and FORM. Each appears in a separate window pane, or band. To temporarily hide, then to re-display a band, press the restore button on the right side of the pane (this button has a double triangle on its face).


Header

To specify an element to compose at the start of each page, place it in the HEADER. The application automatically generates a page break before each HEADER.

Typically, the HEADER includes a report title, and the page number. Optionally, it is a very useful place to display your company logo. This section describes some of the things you can do in a simple HEADER, incorporating these basic elements.

•	To set the font for any controls that appear in the header:

1.	DOUBLE-CLICK in the Header pane.

2.	When the Page Header Properties dialog appears, press the Font... button and choose the font for the controls which appear in the HEADER.

Normally, the default font is the system font. While this is excellent for the screen, for printed reports a TrueType serif font, such as Times New Roman, makes for easier reading.

•	To add a logo graphic to the HEADER:

1.	Choose Controls [image] Image,then click at the top left hand corner of the HEADER pane.

2.	Specify a file in the Image Properties dialog. Then press the OK button.

The image box appears as a square, the same height as the HEADER pane. Resize it, if necessary, by dragging a corner handle. Move the square, if necessary, by dragging the inside of the image box.

Tip:	Whenever possible, use vectorized graphics such as the Windows Metafile Format (*.WMF). When you need to shrink or stretch them, their appearance is less subject to distortion than a bitmap.

Think visually when designing your reports. A small picture or logo can create a professional looking report.

•	To add a rule the width of the report to the HEADER:

1.	Choose Controls [image] Line and click below the image box.

2.	In the Line Properties dialog, set the line Width to Full.

3,	Set the line Height to Fixed, then type the zero in the blank field next to Fixed. The zero indicates the line has no height--its horizontal.

Rules and lines should be key elements of your report layouts. They can help organize data for the users eyes.

•	To place a control that prints the page number.

1.	Add a string variable control for the page number; choose Controls [image] Variable String. CLICK to the right of the string you just placed.

2.	In the Picture field of the String Properties dialog, type @n3, then type a new equate label in the Use Field. CLICK OK.

3.	DOUBLE-CLICK the control; when the Screen String properties dialog appears. Press the Use button.

4.	In the Use Attributes dialog appears, check the Page number box.


Footer

To specify data to compose at the end of each page, place it in the FOOTER. The application automatically generates a page break after a FOOTER.

Placing controls in the FOOTER is similar to placing controls in the HEADER. You can just as easily duplicate the examples above in a FOOTER, and the example below in a HEADER.

•	To place a Date Printed in a FOOTER structure:

1.	Choose Controls [image] Variable String. Click in the FOOTER pane.

2.	In the Picture field, type a date picture (@d1, for example). Type a variable name in the Use box.

You must make sure that you add the variable to the global variable list, and that you initialize its value to the current date--TODAY().


Detail

To specify the data for the body of the report, place it in the DETAIL. The DETAIL carries the lions share of the data. Additionally, the group HEADER and group FOOTER structures appear inside the DETAIL print area on the page.

When working with the Application Generator, the REPORT probably have one DETAIL. When you directly with the Report Formatter, it will add another DETAIL structure every time you add a BREAK. You can delete the ones you dont use.

Tip:	For best automatic handling when it comes to placing structures on the page, nest your DETAIL inside all other structures. For example, if you have two BREAK structures, one nested in the other, delete all DETAIL structures except the one nested inside the second BREAK.

The most commonly used control for displaying data is the Variable String control. You may fill the string with the contents of a field by specifying the field identifier in the USE attribute. You may also specify a display picture.

A report may have multiple DETAIL structures. This allows you to create alternate report layouts for a single report, then utilize control statements in the source code to allow the user to choose which to print at runtime. Each DETAIL structure requires its own PRINT statement.

Multiple DETAIL structures also allows complete control over what prints where and when through executable code.

The typical steps required to place a field in the DETAIL pane are:

1.	Choose Controls [image] Variable String, then click in the DETAIL pane.

2.	Enter a field name, including its prefix, in the Use field of the Screen String properties dialog.

3.	Edit the picture. or choose other properties if necessary.

4.	Press OK.

A series of dollar signs ($) appears to show the controls print position and size.

Thats all there is to placing a field in a report. There are many language elements to customize the report behavior and field formatting which the later part of this chapter will discuss.


Form

To specify a page element which prints on every page, place it in the FORM. This is a free-floating section which can overlap the other sections.

Use the FORM as a layer, to hold graphic frames or preprinted forms into which the data from the other sections fit. Another use for the FORM is to hold a watermark, which prints underneath the report.

The FORM defaults to the same size as the page, less the margins.

The application composes the FORM at the beginning of the print job; it does not update it with each new page. Therefore, the FORM is not suitable for holding normal data fields, or even a page number. You can, however, print fields from a control file, if you wish to print the same field contents on every page of the report.

Tip:	For best results when using a drawing tool to create a watermark, set the fill for the watermark element to 10% gray, or light gray.

The FORM should guide the user to the data. You might use lines and boxes, for example, to divide the DETAIL into compartments, grouping data and columns for the user. You may even create a greenbar paper effect by alternating gray or light green color blocks.


Group Breaks

Group breaks provide a means of breaking the data into sections and optionally providing subtotals. Each group gathers a set of data file records, all sharing the same value in the BREAK field. Within a report, you may visually separate these rows, and add a subtotal or summary information, usually below the group. Group breaks are also called group bands by some popular end user database applications.

The Report Formatter displays group breaks in a tree structure, which allows you better visualize nested group breaks. The group break may contain the same elements as the report: a group HEADER, group DETAIL and group FOOTER.

Perhaps you wish to print an invoice report by customer. You can then summarize the total invoice values for each customer in alphabetical order. The report prints the group DETAIL for the set of records with the same customer, and places a group HEADER above it, and the group FOOTER below it. These structures all print out inside the DETAIL print area, each following the other by any offset specified in their AT attributes.

Though they print on the page at the same time, the application composes the group HEADER before the group DETAIL. The group HEADER is a good place to identify the group, for example, with a label saying Customer: followed by a variable string for the customer name field.

The group FOOTER, prints after the group DETAIL. You can place a string saying Total: followed by a string variable which contains the field to be summed, with the SUM attribute.

To create a group break:

1.	Be sure the DETAIL pane is visible; if not, press the restore button.

2.	Choose Bands [image] Break.

3.	When the cursor changes to a crosshair, CLICK in the DETAIL.

This inserts the group HEADER, group DETAIL and group FOOTER.

4.	In the Break Properties box, type a valid Clarion label to use as a NAME for the break.

5.	Type a Variable or database field, including the prefix, to break on.

4.	Press the OK button.

When the report prints, it groups all records with the same value for the BREAK field, and prints the group HEADER and FOOTER before and after them.

Tip:	If the break variable is a global or local variable, you must be sure that the executable code updates its value, so that it can generate a group BREAK.


Page Breaks

One of the main considerations when laying out a report is unplanned page breaks. For example, you cant always predict how long or short a group will be. You therefore should plan on how your report will behave when it reaches the end of the page, yet there is still more data (in the group) to print.

There are several options available. Each controls what happens when a DETAIL section may be split at the end of a page.

To access the dialogs which allow you to set these options, DOUBLE-CLICK the DETAIL section. Alternatively, select either section and press the Properties button. This displays the Detail Properties dialog, containing the options below.

You may also set these options for break headers or footers. The options are available in the Break Header Properties and Break Footer Properties dialogs.


PAGEAFTER

To print the DETAIL, then force a new page, type a value in the Page after box in the Detail Properties dialog. This sets the PAGEAFTER attribute. This prints the DETAIL, then prints the page FOOTER, then begins a new page.

Tip:	To print a separate page for each record, place the variable strings and/or controls you wish in the DETAIL, and specify the PAGEAFTER attribute in the Detail Properties dialog.

***  In beta 3, this dialog box requires the newpage parameter. This will be changed.

The page number automatically increments, unless you reset it. To reset the page number to a value you specify, type it in the Page after field in the Detail Properties dialog.


PAGEBEFORE

To print the DETAIL structure on a new page, type a value in the Page before box in the Detail Properties dialog. This sets the PAGEBEFORE attribute. The report prints the full DETAIL starting at the top of the next page. The report FOOTER, however, prints on the first page.

***  In beta 3, this dialog box requires the newpage parameter. This will be changed.

The page number automatically increments, unless you reset it. To reset the page number to a value you specify, type it in the Page before field in the Detail Properties dialog.


WITHNEXT

To prevent widow elements in a printout, type a value in the Keep next field in the Detail Properties dialog. This sets the WITHNEXT attribute. A widowed print element is one which prints, but then is separated from the succeeding elements by a page break.

The value specifies the number of succeeding elements to print--a value of 1, for examples, specifies that the next element must print on the same page, else page overflow puts them on the next.


WITHPRIOR

To prevent orphan elements in a printout, type a value in the Keep prior field in the Detail Properties dialog. This sets the WITHPRIOR attribute. An orphaned print element is one which prints on a following page, separated from its related items.

The value specifies the number of preceding elements to print--a value of 1, for examples, specifies that the previous element must print on the same page.

Tip:	When placing subtotals or totals in a DETAIL, use the WITHPRIOR attribute to insure they print with at least one member of the column above it when a page break occurs.


Adding Text Labels and Fields

The most important part of the report creation process is laying out the fields--placing the data on the page. Clarion allows you to place strings and variable string controls on the page for basics. You may also place other controls--graphics and specialized controls such as listboxes--in your report.


Strings

Among the first items you place on the report will probably be titles or labels. String controls are useful for elements such as.

•	To create column titles for a tabular report, place them at the bottom of the HEADER, so that they appear at the top of each DETAIL section, above the data.

Tip:	When placing data controls, be sure to line up the left handles of the data controls with the left handles of the titles, to left justify them.

•	To create labels for a form report, place them alongside each field, within the DETAIL.

•	To place a string control in your report:

1.	Choose Controls [image] String. The cursor changes into a crosshair.

2.	Click in the band which should contain the control. The center of the crosshair determines the upper left corner of the control.

The Report Formatter places a STRING control in the report structure.

Once you CLICK, the String Properties dialog appears. Fill in the properties dialogs for report controls just as you would window controls (within the Window Formatter).

•	To specify statictext for the string, type the text you wish to display directly in the String Text field.

•	To instruct the report to print a dynamic string, place a picture token in the String Text field, then specify a variable in the Use field.

•	To center a title or label appearing over a column of data within a table, choose Centered from the Justification dropdown list.

•	To right align a title or label appearing over a column of numeric data within a table, choose Right Justified from the Justification dropdown list.


Variable Strings

Variable string controls usually hold most of the data in a report. Numeric data must be formatted with a picture token for the report.

•	To place a variable string control in your report:

1.	Choose Controls [image] Variable String. The cursor changes into a crosshair.

2.	CLICK in the band which should contain the control. The center of the crosshair determines the upper left corner of the control.

Once you click, the Screen String Properties dialog appears. The Report Formatter places a STRING control in the report structure.

3.	To properly format the variable string, type in a picture token appropriate to the original data (for example, for a numeric value of 3 digits, type @n3--dont try to convert it to a string, as in @s3).

4.	To identify the variable to print, type in its name or equate in the Use field.

To place a database field in the report, type its label prefix, a colon, and the field name; for example, NAM:FirstName. To place a variable in the report, type its name; for example, MyVariable.


Multi-Line Text

A multi-line text control can print a long string (such as a memo) in the report for you, automatically word-wrapping and printing as many lines as the controls physical size allows.

For each variable string control to place in your report:

1.	Choose Controls [image] Text.

2.	CLICK in the band which should hold the control.

The center of the crosshair determines the upper left corner of the control. Once you click, the Text Properties dialog appears. The Report Formatter places a TEXT control in the report structure.

3.	Specify the variable or field to print by typing its label in the Use field.

Probably the most important pieces of information to fill in for the Text variable are position and size. The simplest way to create a multi-line text box at the size you wish is to accept the defaults, press the OK button in the dialog, then resize the box by using the mouse to drag the handles. The onscreen rulers help verify the correct sizing.

4.	To specify an exact size for the TEXT control, press the More>>> button to unfold the Text Properties dialog, then press the Position button.

5.	Specify a fixed size in the Width and Height boxes, then enter values for both, using the default measurement unit.

*** For beta 3, the edit boxes will only accept up to 999--which limits the size to under an inch by an inch! But you can still drag using the mouse to make it bigger. This will be changed.

Tip:	To specify an approximate number of lines to print, specify the Text control size in points, (the POINTS attribute). If, for example, the font size for the control is ten points, allow 20% extra for leading (the space between each line), Multiply the result (12 points) by the number of lines you wish. For example, for a five line control using 10 point type, type 60 POINTS in the Fixed Height field.


Adding Graphic Controls

Graphic controls embellish the report and guide the readers eye to the data.


Images

Most likely you will wish to place an image, such as a logo, in a HEADER. You may choose from the .BMP, .ICO, or .WMF file formats.

***	The above is subject to change; the final release may support additional formats.

The most important consideration when placing a bitmap is its size--Clarion automatically resizes the bitmap to fit the control size. This may introduce distortion if it shrinks or stretches the bitmap. The simplest way to prevent distortion is to keep the same ratio between the pixel resolution and the printed resolution.

To size a 640 x 480 pixel graphic, for example, determine its height-to-width ratio, which is 4:3. Plan an image box in the same ratio--for example, 2000 x 1500 thousandths, which represents a 2 inch by one and a half inch box on the page.

The Report Band View previews the image. You may even shrink and stretch the image by selecting it and dragging the handles.

To place an IMAGE control in a band:

1.	Choose Controls [image] Image.

2.	CLICK in the band where you want to place the control.

The center of the crosshair determines the upper left corner of the control. When you CLICK, the Image Properties dialog appears. The Report Formatter places an IMAGE control in the report structure.

3.	Type the fully qualified image file name in the File field, or press the ellipsis (...) button next to it, then select the file from the file dialog.

Clarion automatically links the image file in the executable when the file is explicitly named in the control.

4.	Type in a field equate label to refer to the image control in source code.

5.	Press the Position button.

6.	Type the correct image size in the fixed Width and Height fields.

7.	Press OK.


Line

Lines are the simplest means of visually separating sections or fields within your report. When you create a line, you must first CLICK to establish its origin, fill in the Line Properties dialog, then either specify the size and position of the line in the dialog box, or close the dialog and use the mouse to place the line exactly where you want it.

1.	Choose Controls [image] Line--the cursor changes to a crosshair.

2.	CLICK in the band in which you want to place the line.

The center of the crosshair determines the origin. When you click, the Line Properties dialog appears. The Report Formatter places an LINE control in the report structure.

3.	Type in a field equate label in the Use field to refer to the line control in source code.

4.	Press the Position button, if you wish to specify exact coordinates for the line by typing them in.

To specify a horizontal line, be sure to check fixed in the Height group, and type a zero in the box next to it. The height is the measure of the vertical distance between the origin and the end point; for a horizontal line, this is equal to zero. Type the length of the line in the fixed Width box.

To specify a vertical line, check fixed in the Width group, and type a zero in the box next to it. The width is the measure of the horizontal distance between the origin and the end point; for a vertical line, this should be zero. Type the length of the line in the fixed Width box.

To specify a horizontal or vertical line the full width or height of the section, check the Full option.

Tip:	To create a horizontal rule, or divider line useful for splitting a HEADER from the DETAIL section, for example, check Full Width, and set the Fixed Height to zero. To create a very thick rule, you must use a BOX control, also checking Full Width to place it across the page.

5.	To specify a line color, after closing the Position dialog, press the Line Color button, and choose a color from the samples boxes.


Box

You can highlight a report field by placing a gray box underneath it. You can frame an entire area of a report by placing a box with no fill around it. To place a box:

1.	Choose Controls [image] Box.

2.	CLICK in the band in which you want to place the box.

The center of the crosshair determines the upper left corner of the box. When you click, the Box Properties dialog appears. The Report Formatter places a BOX control in the report structure.

3.	Type in a field equate label in the Use field to refer to the box control in source code.

4.	Set the FILL attributes.

If you want a solid box filled with color, check the Fill check box, then press the Fill Color button and choose a color from the samples boxes.

5.	To give the box a border (or edges) and choose its color, set the COLOR attribute.

If you want a colored border, check the Border check box, then press the Border Color button and choose a color from the samples boxes.

6.	If you want rounded edges for the box, check the Round checkbox to set the ROUND attribute.

7.	To set the size of the box by typing in coordinates, press the Position button. Type the measurements you wish in the Fixed Width and Fixed Height boxes.

Tip:	To create a border or frame around the whole report, place a box in the Form band. Be sure the FORM is the full size of the page. Create a box with a border but no fill, and set the width and height to Full.

8.	Press the OK button to close the Position dialog.

9.	Press the OK button to close the Box Properties dialog.

You may make adjustments to the box size by dragging its handles with the mouse.


Ellipse

When placing an ELLIPSE in a report, follow the same procedures as for placing a box.

Remember, however, that the four position coordinates (AT attribute) specify the outer bounds of the ellipse. These define a box whose perimeter exactly contains the ellipse.


Adding Specialized Controls

The Report Formatter gives you the ability to print on the page virtually anything you can put on the screen. Just as a specialized control performs a function on screen--such as graphically portraying a choice, like radio buttons--these same controls may perform the same function in your printed report.


List

When the data you require for the report exists in a QUEUE, you may place a listbox in the report. The listbox that appears on the page is similar to the LIST control that appears on screen, though it will obviously not have the same functionality--the printed page does not support scroll bars, for example.

Because Clarion provides so many listbox formatting options, adding a LIST to the report allows you to create a fancy pigeonholes, suitable for columns and rows of items, for example.

At print time, the first time the code cycles through the queue, it prints the LISTs header, and the first item in the queue. Each additional cycle prints the next member of the QUEUE, without repeating the HEADER. The LISTs footer prints at the end of the QUEUE.

Printing a listbox, rather than individual variable strings, is probably most useful when youve pre-formatted a LIST for the screen, such as a browse window.

To place a list in your report:

1.	Choose Controls [image] List.

2.	CLICK in the band which should contain the control.

The center of the crosshair determines the upper left corner. When you click, the List Properties dialog appears. The Report Formatter places a LIST control in the report structure.

*** Illustration: the listbox formatter, when revised

3.	Type the origin of the listbox data--the QUEUE--in the From field.

4.	Type a field equate label to reference the listbox in the Use field.

5.	Press the Format button to use the Listbox Formatter to format the listbox appearance.

*** this will be described in detail in the Listbox Formatter chapter. Because the Formatter is going to be changing, Beta 3 users should refer to the temporary appendix.

6.	Press the Position button to set the size of the listbox.

Tip:	To create a quick and dirty report from a browse list, choose Full for the Width and Height of the Listbox control within the DETAIL.


Option

You may print an OPTION structure within your report. This appears on the page exactly like it does on screen--as a group box. You may optionally hide it on your report.

You place an option structure on the page only to hold radio buttons. You may hide the structure so that it does not print on the page.

1.	Choose Controls [image] Option.

2.	CLICK in the band in which you want to place the OPTION structure or group box.

The center of the crosshair determines the upper left corner of the box. When you click, the Option Properties dialog appears. The Report Formatter places an OPTION structure within the report structure.

3.	Type in a caption for the group box.

If you choose not to hide the option box when printing, the caption appears at the upper left corner of the box, just as it does on screen.

4.	Type a variable name in the Use field.

This determines the value of the selected radio button.

5.	Press OK.

You must add each radio button separately, placing them in the OPTION box.


Radio

Placing RADIO buttons in a printed report provides a visual aid to the user, by showing all the possible values for a single field in a record, and marking the one which is chosen.

Before you place the radio buttons in the report, you must first place an OPTION structure, by using the Controls [image] Option command. The RADIO button must be placed (at least initially) inside the group box representing the OPTION structure. If you attempt to place a radio button without an OPTION structure, the IDE displays an error message.

1.	Choose Controls [image] Radio.

2.	CLICK inside the OPTION structure or group box.

The center of the crosshair determines the upper left corner of the radio button. When you click, the Radio Button Properties dialog appears. The Report Formatter places an RADIO control within the OPTION structure.

3.	Type button text for the radio button.

This appears next to the radio button when the report prints.

4.	Type a field equate label in the Use field.

Use the equate label to refer to the radio button in your code. The radio button automatically turns on or off according to the value of the variable specified in the OPTION boxs USE attribute.

5.	Optionally create a 3D latched button by placing the ICON attribute on the button.

To do so, select an icon style from the Icon dropdown list. Remember to place a text label next to the button if you use the ICON attribute.

Tip:	If you expect your users may print the report on a low resolution printer, the latched icon style does not provide the best choice for clarity.

6.	Press OK.


Check

The checkbox (CHECK control) provides an attractive way to display a yes/no choice for a record field--the alternative might be an entire column that repeats one, yes, or even .T. for each record.

The printed checkbox looks similar to an onscreen checkbox. To place the checkbox:

1.	Choose Controls [image] Check.

2.	CLICK inside the band where the control will belong.

The center of the crosshair determines the upper left corner of the check box. When you click, the Check Box Properties dialog appears. The Report Formatter places an CHECK structure within the report structure.

3.	Type the label text for the check box.

This appears next to the check box when the report prints.

4.	Type a variable name in the Use field.

This should refer to a numeric variable which turns on or off the check box. A value of zero indicates the box is unchecked; any other value, checked.

5.	Optionally create a 3D latched button by placing the ICON attribute on the check box.

To do so, select an icon style from the Icon dropdown list. Remember to place a text label next to the button if you use the ICON attribute.

6.	Press OK.


Group

The primary reason for placing a group box in a report is to make a group of controls on paper resemble their appearance on screen.

To place the GROUP control:

1.	Choose Controls [image] Group.

2.	CLICK inside the band where the control will belong.

The center of the crosshair determines the upper left corner of the check box. When you click, the Group Properties dialog appears. The Report Formatter places a GROUP structure within the report structure.

3.	Type the Caption Text.

This appears at the upper left of the group box when the report prints, provided you mark the Boxed checkbox.

4.	Type a field equate label in the Use field.

Use the equate label to refer to the group box in your code.

5.	Press OK.

6.	Add additional controls to the group.


Custom

You may place a .VBX CUSTOM control in your report. There are a number of custom control libraries available which are very suitable for reports--including graphs and other visual elements. To place the control:

1.	Choose Controls [image] Custom.

2.	CLICK inside the band which will hold the control.

The center of the crosshair determines the upper left corner of the custom control. When you click, the Custom Control Properties dialog appears. The Report Formatter places a CUSTOM control within the report structure.

3.	Type a title for the control in the Text field.

The .VBX control may or may not display its title on the page, depending on the .VBX you use.

4.	Type the name of a variable in the Use field, to pass a value to the control.

The variable type depends on the .VBX control.

*** Please see the Controls chapter for additional details.

5.	Depending on the .VBX, choose a control type.

6.	Specify whether to print the control as a metafile.

To print a representation of the control, check the Meta checkbox. This outputs the control as a Windows metafile.


Adding Graphs

In addition to placing a simple image control on a page, such as when you place a logo in the HEADER, you may sometimes wish to create a report which includes a graph.

•	When creating a report whose sole purpose is to print a fancy graph, you may also wish to use the ----.VBX add-in.

***	There will more to say about this at a later date.


Graph .VBX

***	Pending further developments...


Sample Report Designs

The examples following the next section illustrate the flexibility of the Report Formatter. The attached code contains generic database field names, which you could quickly adapt to your own. All reports assume a paper size of 8.5 x 11 inches, with .75 margins all around.

***	The samples will be added before the final release.


Miscellaneous Report Design Tips

This section provides hints on using the Report Formatter to take advantage of its flexibility. It provides hints on creating better looking reports, and shows you how to customize the New Structures dialog, how to output a report to .WMF or .TXT files, plus how to build a Print Preview command into your application.


Arranging Controls

•	The simplest step you can take to insure your report looks good is to turn on grid snap and line up your data. Choose Option [image] Snap to Grid.

•	To line up a tabular report, place each field in a row, using grid snap to align the bottoms of the fields.

•	To create a FORM report, arrange each field on a new line. Optionally place a label next to each. Place the PAGEAFTER attribute on the DETAIL section.


Arranging Groups

•	When creating a simple banded layout, mark the Default checkbox for Width in the AT Properties dialog for each section.

•	To arrange groups or sections side by side, choose View [image] Page Layout View. Choose Edit [image] Next Band to cycle through each band--the name of the current band appears on the status bar. Resize bands by dragging their handles with the mouse.

**** more...


Adding Default Report Structures

The IDE allows you to add customized reports to the New Structures dialog. This allows you to store any generic report FORM you create, right down to the field names, then automatically create it again in another application ready to customize.

To store a particular report:

1.	Create the report using the Report Formatter.

Make the report as complete as you want, right down to the database fields. If you plan on making a template, whose title may change from new report to new report, try placing a title string such as Basic Report. When you create a new report, you may then simply open the properties dialog for the string control and change the title text.

2.	Exit the report writer and open the source code document.

3.	Locate the REPORT structure and copy it to the clipboard, (Edit [image] Copy) from the label to the last END statement.

3.	Choose File [image] Open, open the DEFAULTS.CLW file, in the LIBSRC subdirectory, and scroll to the bottom of the file.

4.	Skip a line after the last line of the last structure, and type:

!!> Report YourReportNameHere

5.	Add a carriage return at the end of the line, and paste (Edit [image] Paste) the clipboard contents starting in the first column of the next line.

6.	Choose File [image] Save, then File [image] Close.

When you next create a new structure, your report will appear on the scroll list, at the bottom.


TXT Files

***	To be added


Print Preview

***	To be added


Using the Text Editor

Opening the Editor

Managing Source Code Windows

Using the Edit Menu

Undo

Cut

Copy

Paste

Select All

Goto Line

Goto Next Error

Goto Previous Error

Set Tabstop

Set Right Margin

Reformat Paragraph

Format Structure

Extended Functions

Using The Search Menu

Repeat Last Find

Repeat Backwards

Find Marked Text

Customizing the Editor

Line Formatting Options

Tabs

Block Replace

Remove Block

Colors

Editing Errors


Opening the Editor

Anytime you view a source code document, you use the editor. Here are several ways to open a document within the IDE:

•	Use the File [image] New command, then choose Clarion Source in the New dialog. This opens a blank source code document.

•	Use the File [image] Open command, then choose a source code file in the standard Open File dialog. Clarion Source is the default file type, and .CLW is the default file extension.

•	Use the File [image] Pick command to view your most recently edited files. Select a source code file, and press the Select button.

•	DOUBLECLICK a source code file appearing in any of the dialogs which appear upon pressing any of the first three buttons on the toolbar: Pick, New, and Open File.

***	Its possible we may support File Mgr associations for doc files later

•	Within a Project Tree Window, highlight a source code (.CLW) file, and press the Edit button.

•	After an unsuccessful compile, press the Edit Errors button.


Managing Source Code Windows

Each source code file appears in a separate document window. This section  provides a short summary of actions you can take to change the layout of an open document window(s) within the IDE:

Close a window	Choose File [image] Close from the main menu; choose Close from the windows control menu; double click the windows control menu; or press CTRL+F4.

Activate a window	Click anywhere within the window; or select the document name from the Window menu. Alternatively, press CTRL+F6, or CTRL+TAB until the window you wish is active.

Move a window	Drag the document windows title bar with the mouse. Alternatively, choose Move from the windows control menu, then use the cursor keys, then press ENTER to set the window in place.

Resize a window	Drag its border with the mouse. Alternatively, choose Size from the windows control menu, use the cursor keys to resize, then press ENTER to resume editing.

Maximize a window	Press the maximize button on the document windows title bar; or choose Maximize from the windows control menu.

Iconize a window	Press the minimize button on the document windows title bar; or choose Minimize from the windows control menu.

Restore iconized	To restore an iconized document window, double click the document window icon; or choose Restore from the icons control menu.

Cycle to next doc	To switch to the next document, press CTRL+F6 or CTRL+TAB.

Tile the windows	To arrange all open document windows side by side, choose Window [image] Tile vertically or Window [image] Tile horizontally from the main menu. This provides easy access to documents, as in the illustration below.

Cascade windows	To arrange all open document windows so that the title bars are all visible, choose Window [image]  Cascade from the main menu.


Using the Edit Menu

The process of typing and editing source code is similar to the Windows Notepad accessory. Type the code as if you were typing at a typewriter. To use an editing command, such as Copy, highlight the text you wish the command to act upon, then choose the command. When you wish to insert text, click with the I-Beam cursor at the place you wish to insert text, then type.

The Edit menu features the primary editing commands. This menu appears whenever the active window in the IDE is a source code window. The following sections detail the commands on the Edit menu:


Undo

To undo the most recent editing action, choose the Undo command. This menu item changes to reflect the context of the undo action. Should you type a line of text, the menu item will show that you may Undo Line Edits. Should you delete a line of code, it will allow you to Undo Block Delete.

Certain commands cannot be undone, such as saving a file.


Cut

To delete the highlighted text from the document and hold it in the clipboard, choose the Cut command. The keyboard accelerator is CTRL+X.


Copy

To copy the highlighted text and hold it in the clipboard, use the Copy command. The keyboard accelerator is CTRL+C.


Paste

To place the contents of the clipboard (text only) into the document at the insertion point use the Paste command. The keyboard accelerator is CTRL+V.


Select All

To highlight all the text in the document so that the next editing command affects the entire document, choose the Select All command.


Goto Line

To jump to a specific source code line to edit, choose Goto Line... The keyboard accelerator is CTRL+G.

The editor places the insertion point in the first column of the line number you type in the dialog box. The status bar reflects the current line and column numbers for the insertion point position.


Goto Next Error

To quickly move the insertion point to the next compiler error, choose this command. The Editor places the cursor at the part of the statement where it detected the error.

This command is disabled except following a compile which generated errors.


Goto Previous Error

To quickly move the insertion point to the previous location at which the source code generated a compiler error, choose this command. The Editor places the cursor at the part of the statement where it detected the error.

This command is disabled except following a compile which generated errors.


Set Tabstop

To place a custom tab stop on a line...

***	not implemented yet


Set Right Margin

***	not implemented yet


Reformat Paragraph

***	not implemented yet


Format Structure

Think of this as visually editing a structure--a window or report--in the source code. Just place the insertion point on any line within the structure. The Window Formatter (or Report Formatter) compiles the code for the structure, then creates a sample on screen ready for editing with the toolbox controls or property boxes.

When you exit the Window Formatter (or Report Formatter), the structures source code reflects the changes you made. This provides seamless interaction at the source code level with the visual design tools.

You may also place the insertion point on a blank line, then call the Window Formatter to create a new structure. When you return to the editor, the source code document will contain a new structure that creates the object you drew with the Window Formatter (or Report Formatter). It is up to you to make sure that you insert the structure in the data section of the program.


Extended Functions

The Extended Functions are a group of handy editing commands on a cascading menu:

Duplicate Line	To duplicate the entire line and place the copy on the next line, choose this command or press CTRL+2. The original line need not be highlighted; simply position the cursor anywhere on the line.

Center Line	To center the contents of the current line, choose this command or press CTRL+6.

Toggle Case	To change the case of next character following the insertion point, choose this command or press CTRL+/. A lower case letter becomes upper case, and vice versa.

Delete Line	To delete the entire line on which the insertion point is located, choose this command, or press CTRL+Y.


Using The Search Menu

The Search menu makes it easy to find and change elements in your source code documents. You may search for specific text, change occurrences of selected text throughout the document, or simply highlight a variable, for instance, then jump to the next occurrence of it in the code.

The commands on the Search menu are:

Find	To find the next occurrence of a word, type it in the Find dialog.  It allows you to type in a word, then find the next occurrence forwards or backwards from the current position of the insertion point. The keyboard accelerator is ALT+F3.

The Find dialog is modeless. This means that the dialog will remain on screen so that you may easily search again. This makes it easy to repeat a search several times quickly, using the Find Next button.

1.	Specify the text to search for.

The default contents of the Find What box is the last text searched for.

2.	Optionally specify that the search should only check for the occurrence of the text as a whole word.

For example if you search for the word find, it will not jump to an occurrence of the word findings.

3.	Optionally specify that the search match the case of the search word.

4.	Specify whether to search forwards or backwards.

5.	Press the Find Next button to start the search.

Replace	To change specific text to something else, type the original and replacement text in the Replace dialog. You may make the changes one at a time, throughout a selected text block, or throughout the entire document.

The Find dialog is modeless. This means that the dialog will remain on screen so that you may easily search again. This makes it easy to repeat a search several times quickly, using the Find Next button.

1.	Specify the original text to change.

The default contents of the Find What field is the last text searched for.

2.	Type in the text to replace it in the Replace with field.

3.	Optionally specify that the search should only check for the occurrence of the text as a whole word.

For example if you search for the word find, it will not jump to an occurrence of the word findings.

4.	Optionally specify that the search match the case of the search word,.

5.	To display the next occurrence of the original text and stop before changing it, press the Find Next button.

The IDE will ask you to confirm the change.

6.	To change the next occurrence of the original text without confirmation, press the Replace button.

7.	To change all the occurrences of the original text in the selected block (or the entire document if you selected all or nothing), press the Replace All button.

The Replace dialog is modeless. This means that the dialog will remain on screen so that you may easily replace again. This makes it easier when you change text one occurrence at a time.


Repeat Last Find

To search for the same text you last searched for, choose this command or press the F3 key. This searches in a forward direction.


Repeat Backwards

To search for the same text you last searched for in a backward direction, choose this command or press SHIFT+F3.


Find Marked Text

To quickly find the next occurrence of the currently highlighted text, choose this command or press CTRL+F3. This is equivalent to executing the Find command, typing the currently selected text in the Find What field, and specifying a forward search.


Customizing the Editor

To personalize your editing environment, customize appearance and cursor behavior with the Editor Options dialog. To view the dialog, choose Setup [image] Editor Options.


Line Formatting Options

To customize what happens to the line formatting as the cursor moves during normal editing tasks, set the checkboxes in the top left.

Indentation	To automatically indent new lines, check the Indent New Line box. This will make your code more readable.

Insert	*** not implemented yet

Word-Wrap	*** not implemented yet

Split Line	To automatically begin a new line whenever you press ENTER without splitting the current line, uncheck this box. A new blank line will appear below the current line. The insertion point will appear on the new line.When the option is checked, ENTER will split the line, and the second part will appear on a new line.


Tabs

To set the default spacing between tabs, enter a number in the Tab Size box.


Block Replace

To delete a selected block when pasting, check the Automatic Block Delete box. To insert before a selected block, uncheck the box.


Remove Block

***	not yet implemented


Colors

To choose the color assignments for syntax highlighting, press the Colors... button. The Editor Color Settings dialog appears.

The dialog allows you to set color choices for nineteen different editor elements, including Clarion language statements, highlighted text, and comments.


Editing Errors

One of the chief entry points into the editor is via the compilation results window --when an error aborts the make.

The Edit errors button automatically calls the editor, and places the insertion point at the position where the compiler detected the error. You may then edit the source code to correct the mistake. The Edit [image] Goto Next Error command is available to jump to the next compilation error once you correct the first error.


Using the Project System

The Project System visually manages the source code files, external libraries, resources, and other components of the application in a tree metaphor. The Project System is functionally equivalent to MAKE files in other compiler languages.

A Simple Project File Walkthrough

Project File Procedures

Adding Source Code Files

Adding Standard Libraries

Adding External Resources

Adding Other Projects

Setting the Target File

.EXE Files and CDDWRUN.DLL

.LIB Files

.DLL Files

Setting Project File Options

Project Global Options

Object File Compile Options

Target File Link Options

Editing the Redirection File

Project System Menu Commands

The Project Menu

Other IDE Commands

Calling the Windows API


A Simple Project File Walkthrough

This section provides an overview of the steps necessary to create a project file (*.PRJ). The Project file tracks all the components that make up the final executable file. It also sets the compiler options ranging from whether to include debug code or not, to setting a preferred optimization method.

If you use the Application Generator to create your source code, the only thing you will probably use the Project System for is to set debugging options.

The Project Tree dialog organizes all the components, and provides access to the dialogs that choose additional options.

To create a simple project file, take these steps:

1.	From the IDE menu, choose Project [image] New Project. The New Project File dialog appears.

2.	Type in a short text description for the Project Title.

3.	Press the Browse button next the Main File field. Locate the main source file and either DOUBLE-CLICK the file name, or select it and press the OK button.

4.	The previous step automatically filled in the Target and Project File names. If you wish to set a different name for either, edit the names.

5.	Press the OK button to display the Project Tree dialog.

6.	To link the database driver, select Library and object files within the Tree list, and press the Add File button.

7.	Locate the .LIB file (or files) which correspond to the database driver(s) used by the application. For example, when using the Clarion 3.0 driver, link in the file CDDWC21.LIB. All the .LIB files shipped with Clarion should be in the LIB subdirectory. DOUBLECLICK the file name, or select it and press the OK button.

8.	Back in the Project Tree dialog, select the first line (Project: text description) and press the Properties button. The Global Options dialog appears.

9.	To prepare the project for debugging, mark the Develop checkbox, and press the OK button to return to the Project Tree dialog.

10.	Choose File [image] Save As. Type a name for the project file (*.PRJ), then save the file.


Project File Procedures

These topics explain project file management.

Adding Source Code Files

Adding Standard Libraries

Adding External Resources

Adding Other Projects


Adding Source Code Files

Adding a source code file to the Project Tree dialog is simply a matter of DOUBLECLICKING a file name.

•	To add a generated source code file, highlight the Generated Source Files option in the Project Tree list. Then press Add File, and select the file you wish to add with the standard Open File dialog.

In general, if youre working with generated source code, you should already have a project file which lists the source code files. This option is provided so that you may manually create the project file.

•	To add hand-coded source code files to the list, highlight External Source Code Files. Then press Add File, and select the file you wish to add with the standard Open File dialog.


Adding Standard Libraries

The standard libraries included with Clarion allow you to resolve references to external procedures and data during linking. Clarion places all library files (*.LIB) in the LIB subdirectory by default.

To link a standard library, highlight Library and object files in the Project Tree list, then press the Add Files button. Locate the file in the directory list, then DOUBLE-CLICK or select the file and press the OK button. The .LIB file appears in the Project Tree, and functions referenced in source code are linked into your application.

The standard libraries include:


Adding External Resources

One of the most likely things youll wish to do with the Project System is to specify resources to link into the executable. These include graphics, namely, .BMP, .ICO and .WMF files. By linking them into the executable, you can avoid having to ship them as separate, external files.

If you directly reference a graphic file within a data structure, the compiler automatically links the graphic, so you may skip this. For example, if you place an icon control in a window, and specify a file by name in the Image Properties dialog, the linker automatically includes the file. But if you create a control, then wish to place another graphic in the control through a property assignment, the linker will only add the file if you explicitly instruct it to.

To add graphic files to the executable:

1.	Highlight Library and object files in the Project Tree dialog.

2.	Click the Add File button, then type in the name of the bitmap, icon, or metafile graphic. Press the OK button to return to the Project Tree. The Project Tree dialog lists the file.

3.	Select the source code file that references the graphic, and press the Edit button, to open the file.

4.	Locate the reference to the file in the source code. Most likely, using the Search [image] Find command will locate it fastest.

5.	Place a tilde (~) in front of the file name.

6.	Save the file, then recompile. The executable should no longer require the external graphic file.


Adding Other Projects

The Project System can compile another project(s) referenced in the current project file. The other project can even specify yet another, in a cascading sequence of compile references.

Cascading projects allows you to split the development process into separate .OBJ files, then link them all toether when youre ready. To add a project to the list:

1.	Select Projects to Include in the Project Tree list.

2.	CLICK the Add File button, then choose another project file from the Add File dialog.


Setting the Target File

Using the Project System, you may easily create .EXE, .LIB, or .DLL files. This section provides you with information on creating these files, as well as brief explanations of the files themselves.

•	The project system assumes by default that you wish to create a standard executable  (.EXE) file. When you name the project file in the New Project File dialog, it automatically sets the project filename, plus the extension .EXE as the target file.

•	To create a library (.LIB file), just change the target extension in the Project Tree. If the current target file contains an .EXE file extension, highlight it and press the Remove File button. Then press the Add File button, and type in the name of the .LIB file you wish to create, including the file extension. Press the OK button.

•	To create a .DLL (dynamic link library), just change the target extension in the Project Tree. If the current target file contains an .EXE file extension, highlight it and press the Remove File button. Then press the Add File button, and type in the name of the .DLL file you wish to create, including the file extension. Press the OK button.


.EXE Files and CDDWRUN.DLL

.EXE files created using Clarion for Windows require the file CDDWRUN.DLL be present on the end users system. The file may reside in the same directory as the application, in the Windows\System subdirectory, or in a directory referenced in the DOS PATH.

Multiple Clarion applications may use the same CDDWRUN.DLL file, avoiding the need to duplicate space on the end users hard drive. Windows loads CDDWRUN.DLL into memory only once; each Clarion application accesses the same copy. This keeps the memory requirement for running multiple Clarion applications at the same time reasonably low.

We recommend placing CDDWRUN.DLL in the Windows\System directory.

Should you install to the system directory, always check whether another copy of CDDWRUN.DLL may have already been installed there by another application. If so, your installation program must check the internal version number of the file, and replace it only if your copy is a more recent version.

***	VERSIONINFO is not implemented in the Beta 3 release


.LIB Files

Library files contain external procedures and functions which are linked to your application at compile time. To create library files which may be accessed via Clarion for Windows, or any of the TopSpeed compilers, just set a .LIB file as the target file.

To import functions from a precompiled .LIB file, you must prototype all external procedures and functions. You may call .LIB functions and procedures from your generated programs by:

1.	(*** fill in when the Application Generator is more complete)

To call an external .LIB procedure from hand coded source:

1.	Add a MODULE structure to your applications MAP.

The MODULE should reference the external library file:

2.	Add the function or procedure prototypes:

MAP

Proc1

Proc2

MODULE(EXTERNAL.LIB)

ExtProc(*CSTRING),RAW

ExtFunc(USHORT, *BYTE[]),USHORT

END

END

Each prototype starts with the name of the procedure or function, the data types of any parameters (in parentheses), and the return data type (if a function).

In the example above, the procedure (here named ExtProc) expects the address (without the length, hence the RAW attribute) of a CSTRING to be passed to it as a parameter.

The function (here named ExtFunc) expects the addresses of a USHORT variable, an array of BYTEs, and will return a USHORT.

3.	To optionally specify a stack-based calling convention, add it to the prototype.

You may use .LIB or .OBJ files created by other compilers, even if they do not use TopSpeeds register based parameter passing convention.

Modifying the above examples, the first line below identifies the procedure as expecting the C calling convention. The second line identifies the function with the PASCAL calling convention:

ExtProc(*CSTRING),C,RAW

ExtFunc(USHORT, *BYTE[]),USHORT,PASCAL

4.	To optionally specify a third party linkers identifier, add it to the prototype.

Some linkers, most notably Microsofts, add a leading underscore to the name of procedures and functions at compile time. The examples below add the NAME attribute:

ExtProc(*CSTRING),C,RAW, NAME(_ExtProc)

ExtFunc(USHORT, *BYTE[]),USHORT,PASCAL,NAME(_ExtFunc)


.DLL Files

Dynamic Link Libraries contain external procedures and functions which are linked to your application only at runtime.

A .DLL may be shared by more than one Clarion application, cutting down on the overall disk space and memory requirements. By planning beforehand, especially when your application is divided into multiple .EXE files, you can substantially cut down the memory requirement on the end users system by placing procedures used by more than one .EXE in a dynamic link library.

To create library files which may be accessed via Clarion for Windows or any of the TopSpeed compilers, just set a .DLL file as the target file extension.

Tip:	.DLL files created with Clarion for Windows may only be used by other Clarion programs, by applications created using a TopSpeed compiler. Clarion applications utilize the TopSpeed register-based parameter passing convention, rather than a stack-based convention.

A Clarion program, however, can access .DLLs created by other compilers. All you need to do is specify the different calling convention. In most cases, this will be the PASCAL convention.

To call an external .DLL procedure follow the steps outlined for calling a .LIB procedure, above.


Setting Project File Options

These topics describe the individual components of the project file, and show you how to modify their properties.

Project Global Options

Object File Compile Options

Target File Link Options


Project Global Options

Select the first line of the Project Tree listing and press the Properties button to open the Global Options dialog. This includes the following options:

Title:	To add a short text description, type it in the Title field. The Project System will list the description next to the Project name in the Project Tree list.

Mode:	To specify the debug setting, select one of the following options: Off, Minimum or Full.

CPU	To specify optimization by microprocessor type, choose from 286, 386, or 486.

Tip:	While its true that Windows has no special mode nor even optimizations for the 486, the Clarion compiler can build 486 specific code into the application.

Line Numbers:	To specify line numbers be built into the object file, for Debugger use, mark the checkbox.

Optimize Speed	To favor program speed over creating a smaller executable file, mark the checkbox.

Stack Overflow	To enable stack overflow warnings, mark the checkbox.

NIL-Pointer	To allow compiler warnings when dereferencing of null pointers, mark the checkbox.

Array Index	To have the compiler check for use of an array index larger than the array size, mark the checkbox.

Build Mode	To create an executable for use with the Debugger, mark the Develop checkbox. To create an executable for release, mark the Release checkbox.


Object File Compile Options

You may also set compile options for individual files. Highlight a source code file in the Project Tree dialog, then press the Properties button.

The Compile Options dialog appears, showing all the same controls as the Global Options dialog, minus the Build Mode, which may only be specified for the total project. By accessing the Compile Options individually, you may specify, for example, that one object file be optimized for speed, and another for size.


Target File Link Options

You may set stack size and other options in the Link Options dialog.

Highlight the target file in the Project Tree dialog, then press the Properties button. The Link Options dialog appears, with the following options:

Create Map File	To create a map file, which contains information about segment sizes and public functions, mark the checkbox. The map file may be used with third party debuggers.

Pack Segments	To pack the data and program segments in the .EXE file, mark the checkbox.

Stack Size	To specify the stack size in kilobytes, type a number in this field. The default size is (*** ????).


Editing the Redirection File

Clarion utilizes the redirection file to keep track of the working directories for the IDE components. You may edit the redirection file (which is a text file) from within the IDE. By utilizing the redirection file to store these paths, Clarion saves you the trouble of defining  various environment variables in your AUTOEXEC.BAT file.

To edit the redirection file, choose Setup » Edit Redirection File. A Notepad-like editor appears. File types appear on the left; paths on the right.

•	To change the default path for a file type, select the current path by DOUBLECLICKING, then type over it with the new path.

•	To append an additional subdirectory onto the search path for a file type, add a semicolon at the end of the current path, then add the subdirectory.

The file types which the redirection file keeps track of are:

*.RSC	(*** resource files of some type???)

*.OBJ	Compiled object code files.

*.DBD	Debug data files.

*.LIB	Compiled library files.

*.DLL	Dynamic link libraries required by the Clarion IDE.

*.*	Everything else.


Project System Menu Commands

The IDE menu provides several menu commands which affect or access the Project System. This section provides a list of the commands and what they do:

The Project Menu


The Project Menu

The Project Menu allows you to set the current project, plus commands to compile or run it. The menu allows you to do the following:

Set Current Project	Allows you to open and make current a project (*.PRJ) file. The Open File dialog will appear; select a project file from the listbox.

Edit Current Project	Allows you to edit current project components in the Project Tree dialog. Make the changes you wish in the Project Tree dialog.

New Project	Allows you to create a new project. Fill in the Project Title and Main source code file in the New Project File dialog.

Make	Allows you to compile and link the current project. You can also press the Make button on the IDE toolbar.

Run	Allows you to compile and run the current project.

Debug	Allows you to compile and load the current project into the Debugger.

Make Statistics	Allows you to view a statistical profile of the most reacent make. Data on the size of each module size, including code and data size, will appear in the Make Statistics dialog.

Auto make 	To toggle the Project System setting which forces a recompile each time you choose the Run command, choose Project [image] Auto make before run.

File Save 	To toggle the Project System setting which saves the source code file each time you choose the Run command, choose Project [image] File Save before run.

Minimize 	To toggle the Project System setting which minimizes the IDE before displaying the application each time you choose the Run command, choose Project [image] Minimize on Run.

Wait 	To toggle the Project System setting which suspends the IDE until after you terminate the application upon executing it with the Run command, choose Project [image] Wait for termination on run.


Other IDE Commands

The following commands also access the Project System:

Open 	To open a project file (*.PRJ) directly, choose File [image] Open. Change the List Files of Type dropdown list to Project (*.prj). Locate the project file in the directory list, select it and press the OK button, or doubleclick the filename.

Pick	To open a recently opened project from the Pick list, choose File [image] Pick. Locate the project file in the list, select it and press the Select button, or doubleclick the filename.

Load	To open a recently opened project from a Pick list which only includes project files, choose Clarion » Load Project. Locate the project file in the list, select it and press the Select button, or doubleclick the filename.


Calling the Windows API

Accessing Windows API functions from Clarion involves a specialized form of calling external .DLL functions.

The WINDOWS.LIB contains declarations for Windows API functions. See appendix *** for a comprehensive list of API functions supported.

Windows API functions must be prototyped using the MODULE structure, specifying the PASCAL calling procedure. The following serves as an example:

PROGRAM

MAP

MODULE('WINDOWS.LIB')

MessageBox(USHORT,*CSTRING,*CSTRING,USHORT),PASCAL,RAW

END

END

Caption  CSTRING(18)

MessageText     CSTRING(32)

CODE

Caption = 'Title'

MessageText = 'This is the text'

MessageBox(0,MessageText,Caption,30)


Using the Debugger

The Clarion Debugger is a powerful diagnostic tool for finding errors in your applications. You can examine code and data, and exercise complete control over your applications execution.

Preparing Your Projects for Debugging

Starting the Debugger

Launching

Loading the Source File(s)

Overview: The Debugger Windows

Default Windows

Other Windows

Setting Breakpoints

Unconditional Breakpoints

Conditional Breakpoints

Go!

Working with Source Code

Editing Watch Expressions

Editing Variables

Setting Debugger Options

Debugger Setup Options

Additional Debugger Commands


Preparing Your Projects for Debugging

The Project System allows you to set the debug global options in the Global Options dialog. To create a .EXE file to debug:

1.	Create your project file, and make it the current project (the Using the Project System chapter explains how).

2.	Choose Project [image] Edit Current Project to view the Project Tree dialog.

3.	Select the top level of the tree, which holds the name of the project, and press the Properties button.

4.	When the Global Options dialog appears, mark the Full checkbox in the Debug Information group box.

5.	Check the Line Numbers box.

6.	Press the OK button to close the dialog.

7.	Press the Make button on the toolbar to compile and link the application.

The application now includes the information the Debugger needs.

You can also turn on debugging information for a single module in the project. The advantage of this is that it reduces the overhead for the debugger. To do so:

1.	Create your project file, and make it the current project (the Using the Project System chapter explains how).

2.	Choose Project [image] Edit Current Project to view the Project Tree dialog.

3.	Select only the source module you need to debug, and press the Properties button.

4.	When the Compile Options dialog appears, mark the Full checkbox in the Debug Information group box.

5.	Check the Line Numbers box.

6.	Press the OK button to close the dialog.

7.	Press the Make button on the toolbar to compile and link the application.

The includes debug information for that module only.


Starting the Debugger

The Debugger runs as a separate application, but you can start it either inside the IDE, or directly from Windows.


Launching

•	To start the Debugger inside the IDE, either:

1.	Either choose Project [image] Debug or compile and link your application by pressing the Make button.

2.	With the Compile results dialog still open, press the Debug button.

•	To start the Debugger as a normal application.

1.	Switch to Program Manager and open the Clarion group.

2.	DOUBLE-CLICK the Debugger icon.

If you wish to start the Debugger from another program launcher the application file name is CLWDB.EXE.

3.	With the Debugger launched, choose File [image] File to Debug, then choose an .EXE file in the Open File dialog.

Tip:	The Debugger has to be a system hog in order for it to do its job. Any applications in the background will halt processing when the Debugger is active.


Loading the Source File(s)

When you launch the Debugger from the Compile Results dialog, you must confirm the name of the source code files.

•	To load the source files when the Debugger appears:

1.	Select the source code files in the Sources to include in session dialog.

2.	Press the OK button.

The Debugger windows appear.

It the application does not include debug information, the Debugger skips this step and opens a disassembly window (explained below).


Overview: The Debugger Windows

The Debugger consists of a collection of child windows, which track different information about the program for you. These windows are:

•	The code window

•	The watch window

•	The global variables window

•	The active procedures window

•	The disassembly window

•	The registers window

•	The library window

•	The messages window


Default Windows

At first, the Debugger opens four windows:

u	The code window displays the source code document. The title bar shows the document file name. The current line cursor is green. When you select a line other than the current, the cursor is light cyan.

Tip:	If the Debugger opens without listing any source code documents in the Sources to include in this session dialog, the most probable cause is that none of the source code files listed in the Project Tree contained debug information. Check for .DBD files, which contain the debug information.

u	The watch window shows the current value of variables and expressions. Set a watch expression to see how a variable or expression changes as your program executes.

The title bar is Watch Expressions. See the Editing Watch Expressions section (below) to learn the syntax for watch expressions. To add a variable to the watch list:

1.	DOUBLE-CLICK on an empty line in the watch window.

2.	When the Watch Expressions dialog appears, type a variable name (as it appears in the global variables list) and press OK.

3.	Alternatively, press the Browse button, select a variable from the list, then press OK twice.

The expression or variable appears in the watch window, and its current contents appear next to it.

You can also add a variable to the watch window by double-clicking or pressing enter on a variable in the global variables window.

Tip:	To quickly add a variable to the watch list, DOUBLE-CLICK on it in the Global Variables or Active Procedures windows, then press the Copy Variable to Watch button.

u	The global variables window shows you the current value of each component of each variable. For example, for a string variable of eighteen characters, eighteen separate lines show the contents of the each position of the string. The variables window contains tree controls, so that you can expand only the variables you want to examine.

Each variable has a tree control to expand its listing. The top level is the source code module which contains the variable. The next is the variable name. The next level contains the contents by variable position.

u	The Active Procedures window lists the procedure currently executing, which allows you to monitor nested procedure calls. The window appears in tree format. The upper levels represent the the names of procedures and the lower levels represent the variables. double-clicking on an active procedure displays a button window which allows you to display the source or disassembly.

When working with more than one THREAD, the Active Procedures window displays information for the current thread only.


Other Windows

Other debug windows provide other types of information:

u	The Disassembly window is optional for a project with debug information: choose Options [image] Dissembly On to display it.

If you run the Debugger on a program with no debug information, the Disassembly window automatically displays the assembly language instructions. The current instruction is selected.

double-clicking (or pressing enter) on a line in the Disassembly window which contains a jump or call instruction moves the cursor to the target location. esc returns the cursor to the original location.

del inserts an unconditional break point at the cursor. ins removes one. Pressing the space bar displays the Break Point dialog.

u	The Registers window shows the current register values; choose Window [image] Registers to display it.

The Registers window shows the register in the left column, and its value to the right.

u	The Library window displays return values for Clarion library functions; choose Window [image] Library State to display it. These functions represent all the field and other events.

These functions include ACCEPTED, SELECTED, FIELD, FOCUS, FIRST-FIELD, LASTFIELD, ERRORCODE, AND ERRORFILE.

u	The Messages window displays up to the most recent 200 message events generated by or directed to your application; choose Window [image] Messages to display it.

The Debugger adds a separator line (-----) to indicate a breakpoint ocurred.

Every action the user takes--from mouse movement to menu commands--is first processed by Windows. If Windows determines the action is for your application, it passes the information to your application via a message. For example, if the user types the letter A, it sends a WM_KEYDOWN message to your application, with the key code for A as the first message parameter.

Tip:	If you include DDE services in your application, we recommend testing your application with another DDE application and monitoring the DDE messages. For further information, see the Microsoft Windows 3.1 Programmers Reference, Volume 3, available from Microsoft Press.


Setting Breakpoints

Once you arrange the Debugger windows the way you wish, the next step is to set the breakpoints.

Normally, when debugging an application, youll identify a small part of the program which produces incorrect output, or crashes. The Debugging process for this situation will probably require running just that part of the program, and stopping it at one or more points to check its status.

Breakpoints allow you to automatically halt execution at the line of code at which (or near which) you think the problem occurs. Your program runs up to the breakpoint, then halts and turns control back to the Debugger. You can then check the contents of variables and expressions to identify the cause of the problem, and step through from that point on. When in Step mode, the Debugger executes one source code statement, then returns control to the Debugger until you issue the next Step! command.

You can also set conditions on the breakpoint, telling the program to continue executing if the condition is false, or turning control over to the Debugger if true.

When you set a breakpoint, the source code line where the breakpoint occurs appears in magenta in the source window.


Unconditional Breakpoints

An unconditional or sticky breakpoint is placed on a source code line, and stops execution whenever the program encounters that statement:

1.	Open the source code or disassembly window.

2.	Locate the line of code to break on and DOUBLE-CLICK on it.

3.	When the Break point dialog appears, select Always and press the OK button.

When you execute the Go! command, the program will run until it reaches the breakpoint, then stop.

Tip:	When a source code or disassembly window is the active window, press Insert to add an unconditional break point, or Delete to remove it, if placed.


Conditional Breakpoints

To narrow the search for bugs, you can tell the Debugger to break only when a certain condition exists. The condition takes the form of an expression which can include program variables, operators and constants. You can also tell the Debugger to break when it detects a particular message or messages from Windows to the application.

•	To set a conditional breakpoint on a change in a watch expressions value:

1.	Establish a watch expression as described in the Editing Watch Expressions section, below.

2.	Locate the line of code to break on and DOUBLE-CLICK on it.

3.	When the Break point dialog appears, select Watch Expression #0.

4.	Type the number of the watch expression (from the watch expressions window) in the Watch#0 field.

5.	Press the OK button.

When you execute the Go! command, the program will run until it reaches the breakpoint, evaluate the watch expression, then stop if the expression is true, i.e., evaluates to a non-zero value.

For example, if variable X should have a maximum value of 999, but increments to 1000 anyway, causing havoc, you can tell the Debugger to break at 999, then step through the program to see when and how it reaches 1000.

•	To set a breakpoint conditional on a specific Windows message:

1.	Locate a line of code to break on and DOUBLE-CLICK on it.

2.	When the Break point dialog appears, select Windows Message.

3.	Select a Windows message from the Windows Message combo box.

4.	Press the OK button.

For example, you could place a breakpoint in a loop which checks for a WM_RBUTTONDOWN message, which is the message Windows sends when the user clicks the right mouse button in your window. When you run the program, you RIGHT-CLICK inside it, and Windows sends a WM_RBUTTONDOWN message to your application. The breakpoint condition would be true.

•	To set a breakpoint conditional on one of several Windows messages:

1.	Locate the line of code to break at and DOUBLE-CLICK on it.

2.	When the Break point dialog appears, select Message Group.

3.	Select a message group from the list. This can indicate a category of messages, such as mouse or key messages. You can also set up a custom message group (by pressing the Message button) to remember several specific messages, so that the breakpoint will occur only on one of these messages.

4.	Press the OK button.

For example, you could place a breakpoint in a loop which checks for a Key message. When you run the program, when you press a key, Windows sends a message to your application, and the breakpoint condition would be true.

•	To set a breakpoint which breaks when you receive an unexpected message, that is, one that doesnt belong to a group you specify:

1.	Locate the line of code at which you want to establish the breakpoint and DOUBLECLICK it.

2.	When the Break point dialog appears, select Message Group.

3.	Select a message group from the combo box. The breakpoint will occur only when the application receives a message not in this group.

4.	Press the OK button.


Go!

The Go!, GoCursor!, Step!, and ProcStep! commands execute your application while the Debugger monitors it in the background. They allow you to test your application in a controlled environment which helps you identify bugs faster.

Tip:	These commands are all top level menu commands. No pulldown menus appear below them; just place the cursor on the menu command and click, or press ALT plus the underlined letter to execute.

Go!	To run the program from its current state to the next breakpoint, choose Go!

When a source or disassembly window is active, the g key executes the command.

GoCursor!	To run the program from its current state to the selected source or assembler line in the source code or disassembly window, choose GoCursor!

When a source or disassembly window is active, the c key executes the command.

Step!	To advance the program from the currently selected source or assembler line, one line of code at a time, choose Step!

When a source or disassembly window is active, the s key executes the command.

ProcStep!	To advance the program from the currently selected source or assembler line to the next, but to skip through procedure calls without stopping, choose ProcStep!

When a source or disassembly window is active, the p key executes the command.


Working with Source Code

When the source code window is active, you can navigate through the source code document with the Edit menu. The following commands are available:

Find Text	Locate the line which contains the text you type into the Find Text dialog.

Find Next	Locates the next line which contains text you previously searched for with the Find Text command.

Find Procedure	Locates the first source code line for the procedure you pick from the Find Procedure dialog. The applications procedures appear in a combo box inside the dialog.

Goto Line	Advances the cursor to the line number you specify.

Current Line	Advances the cursor to the source code line which contains the next statement to execute.

Find Last Error	Places the cursor on the last non-fatal error.

Break Points	Displays the Breakpoints dialog, which lists the breakpoints youve set for this debug session. The breakpoints appear in the format SourceCodeFile: Procedure: Line Number. Select a breakpoint from the list, then press one of the following buttons: Locate, Delete, Edit, or OK.


Editing Watch Expressions

The Debugger contains an expression editor dialog, which allows you to edit a watch expression. Sometimes you want to take an action depending on the value of an expression that uses variables from your program. For example, you may want to stop the application and look at a variable if its a negative value, or continue on to the next break point if its positive.

To edit a watch expression, select a line in the Watch Expressions dialog and choose Edit [image] Edit. The Edit Expression dialog appears.

Type an expression in the Expression to Evaluate field, then press the OK button. When the Debugger runs the program, it will test the expression upon reaching the breakpoint, and halt if the expression evaluates true.

The Edit Expression dialog also contains a Browse button, to help create your expression faster. Press the Browse button to see a list of the variables local to the procedure youre currently debugging.

You can prefix the variable name with a procedure name and/or a module name. This allows you to name a variable not currently in scope, for example, a variable in another procedure that would not be visible for the current procedure.

•	To specify a procedure and variable, prefix the variable with the procedure name plus a colon(:).

For example, RoyalFlush:King refers to a variable called King in the procedure called RoyalFlush.

•	To specify a module and global variable, prefix the variable with the module name plus a dot (.).

For example, NewDeal.Shuffled refers to a global variable called Shuffled in the module called NewDeal.

•	To specify a local variable in a procedure in another module, combine the prefixes.

For example, Poker.RoyalFlush:King refers to the variable called King in the procedure called RoyalFlush in the module called Poker.

Tip:	The Debugger will guess the right prefix if the variable is unique.

The following list presents the operators and expression syntax for the Edit Expression dialog. The operators are language independent, derived from C/C++, and Modula 2/Pascal operators.

Key	Function

+	add

-	subtract

*	multiply

/ or DIV	divide

% or MOD	modulus (remainder)

|	bitwise OR

&	bitwise AND

<	less than

<=	less than or equal to

>	greater than

>=	greater than or equal to

=	equal

!= or <>	not equal

! or NOT	logical NOT

& or AND	logical AND

| or OR	logical OR

*	indirection (when prefix)

^	indirection (when post-fix)

->	point at member

.	select member (record field)


Editing Variables

Using the Debugger, you can edit the value of a memory variable while the program is suspended, then resume the program to test execution while the variable contains the new variable.

To change the contents of the variable:

1. Select the variable in either the Global Variables or the Active Procedures windows.

2.	Press F2, or choose Edit [image] Edit.

The Edit Variable dialog appears.

3.	Type a new value for the variable and press the OK button.

When you choose Go!, GoCursor!, Step!, or ProcStep!, the program resumes execution with the memory varaible changed to the new variable.


Setting Debugger Options

The Debugger Options menu provides several toggles which can help fine tune the way in which you debug your project.

Soft Mode	Toggles hard and soft mode debugging.

In soft mode, the Debugger and the Debuggee run as separate Windows applications, with equal standing as far as Windows is concerned.

In hard mode, the Debugger loads and runs the Debuggee, which allows for more control over the debugging process.

Clarion Soft Mode	Same as above, but optimized for Clarion applications.

Extended Stack Trace	Debugger shows information about procedures when no debug information is available.

Disassembly On	The Disassembly window shadows the source window, so that when you select a source line, its disassembly appears.

Assembly Single Step	Toggles step mode for assembler breakpoints. When execution reaches an assember breakpoint, step mode is set on. When execution reaches a source breakpoint, it turns off.

Control Panel	Displays a toolbox window with buttons corresponding to the four Go! commands. The next time the Debuggee is suspended, the control panel will receive focus.

When debugging in hard mode, when you switch the active window to the main Debugger window, you cannot access the control panel.

Setup	Opens the Setup dialog. See below.


Debugger Setup Options

Access the Debugger Setup dialog via the Options [image] Setup command. The dialog provides the following options.

Ignore .DLL Files	Instructs the Debugger to ignore debug information in .DLL files. This reduces the startup time for the Debugger.

Disable Kernel Msgs	If you are running the Debug version of Windows (available in the Microsoft Windows 3.1 SDK), the Debugger will automatically trap error messages posted by the kernel (one of the three main dynamic link libraries utilized by Windows). You can locate such errors with the Find Last Error command.

Report Missing Source	The Debugger automatically prompts for source code files it cannot locate.

Iconize When Inactive	Automatically iconizes the Debugger when the Debugee is active.

Debugger On Top	The Debugger appears on top an any other open windows when active; relevant for hard mode debugging only.

Tip:	When working in Hard mode, type D to bring the Debugger to the top.

Disassembly Opcodes	The disassembly window contains only op codes, eliminating the space taken up by binary codes.

Smart Single Stepping	When enabled, single stepping on a line with a procedure call will load the debug information for the target procedure, if available.

No Horizontal Scroll	Hides the horizontal Debugger scroll bars.

Global Find Text	When disabled, each source window remembers its own search text string. When enabled, the default search text will be the same as the last search, regardless of the window.

Max Source Windows	Self explanatory.

Max Disassembly	Self explanatory.


Additional Debugger Commands

In addition to the normal debugging window and setup options, you can activate special modes and options from these menu commands:

Redirection	To utilize a custom redirection file for use with the Debugger, choose File [image] Load Redirection. The Redirection file follows the same format as the IDE redirection file, and helps you locate files required by the Debugger, such as *.DBD, and *.CLW.

Active DLLs	To add a related dynamic link library (*.DLL) to the debug session, choose File [image] Debug Active DLL. Choose a file from the Active Module dialog. This option is available for hard mode debugging only.

Sleep	To set the Debugger into sleep mode, in which it waits for a protection violation (GPF), ctrl-alt-sys req, or an INT3, choose File [image] Sleeper Mode. This option is available for hard mode debugging only.

Restart	To continue a previously terminated Debug session, choose File [image] Restart. The Debugger will restart with previous watch expressions and break points.

Position	To size the Debuggees window to the maximum desktop area not taken up by the Debugger, choose Window [image] Position Debuggee. This has no effect when the Debugger is maximized.

Groups	To set up your own custom message groups to watch, choose Options [image] Custom Groups. Type a name for the group, and choose the Windows messages from the listbox in the Selective Break Point Groups dialog.

Colors	To customize the Debugger selection colors, choose Options [image] Custom Colors. Select the colors for the Current Line, General Cursor, Inactive Code and Break Points in the Color dialog.


Windows Design

This section provides an introduction to:

•	The design principles which Microsoft suggests for designing the user interface of Windows-based applications.

•	Event driven programming and how it should influence your applications design process.

•	The types of windows, controls, cursors, and other objects common to Windows applications.

•	The standard menus and menu commands recommended for Windows applications.

•	The use of color and how it relates to the user.

Overview

Design Principles

User Control

Event Driven Programming

Windows and Window Elements

Application Window

Dialog Boxes

Buttons

Check Boxes

Radio Buttons

List Boxes

Combo Boxes

Drop-Down Boxes

Text Boxes

Spin Boxes

Static Text

Group Boxes

Control Labels

Cursors

Menus

File Menu

Edit Menu

Help Menu

View MenuView_Menu

Window Menu

Accelerator Keys

Color


Overview: Windows Design

If you make your program look and act like other Windows programs, your users will learn it more quickly, and feel more confident using it to accomplish the tasks you designed it to do. The GUI environment demands that you address your users on their terms. The program design must reflect that the user is in control, both visually and in the underlying structure of program flow.

Microsoft makes specific recommendations on what a Windows application should look like, and how the controls in a window should look and act. There is even a set of standard menu and command recommendations.

This chapter also discusses the use of color in your application.


Design Principles

Apple, in its Human Interface Guidelines, IBM, in its Common User Access: Advanced Interface Design Guide, and Microsoft, in The Windows Interface: an Application Design Guide have all published detailed design principles for software designers working in popular GUI environments. Creating a standard for program design offers these advantages:

•	Given consistency between applications, users learn new applications more quickly and easily, minimizing the need for training.

•	Consistency between applications increases the level of confidence in the user, resulting in increased productivity.

There are two especially important Windows design principles for the Clarion programmer to keep in mind when designing the user interface. The first is user control--providing a real-world based metaphor for the programs organization, and maintaining a consistent look and feel for all parts of the program, builds the users confidence. The second is to remember that Windows programming is event driven--the user decides the next action. The programmers responsibility is to provide a visual list of options the user can act upon.


User Control

Your users may not have years of experience using a wide variety of programs. Providing a metaphor from the real world will help provide a setting or group of expectations to apply to your program. A word processing program, for example, utilizes a paper metaphor--the document is like a piece of paper to write on, erase characters from, etc. Many database programs use rolodex card metaphors. By establishing a relation to the real world, you increase the comfort level of your users, and actively engage them in the work of the program.

Visual consistency is very important. As much as possible, an application should utilize a single way to implement actions. A user learning a new procedure in your program builds upon prior experience with other procedures in the same program. Creating a standard look for your dialog boxes, and making screens for similar tasks look like one another, also reduces the time it takes you to design the different screens your program requires.

Directness makes a user feel they are in charge. Moving a document from one folder to another, or moving one icon to another, such as the trash icon can seem to a user to be a real action. Clarion provides drag-and-drop server support, which allows you to create, for example, an icon with a picture of a person on it, representing an employee record. A user might drag the icon to another representing money, to open a dialog box displaying the employeess payroll records.

Simplicity is usually the best design. Cluttering the screen with too many windows, buttons, icons, lists and other objects can confuse the user. Dialog boxes especially, usually must fit in a small space, so their messages must be simple.

Let the user know whats going on--provide feedback. When the user chooses a command or begins an operation, visual feedback should confirm it is being carried out. The confirmation may be graphical, such as a cursor change, or simply a message on the status bar. If there will be a delay while the program finishes another operation, inform the user, and advise, if possible, how long it will take.

Your application should use plain language. When designing an application for a corporate environment, technical terms are often essential. Watch out for the times when plain English is better. Of special importance to the Clarion programmer, who may be new to Windows programming--beware of Window-isms. Its very easy to create two buttons marked OK and Cancel. Yet Yes and No are far better button labels when the question is: Do you wish to delete this record!


Event Driven Programming

Related to user control issues, and the most important paradigm shift for new Windows programmers, is that you must design Windows programs to be event-driven. In a multi-tasking environment, a program simply cannot direct the sequence of program action--the user directs it.

The underlying structure of Windows is such that the operating system informs the program via messages just what it is the user wants the program to do. This is the opposite of DOS programming.

Windows messages inform a program when a menu is selected, when a window is selected, when the user wants to shut down the operating system--the Windows 3.1 Software Development Kit documentation devotes a book of *** pages just to listing and explaining the different messages. Most programming languages require elaborate message handling procedures to branch program flow upon receiving different types of Windows messages.

Clarion automatically handles the housekeeping associated with message handling. The ACCEPT loop frees the Clarion programmer from worrying about system messages. Yet you still must consider the event-driven model when designing your program.

A Windows program must constantly look for input--in the form of data entry in an edit box, for example. In a window with several fields, the user can tab or click with the mouse to make any of them active. You must plan your input dialogs accordingly.

Additionally, your users will expect a complete set of user interface elements, including menus, multiple windows and graphical controls, all available simultaneously.

You may create an application which allows the user to open two windows, with markedly different functions. Clarion will automatically handle events generated within each window. Yet what about the menu commands, or the tool bar? You should plan these so that the commands will act on any active window. Clarion helps you do this automatically when creating an application using Multiple Document Interface. There may be times, however, when you may need to manually disable and re-enable menu commands.

Finally, the event-driven model should influence the windows you design for your application. Plan on utilizing your main application window as the backbone for your program. Generate another window--dialog box, MDI window, etc.--only upon some user action in the main window.


Windows and Window Elements

This section describes common Windows elements, including window types and controls. Choosing the right element for the right procedure will help your users get the most out of your program.

There are three types of windows: application, document and dialog boxes.


Application Window

The application window should usually contain all the other windows your program may generate. If you open a browse window, it should appear inside the application window. If a user re-sizes an application window to a smaller size, you may allow your other windows to appear partially outside it. Additionally, you may allow users to move moveable dialog boxes outside the application window.

Application windows should always contain a title bar that contains the name of your application. Microsoft recommends that application windows also contain sizable frames, a Control-menu box, and Minimize and Restore buttons. In Clarion, you may add these using the Application Properties dialog.


MDI

Clarion enables the Multiple Document Interface (MDI). This manages multiple documents or multiple views of the same document, each in a separate window which appears inside the main application window. If the user re-sizes the application window to make it smaller than the document window, the document window will appear clipped.

In database programming, the document file is often the database. Use document windows to display browse windows, views, and queries. Since Clarion provides the tools to do virtually anything in a document window, be conservative in your use of document windows. Do use a document window to display the contents of a text file, for example, as a graphics viewer, or to view a report. Dont use a document window for procedures which belong in a dialog box, such as record entry.

Microsoft recommends each document window contain a title bar with the name of the document, a Control-menu box, and a Maximize button. Optionally include a minimize button.


Dialog Boxes

Use a dialog box when you require additional information from a user to complete a task. Adding a record to the database is an example of a task--data entry for the new record would be the process of getting additional information.

The Windows design guidelines for dialog boxes are very flexible. They may be movable, or maintain a fixed position. They may have a single size, or a More >> button to make it unfold and offer additional options. They may be modal or modeless. They may present a brief message with only an OK option, or provide complex choices, controls, and entry options. Since the guidelines allow for wide variation, this section will only present a few pointers which will help you design dialogs that are easier to use.

•	Using either the dialog box caption bar or static text in the box, briefly explain the function of the dialog, or indicate which command caused it to appear.

•	Set as many controls to the default setting as possible, so that you require the least amount of entry on the part of the user.

•	Place the most important information at the upper left, the least important at the lower right. Your users read from left to right, top to bottom--this is the natural way in which they expect to enter information.

•	Set the focus to the first text edit (entry) box. This allows the user to simply type a word or words at the keyboard without having to position the cursor.

•	Place dialog box default buttons--the most likely user choice--on the right. This gives the user to read the choices on the left before presenting the decision.

•	When presenting a brief message, take advantage of the default icons available using the MESSAGE function. The Stop, Information, and Question icons are familiar to users from other applications.


Buttons

A button initiates an action. When the user presses a button, the button appears to be depressed. When a button action is unavailable, the button label should be dimmed.

Clarion allows you to use either text or graphical labels (picture buttons). Be cautious in the use of picture buttons. Stick to standard bitmaps (such as the icons many bestselling applications use for File [image] Open, File [image] Save, etc). Too many picture buttons in a window can be confusing to the user. Some reviewers have accused programs of iconitis--having so many graphical buttons on the screen at once that its impossible for users to remember what button executes which action.

Buttons can perform several types of actions.

•	A button may initiate an action.

•	A button may close the active dialog box, then open another, related dialog.

•	A button mayopen another dialog on top of the current one, without closing the current one.

•	A button may unfold or resize the dialog window to include more options (for example, More >>). With Clarion, you may easily create this type of dialog box by hiding the controls in the lower part of the window, and ...

***	will fill in at a later date

Always designate one button as the default. When the user presses ENTER, it will initiate the default button action. Microsoft also suggests that you not assign a mnemonic--for example, &OK, which appears as OK--to a default button.


Check Boxes

Check boxes control true/false, yes/no, on/off or logical variables. The user toggles the state by clicking on the box, or pressing the SPACEBAR. If a checkbox option is unavailable, the label should be dimmed.

Tip:	To create a 3D push-button, set the Icon option in the Check Box Properties dialog box.


Radio Buttons

Radio buttons, also referred to as option buttons, present the user with a single choice in a mutually exclusive set of choices. The user may select only one at a time. If space is at a premium, and the number of choices is greater than four, consider a dropdown list box, which takes up less space.

The name radio buttons came about because they act like old-fashioned car radio buttons--push one, and the previous selection pops out. Windows radio buttons usually look like circles or diamonds. Clarion provides a new functionality which allows you to make the radio buttons look like real car radio buttons. You may give the radio buttons a 3D look; even resize the buttons.

Tip:	To create 3D radio buttons, select a radio button, open the Radio Button Properties dialog, and activate the Icon property. You should add a static text control next to the button, as the label will disappear.


List Boxes

List boxes display choices for the user. If a choice is unavailable, in general you should drop it from the list. If the choice is important enough that the user should know it is unavailable, Microsoft recommends it appear in the list box as a dimmed selection.

*** It is not expected that Clarion will support dimming a single selection in a list box. You can easily dim the entire listbox.

Always allow your list boxes enough room. Try to allow vertical space for three to eight choices; horizontal space for the average length of selection text plus several extra spaces.

Clarion provides great flexibility in creating list boxes (refer to chapter *** for details on formatting a custom list box). Remember that a list box can present a user with a great deal of information--keep it simple!


Combo Boxes

A combo box is a combination of text box and list box. They are appropriate where the data lends itself to possible responses, but allows the user to type in a response not in the list.

The design guidelines for list boxes apply to combo boxes.


Drop-Down Boxes

Drop-down single-selection lists perform the same function as list boxes, but take up less space. When closed, the drop-down is only tall enough to show one selection. Opened, the list will show three to eight items, like a standard list box.

Novice users often have much more difficulty selecting an item from a drop-down than from a normal list box. Whenever space permits, use radio buttons (for four choices or less) or normal list boxes.


Text Boxes

Text boxes allow the user to type in information. They may be single line or multi-line. Multi-line edit boxes should usually provide a vertical scroll bar.

The standard Windows accelerator keys for copy, paste, etc., are active by default. This is useful, because it enables the user to copy, for example, a paragraph from another application, then paste it directly into a multi-line text box in your application. For this reason, we recommend you do not reassign the default windows editing shortcut keys--such as CTRL+C for copying--to alternate commands in your Clarion application.

Fixed-length, auto-exit text boxes (ENTRY controls with the IMM attribute) may speed up data entry. As soon as the user fills the text box (by typing the maximum allowable characters), the focus moves to the next control. Microsoft recommends applications use this type of text box sparingly, as the shift of focus may be disconcerting if it catches a user by surprise. We recommend using this type of text box when there are many fields to enter in a dialog. For dialogs with only a few fields, the programmer should try to anticipate what the end user will expect, and choose accordingly.

Clarion allows you to select the font for text boxes. We suggest using the default system font (which is a helvetica font, 10 pts., bold style). Microsoft specifically chose this font for menus and other system items because it is especially easy to read on a monitor.


Spin Boxes

Spin boxes are specialized text boxes with a pair of arrows (spin buttons) attached to the right of the text box. Spin boxes accept a limited set of values, which the user may type in, or by using the arrows, increase or decrease the value by a specified unit. Spin boxes can provide an alternative to drop-down lists when the the set of values is limited in quantity and fits into a natural progression; for example, Spring, Summer, Fall, Winter.

Besides increase or decrease controls for simple numbers or choices, you may use spin boxes to manipulate values that consist of several components. You may display time in hours, minutes and seconds, for example. Be sure to visually separate each component with a relevant separator character, such as a colon.


Static Text

Static text should present read-only information, such as directions for entering data in the other controls in the dialog box. You should also use static text to label controls not automatically labelled by the Window Formatter, such as a text box.

Clarion allows you to select the font for static text. We suggest using the default system font (which is a helvetica font, 10 pts., bold style). Microsoft specifically chose this font for menus and other system items because it is especially easy to read on a monitor. You should certainly feel free to make the text bigger, as in creating a title for a dialog box form.

We also advise you to resist the temptation to use odd or too many different colors for static text. You never can tell what the default window background will be.


Group Boxes

Group boxes provide a visual grouping for related controls. They consist of a rectangular frame with a label at the upper left.

A group box can guide the user directly to the controls that are most important to the task at hand. If your application requires a dialog with more than ten controls or fields, we highly recommend taking a moment to consider whether some of the controls fit into logical groups.

Note:	The Clarion Window Formatter automatically creates a group box when you place a radio button in a window, if there isnt one there already. This represents the OPTION structure. The Option Properties dialog will prompt for the caption text for the group box.


Control Labels

The Window Formatter automatically supplies labels for many, but not all controls. You may supply labels for the other controls using static text. Not only will this identify the control for the user, but it also will allow keyboard users to quickly direct the focus to the control.

When the user keys in the mnemonic (such as the S in Daily Sales), Windows automatically directs the focus to the next control after the static text label. Thus, you may place Daily &Sales to the left of a drop-down box. When the user presses ALT+S, the combo box will receive the focus. The keyboard user will merely have to press the DOWN ARROW key to view the choices in the list.

Microsoft suggests the following guidelines for control label text:

•	Capitalize the first letter of each word, except for articles (e.g., a, an, the), coordinate conjunctions (e.g., and, or, for), prepositions (e.g., by, with) or the word to in infinitives.

•	Try to use the first letter of the first word for the mnemonic. Since the mnemonics need to be unique, however, this isnt always possible. Alternately, use another letter if it allows a stronger mnemonic link: such as the x in Exit. If the first word in the control label is less important than another, use the other (e.g., by Ascending Order).

•	Choose consonants over vowels: they are more distinctive and more easily remembered.

Microsoft also suggests the following positioning for control labels for the following controls:

•	Command buttons: inside the button.

•	Check boxes, radio buttons: to the right of the control.

•	Text boxes, spin boxes, lists, combo boxes: above or to the left of the control. Place a colon after the last word of the label. Left align the label with the section of the dialog box in which it appears.


Cursors

In a graphical environment such as Windows, the mouse cursor, or screen pointer, is the means by which the user shows the application what to do next. For example, the I-bar, or insertion point, may tell a word processing application where the next characters typed by the user should appear. This is a key part of the event driven programming referred to earlier in this chapter.

Though Microsoft has not set specific guidelines for the use of each system cursor, the following uses have evolved into de facto standards across GUI platforms:

(pic)	Arrow: selects controls and menu commands.

(pic)	I-beam: selects and inserts text.

(pic)	Crosshairs: draws and manipulates graphics.

(pic)	Plus sign: selects fields in an array.

(pic)	Hourglass: shows that a lengthy operation is in progress.

Tip:	Clarion offers an easy means to change the cursor, via the Cursor property available in the Window Formatter. This allows you to automatically load the appropriate cursor when the user moves the mouse over the applicable window or control.


Menus

Menus display the range of commands available for the user to execute. Windows users are accustomed to standard menus and commands which appear in many different applications. If you utilize these same menus, new users may learn your application more easily, and the sense of familiarity will increase all users confidence and productivity levels.

When designing additional, custom menus and commands, bear in mind that the model for GUI design is the Noun-Verb. principle. Apple fancifully refers to this as Hey you--do this!

In the Noun-Verb model, the user points to something--for example, an on screen object such as text. This is the noun. The model assumes that the next command action the user chooses will tell the application what to do to the noun. The action is the verb. If you word your menus and commands in a way that the menu - command is a short do this sentence--such as Insert [image] Record, View [image] •Transaction, List [image] Activity, or Select [image] Current Group, your menus will gain added clarity.

This guideline should not severely limit you. There are times when it is most appropriate to use a single menu item to initiate complicated instructions, such as bringing up a dialog box with many different preferences and options for the user to set. When doing so, add an ellipsis (...) following the last word of the menu command.

The following discusses the standard menu implementations recommended by Microsoft:


File Menu

Many database applications do not naturally lend themselves toward allowing the user to open and close external document files. In the simplest case, a database or databases open automatically with the application, and user editing is limited to editing individual records. Clarion programmers may wish to limit commands on the file menu to those that affect the global operation of the application--Printer Setup and Exit, in the most extreme case. At the very minimum, your Clarion applications should have a File [image] Exit command: this is how users expect a Windows application to allow them to quit the program.

New or New...	Creates a new file with a default name such as Untitled. This is sometimes a problematical menu item when creating database applications. Unless your application allows the user to create a new database, or creates separate editable external files (such as text files) Clarion programmers may wish to drop this command.

Open	Displays the File Open dialog, from the Windows 3.1 common dialog library. (Clarion programmers may easily call this using the FILEDIALOG procedure).  Allows the user to open external files.

Save	Saves the active document. For a new file, call the Save As dialog.

Save As	Displays the Save As dialog, from the Windows 3.1 common dialog library. (Clarion programmers may easily call this using the FILEDIALOG procedure).

Print or Print...	Prints the active document, or leads to a dialog allowing the user to set print options. The Print command can be an interesting one in a database application. Many times, a database application allows the user only to print pre-formatted reports. Other docu-centric Windows applications may simply go ahead and print the current document in its entirety--but a database application can hardly be expected to print a 30,000 record database as the default print preference.

One solution some popular applications utilize is to drop the print command entirely and provide a separate Report menu. This is a good solution for an application with a limited number of reports. Alternatively, an application with a limited number of reports might also utilize a cascading menu, attached to the File [image] Print command.

For an application with a large number of pre-formatted reports, one solution might be to present a list box in a dialog window when the user selects the File [image] Print command.

Print Setup	Displays the Printer Setup dialog, from the Windows 3.1 common dialog library. (Clarion programmers may easily call this using the PRINTERDIALOG procedure).

This dialog allows the user to change the active printer and/or specify settings for the selected printer.

Exit	Closes all application windows and terminates the application. If dont have a File menu in your application, place your Exit command on the leftmost application menu, as the last command on the menu.


Edit Menu

The Edit menu usually provides commands for reversing the users last action, plus the clipboard editing commands: cut, copy and paste.

Undo	The Undo command should reverse the users last action. It must always be the first command on the Edit menu, if your application supports undo.

Clearly, database programs present special problems for Undo. In general, Windows applications disable the Undo command after a file operation, such as when a File [image] Save command saves an edited document to disk. A database application may easily present a situation in which it writes data to disk every few seconds when, for example, a user enters a group of new records.

Cut	Transfers a selected object to the clipboard and deletes it from the field.

Copy	Places a copy of a selected object in the clipboard.

Paste	Places a copy of an object previously placed in the clipboard into the current field.

Clarion automatically enables clipboard support for Cut, Copy and Paste when in an edit box. The default accelerator keys for these actions are CTRL+X, CTRL+C and CTRL+V respectively.


Help Menu

The Help menu provides the user with access to the Windows Help system. It should always be the last menu on the right. The Help menu usually contains the following commands:

Contents	Loads the Windows Help system, then opens the external Help file to the main contents page.

Search for Help on	This loads the external Help file, then automatically opens the Search dialog. This allows the user to type in a word; if the word appears as a topic title, the Help system jumps to the title.

How to Use Help	This opens the Windows Help system, and displays the instructions for using it. The file WINHELP.HLP, which Windows 3.1 automatically installs, contains the instructions.


View Menu

Microsoft defines the View menu as optional, and states that it includes commands for changing how the program presents the data to the user, without changing any of the data. As such, it presents a natural means for a database application to allow different browse options on a single database.

The View menu may also present options for displaying various interface elements such as toolbars, status bars, and other special controls that are part of the application window.

There are no specific command text suggestions for the View menu.


Window Menu

This is an optional menu. If you choose to support the Multiple Document Interface (MDI) in your application, the Window menu allows the user to manipulate entire child windows.

The commands for this menu are flexible. Common commands include:

Tile	Arranges child windows end-to-end, so that all are visible.

Cascade	Arranges child windows in an overlapping fashion, so that the title bar of each is visible.

The Window menu may also contain a numbered list of up to nine open child windows. A number should precede each child window name. When the user chooses a window from the list, the window should receive the focus.


Accelerator Keys

A number of commands have gained standard accelerator (or alert, or hot) keys. When creating your application, should you utilize any of the following commands, we recommend you use the following keys:

Command	Accelerator

File [image] New	CTRL+N

File [image] Open	CTRL+o

File [image] Save	CTRL+s, or SHIFT+F12

File [image] Exit	ALT+F4

Edit [image] Undo	CTRL+z

Edit [image] Cut	CTRL+x

Edit [image] Copy	CTRL+c

Edit [image] Paste	CTRL+v


Color

Color will greatly affect how your user works with your application. Microsoft does not publish standard guidelines on color usage--yet. When designing your application, the following guidelines may help you:

•	Windows allows users to select default colors for window text and background. Its best to accept these default colors for the parts of the program which require the most data entry: the user has expressed a preference, so you should respect it!

•	Without forgetting the first point, you may choose to accentuate windows and screen elements by using color. Color can set off specific areas in a window--it can be more effective than a group box.

•	Use color to discriminate between different parts of your program. For example, you may associate one window background color for dialog boxes related to accounts receivable data entry, and another for payables.

•	Use color to visually relate similar parts of the program. For example, you may associate one window background color with phone number data.

•	Use standard cultural associations for special alerts. In western culture, the most meaningful colors are probably the ones on the traffic lights: red, yellow and green. You may use red to signal a halt in a procedure. You may use yellow to signal a warning. Green, of course, means go, all clear.

•	When adding color to text elements, remember that most colors look best against a neutral gray background. If you dont use gray, be sure there is a high contrast between the text and the background color. In dim lighting, color tends to wash out.

•	Bear in mind that 8% of males in Europe and America have some degree of colorblindness. The most common type reduces the ability to distinguish red and green from gray. In a less common type, the user cannot distinguish between yellow, blue and gray.

•	Remember that on monochrome LCD screens, light blue is very hard to distinguish from gray and white.


Appendix B:Setting List Properties
Setting List Properties

Setting Listbox Item Properties

Setting Listbox Column Properties

The List Box Formatter will change drastically before the final release of Clarion for Windows. This appendix documents the Formatter in its current state.

The List Box Properties dialog contains attributes which place a scrolling list of data items on the window or toolbar at the position and size specified by its AT attribute.

The From field, (the FROM attribute), specifies the origin of the data items displayed in the list.  This origin will be from a QUEUE, QUEUE field, or STRING which the FROM attribute specifies.

1.	In the From field, type in the origin of the display data.

The Use field, (the USE attribute), requires a field equate label to reference the control in executable code, or the label of the variable that receives the value selected by the user.

2.	In the Use field, type in either a field equate label or a variable.

The Drop field, (the DROP attribute), specifies a drop-down list box and the number of elements the drop-down portion contains.  A LIST with the DROP attribute displays only the currently selected data item on screen until the control has focus and the user presses the down arrow key, or clicks on the icon to the right of the displayed data item.  When either of these occurs, the selection list appears (drops down) to allow the user to select an item.

3.	In the Drop field, specify the number of elements contained in the drop list box.

Pressing the Format button displays the Listbox Format Editor dialog.  The Listbox Format Editor allows you to specify the display format of the data (the FORMAT attribute) in the LIST or COMBO control.

4.	Press the Format button.

The Scroll field specifies the control scrolls with the Listbox.

The Horizontal scroll bar (HSCROLL) is automatically added to the listbox when any portion of the data item lies horizontally outside the visible area.

The Vertical scroll bar (VSCROLL) is automatically added to the listbox when any portion of the data items lies outside the visible area.

If both the Horizontal and the Vertical scroll bars are checked (HVSCROLL), then both the horizontal and vertical scroll bars are automatically added to the listbox when any portion of the data items lies outside the visible area.

5.	Check the Scroll Bars that you want.

6.	Press the More button.

The Justification field lists five choices: Default, Left Justified, Right Justified, Centered, and Decimal.

Default	specifies as-is display.

Left Justified	(the LEFT attribute) specifies that the prompt is left justified within the area specified by the AT attribute.

Right Justified	(the RIGHT attribute) specifies that the prompt is right justified within the area specified by the AT attribute.

Centered	(the CENTER attribute) specifies that the prompt is centered within the area specified by the AT attribute.

Decimal	(the DECIMAL attribute) specifies that the prompt is aligned on the decimal point within the area specified by the AT attribute.

7.	In the Justification field, choose the justification that you want.

The Offset is the parameter of the Justification (I.E. RIGHT (Offset), LEFT (Offset), CENTER (Offset), or DECIMAL (Offset)).  It specifies Justification positioning, such as Indent or Decimal positioning.

8.	In the Offset field, type in your Offset value.

The Cursor (CURSOR) attribute specifies a mouse cursor to be displayed when the mouse is positioned over the control (or any control within the group).  If omitted, the Windows cursor attribute is used, or else the Windows default cursor is used.  By pressing the Drop List button, the different types of cursors available to you are displayed.

9.	Highlight the Cursor (the CURSOR attribute) that you want.

The Help ID field, (the HLP attribute), specifies a string constant containing the key used to access the Help system.  This can be either a Help keyword or a context string.  A Help keyword is a keyword or phrase that is displayed in the Help Search dialog.  When the user presses f1, if only one topic in the Help file specifies this keyword, the Help file is opened at that topic; if more than one topic specifies the keyword, the search dialog is opened for the user.

A context string is identified by a leading tilde (~) in the Help ID, followed by a unique identifier (no spaces allowed) associated with exactly one Help topic.  If the tilde is missing, the Help ID is assumed to be a Help keyword.  When the user presses f1, the Help file is opened at the specific topic associated with that context string.

10.	In the Help ID (HLP) field, type in the string constant.

The Message field, (the MSG attribute), specifies a string constant containing the default text to display in the status bar when any control in the group has focus.

11.	In the Message (MSG) field, type in the text to display in the status bar.

The MARK attribute enables multiple items selection from a LIST control.  When an item in the LIST is selected, the appropriate flag element is set to true (1).  Each marked entry is highlighted in the LIST.  Changing the value of an element of the flag also changes the screen display for the related LIST entry.  If the MARK attribute is specified on the LIST, the IMM attribute may not be.

12.	In the Mark field, type in the items to be selected.

The Columns (COLS) attribute of the Listbox allows you to specify display columns within the Listbox.  It specifies the size of the highlight bar that highlights each column within the Listbox.  It also specifies a variable which receives the highlighted column number when ACCEPT completes the Listbox, and the number of blank spaces to automatically place between each display column.

Without the COLS attribute, the highlight bar covers the entire row of the Listbox entry.  With COLS, only a portion of each Listbox entry is highlighted at one time.

The display columns are formed from the LIST FROM attribute.  The FROM field is split into columns of the size specified by the first parameter of COLS.  This first parameter uses a string containing ASCII codes which set the size of each column.

13.	In the Column field, type in the number of display columns that you want.

The VCR attribute places Video Cassette Recorder style buttons on a LIST control.  These buttons affect the scrolling characteristics of the data displayed in the LIST.  There are six buttons displayed as the VCR:

|<	Top of List

<<	Page Up

<	Entry Up

>	Entry Down

>>	Page Down

>|	Bottom of List

On a LIST controls VCR field, there also appears a button with a question mark (?) in the middle of the other buttons.  This is the locator button that gives focus to the control specified by the field parameter.  When the user enters data and then presses tab on the locator field, the LIST scrolls to its closest matching entry.

14.	Check the VCR field and type in a field equate label that specifies the ENTRY control to use as a locator for the LIST.

The Immediate field (the IMM attribute) specifies immediate generation of an event each time the user presses any keystroke on a LIST control, usually requiring the QUEUE to be refilled.  On a BUTTON control, the IMM attribute indicates the button generates an event when the left mouse button is pressed down on the control, instead of on its release.  The event is continuously generated as long as the user keeps the mouse button pressed.

15.	Check the Immediate field.

By pressing the Font button, you gain access to the Select Font dialog, which contains attributes specifying the display font for the control and the default for all the controls in the group.

16.	Press the Font button and select your Font (FONT) attributes.

Pressing the Key button will display the Choose Key window, which contains attributes specifying an integer constant or keycode equate that immediately gives focus to the first control in the group.

17.	Press the Key button and select your Key (KEY) attributes.

Pressing the Alert key displays the Select Alert Keys dialog, which allows you to specify a hot key active while the control has focus.  When the user presses an Alert (the ALRT attribute) hot key for a control, a field-accepted event is generated.

18.	Press the Alert key and select your Alert (ALRT) key attributes.

19.	Press the OK button.

Your List Properties dialog is now complete.


Setting Listbox Item Properties

Pressing the Format button on the List Properties dialog displays the Listbox Format Editor dialog.  The Listbox Format Editor allows you to specify the display format of the data (the FORMAT attribute) in the LIST or COMBO control.

1.	Press the Format button.

Pressing the Properties button on the Listbox Format Editor dialog, allows you access to the Listbox Item Properties window.

2.	Press the Properties button.

The Header string enclosed in tildes, followed by optional justification and/or indent, displays the header at the top of the list.  The header uses the same justification and indent as the field, if not specifically overridden.

3.	In the Text field, type in your text.

The Justification field requires one component that specifies Left, Right, Center, or Decimal justification.

4.	In the Justification field, press the Drop List box and highlight your choice.

The Indent field contains an optional integer, enclosed in parentheses, that specifies an indent from the justification.  This is measured in dialog units and may be negative.  With Left (L) justification, indent defines a left margin; with Right (R) or Decimal (D), it defines a right margin; and with Center (C), it defines an indent from the center of the field.

5.	In the Indent field, type in the indent value.

The Width field requires an integer defining the width of the field in dialog units unless overridden by the THOUS, MM, or POINTS attribute.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the window.  This measurement is based on the font specified in the FONT attribute of the window, or the system default font specified by Windows.

6.	In the Width field, type in an integer defining the width of the field.

The Columns (COLS) attribute of the Listbox allows you to specify display columns within the Listbox.  It specifies the size of the highlight bar that highlights each column within the Listbox.  It also specifies a variable which receives the highlighted column number when ACCEPT completes the Listbox, and the number of blank spaces to automatically place between each display column.

Without the COLS attribute, the highlight bar covers the entire row of the Listbox entry.  With COLS, only a portion of each Listbox entry is highlighted at one time.

The display columns are formed from the LIST FROM attribute.  The FROM field is split into columns of the size specified by the first parameter of COLS.  This first parameter uses a string containing ASCII codes which set the size of each column.

7.	In the Column field, type in the number of display columns that you want.

The Picture token formats the field for display.  The trailing @ is required to define the end of the picture token, so that picture tokens like  @N12@Kr@ may be used in the format string without creating ambiguity.  If the trailing @ is followed by an E, then the field can be directly edited in the listbox, and the appropriate QUEUE entry is automatically updated with the edited value.

8.	In the Picture field, type in your picture token.

9.	In the Justification field, press the Drop List button and highlight your choice.

10.	In the Indent field, type in the indent value.

Notice that in the Flags box, there are five choices available to you: Underline, Right Border, New Line, Edit in-place, and Selector.

Underline	Uses an underscore to underline the field.

Right Border	Places a vertical line to the right of the field.

New Line	Adds a new line to the list box column.

Edit in-place	Edits the material in-place.

Selector 	(Locator) gives focus to the control specified by the field parameter.  A question mark defines the locator field for a Combo listbox with a selector field.  When the user enters data and then presses tab on the locator field, the list scrolls to its closest matching entry.  For a drop-down multi-column listbox, this is the value displayed in the current selection box.

11.	Check the Flags that you want.

The Format String field contains the information for single or multi-column formatting of the data.  It contains field-specifiers which map to the fields of the QUEUE and/or region-specifiers that group together one or more fields to be displayed as a unit.  Only the fields in the QUEUE for which there are field-specifiers are included in the display.  This means that if there are two fields specified in the format string and three fields in the QUEUE, only the two specified in the format string are displayed in the List or Combo control.

12.	Press the OK button.

You have completed your Listbox Item Properties window.


Setting Listbox Column Properties

Pressing the Column button on the Listbox Format Editor dialog allows you access to the Listbox Column Properties dialog.

1.	Press the Column button.

The Columns (COLS) attribute of the Listbox allows you to specify display columns within the Listbox.  It specifies the size of the highlight bar that highlights each column within the Listbox.  It also specifies a variable which receives the highlighted column number when ACCEPT completes the Listbox, and the number of blank spaces to automatically place between each display column.

Without the COLS attribute, the highlight bar covers the entire row of the Listbox entry.  With COLS, only a portion of each Listbox entry is highlighted at one time.

The display columns are formed from the LIST FROM attribute.  The FROM field is split into columns of the size specified by the first parameter of COLS.  This first parameter uses a string containing ASCII codes which set the size of each column.

2.	In the Column field, type in the number of display columns that you want.

The Header box is composed of Text, Justification, and Indentation fields.  The Header string enclosed in tildes, followed by optional justification and/or indent, displays the header at the top of the list.  The header uses the same justification and indent as the field, if not specifically overridden.

3.	In the Text field, type in your text.

The Justification field requires one component that specifies Left, Right, Center, or Decimal justification.

4.	In the Justification field, press the Drop List box and highlight your choice.

The Indent field contains an optional integer, enclosed in parentheses, that specifies an indent from the justification.  This is measured in dialog units and may be negative.  With Left (L) justification, indent defines a left margin; with Right (R) or Decimal (D), it defines a right margin; and with Center (C), it defines an indent from the center of the field.

5.	In the Indent field, type in the indent value.

6.	Check the Scroll Bar box.

7.	In the Size field, enter the number of rows to scroll.

There are four flags (modifiers) available for your use: Underline, Right Border, Resizeable, and Fixed.

Underline	Uses an underscore to underline the field.

Right Border	Places a vertical line to the right of the field.

Resizeable	Places an M in the format string which allows the group of fields to be dynamically re-sized at runtime.  This allows the right vertical bar to be dragged.

Fixed	Places an F in the format string which creates a fixed column in the list that stays on screen when the user horizontally pages through the fields (by the HSCROLL attribute).  Fixed regions must be at the start of the list.

8.	Check the Flags that you want.

The Format String field contains the information for single or multi-column formatting of the data.  It contains field-specifiers which map to the fields of the QUEUE and/or region-specifiers that group together one or more fields to be displayed as a unit.  Only the fields in the QUEUE for which there are field-specifiers are included in the display.  This means that if there are two fields specified in the format string and three fields in the QUEUE, only the two specified in the format string are displayed in the List or Combo control.

 9.	Press the OK button.

You have completed the Listbox Column Properties window.


Declaring Variables

Variable Declaration Statements

BYTE  (one-byte unsigned integer)

SHORT  (two-byte signed integer)

USHORT  (two-byte unsigned integer)

LONG  (four-byte signed integer)

ULONG  (four-byte unsigned integer)

SREAL  (four-byte signed floating point)

REAL  (eight-byte signed floating point)

BFLOAT4  (four-byte signed floating point)

BFLOAT8  (eight-byte signed floating point)

DECIMAL  (fixed-length signed packed decimal)

PDECIMAL  (fixed-length signed packed decimal)

STRING  (fixed-length string)

CSTRING  (fixed-length null terminated string)

PSTRING  (embedded length-byte string)

DATE  (four-byte date)

TIME  (four-byte time)

GROUP  (compound data structure)

LIKE  (user-defined data types)

Implicit Variables

Reference Variables

Attributes of Variables

PRE  (set group label prefix)

DIM  (set array dimensions)

EXTERNAL  (set variable defined externally)

NAME  (set variable's external name)

OVER  (set shared memory location)

STATIC  (set local variable static)

THREAD  (set thread-specific static variable)

BINDABLE  (set dynamic expression string variables)

Data Declarations and Memory Allocation

Global, Local, Static, and Dynamic

Data Declaration Sections

Picture Tokens

Numeric and Currency Pictures

Scientific Notation Pictures

Date Pictures

Time Pictures

Pattern Pictures

Key-in Template Pictures

String Pictures

Compiler Directives

EQUATE  (assign label)

SIZE  (memory size in bytes)


Variable Declaration Statements

BYTE  (one-byte unsigned integer)

SHORT  (two-byte signed integer)

USHORT  (two-byte unsigned integer)

LONG  (four-byte signed integer)

ULONG  (four-byte unsigned integer)

SREAL  (four-byte signed floating point)

REAL  (eight-byte signed floating point)

BFLOAT4  (four-byte signed floating point)

BFLOAT8  (eight-byte signed floating point)

DECIMAL  (fixed-length signed packed decimal)

PDECIMAL  (fixed-length signed packed decimal)

STRING  (fixed-length string)

CSTRING  (fixed-length null terminated string)

PSTRING  (embedded length-byte string)

DATE  (four-byte date)

TIME  (four-byte time)

GROUP  (compound data structure)

LIKE  (user-defined data types)

Implicit Variables

Reference Variables


BYTE  (one-byte unsigned integer)

label	BYTE(initial value) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

BYTE	A one-byte unsigned integer.

Format:	 single byte variable

Ûì

Bits:	7                   0

Range:	0 to 255

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

BYTE declares a one-byte unsigned integer.  Assigning an out-of-range number to a BYTE produces unpredictable results.

Example:

Count1	BYTE	!Declare one byte integer

Count2	BYTE,OVER(Count1)	!Declare OVER the one byte integer

Count3	BYTE,DIM(4)	!Declare it an array of 4 bytes

Count4	BYTE(5)	!Declare with initial value

Count5	BYTE,EXTERNAL	!Declare as external

Count6	BYTE,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Clarion')	!Declare a file

Record	  RECORD

Count5	    BYTE,NAME('Counter')	!Declare with external name

. .


SHORT  (two-byte signed integer)

label	SHORT([initial value]) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

SHORT	A two-byte signed integer.

Format:	 sign    magnitude

ÛÙì

Bits:	 15                    0

Range:	-32,768 to 32,767

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

SHORT declares a two-byte signed integer, using the Intel 8086 word integer format.  The high-order bit of this configuration is the sign bit (0 = positive, 1 = negative).  Negative values are represented in standard two's complement notation.  Assigning an out-of-range number to a SHORT produces unpredictable results.

Example:

Count1	SHORT	!Declare two-byte signed integer

Count2	SHORT,OVER(Count1)	!Declare OVER the two-byte signed integer

Count3	SHORT,DIM(4)	!Declare it an array of 4 shorts

Count4	SHORT(5)	!Declare with initial value

Count5	SHORT,EXTERNAL	!Declare as external

Count6	SHORT,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Clarion')!Declare a file

Record	  RECORD

Count7	    SHORT,NAME('Counter')	!Declare with external name

. .


USHORT  (two-byte unsigned integer)

label	USHORT([initial value]) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

USHORT	A two-bye unsigned integer.

Format:	       magnitude

Ûì

Bits:	 15                   0

Range:	0 to 65,535

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

USHORT declares a two-byte unsigned integer in the Intel 8086 word format.  There is no sign bit in this configuration.   Assigning an out-of-range number to a USHORT produces unpredictable results.

Example:

Count1	USHORT	!Declare two-byte unsigned integer

Count2	USHORT,OVER(Count1)	!Declare OVER the two-byte unsigned integer

Count3	USHORT,DIM(4)	!Declare it an array of 4 unsigned shorts

Count4	USHORT(5)	!Declare with initial value

Count5	USHORT,EXTERNAL	!Declare as external

Count6	USHORT,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

Count7	    USHORT,NAME('Counter')	!Declare with external name

. .


LONG  (four-byte signed integer)

label	LONG([initial value]) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

LONG	A four-byte unsigned integer.

Format:	 sign    magnitude

ÛÙì

Bits:	 31                    0

Range:	-2,147,483,648 to 2,147,483,647

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

LONG declares a four-byte signed integer, using the Intel 8086 long integer format.  The high-order bit is the sign bit (0 = positive, 1 = negative).  Negative values are represented in standard two's complement notation.  Assigning an out-of-range number to a LONG produces unpredictable results.

Example:

Count1	LONG	!Declare four-byte signed integer

Count2	LONG,OVER(Count1)	!Declare OVER the four-byte signed integer

Count3	LONG,DIM(4)	!Declare it an array of 4 longs

Count4	LONG(5)	!Declare with initial value

Count5	LONG,EXTERNAL	!Declare as external

Count6	LONG,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Clarion') 	!Declare a file

Record	RECORD

Count7	    LONG,NAME('Counter')	!Declare with external name

. .


ULONG  (four-byte unsigned integer)

label	ULONG([initial value]) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

ULONG	A four-byte unsigned integer.

Format:	       magnitude

Ûì

Bits:	 31                   0

Range:	0 to 4,294,967,295

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

ULONG declares a four-byte unsigned integer, using the Intel 8086 long integer format.  There is no sign bit in this configuration.  Assigning an out-of-range number to a ULONG produces unpredictable results.

Example:

Count1	ULONG	!Declare four-byte unsigned integer

Count2	ULONG,OVER(Count1)	!Declare OVER four-byte unsigned integer

Count3	ULONG,DIM(4)	!Declare it an array of 4 unsigned longs

Count4	ULONG(5)	!Declare with initial value

Count5	ULONG,EXTERNAL	!Declare as external

Count6	ULONG,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

Count7	    ULONG,NAME('Counter')	!Declare with external name

. .


SREAL  (four-byte signed floating point)

label	SREAL([initial value]) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

SREAL	A four-byte floating point number.

Format:	 sign   exponent        significand

ÛÙÙì

Bits:	 31            23                       0

Range:	0, ± 1.17549435e-38 .. ± 3.40282347e+38 (6 significant digits)

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

SREAL declares a four-byte floating point signed numeric variable, using the Intel 8087 short real (single precision) format.  Assigning an out-of-range number to an SREAL produces unpredictable results.

Example:

Count1	SREAL	!Declare four-byte signed floating point

Count2	SREAL,OVER(Count1)	!Declare OVER the four-byte

!   signed floating point

Count3	SREAL,DIM(4)	!Declare it an array of 4 floats

Count4	SREAL(5)	!Declare with initial value

Count5	SREAL,EXTERNAL	!Declare as external

Count6	SREAL,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

Count7	    SREAL,NAME('Counter')	!Declare with external name

. .


REAL  (eight-byte signed floating point)

label	REAL([initial value]) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

REAL	An eight-byte floating point number.

Format:	 sign   exponent        significand

ÛÙÙì

Bits:	 63             52                      0

Range:	0, ± 2.225073858507201e-308 .. ± 1.79769313496231e+308

 (15 significant digits)

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

REAL declares an eight-byte floating point signed numeric variable, using the Intel 8087 long real (double precision) format.  Assigning an out-of-range number to a REAL produces unpredictable results.

Example:

Count1	REAL	!Declare eight-byte signed floating point

Count2	REAL,OVER(Count1)	!Declare OVER the eight-byte

!   signed floating point

Count3	REAL,DIM(4)	!Declare it an array of 4 reals

Count4	REAL(5)	!Declare with initial value

Count5	REAL,EXTERNAL	!Declare as external

Count6	REAL,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Clarion') 	!Declare a file

Record	  RECORD

Count5	    REAL,NAME('Counter')	!Declare with external name

. .


BFLOAT4  (four-byte signed floating point)

label	BFLOAT4([initial value]) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

BFLOAT4	A four-byte floating point number.

Format:	 exponent     sign      significand

ÛÙÙì

Bits:	31             23                       0

Range:	0, ± 5.877471754e-39 .. ± 1.7014118346e+38

 (15 significant digits)

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

BFLOAT4 declares a four-byte floating point signed numeric variable, using the Microsoft BASIC (single precision) format.  Assigning an out-of-range number to a BFLOAT4 produces unpredictable results.

Example:

Count1	BFLOAT4	!Declare four-byte signed floating point

Count2	BFLOAT4,OVER(Count1)	!Declare OVER the four-byte

!   signed floating point

Count3	BFLOAT4,DIM(4)	!Declare array of 4 single-precision reals

Count4	BFLOAT4(5)	!Declare with initial value

Count5	BFLOAT4,EXTERNAL	!Declare as external

Count6	BFLOAT4,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

Count5	    BFLOAT4,NAME('Counter')	!Declare with external name

. .


BFLOAT8  (eight-byte signed floating point)

label	BFLOAT8([initial value]) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
[,STATIC] [,THREAD]

BFLOAT8	An eight-byte floating point number.

Format:	 exponent     sign      significand

ÛÙÙì

Bits:	63             55                       0

Range:	0, ± 5.877471754e-39 .. ± 1.7014118346e+38

 (15 significant digits)

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

BFLOAT8 declares an eight-byte floating point signed numeric variable, using the Microsoft BASIC (double precision) format.  Assigning an out-of-range number to a BFLOAT8 produces unpredictable results.

Example:

Count1	BFLOAT8	!Declare eight-byte signed floating point

Count2	BFLOAT8,OVER(Count1)	!Declare OVER the eight-byte

!   signed floating point

Count3	BFLOAT8,DIM(4)	!Declare it an array of 4 reals

Count4	BFLOAT8(5)	!Declare with initial value

Count5	BFLOAT8,EXTERNAL	!Declare as external

Count6	BFLOAT8,NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

Count5	    BFLOAT8,NAME('Counter')	!Declare with external name

. .


DECIMAL  (fixed-length signed packed decimal)

label	DECIMAL(length [,places] [,initial value]) [,DIM( )] [,OVER( )] [,NAME( )]
[,STATIC] [,THREAD]
 [,EXTERNAL]

DECIMAL	A packed decimal floating point number.

Format:	 s d15  d14  d13  d12 d11  d10  d9  d8   d7  d6   d5  d4  d3   d2  d1   d0

ÛÙÙÙÙÙÙÙÙÙÙÙÙÙÙÙÙì

Bits:	 60                                                               0

Range:	-999,999,999,999,999 to 999,999,999,999,999

length	A required numeric constant containing the total number of decimal digits (integer and fractional portion combined) in the variable.  The maximum length is 15.

places	A numeric constant that fixes the number of decimal digits in the fractional portion (to the right of the decimal point) of the variable.  It must be less than or equal to the length parameter.  If omitted, it will be declared as an integer.

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

DECIMAL declares a variable length packed decimal signed numeric variable in the Intel 8087 type of format.  Each byte of a DECIMAL holds two decimal digits (4 bits per digit).  The left-most byte holds the sign in its high-order nibble (0 = positive, anything else is negative) and one decimal digit.  Therefore, DECIMAL variables always contain a fixed "odd" number of digits (DECIMAL(10) and DECIMAL(11) both use 6 bytes).  Assigning an out-of-range number to a DECIMAL produces unpredictable results.

Example:

Count1	DECIMAL(5,0)	!Declare three-byte signed packed decimal

Count2	DECIMAL(5),OVER(Count1)	!Declare OVER the three-byte

!   signed packed decimal

Count3	DECIMAL(5,0),DIM(4)	!Declare it an array of 4 decimals

Count4	DECIMAL(5,0,5)	!Declare with initial value

Count5	DECIMAL(5,0),EXTERNAL	!Declare as external

Count6	DECIMAL(5,0),NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Clarion') 	!Declare a file

Record	  RECORD

Count7	    DECIMAL(5,0),NAME('Counter')	!Declare with external name

. .


PDECIMAL  (fixed-length signed packed decimal)

label	PDECIMAL(length [,places] [,initial value]) [,DIM( )] [,OVER( )] [,NAME( )]
[,EXTERNAL] [,STATIC] [,THREAD]

PDECIMAL	A packed decimal floating point number.

Format:	 d15  d14  d13  d12 d11  d10  d9  d8   d7  d6   d5  d4  d3   d2  d1   d0  s

ÛÙÙÙÙÙÙÙÙÙÙÙÙÙÙÙÙì

Bits:	63                                                              5 0

Range:	-999,999,999,999,999 to 999,999,999,999,999

length	A required numeric constant containing the total number of decimal digits (integer and fractional portion combined) in the variable.  The maximum length is 15.

places	A numeric constant that fixes the number of decimal digits in the fractional portion (to the right of the decimal point) of the variable.  It must be less than or equal to the length parameter.  If omitted, it will be declared as an integer.

initial value	A numeric constant.  Variables are not initialized unless given an initial value.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

PDECIMAL declares a variable length packed decimal signed numeric variable in the Btrieve and IBM/EBCDIC type of format.  Each byte of an PDECIMAL holds two decimal digits (4 bits per digit).  The right-most byte holds the sign in its low-order nibble (0Fh or 0Ch = positive, 0Dh = negative) and one decimal digit.  Therefore, PDECIMAL variables always contain a fixed "odd" number of digits (PDECIMAL(10) and PDECIMAL(11) both use 6 bytes).  Assigning an out-of-range number to a PDECIMAL produces unpredictable results.

Example:

Count1	PDECIMAL(5,0)	!Declare three-byte signed packed decimal

Count2	PDECIMAL(5),OVER(Count1)	!Declare OVER the three-byte

!   signed packed decimal

Count3	PDECIMAL(5,0),DIM(4)	!Declare it an array of 4 decimals

Count4	PDECIMAL(5,0,5)	!Declare with initial value

Count5	PDECIMAL(5,0),EXTERNAL	!Declare as external

Count6	PDECIMAL(5,0),NAME('SixCount')	!Declare with external name

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

Count7	    PDECIMAL(5,0),NAME('Counter')	!Declare with external name

. .


STRING  (fixed-length string)

     length
label	STRING(	string constant	) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
     picture	  [,STATIC] [,THREAD]

STRING	A character string.

Format:	A fixed number of bytes.

Size:	1 to 65,520 bytes.

length	A numeric constant that defines the number of bytes in the STRING.  String variables are not initialized unless given a string constant.

string constant	The initial value of the STRING.  The length of the STRING (in bytes) is set to the length of the string constant.

picture	Used to format the values assigned to the STRING.  The length is the number of bytes needed to contain the formatted STRING.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

STRING declares a fixed-length character string.  The memory assigned to the STRING is not initialized to any value unless it is declared with a string constant.

In addition to its explicit declaration, all STRING variables are also implicitly declared as STRING(1),DIM(length of string).  This allows each character in the STRING to be addressed as an array element.  If the STRING also has a DIM attribute, this implicit array declaration is the last (optional) dimension of the array (to the right of the explicit dimensions).

You may also directly address multiple characters within a STRING using the "string slicing" technique.  This technique performs similar action to the SUB function, but is much more flexible and efficient.  It is more flexible because a "string slice" may be used on both the destination and source sides of an assignment statement and the SUB function can only be used as the source.  It is more efficient because it takes less memory than individual character assignments or the SUB function.

To take a "slice" of the STRING, the beginning and ending character numbers are separated by a colon (:) and placed in the implicit array dimension position within the square brackets ([]) of the STRING.  The position numbers may be integer constants, variables, or expressions.  If variables are used, there must be at least one blank space between the variable name and the colon separating the beginning and ending number (to prevent PREfix confusion).

Example:

Name	STRING(20)	!Declare 20 byte name field

ArrayString	STRING(5),DIM(20)	!Declare array

Company	STRING('Clarion Software, Inc.')	!The software company - 22 bytes

Phone	STRING(@P(###)###-####P)	!Phone number field - 13 bytes

ExampleFile	FILE,DRIVER('Clarion') 	!Declare a file

Record	  RECORD

NameField 	    STRING(20),NAME('Name')	!Declare with external name

. .

  CODE

  NameField = 'Tammi'	!Assign a value

  NameField[5] = 'y'	! change fifth letter

  NameField[5:6] = 'ie'	! and change a "slice"

!   -- the fifth and sixth letters

  ArrayString[1] = 'First'	!Assign value to first element

  ArrayString[1,2] = 'u'	!Change first element 2nd character

  ArrayString[1,2:3] = NameField[5:6]	!Assign slice to slice


CSTRING  (fixed-length null terminated string)

     length
label	CSTRING(	string constant	) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
     picture	  [,STATIC] [,THREAD]

CSTRING	A character string.

Format:	A fixed number of bytes.

Size:	2 to 65,520 bytes.

length	A numeric constant that defines the number of bytes of storage the string will use.  This must include a position for the terminating null character.  String variables are not initialized unless given a string constant.

string constant	A string constant containing the initial value of the string.  The length of the string is set to the length of the string constant plus the terminating null character.

picture	The picture token used to format the values assigned to the string.  The length of the string is the number of bytes needed to contain the formatted string and the terminating null character.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

CSTRING declares a character string terminated by a null character (ASCII zero).  The memory assigned to the CSTRING is not initialized to any value unless it is declared with a string constant.

CSTRING matches the string data type used in the "C" language and the "ZSTRING" data type of the Btrieve Record Manager.  Storage and memory requirements are fixed-length, however the terminating null character is placed at the end of the data entered.  CSTRING is internally converted to a STRING intermediate value for use during program execution.  It should be used to achieve compatibility with outside files or procedures.

In addition to its explicit declaration, all CSTRINGs are implicitly declared as a CSTRING(1),DIM(length of string).  This allows each character in the CSTRING to be addressed as an array element.  If the CSTRING also has a DIM attribute, this implicit array declaration is the last (optional) dimension of the array (to the right of the explicit dimensions).

You may also directly address multiple characters within a CSTRING using the "string slicing" technique.  This technique performs similar action to the SUB function, but is much more flexible and efficient.  It is more flexible because a "string slice" may be used on both the destination and source sides of an assignment statement and the SUB function can only be used as the source.  It is more efficient because it takes less memory than individual character assignments or the SUB function.

To take a "slice" of the CSTRING, the beginning and ending character numbers are separated by a colon (:) and placed in the implicit array dimension position within the square brackets ([]) of the CSTRING.  The position numbers may be integer constants, variables, or expressions.  If variables are used, there must be at least one blank space between the variable name and the colon separating the beginning and ending number (to prevent PREfix confusion).

Since a CSTRING must be null-terminated, the programmer must be responsible for ensuring that an ASCII zero is placed at the end of the data if the field is only accessed through its array elements or as a "slice" (not as a whole entity).

Example:

Name	CSTRING(21)	!Declare 21 byte field - 20 bytes data

OtherName	CSTRING(21),OVER(Name)	!Declare field over name field

Contact 	CSTRING(21),DIM(4) 	!Array 21 byte fields - 80 bytes data

Company	CSTRING('Clarion Software, Inc.')  !23 byte string - 22 bytes data

Phone	CSTRING(@P(###)###-####P)	!Declare 14 bytes - 13 bytes data

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

NameField 	    CSTRING(21),NAME('ZstringField')  !Declare with external name

. .

  CODE

  Name = 'Tammi'	!Assign a value

  Name[5] = 'y'	! then change fifth letter

  Name[6] = 's'	! then add a letter

  Name[7] = '<0>'	! and handle null terminator

  Name[5:6] = 'ie'	! and change a "slice"

!   -- the fifth and sixth letters

  Contact[1] = 'First'	!Assign value to first element

  Contact[1,2] = 'u'	!Change first element 2nd character

  Contact[1,2:3] = Name[5:6]	!Assign slice to slice


PSTRING  (embedded length-byte string)

     length
label	PSTRING(	string constant	) [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL]
     picture	  [,STATIC] [,THREAD]

PSTRING	A character string.

Format:	A fixed number of bytes.

Size:	2 to 255 bytes.

length	A numeric constant that defines the number of bytes in the string.  This must include the first position length-byte.

string constant	A string constant containing the initial value of the string.  The length of the string is set to the length of the string constant plus the length-byte.

picture	The picture token used to format the values assigned to the string.  The length of the string is the number of bytes needed to contain the formatted string plus the first position length byte.  String variables are not initialized unless given a string constant.

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

PSTRING declares a character string with a leading length byte included in the number of bytes declared for the string.  The memory assigned to the PSTRING is not initialized to any value unless it is declared with a string constant.

PSTRING matches the string dta type used by the Pascal language and the "LSTRING" data type of the Btrieve Record Manager.  Storage and memory requirements are fixed-length, however, the leading length byte will contain the number of characters actually stored.  PSTRING is internally converted to a STRING intermediate value for use during program execution.  It should be used to achieve compatibility with outside files or procedures.

In addition to its explicit declaration, all PSTRINGs are implicitly declared as a PSTRING(1),DIM(length of string).  This allows each character in the PSTRING to be addressed as an array element.  If the PSTRING also has a DIM attribute, this implicit array declaration is the last (optional) dimension of the array (to the right of the explicit dimensions).

You may also directly address multiple characters within a PSTRING using the "string slicing" technique.  This technique performs similar action to the SUB function, but is much more flexible and efficient.  It is more flexible because a "string slice" may be used on both the destination and source sides of an assignment statement and the SUB function can only be used as the source.  It is more efficient because it takes less memory than individual character assignments or the SUB function.

To take a "slice" of the PSTRING, the beginning and ending character numbers are separated by a colon (:) and placed in the implicit array dimension position within the square brackets ([]) of the PSTRING.  The position numbers may be integer constants, variables, or expressions.  If variables are used, there must be at least one blank space between the variable name and the colon separating the beginning and ending number (to prevent PREfix confusion).

Since a PSTRING must have a leading length byte, the programmer must be responsible for ensuring that its value is always correct if the field is only accessed through its array elements or as a "slice" (not as a whole entity).  The PSTRING's length byte is addressed as element zero (0) of the array (the only case in Clarion where an array has a zero element).  Therefore, the valid range of array indexes for a PSTRING(30) would be 0 to 29.

Example:

Name	PSTRING(21)	!Declare 21 byte field - 20 bytes data

OtherName	PSTRING(21),OVER(Name)	!Declare field over name field

Contact 	PSTRING(21),DIM(4) 	!Array 21 byte fields - 80 bytes data

Company	PSTRING('Clarion Software, Inc.')	!23 byte string - 22 bytes data

Phone	PSTRING(@P(###)###-####P)	!Declare 14 bytes - 13 bytes data

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

NameField 	    PSTRING(21),NAME('LstringField')	!Declare with external name

. .

  CODE

  Name = 'Tammi'	!Assign a value

  Name[5] = 'y'	! then change fifth letter

  Name[6] = 's'	! then add a letter

  Name[0] = '<6>'	! and handle length byte

  Name[5:6] = 'ie'	! and change a "slice"

!   -- the fifth and sixth letters

  Contact[1] = 'First'	!Assign value to first element

  Contact[1,2] = 'u'	!Change first element 2nd character

  Contact[1,2:3] = Name[5:6]	!Assign slice to slice


DATE  (four-byte date)

label	DATE [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL] [,STATIC] [,THREAD]

DATE	A four-byte date.

Format:	 year [image] mm dd

ÛÙÙÙì

Range:	 year: 1 to 9999

month: 1 to 12

  day: 1 to 31

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

DATE declares a four-byte date variable.  This format matches the "DATE" field type used by the Btrieve Record Manager.  A DATE used in a numeric expression is converted to the number of days elapsed since December 28, 1800 (Clarion Standard Date   usually stored as a LONG).  The valid Clarion Standard Date range is January 1, 1801 through December 31, 2099.  Using an out-of-range date produces unpredictable results.  DATE fields should be used to achieve compatibility with outside files or procedures.

Example:

DueDate	DATE	!Declare a date field

OtherDate	DATE,OVER(DueDate)	!Declare field over date field

ContactDate	DATE,DIM(4) 	!Array of 4 date fields

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

DateRecd 	    DATE,NAME('DateField')	!Declare with external name

. .

See Also:

Standard Date


TIME  (four-byte time)

label	TIME [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL] [,STATIC] [,THREAD]

TIME	A four-byte time.

Format:	 hh mm ss hs

ÛÙÙÙì

Range:	      hours: 0 to 23

    minutes: 0 to 59

    seconds: 0 to 59

seconds/100: 0 to 99

DIM	Dimension the variable as an array.

OVER	Share a memory location with another variable.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

TIME declares a four byte time variable.  This format matches the "TIME" field type used by the Btrieve Record Manager.  A TIME used in a numeric expression is converted to the number of hundredths of a second elapsed since midnight (Clarion Standard Time   usually stored as a LONG).  TIME fields should be used to achieve compatibility with outside files or procedures.

Example:

ChkoutTime	TIME	!Declare checkout time field

OtherTime 	TIME,OVER(CheckoutTime)	!Declare field over time field

ContactTime	TIME,DIM(4) 	!Array of 4 time fields

ExampleFile	FILE,DRIVER('Btrieve') 	!Declare a file

Record	  RECORD

TimeRecd 	    TIME,NAME('TimeField')	!Declare with external name

. .

See Also:

Standard Time


GROUP  (compound data structure)

label	GROUP [,PRE( )] [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL] [,STATIC]
[,THREAD] [,BINDABLE]
  declarations
END

GROUP	A compound data structure.

declarations	Multiple consecutive variable declarations.

PRE	Declare a label prefix for variables within the structure.

DIM	Dimension the variables into an array.

OVER	Share a memory location with another variable or structure.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

BINDABLE	Specify all variables in the group may be used in dynamic expressions.

A GROUP structure allows multiple variable declarations to be referenced by a single label.  It may be used to dimension a set of variables, or to assign or compare sets of variables in a single statement.  In large complicated programs, a GROUP structure is helpful for keeping sets of related data organized.  A GROUP must be terminated by a period or the END statement.

When referenced in a statement or expression, a GROUP is treated as a STRING composed of all the variables within the structure.  A GROUP structure may be nested within another data structure, such as a RECORD or another GROUP.

Because of their internal storage format, numeric variables (other than DECIMAL) declared in a group do not collate properly when treated as strings.  For this reason, building a KEY on a GROUP that contains numeric variables may produce an unexpected collating sequence.

A GROUP with the BINDABLE attribute all the variables within the GROUP as available for use in a dynamic expression.  The contents of each variable's NAME attribute is the logical name used in the dynamic expression.  If no NAME attribute is present, the label of the variable (including prefix) is used.  Space is allocated in the .EXE for the names of all of the variables in the structure.  This creates a larger program that uses more memory than it normally would.  Therefore, the BINDABLE attribute should only be used when a large proportion of the constituent fields are going to be used.

Example:

NameGroup	GROUP,PRE(Nme)	!Name group

First	  STRING(20)	!  first name

Middle	  STRING(1)	!  middle initial

Last	  STRING(20)	!  last name

END	!End group declaration

DateTimeGrp	GROUP,PRE(Dtg),DIM(10)	!Date/time array

Date 	  LONG	!

Time	  LONG	!

END	!End group declaration

FileNames	GROUP,BINDABLE	!Bindable group

FileName	  STRING(8),NAME('FILE')	!Dynamic name: FILE

Dot	  STRING('.')	!Dynamic name: Dot

Extension	  STRING(3),NAME('EXT')	!Dynamic name: EXT

END	!


LIKE  (user-defined data types)

new declaration	LIKE(like declaration) [,DIM( )] [,OVER( )] [,PRE( )] [,NAME( )] [,BINDABLE]

LIKE	Declares a variable whose data type is taken from another variable.

new declaration	The label of the new data element declaration.

like declaration	The label of the data element declaration whose definition will be used.

DIM	Dimension the variables into an array.

OVER	Share a memory location with another variable or structure.

PRE	Declare a label prefix for any variables within the structure.  This is required when the like declaration is a GROUP.

NAME	Specify an alternate, "external" name for the field.

EXTERNAL	Specify the variable is defined, and its memory is allocated, in an external library.  Not valid within FILE, QUEUE, or GROUP declarations.

STATIC	Specify the variable's memory is permanently allocated.

THREAD	Specify memory for the variable is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

BINDABLE	Specify all variables in the group may be used in dynamic expressions.

LIKE tells the compiler to define the new declaration using the same definition as the like declaration, including all attributes.

The new declaration may use the DIM and OVER attributes.  If the like declaration has a DIM attribute, the new declaration is already an array.  If a further DIM attribute is added to the new declaration, the array is further dimensioned.

The PRE and NAME attributes may be used, if appropriate.  If the like declaration already has these attributes, the new declaration will inherit them and compiler errors can occur.  To correct this, specify a PRE or NAME attribute on the new declaration to override the inherited attribute.

Example:

Amount	REAL	!Define a field

QTDAmount	LIKE(Amount)	!Use same definition

YTDAmount	LIKE(QTDAmount)	!Use same definition again

MonthlyAmts	LIKE(Amount),DIM(12)	!Use same definition for array, 12 elements

AmtPrPerson	LIKE(MonthlyAmts),DIM(10)

!Use same definition for array of 120 elements (12,10)

Construct	GROUP,PRE(Con)	!Define a group

Field1	  LIKE(Amount)	!  con:field1 - real

Field2	  STRING(10)	!  con:field2 - string(10)

END

NewGroup	LIKE(Construct),PRE(New)	!Define new group, with

!  new:field1 - real

!  new:field2 - string(10)

AmountFile	FILE,DRIVER('Clarion'),PRE(Amt)

Record	  RECORD

Amount	    REAL	!Define a field

QTDAmount	    LIKE(Amount)	!Use same definition

. .

See Also:

DIM

OVER

PRE

NAME


Implicit Variables

Implicit variables are not declared in data declarations.  They are created by the compiler when it first encounters them.  Implicit variables are automatically initialized to blank or zero; they do not have to be explicitly assigned values before use.  You may always assume that they contain blanks or zero before your program's first assignment to them.

Any implicit variable used in the global data declaration area (between the keywords PROGRAM and CODE) is Global data, assigned static memory.  Any implicit variable used between the keywords MEMBER and PROCEDURE (or FUNCTION) is Module data, assigned static memory.  Any other implicit variable is Local data, assigned dynamic memory on the program's stack.

Since the compiler dynamically creates implicit variables as they are encountered, there is a danger that problems may arise that can be difficult to trace.  This is due to the lack of compile-time error and type checking on implicit variables.  For example, if you spell incorrectly the name of a previously used implicit variable, the compiler will not tell you, but will simply create a new implicit variable with the new spelling.  When your program checks the value in the original implicit variable, it will be incorrect.  Therefore, implicit variables should be used with care and caution, and only within a limited scope.

Implicit variables are generally used for: array subscripts, true/false switches, intermediate variables in complex calculations, loop control variables, etc.  The Clarion language provides three types of implicit variables:

   #	Pound sign names an implicit LONG variable, a label terminated by a # character.

   $	Dollar sign names an implicit REAL variable, a label terminated by a $ character.

   "	Double quote names an implicit 32 byte string, a label terminated by a " character.

Example:

LOOP Counter# = 1 TO 10	!Implicit LONG

  ArrayField[Counter#] = Counter# * 2	!Initialize an array

END

Address" = CLIP(City) & ', ' & State & '  ' & Zip	!Implicit STRING(32)

MESSAGE(Address")	!Used to display a temporary value

Percent$ = ROUND((Quota / Sales),.1) * 100	!Implicit REAL

MESSAGE(FORMAT(Percent$,@P%<<<.##P))	!Used to display a temporary value

See Also:

Data Declarations & Memory Allocation


Reference Variables

A reference variable contains a reference to another data declaration (its "target").  You declare a reference variable by prepending an ampersand (&) to the data type of its target (&BYTE, &FILE, &LONG, &WINDOW, etc.).  Depending upon the target's data type, the reference variable may contain the target's memory address, or a more complex internal data structure (describing the location and type of target data).

Valid reference variable declarations are: &BYTE, &SHORT, &USHORT, &LONG, &ULONG, &REAL, &SREAL, &BFLOAT8, &BFLOAT4, &DECIMAL, &PDECIMAL, &STRING, &CSTRING, &PSTRING, &GROUP, &QUEUE, &FILE, &VIEW, &WINDOW.  Reference variables may not be declared within GROUP, FILE, QUEUE, or VIEW structures.

The &STRING, &CSTRING, &PSTRING, &DECIMAL, and &PDECIMAL reference variable declarations do not require length parameters, since all necessary information about the specific target data item is contained in the reference.  This means a &STRING reference variable may contain a reference to any length STRING variable.  A reference variable declared with &WINDOW can target either an APPLICATION, WINDOW, or REPORT structure.

The label of the reference variable is syntactically correct every place in executable code where its target is allowed.  When used in a code statement, the reference variable is automatically "dereferenced" to supply the statement the value of its target (except for reference assignment statements).

The &= operator executes a reference assignment statement (destination &= source).  This assigns the source's reference to the destination reference variable.

Example:

App1   APPLICATION('Hello')

       END

App2   APPLICATION('Buenos Dias')

       END

AppRef &WINDOW	!Reference to an APPLICATION, WINDOW, or REPORT

  CODE

  IF CTL:Language = 'English'  	!If english language user

    AppRef &= App1	! reference english application frame

  ELSE

    AppRef &= App2	! else reference spanish application frame

  END

  OPEN(AppRef)	!Open the referenced application frame window

See Also:

Reference Assignment Statements


Attributes of Variables

PRE  (set group label prefix)

DIM  (set array dimensions)

EXTERNAL  (set variable defined externally)

NAME  (set variable's external name)

OVER  (set shared memory location)

STATIC  (set local variable static)

THREAD  (set thread-specific static variable)

BINDABLE  (set dynamic expression string variables)


PRE  (set group label prefix)

PRE(prefix)

PRE 	Provides a label prefix for complex data structures.

prefix	Acceptable characters are alphabet letters, numerals 0 through 9, and the underscore character.  A prefix must start with an alphabet character and must not be a reserved word.

The PRE attribute provides a label prefix for complex data structures.  It is used to distinguish between identical variable names that occur in different structures.  When referenced in executable statements, assignments, and parameter lists, a prefix is attached to a label by a colon (Pre:Label).  PRE may be used with the following data structures discussed in this chapter: GROUP, and LIKE.

Example:

G1	GROUP,PRE(Mem)	!Declare some memory variables

Message	  STRING(30)	! with the Mem prefix

Page	  LONG

Line	  LONG

Device	  STRING(30)

END

G2	LIKE(G1),PRE(Me2)	!Declare second GROUP LIKE the first

!Contains same variables with Me2 prefix

  CODE

  Mem:Message = 'Variable in original group'

  Me2:Message = 'Variable in LIKE group'

See Also:

Reserved Words


DIM  (set array dimensions)

DIM(dimension,...,dimension)

DIM 	Declares a variable as an array.

dimension	A numeric constant which specifies the number of elements in this dimension of the array.

The DIM attribute declares a variable as an array.  The variable is repeated the number of times specified by the dimension parameters.  Multi-dimensional arrays may be thought of as nested.  Each dimension in the array has a corresponding subscript.  Therefore, referencing a variable in a three dimensional array requires three subscripts.  There is no limit to the number of dimensions; however, the total size of an array must not exceed 65,520 bytes of data.

Subscripts identify which element of the array is being referenced.  A subscript list contains a subscript for each dimension of the array.  The each subscript is separated by a comma and the entire list is enclosed in brackets ([ ]).  A subscript may be a numeric constant, expression, or function.  The entire array may be referenced by the label of the array without a subscript list.

A GROUP structure is a special case.  Each level of nesting adds subscripts to the GROUP and the variables within the GROUP.  Data declared within the GROUP may be referenced exactly like the GROUP itself.

Example:

Screen	GROUP	!Characters on the screen

Row	  GROUP,DIM(25)	!Twenty-five rows

Pos	    GROUP,DIM(80)	!Two thousand positions

Attr	      BYTE	!Attribute byte

Char	      BYTE	!Character byte

. . .	!Terminate the group structures

! In the group above:

! Screen	is a 4,000 byte GROUP

! Row[1]	is a 160 byte GROUP

! Pos[1,1]	is a 2 byte GROUP

! Attr[1,1]	is a BYTE

! Char[1,1]	is a BYTE

Month	STRING(10),DIM(12)	!Dimension the month to 12

  CODE

  CLEAR(Month)	!Assign blanks to the entire array

  Month[1] = 'January'	!Load the months into the array

  Month[2] = 'February'

  Month[3] = 'March'

See Also:

MAXIMUM


EXTERNAL  (set variable defined externally)

EXTERNAL( [ member ] )

EXTERNAL 	Specifies the variable or FILE is defined in an external library.

member	A string constant.  Valid only on a FILE declaration.  It contains the filename (without extension) of the MEMBER module containing the FILE definition without the EXTERNAL attribute.  If the FILE is defined in a PROGRAM module, an empty member string ('') is required.

The EXTERNAL attribute specifies that the variable or FILE on which it is placed is defined in an external library.  Therefore, a variable or FILE with the EXTERNAL attribute is declared and may be referenced in the Clarion code, but is not allocated memory.  The memory for the variable or FILE is allocated by the external library.  This allows the Clarion program access to variables or FILEs declared as public in external libraries.

The EXTERNAL attribute, without the member parameter, is valid only on variables declared outside FILE, QUEUE, or GROUP structures.

When using EXTERNAL(member) to declare a FILE shared by multiple libraries (.LIBs, or .DLLs and .EXE), only one library should define the FILE without the EXTERNAL attribute.  All the other libraries (and the .EXE) should declare the FILE with the EXTERNAL attribute.  This ensures that there is only one record buffer allocated for the FILE and all the libraries and the .EXE will reference the same memory when referring to data elements from that FILE.

The FILE declarations in all libraries (or .EXEs) that reference common files must be EXACTLY the same (with the appropriate addition of the EXTERNAL attribute).  If they are not exactly the same, data corruption could occur.  The actual consequence of incompatible FILE declarations is dependent upon the file driver for that file system.  Any incompatibilities between libraries cannot be detected by the compiler or linker, therefore it is the programmer's responsibility to ensure that consistency is maintained.

One suggested way of coding large systems using many .DLLs and/or .EXEs that share the same files would have one .DLL containing the actual FILE definition that only contains FILE and global variable definitions that are shared among all (or most) of the .DLLs and .EXEs.  This makes one central library in which the actual file definitions are maintained.  This one central .DLL is linked into all .EXEs that use those common files.  All other .DLLs and/or .EXEs in the system would declare the common FILEs with the EXTERNAL attribute.

Example:

PROGRAM

MAP

  MODULE('LIB.LIB')

    AddCount	!External library procedure

. .

TotalCount	LONG,EXTERNAL	!A variable declared in an external library

Cust	FILE,PRE(Cus),EXTERNAL('')	!A File defined in a PROGRAM module

CustKey	  KEY('Name')	! whose .LIB is linked into this program

Record	  RECORD

Name	    STRING(20)

. .

Contact	FILE,PRE(Con),EXTERNAL('LIB01')	!A File defined in a MEMBER module

ContactKey	  KEY('Name')	! whose .LIB is linked into this program

Record	  RECORD

Name	    STRING(20)

. .

  The LIB.CLA file contains:

PROGRAM

MAP

  MODULE('LIB01')

    AddCount	!

. .

TotalCount	LONG 	!The TotalCount variable definition

Cust	FILE,PRE(Cus)	!The Cust File definition where the

CustKey	  KEY('Cus:Name')	!  record buffer is allocated

Record	  RECORD

Name	    STRING(20)

. .

  CODE

  !Executable code ...

  The LIB01.CLA file contains:

MEMBER('LIB')

Contact	FILE,PRE(Con) 	!The Contact File definition where the

ContactKey	  KEY('Con:Name')	!  record buffer is allocated

Record	  RECORD

Name	    STRING(20)

. .

AddCount	PROCEDURE

  CODE

  TotalCount += 1

See Also:`

NAME


NAME  (set variable's external name)

NAME([	 constant	 ])
 variable

NAME 	Specifies an "external" name for the linker or file driver.

constant	A string constant.

variable	The label of a STRING variable declared in the global data declaration area or a MEMBER module's data declaration area.

The NAME attribute specifies an "external" name for the linker or file driver.  The NAME attribute is completely independent of the EXTERNAL attribute there is no required connection between the two, although both attributes may be used on the same variable.

The NAME attribute may be placed on a FUNCTION or PROCEDURE Prototype, FILE, KEY, INDEX, MEMO, any field declared within a FILE, any field declared within a QUEUE structure, or any field not within a structure.  The NAME attribute has different implications depending on where it is used.

NAME(constant) may be specified on a FUNCTION or PROCEDURE Prototype.  The constant supplies the external name used by the linker to identify the procedure or function from an external library.

The NAME(constant) or NAME(variable) attribute on a FILE declaration specifies a DOS directory file specification.  If the constant or variable does not contain a drive and path, the current drive and directory are assumed.  If the extension is omitted, the directory entry assumes the file driver's default value.  Some file drivers require that KEYs, INDEXes, or MEMOs be in separate files.  Therefore, a NAME may also be placed on a KEY, INDEX, or MEMO.  A NAME attribute without a constant or variable defaults to the label of the declaration statement on which it is placed (including any specified prefix).

NAME(constant) may be used on any field declared within the RECORD structure.  This provides the file driver with the name of a field as it may be used in that driver's file system.

NAME(constant) may be used on any field declared within a QUEUE structure.  This provides the capability of run time dynamic sorts.

NAME(constant) may be used on any variable declared outside of any structure.  This provides the linker with an external name to identify a variable declared in an external library.  If the variable also has the EXTERNAL attribute, it is declared, and its memory is allocated, as a public variable in the external library.  Without the EXTERNAL attribute, it is declared, and its memory is allocated, in the Clarion program, and it is declared as an external variable in the external library.

Example:

PROGRAM

MAP

  MODULE('External.Obj')

    AddCount(LONG),LONG,C,NAME('_AddCount')

!C function named '_AddCount'

. .

Cust	FILE,PRE(Cus),NAME(CustName)	!Filename in CustName variable

CustKey	  KEY('Name'),NAME('c:\data\cust.idx')	!Declare key, cust.idx

Record	  RECORD

Name	    STRING(20),NAME	!Default NAME to 'Cus:Name'

. .	!End file declaration

SortQue	QUEUE,PRE(Que)

Field1	  STRING(10),NAME('FirstField')	!QUEUE SORT NAME

Field2	  LONG,NAME('SecondField')	!QUEUE SORT NAME

.

CurrentCnt	LONG,EXTERNAL,NAME('Cur')	!Field declared public in

!  external library as 'Cur'

TotalCnt	LONG,NAME('Tot')	!Field declared external

! in external library as 'Tot'

See Also:

FUNCTION and PROCEDURE Prototypes

FILE

KEY

INDEX

QUEUE

EXTERNAL


OVER  (set shared memory location)

OVER(overvariable)

OVER 	Allows one memory address to be referenced two different ways.

overvariable	The label of a variable that already occupies the memory to be shared.

The OVER attribute allows one memory address to be referenced two different ways.  The variable declared with the OVER attribute must not be larger than the overvariable it is being declared OVER (it may be smaller, though).

You may declare a variable OVER an overvariable which is part of the parameter list passed into a PROCEDURE or FUNCTION.  However, if the passed parameter is a *STRING or *GROUP, the compiler will issue a warning because it cannot determine at compile time whether the overvariable is as large as the variable declared with the OVER attribute.

A field within a GROUP structure cannot be declared OVER a variable outside that GROUP structure.

Example:

SomeProc	PROCEDURE(PassedGroup)	!Proc receives a GROUP parameter

NewGroup	GROUP,OVER(PassedGroup)	!Redeclare passed GROUP parameter

Field1	  STRING(10)	!Compiler warning issued that

Field2	  STRING(2)	!  NewGroup must not be larger

END	!  than PassedGroup

CustNote	FILE,PRE(Csn)	!Declare CustNote file

Notes	  MEMO(2000)	!The memo field

Record	  RECORD

CustID	    LONG

. .

CsnMemoRow	STRING(10),DIM(200),OVER(Csn:Notes)	!Csn:Notes memo may be addressed

! as a whole or in 10-byte chunks

See Also:

DIM


STATIC  (set local variable static)

STATIC

The STATIC attribute allows a variable declared within a PROCEDURE or FUNCTION to be allocated static memory instead of stack memory.  This makes any value contained in the variable "persistent" from one instance of the procedure to the next.

Example:

SomeProc	PROCEDURE

AcctFile 	STRING(64),STATIC 	!STATIC needed for use as

! Variable in NAME attribute

Transactions	FILE,DRIVER('Clarion'),PRE(TRA),NAME(AcctFile)

AccountKey     	  KEY(TRA:Account),OPT,DUP

Record         	  RECORD

Account          	    SHORT 	!Account code

Date             	    LONG 	!Transaction Date

Amount           	    DECIMAL(14.2) 	!Transaction Amount

. .

See Also:

Data Declarations and Memory Allocation


THREAD  (set thread-specific static variable)

THREAD

The THREAD attribute declares a static variable which is allocated memory separately for each execution thread in the program.  This makes the value contained in the variable dependent upon which thread is executing.  Whenever a new execution thread is begun, a new instance of the variable, specific to that thread, is created.

The variable must be allocated static memory so it should be declared as Local data with the STATIC attribute.  It may also be declared as Global data or Module data.

This attribute creates a lot of runtime "overhead," particularly on Global or Module data.  Therefore, it should be used only when absolutely necessary.

Example:

GlobalVar	LONG,THREAD	!Each execution thread gets its own copy

See Also:

Data Declarations and Memory Allocation


BINDABLE  (set dynamic expression string variables)

BINDABLE

The BINDABLE attribute declares a GROUP, QUEUE, FILE, or VIEW whose constituent variables are all available for use in a runtime expression string.  The contents of each variable's NAME attribute is the logical name used in the runtime expression string.  If no NAME attribute is present, the label of the variable (including prefix) is used.  Space is allocated in the .EXE for the names of all of the variables in the structure.  This creates a larger program that uses more memory than it normally would.  Therefore, the BINDABLE attribute should only be used when a large proportion of the constituent fields are going to be used.

Example:

FileNames	GROUP,BINDABLE	!Bindable group

FileName	  STRING(8),NAME('FILE')	!Dynamic name: FILE

Dot	  STRING('.')	!Dynamic name: Dot

Extension	  STRING(3),NAME('EXT')	!Dynamic name: EXT

END	!

See Also:

BIND

UNBIND

EVALUATE


Data Declarations amd Memory Allocation
Data Declarations and Memory Allocation

Global, Local, Static, and Dynamic

Data Declaration Sections


Global, Local, Static, and Dynamic

Data declarations allocate memory to store the data values.  Global, Local, Static, and Dynamic are terms that describe types of memory allocation.

The terms "Global" and "Local" refer to the "visibility" of data:

     _	"Global" means the data is visible and available to all procedures in the program.

     _	"Local" means the data has limited visibility.  This may be limited to one procedure or function, or limited to a specific set of procedures and/or functions.

The terms "Static" and "Dynamic" refer to the persistence of the data's memory allocation:

     _	"Static" means the data is allocated memory that is not released until the entire program is finished executing.

     _	"Dynamic" means the data is allocated memory on the program's stack.  Stack memory is released when the PROCEDURE or FUNCTION that allocated the stack memory returns to the place in the program from which it was called.


Data Declaration Sections

There are three areas where data can be declared in a Clarion program:

     _	In the PROGRAM module, after the keyword PROGRAM and before the CODE statement.  This is the Global data section.

     _	In a MEMBER module, after the keyword MEMBER and before the first PROCEDURE or FUNCTION statement.  This is the Module data section.

     _	In a PROCEDURE or FUNCTION, after the keyword PROCEDURE (or FUNCTION) and before the CODE statement.  This is the Local data section.

Global data is visible to executable statements and expressions in every PROCEDURE and FUNCTION in the PROGRAM.  Global data is allocated in Static memory.

Module data is visible only to the set of PROCEDUREs and FUNCTIONs contained in the MEMBER module.  Of course, it may be passed as a parameter to PROCEDUREs or FUNCTIONs in other MEMBER modules, if required.  Module data is also allocated Static memory.

Local data is visible only within the PROCEDURE or FUNCTION in which it is declared.  Of course, it may be passed as a parameter to any other PROCEDURE or FUNCTION.  Local data is allocated Dynamic memory on the program's stack.  This can be overridden by using the STATIC attribute, making its value persistent between calls to the procedure.

Dynamic memory allocation for Local data allows a FUNCTION or PROCEDURE to be truly recursive, receiving a new copy of its local variables each time it is called.

See Also:

FUNCTION and PROCEDURE Prototypes

STATIC


Picture Tokens

Picture tokens provide a masking format for displaying and editing variables.  Picture tokens may be used as parameters of STRING, ENTRY, or STRING OPTION declarations in SCREEN structures; as a parameter of STRING statements in a REPORT structure; as a parameter of some Clarion procedures and functions; or, the parameter of STRING, CSTRING and PSTRING variable declarations.  There are seven types of picture tokens: numeric and currency, scientific notation, date, time, pattern, key-in template, and string.

Numeric and Currency Pictures

Scientific Notation Pictures

Date Pictures

Time Pictures

Pattern Pictures

Key-in Template Pictures

String Pictures


Numeric and Currency Pictures

@N [currency] [sign] [fill] size [grouping] [places] [sign] [currency] [B]

@N	All numeric and currency pictures begin with @N.

currency	Either a dollar sign ($) or a string constant enclosed in tildes (~).  When it precedes the sign indicator and there is no fill indicator, the currency symbol "floats" to the left of the high order digit.  If there is a fill indicator, the currency symbol remains fixed in the left-most position.  If the currency indicator follows the size and grouping, it appears at the end of the number displayed.

sign	Specifies the display format for negative numbers.  If a hyphen precedes the fill and size indicators, negative numbers will display with a leading minus sign.  If a hyphen follows the size, grouping, places, and currency indicators, negative numbers will display with a trailing minus sign.  If parentheses are placed in both positions, negative numbers will be displayed enclosed in parentheses.

fill	Specifies leading zeros, spaces, or asterisks (*) in any leading zero positions.  If the fill indicator is omitted, leading zeros are suppressed.

0 Produces leading zeroes and suppresses grouping

_ Produces leading spaces and suppresses grouping

* Produces leading asterisks and suppresses grouping

size	The size is required to specify the total number of significant digits to display, including the number of digits in the places indicator and any formatting characters.

grouping	A grouping symbol, other than a comma (the default), can be placed to the right of the size indicator to specify a three digit group separator.

. Produces periods	- Produces hyphens

_ Produces spaces

places	Specifies the decimal separator symbol and the number of decimal digits.  The number of decimal digits must be less than the size indicator.  The decimal separator may be a period (.), grave accent (`), or the letter "v" (used only for STRING field storage declarations not for display).

. Period produces a period as the decimal separator

` Grave accent produces a comma as the decimal separator (with periods for

 grouping separators, unless overridden)

v Produces no decimal separator (for STRING field storage only)

B	Specifies that the format displays as blank whenever its value is zero.

The numeric and currency pictures format numeric values for screen display or in reports.  If the value is greater than the maximum value the picture can display, a string of asterisks is displayed.

Example:

Numeric         Result	Format

@N9	   4,550,000	Nine digits, group with commas (default)

@N_9B	     4550000	Nine digits, no grouping, leading blanks if zero

@N09	   004550000	Nine digits, leading zero

@N*9	   ***45,000	Nine digits, asterisk fill, group with commas

@N9_	   4 550 000	Nine digits, group with spaces

@N9.	   4.550.000	Nine digits, group with periods

Decimal                  Result	Format

@N9.2	    4,550.75	Two decimal places, period decimal separator

@N_9.2B	     4550.75	Two decimal places, period decimal separator, no grouping, blank if zero

@N_9`2	     4550,75	Two decimal places, comma decimal separator

@N9.`2	    4.550,75	Comma decimal separator, group with periods

@N9_`2	    4 550,75	Comma decimal separator, group with spaces,

Signed                   Result 	Format

@N-9.2B	   -2,347.25	Leading minus sign, blank if zero

@N9.2-	    2,347.25-	Trailing minus sign

@N(10.2)	   (2,347.25)	Enclosed in parens when negative

Dollar Currency   Result       Format

@N$9.2B	   $2,347.25      Leading dollar sign, blank if zero

@N$10.2-	   $2,347.25-     Leading dollar sign, trailing minus when negative

@N$(11.2)	  $(2,347.25)     Leading dollar sign, in parens when negative

International Currency   Result 	Format

@N12_`2~ F~	     1 5430,50 F	France

@N~L. ~12`	          L.  1.430.050	Italy

@N~£~12.2	           £1,240.50	United Kingdom

@N~kr~12`2	          kr1.430,50	Norway

@N~DM~12`2	          DM1.430,50	Germany

@N12_`2~ mk~	            1 430,50 mk	Finland

@N12`2~ kr~	       1.430,50 kr	Sweden

Storage-Only Pictures:

Variable1	STRING(@N_6v2)	!Declare as 6 bytes stored without decimal

  CODE

  Variable1 = 1234.56	!Assign value, stores '123456' in file

  MESSAGE(FORMAT(Variable1,@N_7.2))	!Display with decimal point: '1234.56'


Scientific Notation Pictures

@Em.n[B]

@E	All scientific notation pictures begin with @E.

m	Determines the total number of characters in the format provided by the picture.

n	Indicates the number of digits that appear to the left of the decimal point.

B	Specifies that the format displays as blank when the value is zero.

The scientific notation picture formats very large or very small numbers.  The format is a decimal number raised by a power of ten.

Example:

Picture	Value	Result

@E9.0	 1,967,865	  .20e+007

@E12.1	 1,967,865	 1.9679e+006

@E12.1B	         	0

@E12.1	-1,967,865	-1.9679e+006

@E12.1	.000000032	 3.2000e-008


Date Pictures

@Dn[s][B]

@D	All date pictures begin with @D.

n	Determines the date picture format.  Date picture formats range from 1 through 16.

s	A separation character.  Slash ( / ) characters appear between the month, day, and year components of certain date picture formats.  Following are alternate separation characters.

.	Produces periods	`	(grave accent) produces commas

-	Produces hyphens	_	(underscore) produces spaces

B	Specifies that the format displays as blank when the value is zero.

Dates may be stored in numeric variables (usually LONG), a DATE field (for Btrieve compatibility), or in a STRING declared with a date picture.  A date stored in a numeric variable is called a "Clarion Standard Date."  The stored value is the number of days since December 28, 1800.  The date picture token converts the value into one of the 16 date formats.

Example:

Picture	Format	Result

@D1	mm/dd/yy	10/31/59

@D2	mm/dd/yyyy	10/31/1959

@D3	mmm dd, yyyy	OCT 31,1959

@D4	mmmmmmmmm dd, yyyy	October 31, 1959

@D5	dd/mm/yy	31/10/59

@D6	dd/mm/yyyy	31/10/1959

@D7	dd mmm yy	31 OCT 59

@D8	dd mmm yyyy	31 OCT 1959

@D9	yy/mm/dd	59/10/31

@D10	yyyy/mm/dd	1959/10/31

@D11	yymmdd	591031

@D12	yyyymmdd	19591031

@D13	mm/yy	10/59

@D14	mm/yyyy	10/1959

@D15	yy/mm	59/10

@D16	yyyy/mm	1959/10

 Alternate separators

@D1.	mm.dd.yy	Period separator

@D2-	mm-dd-yyyy	Dash separator

@D5_	dd mm yy	Underscore produces space separator

@D6`	dd,mm,yyyy	Grave accent produces comma separator


Time Pictures

@Tn[s][B]

@T	All time pictures begin with @T.

n	Determines the time picture format.  Time picture formats range from 1 through 6.

s	A separation character.  Colon ( : ) characters appear between the hour, minute, and second components of certain time picture formats.  The following s indicators provide an alternate separation character for these formats.

.	Produces periods	`	(grave accent) produces commas

-	Produces hyphens	_	(underscore) produces spaces

B	Specifies that the format displays as blank when the value is zero.

Times may be stored in a numeric variable (usually a LONG), a TIME field (for Btrieve compatibility), or in a STRING declared with a time picture.  A time stored in a numeric variable is called a "Standard Time."  The stored value is the number of hundredths of a second since midnight.  The picture token converts the value to one of the six time formats.

Example:

Picture	Format	Result

@T1	hh:mm	17:30

@T2	hhmm	1730

@T3	hh:mmXM	5:30PM

@T4	hh:mm:ss	17:30:00

@T5	hhmmss	173000

@T6	hh:mm:ssXM	5:30:00PM

 Alternate separators

@T1.	hh.mm	Period separator

@T1-	hh-mm	Dash separator

@T3_	hh mmXM	Underscore produces space separator

@T4`	hh,mm,ss	Grave accent produces comma separator


Pattern Pictures

@P[<][#][x]P[B]

@P	All pattern pictures begin with the @P delimiter and end with the P delimiter.  The case of the delimiters must be the same.

<	Specifies an integer position that is blank when zero.

#	Specifies an integer position.

x	Represents optional display characters.  These characters appear in the final result string.

P	All pattern pictures must end with P.  If a lower case @p delimiter is used, the ending P delimiter must also be lower case.

B	Specifies that the format displays as blank when the value is zero.

Pattern pictures contain optional integer positions and optional edit characters.  Any character other than < or # is considered an edit character which will appear in the formatted picture string.  The @P and P delimiters are case sensitive.  Therefore, an upper case "P" can be included as an edit character if the delimiters are both lower case "p" and vice versa.

Pattern pictures do not recognize decimal points, in order to permit the period to be used as an edit character.  Therefore, the value formatted by a pattern picture should be an integer.  If a floating piont value is formatted by a pattern picture, only the integer portion of the number will appear in the result.

Example:

Picture	      Value	Result

@P###-##-####P	    215846377	  215-84-6377

@P<#/##/##P	       103159	     10/31/59

@P(###)###-####P	   3057854555	(305)785-4555

@P###/###-####P	      7854555	 000/785-4555

@p<#:##PMp	             530	       5:30PM

@P<#' <#"P	             506	       5'  6"

@P<#lb. <#oz.P	          902	   9lb.  2oz.

@P4##A-#P	             112	       411A-2

@PA##.C#P	       312.45	       A31.C2


Key-in Template Pictures

@K[@][#][<][x][\][?][^][_][|]K[B]

@K	All key-in template pictures begin with the @K delimiter and end with the K delimiter.  The case of the delimiters must be the same.

@	Specifies only uppercase and lowercase alphabetic characters.

#	Specifies an integer 0 through 9.

<	Specifies an integer that is blank for high order zeros.

x	Represents optional constant display characters (any displayable character).  These characters appear in the final result string.

\	Indicates the following character is a display character.  This allows you to include any of the picture formatting characters (@,#,<,\,?,^,_,|) within the string as a display character.

?	Specifies any character may be placed in this position.

^	Specifies only uppercase alphabetic characters in this position.

_	Specifies only lowercase alphabetic characters in this position.

|	Allows the operator to "stop here" if there are no more characters to input.  Only the data entered and any display characters up to that point will be in the string result.

K	All key-in template pictures must end with K.  If a lower case @k delimiter is used, the ending K delimiter must also be lower case.

B	Specifies that the format displays as blank when the value is zero.

Key-in pictures may contain integer positions ( # < ), alphabet character positions ( @ ^ _ ), any character positions ( ? ), and display characters.  Any character other than a formatting indicator is considered a display character, which appears in the formatted picture string.  The @K and K delimiters are case sensitive.  Therefore, an upper case "K" may be included as a display character if the delimiters are both lower case "k" and vice versa.

Key-in pictures are used specifically with STRING, PSTRING, and CSTRING fields to allow custom field editing control and validation.  Using a key-in picture containing any of the alphabet indicators ( @ ^ _ ) on a numeric entry field produces unpredictable results.

Using the Insert typing mode for a key-in picture could produce unpredictable results.  Therefore, key-in pictures always receive data entry in Overwrite mode, even if the INS attribute is present.

Example:

Picture	Value Entered	Result String

@K###-##-####K	    215846377	  215-84-6377

@K#####|-####K	        33064	        33064

@K#####|-####K	    330643597	   33064-3597

@K<# ^^^ ##K	         10AUG59	    10 AUG 59

@K(###)@@@-##\@##K	   305abc4555	    (305)abc-45@55

@K###/?##-####K	      7854555	 000/785-4555

@k<#:##^Mk	            530P	       5:30PM

@K<#' <#"K	             506	       5'  6"

@K4#_#A-#K	            1g12	      41g1A-2


String Pictures

@Slength

@S	All string pictures begin with @S.

length	Determines the number of characters in the picture format.

A string picture describes an unformatted string of a specific length.

Example:

Name	STRING(@S20)	!A 20 character string field


Compiler Directives

EQUATE  (assign label)

SIZE  (memory size in bytes)


EQUATE  (assign label)

  label
label	EQUATE(	constant	)
 picture

EQUATE 	Assigns a label to another label or constant.

label	The label of any statement preceding the EQUATE statement.  This is used to declare an alternate statement label.

constant	A numeric or string constant.  This is used to declare a shorthand label for a constant value.  It also makes a constant easy to locate and change.

picture	A picture token.  This is used to declare a shorthand label for a picture token.  However, the screen and report formatter in the Clarion Editor will not recognize the equated label as a valid picture.

The EQUATE directive assigns a label to another label or constant.  It does not use any run-time memory.  The label of an EQUATE directive cannot be the same as its parameter.

Example:

Init	EQUATE(SetUpProg)	!Set alias label

Off	EQUATE(0)	!Off means zero

On	EQUATE(1)	!On means one

PI	EQUATE(3.1415927)	!The value of PI

EnterMsg	EQUATE('Press Ctrl-Enter to SAVE')

SocSecPic	EQUATE(@P###-##-####P)	!Soc-sec number picture

See Also:

Reserved Words


SIZE  (memory size in bytes)

 variable
SIZE(	 constant	)
 picture

SIZE 	Supplies the amount of memory used for storage.

variable	The label of a previously declared variable.

constant	A numeric or string constant.

picture	A picture token.

SIZE directs the compiler to supply the amount of memory (in bytes) used to store the variable, constant, or picture.

Example:

SavRec	STRING(1),DIM(SIZE(Cus:Record)	!Dimension the string to size of record

StringVar	STRING(SIZE('Clarion Software, Inc.'))

!A string long enough for the constant

LOOP I# = 1 TO SIZE(ParseString)	!Loop for number of bytes in the string

PicLen = SIZE(@P(###)###-####P)	!Save size of the picture


Introduction

The Language Reference Manual

Reference Item Format

Conventions and Symbols


The Language Reference Manual

Clarion for Windows is an integrated environment for writing data processing applications and management information systems for microcomputers using the Windows operating environment.  Clarion's programming language is the foundation of this environment.  In this reference,  the language is concisely documented in a modular fashion.  Although this is not a text book, you should consult this reference  first when you want to know the precise syntax required to implement any declaration, statement, or function.

As far as possible, real-world example code is provided for each item.


Reference Item Format

Each Clarion programming language element referenced in this reference is displayed in UPPER CASE letters.  Components of the language are documented with a syntax diagram, a detailed description, and source code examples.

Items are documented in logical groupings, dependent upon their hierarchical relationships. Therefore, the table of contents for this help system is not listed in alphabetical order.  In general, data types and structures occur at the beginning of a section, followed by their attributes, and executable statements and functions at the end.

The documentation format used in this reference is illustrated in the syntax diagram on the following page.

KEYWORD  (short description of intended use)

[label]	KEYWORD(	parameter1	 [parameter2]) [ATTRIBUTE1( )] [ATTRIBUTE2( )]
alternate
parameter
list

KEYWORD	A brief statement of what the KEYWORD does.

parameter1	A complete description of parameter1, along with how it relates to parameter2 and the KEYWORD.

parameter2	A complete description of parameter2, along with how it relates to parameter1 and the KEYWORD.  Because it is enclosed in brackets, [ ], it is optional, and may be omitted.

alternate

 parameter list	A complete description of alternates to parameter1, along with how they relate to parameter2 and the KEYWORD.

ATTRIBUTE1	A sentence describing the relation of ATTRIBUTE1 to the KEYWORD.

ATTRIBUTE2	A sentence describing the relation of ATTRIBUTE2 to the KEYWORD.

A concise description of what the KEYWORD does.  In many cases the KEYWORD will be an attribute of a keyword that was described in the preceding text.  Sometimes a KEYWORD has no parameters and/or attributes.

Events Generated:  If the KEYWORD generates events, they are listed here.

Return Data Type:  The data type returned if KEYWORD is a function.

Errors Posted:	If KEYWORD posts errors which may be trapped by the ERROR and ERRORCODE functions, they are listed here.

Example:

FieldOne = FieldTwo + FieldThree	!This is a source code example

FieldThree = KEYWORD(FieldOne,FieldTwo)	!Comments follow the "!" character

See Also:

ATTRIBUTE1

ATTRIBUTE2

other pertinent keywords


Conventions and Symbols

Symbols are used in the syntax diagram as follows:

 Symbol	Meaning

  [ ]	Brackets enclose an optional (not required) attribute or parameter.

  ( )	Parentheses enclose a parameter list.

   	Vertical lines enclose parameters, where one, but only one, of the parameters is allowed.

Coding example conventions used throughout this manual:

CLARION KEYWORDS	All caps

DataNames	Mixed case with caps used for readability

Comments	Predominantly lower case

The purpose of these conventions is to make the code examples readable and clear.


ATTRIBUTE1

Clicking here takes you to the appropriate topic


ATTRIBUTE2

Clicking here takes you to the appropriate topic.


Program Source Code Format

Statement Format

Declaration and Statement Labels

Structure Termination

Reserved Words

Special Characters

Program Format

PROGRAM  (declare a program)

MEMBER  (identify member source file)

MAP  (declare PROCEDURE and/or FUNCTION prototypes)

MODULE  (specify MEMBER source file)

PROCEDURE  (declare a procedure)

FUNCTION  (declare a function)

CODE  (begin executable statements)

ROUTINE  (declare local subroutine)

END  (terminate a structure)

Statement Execution Sequence

PROCEDURE and FUNCTION Calls

Prototyping Procedures

FUNCTION and PROCEDURE Prototypes

FUNCTION Return Types

Parameter Passing

Passing Parameters of Unspecified Data Type

Passing Arrays as Parameters

Program Structure Compiler Directives

BEGIN  (define code structure)

COMPILE  (specify source to be compiled)

EJECT  (start new listing page)

EMBED  (embedded source code section)

INCLUDE  (compile code in another file)

OMIT  (specify source not to be compiled)

SECTION  (specify source code section)

SUBTITLE  (print MODULE subtitle)

TITLE  (print MODULE title)


Statement Format

Clarion is a "statement oriented" language.  A statement oriented language makes use of the fact that its source code is contained in ASCII text files so every line of code is a separate record in the file.  Therefore, the Carriage Return/Line Feed record delimiter can be used to eliminate punctuation.

In general, Clarion statement format is:

label	STATEMENT[(parameters)] [,ATTRIBUTE[(parameters)]] ...

Attributes specify the properties of the item and are only used on data declarations.  Executable statements take the form of a standard procedure call, except assignment statements (A = B) and control structures (such as IF, CASE, and LOOP).

A statement's label must begin in column one (1) of the source code.  A statement without a label must not start in column one.  A statement is terminated by the end of the line.  A statement too long to fit on one line can be continued by a vertical bar ( | ).  The semi-colon is an optional statement separator that allows you to place more than one statement on a line.

Being a statement oriented language eliminates from Clarion much of the punctuation required in other languages to identify labels and separate statements.  Blocks of statements are initiated by a single compound statement, and are terminated by an END statement (or period).

Declaration and Statement Labels

Structure Termination

Reserved Words

Special Characters


Declaration and Statement Labels

The language statements in a source module can be divided into two general categories: data declarations and executable statements, or simply "data" and "code."

During program execution, data declarations reserve memory storage areas that are manipulated by executable statements.  A label is required for the data to be referenced in executable code.  All variables, data structures, PROCEDUREs, FUNCTIONs, and ROUTINEs are referenced by labels.

A label defines a specific location in a PROGRAM.  Any code statement may be identified and referenced by a label.  This allows it to be used as the target of a GOTO statement.

The label on a PROCEDURE or FUNCTION statement is the procedure or function's name.  Using the label of a PROCEDURE in an executable statement executes the procedure.  The label of a FUNCTION is used in expressions, or parameter lists of other functions, to assign the value returned by the function.

The rules for valid Clarion labels are:

     _	A label MUST begin in column one (1) of the source code.

     _	A label may contain letters (upper or lower case), numerals 0 through 9, the underscore character (_), and colon (:).

     _	The first character must be a letter or the underscore character.

     _	Labels are not case sensitive (i.e. CurRent and CURRENT are the same).

     _	A label may not be a reserved word.


Structure Termination

Compound data structures are created when data declarations are nested within other data declarations.  There are many compound data structures within the Clarion language: APPLICATION, WINDOW, REPORT, FILE, RECORD, GROUP, VIEW, etc.  These compound data structures must be terminated by a period (.) or the keyword END.  IF, CASE, EXECUTE, LOOP, BEGIN, and ACCEPT are all executable control structures which must also be terminated with a period or END statement.


Reserved Words

The following keywords are reserved and may not be used as labels:

ACCEPT	AND	BEGIN
BREAK	BY	CASE
COMPILE	CYCLE	DO
EJECT	ELSE	ELSIF
EMBED	END	ENDEMBED
EXECUTE	EXIT	FUNCTION
GOTO	IF	INCLUDE
LOOP	MEMBER	NOT
OF	OMIT	OR
OROF	PROCEDURE	PROGRAM
RETURN	ROUTINE	SECTION
THEN	TIMES	TO
UNTIL	WHILE	XOR
The following keywords may be used as labels of data structures or executable statements.  They may not be used as labels of PROCEDURE or FUNCTION statements:

APPLICATION	CODE	DETAIL
FILE	FOOTER	FORM
GROUP	HEADER	ITEM
MAP	MENU	MENUBAR
MODULE	OPTION	QUEUE
RECORD	REPORT	SUBTITLE
TITLE	TOOLBAR	VIEW
WINDOW


Special Characters

Initiators

!	Exclamation point begins a source code comment.

?	Question mark begins a field equate label.

@	"At" sign begins a picture token.

*	Asterisk begins a parameter passed by address in a MAP prototype.

Terminators	;	Semi-colon is an executable statement separator.

CR/LF	Carriage-return/Line-feed is an executable statement separator.

.	Period terminates a structure.

|	Vertical bar is the source code line continuation character.

#	Pound sign declares an implicit LONG variable.

$	Dollar sign declares an implicit REAL variable.

"	Double quote declares an implicit STRING variable.

Delimiters	( )	Parentheses enclose a parameter list.

[ ]	Brackets enclose an array subscript list.

' '	Single quotes enclose a string constant.

{ }	Curly braces enclose a repeat count in a string constant, or a control field property parameter to a field equate label in an assignment statement.

< >	Angle brackets enclose an ASCII code in a string constant, or indicate a parameter in a MAP prototype which may be omitted.

:	Colon separates the start and stop positions of a string "slice."

Connecters	.	Period is a decimal point used in numeric constants.

,	Comma connects parameters in a parameter list.

:	Colon connects a prefix to a label or character groups within a label.

$	Dollar sign connects the window to a field equate label in a control property assignment statement.

_	Underscore connects character groups within a label.

Operators	+	Plus sign indicates addition.

-	Minus sign indicates subtraction.

*	Asterisk indicates multiplication.

/	Slash indicates division.

%	Percent sign indicates modulus division.

^	Carat indicates exponentiation.

<	Left angle bracket indicates less than.

>	Right angle bracket indicates greater than.

=	Equal sign indicates assignment or equivalence.

~	Tilde indicates the logical "NOT" operator.

&	Ampersand indicates concatenation.


Program Format

PROGRAM  (declare a program)

MEMBER  (identify member source file)

MAP  (declare PROCEDURE and/or FUNCTION prototypes)

MODULE  (specify MEMBER source file)

PROCEDURE  (declare a procedure)

FUNCTION  (declare a function)

CODE  (begin executable statements)

ROUTINE  (declare local subroutine)

END  (terminate a structure)

Statement Execution Sequence

PROCEDURE and FUNCTION Calls


PROGRAM  (declare a program)

PROGRAM
[MAP
prototypes
 END ]
global data
CODE
statements
[RETURN]
procedures or functions

PROGRAM	The first declaration in a Clarion program source module.  Required.

MAP	Global procedure and function declarations.

prototypes	Declare a PROCEDURE or FUNCTION.

global data 	Declare Global data which may be referenced by all procedures and functions.

CODE	Begin executable statements.

statements	Executable program instructions.

RETURN	Terminate program execution.  Return to operating system control.

procedures or

 functions	Source code for the procedures and functions in the PROGRAM module.

The PROGRAM statement is required to be the first declaration in a Clarion program source module.  It may only be preceded by source code comments or a TITLE or SUBTITLE compiler directive.  The PROGRAM source file name is used as the object (.OBJ) and executable (.EXE) file name, when compiled.  The PROGRAM statement may have a label, but the label is ignored by the compiler.

A PROGRAM with PROCEDUREs and/or FUNCTIONs must have a MAP structure.  The MAP declares the PROCEDURE and/or FUNCTION prototypes.  Any PROCEDURE or FUNCTION contained in a separate source file must be declared in a MODULE structure within the MAP.

Data declared in the PROGRAM module, between the keywords PROGRAM and CODE, is Global data that may be accessed by any PROCEDURE or FUNCTION in the PROGRAM.  Its memory allocation is Static.

Example:

             PROGRAM                         !Sample program declaration

Fahrenheit   REAL(0)                         !Global data declarations

Centigrade   REAL(0)

Window 	WINDOW('Temperature Conversion'),CENTER,SYSTEM

  STRING('Enter Fahrenheit Temperature: '),AT(34,50,101,10)

  ENTRY(@N04),AT(138,49,60,12),USE(Fahrenheit)

  STRING('Centigrade Temperature:'),AT(34,71,80,10),LEFT

  ENTRY(@N04),AT(138,70,60,12),USE(Centigrade),SKIP

  BUTTON('Another'),AT(34,92,32,16),USE(?Another)

  BUTTON('Exit'),AT(138,92,32,16),USE(?Exit)

END

  CODE                                       !Begin executable code section

  OPEN(Window)

  ACCEPT

    CASE ACCEPTED()

    OF ?Fahrenheit

      Centigrade = (Fahrenheit - 32) / 1.8

      DISPLAY(?Centigrade)

    OF ?Another

      Fahrenheit = 0

      Centigrade = 0

      SELECT(?Fahrenheit)

    OF ?Exit

      BREAK

    END

  END

  RETURN

See Also:

MAP

MODULE

PROCEDURE

Data Declarations amd Memory Allocation


MEMBER  (identify member source file)

MEMBER(program)
[MAP
prototypes
 END ]
[label]	local data
procedures or functions

MEMBER	The first statement in a source module that is not a PROGRAM source file.  Required.

program	A string constant containing the filename (without extension) of a PROGRAM source file.  This parameter is required.

MAP	Local procedure and function declarations.  Any procedures or functions declared here may be referenced only by the procedures or functions in the MEMBER module.

prototypes	Declare a PROCEDURE or FUNCTION.

local data 	Declare Local Static data which may be referenced only by the procedures and functions whose source code is in the MEMBER module.

procedures or

 functions	Source code for the procedures and functions in the MEMBER module.

MEMBER is the first statement required to be in a source module that is not a PROGRAM source file.  It may only be preceded by source code comments or a TITLE or SUBTITLE compiler directive.  It is required at the beginning of any source file that contains PROCEDUREs or FUNCTIONs that are used by a PROGRAM.  The MEMBER statement identifies the program to which the source MODULE belongs.

A MEMBER module may have a local MAP structure.  Procedures and functions declared in this MAP are visible only to the other procedures and functions in the MEMBER module.  The source code for the procedures and functions declared in this MEMBER MAP may be contained in the MEMBER source file, or another file.  If the source code for the PROCEDURE or FUNCTION declared in a MEMBER MAP is contained in a separate file, the PROCEDURE or FUNCTION's prototype must be declared in a MODULE structure within the MEMBER MAP.  That separate source file MEMBER MODULE must also contain its own MAP which declares the same prototype for that PROCEDURE or FUNCTION.  Any PROCEDURE or FUNCTION not declared in the Global (PROGRAM) MAP must be declared in a local MAP in the MEMBER MODULE which contains its source code.

Data declared in the MEMBER module, after the keyword MEMBER and before the first PROCEDURE or FUNCTION statement, is Member Local data that may only be accessed by PROCEDUREs or FUNCTIONs within the module (unless passed as a parameter).  Its memory allocation is Static.

Example:

MEMBER('OrderSys')	!Module belongs to the OrderSys program

MAP	!Declare local procedures

  Func1(STRING),STRING	!Func1 is known only in this module

END

LocalData	STRING(10)	!Declare data local to MEMBER module

HistOrd	PROCEDURE	!Declare order history procedure

HistData	STRING(10)	!Declare data local to PROCEDURE

  CODE

  LocalData = Func1(HistData)

HistOrd2	PROCEDURE	!Declare second order history procedure

  CODE

  LocalData = Func1(LocalData)

Func1	FUNCTION(RecField)

  CODE

    !Executable code statements

See Also:

MODULE

PROCEDURE

FUNCTION

Data Declarations and Memory Allocation


MAP  (declare PROCEDURE and/or FUNCTION prototypes)

MAP
  prototypes
  [MODULE( )
    prototypes
   END ]
END

MAP	Contains the prototypes which declare the functions, procedures and external source modules used in a PROGRAM or MEMBER module.

prototypes	Declare a PROCEDURE or FUNCTION.

MODULE	Declare a member source module.

A MAP structure contains the prototypes which declare the functions, procedures and external source modules used in a PROGRAM or MEMBER module.  A MAP declared in the PROGRAM source module declares PROCEDUREs or FUNCTIONs that are available throughout the program.  A MAP in a MEMBER module declares PROCEDUREs or FUNCTIONs that are available in that MEMBER module only.

The BUILTINS.CLW file is automatically included in your PROGRAM MAP structure by the compiler.  This file contains prototypes of procedures and functions in the Clarion internal library that are available as part of the Clarion language, but the compiler does not have their prototypes built into it.

Example:

One file contains:

PROGRAM	!Sample program in sample.cla

MAP	!Begin map declaration

  LoadIt	!  LoadIt procedure

END	!End of map

A separate file contains:

MEMBER('Sample')	!Declare MEMBER module

MAP	!Begin local map declaration

  ComputeIt	!  compute it procedure

END	!End of map

See Also:

PROGRAM

MEMBER

MODULE

FUNCTION and PROCEDURE Prototypes


MODULE  (specify MEMBER source file)

MODULE(sourcefile)
  procedure prototype
  function prototype
END

MODULE	Names a MEMBER module or external library file.

sourcefile	A string constant.  If the sourcefile contains Clarion language source code, this specifies the filename (without extension) of the source file which contains the PROCEDUREs and/or FUNCTIONs.  If the sourcefile is an external library, this string may contain any unique identifier.

procedure

 prototype	The prototype of a PROCEDURE contained in the sourcefile.

function

 prototype	The prototype of a FUNCTION contained in the sourcefile.

A MODULE structure names a MEMBER module or external library file.  It contains the prototypes for the PROCEDUREs and FUNCTIONs contained in the sourcefile.  A MODULE structure can only be declared within a MAP structure.

Example:

The "sample.cla" file contains:

PROGRAM	!Sample program in sample.cla

MAP	!Begin map declaration

  MODULE('Loadit')	!  source module loadit.cla

    LoadIt	!    load it procedure

  END	!  end module

  MODULE('Compute')	!  source module compute.cla

    ComputeIt	!    compute it procedure

  END	!  end module

END	!End map

The "loadit.cla" file contains:

MEMBER('Sample')	!Declare MEMBER module

MAP	!Begin local map declaration

  MODULE('Process')	!  source module process.cla

    ProcessIt	!    process it procedure

  END	!  end module

END	!End map

See Also:

MEMBER

MAP

FUNCTION and PROCEDURE Prototypes


PROCEDURE  (declare a procedure)

label	PROCEDURE [(parameter list)]
local data
CODE
statements
[RETURN]

PROCEDURE	Begins a section of source code that can be executed from within a PROGRAM.

label	Names the PROCEDURE.

parameter list	An optional list of variables which pass values to the PROCEDURE.  This list defines the name of each parameter as used within the PROCEDURE's source code.  Each parameter is separated by a comma.  The data type of each parameter is specified in the procedure's prototype in the MAP structure.

local data 	Declare Local data which may be referenced only by this procedure.

CODE	Begin executable statements.

statements	Executable program instructions.

RETURN	Terminate procedure execution.  Return to the point from which the procedure was called.

PROCEDURE begins a section of source code that can be executed from within a PROGRAM.  It is called by naming the PROCEDURE label (with its parameter list, if any) as an executable statement in the code section of a PROGRAM, PROCEDURE, or FUNCTION.

A PROCEDURE terminates and returns to its caller when a RETURN statement is executed.  An implicit RETURN occurs at the end of the executable code.  The end of executable code for the PROCEDURE is defined as the end of the source file, or the first encounter of a FUNCTION, ROUTINE, or another PROCEDURE.

Data declared within a PROCEDURE, between the keywords PROCEDURE and CODE, is Procedure Local data that can only be accessed by that PROCEDURE (unless passed as a parameter to another PROCEDURE or FUNCTION).  This data is allocated memory on the stack upon entering the procedure, and de-allocated when it terminates.

A PROCEDURE must be declared in the MAP of a PROGRAM or MEMBER module.  If declared in the PROGRAM MAP, it is available to any other procedure or function in the program.  If declared in a MEMBER MAP, it is only available to other procedures or functions in that MEMBER module.

Example:

PROGRAM	!Example program code

MAP

  OpenFile(FILE)	!Procedure prototype with parameter

  ShoTime	!Procedure prototype without parameter

END

  CODE

  OpenFile(FileOne)	!Call procedure to open file

  ShoTime	!Call ShoTime procedure

  :	!More executable statements

OpenFile	PROCEDURE(AnyFile)	!Open any file

  CODE	!Begin code section

  OPEN(AnyFile)	!Open the file

  IF ERRORCODE() = 2	!If file not found

    CREATE(AnyFile)	!  create it

  END	!End if

  RETURN	!Return to caller

ShoTime	PROCEDURE	!Show time

Time	LONG	!Local variable

Window	WINDOW,CENTER

  STRING(@T3),USE(Time),AT(34,70)

  BUTTON('Exit'),AT(138,92,32,16),USE(?Exit)

END

  CODE 	!Begin executable code section

  Time = CLOCK()	!Get time from system

  OPEN(Window)

  ACCEPT

    CASE ACCEPTED()

    OF ?Exit

      BREAK

    END

  END

  RETURN	!Return to caller

See Also:

FUNCTION and PROCEDURE Prototypes

Data Declarations amd Memory Allocation


FUNCTION  (declare a function)

label	FUNCTION [(parameter list)]
local data
CODE
statements
RETURN(value)

FUNCTION	Begins a section of source code that can be executed executed from within a PROGRAM.

label	Names the FUNCTION.

parameter list	An optional list of variables which pass values to the FUNCTION.  This list defines the name of each parameter as used within the FUNCTION's source code.  Each parameter is separated by a comma.  The data type of each parameter is specified in the procedure's prototype in the MAP structure.

local data 	Declare Local data which may be referenced only by this function.

CODE	Begin executable statements.

statements	Executable program instructions.

RETURN	Terminate function execution and return the value to the expression in which the function was used.

value	A numeric or string constant or variable which specifies the result of the function call.

FUNCTION begins a section of source code that can be executed by naming the FUNCTION label with its parameter list (empty parentheses are required if no parameters are passed).  FUNCTION execution is terminated by a RETURN statement in its CODE section (required).

A function can be used as an expression component, or a parameter of a PROCEDURE or another FUNCTION.  A FUNCTION may also be called in the same manner as a PROCEDURE, if the program logic does not require the RETURN value.  In this case, the compiler will generate a warning which may be safely ignored.

Data declared within a FUNCTION, between the keywords FUNCTION and CODE, is Procedure Local data that can only be accessed by that FUNCTION (unless passed as a parameter to another PROCEDURE or FUNCTION).  This data is allocated memory on the stack upon entering the function, and de-allocated when it terminates.

A FUNCTION must be declared in the MAP of a PROGRAM or MEMBER module.  If declared in the PROGRAM MAP, it is available to any other procedure or function in the program.  If declared in a MEMBER MAP, it is only available to other procedures or functions in the MEMBER module.

Example:

PROGRAM

MAP

  NewThread	!A procedure

  FullName(STRING,STRING,STRING),STRING

!Function prototype with parameters

  DayString,STRING	!Function prototype without parameters

END

TodayString	STRING(9)

  CODE

  TodayString = DayString()	!Function call without parameters

! the () is required for a function

    :	!Global executable statements

    :

  START(NewThread)	!Clarion START function called as a

! procedure -- generates compiler warning

! but executes correctly

FullName	FUNCTION(Last,First,Init)	!Full name function

  CODE	!Begin executable code section

  IF Init = ''	!If no middle initial

    RETURN(CLIP(First) & ' ' & Last)	!  return full name

  ELSE	!Otherwise

    RETURN(CLIP(First) & ' ' & Init & '. ' & Last)

!  return full name

  END	!End if

DayString	FUNCTION	!Day string function

  CODE	!Begin executable code section

  Day# = (TODAY() % 7) + 1	!Find day of week from system date

  EXECUTE Day#	!Execute, return day string

    RETURN('Sunday')

    RETURN('Monday')

    RETURN('Tuesday')

    RETURN('Wednesday')

    RETURN('Thursday')

    RETURN('Friday')

    RETURN('Saturday')

  END	!END execute structure

See Also:

FUNCTION and PROCEDURE Prototypes


CODE  (begin executable statements)

CODE

The CODE statement separates the data declaration section from the executable statement section within a PROGRAM, PROCEDURE, or FUNCTION.  The first statement executed in a PROGRAM, PROCEDURE or FUNCTION is the statement following CODE.

Example:

OrdList	PROCEDURE	!Declare a procedure

!Data declarations go here

  CODE	!This is the beginning of the "code" section

!Executable statements go here

See Also:

PROGRAM

PROCEDURE

FUNCTION


ROUTINE  (declare local subroutine)

label	ROUTINE

ROUTINE	Declares the beginning of a local subroutine of executable statements.

label	The name of the ROUTINE.

ROUTINE declares the beginning of a local subroutine of executable statements.  It is local to the PROCEDURE or FUNCTION in which it is written and must be at the end of the CODE section of the PROCEDURE or FUNCTION to which it belongs.  All variables visible to the PROCEDURE or FUNCTION are available in the ROUTINE.  This includes all Procedure Local, Module Local, and Global data.

A ROUTINE is called by the DO statement followed by the label of the ROUTINE.  Program control following execution of a ROUTINE is returned to the statement following the calling DO statement.  A ROUTINE is terminated by the end of the source module, or by another ROUTINE, PROCEDURE, or FUNCTION.  The EXIT statement can also be used to terminate execution of a ROUTINE's code (similar to RETURN in a PROCEDURE).

Example:

SomeProc	PROCEDURE

  CODE

!Code statements

  DO Tally	!Call the routine

!More code statements

Tally	ROUTINE	!Begin routine, end procedure

  IF CountVar < 55	!If less than 55

    CountVar += 1 	!  increment counter

  ELSE	! otherwise

    CountVar = 0	!  reset counter

    EXIT	!  exit the routine

  END	!End if

See Also:

EXIT

DO


END  (terminate a structure)

END

END terminates a data declaration structure or a compound executable statement.  It is functionally equivalent to a period (.).

Example:

Customer	FILE,DRIVER('Clarion')	!Declare a file

  RECORD	!  begin record declaration

Name	    STRING(20)

Number	    LONG

  END	!  end record declaration

END	!End file declaration

  CODE

  IF Number <> SavNumber	!Begin if structure

    DO GetNumber

  END	!End if structure

  CASE Action	!Begin case structure

  OF 1

    DO AddRec

  OF 2

    DO ChgRec

  OF 3

    DO DelRec

  END	!End case structure


Statement Execution Sequence

In the CODE section of a Clarion program, statements are normally executed line-by-line, in the sequence in which they appear in the source module.  Control statements, procedure calls, and function calls, are used to modify this execution sequence.

PROCEDURE calls modify the execution sequence by branching to the called procedure and executing the code contained in it.  Control returns to the executable statement following the procedure call when a RETURN statement is executed in the called procedure, or there are no more statements in the called procedure to execute.

FUNCTION calls modify the execution sequence by branching to the called function and executing the code contained in it.  Control returns to the executable statement containing the function call when a RETURN statement is executed in the called function, returning the value of the function.

Control structures IF, CASE, LOOP, and EXECUTE change the execution sequence by evaluating expressions.  When the expression is evaluated, the control structure conditionally executes statements contained within the structure.

Branching also occurs with the GOTO, DO, CYCLE, BREAK, EXIT, RETURN, and RESTART statements.  These statements immediately and unconditionally alter the normal execution sequence.

The START function begins a new execution thread, unconditionally branching to that thread.  However, the user may choose to activate another thread by clicking the mouse on the other thread's active window.

Example:

PROGRAM

MAP

  ComputeTime(*GROUP)	!Passing a group parameter

  MatchMaster	!Passing no parameters

END

ParmGroup	GROUP	!Declare a group

FieldOne	  STRING(10)

FieldTwo	  LONG

END

  CODE	!Begin executable code

  FieldTwo = CLOCK()	!Executes 1st

  ComputeTime(ParmGroup)    	!Executes 2nd, passes control to procedure

  MatchMaster      	!Executes after procedure executes fully


PROCEDURE and FUNCTION Calls

procname[(parameters)]

procname	The name of the PROCEDURE or FUNCTION as declared in the procedure's prototype in the MAP.  If this is not the label of a PROCEDURE statement, compiler errors are issued.

parameters	An optional parameter list passed to the PROCEDURE or FUNCTION.  A parameter list may be one or more variable labels or expressions.  The parameters are separated by commas and are declared in the prototype in the MAP.

A PROCEDURE is called by its label (including any parameter list) as a statement in the CODE section of a PROGRAM, PROCEDURE, or FUNCTION.  The parameter list must match the parameter list declared in the procedure's prototype in the MAP.  Procedures cannot be called in expressions.

A FUNCTION is called by its label (including any parameter list) as a component of an expression or parameter list passed to another PROCEDURE or FUNCTION.  The parameter list must match the parameter list declared in the function's prototype in the MAP.

A FUNCTION may also be called by its label (including any parameter list), in the same manner as a PROCEDURE, if its return value is not needed.  This will generate a compiler warning that can be safely ignored.

Example:

PROGRAM

MAP

  ComputeTime(*GROUP)	!Passing a group parameter

  MatchMaster,BYTE	!FUNCTION passing no parameters

END

ParmGroup	GROUP	!Declare a group

FieldOne	STRING(10)

FieldTwo	LONG

END

  CODE

  FieldTwo = CLOCK()	!Built-in function called as expression

  ComputeTime(ParmGroup)	!Call the compute time procedure

  MatchMaster()	!Call the function as a procedure

See Also:

FUNCTION and PROCEDURE Prototypes


Prototyping Procedures

FUNCTION and PROCEDURE Prototypes

FUNCTION Return Types

Parameter Passing

Passing Parameters of Unspecified Data Type

Passing Arrays as Parameters


FUNCTION and PROCEDURE Prototypes

name[(parameter list)] [,return type] [,calling convention] [, RAW] [, NAME( )] [, TYPE]

name	The label of a PROCEDURE or FUNCTION statement.

parameter list	The data types of the parameters passed to the PROCEDURE or FUNCTION.

return type	The data type the FUNCTION will RETURN.

calling

 convention	Specify the C or PASCAL stack-based parameter calling convention.

RAW	Specifies that STRING or GROUP parameters pass the memory address only.

NAME	Specify an alternate, "external" name for the PROCEDURE or FUNCTION.

TYPE	Specify the prototype is a type definition for procedures passed as parameters.

All PROCEDUREs and FUNCTIONs in a PROGRAM must be declared as a prototype in a MAP.  A prototype is defined as the name of the PROCEDURE or FUNCTION, an optional parameter list, and the data type returned (if prototyping a FUNCTION).  You may specify the C or PASCAL, stack-based parameter calling convention, if you are linking in objects that require them (such as objects that were not compiled with a Clarion TopSpeed compiler).  An external NAME may also be specified.

The optional parameter list is a list of the data types that are passed to the PROCEDURE or FUNCTION, separated by commas and enclosed in parentheses.  Any parameter that may be omitted when the PROCEDURE or FUNCTION is called must be included in the prototype parameter list and enclosed in angle brackets ( < > ).  The OMITTED function allows you to test for unpassed paramters at runtime.

You can optionally specify the C (right to left) or PASCAL (left to right) stack-based parameter calling conventions for your PROCEDURE or FUNCTION.  This provides compatibility with third-party libraries written in other languages (if they were not compiled with a TopSpeed compiler).  If you do not specify a calling convention, the default is internal, register-based convention used by all TopSpeed compilers.

The RAW attribute allows you to pass just the memory address of a STRING or GROUP, whether passed by value or by reference, to a non-Clarion language procedure or function.  Normally, STRING or GROUP parameters pass the address and the length of the string.  The RAW attribute eliminates the length portion.  This is provided for compatibility with external library functions which expect only the address of the string.

The NAME attribute provides the linker an external name for the PROCEDURE or FUNCTION.  This is also provided for compatibility with libraries written in other languages.  For example: in some C language compilers, with the C calling convention specified, the compiler adds a leading underscore to the function name.  The NAME attribute allows the linker to resolve the name of the function correctly.

The TYPE attribute indicates the prototype does not reference a specific PROCEDURE or FUNCTION.  Instead, it defines a prototype name used in other prototypes to indicate the type of procedure passed to another PROCEDURE or FUNCTION as a parameter.  When the name of a prototype is used in the parameter list of another prototype, it indicates the procedure being prototyped will receive the label of a PROCEDURE or FUNCTION that receives the same parameter list (and has the same return type, if it is a FUNCTION).  A prototype with the TYPE attribute may not also have the NAME attribute.


FUNCTION Return Types

A FUNCTION must RETURN a value.  The data type to be returned is listed, separated by a comma, after the optional parameter list.  Valid RETURN types are:

   BYTE  SHORT  USHORT  LONG  ULONG  SREAL  REAL  DATE  TIME  STRING  CSTRING

   *BYTE *SHORT *USHORT *LONG *ULONG *SREAL *REAL *DATE *TIME *CSTRING

   Untyped value-parameter return value (?)

An untyped value-parameter return value (?) indicates the data type of the value returned by the FUNCTION is not known.  This functions in exactly the same manner as an untyped value-parameter.  When the value is returned from the FUNCTION, standard Clarion Data Conversion Rules apply, no matter what data type is returned.

Functions which return pointers (the address of some data) should be prototyped with an asterisk prepended to the return data type.  This is provided just for compatibility with external library functions (written in another language) which return only the address of data.  The compiler automatically handles the returned pointer at runtime.  Functions prototyped this way act just like a variable defined in the program when the function is used in Clarion code, the data referenced by the returned pointer is automatically used.  This data can be assigned to other variables, passed as parameters to procedures or functions, or the ADDRESS function may return the address of the data.

As an example of this, assume that the XYZ() function returns *CSTRING (pointer to a CSTRING), CStringVar is a CSTRING variable, and LongVar is a LONG variable.  The simple Clarion assignment statement, CStringVar = XYZ(), places the data referenced by the XYZ() function's returned pointer, in the CStringVar variable.  The assignment, LongVar = ADDRESS(XYZ()), places the memory address of that data in the LongVar variable.


Parameter Passing

There are four types of parameters that may be passed to a PROCEDURE or FUNCTION:  value-parameters, variable-parameters, entity-parameters, and procedure-parameters.

Value-parameters are "passed by value."  A copy of the variable passed in the parameter list of the "calling" PROCEDURE or FUNCTION is used in the "called" PROCEDURE or FUNCTION.  The "called" PROCEDURE or FUNCTION cannot change the value of the variable passed to it by the "caller."  Value-parameters are listed by data type in the PROCEDURE or FUNCTION prototype in the MAP.  Valid value-parameters are:

   BYTE  SHORT  USHORT  LONG  ULONG  SREAL  REAL  BFLOAT  DATE  TIME  STRING

Variable-parameters are "passed by address."  A variable passed by address has only one memory address.  Changing the value of the variable in the "called" PROCEDURE or FUNCTION also changes its value in the "caller."  Variable-parameters are listed by data type with a leading asterisk (*) in the PROCEDURE or FUNCTION prototype in the MAP.  Valid variable-parameters are:

   *BYTE  *SHORT  *USHORT  *LONG  *ULONG  *SREAL  *REAL  *BFLOAT  *DECIMAL

   *PDECIMAL  *DATE  *TIME  *STRING  *PSTRING  *CSTRING  *GROUP

Entity-parameters pass the name of a data structure to the "called" PROCEDURE or FUNCTION.  Passing the entity allows the "called" PROCEDURE or FUNCTION to use those Clarion commands that require the label of the structure as a parameter.  Entity-parameters are listed by entity type in the PROCEDURE or FUNCTION prototype in the MAP.  Entity-parameters are always "passed by address."  Valid entity-parameters are:

   FILE  VIEW  KEY  INDEX  QUEUE  APPLICATION  WINDOW  REPORT

Procedure-parameters pass the name of another PROCEDURE or FUNCTION to the "called" PROCEDURE or FUNCTION.  Procedure-parameters are listed by the name of a preceding prototype of the same type in the PROCEDURE or FUNCTION prototype in the MAP (which may or may not have the TYPE attribute).  When called in executable code, the "called" PROCEDURE or FUNCTION must be passed the name of a PROCEDURE or FUNCTION whose prototype is exactly the same as the procedure named in the "called" procedure's prototype.

Example:

MAP

  MODULE('Test')	!'test.cla' contains these procedure & functions

    MyProc1(LONG)	!LONG value-parameter

    MyProc2(<*LONG>)	!Omittable LONG variable-parameter

    MyFunc1(*SREAL),REAL,C	!SREAL variable-parameter, REAL return, C call conv

    MyFunc2(FILE),STRING	!FILE entity-parameter, returning a STRING

    ProcType(FILE),TYPE	!Procedure-parameter type definition

    MyFunc3(ProcType),STRING	!ProcType procedure-parameter, returning a STRING,

!  must be passed a procedure that takes a FILE

!  as a parameter

  END

  MODULE('Party3.Obj')	!A third-party library

    Func46(*CSTRING),REAL,C,RAW 	!Pass CSTRING address-only to C function

    Func47(*CSTRING),*CSTRING,C,RAW	!Returns pointer to a CSTRING

    Func48(REAL),REAL,PASCAL	!PASCAL calling convention

    Func49(SREAL),REAL,C,NAME('_func49')  !C convention and external function name

  END

END

See Also:

MAP

MEMBER

MODULE

NAME

RETURN


Passing Parameters of Unspecified Data Type

The desire to write general purpose functions which perform some operation on a passed parameter, where the exact data type of the parameter may vary from one call to the next, is fairly common.  Therefore, the function's prototype must indicate that the data type of the parameter is unknown at compile time.  The Clarion language allows for this with untyped value-parameters and untyped variable-parameters.  These are polymorphic parameters; they may become any other data type depending upon the data type passed to the procedure or function.

Untyped value-parameters are represented in the PROCEDURE or FUNCTION prototype with a question mark (?).  When the procedure executes, the parameter is dynamically typed and acts as a data object of the base type (LONG, STRING, or REAL) of the passed variable, or the base type of whatever it was last assigned.  This means that the "assumed" data type of the parameter can change within the PROCEDURE or FUNCTION, allowing it to be treated as any data type.

An untyped value-parameter is "passed by value" to the PROCEDURE or FUNCTION and its assumed data type is handled by Clarion's automatic Data Conversion Rules.  Any changes made to the passed parameter within the PROCEDURE or FUNCTION do not affect the variable which was passed in.

Data types which may be passed as untyped value-parameters:

   BYTE  SHORT  USHORT  LONG  ULONG  SREAL  REAL  BFLOAT  DECIMAL  PDECIMAL

   DATE  TIME   STRING  PSTRING  CSTRING  GROUP-(treated as a STRING)

   Untyped value-parameter (?)    Untyped Variable-parameter (*?)

Untyped variable-parameters are represented in the PROCEDURE or FUNCTION prototype with an asterisk and a question mark (*?).  Inside the procedure, the parameter acts as a data object of the type of the variable passed in at runtime.  This means the data type of the parameter is fixed during the execution of the PROCEDURE or FUNCTION.

An untyped variable-parameter is "passed by address" to the PROCEDURE or FUNCTION.  Therefore, any changes made to the passed parameter within the PROCEDURE or FUNCTION are made directly to the variable which was passed in.  This allows you to write polymorphic functions.

Within a PROCEDURE or FUNCTION which receives an untyped variable-parameter, it is not safe to make any assumptions about the data type coming in.  The danger of making assumptions is the possiblity of assigning an out-of-range value which the variable's actual data type cannot handle.  If this happens, the result may be disastrously different from that expected.

Data types which may be passed as untyped variable-parameters:

   BYTE  SHORT  USHORT  LONG  ULONG  SREAL  REAL  BFLOAT  DECIMAL  PDECIMAL

   DATE  TIME   STRING  PSTRING  CSTRING  Untyped variable-parameter (*?)

The RAW attribute can be specified if the untyped parameter is being passed to external library functions written in other languages than Clarion.  This has the same effect as passing a C or C++ void * parameter.

Arrays may not be passed as either kind of untyped parameter.

Example:

PROGRAM

MAP

  Proc1(?)	!Untyped value-parameter

  Proc2(*?)	!Untyped variable-parameter

  Proc3(*?)	!Untyped variable-parameter (set to crash)

  Max(?,?),?	!Function returning Untyped value-parameter

END

GlobalVar1	BYTE(3)	!BYTE initialized to 3

GlobalVar2	DECIMAL(8,2,3)

GlobalVar3	DECIMAL(8,1,3)

MaxInteger 	LONG

MaxString 	STRING(255)

MaxFloat 	REAL

  CODE

  Proc1(GlobalVar1)	!Pass in a BYTE, value is 3

  Proc2(GlobalVar2)	!Pass it a DECIMAL(8,2), value is 3.00

! and it prints 3.33

  Proc2(GlobalVar3)	!Pass it a DECIMAL(8,1), value is 3.0

! and it prints 3.3

  Proc3(GlobalVar1)	!Pass it a BYTE and watch

! it crash

  MaxInteger = Max(1,5)	!Max function returns the 5

  MaxString = Max('Z','A')	!Max function returns the 'Z'

  MaxFloat = Max(1.3,1.25)	!Max function returns the 1.3

Proc1	PROCEDURE(ValueParm)

  CODE	! ValueParm starts at 3 and is a LONG

  ValueParm = ValueParm & ValueParm

!Now Contains '33' and is a STRING

  ValueParm = ValueParm / 10

 	!Now Contains 3.3 and is a REAL

Proc2	PROCEDURE(VariableParm)

  CODE

  VariableParm = 10 / 3	!Assign 3.33333333... to passed variable

Proc3	PROCEDURE(VariableParm)

  CODE

  LOOP

    IF VariableParm > 250 THEN BREAK	!If passed a BYTE, BREAK will never happen

    VariableParm += 10

  END

Max	FUNCTION(Val1,Val1)	!Find the larger of two passed values

  CODE

  IF Val1 > Val2	!Check first value against second

    RETURN(Val1)	! return first, if largest

  ELSE	!otherwise

    RETURN(Val2)	! return the second

  END

See Also:

FUNCTION and PROCEDURE Prototypes

Parameter Passing

Data Conversion Rules


Passing Arrays as Parameters

An array may be passed to a PROCEDURE or FUNCTION.  The prototype in the MAP structure must declare the array's data type as a variable-parameter ("passed by address") with an empty subscript list.  If the array is more than one dimension, commas must be used as position holders to indicate the number of dimensions in the array.

The calling statement should pass the entire array to the PROCEDURE or FUNCTION, not just one element.

Example:

PROGRAM

MAP

  MainProc

  AddCount(*LONG[,],*LONG[,])	!Passing two two-dimensional long arrays

END

  CODE

  MainProc	!Call first procedure

MainProc	PROCEDURE

TotalCount	LONG,DIM(10,10)

CurrentCnt	LONG,DIM(10,10)

  CODE

  AddCount(TotalCount,CurrentCnt)	!Call the procedure passing the arrays

AddCount	PROCEDURE(Tot,Cur)	!Procedure expects two arrays

  CODE

  LOOP I# = 1 TO MAXIMUM(Tot,1)	!Loop through first subscript

    LOOP J# = 1 TO MAXIMUM(Tot,2)	!Loop through second subscript

      Tot[I#,J#] += Cur[I#,J#]	! increment TotalCount from CurrentCnt

    END

  END

  CLEAR(Cur)	!Clear CurrentCnt array

  RETURN

See Also:

DIM

FUNCTION and PROCEDURE Prototypes

MAXIMUM


Program Structure Compiler Directives

Compiler Directives are statements that tell the compiler to take some action at compile time.  These statements are not included in the executable program object code which the compiler generates.  Therefore, there is no run-time overhead associated with their use.

BEGIN  (define code structure)

COMPILE  (specify source to be compiled)

EJECT  (start new listing page)

EMBED  (embedded source code section)

INCLUDE  (compile code in another file)

OMIT  (specify source not to be compiled)

SECTION  (specify source code section)

SUBTITLE  (print MODULE subtitle)

TITLE  (print MODULE title)


BEGIN  (define code structure)

BEGIN
  statements
END

BEGIN	Declares a single code statement structure.

statements	Executable program instructions.

The BEGIN compiler directive tells the compiler to treat the statements as a single structure.  The BEGIN structure must be terminated by a period or the END statement.

BEGIN is used in an EXECUTE control structure to allow several lines of code to be treated as one.

Example:

EXECUTE Value

  Proc1	!Execute if Value = 1

  BEGIN	!Execute if Value = 2

    Value += 1

    Proc2

  END

  Proc3	!Execute if Value = 3

END

See Also:

EXECUTE


COMPILE  (specify source to be compiled)

COMPILE(terminator [,expression])

COMPILE 	Specifies a block of source code lines to be included in the compilation.

terminator	A string constant that marks the last line of a block of source code.

expression	An expression allowing conditional execution of the COMPILE.  The expression is: EQUATE = integer.

The COMPILE directive specifies a block of source code lines to be included in the compilation.  The included block begins with the COMPILE directive and ends with the line that contains the same string constant as the terminator.  The entire terminating line is included in the COMPILE block.

The optional expression parameter permits conditional COMPILE.  The form of the expression is fixed.  It is the label of an EQUATE statement, or a Conditional Switch set in the Project System, followed by an equal sign ( = ), followed by an integer constant.  The code between COMPILE and the terminator is compiled only if the expression is true.  Although the expression is not required, COMPILE without an expression parameter is not necessary because all source code is compiled unless explicitly omitted.  COMPILE and OMIT are opposites and may not be nested within each other, or themselves.

Example:

Demo	EQUATE(1)	!Specify the Demo EQUATE value

  CODE

  COMPILE('EndDemoChk',Demo = 1)	!COMPILE only if Demo equate is turned on

  DO DemoCheck	!Check for demo limits passed

EndDemoChk	!End of conditional COMPILE code

See Also:

OMIT

EQUATE


EJECT  (start new listing page)

EJECT([module subtitle])

EJECT 	Starts a new page in a Clarion listing.

module subtitle	A string constant containing the subtitle to be printed.  On the next page of the listing, the module subtitle is printed in the first column of the third line.

The EJECT directive starts a new page and an optional new module subtitle in a Clarion listing.  If the module subtitle parameter is omitted, the subtitle set by a previous SUBTITLE or EJECT directive will be used on the next page.

Example:

EJECT('File Declarations')	!Start new page, new subtitle


EMBED  (embedded source code section)

EMBED(string)
embedded source code statements
ENDEMBED

EMBED 	Begins a block of embedded source code.

string	A string constant that identifies the section of embedded source code. This is usually used for error messages for easy identification of the error location.

embedded

 source code

 statements	Any valid Clarion language statements.

The EMBED directive identifies a block of embedded source code.  The block begins with the EMBED directive and ends with the ENDEMBED statement.

The EMBED directive causes the compiler to number source code lines relative to the beginning of the embedded source.  The string is used in error messages to identify exactly what embedded source contains the error.  After the terminating period or END statement, the compiler's line numbering resumes where it left off before the EMBED (including the number of lines contained in the embedded source).

The EMBED directive is usually used to identify blocks of embedded source code included within generated source code from the Application Generator.

Example:

  CODE

  Y = 3	!Line 1

  BLANK	!Line 2

  X = Y	!Line 3

  EMBED('Source One')	!Line 4

    A = B + C 	!Embedded Line 1

    MESSAGE('Message') 	!Embedded Line 2

    X = A	!Embedded Line 3

  ENDEMBED	!Line 8, End of embedded source

  OPEN(Screen)	!Line 9


INCLUDE  (compile code in another file)

INCLUDE(filename [,section]) [,LIST]

INCLUDE 	Specifies source code to be compiled which exists in a separate file which is not a MEMBER module.

filename	A string constant that contains the DOS file specification for a source file.  If the extension is omitted, .CLA is assumed.

section	A string constant which is the string parameter of the SECTION directive marking the beginning of the source code to be included.

The INCLUDE directive specifies source code to be compiled which exists in a separate file which is not a MEMBER module.  Starting on the line of the INCLUDE directive, the source file, or the specified section of that file, is compiled as if it appeared in sequence within the source module being compiled.

The compiler uses the Redirection file (CLARION.RED) to find the file, searching the path specified for that type of filename (usually by extension).  This makes it unnecessary to provide a complete path in the filename to be included.  A discussion of the Redirection file is in the Programmer's Guide.

Example:

GenLedger	PROCEDURE	!Declare procedure

INCLUDE('filedefs.cla')	!Include file definitions here

    CODE	!Begin code section

    INCLUDE('Setups','ChkErr')	!Include error check from setups.cla


OMIT  (specify source not to be compiled)

OMIT(terminator [,expression])

OMIT 	Specifies a block of source code lines to be omitted from the compilation.

terminator	A string constant that marks the last line of a block of source code.

expression	An expression allowing conditional execution of the OMIT.  The expression must be: EQUATE = integer.

The OMIT directive specifies a block of source code lines to be omitted from the compilation.  These lines may contain source code comments or a section of code that has been "stubbed out" for testing purposes.  The omitted block begins with the OMIT directive and ends with the line that contains the same string constant as the terminator.  The entire terminating line is included in the OMIT block.

The optional expression parameter permits conditional OMIT.  The form of the expression is fixed.  It is the label of an EQUATE statement, or a Conditional Switch set in the Project System, followed by an equal sign ( = ), followed by an integer constant.  The OMIT directive executes only if the expression is true.

COMPILE and OMIT are opposites and may not be nested within each other, or themselves.

Example:

  OMIT('**END**')	!Unconditional OMIT

*************************************************

*

*  Main Program Loop

*

*************************************************

**END**

Demo	EQUATE(0)	!Specify the Demo EQUATE value

  CODE

  OMIT('EndDemoChk',Demo = 0)	!OMIT only if Demo is turned off

  DO DemoCheck	!Check for demo limits passed

EndDemoChk	!End of omitted code

See Also:

COMPILE

EQUATE


SECTION  (specify source code section)

SECTION(string)

SECTION 	Identifies the beginning of a block of executable source code or data declarations.

string	A string constant which names the SECTION.

The SECTION compiler directive identifies the beginning of a block of executable source code or data declarations which may be INCLUDEd in source code in another file.  The SECTION's string parameter is used as an optional parameter of the INCLUDE directive to include a specific block of source code.  A SECTION is terminated by the next SECTION or the end of the file.

Example:

SECTION('FirstSection')	!Begin section

FieldOne	STRING(20)

FieldTwo	LONG

SECTION('SecondSection')	!End previous section, begin new section

  IF Number <> SavNumber

    DO GetNumber

  END

SECTION('ThirdSection')	!End previous section, begin new section

  CASE Action

  OF 1

    DO AddRec

  OF 2

    DO ChgRec

  OF 3

    DO DelRec

  END	!Third section ends at end of file

See Also:

INCLUDE


SUBTITLE  (print MODULE subtitle)

SUBTITLE(module subtitle)

SUBTITLE 	Declares a listing subtitle printed in the first column of the third line of a Clarion listing.

module subtitle	A string constant containing the subtitle to be printed.

A SUBTITLE is printed in the first column of the third line of a Clarion listing.  The SUBTITLE directive does not print in the listing.  The SUBTITLE directive must be placed at the beginning of a source module prior to the PROGRAM or MEMBER declarations.  The subtitle remains the same on every page of the listing unless it is changed by an EJECT directive.

Example:

SUBTITLE('Global Data Declarations')


TITLE  (print MODULE title)

TITLE(module title)

TITLE 	Declares a listing title printed in the first column of the first line of a Clarion listing.

module title	A string constant containing the title to be printed.

A TITLE is printed in the first column of the first line of a Clarion listing.  The TITLE directive does not print in the listing.  The TITLE directive must be placed at the beginning of a source module prior to the PROGRAM or MEMBER declarations.  The title remains the same on every page of the listing.

Example:

TITLE('ORDERSYS - Order Entry System Listing')


Expressions and Assignments

Expressions

Expression Evaluation

Arithmetic Operators

Logical Operators

Numeric Constants

Numeric Expressions

String Constants

The Concatenation Operator

String Expressions

Logical Expressions

Runtime Expression Strings

BIND  (declare runtime expression string variable)

UNBIND  (free runtime expression string variable)

EVALUATE  (return runtime expression string result)

Assignment Statements

Simple Assignment Statements

Operating Assignment Statements

Deep Assignment Statements

Reference Assignment Statements

CLEAR  (clear a variable)

Data Structure Property Assignments

Property Expressions

Property Equates

Undeclared Properties

Data Conversion Rules


Expressions

An expression is a mathematical or logical formula that produces a value.  An expression may be the source variable of an assignment statement, a parameter of a procedure or function, a subscript of an array (a dimensioned variable), or the condition of an IF, CASE, LOOP, or EXECUTE structure.  Expressions may contain constant values, variables, and function calls connected by logical and/or arithmetic operators.


Expression Evaluation

Expressions are evaluated in the standard algebraic order of operations.  The precedence of operations is controlled by operator type and placement of parentheses.  Each operation produces an (internal) intermediate value used in subsequent operations.  Parentheses may be used to group operations within expressions.  Expressions are evaluated beginning with the inner-most set of parentheses and working through to the outer-most set.

Precedence levels for expression evaluation, from highest to lowest, are:

   Level 1	( )	Parenthetical Grouping

   Level 1	-	Unary Minus (Negative sign)

   Level 3	function call	Gets the RETURN value

   Level 4	^	Exponentiation

   Level 5	* / %	Multiplication, Division, Modulus Division

   Level 6	+ -	Addition, Subtraction

   Level 7	&	Concatenation

Expressions may produce numeric values, string values, or logical values (true/false evaluation).  An expression may contain no operators at all; it may be a single variable, constant value, or function call.


Arithmetic Operators

An arithmetic operator combines two operands arithmetically to produce an intermediate value.  The operators are:

   +	Addition	(A + B gives A plus B)

   -	Subtraction	(A - B gives A minus B)

   *	Multiplication	(A * B gives A times B)

   /	Division	(A / B gives A divided by B)

   ^	Exponentiation	(A ^ B gives A raised to power of B)

   %	Modulus Division	(A % B gives the remainder of A divided by B)

All arithmetic operations produce LONG or REAL intermediate values.  The data type of the intermediate value is determined by the type of operation performed and the data types involved.  However, division or exponentiation always produces REAL intermediate values.


Logical Operators

A logical operator compares two operands or expressions and produces a true or false condition.  There are two types of logical operators: conditional and Boolean.  Conditional operators compare two values or expressions.  Boolean operators connect string, numeric, or logical expressions together to determine true-false logic.  Operators may be combined to create complex operators.

Conditional Operators	=	Equal sign

<	Less than

>	Greater than

Boolean Operators	NOT	Boolean NOT

~	Tilde (Logical NOT)

AND	Boolean AND

OR	Boolean OR

XOR	Boolean XOR (eXclusive OR)

Combined operators	<>	Not equal

~=	Not equal

NOT =	Not equal

<=	Less than or equal to

=<	Less than or equal to

~>	Not greater than

NOT >	Not greater than

>=	Greater than or equal to

=>	Greater than or equal to

~<	Not less than

NOT <	Not less than

During logical evaluation, any non-zero value indicates a true condition, and a null (blank) string or zero value indicates a false condition.

Example:

Logical Expression 	Result

A = B	True when A is equal to B

A < B	True when A is less than B

A > B	True when A is greater than B

A <> B, A ~= B, A NOT = B	True when A is not equal to B

A ~< B, A >= B, A NOT < B	True when A is not less than B

A ~> B, A <= B, A NOT > B	True when A is not greater than B

~ A, NOT A	True when A is null or zero

A AND B	True when A is true and B is true

A OR B	True when either A is true or B is true or both are true

A XOR B	True when A is true or B is true, but not both.


Numeric Constants

Numeric constants are fixed numeric values.  They may occur in data declarations, in expressions, and as parameters of procedures, functions, or attributes.  A numeric constant may be represented in decimal (base 10 the default), binary (base 2), octal (base 8), hexadecimal (base 16), or scientific notation formats.  Formatting characters, such as dollar signs and commas, are not permitted in numeric constants.

Decimal (base ten) numeric constants may contain an optional leading minus sign (hyphen character), an integer, and an optional decimal with a fractional component.

Example:

-924

  76.346

 -45.026

Binary (base two) numeric constants may contain an optional leading minus sign, the digits 0 and 1, and a terminating B or b character.

Example:

    1011b

-1000110B

Octal (base eight) numeric constants contain an optional leading minus sign, the digits 0 through 7, and a terminating O or o character.

Example:

    3403o

-7041312O

Hexadecimal (base sixteen) numeric constants contain an optional leading minus sign, the digits 0 through 9, alphabet characters A through F (representing the numbers 10 through 15) and a terminating H or h character.  If the left-most character is a letter A through F, a leading zero must be used.

Example:

   -1FFBh

0CD1F74FH


Numeric Expressions

Numeric expressions may be used as parameters of procedures or functions, the condition of IF, CASE, LOOP, or EXECUTE structures, or as the source portion of an assignment statement where the destination is a numeric variable.  A numeric expression may contain arithmetic operators and the concatenation operator, but they may not contain logical operators.

When used in a numeric expression, string constants and variables are converted to numeric intermediate values.  If the concatenation operator is used, the intermediate value is converted to numeric after the concatenation occurs.

Example:

3.14159	!The value of PI

Count + 1	!Add 1 to Count

(1 - N * N) / R	!N times N subtracted from 1

!  then divided by R

305 & 7854555	!Concatenate area code with phone number

See Also:

Data Conversion Rules


String Constants

A string constant is a set of characters enclosed in single quotes (apostrophes).  The maximum length of a string constant is 255 characters.  Characters that cannot be entered from the keyboard may be inserted into a string constant by enclosing their ASCII character codes in angle brackets ( < > ).  ASCII character codes may be represented in decimal or hexadecimal numeric constant format.

In a string constant, a left angle bracket ( < ) initiates a scan for a right angle bracket.  Therefore, to include a left angle bracket in a string constant requires two left angle brackets in succession.  To include an apostrophe as part of the value inside a string constant requires two apostrophes in succession.  Two apostrophes ( '' ), with no characters (or just spaces) between them, represents a null, or blank, string.  Consecutive occurrences of the same character within a string constant may be represented by repeat count notation.  The number of times the character is to be repeated is placed within curly braces ( { } ) immediately following the character to repeat.  To include a left curly brace ({) as part of the value inside a string constant requires two left curly braces ({{) in succession.

Example:

'string constant'	!A string constant

'It''s a girl!'	!With embedded apostrophe

'<27,15>'	!Using decimal ASCII codes

'A << B'	!With embedded left angle, A < B

'*{20}'	!Twenty asterisks, repeat-count notation

''	!A null (blank) string


The Concatenation Operator

The concatenation operator ( & ) is used to append one string or variable to another.  The length of the result string is the sum of the lengths of the two values being concatenated.  Numeric data types may be concatenated with strings or other numeric variables or constants.  In many cases, the CLIP function should be used to remove any trailing spaces from a string being concatenated to another string.

Example:

CLIP(FirstName) & ' ' Initial & '. ' & LastName	!Concatenate full name

'Clarion Software' & ', Inc.'	!Concatenate two constants

See Also:

Data Conversion Rules

CLIP

Numeric Expressions


String Expressions

String expressions may be used as parameters of procedures, functions, and attributes, or as the source portion of an assignment statement when the destination is a string variable.  String expressions may contain a single string or numeric variable, or a complex combination of sub-expressions, functions, and operations.

Example:

Name	STRING(10)

Weight	STRING(3)

Phone	LONG

  CODE

  'Address:' & Cus:Address	!Concatenate a constant and variable

  Name	!A string variable

  'Phone:' & ' 305-' & FORMAT(Phone,@P###-####P)

!Concatenate constants and FORMAT function's return value

  Weight & 'lbs.'	!Concatenate a constant and variable


Logical Expressions

Logical expressions evaluate true-false conditions in IF, LOOP UNTIL, and LOOP WHILE control structures.  Control is determined by the final result (true or false) of the expression.  Logical expressions are evaluated from left to right.  The right operand of an AND, OR, or XOR logical expression will only be evaluated if it could affect the result.  Parentheses should be used to eliminate ambiguous evaluation and to control evaluation precedence.  The level or precedence for the logical operators is as follows:

Level 1	Conditional operators

Level 2	~, NOT

Level 3	AND

Level 4	OR, XOR

Example:

LOOP UNTIL KEYBOARD()	!True when user presses any key

!some statements

END

IF A = B THEN RETURN.	!RETURN if A is equal to B

LOOP WHILE ~ Done#	!Loop while false (Done# = 0)

!some statements

END

IF A >= B OR (C > B AND E = D) THEN RETURN.	!True if a >= b, also true if

!  both c > b and e = d.

!The second part of the expression

! (after OR) is evaluated only if the

! first part is not true.


Runtime Expression Strings

Clarion for Windows has the ability to evaluate Clarion language expressions dynamically created at runtime, rather than at development time.  This allows a Clarion program to contruct expressions "on the fly."  This also makes it possible to allow an end-user to enter the expression to evaluate.

An expression is a mathematical or logical formula that produces a value; it is not a complete Clarion language statement.  Expressions may only contain constant values, variables, or function calls connected by logical and/or arithmetic operators.  An expression may be used as the source side of an assignment statement, a parameter of a procedure or function, a subscript of an array (a dimensioned variable), or the condition of an IF, CASE, LOOP, or EXECUTE structure.

Any program variable, and most of the internal Clarion functions, can be used as part of a runtime expression string.  User-defined functions that fall within certain specific guidelines (described in the BIND statement documentation) may also be used in runtime expression strings.

All of the standard Clarion expression syntax is available for use in runtime expression strings.  This includes parenthetical grouping and all the arithmetic, logical, and string operators.  Dynamic expressions are evaluated just as any other Clarion expression and all the standard operator precedence level rules described in the Expression Evaluation section apply.

It takes three steps to use runtime expression strings:

     _	The variables that are allowed to be used in the expressions must be explicitly declared with the BIND statement.

     _	The expression must be built.  This may involve concatenating user choices or allowing the user to directly type in their own expression.

     _	The expression is passed to the EVALUATE function which returns the result.  If the expression is not a valid Clarion expression, ERRORCODE is set.

Once the expression is evaluated, its result is used just as the result of any hard-coded expression would be.  For example, a runtime expression string could provide a filter expression to eliminate certain records when viewing or printing a database.


BIND  (declare runtime expression string variable)

BIND(	 name,variable	 )
 name,function
 group

BIND	Identifies variables allowed to be used in dynamic expressions.

name	A string constant containing the identifier used in the dynamic expression.

variable	The label of any variable or passed parameter.  If it is an array, it must have only one dimension.

function	The label of a Clarion language FUNCTION that returns a STRING, REAL, or LONG value.  If parameters are passed to the function, they must be STRING value-parameters (passed by value, not by address).

group	The label of a GROUP, RECORD (FILE), or QUEUE structure declared with the BINDABLE attribute.  *** NOT YET IMPLEMENTED.

The BIND statement declares the logical name used to identify a variable or user-defined function in runtime expression strings.  A variable or user-defined function must be identified with the BIND statement before it can be used in an expression string.

  BIND(name,variable)

The specified name is used in the expression in place of the label of the variable.

  BIND(name,function)

The specified name is used in the expression in place of the label of the function.

  BIND(group)

Declares all the variables within the GROUP, RECORD, VIEW, or QUEUE (with the BINDABLE attribute) available for use in a dynamic expression.  The contents of each variable's NAME attribute is the logical name used in the dynamic expression.  If no NAME attribute is present, the label of the variable (including prefix) is used.

A GROUP, FILE (RECORD), or QUEUE structure declared with the BINDABLE attribute has space allocated in the .EXE for the names of all of the data elements in the structure.  This creates a larger program that uses more memory than it normally would.  Also, the more variables that are bound at one time, the slower the EVALUATE function will work.  Therefore, BIND(group) should only be used when a large proportion of the constituent fields are going to be used.

Example:

PROGRAM

MAP

  AllCapsFunc(STRING),STRING	!Clarion function

END

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl),BINDABLE	!Bindable RECORD structure

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

  CODE

  BIND('ShipName',Hea:ShipToName)	!BIND a single variable

  BIND(Dtl:Record)	!BIND a RECORD structure

  BIND('SomeFunc',AllCapsFunc)	!BIND a Clarion language function

AllCapsFunc	FUNCTION(PassedString)

  CODE

  RETURN(UPPER(PassedString))

See Also:

UNBIND

EVALUATE


UNBIND  (free runtime expression string variable)

UNBIND( [name] )

UNBIND	Frees variables from use in runtime expression strings.

name	A string constant that specifies the identifier used by the dynamic expression evaluator.  If omitted, all bound variables are unbound.

The UNBIND statement frees logical names previously bound by the BIND statement.  The more variables that are bound at one time, the slower the EVALUATE function works.  Therefore, UNBIND should be used to free all variables and user-defined functions not currently available for use in runtime expression strings.

Example:

PROGRAM

MAP

  AllCapsFunc(STRING),STRING	!Clarion function

END

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl),BINDABLE	!Bindable RECORD structure

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

  CODE

  BIND('ShipName',Hea:ShipToName)

  BIND(Dtl:Record)

  BIND('SomeFunc',AllCapsFunc)

  UNBIND('ShipName')	!UNBIND the variable

  UNBIND('SomeFunc') 	!UNBIND the Clarion language function

  UNBIND	!UNBIND all bound variables

AllCapsFunc	FUNCTION(PassedString)

  CODE

  RETURN(UPPER(PassedString))

See Also:

BIND

EVALUATE


EVALUATE  (return runtime expression string result)

EVALUATE(expression)

EVALUATE	Evaluates runtime expression strings.

expression	A string constant or variable containing the expression to evaluate.

The EVALUATE function returns the result of the expression as a STRING value.  If the expression does not meet the rules of a valid Clarion expression, the result will be a null string, and the ERRORCODE function is set.

The more variables are bound at one time, the slower the EVALUATE function works.  Therefore, BIND(group) should only be used when most of the group's fields are needed, and UNBIND should be used to free all variables and user-defined functions not currently required for use in dynamic expressions.

Return Data Type:  STRING

Errors Posted:    *** NO ERRORS YET IMPLEMENTED.

Example:

PROGRAM

MAP

  AllCapsFunc(STRING),STRING	!Clarion function

END

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

. .

StringVar	STRING(20)

  CODE

  BIND('ShipName',Hea:ShipToName)

  BIND('SomeFunc',AllCapsFunc)

  StringVar = 'SMITH'

  IF EVALUATE('SomeFunc(ShipName) = StringVar')

    DO SmithProcess

  END

AllCapsFunc	FUNCTION(PassedString)

  CODE

  RETURN(UPPER(PassedString))

See Also:

BIND

UNBIND


Assignment Statements

Simple Assignment Statements

Operating Assignment Statements

Deep Assignment Statements

Reference Assignment Statements

CLEAR  (clear a variable)


Simple Assignment Statements

destination = source

destination	The label of a variable or data structure property.

source	A numeric or string constant, variable, function, expression, or data structure property.

The = sign assigns the value of source to the destination; it copies the value of the source expression into the destination variable.  If destination and source are different data types, the value the destination receives from the source is dependent upon the Data Conversion Rules.

Example:

Name = 'JONES'	!Variable = string constant

PI = 3.14159	!Variable = numeric constant

Cosine = SQRT(1 - Sine * Sine)	!Variable = function return value

A = B + C + 3	!Variable = numeric expression

Name = CLIP(FirstName) & ' ' Initial & '. ' & LastName

!Variable = string expression

See Also:

Data Conversion Rules


Operating Assignment Statements

destination	+=	source
destination	-=	source
destination	*=	source
destination	/=	source
destination	^=	source
destination	%=	source

destination	Must be the label of a variable.

source	A numeric or string constant, variable, function, or expression.

Operating assignment statements perform arithmetic on a variable.  In the examples below, the statements on the right and left are functionally equivalent, however, the operating assignment statements perform more efficiently.

Example:

    Operating Assignment	Functional Equivalent

A += 1	   A = A + 1

A -= B	   A = A - B

A *= -5	   A = A * -5

A /= 100	   A = A / 100

A ^= I + 1	   A = A ^ (I + 1)

A %= 7	   A = A % 7


Deep Assignment Statements

destination	:=:	source

destination	The label of a GROUP, RECORD, VIEW, or QUEUE data structure, or an array.

source	The label of a GROUP, RECORD, VIEW, or QUEUE data structure, or a numeric or string constant, variable, function, or expression.

The :=: sign executes a deep assignment statement which performs multiple individual component variable assignments from one data structure to another.  The assignments are only performed between the variables within each structure that have exactly matching labels, ignoring all prefixes.  The compiler looks within nested GROUP structures to find matching labels.  Any variable in the destination which does not have a label exactly matching a variable in the source, is not changed.

Deep assignments are performed just as if each matching variable were individually assigned to its matching variable.  This means that all normal data conversion rules apply to each matching variable assignment.  For example, the label of a nested source GROUP may match a nested destination GROUP or simple variable.  In this case, the nested source GROUP is assigned to the destination as a STRING, just as normal GROUP assignment is handled.

The name of a source array may match a destination array.  In this case, each element of the source array is assigned to its corresponding element in the destination array.  If the source array has more or fewer elements than the destination array, only the matching elements are assigned to the destination.

If the destination is an array variable that is not part of a GROUP, RECORD, or QUEUE, and the source is a constant, variable, or expression, then each element of the destination array is initialized to the value of the source.  This is a much more efficient method of initializing an array to a specific value than using a LOOP structure and assigning each element in turn.

Example:

Group1	GROUP,PRE(G1)

S	  SHORT

L	  LONG

END

Group2	GROUP,PRE(G2)

L	  SHORT

S	  REAL

T	  LONG

END

ArrayField	SHORT,DIM(1000)

  CODE

  Group2 :=: Group1  	!Is equivalent to:	G2:S = G1:S

!	G2:L = G1:L

  ArrayField :=: 7	!Is equivalent to:	LOOP I# = 1 to 1000

!	  ArrayField[I#] = 7

!	END


Reference Assignment Statements

destination &= source

destination	The label of a reference variable.

source	The label of another reference variable of the same type as the destination, or the label of a variable or data structure of the type referenced by the destination.  This cannot be an expression, only a data label.

The &= sign executes a reference assignment statement which assigns to the destination reference variable the reference to the source variable.  Depending upon the data type, the destination reference variable may receive the source's memory address, or a more complex internal data structure (describing the location and type of source data).

The declarations of the destination reference variable and its source must match exactly; reference assignment does not perform automatic type conversion.  For example, a reference assignment statement to a destination declared as &GROUP must have a source that is either another &GROUP reference variable, or the label of a GROUP structure.

Example:

Group1	GROUP,PRE(G1)

ShortVar	  SHORT

LongVar1	  LONG

LongVar2	  LONG

END

GroupRef	&GROUP	!Reference a GROUP, only

LongRef	&LONG	!Reference a LONG, only

  CODE

  GroupRef &= Group1	!Assign GROUP reference

  IF SomeCondition	!Evaluate some condition

    LongRef &= G1:LongVar1	! and reference an appropriate variable

  ELSE

    LongRef &= G1:LongVar2

  END

  LongRef += 1	!Increment either LongVar1 or LongVar2

! depending upon which variable is referenced

See Also:

Reference Variables


CLEAR  (clear a variable)

CLEAR(label [,n])

CLEAR	Clears any value from a variable.

label	The label of a variable.

n	A numeric constant; 1 or -1.  This parameter indicates a cleared value other than zero or blank.  If n is 1, the variable is set to the highest possible value for that data type.  For STRING, PSTRING and CSTRING, that is ASCII 255.  If n is -1, the variable is set to the lowest possible value for that data type.  For STRING, PSTRING and CSTRING, that is ASCII 0.

The CLEAR statement clears any value from the label variable.  If n is omitted, numeric variables are cleared to zero, and string variables are cleared to spaces.  If the label parameter is a GROUP, RECORD, or QUEUE structure name, all variables in the structure are cleared.  If the variable has a DIM attribute, the entire array is cleared.  A single element of an array cannot be CLEARed.

Example:

CLEAR(Count)	!Clear a variable

CLEAR(Cus:Record)	!Clear the record structure

CLEAR(Amount,1)	!Clear variable to highest possible value

CLEAR(Amount,-1)	!Clear variable to lowest possible value


Data Structure Property Assignments

The attributes (properties) of the APPLICATION, WINDOW, and REPORT data structures, and their component controls, only allow you to place constant values in the data structure declaration.  The same is true of FILE, VIEW, and QUEUE data structures.  The values of most of these constant properties may be changed or determined using simple assignment statements containing property expressions.

Property expressions represent the attributes (properties) and the parameters of attributes declared in APPLICATION, WINDOW, REPORT, FILE, VIEW, and QUEUE structures, and their components.  Most attributes have corresponding property expressions.  However, attributes such as PRE, OVER, and THREAD are actually compiler directives which have no associated property expresion.  In addition, there are some property expressions which are not associated with declared attributes.

A property expression can be used as the destination of an assignment statement.  This changes the value of the attribute (or attribute parameter) associated with the property.  A property expression can also be used in any string expression to determine the current value of the attribute (or attribute parameter).


Property Expressions

[target] [$] [control] { property [,element] }

target	The label of an APPLICATION, WINDOW, REPORT, FILE, VIEW, or QUEUE structure, or the built-in variable TARGET.  If omitted, the current APPLICATION or WINDOW structure is assumed to be the target. The value of the builtin variable TARGET can be changed by the SETTARGET command.

$	Required separator when both target and control are specified.  May be omitted if either target or control is omitted.

control	A field number or field equate label for the control in the target structure to affect.  If omitted, the target must be specified.

property	An integer constant, EQUATE, or variable that specifies the property (attribute) to change.

element	An integer constant or variable that specifies which parameter to change (for those attributes that have multiple parameters).

This property expression syntax allows you access to the attributes of APPLICATION, WINDOW, or REPORT structures, or any control within these structures.  It also allows you access to any attribute of a FILE, VIEW, or QUEUE structure.

To specify an attribute of an APPLICATION, WINDOW, REPORT, FILE, VIEW, or QUEUE structure (not a component control) omit the control portion of the property expression.  To specify a control in the current window, omit the target portion of the property expression.

REPORT, FILE, VIEW, or QUEUE data structures are never the default target.  Therefore, either SETTARGET must be used to change the default target, or the structure's label must be explicitly specified as the target before you can change any property of the structure, or any control it contains.

Property expressions do not apply to the components within the FILE, VIEW, or QUEUE structure, so a control is not needed.  This makes the FILE, VIEW, and QUEUE property expressions always: target{property}.

TARGET is a builtin variable used primarily to reference windows in other execution threads.  The SETTARGET statement is used to change the window referenced by TARGET.

Property expressions may be used in Clarion language statements anywhere a string expression is allowed.  Therefore, assigning a new value to a property becomes an assignment statement with the property as the destination and the new value as the source.  Determining the current value of a property becomes an assignment statement where the property is the source and the new value is the destination.

All properties are treated as string data at runtime; the compiler automatically performs any necessary data type conversion.  An attribute without parameters is a binary attribute.  Binary attributes are either "present" or "missing."  A binary attribute returns a '1' if it is present, and '' (null) if it is missing.  Changing the value of a binary attribute to '' (null), '0' (zero), or any non-numeric string sets it to missing.  Changing it to any other value sets it to "present."

Most properties can be both examined (read) and changed (written).  However, some properties are "readonly" and cannot be changed.  Assigning a value to a "readonly" property has no effect at all.  Other properties are "writeonly" properties that return a "1" if present, and '' (null) if missing, just as binary attributes do.

Example:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    MENU('File'),USE(?FileMenu)

      ITEM('Open...'),USE(?OpenFile)

      ITEM('Close'),USE(?CloseFile),DISABLE

      ITEM('E&xit'),USE(?MainExit)

    END

    MENU('Help'),USE(?HelpMenu)

      ITEM('Contents'),USE(?HelpContents),STD(STD:HelpIndex)

      ITEM('Search for Help On...'),USE(?HelpSearch),STD(STD:HelpSearch)

      ITEM('How to Use Help'),USE(?HelpOnHelp),STD(STD:HelpOnHelp)

      ITEM('About MyApp...'),USE(?HelpAbout)

    END

  END

  TOOLBAR

    BUTTON('Open'),USE(?OpenButton),ICON(ICON:Open)

  END

END

  CODE

  OPEN(MainWin)

  MainWin{PROP:text} = 'A New Title'	!Change window title

  ?OpenButton{PROP:icon} = ICON:Asterisk	!Change button icon

  IF MainWin$?HelpContents{PROP:std} <> STD:HelpIndex

    MainWin$?HelpContents{PROP:std} = STD:HelpIndex

  END

  MainWin{PROP:maximize} = 1	!Expand to full screen

  ACCEPT

    CASE ACCEPTED()	!Which control was chosen?

    OF ?OpenFile	!Open... menu selection

    OROF ?OpenButton	!Open button on toolbar

      START(OpenFileProc)	!Start new execution thread

    OF ?MainExit	!Exit menu selection

    OROF ?MainExitButton	!Exit button on toolbar

      BREAK	!Break ACCEPT loop

    OF ?HelpAbout	!About... menu selection

      HelpAboutProc	!Call application information procedure

    END

  END

  CLOSE(MainWin)	!Close APPLICATION

  RETURN

See Also:

SETTARGET


Property Equates

Equates for all properties are contained in the PROPERTY.CLW file.  This file also contains equates for the standard values used by some of these properties.  Some properties are "read-only" and their value may not be changed, and others are "write-only" properties whose value cannot be determined.  These restrictions are noted for each control affected.

EQUATE statements for the properties are contained in the PROPERTY.CLW file.  The following list is a comprehensive sample of these (see PROPERTY.CLW for the complete list):

  PROP:Text	APPLICATION(text), WINDOW(text), or control(text) parameter.

  PROP:Type	Contains the type of control.  Valid values to assign are the CREATE:xxxx equate values.

AT attribute properties:

  PROP:At	AT attribute.  An array (4 values).

  PROP:Xpos	AT(x) parameter, equivalent to {PROP:at,1}

  PROP:Ypos	AT(,y) parameter, equivalent to {PROP:at,2}

  PROP:Width	AT(,,width) parameter, equivalent to {PROP:at,3}

  PROP:Height	AT(,,,height) parameter, equivalent to {PROP:at,4}

FONT attribute properties:

  PROP:Font	FONT attribute.  An array (4 values).

  PROP:FontName	FONT(fontname) parameter, equivalent to {PROP:font,1}.

  PROP:FontSize	FONT(,fontsize) parameter, equivalent to {PROP:font,2}.

  PROP:FontColor	FONT(,,fontcolor) parameter, equivalent to {PROP:font,3}.

  PROP:FontStyle	FONT(,,,fontstyle) parameter, equivalent to {PROP:font,4}.

CLASS attribute properties:

  PROP:Class	CLASS attribute.  An array (2 values).

  PROP:VbxFile	CLASS(vbxfile) parameter, equivalent to {PROP:class,1}.

  PROP:VbxName	CLASS(,vbxname) parameter, equivalent to {PROP:class,2}.

All other attribute properties:

  PROP:Absolute	ABSOLUTE attribute ('' if missing, else present).

  PROP:Alone	ALONE attribute ('' if missing, else present).

  PROP:Alrt 	ALRT attribute.  An array (up to 256 values).

  PROP:Ave	AVE attribute ('' if missing, else present).

  PROP:Boxed	ABSOLUTE attribute ('' if missing, else present).

  PROP:Cap  	ABSOLUTE attribute ('' if missing, else present).

  PROP:Center	CENTER attribute ('' if missing, else present).

  PROP:CenterOffset	CENTER(offset) parameter, equivalent to {PROP:center,2}.

  PROP:Check	CHECK attribute, ('' if missing, else present).

  PROP:Cnt	CNT attribute ('' if missing, else present).

  PROP:Color	COLOR attribute (COLOR:none if none).

  PROP:Column	COLUMN attribute (0 = off, else column number).

  PROP:Cursor	CURSOR attribute (empty string if not specifed).

  PROP:Decimal	DECIMAL attribute ('' if missing, else present).

  PROP:DecimalOffset

DECIMAL(offset) parameter, equivalent to {PROP:decimal,2}.

  PROP:Default	DEFAULT attribute, ('' if missing, else present).

  PROP:Disable	DISABLE attribute, ('' if missing, else present).

  PROP:Double	DOUBLE attribute ('' if missing, else present).

  PROP:Dragid	DRAGID attribute. An array (up to 16 strings).

  PROP:Drop	DROP attribute (0 if none).  May not change to or from 0.

  PROP:Dropid	DROPID attribute. An array (up to 16 strings).

  PROP:Fill	FILL attribute (COLOR:none if none).

  PROP:First	FIRST attribute ('' if missing, else present).

  PROP:Format	FORMAT attribute (blank if none).

  PROP:From	FROM attribute (queue, queue field, or string). (WRITEONLY)

  PROP:Full	FULL attribute, ('' if missing, else present).

  PROP:Gray	GRAY attribute, ('' if missing, else present).

  PROP:Hide	HIDE attribute, ('' if missing, else present).

  PROP:Hlp	HLP attribute (blank if none).

  PROP:Hscroll	HSCROLL attribute, ('' if missing, else present).

  PROP:Icon	ICON attribute, (blank if none).

  PROP:Iconize	ICONIZE attribute, ('' if missing, else present).

  PROP:Imm	IMM attribute, ('' if missing, else present).

  PROP:Ins 	INS attribute ('' if missing, else present).

  PROP:Key	KEY attribute (blank if none).

  PROP:Landscape	LANDSCAPE attribute, ('' if missing, else present).

  PROP:Last	LAST attribute ('' if missing, else present).

  PROP:Left	LEFT attribute ('' if missing, else present).

  PROP:LeftOffset	LEFT(offset) parameter, equivalent to {PROP:left,2}.

  PROP:Mark	MARK attribute (queue, queue field, or array). (WRITEONLY)

  PROP:Mask	MASK attribute, ('' if missing, else present).

  PROP:Max	MAX attribute ('' if missing, else present).

  PROP:Maximize	MAXIMIZE attribute, ('' if missing, else present).

  PROP:Mdi	MDI attribute ('' if missing, else present). (READ-ONLY)

  PROP:Meta	META attribute, ('' if missing, else present).

  PROP:Min	MIN attribute ('' if missing, else present).

  PROP:Mm	MM attribute ('' if missing, else present).

  PROP:Modal	MODAL attribute ('' if missing, else present). (READ-ONLY)

  PROP:Msg	MSG attribute (blank if none).

  PROP:NoBar	NOBAR attribute, ('' if missing, else present).

  PROP:NoFrame	NOFRAME attribute ('' if missing, else present).

  PROP:NoMerge	NOMERGE attribute, ('' if missing, else present).

  PROP:Ovr 	OVR attribute ('' if missing, else present).

  PROP:Page	PAGE attribute ('' if missing, else present).

  PROP:PageAfter	PAGEAFTER attribute, ('' if missing, else present).

  PROP:PageAfterNum	PAGEAFTER(pageafternum) parameter, equivalent to {PROP:pageafter,2}.

  PROP:PageBefore	PAGEBEFORE attribute, ('' if missing, else present).

  PROP:PageBeforeNum

PAGEBEFORE(pagebeforenum) parameter, equivalent to {PROP:pagebefore,2}.

  PROP:Pageno	PAGENO attribute ('' if missing, else present).

  PROP:Palette	PALETTE attribute.  Single value.

  PROP:Password	PASSWORD attribute, ('' if missing, else present).

  PROP:Points	POINTS attribute ('' if missing, else present).

  PROP:Preview	PREVIEW attribute (queue or queue field). (WRITEONLY)

  PROP:Range	RANGE attribute.  An array (2 values).

  PROP:RangeHigh	RANGE(,rangehigh) parameter, equivalent to {PROP:range,2}.

  PROP:RangeLow	RANGE(rangelow) parameter, equivalent to {PROP:range,1}.

  PROP:ReadOnly	READONLY attribute, ('' if missing, else present).

  PROP:Req	REQ attribute, ('' if missing, else present).

  PROP:Reset	RESET attribute (0 = off, else breaklevel nesting depth).

  PROP:Resize	RESIZE attribute ('' if missing, else present).

  PROP:Right	RIGHT attribute ('' if missing, else present).

  PROP:RightOffset	RIGHT(offset) parameter, equivalent to {PROP:right,2}.

  PROP:Round	ROUND attribute, ('' if missing, else present).

  PROP:Scroll	SCROLL attribute, ('' if missing, else present).

  PROP:Separate	SEPARATE attribute, ('' if missing, else present).

  PROP:Skip	SKIP attribute, ('' if missing, else present).

  PROP:Status	STATUS attribute. An array (up to 16 values, 0 terminates).

  PROP:StatusText 	STATUS bar text. An array (up to 16 values, 0 terminates).

  PROP:Std	STD attribute (blank if none).

  PROP:Step	STEP attribute (blank if none).

  PROP:Sum	SUM attribute ('' if missing, else present).

  PROP:System	SYSTEM attribute, ('' if missing, else present).

  PROP:Thous	THOUS attribute ('' if missing, else present).

  PROP:Timer	TIMER attribute (0 if none).

  PROP:Toolbox	TOOLBOX attribute ('' if missing, else present).

  PROP:Trn	TRN attribute, ('' if missing, else present).

  PROP:Upr	UPR attribute, ('' if missing, else present).

  PROP:Use 	USE attribute (variable name).  Writing to it changes the USE variable.  Reading it returns the contents of the USE variable.

  PROP:Vcr	VCR attribute ('' if missing, else present).

  PROP:VcrFeq	VCR(vcrfeq) parameter, equivalent to {PROP:vcr,2}.

  PROP:Vscroll	VSCROLL attribute, ('' if missing, else present).

  PROP:WithNext	WITHNEXT attribute (0 if none).

  PROP:WithPrior	WITHPRIOR attribute (0 if none).


Undeclared Properties

In addition to the properties that relate directly to data structure and control field attributes, there are also some properties that are undeclared.  These properties have no equivalent data structure attributes.  The following properties can only be accessed at runtime:

  PROP:FlushPreview	Flushes the PREVIEW attribute metafiles to the printer (0 = off, else on, always 0 at report open).

  PROP:Items 	Returns the number of entries visible in a LIST or COMBO.  (READ-ONLY)

  PROP:Redraw	When turned off, it inhibits automatic screen re-draw until turned on again (0 = off, else on).

  PROP:SelStart	Sets or retrieves the beginning (inclusive) character to mark as a block in an ENTRY or TEXT control.  It positions the data entry cursor left of the character, and sets PROP:selend to zero (0) to indicate no block is marked.

  PROP:SelEnd	Sets or retrieves the ending (inclusive) character to mark as a block in an ENTRY or TEXT control.

  PROP:ImageBits	Property of an IMAGE control that allows bitmap images to be moved into and out of memo fields.

  PROP:Thread	Returns the thread number. (READ-ONLY)

  PROP:Handle	Returns the window handle. (READ-ONLY)

  PROP:Active	Returns 1 if window is the active window, blank if not.  Set to 1 to make the top window of a thread the active window.

  PROP:VBXEvent	Returns the name of a VBX event. (READ-ONLY)

  PROP:VBXEventArg	VBX event parameters.  An array (up to 16 args).

  PROP:Follows	Changes the tab order to specify the position within the parent that the control will occupy.  The control follows the control number you specify in the tab order.  This must specify an existing control within the parent (window, option, group).  (WRITE-ONLY)


Data Conversion Rules

The Clarion language provides automatic conversion between data types.  However, some assignments can produce an unequal source and destination.  Assigning an "out of range" value can produce unpredictable results.

PSTRING and CSTRING data types are treated the same as STRING, because they are first converted to STRING intermediate values for all operations.  DATE and TIME data types are converted to Clarion Standard Date and Clarion Standard Time intermediate values and are treated as a LONG data type for all operations.

The rules of data conversion from source to destination are as follows:

BYTE = SHORT

BYTE = USHORT

BYTE = LONG

BYTE = ULONG

The destination receives the low-order 8 bits of the source.

BYTE = DECIMAL

BYTE = PDECIMAL

BYTE = REAL

BYTE = SREAL

BYTE = BFLOAT8

BYTE = BFLOAT4

The source is first converted to a LONG, which truncates any decimal portion, then the destination receives the low-order 8 bits of the LONG.

BYTE = STRING

BYTE = CSTRING

BYTE = PSTRING

The source must be a numeric value with no formatting characters.  The source is converted to a LONG, which truncates any decimal portion, then the destination receives the low-order 8 bits of the LONG.

SHORT = BYTE

The destination receives the value of the source.

SHORT = USHORT

SHORT = LONG

SHORT = ULONG

The destination receives the low-order 16 bits of the source.

SHORT = DECIMAL

SHORT = PDECIMAL

SHORT = REAL

SHORT = SREAL

SHORT = BFLOAT8

SHORT = BFLOAT4

The source is first converted to a LONG, which truncates any decimal portion, then the destination receives the low-order 16 bits of the LONG.

SHORT = STRING

SHORT = CSTRING

SHORT = PSTRING

The source must be a numeric value with no formatting characters.  The source is first converted to a LONG, which truncates any decimal portion, then the destination receives the low-order 16 bits of the LONG.

USHORT = BYTE

The destination receives the value of the source.

USHORT = SHORT

USHORT = LONG

USHORT = ULONG

The destination receives the low-order 16 bits of the source.

USHORT = DECIMAL

USHORT = PDECIMAL

USHORT = REAL

USHORT = SREAL

USHORT = BFLOAT8

USHORT = BFLOAT4

The source is first converted to a LONG, which truncates any decimal portion, then the destination receives the low-order 16 bits of the LONG.

USHORT = STRING

USHORT = CSTRING

USHORT = PSTRING

The source must be a numeric value with no embedded formatting characters.  The source is first converted to a LONG, which truncates any decimal portion, then the destination receives the low-order 16 bits of the LONG.

LONG = BYTE

LONG = SHORT

LONG = USHORT

LONG = ULONG

The destination receives the value and the sign of the source.

LONG = DECIMAL

LONG = PDECIMAL

LONG = REAL

LONG = SREAL

LONG = BFLOAT8

LONG = BFLOAT4

The destination receives the value of the source, including the sign, up to 231.  If the number is greater than 231, the destination receives the result of modulo 231.  Any decimal portion is truncated.

LONG = STRING

LONG = CSTRING

LONG = PSTRING

The source must be a numeric value with no embedded formatting characters.  The source is first converted to a REAL, which is then converted to the LONG.

DATE = BYTE

DATE = SHORT

DATE = USHORT

DATE = ULONG

The destination receives the Btrieve format for the Clarion Standard Date for the value of the source.

DATE = DECIMAL

DATE = PDECIMAL

DATE = REAL

DATE = SREAL

DATE = BFLOAT8

DATE = BFLOAT4

The source is first converted to a LONG as a Clarion Standard Date, which truncates any decimal portion, then the destination receives the Btrieve format for the Clarion Standard Date.

DATE = STRING

DATE = CSTRING

DATE = PSTRING

The source must be a numeric value with no embedded formatting characters.  The source is first converted to a LONG as a Clarion Standard Date, which truncates any decimal portion, then the destination receives the Btrieve format for the Clarion Standard Date.

TIME = BYTE

TIME = SHORT

TIME = USHORT

TIME = ULONG

The destination receives the Btrieve format for the Clarion Standard Time for the value of the source.

TIME = DECIMAL

TIME = PDECIMAL

TIME = REAL

TIME = SREAL

TIME = BFLOAT8

TIME = BFLOAT4

The source is first converted to a LONG as a Clarion Standard Time, which truncates any decimal portion, then the destination receives the Btrieve format for the Clarion Standard Time.

TIME = STRING

TIME = CSTRING

TIME = PSTRING

The source must be a numeric value with no embedded formatting characters.  The source is first converted to a LONG as a Clarion Standard Time, which truncates any decimal portion, then the destination receives the Btrieve format for the Clarion Standard Time.

ULONG = BYTE

ULONG = SHORT

ULONG = USHORT

The source is first converted to a LONG, then the destination receives the entire 32 bits of the LONG.

ULONG = LONG

The destination receives the entire 32 bits of the source.

ULONG = DECIMAL

ULONG = PDECIMAL

ULONG = REAL

ULONG = SREAL

ULONG = BFLOAT8

ULONG = BFLOAT4

The source is first converted to a LONG, which truncates any decimal portion, then the destination receives the entire 32 bits of the LONG.

ULONG = STRING

ULONG = CSTRING

ULONG = PSTRING

The source must be a numeric value with no embedded formatting characters.  The source is first converted to a LONG, which truncates any decimal portion, then the destination receives the entire 32 bits of the LONG.

REAL = BYTE

REAL = SHORT

REAL = USHORT

REAL = LONG

REAL = ULONG

The destination receives the full integer portion and the sign of the source.

REAL = DECIMAL

REAL = PDECIMAL

REAL = SREAL

REAL = BFLOAT8

REAL = BFLOAT4

The destination receives the sign, integer portion, and the decimal portion of the source.

REAL = STRING

REAL = CSTRING

REAL = PSTRING

The source must be a numeric string value with no embedded formatting characters.  The destination receives the sign, integer, and decimal portion of the number.  Trailing spaces are ignored.

SREAL = BYTE

SREAL = SHORT

SREAL = USHORT

SREAL = LONG

SREAL = ULONG

The destination receives the sign and value of the source.

SREAL = DECIMAL

SREAL = PDECIMAL

SREAL = REAL

The destination receives the sign, integer, and fractional portion of the source.

SREAL = STRING

SREAL = CSTRING

SREAL = PSTRING

The source must be a numeric string value with no embedded formatting characters.  The destination receives the sign, integer, and decimal portion of the number.  Trailing spaces are ignored.

BFLOAT8 = BYTE

BFLOAT8 = SHORT

BFLOAT8 = USHORT

BFLOAT8 = LONG

BFLOAT8 = ULONG

The destination receives the sign and value of the source.

BFLOAT8 = DECIMAL

BFLOAT8 = PDECIMAL

BFLOAT8 = REAL

The destination receives the sign, integer, and fractional portion of the source.

BFLOAT8 = STRING

BFLOAT8 = CSTRING

BFLOAT8 = PSTRING

The source must be a numeric string value with no embedded formatting characters.  The destination receives the sign, integer, and decimal portion of the number.  Trailing spaces are ignored.

BFLOAT4 = BYTE

BFLOAT4 = SHORT

BFLOAT4 = USHORT

BFLOAT4 = LONG

BFLOAT4 = ULONG

The destination receives the sign and value of the source.

BFLOAT4 = DECIMAL

BFLOAT4 = PDECIMAL

BFLOAT4 = REAL

The destination receives the sign, integer, and fractional portion of the source.

BFLOAT4 = STRING

BFLOAT4 = CSTRING

BFLOAT4 = PSTRING

The source must be a numeric string value with no embedded formatting characters.  The destination receives the sign, integer, and decimal portion of the number.  Trailing spaces are ignored.

DECIMAL = BYTE

DECIMAL = SHORT

DECIMAL = USHORT

DECIMAL = LONG

DECIMAL = ULONG

DECIMAL = PDECIMAL

The destination receives the sign and the value of the source.

DECIMAL = REAL

DECIMAL = SREAL

The destination receives the sign, integer, and the high order part of the fraction from the source.  The high order fractional portion is rounded in the destination.

DECIMAL = STRING

DECIMAL = CSTRING

DECIMAL = PSTRING

The source must be a numeric string value with no embedded formatting characters.  The destination receives the sign, integer, and decimal portion of the number.  Trailing spaces are ignored.

PDECIMAL = BYTE

PDECIMAL = SHORT

PDECIMAL = USHORT

PDECIMAL = LONG

PDECIMAL = ULONG

PDECIMAL = DECIMAL

The destination receives the sign and the value of the source.

PDECIMAL = REAL

PDECIMAL = SREAL

PDECIMAL = BFLOAT8

PDECIMAL = BFLOAT4

The destination receives the sign, integer, and the high order part of the fraction from the source.  The high order fractional portion is rounded in the destination.

PDECIMAL = STRING

PDECIMAL = CSTRING

PDECIMAL = PSTRING

The source must be a numeric string value with no embedded formatting characters.  The destination receives the sign, integer, and decimal portion of the number.  Trailing spaces are ignored.

STRING = BYTE

STRING = SHORT

STRING = USHORT

STRING = LONG

STRING = ULONG

The destination receives the sign and the unformatted number.  The value is left justified in the destination.

STRING = DECIMAL

STRING = PDECIMAL

STRING = REAL

STRING = SREAL

STRING = BFLOAT8

STRING = BFLOAT4

The destination receives the sign, integer, and fractional portion of the source (rounded into the string's picture format).  The value is left justified in the destination.

CSTRING = BYTE

CSTRING = SHORT

CSTRING = USHORT

CSTRING = LONG

CSTRING = ULONG

The destination receives the sign and the unformatted number.  The value is left justified in the destination.

CSTRING = DECIMAL

CSTRING = PDECIMAL

CSTRING = REAL

CSTRING = SREAL

CSTRING = BFLOAT8

CSTRING = BFLOAT4

The destination receives the sign, integer, and fractional portion of the source (rounded into the string's picture format).  The value is left justified in the destination.

PSTRING = BYTE

PSTRING = SHORT

PSTRING = USHORT

PSTRING = LONG

PSTRING = ULONG

The destination receives the sign and the unformatted number.  The value is left justified in the destination.

PSTRING = DECIMAL

PSTRING = PDECIMAL

PSTRING = REAL

PSTRING = SREAL

PSTRING = BFLOAT8

PSTRING = BFLOAT4

The destination receives the sign, integer, and fractional portion of the source (rounded into the string's picture format).  The value is left justified in the destination.


Control Statements

Control Structures

CASE  (conditional execution structure)

EXECUTE  (statement selection structure)

IF  (conditional execution structure)

LOOP  (iteration structure)

Control Statements

BREAK  (immediately leave loop)

CHAIN  (execute another program)

CYCLE  (go to top of loop)

DO  (call a ROUTINE)

EXIT  (leave a ROUTINE)

GOTO  (go to a label)

HALT  (exit program)

IDLE  (arm periodic procedure)

NOTIFY  (critical error handling)

RETURN  (return to caller)

RUN  (execute command)

STOP  (suspend program execution)


Control Structures

CASE  (conditional execution structure)

EXECUTE  (statement selection structure)

IF  (conditional execution structure)

LOOP  (iteration structure)


CASE  (conditional execution structure)

CASE condition
OF expression [TO expression]
  statements
[OROF expression [TO expression] ]
  statements
[ELSE]
  statements
END

CASE	Initiates a selective execution structure.

condition	A numeric or string variable or expression.

OF	The statements following an OF are executed when the expression following the OF option is equal to the condition of the CASE.  There may be many OF options in a CASE structure.

expression	A numeric or string constant, variable, or expression.

TO	TO allows a range of values in an OF or OROF.  The statements following the OF (or OROF) are executed if the value of the condition falls within the inclusive range specified by the expressions.  The expression following OF (or OROF) must contain the lower limit of the range.  The expression following TO must contain the upper limit of the range.

OROF	The statements following an OROF are executed when either the expression following the OROF or the OF option is equal to the condition of the CASE.  There may be many OROF options associated with one OF option.  An OROF may optionally be put on a separate line.  An OROF does not terminate preceding statements groups, so control "falls into" the OROF statements.

ELSE	The statements following ELSE are executed when all preceding OF and OROF options have been evaluated as not equivalent.  ELSE is not required; however, when used, it must be the last option in the CASE structure.

statements	Any valid Clarion executable source code.

A CASE structure selectively executes statements based on equivalence between the condition and expression or range of expressions.  CASE structures may be nested within other executable structures and other executable structures may be nested within CASE structures.

Example:

CASE ACCEPTED() 	!Evaluate field edit routine

OF ?Name	!If field is Name

  ERASE(?Address,?Zip)	!  erase Address through Zip

  GET(NameFile,NameKey)	!  get the record

  CASE Action	!Evaluate Action

  OF 1	!  adding record - does not exist

    IF NOT ERRORCODE()	!  should be a file error

      ErrMsg = 'ALREADY ON FILE'	!    otherwise display error message

      DISPLAY(?Address,?Zip)	!    display address through zipcode

      SELECT(?Name)	!    re-enter the name

    END	!  end if

  OF 2 OROF 3	!  change or delete - record exists

    DISPLAY(?Address,?Zip)	!    display address through zipcode

  END	!  end case action

  CASE Name[1] 	!Get first letter of name

  OF 'A' TO 'M'	!Process first half of alphabet

  OROF 'a' TO 'm'

    DO FirstHalf

  OF 'N TO 'Z' OROF 'n' TO 'z'	!Process second half of alphabet

    DO SecondHalf

  END	!End case sub(name

OF ?Address	!If field is address

  DO AddressVal	!  call validation routine

END	!End case accepted()


EXECUTE  (statement selection structure)

EXECUTE expression
  statement 1
  statement 2
  [BEGIN
statements
  END]
  statement n
END

EXECUTE	Initiates a single statement execution structure.

expression	A numeric expression or a variable that contains a numeric integer.

statement 1	A single statement that executes only when the expression is equal to 1.

statement 2	A single statement that executes only when the expression is equal to 2.

BEGIN	BEGIN marks the beginning of a structure containing a number of lines of code.  The BEGIN structure will be treated as a single statement by the EXECUTE structure.  The BEGIN structure is terminated by a period or the keyword END.

statement n	A single statement that executes only when the expression is equal to n.

An EXECUTE structure selects a single executable statement (or executable code structure) based on the value of the expression.  If expression equals 1, the first statement (statement 1) executes.  If expression equals 2, the second statement (statement 2) executes, and so on.  If the value of expression is zero or greater than the total number of statements (or structures) within the EXECUTE structure, the EXECUTE is ignored.

EXECUTE structures may be nested within other executable structures and other executable structures (IF, CASE, LOOP, EXECUTE, and BEGIN) may be nested within an EXECUTE.

Example:

EXECUTE Transact	!Evaluate Transact

  ADD(Customer)	!Execute if Transact = 1

  PUT(Customer)	!Execute if Transact = 2

  DELETE(Customer)	!Execute if Transact = 3

END	!End execute

EXECUTE CHOICE()	!Evaluate CHOICE() function

  OrderPart	!Execute if CHOICE() = 1

  BEGIN	!Execute if CHOICE() = 2

    SavVendor" = Vendor

    UpdVendor

    IF Vendor <> SavVendor"

      Mem:Message = 'VENDOR NAME CHANGED'

  . .

  CASE VendorType	!Execute if CHOICE() = 3

    OF 1

      UpdPartNo1

    OF 2

      UpdPartNo2

  END

  RETURN	!Execute if CHOICE() = 4

END	!End execute

See Also:

BEGIN


IF  (conditional execution structure)

IF logical expression [THEN]
  statements
[ELSIF logical expression] [THEN]
  statements
[ELSE]
  statements
END

IF	Initiates a conditional statement execution structure.

logical

 expression	A numeric or string variable, expression, or function.  A logical expression evaluates a condition.  Control is determined by the result (true or false) of the expression.  A zero (or blank) value evaluates as false, anything else is true.

THEN	The statements following THEN are executed when the preceding logical expression is evaluated as true.  If used, THEN must only be placed on the same line as the IF or ELSIF.

statements	An executable statement, or a sequence of executable statements.

ELSIF	The logical expression following an ELSIF is evaluated only when all preceding IF or ELSIF conditions were evaluated as false.

ELSE	The statements following ELSE are executed when all preceding IF and ELSIF options were evaluated as false.  ELSE is not required, however, when it is used, it must be the last option in the IF structure.

An IF structure controls program execution based on the outcome of one or more logical expressions.  IF structures may have any number of ELSIF THEN statement groups.  IF structures may be "nested" within other executable structures, and other executable structures may be nested within an IF structure.

Example:

IF Cus:TransCount = 1	!If new customer

  AcctSetup	!  call account setup procedure

ELSIF Cus:TransCount > 10 AND Cus:TransCount < 100	!If regular customer

  DO RegularAcct	!  process the account

ELSIF Cus:TransCount > 100	!If special customer

  DO SpecialAcct	!  process the account

ELSE	!Otherwise

  DO NewAcct	!  process the account

  IF Cus:Credit THEN CheckCredit ELSE CLEAR(Cus:CreditStat). !  verify credit status

END	!End if

IF ERRORCODE() THEN ErrHandler(Cus:AcctNumber,Trn:InvoiceNbr).	!Handle errors


LOOP  (iteration structure)

count TIMES
LOOP [	 i = initial TO limit [BY step]	 ]
  UNTIL logical expression
  WHILE logical expression
  statements
END

LOOP	Initiates an iterative statement execution structure.

count	A numeric constant, variable, or expression that determines the number of TIMES the statements in the LOOP are executed.

TIMES	Executes count number of iterations of the statements.

i	The label of a variable which is automatically incremented on each iteration of the LOOP.

=	Assigns a new value to the increment ( i ) variable for each cycle of the LOOP.

initial	A numeric constant, variable, or expression that specifies the initial value assigned to the increment variable ( i ) on the first pass through the LOOP structure.

TO	A syntax conjunctive for the limit parameter.

limit	When i is greater than limit, the LOOP structure control sequence terminates.

BY	A syntax conjunctive for the step parameter.

step	A numeric constant, variable, or expression.  The step determines the quantity by which the i variable increments on each iteration of the LOOP.  If the BY step parameter is omitted, i increments by 1.

UNTIL	Evaluates the logical expression before each iteration of the LOOP.  If the logical expression evaluates to true, the LOOP control sequence terminates.

WHILE	Evaluates the logical expression before each iteration of the LOOP.  If the logical expression evaluates to false, the LOOP control sequence terminates.

logical

 expression	A numeric or string variable, expression, or function.  A logical expression evaluates a condition.  Control is determined by the result (true or false) of the expression.  A zero (or blank) value evaluates as false, anything else is true.

statements	An executable statement, or a sequence of executable statements.

A LOOP structure repetitively executes the statements within its structure.  LOOP conditions are always evaluated at the top of the LOOP, before the LOOP is executed.  LOOP structures may be nested within other executable code structures, and other executable code structures may be nested within a LOOP.

A LOOP with no parameters iterates continuously, unless a BREAK or RETURN statement is executed.  BREAK discontinues the LOOP and continues program execution with the statement following the LOOP structure.  All statements within a LOOP structure are executed unless a CYCLE statement is executed.  CYCLE immediately sends program execution back to the top of the LOOP for the next iteration, without executing any statements following the CYCLE in the LOOP.

Example:

LOOP	!Continuous loop

  Char = GetChar()	!  get a character

  IF Char <> CarrReturn	!  if it's not a carriage return

    Field = CLIP(Field) & Char	!    append the character

  ELSE	!  otherwise

    BREAK	!    break out of the loop

. .	!End if, end loop

IF ERRORCODE()	!On error

  LOOP 3 TIMES	!  loop three times

    BEEP	!    sound the alarm

. .	!End loop, end if

LOOP I# = 1 TO 365 BY 7	!Loop, increment I# by 7 each time

  GET(DailyTotal,I#)	!  read every 7th record

  DO WeeklyJob	!  do the routine

END	!End loop

SET(MasterFile)	!Point to first record

LOOP UNTIL EOF(MasterFile)	!Process all the records

  NEXT(MasterFile)	!  read a record

  ProcMaster	!  call the procedure

END

LOOP WHILE KEYBOARD()	!Empty the keyboard buffer

  ASK	! without processing keystrokes

END	!End loop

See Also:

BREAK

CYCLE


Control Statements

BREAK  (immediately leave loop)

CHAIN  (execute another program)

CYCLE  (go to top of loop)

DO  (call a ROUTINE)

EXIT  (leave a ROUTINE)

GOTO  (go to a label)

HALT  (exit program)

IDLE  (arm periodic procedure)

NOTIFY  (critical error handling)

RETURN  (return to caller)

RUN  (execute command)

STOP  (suspend program execution)


BREAK  (immediately leave loop)

BREAK

The BREAK statement immediately terminates the LOOP or ACCEPT loop and transfers control to the first statement following the LOOP or ACCEPT loop structure.  BREAK may only be used in a LOOP or ACCEPT loop structure.

Example:

LOOP	!Loop

  ASK	!  wait for a keystroke

  IF KEYCODE() = 256	!  if Esc key pressed

    BREAK	!    break out of the loop

  ELSE	!  otherwise

    BEEP	!    sound the alarm

  END	!End if

END	!End loop

ACCEPT	!Loop

  CASE ACCEPTED()

  OF ?Ok

    CallSomeProc

  OF ?Cancel

    BREAK	!    break out of the loop

  END	!End case

END	!End ACCEPT loop

See Also:

CYCLE

LOOP

ACCEPT


CHAIN  (execute another program)

CHAIN(program)

CHAIN	Terminates the current program and executes another.

program	A string constant or variable containing the name of the program to execute.  This may be any .EXE or .COM program.

CHAIN terminates the current program, closing all files and returning its memory to the operating system, and executes another program.

Example:

PROGRAM	!MainMenu program code

  CODE

  EXECUTE CHOICE()

    CHAIN('Ledger')    !Execute LEDGER.EXE

    CHAIN('Payroll')    !Execute PAYROLL.EXE

    RETURN      !Return to DOS

  END

  	PROGRAM        !Ledger program code

  CODE

  EXECUTE CHOICE()

    CHAIN('MainMenu')    !Return to MainMenu program

    RETURN      !Return to DOS

  END

 	PROGRAM        !Payroll program code

  CODE

  EXECUTE CHOICE()

    CHAIN('MainMenu')    !Return to MainMenu program

    RETURN      !Return to DOS

  END


CYCLE  (go to top of loop)

CYCLE

The CYCLE statement passes control immediately back to the top of the LOOP or ACCEPT loop, where the LOOP condition is evaluated.  CYCLE may only be used in a LOOP or ACCEPT loop structure.

Example:

SET(MasterFile)	!Point to first record

LOOP 	!Process all the records

  NEXT(MasterFile)	!  read a record

  IF ERRORCODE() THEN BREAK.	!Get out of loop at end of file

  DO MatchMaster	!  check for a match

  IF NoMatch	!  if match not found

    CYCLE	!    jump to top of loop

  END	!  end if

  DO TransVal	!  validate the transaction

  PUT(MasterFile)	!  write the record

END	!End loop

See Also:

LOOP

BREAK


DO  (call a ROUTINE)

DO label

DO	Executes a ROUTINE.

label	The label of a ROUTINE statement.

The DO statement is used to execute a ROUTINE local to a PROGRAM, PROCEDURE, or FUNCTION.  When a ROUTINE completes execution, program control reverts to the statement following the DO statement.  A ROUTINE may only be called within the CODE section containing the ROUTINE's source code.

Example:

DO NextRecord	!Call the next record routine

DO CalcNetPay	!Call the calc net pay routine


EXIT  (leave a ROUTINE)

EXIT

The EXIT statement immediately leaves a ROUTINE and returns program control to the statement following the DO statement that called it.  An EXIT statement is not required.  A ROUTINE with no EXIT statement terminates automatically when the entire sequence of statements in the ROUTINE is complete.

Example:

CalcNetPay	ROUTINE

  IF GrossPay = 0	!If no pay

    EXIT	!  exit the routine

  END

  NetPay = GrossPay - FedTax - Fica

  QtdNetPay += NetPay

  YtdNetPay += NetPay


GOTO  (go to a label)

GOTO label

GOTO	Unconditionally transfers program control to another statement.

label	The label of another executable statement within the PROGRAM, PROCEDURE, FUNCTION, or ROUTINE.

The GOTO statement unconditionally transfers control from one statement to another.  The target label of a GOTO must not be the label of a ROUTINE, PROCEDURE, or FUNCTION.

The scope of GOTO is limited to the currently executing ROUTINE, PROCEDURE, or FUNCTION; it may not target a label outside the ROUTINE, PROCEDURE, or FUNCTION in which it is used.

Example:

ComputeIt	FUNCTION(Level)

  CODE

  IF Level = 0 THEN GOTO PassCompute.	!Skip rate calculation if no Level

  Rate = Level * MarkUp	!Compute Rate

  RETURN(Rate)	! and return it

PassCompute	 RETURN(999999)	!Return bogus number


HALT  (exit program)

HALT([errorlevel] [,message])

HALT	Immediately terminates the program.

errorlevel	A positive integer constant or variable (range: 0 - 250) which is the exit code to pass to DOS, setting the DOS ERRORLEVEL.  If omitted,the default is zero.

message	A string constant or variable which is typed on the screen after program termination.

The HALT statement immediately returns to DOS, setting the errorlevel and optionally displaying a message after the program terminates.

If the program being HALTed was launched by a RUN or RUNSMALL statement within another Clarion program, the errorlevel exit code HALT sets may be determined by using the RUNCODE function in the launching program.

Example:

PasswordProc	PROCEDURE

Password	STRING(10)

Window	WINDOW,CENTER

  ENTRY(@s10),AT(5,5),USE(Password),HIDE

END

  CODE

  OPEN(Window)

  ACCEPT

    CASE ACCEPTED()

    OF ?Password)

      IF Password <> 'Pay$MeMoRe'

        HALT(0,'Incorrect Password entered.')

      END

    END

  END

See Also:

RUN

RUNCODE


IDLE  (arm periodic procedure)

IDLE([procedure] [,separation])

IDLE	Arms a procedure that periodically executes.

procedure	The label of a PROCEDURE.  The procedure may not take any parameters.

separation	An integer that specifies the minimum wait time (in seconds) between calls to the procedure.  A separation of 0 specifies continuous calls.  If separation is omitted, the default value is 1 second.

An IDLE procedure is active while an ASK or ACCEPT statement is waiting for user input.  Only one IDLE procedure may be active at a time.  Naming a new IDLE procedure overrides the previous one.  An IDLE statement with no parameters disarms the IDLE process.

An IDLE procedure is usually prototyped in the PROGRAM's MAP (not a MEMBER MAP).  If prototyped in a MEMBER MAP, the IDLE statements which activate and de-activate it must be contained in a procedure or function within the same MEMBER module.

Example:

IDLE(ShoTime,10)	!Call shotime every 10 seconds

IDLE(CheckNet)	!Check network activity every 1 second

IDLE	!Disarm idle procedure

See Also:

ASK

ACCEPT

PROCEDURE

MAP


NOTIFY  (critical error handling)

NOTIFY(procedure,event)

NOTIFY	Arms a procedure to handle DOS critical errors.

procedure	The label of a PROCEDURE.  Its prototype must be declared in the MAP as receiving a *STRING parameter (a STRING passed by address).

event	An integer constant, variable, or expression.  If zero, the NOTIFY procedure is disarmed; if one, DOS critical errors will be handled by the procedure.

The NOTIFY statement arms a procedure to handle DOS critical errors.  This procedure receives a *STRING parameter, which is internally passed to it by address when a critical error occurs.

The purpose of the procedure is to allow a Clarion application to handle the critical error.  The procedure may perform disk operations or any other operation.  The procedure must RETURN normally (RESTART is not recommended) and must select a return value which DOS allows for that specific error.

The STRING parameter passed by address to the procedure should first be assigned to a GROUP, to eliminate the necessity of parsing the string for the error information.  The GROUP may be defined globally (Global Static data), or local to the MEMBER module (Local Static data), to minimize the amount of memory allocation on the stack.  The GROUP should be defined with the following fields:

CritParmGroup	GROUP,PRE(Crt)	!Parameter group definition

Status	  LONG	!Processing status, 1 for critical errors

CritType	  SHORT	!Critical error code, 1-12, 15

CritMsg	  STRING(25)	!Critical error description

CritDev	  STRING(25)	!Error device name string

RetVal	  STRING(1)	!Return value - A, I, R, or F

END

The possible DOS Critical Errors that can be handled by the procedure:

CritType	CritMsg

 0	Write protect error

 1	Invalid drive number

 2	Drive not ready

 3	Unknown command requested

 4	Data error (CRC)

 5	Bad request structure length

 6	Seek error

 7	Unknown disk format

 8	Sector not found

 9	Printer out of paper

10	Write fault

11	Read fault

12	General, non-specific error

15	Invalid disk change

After assignment of the passed parameter STRING to the GROUP, the procedure may determine which error occurred through the values in CritType (the error number), CritMsg (the error description), and CritDev (the offending device).  It may then determine which option to choose for the particular error and assign that value to RetVal.

Valid RetVal values:

 I	Ignore

 R	Retry

 A	Abort

 F	Fail

The value in RetVal at the end of the procedure determines how the error is handled.  The option chosen is returned by assigning the GROUP back to the passed *STRING parameter at the end of the procedure.

Example:

This example code contains two examples of critical error handlers.  PrinterReady is printer-specific, and ErrorProc is a generic error handler.

PROGRAM

MAP

  PrintReport	!A print procedure

  PrinterReady(*STRING)	!Printer ready error handler

  ErrorProc(*STRING)	!Generic error handler prototype

END

CritParmGroup GROUP,PRE(Crt)	!Parameter group definition

Status	  LONG(1)	!Processing status, always 1

CritType	  SHORT(0)	!Critical error code, 1-12, 15

CritMsg	  STRING(25)	!Critical error description

CritDev	  STRING(25)	!Error device name string

RetVal	  STRING(1)	!Action option chosen - A, I, R, or F

END

ErrFlag	BYTE(0)	!Error occurrence flag

  CODE

  PrintReport	!Call report procedure

  NOTIFY(ErrorProc,1)	!Arm Generic Error Handler

!Other executable code goes here

PrintReport	PROCEDURE

!Report format declaration goes here

ErrScreen	WINDOW('Printer Error'),CENTER,MODAL

  STRING('Printer Error -- Check Printer')

END

  CODE

  NOTIFY(PrinterReady,1)	!Arm printer error handler

!The rest of the report code goes here

! and somewhere within it is :

  IF ErrFlag	!Did critical error occur?

    OPEN(ErrScreen)	!  display screen

    ASK	!  wait for keystroke

    ErrFlag = 0	!  reset error flag

    RETURN	!  and bail out

  END

PrinterReady	PROCEDURE(ParmString)	!Specific Error Handler

  CODE

  ErrFlag = 1	!A critical error occurred

  CritParmGroup = ParmString 	!Get the error

  Crt:RetVal = 'F'	!Fail the error

  ParmString = CritParmGroup	!Re-assign parameter string

ErrorProc 	PROCEDURE(ParmString) 	!Generic Critical Error Handler

Opt 	STRING(1) 	!Allocated on stack

ErrScreen	WINDOW,CENTER,MODAL

  STRING('Error:')

  STRING(@S25),USE(Crt:CritMsg)

  STRING(@S25),USE(Crt:CritDev)

  STRING('Options: Abort  Retry  Ignore  Fail')

END

  CODE

  CritParmGroup = ParmString 	!Get error information

  OPEN(ErrScreen)	!Open the screen

  LOOP	!Loop to input valid choice

    ASK	!Get a keystroke

    Opt = UPPER(CHR(KEYCODE()))

    IF Opt <> 'A' AND Opt <> 'R' AND Opt <> 'I' AND Opt <> 'F'

!If not valid option

      BEEP	!  alert user

      CYCLE	!  to re-enter option

    ELSE	!Otherwise

      BREAK	!  continue

  . .	!End if, end loop

  Crt:RetVal = Opt	!Put user's option in CritParmGroup

  ParmString = CritParmGroup	!Re-assign parameter string


RETURN  (return to caller)

RETURN( [expression] )

RETURN	Terminates a PROGRAM, PROCEDURE, or FUNCTION.

expression	The expression passes the return value of a FUNCTION back to the expression in which the FUNCTION was used.  The expression is required for a FUNCTION and may not be used in a PROCEDURE or PROGRAM.

The RETURN statement terminates a PROGRAM, PROCEDURE, or FUNCTION, and passes control back to the caller.  When RETURN is executed from the CODE section of a PROGRAM, the program is terminated, all files and windows are closed, and control is passed to the operating system.

RETURN is required in a FUNCTION and optional in a PROCEDURE or PROGRAM.  If RETURN is not used in a PROCEDURE or PROGRAM, an implicit RETURN occurs at the end of the executable code.  The end of executable code is defined as the end of the source file, or the beginning of another PROCEDURE, FUNCTION, or ROUTINE.

RETURN from a PROCEDURE or FUNCTION (whether explicit or implicit) automatically closes any local APPLICATION, WINDOW, or REPORT structure opened in the PROCEDURE or FUNCTION.  It does not automatically close any Global or Module Static APPLICATION, WINDOW, or REPORT.

Example:

  IF Done# THEN RETURN.	!Quit when done

DayOfWeek	FUNCTION(Date)	!Function to return the day of the week

  CODE

  EXECUTE (Date % 7) + 1	!Determine what day of week Date is

    RETURN('Sunday')	!  and RETURN the correct day string

    RETURN('Monday')

    RETURN('Tuesday')

    RETURN('Wednesday')

    RETURN('Thursday')

    RETURN('Friday')

    RETURN('Saturday')

  END


RUN  (execute command)

RUN(command [,screen save] [,pause message])

RUN	Executes a command as if it were entered on the DOS command line.

command	A string constant or variable containing the command.

screen save	An integer constant or variable, in the range 0-3, which defines the screen save characteristics of the RUN statement.  If omitted, the default value is zero.

pause message	A string constant or variable containing the message to display while RUN is paused before restoring the saved screen.  This is only valid if the value of the screen save parameter is set to three (3).  If omitted, the pause message "Press any key to continue" is displayed.

The RUN statement executes a command as if it were entered on the DOS command line.  When the command has executed, control returns to the statement following the RUN statement.

RUN closes all files, saves the screen (if a second parameter is specified), and writes a memory image of the program to a DOS temporary filename with a .RUN extension.  This provides unique file names for multiple temporary RUN files.  The temporary file is written to disk in the current drive and directory, unless a 'CLATMP=' environment variable has been specified.  CLATMP specifies a drive and directory for any Clarion temporary files.  This may be a RAM drive (512K or more is recommended).  The DOS command SET CLATMP=D:\ specifies the root directory of D: as the temporary file directory.

The screen save action RUN takes is dependent upon the value placed in the second parameter:

0 -	The command is executed without saving or restoring the screen.

1 -	The screen is saved before the command is executed and restored upon return from the command.

2 -	The screen is saved then blanked before the command is executed.  The saved screen is restored upon return from the command.

3 -	The screen is saved then blanked before the command is executed.  After the command is executed, the pause message is displayed until the user presses a key, then the saved screen is restored.

RUN does not automatically load a second copy of COMMAND.COM.  Therefore, the command must load it, if needed.  COMMAND.COM is needed for DOS internal commands, .BAT files, or a command that should search the DOS PATH for the program to RUN.  If the command program is in the current directory, or the path is specified, a second copy of COMMAND.COM is not necessary.  However, without COMMAND.COM, the command must include the extension (.EXE or .COM).

When the command has been executed, the temporary file is reloaded in memory and execution of the program continues from the statement following the RUN statement.  As the program is restored to memory, all files are re-opened with the same access mode they had before the RUN, and the saved screen is restored.  The temporary file must be reloaded in the same place in memory the program was previously loaded, therefore, using RUN to load a Terminate and Stay Resident (TSR) program is not allowed.  Since RUN closes all files then re-opens them, the current state of each file (processing order and current record pointer) is lost.  Therefore, executing a RUN statement during sequential file access is not recommended.

The successful execution of the command may be verified with the RUNCODE function, which returns the DOS exit code of the command.  If unsuccessful, RUN posts the error to the ERROR and ERRORCODE functions.

Errors Posted:

RUN may post any possible error (see Appendix B)

Example:

RUN('\command.com /c dir',3,'Press any key to return')

!Run the DOS directory command with pause

RUN('\command.com /c c:\wp51\wp.exe',1)	!Run WordPerfect, save and restore screen

RUN(ProgName,1)	!Run the command in the ProgName variable

See Also:

RUNCODE


STOP  (suspend program execution)

STOP([message])

STOP	Suspends program execution and displays a message window.

message	An optional string expression (up to 64K) which displays in the error window.

STOP suspends program execution and displays a message window.  It offers the user the option of continuing the program or exiting.  When exiting, it closes all files and frees the allocated memory.

Example:

PswdScreen	WINDOW

  STRING(' Please Enter the Password '),AT(5,5)

  ENTRY(@10),AT(20,5),USE(Password),HIDE	!Password storage field

END

  CODE

  OPEN(PswdScreen)	!Open the password screen

  ACCEPT	!  and get user input

    CASE ACCEPTED

    OF ?Password)

      IF Password <> 'PayMe$moRe'	!Correct password?

        LOOP;STOP('Incorrect Password Entered -- Access Denied').

      END	!If not, throw them out

    END

  END


Window Structures

Clarion Windows

Window Overview

Control Fields and Input Focus

Field Equate Labels

Window Structures

APPLICATION  (declare an MDI frame window)

WINDOW  (declare a dialog window)

APPLICATION and WINDOW Attributes

ALRT  (set window "hot" keys)

AT  (set window position and size)

CENTER  (set position and size)

CURSOR  (set mouse cursor type)

DOUBLE, NOFRAME, RESIZE  (set window border)

FONT  (set window default font)

GRAY  (set 3-D look background)

HLP  (set window's on-line help identifier)

HSCROLL, VSCROLL, HVSCROLL  (set window scroll bars)

ICON  (set window icon)

ICONIZE  (set window open as icon)

MASK  (set pattern editing data entry)

MAX  (set maximize control)

MAXIMIZE  (set window open maximized)

MDI  (set Multiple Document Interface)

MODAL  (set system modal window)

MSG  (set window status bar message)

PALETTE  (set number of hardware colors)

STATUS  (set status bar)

SYSTEM  (set system menu)

THOUS, MM, POINTS  (set screen coordinate measure)

TOOLBOX  (set toolbox window behavior)

TIMER  (set periodic event)

MENUBAR and TOOLBAR Structures

MENUBAR  (declare a pulldown menu)

TOOLBAR  (declare a tool bar)

MENUBAR and TOOLBAR Attributes

CURSOR  (set toolbar mouse cursor type)

FONT  (set toolbar default font)

NOMERGE  (set merging behavior)

MENUBAR Controls

MENU  (declare a menu box)

ITEM  (declare a menu item)

TOOLBAR and WINDOW Control Fields

BOX  (declare a window box control)

BUTTON  (declare a pushbutton control)

CHECK  (declare a window checkbox control)

COMBO  (declare an entry/list control)

CUSTOM  (declare a window .VBX custom control)

ELLIPSE  (declare a window ellipse control)

ENTRY  (declare a data entry control)

GROUP  (declare a group of window controls)

IMAGE  (declare a window graphic image control)

LINE  (declare a window line control)

LIST  (declare a window list control)

OPTION  (declare a group of window RADIO controls)

PROMPT  (declare a prompt control)

RADIO  (declare a window radio button control)

REGION  (declare a window region control)

SPIN  (declare a spinning list control)

STRING  (declare a window string control)

TEXT  (declare a multi-line data entry control)

Control Field Attributes

ALRT  (set control "hot" keys)

AT  (set control position and size in window)

BOXED  (set window controls group border)

CAP, UPR  (set display case)

CHECK  (set on/off ITEM)

CLASS  (set .VBX custom control class)

COLOR  (set control display color)

COLUMN  (set list box highlight bar)

CURSOR  (set control mouse cursor type)

DEFAULT  (set enter key button)

DISABLE  (set control dimmed at open)

DROP  (set list box behavior)

DRAGID  (set drag-and-drop host signatures)

DROPID  (set drag-and-drop target signatures)

FILL  (set display fill color)

FIRST, LAST  (set MENU or ITEM position)

FONT  (set control font)

FORMAT  (set LIST or COMBO layout)

FROM  (set window listbox data source)

FULL  (set full-screen)

HIDE  (set control hidden at open)

HLP  (set control's on-line help identifier)

HSCROLL, VSCROLL, HVSCROLL  (set control scroll bars)

ICON  (set control icon)

IMM  (set immediate event notification)

INS, OVR  (set typing mode)

KEY  (set control execution keycode)

LEFT, RIGHT, CENTER, DECIMAL  (set display justification)

MARK  (set multiple selection mode)

MSG  (set control status bar message)

NOBAR  (set no highlight bar)

PASSWORD  (set data non-display)

RANGE  (set SPIN range limits)

READONLY  (set display-only)

REQ  (set required entry)

RIGHT  (set MENU position)

ROUND  (set round-cornered window BOX)

SCROLL  (set scrolling control)

SEPARATOR  (set separator line ITEM)

SKIP  (set Tab key skip)

STD  (set standard behavior)

STEP  (set SPIN increment)

TRN  (set transparent window string)

USE  (set control variable or equate label)

VCR  (set VCR control)


Clarion Windows

Window Overview

Control Fields and Input Focus

Field Equate Labels


Window Overview

In most Windows programs there are three types of screen windows used:  application windows, document windows, and dialog boxes.  An application window is the first window opened in a Windows program, and it usually contains the main menu as the entry point to the rest of the program.  All other windows in the program are document windows or dialog boxes.

Along with these three screen window types, there are two user interface design conventions that are used in Windows programs:  the Single Document Interface (SDI), and the Multiple Document Interface (MDI).

An SDI program usually only contains linear logic that allows the user to take only one execution path (thread) at a time; it does not open separate execution threads which the user may move between.  This is the same type of program logic used in most DOS programs.  An SDI program would not contain a Clarion APPLICATION structure as its application window.  The Clarion WINDOW structure (without an MDI attribute) is used to define an SDI program's application window, and the subsequent document windows or dialog boxes opened on top of it.

An MDI program allows the user to choose multiple execution paths (threads) and change from one to another at any time.  This is a very common Windows program user interface.  It is used by applications as a way of organizing and grouping windows which present several execution paths for the user to take.

A Clarion APPLICATION structure defines the MDI application window.  The MDI application window acts as a parent for all the MDI child windows (document windows and dialog boxes), in that the child windows are clipped to its frame and automatically moved when the application frame is moved.  They can also be concealed en masse by minimizing the parent.  There may be only one APPLICATION open at any time in a Clarion Windows program.

Document windows and dialog boxes are very similar in that they are both defined as Clarion WINDOW structures.  They differ in the conventional context in which they are commonly used and the conventions regarding appearance and attributes.  In many cases, the difference is not distinguishable and does not matter.  The generic term for both document windows and dialog boxes is "window" and that is what will be used throughout this reference.

Document windows usually display data.  By convention they are movable and resizable.  They usually have a title, a system menu, and maximize button.  For example, in the Windows environment, the "Main" program group window that appears when you DOUBLE-CLICK on the "Main" icon in the Program Manager's desktop, is a document window.

Dialog boxes usually request information from the user or alert the user to some condition, usually prior to performing some action requested by the user.  They may or may not be movable, and so, may or may not have a system menu and title.  By convention, they are not resizable, although they can have a maximize button which gives the dialog two alternate sizes.  A dialog box may be system modal (the user must respond before doing anything else in Windows), application modal (the user must respond before doing anything in the application), or modeless.  For example, in the Clarion environment, the window that appears from the File menu's Open selection is an application modal  dialog box that requests the name of the file to open.


Control Fields and Input Focus

The objects placed in an APPLICATION or WINDOW structure are "control fields."  "Control" is a standard Windows term used to refer to any screen object command buttons, text entry fields, radio buttons, list boxes, etc.  In most DOS programs, the term "field" is usually used to refer to these objects.  In this document, the terms "control" and "field" are generally interchangeable.

Controls appear only in MENUBARs, TOOLBARs, or WINDOW structures.  Controls are available to the user to select and/or edit the data they contain only when it has "input focus."  This occurs when the user uses the TAB key, the mouse, or an accelerator key combination to highlight the control.

A WINDOW also has "input focus" when it is the top WINDOW in the currently active execution thread.  Since Clarion for Windows allows multi-threaded programs, the concept of which WINDOW currently has focus is important.  Only the thread whose uppermost WINDOW has focus is active.  The user may edit data in the WINDOW's control fields only when it has focus.


Field Equate Labels

In WINDOW structures, every control field with a USE variable is assigned a field number by the compiler.  By default, these field numbers begin with one (1) and are assigned to controls in the order they appear in the WINDOW structure code.  The actual assigned numbers can be overridden by the second parameter of the USE attribute.  The order of appearance in code determines the "natural" selection order of control fields for the ACCEPT structure (which may be altered with the SELECT statement).  The order of appearance in code is independent of the control's placement on the screen.  Therefore, there is not necessarily any correlation between a control's position on screen and the field number assigned by the compiler.

There are a number of statements that use these field numbers as parameters.  It would be very tedious to "hard code" these numbers in order to use these statements.  Therefore, Clarion provides a mechanism to address this problem: Field Equate Labels.

Field Equate Labels always begin with a question mark (?) followed by the name of the control's USE variable.  The leading question mark indicates to the compiler a Field Equate Label.  They are very similar to normal EQUATE compiler directives.  The compiler substitutes the field number for the Field Equate Label at compile time.  This makes it unnecessary to know field numbers in advance.

Field Equate Labels for USE variables which are array elements always begin with a question mark ( ? ) followed by the name of the USE variable followed by an underscore and a number (?ArrayField_1).  Array elements from the same array are incrementally numbered beginning with one (1) for each element used in the same structure (?ArrayField_1, ?ArrayField_2, ...).

Two or more controls with exactly the same USE variable in one WINDOW or APPLICATION structure would create the same Field Equate Label for all.  Therefore, when the compiler encounters this condition, all Field Equate Labels for that USE variable are discarded.  This makes it impossible to reference any of these controls in executable code, preventing confusion about which control you really want to reference.  It also allows you to deliberately create this condition to display the contents of the variable in multiple controls using different display pictures.  Some fields may have USE variables that can only be Field Equate Labels (a unique label with a leading question mark).  This provides a way of referencing these fields in code statements.

In APPLICATION structures, every menu selection in the MENUBAR, and every control with a USE variable placed in the TOOLBAR, is assigned a number by the compiler.  By default, these numbers begin with negative one (-1) and are decremented by one (1) in the order the menu selections and controls appear in the APPLICATION structure code.


Window Structures

APPLICATION  (declare an MDI frame window)

WINDOW  (declare a dialog window)


APPLICATION  (declare an MDI frame window)

label	APPLICATION('title') [,AT( )] [,CENTER] [,SYSTEM] [,MAX] [,ICON( )]
[,STATUS( )] [,HLP( )] [,CURSOR( )] [,TIMER( )] [,ALRT( )] [,ICONIZE]
[,MAXIMIZE] [,MASK] [,FONT( )] [,MSG( )]
[,	 HSCROLL	 ] [,	 DOUBLE	 ] [,	 THOUS	 ]
 VSCROLL	 NOFRAME	 MM
 HVSCROLL	 RESIZE	 POINTS
  [ MENUBAR
      multiple menu and/or item declarations
    END ]
  [ TOOLBAR
      multiple control field declarations
    END ]
END

APPLICATION	Declares a Multiple Document Interface (MDI) frame window.

label	A valid Clarion label.  A label is required on the APPLICATION statement.

title	Specifies the title text for the application window.

AT	Specifies the initial size and location of the application window.  If omitted, default values are selected by the runtime library.

CENTER	Specifies that the window's initial position is centered in the screen by default.  This attribute takes effect only if at least one parameter of the AT attribute is omitted.

SYSTEM	Specifies the presence of a system menu.

MAX	Specifies the presence of a maximize control.

ICON	Specifies the presence of a minimize control, and names a file or standard icon identifier for the icon displayed when the window is minimized.

STATUS	Specifies the presence of a status bar at the base of the application window.

HLP	Specifies the "Help ID" associated with the APPLICATION window and provides the default for any child windows.

CURSOR	Specifies a mouse cursor to be displayed when the mouse is positioned over the APPLICATION window.  If omitted, the Windows default cursor is used.

TIMER	Specifies periodic timed event generation.

ALRT	Specifies "hot" keys active for the entire APPLICATION.

ICONIZE	Specifies the APPLICATION is minimized to an icon when opened.

MAXIMIZE	Specifies the APPLICATION is maximized when opened.

MASK	Specifies pattern input editing mode of all ENTRY controls in the TOOLBAR.

FONT	Specifies the default font for all controls in the toolbar.

MSG	Specifies a string constant containing the default text to display in the status bar for all controls in the APPLICATION.

HSCROLL	Specifies that a horizontal scroll bar is automatically added to the application frame when any portion of a child window lies horizontally outside the visible area.

VSCROLL	Specifies that a vertical scroll bar is automatically added to the application frame when any portion of a child window lies vertically outside the visible area.

HVSCROLL	Specifies that both vertical and horizontal scroll bars are automatically added to the application frame when any portion of a child window lies outside the visible area.

DOUBLE	Specifies a double-width frame around the window.  A window with this type of frame may not be resized.

NOFRAME	Specifies a window with no frame.  A window with this type of frame may not be resized.

RESIZE	Specifies a thick frame around the window which does allow window resizing.

THOUS	Specifies thousandths of an inch as the measurement unit used for all attributes which use screen coordinates.

MM	Specifies millimeters as the measurement unit used for all attributes which use screen coordinates.

POINTS	Specifies points as the measurement unit used for all attributes which use screen coordinates.  There are 72 points per inch, vertically and horizontally.

MENUBAR	Defines the menu structure (optional).  The menu specified in an APPLICATION is the "Global menu."

TOOLBAR	Defines a toolbar structure (optional).  The toolbar specified in an APPLICATION is the "Global toolbar."

APPLICATION declares a Multiple Document Interface (MDI) frame window.  MDI is a part of the standard Windows interface, and is used by Windows applications to present several "views" in different windows.  This is a way of organizing and grouping these.  The MDI frame window (APPLICATION structure) acts as a "parent" for all the MDI "child" windows (WINDOW structures with the MDI attribute).  These MDI "child" windows are clipped to the APPLICATION frame and automatically moved when the frame is moved, and can be totally concealed by minimizing the parent.

There may be only one APPLICATION window open at any time in a Clarion Windows program, and it must be opened before any MDI "child" windows may be opened.  However, non-MDI windows may be opened before or after the APPLICATION is opened, and may be on the same execution thread as the APPLICATION.  An MDI "child" window must not be on the same execution thread as the APPLICATION.  Therefore, any MDI "child" window called directly from the APPLICATION must be in a separate procedure so the START function can be used to begin a new execution thread.  Once started, multiple MDI "child" windows may be called in the new thread.

A "conventional" APPLICATION window would have the ICON, MAX, STATUS, RESIZE, and SYSTEM attributes.  This creates an application frame window with minimize and maximize buttons, a status bar, a resizable frame, and a system menu.  It would also have a MENUBAR structure containing the global menu items, and may have a TOOLBAR with "shortcuts" to global memu items.  These attributes create a standard Windows look and feel.

An APPLICATION window may not contain controls except within its MENUBAR and TOOLBAR structures, and cannot be used for any output.  For output, document windows or dialog boxes are required (defined using the WINDOW structure).  When the APPLICATION window is first opened, it remains hidden until the first DISPLAY statement or ACCEPT loop is encountered.  This enables any changes to be made to the appearance before it is displayed.  For example, the caption or size can be adjusted via runtime property assignment.

Example:

!An MDI application frame window with system menu, minimize and maximize

! buttons, a status bar, scroll bars, and a resizable frame, containing the

! main menu and toolbar for the application:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    MENU('&File'),USE(?FileMenu)

      ITEM('&Open...'),USE(?OpenFile)

      ITEM('&Close'),USE(?CloseFile),DISABLE

      ITEM('E&xit'),USE(?MainExit)

    END

    MENU('&Edit'),USE(?EditMenu)

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut),DISABLE

      ITEM('&Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy),DISABLE

      ITEM('&Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste),DISABLE

    END

    MENU('&Window'),STD(STD:WindowList),LAST

      ITEM('&Tile'),STD(STD:TileWindow)

      ITEM('&Cascade'),STD(STD:CascadeWindow)

      ITEM('&Arrange Icons'),STD(STD:ArrangeIcons)

    END

    MENU('&Help'),USE(?HelpMenu)

      ITEM('&Contents'),USE(?HelpContents),STD(STD:HelpIndex)

      ITEM('&Search for Help On...'),USE(?HelpSearch),STD(STD:HelpSearch)

      ITEM('&How to Use Help'),USE(?HelpOnHelp),STD(STD:HelpOnHelp)

      ITEM('&About MyApp...'),USE(?HelpAbout)

    END

  END

  TOOLBAR

    BUTTON('E&xit'),USE(?MainExitButton)

    BUTTON('&Open'),USE(?OpenButton),ICON(ICON:Open)

  END

END

  CODE

  OPEN(MainWin)	!Open APPLICATION

  ACCEPT	!Display APPLICATION and accept user input

    CASE ACCEPTED()	!Which control was chosen?

    OF ?OpenFile	!Open... menu selection

    OROF ?OpenButton	!Open button on toolbar

      START(OpenFileProc)	!Start new execution thread

    OF ?MainExit	!Exit menu selection

    OROF ?MainExitButton	!Exit button on toolbar

      BREAK	!Break ACCEPT loop

    OF ?HelpAbout	!About... menu selection

      HelpAboutProc	!Call application information procedure

    END

  END

  CLOSE(MainWin)	!Close APPLICATION


WINDOW  (declare a dialog window)

label	WINDOW('title') [,AT( )] [,CENTER] [,SYSTEM] [,MAX] [,ICON( )] [,STATUS( )]
[,HLP( )] [,CURSOR( )] [,MDI] [,MODAL] [,MASK] [,FONT( )] [,GRAY]
[,TIMER( )] [,ALRT( )] [,ICONIZE] [,MAXIMIZE] [,MSG( )] [,TOOLBOX]
[,PALETTE( )] [,DROPID( )]
              [,	| HSCROLL	| ] [,	| DOUBLE	| ] [,	| THOUS	| ]
| VSCROLL	|	| NOFRAME	|	| MM	|
| HVSCROLL	|	| RESIZE	|	| POINTS	|
  [ MENUBAR
      menus and/or items
    END ]
  [ TOOLBAR
      controls
    END ]
  controls
END

WINDOW	Declares a document window or dialog box.

label	A valid Clarion label.  A label is required on the WINDOW statement.

title	A string constant containing the title text for the window.

AT	Specifies the initial size and location of the window.  If omitted, default values are selected by the runtime library.

CENTER	Specifies that the window's initial position is centered on screen relative to its parent window, by default.  This attribute takes effect only if at least one parameter of the AT attribute is omitted.

SYSTEM	Specifies the presence of a system menu.

MAX	Specifies the presence of a maximize control.

ICON	Specifies the presence of a minimize control, and names a file or standard icon identifier for the icon displayed when the window is minimized.

STATUS	Specifies the presence of a status bar for the window.

HLP	Specifies the "Help ID" associated with the window.

CURSOR	Specifies a mouse cursor to be displayed when the mouse is positioned over the window.  This cursor is inherited by the WINDOW's controls unless it is overridden.

MDI	Specifies that the window conforms to normal MDI child-window behavior.

MODAL	Specifies the window is "system modal" and must be closed before the user may do anything else.

MASK	Specifies pattern input editing mode of all ENTRY controls in this window.

FONT	Specifies the default font for all controls in this window.

GRAY	Specifies that the window has a gray background for use with 3-D look controls.

TIMER	Specifies periodic timed event generation.

ALRT	Specifies "hot" keys active when the WINDOW has focus.

ICONIZE	Specifies the WINDOW is minimized to an icon when opened.

MAXIMIZE	Specifies the WINDOW is maximized when opened.

MSG	Specifies a string constant containing the default text to display in the status bar for all controls in the WINDOW.

TOOLBOX	Specifies the WINDOW is "always on top" and its controls never retain focus.

PALETTE	Specifies the number of hardware colors used for graphics in the window.

DROPID	Specifies the window may serve as a drop target for drag-and-drop actions.

HSCROLL	Specifies that a horizontal scroll bar is automatically added to the window when any scrollable portion of the window lies horizontally outside the visible area.

VSCROLL	Specifies that a vertical scroll bar is automatically added to the window when any scrollable portion of the window lies vertically outside the visible area.

HVSCROLL	Specifies that both vertical and horizontal scroll bars are automatically added to the window when any scrollable portion of the window lies outside the visible area.

DOUBLE	Specifies a double-width frame around the window.  A window with this type of frame may not be resized.

NOFRAME	Specifies a window with no frame.  A window with this type of frame may not be resized.

RESIZE	Specifies a thick frame around the window, which does allow window resizing.

THOUS	Specifies thousandths of an inch as the measurement unit used for all attributes which use screen coordinates.

MM	Specifies millimeters as the measurement unit used for all attributes which use screen coordinates.

POINTS	Specifies points as the measurement unit used for all attributes which use screen coordinates.  There are 72 points per inch, vertically and horizontally.

MENUBAR	Defines a menu structure (optional).

menus

 and/or items	MENU and/or ITEM declarations that define the menu selections.

TOOLBAR	Defines a toolbar structure (optional).

controls	Control field declarations that define tools available on the TOOLBAR, or the control fields in the WINDOW.

A WINDOW declares a document window or dialog box which may contain controls, and may be used to display output to the user.  When the WINDOW is first opened, it remains hidden until the first DISPLAY statement or ACCEPT loop is encountered.  This enables any changes to be made to the appearance before it is displayed.  For example, the caption or size can be adjusted via runtime property assignment.  Any previously opened WINDOW on the same execution thread is disabled.

A WINDOW automatically receives a single-width border frame unless one of the DOUBLE, NOFRAME, or RESIZE attributes are specified.  Screen coordinates are measured in dialog units unless overridden by the THOUS, MM, or POINTS attributes.  A dialog unit is defined as one-quarter the average character width and one-eighth the average character height of the font specified in the WINDOW's FONT attribute (or the system font, if no FONT attribute is specified on the WINDOW).

A WINDOW with the MODAL attribute is system modal; it takes exclusive control of the computer.  This means that any other progam running in the background halts its execution until the MODAL WINDOW is closed.  Therefore, the MODAL attribute should be used only when absolutely necessary.  Also, the RESIZE attribute is ignored, and the WINDOW cannot be moved when the MODAL attribute is present.

A WINDOW without the MDI attribute, when opened in an MDI program, is application modal.  This means that the user must respond before moving to any other window in the application.  The user may, however, move to any other program running in Windows at the time.  Non-MDI windows may be opened either before or after an APPLICATION is opened, and may be on the same execution thread as the APPLICATION.

A WINDOW with the MDI attribute is an MDI "child" window.  MDI "child" windows are clipped to the APPLICATION frame and automatically moved when the frame is moved, and can be totally concealed by minimizing the parent APPLICATION.  MDI "child" windows are modeless; the user may change to the top window of another execution thread, within the same application or any other application running in Windows, at any time.  An MDI "child" window must not be on the same execution thread as the APPLICATION.  Therefore, any MDI "child" window called directly from the APPLICATION must be in a separate procedure so the START function can be used to begin a new execution thread.  Once started, multiple MDI "child" windows may be called in the new thread.

The MENUBAR specified in a WINDOW with the MDI attribute is automatically merged into the "Global menu" (from the APPLICATION) when the WINDOW receives focus unless either the WINDOW's or APPLICATION's MENUBAR has the NOMERGE attribute.  A MENUBAR specified in a WINDOW without the MDI attribute is never merged into the "Global menu" it always appears in the window itself.

The TOOLBAR specified in a WINDOW with the MDI attribute is automatically merged into the "Global toolbar" (from the APPLICATION) when the WINDOW receives focus, unless either the WINDOW's or APPLICATION's TOOLBAR has the NOMERGE attribute.  The toolbar specified in a WINDOW without the MDI attribute is never merged into the "Global toolbar" it always appears in the window itself.

A WINDOW with the TOOLBOX attribute is automatically "always on top" and its controls do not retain focus (just as if they all had the SKIP attribute).  This creates a window whose controls all behave in the same manner as controls in the toolbar.  Normally, a WINDOW with the TOOLBOX attribute would be executed in its own thread.

Example:

!An MDI child window with system menu, minimize and maximize buttons,

! a status bar, scroll bars, and a resizable frame, containing a

! menu and toolbar for the window, which are merged into the application's

! menubar and toolbar:

MDIChild	WINDOW('Child One'),MDI,SYSTEM,MAX,ICON('WinIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    MENU('File'),USE(?FileMenu)

      ITEM('Close'),USE(?CloseFile)

    END

    MENU('Edit'),USE(?EditMenu)

      ITEM('Undo'),USE(?UndoText),KEY(CtrlZ),STD(STD:Undo)

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut)

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy)

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste)

    END

  END

  TOOLBAR

    BUTTON('Cut'),USE(?CutButton),ICON(ICON:Cut),STD(STD:Cut)

    BUTTON('Copy'),USE(?CopyButton),ICON(ICON:Copy),STD(STD:Copy)

    BUTTON('Paste'),USE(?PasteButton),ICON(ICON:Paste),STD(STD:Paste)

  END

  TEXT,HVSCROLL,USE(Pre:Field)

  BUTTON('&OK'),USE(?Exit),DEFAULT

END

!A non-MDI window with system menu, maximize button, a status bar, and a

! non-resizable frame, containing control fields

NonMDI	WINDOW('Dialog Window'),SYSTEM,MAX,STATUS

  TEXT,HVSCROLL,USE(Pre:Field),MSG('Enter some text here')

  BUTTON('&OK'),USE(?Exit),DEFAULT

END

!A system-modal window with a non-resizable frame,

! containing only a message and Ok button:

ModalWin	WINDOW('Modal Window'),MODAL

  ICON(ICON:Exclamation)

  STRING('An ERROR has occurred')

  BUTTON('&OK'),USE(?Exit),DEFAULT

END


APPLICATION and WINDOW Attributes

ALRT  (set window "hot" keys)

AT  (set window position and size)

CENTER  (set position and size)

CURSOR  (set mouse cursor type)

DOUBLE, NOFRAME, RESIZE  (set window border)

FONT  (set window default font)

GRAY  (set 3-D look background)

HLP  (set window's on-line help identifier)

HSCROLL, VSCROLL, HVSCROLL  (set window scroll bars)

ICON  (set window icon)

ICONIZE  (set window open as icon)

MASK  (set pattern editing data entry)

MAX  (set maximize control)

MAXIMIZE  (set window open maximized)

MDI  (set Multiple Document Interface)

MODAL  (set system modal window)

MSG  (set window status bar message)

PALETTE  (set number of hardware colors)

STATUS  (set status bar)

SYSTEM  (set system menu)

THOUS, MM, POINTS  (set screen coordinate measure)

TOOLBOX  (set toolbox window behavior)

TIMER  (set periodic event)


ALRT  (set window "hot" keys)

ALRT(keycode)

ALRT	Specifies a "hot" key active while the APPLICATION or WINDOW has focus.

keycode	A numeric constant keycode or keycode EQUATE.

The ALRT attribute specifies a "hot" key active while the APPLICATION or WINDOW has focus.  When the user presses an ALRT "hot" key for the APPLICATION or WINDOW, two field-independent events, EVENT:PreAlert and EVENT:AlertKey, are generated.  EVENT:PreAlert allows you the opportunity to "shortstop" the library's default action on an alerted keypress for the window.

You may have multiple ALRT attributes on one APPLICATION or WINDOW.  The ALERT statement and the ALRT attribute of a window or control are completely separate.  This means that clearing ALERT keys has no effect on any keys alerted by ALRT attributes.

Example:

Screen	WINDOW,ALRT(F10Key)	!F10 alerted for all fields

END

  CODE

  OPEN(Screen)	!Open screen for processing

  ACCEPT	!  and process all fields

    IF KEYCODE() = F10Key	!Check for the WINDOW's "hot" key

      CLOSE(Screen)

      RETURN

    END

  END


AT  (set window position and size)

AT([x] [,y] [,width] [,height])

AT	Specifies the initial position and size of an APPLICATION or WINDOW.

x	An integer constant or constant expression that specifies the initial horizontal position of the top left corner.  If omitted, the runtime library provides a default value.

y	An integer constant or constant expression that specifies the initial vertical position of the top left corner.  If omitted, the runtime library provides a default value.

width	An integer constant or constant expression that specifies the initial width.  If omitted, the runtime library provides a default value.

height	An integer constant or constant expression that specifies the initial height.  If omitted, the runtime library provides a default value.

The AT attribute defines the initial position and size of an APPLICATION or WINDOW.  If any parameter is omitted, the runtime library provides a default value.  The x and y parameters are relative to the top left hand corner of the video screen when the AT attribute is placed on an APPLICATION structure, or a WINDOW without the MDI attribute that is opened before any APPLICATION structure is opened by the program.  They are relative to the top left hand corner of the APPLICATION when the AT attribute is placed on a WINDOW with the MDI attribute, or a WINDOW without the MDI attribute opened after an APPLICATION structure has been opened.

The width and height parameters specify the size of the "client area" or "workspace" of an APPLICATION.  This is the area below the MENUBAR and above the status bar which defines the area in which the TOOLBAR is placed and MDI "child" windows are opened.  On a WINDOW, they specify the size of the "workspace" which may contain control fields.

The values contained in the x, y, width, and height parameters default to dialog units unless the THOUS, MM, or POINTS attribute is also present.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the window.  This measurement is based on the font specified in the FONT attribute of the window, or the system default font specified by Windows.

Example:

!Window at top left corner, relative to application frame:

WinOne	WINDOW,AT(0,0,380,200),MDI

END

!Window at top left corner, relative to video screen:

WinTwo	WINDOW,AT(0,0,380,200)

END


CENTER  (set position and size)

CENTER

The CENTER attribute indicates that the window's default width and height are centered.  A WINDOW structure with the MDI attribute is centered on the APPLICATION.  An APPLICATION structure is centered on the screen.  A non-MDI WINDOW is centered on its parent (the window currently with focus when the non-MDI WINDOW is opened).

This attribute has no meaning unless at least one parameter of the AT attribute is omitted.  This means that the CENTER attribute provides a default value for any omitted AT parameter.

Example:

!Window centered relative to application frame:

WinOne	WINDOW,AT(,,380,200),MDI,CENTER

END

!Window centered relative to its parent:

WinTwo	WINDOW,AT(,,380,200),CENTER

END


CURSOR  (set mouse cursor type)

CURSOR(file)

CURSOR	Specifies a mouse cursor to display for the window.

file	A string constant containing the name of a .CUR file, or an EQUATE naming a Windows-standard mouse cursor.  The .CUR file is linked into the .EXE as a resource.

The CURSOR attribute specifies a mouse cursor to be displayed when the mouse is positioned over the window.  This cursor is inherited by the controls in the window unless overridden.

The Windows standard mouse cursors contained in EQUATES.CLW are:

  CURSOR:None	No mouse cursor

  CURSOR:Arrow	The normal windows arrow cursor

  CURSOR:IBeam	A capital "I" like a steel I-beam

  CURSOR:Wait	An hourglass

  CURSOR:Cross	A large plus sign

  CURSOR:UpArrow	A vertical arrow

  CURSOR:Size	A four-headed arrow

  CURSOR:Icon	A box within a box

  CURSOR:SizeNWSE	A double-headed arrow slanting left

  CURSOR:SizeNESW	A double-headed arrow slanting right

  CURSOR:SizeWE	A double-headed horizontal arrow

  CURSOR:SizeNS	A double-headed vertical arrow

  CURSOR:DragWE	A double-headed horizontal arrow

Example:

!Window with Windows-standard large plus sign cursor

WinOne	WINDOW,CURSOR(CURSOR:Cross)

END

!Window with custom cursor

WinTwo	WINDOW,CURSOR('CUSTOM.CUR')

END


DOUBLE, NOFRAME, RESIZE  (set window border)

DOUBLE
NOFRAME
RESIZE

The DOUBLE, NOFRAME, and RESIZE attributes specify a WINDOW border frame style other than the default single-width border.  The DOUBLE attribute places a double-width border around the window and the NOFRAME attribute places no border on the window.  A window with these frame types may not be resized.

The RESIZE attribute places a thick border frame around the window.  This is the only type that allows the user to dynamically resize the window.  RESIZE is ignored on any WINDOW with the MODAL attribute.

Example:

!A Window with a single-width border:

Win1	WINDOW

END

!A resizable Window:

Win2	WINDOW,RESIZE

END

!A Window with a double-width border:

Win3	WINDOW,DOUBLE

END

!A Window without a border:

Win4	WINDOW,NOFRAME

END


FONT  (set window default font)

FONT([typeface] [,size] [,color] [,style])

FONT	Specifies the default display font for the window.

typeface	A string constant containing the name of the font.  If omitted, the system font is used.

size	An integer constant containing the size (in points) of the font.  If omitted, the system default font size is used.

color	A LONG integer constant containing the red, green, and blue values for the color of the font in the low-order three bytes, or an EQUATE for a standard Windows color value.  If omitted, black is used.

style	An integer constant or constant expression or EQUATE specifying the strike weight and style of the font.  If omitted, the weight is normal.

The FONT attribute on a WINDOW or APPLICATION structure specifies the default display font for all controls in the WINDOW or APPLICATION that do not have a FONT attribute.  This is also the default font for newly created controls on the window, and is the font used by the SHOW and TYPE statements when writing to the window.

The typeface may name any font registered in the Windows system.  The EQUATES.CLW file contains EQUATE values for standard style values.  A style on the range zero (0) to one thousand (1000) specifies the strike weight of the font.  You may add to that values that indicate italic, underline, or strikeout text.  The following EQUATES are in EQUATES.CLW:

  FONT:thin 	EQUATE (100)

  FONT:regular 	EQUATE (400)

  FONT:bold 	EQUATE (700)

  FONT:italic 	EQUATE (01000H)

  FONT:underline 	EQUATE (02000H)

  FONT:strikeout 	EQUATE (04000H)

Example:

!A Window using 14 point Times New Roman

Win1	WINDOW,FONT('Times New Roman',14,00H)

END

!A Window using 14 point Times New Roman, Bold and Italic

Win2	WINDOW,FONT('Times New Roman',14,00H,FONT:italic+FONT:bold)

END


GRAY  (set 3-D look background)

GRAY

The GRAY attribute indicates that the WINDOW has a gray background, suitable for use with three-dimensional dialog controls.  All controls on a WINDOW with the GRAY attribute are automatically given a three-dimensional appearance.  Controls in a TOOLBAR are always automatically given a three-dimensional appearance, without the GRAY attribute.

The three-dimensional look may be disabled by SET3DLOOK.

Example:

!A Window with 3-D controls

Win1	WINDOW,GRAY

END


HLP  (set window's on-line help identifier)

HLP(helpID)

HLP	Specifies the helpID for the APPLICATION, WINDOW, or control.

helpID	A string constant specifying the key used to access the Help system.  This may be either a Help keyword or a "context string."

The HLP attribute specifies the helpID for the APPLICATION or WINDOW.  Help, if available, is automatically displayed by Windows whenever the user presses F1.

If the user presses F1 to request help when the APPLICATION window is foremost and no menus are active, the APPLICATION's helpID is used to locate the Help text.  Otherwise, the library automatically uses the helpID of the active menu of uppermost control or window, searching up the hierarchy until an object with that helpID is found.  The helpID of the APPLICATION is at the top of the hierarchy.

The helpID may contain a Help keyword or a "context string."  A Help keyword is a keyword or phrase that is displayed in the Help Search dialog.  When the user presses F1, if only one topic in the help file specifies this keyword, the help file is opened at that topic; if more than one topic specifies the keyword, the search dialog is opened for the user.

A "context string" is identified by a leading tilde (~) in the helpID, followed by a unique identifier (no spaces allowed) associated with exactly one help topic.  If the tilde is missing, the helpID is assumed to be a help keyword.  When the user presses F1, the help file is opened at the specific topic associated with that "context string."

Example:

!A Window with a help context string:

Win1	WINDOW,HLP('~Win1Help')

END

!A Window with a help keyword:

Win2	WINDOW,HLP('Window One Help')

END


HSCROLL, VSCROLL, HVSCROLL  (set window scroll bars)

HSCROLL
VSCROLL
HVSCROLL

The HSCROLL, VSCROLL, and HVSCROLL parameters place scroll bars on an APPLICATION or WINDOW.  HSCROLL adds a horizontal scroll bar to the bottom, VSCROLL adds a vertical scroll bar on the right side, and HVSCROLL adds both.

The vertical scroll bar allows a mouse to scroll up or down.  The horizontal scroll bar allows a mouse to scroll left or right.  The scroll bars appear whenever any scrollable portion of the APPLICATION or WINDOW lies outside the visible area on screen.

Example:

!A Window with a horizontal scroll bar:

Win1	WINDOW,HSCROLL

END

!A Window with a vertical scroll bar:

Win2	WINDOW,VSCROLL

END

!A Window with both scroll bars:

Win2	WINDOW,HVSCROLL

END


ICON  (set window icon)

ICON( [file] )

ICON	Specifies an icon to display for the APPLICATION or WINDOW.

file	A string constant containing the name of an .ICO file, or an EQUATE for the Windows-standard icon to display.  The .ICO file is linked into the .EXE as a resource.

The ICON attribute specifies an icon to display for the APPLICATION or WINDOW.  On an APPLICATION or WINDOW, ICON also specifies the presence of a minimize control.  The minimize control appears in the top right corner of the window as a downward pointing triangle (usually).  When the user clicks the mouse on it, the window shrinks to an icon without halting its execution.  When an APPLICATION or non-MDI WINDOW is minimized, the icon file is displayed in the operating system's desktop; when a WINDOW with the MDI attribute is minimized, the icon file is displayed in the APPLICATION.

EQUATE statements for the Windows-standard icons are contained in the EQUATES.CLW file.  The following list is a representative sample of these (see EQUATES.CLW for the complete list):

ICON:None	No icon

ICON:Application

ICON:Question	?

ICON:Exclamation	!

ICON:Asterisk	*

ICON:VCRtop	>>|

ICON:VCRrewind	<<

ICON:VCRback	<

ICON:VCRplay	>

ICON:VCRfastforward	>>

ICON:VCRbottom	|<<

ICON:VCRlocate	?

Example:

!A Window with a minimize button:

WinOne	WINDOW,ICON('MyIcon.ICO')

END

!A Window with a minimize button:

WinTwo	WINDOW,ICON(ICON:Application)

END


ICONIZE  (set window open as icon)

ICONIZE

The ICONIZE attribute specifies the APPLICATION or WINDOW is opened minimized as the icon specified by the ICON attribute.  When an APPLICATION or non-MDI WINDOW is minimized, the icon file is displayed in the operating system's desktop; when a WINDOW with the MDI attribute is minimized, the icon file is displayed in the APPLICATION.

Example:

!A Window with a minimize button, opened as the icon:

Win2	WINDOW,ICON('MyIcon.ICO'),ICONIZE

END


MASK  (set pattern editing data entry)

MASK

The MASK attribute specifies pattern input editing mode of all controls in this window.  This means that, as the user types in data, each character is automatically validated against the control's picture for proper input (numbers only in numeric pictures, etc.).  This forces the user to enter data in the format specified by the control's display picture.

If omitted, Windows free-input is allowed in the controls.  Free-input means the user's data is formatted to the control's picture only after entry.  This allows users to enter data as they choose and it is automatically formatted to the control's picture after entry.  If the user types in data in a format different from the control's picture, the libraries attempt to determine the format the user used, and convert the data to the control's display picture.  For example, if the user types "January 1, 1995" into a control with a display picture of @D1, the runtime library formats the user's input to "1/1/95."  This action occurs only after the user completes data entry and moves to another control.  If the runtime library cannot determine what format the user used, it will not update the USE variable.  It then beeps and leaves the user on the same control with the data they entered, to allow them to try again.

Example:

!A Window with pattern input editing enabled

Win2	WINDOW,MASK

END


MAX  (set maximize control)

MAX

The MAX attribute specifies a maximize control on the APPLICATION or WINDOW.  The maximize control appears in the top right corner of the window as a box containing either an upward pointing triangle, or an upward pointing triangle above a downward pointing triangle (in Windows 3.1).  When the user clicks the mouse on it, an APPLICATION or non-MDI WINDOW expands to occupy the full screen, an MDI WINDOW expands to occupy the entire APPLICATION.  Once expanded, the maximize control appears as an upward pointing triangle above a downward pointing triangle.  Click the mouse on it again, and the window returns to its previous size and the maximize control appears as an upward pointing triangle.

Example:

!A Window with a maximize button:

Win2	WINDOW,MAX

END


MAXIMIZE  (set window open maximized)

MAXIMIZE

The MAXIMIZE attribute specifies the APPLICATION or WINDOW is opened maximized.

When maximized, an APPLICATION or non-MDI WINDOW expands to occupy the full screen, and an MDI WINDOW expands to occupy the entire APPLICATION.  Once expanded, the maximize control appears as an upward pointing triangle above a downward pointing triangle (in Windows 3.1).

Example:

!A Window with a maximize button, opened maximized:

Win2	WINDOW,MAX,MAXIMIZE

END


MDI  (set Multiple Document Interface)

MDI

The MDI attribute specifies a WINDOW structure that acts as a "child" window to the APPLICATION.  MDI "child" windows are clipped to the APPLICATION frame they scroll only within the boundaries set by the display size of the APPLICATION.  MDI "child" windows are automatically moved when the APPLICATION frame is moved, and can be totally concealed by minimizing the APPLICATION.  A WINDOW with the MDI attribute cannot be opened unless there is a currently open APPLICATION.

MDI "child" windows are modeless; the user may change to the top window of another execution thread, within the same application or any other application running in Windows, at any time.  An MDI "child" window must not be on the same execution thread as the APPLICATION.  Therefore, any MDI "child" window called directly from the APPLICATION must be in a separate procedure so the START function can be used to begin a new execution thread.  Once started, multiple MDI "child" windows may be called in the new thread.

A non-MDI WINDOW operates independently of any previously opened APPLICATION.  It will, however, disable an APPLICATION if it or any of its MDI "child" windows are on the same execution thread.  This makes a non-MDI window opened in an MDI program an "application modal" window which effectively disables the application while the user has the window open (unless it is opened in its own execution thread).  It does not, however, prevent the user from changing to another application running under Windows.

Example:

!An MDI child Window:

Win2	WINDOW,MDI

END


MODAL  (set system modal window)

MODAL

The MODAL attribute specifies the WINDOW is "system modal."  This means that no other window (in the same or any other concurrent program) can receive focus while the MODAL window has focus the MODAL window has exclusive control of the computer.  MODAL windows are usually used for error messages, or messages which require immediate attention by the user, such as:  "Please insert a disk in drive A:."

A WINDOW without the MODAL attribute, may be "application modal" or "modeless."  An application modal window is a non-MDI WINDOW (without the MDI attribute) opened in an MDI program.  An application modal window restricts the user from moving to another execution thread in the same application but does not restrict them from changing to another Windows program.

A modeless window is an MDI "child" WINDOW (with the MDI attribute) without the MODAL attribute.  From a modeless window, other windows on other execution threads may be selected by means of the mouse, keyboard, or menu commands.  If so, the other window will then take the focus and become uppermost on the video display.  Any window opened previously on the same execution thread may not be selected to receive focus, even from a modeless window.

Example:

!A system-modal Window:

Win2	WINDOW,MODAL

END


MSG  (set window status bar message)

MSG(text)

MSG	Specifies text to display in the status bar.

text	A string constant containing the message to display in the status bar.

The MSG attribute on an APPLICATION or WINDOW structure specifies the text to display in the first zone of the status bar when the control with focus has no MSG attribute of its own.

Example:

WinOne	WINDOW,AT(0,0,160,400),MSG('Enter Data')	!Default MSG to use

  COMBO(@S8),AT(120,120,20,20),USE(?C1),FROM(Q1:F2),MSG('Enter or Select')

  LIST,AT(120,0,20,20),USE(?L1),FROM(Que1),MSG('Select One')

  SPIN(@N8.2),AT(280,0,20,20),USE(SpinVar1),FROM(Q),MSG('Choose One')

  TEXT,AT(20,0,40,40),USE(E2)	!Default MSG used

  ENTRY(@S8),AT(100,200,20,20),USE(E2)	!Default MSG used

  CHECK('&A'),AT(0,120,20,20),USE(?C7),MSG('On or Off')

  OPTION('Option 1'),USE(OptVar),MSG('Pick One or Two')

    RADIO('Radio 1'),AT(120,0,20,20),USE(?R1)

    RADIO('Radio 2'),AT(140,0,20,20),USE(?R2)

  END

END


PALETTE  (set number of hardware colors)

PALETTE(colors)

PALETTE	Specifies the number of hardware colors displayed in the window.

colors	An integer constant specifying the number of hardware colors displayed in the window.

The PALETTE attribute on a WINDOW specifies the number of hardware colors used in the window for graphics display.  This enforces a particular set of colors for the graphics.

*** HOW??? EXACTLY WHAT DOES THIS DO???

Example:

WinOne	WINDOW,AT(0,0,160,400),PALETTE(256)	!Enforce 256-color

  IMAGE,AT(120,120,20,20),USE(ImageField)

END


STATUS  (set status bar)

STATUS( [widths] )

STATUS	Specifies the presence of a status bar.

widths	A list of integer constants (separated by commas) specifying the size of each zone in the status bar.  If omitted, the status bar has one zone the width of the window.

The STATUS attribute specifies the presence of a status bar at the base of the APPLICATION or WINDOW.  The status bar of an MDI WINDOW is always displayed at the bottom of the APPLICATION.  A WINDOW without the MDI attribute displays its status bar at the base of the WINDOW.  If the STATUS attribute is not present on the APPLICATION or WINDOW, there is no status bar.

The status bar may be divided into a number of zones specified by the widths parameters.  The size of each zone is specified in dialog units unless overridden by the THOUS, MM, or POINTS attribute.  A negative value indicates the zone is expandable, but has a minimum width indicated by the parameter's absolute value.  If no widths parameters are specified, a single expanding zone with no minimum width is created, which is equivalent to a STATUS(-1).

The first zone of the status bar is always used to display MSG attributes.  The MSG attribute string is displayed in the status bar as long as its control field still has input focus.  A control or menu item without a MSG attribute causes the status bar to revert to its former state (either blank or displaying the text previously displayed in the zone).

Text may be placed in, or retrieved from, any zone of the status bar using the runtime property assignment syntax.  The text remains present until replaced.  The status bar configuration can also be changed dynamically by using the runtime property assignment syntax.

Example:

!An APPLICATION with a one-zone status bar:

MainWin	APPLICATION,STATUS

END

!A WINDOW with a two-zone status bar:

Win1	WINDOW,STATUS(160,160)

END


SYSTEM  (set system menu)

SYSTEM

The SYSTEM attribute specifies the presence of a Windows system menu (also called the control menu) on the APPLICATION or WINDOW.  This menu contains standard Windows menu selections, such as: Close, Minimize, Maximize (the window), and Switch To (another window).  The actual selections available on a given window depend upon the attributes set for that window.

Example:

!An APPLICATION with a system menu:

MainWin	APPLICATION,SYSTEM

END

!A WINDOW with a system menu:

Win1	WINDOW,SYSTEM

END


THOUS, MM, POINTS  (set screen coordinate measure)

THOUS
MM
POINTS

The THOUS, MM, and POINTS attributes specify the coordinate measure used to position controls on the WINDOW or an APPLICATION structure's TOOLBAR.

The THOUS attribute specifies thousandths of an inch, MM specifies millimeters, and POINTS specifies points (there are seventy-two points per inch, both vertically and horizontally).

If all these attributes are omitted, measurement defaults to dialog units.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the window.  This measurement is based on the font specified in the FONT attribute of the window, or the system default font specified by Windows.

Example:

!An APPLICATION using dialog units:

MainWin	APPLICATION

END

!A WINDOW using thousandths of an inch:

Win1	WINDOW,THOUS

END

!A WINDOW using millimeters

Win2	WINDOW,MM

END

!A WINDOW using points

Win1	WINDOW,POINTS

END


TOOLBOX  (set toolbox window behavior)

TOOLBOX

The TOOLBOX attribute specifies a WINDOW that is "always on top."  Neither the WINDOW nor its controls retain input focus.  This creates control behavior as if all the controls in the WINDOW had the SKIP attribute.  Normally, a WINDOW with the TOOLBOX attribute executes in its own execution thread to provide a set of tools to the window with input focus.  The MSG attributes of the controls in the window appear in the status bar when the mouse cursor is positioned over the control.

Example:

PROGRAM

MainWin	APPLICATION('My Application')

  MENUBAR

    MENU('File'),USE(?FileMenu)

      ITEM('E&xit'),USE(?MainExit),LAST

    END

    MENU('Edit'),USE(?EditMenu)

      ITEM('Use Tools'),USE(?UseTools)

    END

  END

END

Pre:Field	STRING(400)

UseToolsThread  BYTE

ToolsThread	BYTE

  CODE

  OPEN(MainWin)

  ACCEPT

    CASE ACCEPTED()

    OF ?MainExit

      BREAK

    OF ?UseTools

      UseToolsThread = START(UseTools)

    END

  END

UseTools	PROCEDURE	!A procedure that uses a toolbox

MDIChild	WINDOW('Use Tools Window'),MDI

  TEXT,HVSCROLL,USE(Pre:Field)

  BUTTON('&OK'),USE(?Exit),DEFAULT

END

  CODE

  OPEN(MDIChild)	!Open the window

  DISPLAY	! and display it

  ToolsThread = START(Tools)	!Pop up the toolbox

  ACCEPT

    CASE EVENT()	!Check for user-defined events

    OF 401h	! posted by toolbox controls

      Pre:Field += ' ' & FORMAT(TODAY(),@D1)  ! append date to end of field

    OF 402h

      Pre:Field += ' ' & FORMAT(CLOCK(),@T1)  ! append time to end of field

    END

    CASE ACCEPTED()

    OF ?Exit

      POSTEVENT(400h,,ToolsThread)	!Signal to close tools window

      BREAK

    END

  END

  CLOSE(MDIChild)

Tools 	PROCEDURE	!The toolbox procedure

Win1	WINDOW('Tools'),TOOLBOX

  BUTTON('Date'),USE(?Button1)

  BUTTON('Time'),USE(?Button2)

END

  CODE

  OPEN(Win1)

  ACCEPT

    IF EVENT() = 400h THEN BREAK.	!Check for close window signal

    CASE ACCEPTED()

    OF ?Button1

      POSTEVENT(401h,,UseToolsThread)  !Post datestamp signal

    OF ?Button2

      POSTEVENT(402h,,UseToolsThread)  !Post timestamp signal

    END

  END

  CLOSE(Win1)


TIMER  (set periodic event)

TIMER(period)

TIMER	Specifies a periodic event.

period	An integer constant or constant expression specifying the interval between timed events, in hundredths of a second.

The TIMER attribute specifies generation of a periodic field-independent event whenever the time period passes.  EQUATES.CLW contains EVENT:Timer which equates the timer-generated event.  The FOCUS() function returns the number of the control that currently has focus at the time of the event.

Example:

RunClock	PROCEDURE

ShowTime	LONG

!A WINDOW with a timed event occurring every second:

Win1	WINDOW,TIMER(100)

  STRING(@T4),USE(ShowTime)

END

  CODE

  OPEN(Win1)

  ShowTime = CLOCK()

  ACCEPT

    CASE EVENT()

    OF EVENT:Timer

      ShowTime = CLOCK()

      DISPLAY

    END

  END

  CLOSE(Win1)


MENUBAR and TOOLBAR Structures

MENUBAR  (declare a pulldown menu)

TOOLBAR  (declare a tool bar)


MENUBAR  (declare a pulldown menu)

MENUBAR [,NOMERGE]
    [MENU( )
        [ITEM( )]
        [MENU( )
            [ITEM( )]
         END ]
     END ]
    [ITEM( )]
END

MENUBAR	Declares the menu for an APPLICATION or WINDOW.

NOMERGE	Specifies menu merging behavior.

MENU	A menu item with an associated drop box containing other menu selections.

ITEM	A menu item for selection.

The MENUBAR structure declares the pulldown menu selections displayed for an APPLICATION or WINDOW.  MENUBAR must appear in the source code before any TOOLBAR or controls.

On an APPLICATION, the MENUBAR defines the Global menu selections for the program.  These are active and available on all MDI "child" windows (unless the window's own MENUBAR structure has the NOMERGE attribute).  If the NOMERGE attribute is specified on the APPLICATION's MENUBAR, then the menu is a local menu displayed only when no MDI child windows are open and there is no global menu.

On an MDI WINDOW, the MENUBAR defines menu selections that are automatically merged with the Global menu.  Both the Global and the window's menu selections are then active while the MDI "child" window has input focus.  Once the window loses focus, its specific menu selections are removed from the Global menu.  If the NOMERGE attribute is specified on an MDI WINDOW's MENUBAR, the menu overwrites and replaces the Global menu.

On a non-MDI WINDOW, the MENUBAR is never merged with the Global menu.  A MENUBAR on a non-MDI WINDOW always appears in the WINDOW, not on any APPLICATION which may have been previously opened.

Events generated by local menu items are sent to the WINDOW's ACCEPT loop in the normal way.  Events generated by global menu items are sent to the active event loop of the thread which opened the APPLICATION (in a normal multi-thread application this means the APPLICATION's own ACCEPT loop).

Dynamic changes to menu items which reference the currently active window affect only the currently displayed menu, even if global items are changed.  Changes made to the Global menu items when the APPLICATION is the current window, or which reference the global APPLICATION window affect the global portions of all menus, whether already open or not.

When a WINDOW's MENUBAR is merged into an APPLICATION's MENUBAR, the global menu selections appear first, followed by the local menu selections, unless the FIRST or LAST attributes are specified on individual menu selections.

Example:

!An MDI application frame window with main menu for the application:

MainWin	APPLICATION('My Application')

  MENUBAR

    MENU('File'),USE(?FileMenu)

      ITEM('Open...'),USE(?OpenFile)

      ITEM('Close'),USE(?CloseFile),DISABLE

      ITEM('E&xit'),USE(?MainExit),LAST

    END

    MENU('Edit'),USE(?EditMenu)

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut),DISABLE

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy),DISABLE

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste),DISABLE

    END

    MENU('Help'),USE(?HelpMenu),LAST

      ITEM('Contents'),USE(?HelpContents),STD(STD:HelpIndex)

      ITEM('Search for Help On...'),USE(?HelpSearch),STD(STD:HelpSearch)

      ITEM('How to Use Help'),USE(?HelpOnHelp),STD(STD:HelpOnHelp)

      ITEM('About MyApp...'),USE(?HelpAbout)

    END

  END

END

!An MDI child window with menu for the window, merged into the

! application's menubar:

MDIChild	WINDOW('Child One'),MDI

  MENUBAR

    MENU('File'),USE(?FileMenu)	!Merges into File menu

      ITEM('Close'),USE(?CloseFile)	!Supercedes main menu selection

      ITEM('Pick...'),USE(?PickFile)	!Added to menu selections

    END

    MENU('Edit'),USE(?EditMenu)	!Merges into Edit menu

      ITEM('Undo'),USE(?UndoText),KEY(CtrlZ),STD(STD:Undo)  !Added to menu

!These items supercede main menu selections

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut)

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy)

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste)

    END

    MENU('Window'),STD(STD:WindowList),LAST

      ITEM('Tile'),STD(STD:TileWindow)

      ITEM('Cascade'),STD(STD:CascadeWindow)

    END

  END

  TEXT,HVSCROLL,USE(Pre:Field)

  BUTTON('&OK'),USE(?Exit),DEFAULT

END

!An MDI window with its own menu, overwriting the main menu:

MDIChild2	WINDOW('Dialog Window'),MDI,SYSTEM,MAX,STATUS

  MENUBAR,NOMERGE

    MENU('File'),USE(?FileMenu)

      ITEM('Close'),USE(?CloseFile)

    END

    MENU('Edit'),USE(?EditMenu)

      ITEM('Undo'),USE(?UndoText),KEY(CtrlZ),STD(STD:Undo)

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut)

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy)

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste)

    END

  END

  TEXT,HVSCROLL,USE(Pre:Field),MSG('Enter some text here')

  BUTTON('&OK'),USE(?Exit),DEFAULT

END

!A non-MDI window with its own menu:

NonMDI	WINDOW('Dialog Window'),SYSTEM,MAX,STATUS

  MENUBAR

    MENU('File'),USE(?FileMenu)

      ITEM('Close'),USE(?CloseFile)

    END

    MENU('Edit'),USE(?EditMenu)

      ITEM('Undo'),USE(?UndoText),KEY(CtrlZ),STD(STD:Undo)

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut)

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy)

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste)

    END

  END

  TEXT,HVSCROLL,USE(Pre:Field),MSG('Enter some text here')

  BUTTON('&OK'),USE(?Exit),DEFAULT

END


TOOLBAR  (declare a tool bar)

TOOLBAR [,AT( )] [,CURSOR( )] [,FONT( )] [,NOMERGE]
controls
END

TOOLBAR	Declares tools for an APPLICATION or WINDOW.

AT	Specifies the initial size of the toolbar.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the TOOLBAR.  If omitted, the WINDOW or APPLICATION structure's CURSOR attribute is used, else the Windows default cursor is used.

FONT	Specifies the default display font for the controls in the TOOLBAR.

NOMERGE	Specifies tools merging behavior.

controls	Control field declarations that define the available tools.

The TOOLBAR structure declares the tools displayed for an APPLICATION or WINDOW.  On an APPLICATION, the TOOLBAR defines the Global tools for the program.  If the NOMERGE attribute is specified on the APPLICATION's TOOLBAR, the tools are local and are displayed only when no MDI child windows are open; there are no global tools.  Global tools are active and available on all MDI "child" windows unless an MDI "child" window's TOOLBAR structure has the NOMERGE attribute.  If so, the "child" window's tools overwrite the Global tools.

On an MDI WINDOW, the TOOLBAR defines tools that are automatically merged with the Global toolbar.  Both the Global and the window's tools are then active while the MDI "child" window has input focus.  Once the window loses focus, its specific tools are removed from the Global toolbar.  If the NOMERGE attribute is specified on an MDI WINDOW's TOOLBAR, the tools overwrite and replace the Global toolbar.  On a non-MDI WINDOW, the TOOLBAR is never merged with the Global menu.  A TOOLBAR on a non-MDI WINDOW always appears in the WINDOW, not on any APPLICATION which may have been previously opened.

Events generated by local tools are sent to the WINDOW's ACCEPT loop in the normal way.  Events generated by global tools are sent to the active event loop of the thread which opened the APPLICATION.  In a normal multi-thread application, this means the APPLICATION's own ACCEPT loop.

TOOLBAR controls generate events in the normal manner.  However, they do not keep the focus, and cannot be operated from the keyboard unless accelerator keys are provided.  As soon as user interaction with a TOOLBAR control is done, focus returns to the window and local control which previously had it.

Dynamic changes to tools which reference the currently active window affect only the currently displayed toolbar, even if global tools are changed.  Changes made to the Global toolbar when the APPLICATION is the current window, or which reference the global APPLICATION's window affect the global portions of all toolbars, whether already open or not.

When a WINDOW's TOOLBAR is merged into an APPLICATION's TOOLBAR, the global tools appear first, followed by the local tools.  The toolbars are merged so that the fields in the WINDOW's toolbar begin just right of the position specified by the value of the width parameter of the APPLICATION TOOLBAR's AT attribute.  The height of the displayed toolbar is the maximum height of the "tallest" tool, whether global or local.  If any part of a control falls below the bottom, the height is increased accordingly.

Example:

!An MDI application frame window containing the

! main menu and toolbar for the application:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    ITEM('E&xit'),USE(?MainExit)

  END

  TOOLBAR

    BUTTON('Exit'),USE(?MainExitButton)

  END

END

!An MDI child window with toolbar for the window, merged into the

! application's toolbar:

MDIChild	WINDOW('Child One'),MDI

  TOOLBAR

    BUTTON('Cut'),USE(?CutButton),STD(STD:Cut)

    BUTTON('Copy'),USE(?CopyButton),STD(STD:Copy)

    BUTTON('Paste'),USE(?PasteButton),STD(STD:Paste)

  END

  TEXT,HVSCROLL,USE(Pre:Field)

  BUTTON('&OK'),USE(?Exit),DEFAULT

END

!An MDI window with its own toolbar, overwriting the main toolbar:

MDIChild2	WINDOW('Dialog Window'),MDI,SYSTEM,MAX,STATUS

  TOOLBAR,NOMERGE

    BUTTON('Cut'),USE(?CutButton),STD(STD:Cut)

    BUTTON('Copy'),USE(?CopyButton),STD(STD:Copy)

    BUTTON('Paste'),USE(?PasteButton),STD(STD:Paste)

  END

  TEXT,HVSCROLL,USE(Pre:Field),MSG('Enter some text here')

  BUTTON('&OK'),USE(?Exit),DEFAULT

END

!A non-MDI window with its own toolbar:

NonMDI	WINDOW('Dialog Window'),SYSTEM,MAX,STATUS

  TOOLBAR

    BUTTON('Cut'),USE(?CutButton),STD(STD:Cut)

    BUTTON('Copy'),USE(?CopyButton),STD(STD:Copy)

    BUTTON('Paste'),USE(?PasteButton),STD(STD:Paste)

  END

  TEXT,HVSCROLL,USE(Pre:Field),MSG('Enter some text here')

  BUTTON('&OK'),USE(?Exit),DEFAULT

END


MENUBAR and TOOLBAR Attributes

CURSOR  (set toolbar mouse cursor type)

FONT  (set toolbar default font)

NOMERGE  (set merging behavior)


CURSOR  (set toolbar mouse cursor type)

CURSOR(file)

CURSOR	Specifies a mouse cursor to display for the TOOLBAR.

file	A string constant containing the name of a .CUR file, or an EQUATE naming a Windows-standard mouse cursor.  The .CUR file is linked into the .EXE as a resource.

The CURSOR attribute specifies a mouse cursor to be displayed when the mouse is positioned over the TOOLBAR.  This cursor is inherited by the controls in the toolbar unless overridden.

EQUATE statements for the Windows-standard mouse cursors are contained in the EQUATES.CLW file.  The following list is a representative sample of these (see EQUATES.CLW for the complete list):

CURSOR:None	No mouse cursor

CURSOR:Arrow	Normal windows arrow cursor

CURSOR:IBeam	Capital "I" like a steel I-beam

CURSOR:Wait	Hourglass

CURSOR:Cross	Large plus sign

CURSOR:UpArrow	Vertical arrow

CURSOR:Size	Four-headed arrow

CURSOR:Icon	Box within a box

CURSOR:SizeNWSE	Double-headed arrow slanting left

CURSOR:SizeNESW	Double-headed arrow slanting right

CURSOR:SizeWE	Double-headed horizontal arrow

CURSOR:SizeNS	Double-headed vertical arrow

CURSOR:DragWE	Double-headed horizontal arrow

Example:

!Toolbar with large plus sign cursor

WinOne	WINDOW

  TOOLBAR,CURSOR('CURSOR:Cross')

    BUTTON('Cut'),USE(?CutButton),STD(STD:Cut)

    BUTTON('Copy'),USE(?CopyButton),STD(STD:Copy)

    BUTTON('Paste'),USE(?PasteButton),STD(STD:Paste)

  END

END


FONT  (set toolbar default font)

FONT([typeface] [,size] [,color] [,style])

FONT	Specifies the default display font for the TOOLBAR.

typeface	A string constant containing the name of the font.  If omitted, the system font is used.

size	An integer constant containing the size (in points) of the font.  If omitted, the system default font size is used.

color	A LONG integer constant containing the red, green, and blue values for the color of the font in the low-order three bytes, or an EQUATE for a standard Windows color value.  If omitted, black is used.

style	An integer constant or constant expression or EQUATE specifying the strike weight and style of the font.  If omitted, the weight is normal.

The FONT attribute on a TOOLBAR structure specifies the default display font for all controls in the TOOLBAR that do not have a FONT attribute.  The typeface may name any font registered in the Windows system.  The EQUATES.CLW file contains EQUATE values for standard style values.  A style on the range zero (0) to one thousand (1000) specifies the strike weight of the font.  You may add to that values that indicate italic, underline, or strikeout text.  The following EQUATES are in EQUATES.CLW:

  FONT:thin 	EQUATE (100)

  FONT:regular 	EQUATE (400)

  FONT:bold 	EQUATE (700)

  FONT:italic 	EQUATE (01000H)

  FONT:underline 	EQUATE (02000H)

  FONT:strikeout 	EQUATE (04000H)

Example:

Win1	WINDOW	!A toolbar using 14 point Times New Roman

  TOOLBAR,FONT('Times New Roman',14,00H)

    BUTTON('Cut'),USE(?CutButton),STD(STD:Cut)

    BUTTON('Paste'),USE(?PasteButton),STD(STD:Paste)

  END

END

Win2	WINDOW	!A toolbar using 14 point Times New Roman, Bold and Italic

  TOOLBAR,FONT('Times New Roman',14,00H,FONT:italic+FONT:bold)

    BUTTON('Cut'),USE(?CutButton),STD(STD:Cut)

    BUTTON('Paste'),USE(?PasteButton),STD(STD:Paste)

  END

END


NOMERGE  (set merging behavior)

NOMERGE

The NOMERGE attribute indicates that the MENUBAR or TOOLBAR on a WINDOW should not be merged with the Global menu or toolbar.

The NOMERGE attribute on an APPLICATION's MENUBAR indicates that the menu is local and to be displayed only when no MDI "child" windows are open and that there is no Global menu.  The NOMERGE attribute on an APPLICATION's TOOLBAR indicates that the tools are local and to be displayed only when no MDI "child" windows are open and that there are no Global tools.

Without the NOMERGE attribute, an MDI WINDOW's menu and toolbar are automatically merged with the global menu and toolbar, and then displayed in the APPLICATION menu and toolbar.  When NOMERGE is specified, the WINDOW's menu and toolbar overwrite the Global menu and toolbar.  The menu and toolbar displayed when the WINDOW has focus are only the WINDOW's own menu and toolbar.  However, they are still displayed on the APPLICATION.

A MENUBAR or TOOLBAR specified in a non-MDI WINDOW is never merged with the Global menu or toolbar they appear in the WINDOW.

Example:

!An MDI application frame window with local-only menu and toolbar:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS

  MENUBAR,NOMERGE

    ITEM('E&xit'),USE(?MainExit)

  END

  TOOLBAR,NOMERGE

    BUTTON('Exit'),USE(?MainExitButton)

  END

END

!MDI window with its own menu and toolbar, overwriting the application's:

MDIChild	WINDOW('Dialog Window'),MDI,SYSTEM,MAX,STATUS

  MENUBAR,NOMERGE

    MENU('Edit'),USE(?EditMenu)

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut)

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy)

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste)

    END

  END

  TOOLBAR,NOMERGE

    BUTTON('Cut'),USE(?CutButton),STD(STD:Cut)

    BUTTON('Copy'),USE(?CopyButton),STD(STD:Copy)

    BUTTON('Paste'),USE(?PasteButton),STD(STD:Paste)

  END

  TEXT,HVSCROLL,USE(Pre:Field),MSG('Enter some text here')

  BUTTON('&OK'),USE(?Exit),DEFAULT

END


MENUBAR Controls

MENU  (declare a menu box)

ITEM  (declare a menu item)


MENU  (declare a menu box)

MENU(text) [,USE( )] [,KEY( )] [,MSG( )] [,HLP( )] [,STD( )] [,RIGHT]
[,	| FIRST	| ] [,DISABLE] [,HIDE]
| LAST	|

MENU	Declares a menu box within a MENUBAR.

text	A string constant containing the display text for the menu selection.

USE	A field equate label to reference the menu selection in executable code.

KEY	Specifies an integer constant or keycode equate that immediately opens the menu.

MSG	Specifies a string constant containing the text to display in the status bar when the menu is pulled down.

HLP	Specifies a string constant containing the help system identifier for the menu.

STD	Specifies an integer constant or equate that identifies a "Windows standard behavior" for the menu.

RIGHT	Specifies the MENU appears at the far right of the action bar.

FIRST	Specifies the MENU appears at the left or top of the menu when merged.

LAST	Specifies the MENU appears at the right or bottom of the menu when merged.

DISABLE	Specifies the menu appears dimmed when the WINDOW or APPLICATION is first opened.

HIDE	Specifies the menu does not appear when the WINDOW or APPLICATION is first opened; UNHIDE must be used to display it.

MENU declares a drop-down or cascading menu box structure within a MENUBAR structure.  When the MENU is selected, the MENU and/or ITEM statements within the structure are displayed in a menu box.  A MENU is not required to have any MENUs or ITEMs in it.  A menu box usually appears (drops down) immediately below its text on the menu bar (or above, if there is no room below).  When selected with ENTER or RIGHT ARROW, any subsequent menu drop-box appears (cascades) immediately to the right of the MENU text in the preceding menu box (or left, if there is no room to the right).  LEFT ARROW backs up to the preceding menu.  The KEY attribute designates a separate accelerator key for the field.  This may be any valid Clarion keycode to immediately pull down the MENU.

The text string may contain an ampersand ( & ) which designates the following character as the accelerator "hot" key which is automatically underlined.  If the MENU is on the menu bar, pressing the Alt key together with the accelerator key highlights and displays the MENU.  If the MENU is within another MENU, pressing the accelerator key, alone, highlights and executes the MENU.  If there is no ampersand in the text, the first non-blank character in the text string is the accelerator key for the MENU, but it will not be underlined.  To include an ampersand as part of the text, place two ampersands together (&&) in the text string and only one will display.

Example:

!An MDI application frame window with main menu for the application:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    MENU('File'),USE(?FileMenu),FIRST

      ITEM('Open...'),USE(?OpenFile)

      ITEM('Close'),USE(?CloseFile),DISABLE

      ITEM('E&xit'),USE(?MainExit)

    END

    MENU('Edit'),USE(?EditMenu),KEY(CtrlE),HLP('EditMenuHelp')

      ITEM('Undo'),USE(?UndoText),KEY(CtrlZ),STD(STD:Undo),DISABLE

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut),DISABLE

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy),DISABLE

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste),DISABLE

    END

    MENU('Window'),STD(STD:WindowList),MSG('Arrange or Select Window'),LAST

      ITEM('Tile'),STD(STD:TileWindow)

      ITEM('Cascade'),STD(STD:CascadeWindow)

      ITEM('Arrange Icons'),STD(STD:ArrangeIcons)

    END

    MENU('Help'),USE(?HelpMenu),LAST,RIGHT

      ITEM('Contents'),USE(?HelpContents),STD(STD:HelpIndex)

      ITEM('Search for Help On...'),USE(?HelpSearch),STD(STD:HelpSearch)

      ITEM('How to Use Help'),USE(?HelpOnHelp),STD(STD:HelpOnHelp)

      ITEM('About MyApp...'),USE(?HelpAbout)

    END

  END

END


ITEM  (declare a menu item)

ITEM(text) [,USE( )] [,KEY( )] [,MSG( )] [,HLP( )] [,STD( )] [,CHECK] [,DISABLE]
[,	| FIRST	| ] [,SEPARATOR] [,HIDE]
| LAST	|

ITEM	Declares a menu choice within a MENUBAR or MENU structure.

text	A string constant containing the display text for the menu item.

USE	A variable (only for use with the CHECK attribute) or field equate label to reference the menu item in executable code.

KEY	Specifies an integer constant or keycode equate that immediately executes the menu item.

MSG	Specifies a string constant containing the text to display in the status bar when the menu item is highlighted.

HLP	Specifies a string constant containing the help system identifier for the menu item.

STD	Specifies an integer constant or equate that identifies a "Windows standard action" the menu item executes.

CHECK	Specifies an on/off ITEM.

DISABLE	Specifies the menu item appears dimmed when the WINDOW or APPLICATION is first opened.

FIRST	Specifies the ITEM appears at the top of the menu when menus are merged.

LAST	Specifies the ITEM appears at the bottom of the menu when menus are merged.

SEPARATOR	Specifies the ITEM display a solid horizontal line across the menu box at run-time to delimit groups of menu selections.  No other attributes may be specified with SEPARATOR.

HIDE	Specifies the menu item does not appear when the WINDOW or APPLICATION is first opened; UNHIDE must be used to display it.

ITEM declares a menu choice within a MENUBAR or MENU structure.  The text string may contain an ampersand ( & ) which designates the following character as an accelerator "hot" key which is automatically underlined.  If the ITEM is on the menu bar, pressing the Alt key together with the accelerator key highlights and executes the ITEM.  If the ITEM is in a MENU, pressing the accelerator key, alone, when the menu is displayed, highlights and executes the ITEM.  If there is no ampersand in the text, the first non-blank character in the text string is the accelerator key for the ITEM, which will not be underlined.  To include an ampersand as part of the text, place two ampersands together (&&) in the text string and only one will display.

The KEY attribute designates a separate "hot" key for the field.  This may be any valid Clarion keycode to immediately execute the ITEM's action.

A cursor bar highlights individual ITEMs within the MENU structure.  Each ITEM is usually associated with some code to be executed upon selection of that ITEM, unless the STD attribute is present.  The STD atribute specifies a standard Windows action the menu item performs, such as Tile or Cascade the windows.

The SEPARATOR attribute creates an ITEM which serves only to delimit groups of menus selections so it should not have a text parameter, nor any other attributes.  It creates a solid horizontal line across the menu box.

An ITEM that is not within a MENU structure is placed on the menu bar.  This creates a menu bar selection which has no related drop-down menu.  The normal convention to indicate this to the user is to terminate the text displayed for the item with an exclamation point (!).  For example, the text for the ITEM might contain 'Exit!' to alert the user to the executable nature of the menu choice.

Example:

!An MDI application frame window with main menu for the application:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    ITEM('E&xit!'),USE(?MainExit),FIRST

    MENU('File'),USE(?FileMenu),FIRST

      ITEM('Open...'),USE(?OpenFile) ,HLP('OpenFileHelp') ,FIRST

      ITEM('Close'),USE(?CloseFile),HLP('CloseFileHelp'),DISABLE

      ITEM('Auto Increment'),USE(ToggleVar),CHECK

    END

    MENU('Edit'),USE(?EditMenu),KEY(CtrlE),HLP('EditMenuHelp')

      ITEM('Undo'),USE(?UndoText),KEY(CtrlZ),STD(STD:Undo),DISABLE

      ITEM,SEPARATOR

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut),DISABLE

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy),DISABLE

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste),DISABLE

    END

    MENU('Window'),STD(STD:WindowList),MSG('Arrange or Select Window'),LAST

      ITEM('Tile'),STD(STD:TileWindow)

      ITEM('Cascade'),STD(STD:CascadeWindow)

      ITEM('Arrange Icons'),STD(STD:ArrangeIcons)

      ITEM,SEPARATOR

    END

    MENU('Help'),USE(?HelpMenu),LAST,RIGHT

      ITEM('Contents'),USE(?HelpContents),STD(STD:HelpIndex)

      ITEM('Search for Help On...'),USE(?HelpSearch),STD(STD:HelpSearch)

      ITEM('How to Use Help'),USE(?HelpOnHelp),STD(STD:HelpOnHelp)

      ITEM('About MyApp...'),USE(?HelpAbout),MSG('Copyright Info'),LAST

    END

  END

END


TOOLBAR and WINDOW Control Fields

BOX  (declare a window box control)

BUTTON  (declare a pushbutton control)

CHECK  (declare a window checkbox control)

COMBO  (declare an entry/list control)

CUSTOM  (declare a window .VBX custom control)

ELLIPSE  (declare a window ellipse control)

ENTRY  (declare a data entry control)

GROUP  (declare a group of window controls)

IMAGE  (declare a window graphic image control)

LINE  (declare a window line control)

LIST  (declare a window list control)

OPTION  (declare a group of window RADIO controls)

PROMPT  (declare a prompt control)

RADIO  (declare a window radio button control)

REGION  (declare a window region control)

SPIN  (declare a spinning list control)

STRING  (declare a window string control)

TEXT  (declare a multi-line data entry control)


BOX  (declare a window box control)

BOX ,AT( ) [,USE( )] [,DISABLE] [,COLOR( )] [,FILL( )] [,ROUND] [,FULL]
[,SCROLL] [,HIDE]

BOX	Places a rectangular box on the window.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the control appears dimmed when the WINDOW (or APPLICATION) is first opened.

COLOR	Specifies the color for the border of the control.  If omitted, the border is black.

FILL	Specifies the fill color for the control.  If omitted, the box is not filled with color.

ROUND	Specifies the box corners are rounded.  If omitted, the corners are square.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

The BOX control places a rectangular box on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  This control cannot receive input focus and does not generate events.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  BOX,FILL(COLOR:MENU),FULL	!Filled, full screen, black border

  BOX,AT(0,0,20,20)	!Unfilled, black border

  BOX,AT(0,20,20,20),USE(?Box1),DISABLE	!Unfilled, black border, dimmed

  BOX,AT(20,20,20,20),ROUND	!Unfilled, rounded, black border

  BOX,AT(40,40,20,20),FILL(COLOR:ACTIVEBORDER)	!Filled, black border

  BOX,AT(60,60,20,20),COLOR(COLOR:ACTIVEBORDER)

!Unfilled, active border color border

  BOX,AT(480,180,20,20),SCROLL	!Scrolls with screen

END


BUTTON  (declare a pushbutton control)

BUTTON(text) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )] [,MSG( )]
[,HLP( )] [,SKIP] [,STD( )] [,FONT( )] [,ICON( )] [,DEFAULT] [,IMM]
[,REQ] [,FULL] [,SCROLL] [,ALRT( )] [,HIDE] [DROPID( )]

BUTTON	Places a pushbutton on the WINDOW or TOOLBAR.

text	A string constant containing the text to display on the button.  This may contain an ampersand (&) to indicate the "hot" letter (accelerator key) for the button.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to and presses the button.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control does not receive input focus and may only be accessed with the mouse or accelerator key.

STD	Specifies an integer constant or equate that identifies a "Windows standard action" the control executes.

FONT	Specifies the display font for the control.

ICON	Specifies an .ICO file or standard icon to display on the button face.

DEFAULT	Specifies the BUTTON is automatically pressed when the user presses the ENTER key.

IMM	Specifies the control generates an event when the left mouse button is pressed, continuing as long as it is depressed.  If omitted, an event is generated only when the left mouse button is pressed and released on the control.

REQ	Specifies that when the BUTTON is pressed, the runtime library automatically checks all ENTRY controls in the same WINDOW with the REQ attribute to ensure they contain data other than blanks or zeroes.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

ALRT	Specifies "hot" keys active for the control.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

The BUTTON control places a pushbutton on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.

A BUTTON with the IMM attribute generates an event as soon as the left mouse button is pressed on the control and continues to do so until it is released.  This allows the BUTTON control's executable code to execute continuously until the mouse button is released.  A BUTTON without the IMM attribute generates an event only when the left mouse button is pressed and released on the control.

A BUTTON with the REQ attribute is a "required control fields check" button.  REQ attributes of ENTRY or TEXT control fields are not checked until a BUTTON with the REQ attribute is pressed or the INCOMPLETE function is called.  Focus is given to the first required control which is blank or zero.

A BUTTON with an ICON attribute displays the icon on the button face in place of its text parameter.  The text parameter then serves only for accelerator "hot" key definition.

Events Generated:

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The control has been pressed by the user.

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  BUTTON('1'),AT(0,0,20,20),USE(?B1)

  BUTTON('2'),AT(20,0,20,20),USE(?B2),KEY(F10Key)

  BUTTON('3'),AT(40,0,20,20),USE(?B3),MSG('Button 3')

  BUTTON('4'),AT(60,0,20,20),USE(?B4),HLP('Button4Help')

  BUTTON('5'),AT(80,0,20,20),USE(?B5),STD(STD:Cut)

  BUTTON('6'),AT(100,0,20,20),USE(?B6),FONT('Arial',12)

  BUTTON('7'),AT(120,0,20,20),USE(?B7),ICON(ICON:Question)

  BUTTON('8'),AT(140,0,20,20),USE(?B8),DEFAULT

  BUTTON('9'),AT(160,0,20,20),USE(?B9),IMM

  BUTTON('10'),AT(180,0,20,20),USE(?B10),CURSOR(CURSOR:Wait)

  BUTTON('11'),AT(200,0,20,20),USE(?B11),REQ

  BUTTON('12'),AT(220,0,20,20),USE(?B12),ALRT(F10Key)

  BUTTON('13'),AT(240,0,20,20),USE(?B13),SCROLL

END


CHECK  (declare a window checkbox control)

CHECK(text) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )] [,MSG( )]
[,HLP( )] [,SKIP] [,FONT( )] [,ICON( )] [,FULL] [,SCROLL] [,ALRT( )]
[,	| LEFT	| ] [,HIDE] [DROPID( )]
| RIGHT	|

CHECK	Places a check box on the WINDOW or TOOLBAR.

text	A string constant containing the text to display for the check box.  This may contain an ampersand (&) to indicate the "hot" letter for the check box.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	The label of a numeric variable to receive the value of the check box, zero (0 = OFF) or one (1 = ON).

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to and toggles the box.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control does not receive input focus and may only be accessed with the mouse or accelerator key.

FONT	Specifies the display font for the control.

ICON	Specifies an .ICO file or standard icon to display on the button face of a "latching" pushbutton.

LEFT	Specifies that the text appears to the left of the check box.

RIGHT	Specifies that the text appears to the right of the check box (the default position).

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

ALRT	Specifies "hot" keys active for the control.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

The CHECK control places a check box on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.

A CHECK with an ICON attribute appears as a "latched" button with the icon displayed on the button face.  When the button appears "up" the CHECK is off and the USE variable receives a zero (0); when it appears "down" the CHECK is on and the USE variable receives a one (1).

Events Generated:

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The control has been toggled by the user.

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  CHECK('1'),AT(0,0,20,20),USE(?C1)

  CHECK('2'),AT(0,20,20,20),USE(?C2),KEY(F10Key)

  CHECK('3'),AT(0,40,20,20),USE(?C3),MSG('Button 3')

  CHECK('4'),AT(0,60,20,20),USE(?C4),HLP('Check4Help')

  CHECK('5'),AT(20,80,20,20),USE(?C5),LEFT

  CHECK('6'),AT(0,100,20,20),USE(?C6),FONT('Arial',12)

  CHECK('7'),AT(0,120,20,20),USE(?C7),ICON(ICON:Question)

  CHECK('8'),AT(0,140,20,20),USE(?C8),DEFAULT

  CHECK('9'),AT(0,160,20,20),USE(?C9),IMM

  CHECK('10'),AT(0,180,20,20),USE(?C10),CURSOR(CURSOR:Wait)

  CHECK('11'),AT(0,200,20,20),USE(?C11),ALRT(F10Key)

END


COMBO  (declare an entry/list control)

COMBO(picture) ,FROM( ) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )]
[,MSG( )] [,HLP( )] [,SKIP] [,FONT( )] [,FORMAT( )] [,DROP] [,COLUMN]
[,VCR] [,FULL] [,SCROLL] [,ALRT( )] [,HIDE] [,READONLY] [,REQ]
[,NOBAR] [DROPID( )]
[,	| MARK()	|][,	| HSCROLL	|][,	| LEFT	|][,	| INS	|]
| IMM	| 	| VSCROLL	| 	| RIGHT	| 	| OVR	|
| HVSCROLL	|	| CENTER	|
| DECIMAL	|
[,	| UPR	|]
| CAP	|

COMBO	Places a data entry field with an associated list of data items on the WINDOW or TOOLBAR.

picture	A display picture token that specifies the input format for the data entered into the control.

FROM	Specifies the origin of the data displayed in the list.

AT	Specifies the initial size and location of the control.  If omitted, the runtime library chooses a value.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code or the label of the variable that receives the value selected by the user.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to the control.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control receives input focus to enter text only with the mouse or accelerator key and does not retain focus.

FONT	Specifies the display font for the control.

FORMAT	Specifies the the display format of the data.

DROP	Specifies a drop-down list box and the number of elements the drop-down portion contains.

COLUMN	Specifies a field-by-field highlight bar on multi-column list boxes.

VCR	Specifies a VCR-type control to the left of the horizontal scroll bar (if present).

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

ALRT	Specifies "hot" keys active for the control.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

READONLY	Specifies the control does not allow data entry.

NOBAR	Specifies the highlight bar is displayed only when the LIST has focus.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

REQ	Specifies the control may not be left blank or zero.

MARK	Specifies multiple item selection mode.

IMM	Specifies generation of an event whenever the user presses any key.

HSCROLL	Specifies that a horizontal scroll bar is automatically added to the list box when any portion of the data item lies horizontally outside the visible area.

VSCROLL	Specifies that a vertical scroll bar is automatically added to the list box when any data items lie vertically outside the visible area.

HVSCROLL	Specifies that both vertical and horizontal scroll bars are automatically added to the list box when any portion of the data items lies outside the visible area.

LEFT	Specifies that the data is left justified within the list.

RIGHT	Specifies that the data is right justified within the list.

CENTER	Specifies that the data is centered within the list.

DECIMAL	Specifies that the data is aligned on the decimal point within the list.

INS / OVR	Specifies Insert or Overwrite entry mode (valid only on windows with the MASK attribute).

UPR / CAP	Specifies all upper case or proper name capitalization (First Letter Of Each Word Capitalized) entry.

The COMBO control places a data entry field with an associated list of data items on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute (a combination of an ENTRY and LIST control).  The user may type in data or select an item from the list.  The entered data is not automatically validated against the entries in the list.  The data entry portion of the COMBO acts as an "incremental locator" to the list as the user types each character, the highlight bar is positioned to the closest matching entry.

A COMBO with the DROP attribute displays only the currently selected data item on screen until the control has focus and the user presses the down arrow key, or CLICKS ON the the icon to the right of the displayed data item.  When either of these occurs, the selection list appears ("drops down") to allow the user to select an item.

A COMBO with the IMM attribute generates an event every time the user moves the highlight bar to another selection, or pressed any key that causes the displayed entries to scroll.  This allows an opportunity for the source code to re-fill the display QUEUE, or get the currently highlighted record to display other fields from the record.  A COMBO with the VCR attribute has scroll control buttons like a Video Cassette Recorder to the left of the horizontal scroll bar (if there is one).  These buttons allow the user to use the mouse to scroll through the list.

Events Generated:

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The user has selected an entry.

EVENT:NewSelection

The current selection in the list has changed (highlight has moved up or down).

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

  A COMBO with the IMM attribute also generates the following events:

EVENT:ScrollUp

The highlight bar has attempted to move off the top of the LIST.

EVENT:ScrollDown

The highlight bar has attempted to move off the bottom of the LIST.

EVENT:PageUp

The user pressed PgUp.

EVENT:PageDown

The user pressed PgDn.

EVENT:ScrollTop

The user pressed Ctrl-PgUp.

EVENT:ScrollBottom

The user pressed Ctrl-PgDn.

EVENT:PreAlert

The user pressed a printable character or an ALRT attribute hot key.

EVENT:AlertKey

The user pressed a printable character or an ALRT attribute hot key.

EVENT:Locate

The user pressed the locator VCR button.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  COMBO(@S8),AT(0,0,20,20),USE(?C1),FROM(Que)

  COMBO(@S8),AT(20,0,20,20),USE(?C2),FROM(Que),KEY(F10Key)

  COMBO(@S8),AT(40,0,20,20),USE(?C3),FROM(Que),MSG('Button 3')

  COMBO(@S8),AT(60,0,20,20),USE(?C4),FROM(Que),HLP('Check4Help')

  COMBO(@S8),AT(80,0,20,20),USE(?C5),FROM(Q) |

,FORMAT('5C~List~15L~Box~'),COLUMN

  COMBO(@S8),AT(100,0,20,20),USE(?C6),FROM(Que),FONT('Arial',12)

  COMBO(@S8),AT(120,0,20,20),USE(?C7),FROM(Que),DROP(8)

  COMBO(@S8),AT(140,0,20,20),USE(?C8),FROM(Que),HVSCROLL,VCR

  COMBO(@S8),AT(160,0,20,20),USE(?C9),FROM(Que),IMM

  COMBO(@S8),AT(180,0,20,20),USE(?C10),FROM(Que),CURSOR(CURSOR:Wait)

  COMBO(@S8),AT(200,0,20,20),USE(?C11),FROM(Que),ALRT(F10Key)

  COMBO(@S8),AT(220,0,20,20),USE(?C12),FROM(Que),LEFT

  COMBO(@S8),AT(240,0,20,20),USE(?C13),FROM(Que),RIGHT

  COMBO(@S8),AT(260,0,20,20),USE(?C14),FROM(Que),CENTER

  COMBO(@N8.2),AT(280,0,20,20),USE(?C15),FROM(Que),DECIMAL

END

See Also:

LIST

ENTRY


CUSTOM  (declare a window .VBX custom control)

CUSTOM(text) ,AT( ) [,CLASS( )] [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )]
[,MSG( )] [,HLP( )] [,SKIP] [,FULL] [,SCROLL] [,ALRT( )] [,HIDE] [,FONT( )]
[DROPID( )] [,property( value )]

CUSTOM	Places a Visual Basic .VBX control on the WINDOW or TOOLBAR.

text	A string constant containing the title for the control.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the control.

CLASS	Specifies the .VBX filename and type of control.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	The label of a variable to receive the value of the control.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to the control.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control does not receive input focus and may only be accessed with the mouse or accelerator key.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

ALRT	Specifies "hot" keys active for the control.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

FONT	Specifies the display font for the control.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

property	A string constant containing the name of a custom property setting for the control.

value	A string constant containing the property value number or EQUATE for the property.

The CUSTOM control places a Visual Basic .VBX control on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.

The property attribute allows you to specify any additional property settings the .VBX control may require.  These are properties that need to be set for the .VBX control to properly function, and are not standard Clarion properties (such as AT, CURSOR, or USE).  The custom control should only receive values for these properties that are defined for that control.  Valid properties and values for those properties would be defined in the custom control's documentation.  You may have multiple property attributes on a single CUSTOM control.

Events Generated:

EVENT:VBXevent

*** WHAT IS THIS EVENT ALL ABOUT???

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The user has completed using the control.

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  CUSTOM,AT(0,0,120,320),CLASS('graph.vbx','graph'),'graphstyle'('2')

END


ELLIPSE  (declare a window ellipse control)

ELLIPSE ,AT( ) [,USE( )] [,DISABLE] [,COLOR( )] [,FILL( )] [,FULL] [,SCROLL]
[,HIDE]

ELLIPSE	Places a "circular" figure on the WINDOW or TOOLBAR.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

COLOR	Specifies the color for the border of the ellipse.  If omitted, the ellipse has a black border.

FILL	Specifies the fill color for the control.  If omitted, the ellipse is not filled with color.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

The ELLIPSE control places a "circular" figure on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  The ellipse is drawn inside a "bounding box" defined by the  x, y, width, and height parameters of it sAT attribute.  The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the "bounding box."  This control cannot receive input focus and does not generate events.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  ELLIPSE,FILL(COLOR:MENU),FULL	!Filled, full screen, black border

  ELLIPSE,AT(0,0,20,20)	!Unfilled, black border

  ELLIPSE,AT(0,20,20,20),USE(?Box1),DISABLE !Dimmed

  ELLIPSE,AT(20,20,20,20),ROUND	!Unfilled, rounded, black border

  ELLIPSE,AT(40,40,20,20),FILL(COLOR:ACTIVEBORDER) !Filled, black border

  ELLIPSE,AT(60,60,20,20),COLOR(COLOR:ACTIVEBORDER)

!Unfilled, active border color border

  ELLIPSE,AT(480,180,20,20),SCROLL !Scrolls with screen

END


ENTRY  (declare a data entry control)

ENTRY(picture) ,AT() [,CURSOR()] [,USE()] [,DISABLE] [,KEY()] [,MSG()]
[,HLP()] [,SKIP] [,FONT()] [,IMM] [,PASSWORD] [,REQ] [,FULL] [,SCROLL]
[,ALRT()] [,HIDE] [,READONLY] [DROPID( )]
[,	 INS	 ] [,	 CAP	 ] [,	 LEFT	 ]
 OVR	 	 UPR	 	 RIGHT
 CENTER
 DECIMAL

ENTRY	Places a data entry field on the WINDOW or TOOLBAR.

picture	A display picture token that specifies the input format for the data entered into the control.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	The label of the variable that receives the value entered into the control by the user.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to the control.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control receives input focus to enter text only with the mouse or accelerator key and does not retain focus.

FONT	Specifies the display font for the control.

IMM	Specifies immediate event generation whenever the user presses any key.

PASSWORD	Specifies non-display of the data entered (password mode).

REQ	Specifies the control may not be left blank or zero.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

ALRT	Specifies "hot" keys active for the control.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

READONLY	Specifies the control does not allow data entry.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

INS / OVR	Specifies Insert or Overwrite entry mode (valid only on windows with the MASK attribute).

UPR / CAP	Specifies all upper case or proper name capitalization (First Letter Of Each Word Capitalized) entry.

LEFT	Specifies that the data entered is left justified within the area specified by the AT attribute.

RIGHT	Specifies that the data entered is right justified within the area specified by the AT attribute.

CENTER	Specifies that the data entered is centered within the area specified by the AT attribute.

DECIMAL	Specifies that the data entered is aligned on the decimal point within the area specified by the AT attribute.

The ENTRY control places a data entry field on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  Data entered is formatted according to the picture, and the variable specified in the USE attribute receives the data entered when the user has completed data entry and moves on to another control.  Data entry scrolls horizontally to allow the user to enter data to the full length of the variable.  Therefore, the right and left arrow keys move within the data in the ENTRY control.

An ENTRY control with the PASSWORD attribute displays asterisks when the user enters data.  This is useful for password-type variables.  An ENTRY control with the SKIP attribute is used for seldom-used data entry.  Display-only data should be declared with the READONLY attribute.

The MASK attribute on a WINDOW specifies pattern input editing mode of all controls in the window.  This means that, as the user types in data, each character is automatically validated against the control's picture for proper input (numbers only in numeric pictures, etc.).  This forces the user to enter data in the format specified by the control's display picture.  If omitted, Windows free-input is allowed in the controls.  This is Windows' default data entry mode.  Free-input means the user's data is formatted to the control's picture only after entry.  This allows users to enter data as they choose and it is automatically formatted to the control's picture after entry.  If the user types in data in a format different from the control's picture, the libraries attempt to determine the format the user used, and convert the data to the control's display picture.  For example, if the user types "January 1, 1995" into a control with a display picture of @D1, the runtime library formats the user's input to "1/1/95."  This action occurs only after the user completes data entry and moves to another control.  If the runtime library cannot determine what format the user used, it will not update the USE variable.  It then beeps and leaves the user on the same control with the data they entered, to allow them to try again.

Events Generated:

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The user has completed data entry in the control.

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

  An ENTRY with the IMM attribute also generates the following events:

EVENT:NewSelection

The user has pressed a key.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  ENTRY(@S8),AT(0,0,20,20),USE(E1)

  ENTRY(@S8),AT(20,0,20,20),USE(E2),KEY(F10Key)

  ENTRY(@S8),AT(40,0,20,20),USE(E3),MSG('Button 3')

  ENTRY(@S8),AT(60,0,20,20),USE(E4),HLP('Entry4Help')

  ENTRY(@S8),AT(80,0,20,20),USE(E5),DISABLE

  ENTRY(@S8),AT(100,0,20,20),USE(E6),FONT('Arial',12)

  ENTRY(@S8),AT(120,0,20,20),USE(E7),REQ,INS,CAP

  ENTRY(@S8),AT(140,0,20,20),USE(E8),SCROLL,OVR,UPR

  ENTRY(@S8),AT(160,0,20,20),USE(E9),IMM

  ENTRY(@S8),AT(180,0,20,20),USE(E10),CURSOR(CURSOR:Wait)

  ENTRY(@S8),AT(200,0,20,20),USE(E11),ALRT(F10Key)

  ENTRY(@S8),AT(220,0,20,20),USE(E12),LEFT

  ENTRY(@S8),AT(240,0,20,20),USE(E13),RIGHT

  ENTRY(@S8),AT(260,0,20,20),USE(E14),CENTER

  ENTRY(@N8.2),AT(280,0,20,20),USE(E15),DECIMAL

END


GROUP  (declare a group of window controls)

GROUP(text) ,AT() [,CURSOR()] [,USE()] [,DISABLE] [,KEY()] [,MSG()]
[,HLP()] [,FONT()] [,BOXED] [,FULL] [,SCROLL] [,HIDE] [,ALRT( )] [,SKIP]
  controls
END

GROUP	Declares a group of controls that may be referenced as one entity.

text	A string constant containing the prompt for the group of controls.  This may contain an ampersand (&) to indicate the "hot" letter for the prompt.  The text is displayed on screen only if the BOXED attribute is also present.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control (or any control within the GROUP).  If omitted, the window's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the GROUP control and the controls in the GROUP appear dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to the first control in the GROUP.

MSG	Specifies a string constant containing the default text to display in the status bar when any control in the GROUP has focus.

HLP	Specifies a string constant containing the default help system identifier for any control in the GROUP.

FONT	Specifies the display font for the control and the default for all the controls in the GROUP.

BOXED	Specifies a single-track border around the group of controls with the text at the top of the border.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the GROUP control and the controls in the GROUP scroll with the window.

HIDE	Specifies the GROUP control and the controls in the GROUP do not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display them.

ALRT	Specifies "hot" keys active for the controls in the GROUP.

SKIP	Specifies the controls in the GROUP do not receive input focus and may only be accessed with the mouse or accelerator key.

controls	Control declarations that may be referenced as the GROUP.

The GROUP control declares a group of controls that may be referenced as one entity.  GROUP allows the user to use the cursor keys instead of the TAB key to move between the controls in the GROUP, and provides default MSG and HLP attributes for all controls in the GROUP.

This control cannot receive input focus and does not generate events.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  GROUP('Group 1'),USE(?G1),KEY(F10Key)

    ENTRY(@S8),AT(0,0,20,20),USE(?E1)

    ENTRY(@S8),AT(20,0,20,20),USE(?E2)

  END

  GROUP('Group 2'),USE(?G2),MSG('Group 2')

    ENTRY(@S8),AT(40,0,20,20),USE(?E3)

    ENTRY(@S8),AT(60,0,20,20),USE(?E4)

  END

  GROUP('Group 3'),USE(?G3),AT(80,0,20,20),BOXED

    ENTRY(@S8),AT(80,0,20,20),USE(?E5)

    ENTRY(@S8),AT(100,0,20,20),USE(?E6)

  END

  GROUP('Group 4'),USE(?G4),FONT('Arial',12)

    ENTRY(@S8),AT(120,0,20,20),USE(?E7)

    ENTRY(@S8),AT(140,0,20,20),USE(?E8)

  END

  GROUP('Group 5'),USE(?G5),CURSOR(CURSOR:Wait)

    ENTRY(@S8),AT(160,0,20,20),USE(?E9)

    ENTRY(@S8),AT(180,0,20,20),USE(?E10)

  END

  GROUP('Group 6'),USE(?G6),SCROLL

    ENTRY(@S8),AT(200,0,20,20),USE(?E11)

    ENTRY(@S8),AT(220,0,20,20),USE(?E12)

  END

  GROUP('Group 7'),USE(?G7),HLP('Group7Help')

    ENTRY(@S8),AT(240,0,20,20),USE(?E13)

    ENTRY(@S8),AT(260,0,20,20),USE(?E14)

  END

END


IMAGE  (declare a window graphic image control)

IMAGE(file) ,AT( ) [,USE( )] [,DISABLE] [,FULL] [,SCROLL] [,HIDE]
[,	 HSCROLL	 ]
 VSCROLL
 HVSCROLL

IMAGE	Places a graphic image on the WINDOW or TOOLBAR.

file	A string constant containing the name of the file to display.  The file is linked into the .EXE as a resource.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

HSCROLL	Specifies that a horizontal scroll bar is automatically added to the IMAGE control when the graphic image is wider than the area specified for display.

VSCROLL	Specifies that a vertical scroll bar is automatically added to the IMAGE control when the graphic image is taller than the area specified for display.

HVSCROLL	Specifies that both vertical and horizontal scroll bars are automatically added to the IMAGE control when the graphic image is larger than the display area.

The IMAGE control places a graphic image on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  This may be a bitmap (.BMP), icon (.ICO), or Windows metafile (.WMF).  This control cannot receive input focus and does not generate events.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  IMAGE('PIC.BMP'),AT(0,0,20,20),USE(?I1)

  IMAGE('PIC.WMF'),AT(40,0,20,20),USE(?I3),SCROLL

END


LINE  (declare a window line control)

LINE ,AT( ) [,USE( )] [,DISABLE] [,COLOR( )] [,FULL] [,SCROLL] [,HIDE]

LINE	Places a straight line on the WINDOW or TOOLBAR.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

COLOR	Specifies the color for the line.  If omitted, the color is black.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

The LINE control places a straight line on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  The x and y parameters of the AT attribute specify the starting point of the line.  The width and height parameters of the AT attribute specify the horizontal and vertical distance to the end point of the line.  If these are both positive numbers, the line slopes to the right and down from its starting point.  If the width is negative, the line slopes left; if the height is negative, the line slopes left.  If either the width or height is zero, the line is horizontal or vertical.  This control cannot receive input focus and does not generate events.

Width	Height	Result

    	positive	positive	right and down from start point

negative	positive	left and down from start point

positive	negative	right and up from start point

negative	negative	left and up from start point

zero	positive	vertical, down from start point

zero	negative	vertical, up from start point

positive	zero	horizontal, right from start point

negative	zero	horizontal, left from start point

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  LINE,AT(60,60,20,20),COLOR(COLOR:ACTIVEBORDER)  !Border color

  LINE,AT(480,180,20,20),SCROLL	!Scrolls with screen

END


LIST  (declare a window list control)

LIST ,FROM( ) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )] [,MSG( )]
[,HLP( )] [,SKIP] [,FONT( )] [,FORMAT( )] [,DROP] [,COLUMN] [,VCR] [,FULL]
[,SCROLL] [,NOBAR] [,ALRT( )] [,HIDE] [,DRAGID( )] [,DROPID( )]
[,	 MARK( )	 ] [,	 HSCROLL	 ] [,	 LEFT	 ]
 IMM	 	 VSCROLL	 	 RIGHT
 HVSCROLL	 CENTER
 DECIMAL

LIST	Places a scrolling list of data items on the WINDOW or TOOLBAR.

FROM	Specifies the origin of the data displayed in the list.

AT	Specifies the initial size and location of the control.  If omitted, the runtime library chooses a value.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code, or the label of the variable that receives the value selected by the user.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to the control.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control does not receive input focus and may only be accessed with the mouse or accelerator key.

FONT	Specifies the display font for the control.

FORMAT	Specifies the display format of the data.

DROP	Specifies a drop-down list box and the number of elements the drop-down portion contains.

COLUMN	Specifies a field-by-field highlight bar on multi-column list boxes.

VCR	Specifies a VCR-type control to the left of the horizontal scroll bar (if present).

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

NOBAR	Specifies the highlight bar is displayed only when the LIST has focus.

ALRT	Specifies "hot" keys active for the control.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

DRAGID	Specifies the control may serve as a drag host for drag-and-drop actions.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

MARK	Specifies multiple items selection mode.

IMM	Specifies generation of an event whenever the user presses any key.

HSCROLL	Specifies that a horizontal scroll bar is automatically added to the list box when any portion of the data item lies horizontally outside the visible area.

VSCROLL	Specifies that a vertical scroll bar is automatically added to the list box when any data items lie vertically outside the visible area.

HVSCROLL	Specifies that both vertical and horizontal scroll bars are automatically added to the list box when any portion of the data items lies outside the visible area.

LEFT	Specifies that the data is left justified within the LIST.

RIGHT	Specifies that the data is right justified within the LIST.

CENTER	Specifies that the data is centered within the LIST.

DECIMAL	Specifies that the data is aligned on the decimal point within the LIST.

The LIST control places a scrolling list of data items on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  The data items displayed in the LIST come from a QUEUE or STRING specified by the FROM attribute.  The CHOICE function returns the QUEUE entry number (the value returned by POINTER(queue)) of the selected item when the EVENT:Accepted event has been generated by the LIST.

A LIST with the DROP attribute displays only the currently selected data item on screen until the control has focus and the user presses the down arrow key, or CLICKS ON the the icon to the right of the displayed data item.  When either of these occurs, the selection list appears ("drops down") to allow the user to select an item.

A LIST with the IMM attribute generates an event every time the user moves the highlight bar to another selection, or pressed any key that causes the displayed entries to scroll.  This allows an opportunity for the source code to re-fill the display QUEUE, or get the currently highlighted record to display other fields from the record.

A LIST with the VCR attribute has scroll control buttons like a Video Cassette Recorder to the left of the horizontal scroll bar (if there is one).  These buttons allow the user to use the mouse to scroll through the list.

A LIST with the DRAGID attribute can serve as a drag-and-drop host, providing information to be moved or copied to another control.  A LIST with the DROPID attribute can serve as a drag-and-drop target, receiving information from another control.  These attributes work together to specify drag-and-drop "signatures" that define a valid target for the operation.  The DRAGID() and DROPID() functions, along with the SETDROPID procedure, are used to perform the data exchange.

Events Generated:

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The user has selected an entry from the control.

EVENT:NewSelection

The current selection in the list has changed (highlight has moved up or down).

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

  A LIST with the IMM attribute also generates the following events:

EVENT:ScrollUp

The highlight bar has attempted to move off the top of the LIST.

EVENT:ScrollDown

The highlight bar has attempted to move off the bottom of the LIST.

EVENT:PageUp

The user pressed PgUp.

EVENT:PageDown

The user pressed PgDn.

EVENT:ScrollTop

The user pressed Ctrl-PgUp.

EVENT:ScrollBottom

The user pressed Ctrl-PgDn.

EVENT:PreAlert

The user pressed a printable character or an ALRT attribute hot key.

EVENT:AlertKey

The user pressed a printable character or an ALRT attribute hot key.

EVENT:Locate

The user pressed the locator VCR button.

  A LIST with the DRAGID attribute also generates the following events:

EVENT:Dragging

The mouse cursor is over a potential drag target.

EVENT:Drag

The mouse cursor has been released over a drag target.

  A LIST with the DROPID attribute also generates the following events:

EVENT:Drop

The mouse cursor has been released over a drag target.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  LIST,AT(0,0,20,20),USE(?L1),FROM(Que),IMM

  LIST,AT(20,0,20,20),USE(?L2),FROM(Que),KEY(F10Key)

  LIST,AT(40,0,20,20),USE(?L3),FROM(Que),MSG('Button 3')

  LIST,AT(60,0,20,20),USE(?L4),FROM(Que),HLP('Check4Help')

  LIST,AT(80,0,20,20),USE(?L5),FROM(Q),FORMAT('5C~List~15L~Box~'),COLUMN

  LIST,AT(100,0,20,20),USE(?L6),FROM(Que),FONT('Arial',12)

  LIST,AT(120,0,20,20),USE(?L7),FROM(Que),DROP(6)

  LIST,AT(140,0,20,20),USE(?L8),FROM(Que),HVSCROLL,VCR

  LIST,AT(180,0,20,20),USE(?L10),FROM(Que),CURSOR(CURSOR:Wait)

  LIST,AT(200,0,20,20),USE(?L11),FROM(Que),ALRT(F10Key)

  LIST,AT(220,0,20,20),USE(?L12),FROM(Que),LEFT

  LIST,AT(240,0,20,20),USE(?L13),FROM(Que),RIGHT

  LIST,AT(260,0,20,20),USE(?L14),FROM(Que),CENTER

  LIST,AT(280,0,20,20),USE(?L15),FROM(Que),DECIMAL

END

See Also:

COMBO

DRAGID

DROPID

SETDROPID


OPTION  (declare a group of window RADIO controls)

OPTION(text) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )] [,MSG( )]
[,HLP( )] [,BOXED] [,FULL] [,SCROLL] [,HIDE] [,FONT( )] [,ALRT( )] [,SKIP]
[DROPID( )]
  radios
END

OPTION	Declares a group of RADIO controls.

text	A string constant containing the prompt for the group of controls.  This may contain an ampersand (&) to indicate the "hot" letter for the prompt.  The text is displayed on screen only if the BOXED attribute is also present.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	The label of a string variable to receive the value of the RADIO string (with any accelerator key ampersand stripped out) selected by the user.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to the currently selected RADIO in the OPTION control.

MSG	Specifies a string constant containing the default text to display in the status bar when any control in the OPTION has focus.

HLP	Specifies a string constant containing the default help system identifier for any control in the OPTION.

BOXED	Specifies a single-track border around the RADIO controls with the text at the top of the border.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

FONT	Specifies the display font for the control and the default for all the controls in the OPTION.

ALRT	Specifies "hot" keys active for the controls in the OPTION.

SKIP	Specifies the controls in the OPTION do not receive input focus and may only be accessed with the mouse or accelerator key.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

radios	Multiple RADIO control declarations.

The OPTION control declares a group of RADIO controls that offer the user a list of choices.  The multiple RADIO controls in the OPTION structure define the choices offered to the user.

Input focus changes between the OPTION's RADIO controls are signalled only to the individual RADIO controls affected.  This means the events generated when the user changes input focus within an OPTION structure are field-specific events for the affected RADIO controls, not the OPTION structure which contains them.

The variable named in the OPTION structure's USE attribute receives the text of the RADIO control selected by the user.  The CHOICE(?Option) function returns the number of the selected RADIO.  No RADIO button selected is a valid option, which occurs only when the OPTION structure's USE variable does not contain a value duplicated by one of its component RADIO controls.  This condition only lasts until the user has selected one of the RADIOs.

Events Generated:

EVENT:Selected

One of the OPTION's RADIO controls has received input focus.

EVENT:Accepted

One of the OPTION's RADIO controls has been selected by the user.

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  OPTION('Option 1'),USE(OptVar1),KEY(F10Key),HLP('Option1Help')

    RADIO('Radio 1'),AT(0,0,20,20),USE(?R1)

    RADIO('Radio 2'),AT(20,0,20,20),USE(?R2)

  END

  OPTION('Option 2'),USE(OptVar2),MSG('Option 2'),SCROLL

    RADIO('Radio 3'),AT(40,0,20,20),USE(?R3)

    RADIO('Radio 4'),AT(60,0,20,20),USE(?R4)

  END

  OPTION('Option 3'),USE(OptVar3),AT(80,0,20,20),BOXED

    RADIO('Radio 5'),AT(80,0,20,20),USE(?R5)

    RADIO('Radio 6'),AT(100,0,20,20),USE(?R6)

  END

  OPTION('Option 4'),USE(OptVar4),FONT('Arial',12),CURSOR(CURSOR:Wait)

    RADIO('Radio 7'),AT(120,0,20,20),USE(?R7)

    RADIO('Radio 8'),AT(140,0,20,20),USE(?R8)

  END

END

See Also:

RADIO


PROMPT  (declare a prompt control)

PROMPT(text) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,FONT( )]
[,FULL] [,SCROLL] [,HIDE] [,	 LEFT	 ]
 RIGHT

PROMPT	Places a prompt for the next control following it, in the WINDOW or TOOLBAR.

text	A string constant containing the text to display.  This may contain an ampersand (&) to indicate the "hot" letter for the prompt.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

FONT	Specifies the font used to display the text.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

LEFT	Specifies that the prompt is left justified.

RIGHT	Specifies that the prompt is right justified.

The PROMPT control places a prompt for the next control following the PROMPT in the WINDOW or TOOLBAR structure.  The prompt text is placed on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  The text may contain an ampersand (&) to indicate the letter immediately following the ampersand is the "hot" letter for the prompt.  By default, the "hot" letter displays with an underscore below it to indicate its special purpose.  This "hot" letter, when pressed in conjunction with the ALT key, changes input focus to the next control following the PROMPT in the WINDOW or TOOLBAR structure, which is capable of receiving focus.  To include an ampersand as part of the text, place two ampersands together (&&) in the text string and only one will display.  This control cannot receive input focus and does not generate events.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  PROMPT('Enter Data in E1:'),AT(10,100,20,20),USE(?P1),CURSOR(CURSOR:Wait)

  ENTRY(@S8),AT(100,100,20,20),USE(E1)

END


RADIO  (declare a window radio button control)

RADIO(text) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )] [,MSG( )]
 [,HLP( )] [,SKIP] [,FONT( )] [,ICON( )] [,FULL] [,SCROLL] [,HIDE]
 [,	 LEFT	 ] [,ALRT( )] [DROPID( )]
 RIGHT

RADIO	Places a radio button on the WINDOW or TOOLBAR.

text	A string constant containing the text to display for the radio button.  This may contain an ampersand (&) to indicate the "hot" letter for the radio button.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately selects the radio button.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control does not receive input focus and may only be accessed with the mouse or accelerator key.

FONT	Specifies the display font for the control.

ICON	Specifies an .ICO file or standard icon to display on the face of a "latching" button.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

LEFT	Specifies that the text appears to the left of the radio button.

RIGHT	Specifies that the text appears to the right of the radio button (the default position).

ALRT	Specifies "hot" keys active for the control.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

The RADIO control places a radio button on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  A RADIO control may only be placed within an OPTION control.  When selected by the user, the RADIO text (with any accelerator key ampersand stripped out) is placed in the OPTION's USE variable.  A RADIO with an ICON attribute appears as a "latched" pushbutton with the icon on the button face.  When the icon appears "up" the RADIO is off; when it appears "down" the RADIO is on and the OPTION's USE variable receives the value in the selected RADIO's text parameter.

Events Generated:

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The control has been selected by the user.

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  OPTION('Option 1'),USE(OptVar1)

    RADIO('Radio 1'),AT(0,0,20,20),USE(?R1),KEY(F10Key)

    RADIO('Radio 2'),AT(20,0,20,20),USE(?R2),MSG('Radio 2')

  END

  OPTION('Option 2'),USE(OptVar2)

    RADIO('Radio 3'),AT(40,0,20,20),USE(?R3),FONT('Arial',12)

    RADIO('Radio 4'),AT(60,0,20,20),USE(?R4),CURSOR(CURSOR:Wait)

  END

  OPTION('Option 3'),USE(OptVar3)

    RADIO('Radio 5'),AT(80,0,20,20),USE(?R5),HLP('Radio5Help')

    RADIO('Radio 6'),AT(100,0,20,20),USE(?R6)

  END

  OPTION('Option 4'),USE(OptVar4)

    RADIO('Radio 7'),AT(120,0,20,20),USE(?R7),ICON('Radio1.ICO')

    RADIO('Radio 8'),AT(140,0,20,20),USE(?R8),ICON('Radio2.ICO')

  END

  OPTION('Option 5'),USE(OptVar5)

    RADIO('Radio 9'),AT(100,20,20,20),USE(?R9),LEFT

    RADIO('Radio 10'),AT(120,20,20,20),USE(?R10),LEFT

  END

  OPTION('Option 6'),USE(OptVar6),SCROLL

    RADIO('Radio 11'),AT(200,0,20,20),USE(?R11),SCROLL

    RADIO('Radio 12'),AT(220,0,20,20),USE(?R12),SCROLL

  END

END

See Also:

OPTION


REGION  (declare a window region control)

REGION ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,FILL] [,COLOR( )] [,IMM]
[,FULL] [,SCROLL] [,HIDE] [,DRAGID( )] [,DROPID( )]

REGION	Defines an area in the WINDOW or TOOLBAR.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code.

DISABLE	Specifies the control is disabled when the WINDOW or APPLICATION is first opened.

FILL	Specifies the red, green, and blue component values that create the fill color for the control.  If omitted, the region is not filled with color.

COLOR	Specifies the border color of the control.  If omitted, there is no border.

IMM	Specifies control generates an event whenever the mouse is moved in the region.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

DRAGID	Specifies the control may serve as a drag host for drag-and-drop actions.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

The REGION control defines an area on screen at the position and size specified by its AT attribute.  Generally, tracking the position of the mouse is the reason for defining a REGION.  The MOUSEX and MOUSEY functions can be used to determine the exact position of the mouse when the event occurs.  Use of the IMM attribute causes some excess code and speed overhead at runtime, so it should be used only when necessary.  This control cannot receive input focus.

A REGION with the DRAGID attribute can serve as a drag-and-drop host, providing information to be moved or copied to another control.  A REGION with the DROPID attribute can serve as a drag-and-drop target, receiving information from another control.  These attributes work together to specify drag-and-drop "signatures" that define a valid target for the operation.  The DRAGID() and DROPID() functions, along with the SETDROPID procedure, are used to perform the data exchange.  Since a REGION can be defined over any other control, you can write drag-and-drop code between any two controls.  Simply define REGION controls to handle the required drag-and drop functionality.

Events Generated:

EVENT:Accepted

The mouse has been clicked by the user in the region.

  A REGION with the IMM attribute also generates the following events:

EVENT:MouseIn

The mouse has entered the region.

EVENT:MouseOut

The mouse has left the region.

EVENT:MouseMove

The mouse has moved within the region.

  A REGION with the DRAGID attribute also generates the following events:

EVENT:Dragging

The mouse cursor is over a potential drag target.

EVENT:Drag

The mouse cursor has been released over a drag target.

  A REGION with the DROPID attribute also generates the following events:

EVENT:Drop

The mouse cursor has been released over a drag target.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  REGION,AT(10,100,20,20),USE(?R1)

  REGION,AT(100,100,20,20),USE(?R2),CURSOR(CURSOR:Wait)

  REGION,AT(10,200,20,20),USE(?R3),IMM

  REGION,AT(100,200,20,20),USE(?R4),COLOR(COLOR:ACTIVEBORDER)

  REGION,AT(10,300,20,20),USE(?R4),FILL(COLOR:ACTIVEBORDER)

END


SPIN  (declare a spinning list control)

SPIN(picture) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )] [,MSG( )]
[,HLP( )] [,SKIP] [,FONT( )] [,FULL] [,SCROLL] [,ALRT( )] [,HIDE]
[,READONLY] [,REQ] [,IMM] [DROPID( )]
[,	 LEFT	 ] [,	 INS	 ] ,	 RANGE()[,STEP]	 [,	 UPR	]
 RIGHT	 	 OVR	 FROM( )	 CAP
 CENTER
 DECIMAL

SPIN	Places a "spinning" list of data items on the WINDOW or TOOLBAR.

picture	A display picture token that specifies the format for the data displayed in the control.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code or the label of the variable that receives the value selected by the user.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to the control.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control receives input focus to enter text only with the mouse or accelerator key and does not retain focus.

FONT	Specifies the display font for the control.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

ALRT	Specifies "hot" keys active for the control.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

READONLY	Specifies the control does not allow data entry.

REQ	Specifies the control may not be left blank or zero.

IMM	Specifies immediate event generation whenever the user presses any key.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

LEFT	Specifies that the data is left justified within the area specified by the AT attribute.

RIGHT	Specifies that the data is right justified within the area specified by the AT attribute.

CENTER	Specifies that the data is centered within the area specified by the AT attribute.

DECIMAL	Specifies that the data is aligned on the decimal point within the area specified by the AT attribute.

INS / OVR	Specifies Insert or Overwrite entry mode (valid only on windows with the MASK attribute).

RANGE	Specifies the range of values the user may choose.

STEP	Specifies the increment/decrement amount of the choices within the specified RANGE.  If omitted, the STEP is 1.0.

FROM	Specifies the origin of the choices displayed for the user.

UPR / CAP	Specifies all upper case or proper name capitalization (First Letter Of Each Word Capitalized) entry.

The SPIN control places a "spinning" list of data items on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  The "spinning" list displays only the current selection with a pair of buttons to the right to allow the user to "spin" through the available selections (similar to a slot machine wheel).

If the SPIN control offers the user regularly spaced numeric choices, the RANGE attribute specifies the valid range of values from which the user may choose.  The STEP attribute then works in conjunction with RANGE to increment/decrement those values by the specified amount.  If the choices are not regular, or are string values, the FROM attribute is used instead of RANGE and STEP.  The FROM attribute provides the SPIN control its list of choices from a memory QUEUE or a string.  Using the FROM attribute, you may provide the user any type of choices in the SPIN control.

The user may select an item from the list or type in the desired value, so this control also acts as an ENTRY control.

Events Generated:

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The user has selected a value from the control.

EVENT:NewSelection

The user has changed the displayed value.

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  SPIN(@S8),AT(0,0,20,20),USE(SpinVar1),FROM(Que)

  SPIN(@N3),AT(20,0,20,20),USE(SpinVar2),RANGE(1,999),KEY(F10Key)

  SPIN(@N3),AT(40,0,20,20),USE(SpinVar3),RANGE(5,995),STEP(5)

  SPIN(@S8),AT(60,0,20,20),USE(SpinVar4),FROM(Que),HLP('Check4Help')

  SPIN(@S8),AT(80,0,20,20),USE(SpinVar5),FROM(Que),MSG('Button 3')

  SPIN(@S8),AT(100,0,20,20),USE(SpinVar6),FROM(Que),FONT('Arial',12)

  SPIN(@S8),AT(120,0,20,20),USE(SpinVar7),FROM(Que),DROP

  SPIN(@S8),AT(140,0,20,20),USE(SpinVar8),FROM(Que),HVSCROLL,VCR

  SPIN(@S8),AT(160,0,20,20),USE(SpinVar9),FROM(Que),IMM

  SPIN(@S8),AT(180,0,20,20),USE(SpinVar10),FROM(Que),CURSOR(CURSOR:Wait)

  SPIN(@S8),AT(200,0,20,20),USE(SpinVar11),FROM(Que),ALRT(F10Key)

  SPIN(@S8),AT(220,0,20,20),USE(SpinVar12),FROM(Que),LEFT

  SPIN(@S8),AT(240,0,20,20),USE(SpinVar13),FROM(Que),RIGHT

  SPIN(@S8),AT(260,0,20,20),USE(SpinVar14),FROM(Que),CENTER

  SPIN(@N8.2),AT(280,0,20,20),USE(SpinVar15),FROM(Que),DECIMAL

END


STRING  (declare a window string control)

STRING(text) ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,FONT( )]
[,	 LEFT	 ] [,FULL] [,SCROLL] [,HIDE] [,TRN]
 RIGHT
 CENTER
 DECIMAL

STRING	Places the text on the WINDOW or TOOLBAR.

text	A string constant containing the text to display, or a display picture token to format the variable specified in the USE attribute.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	A field equate label to reference the control in executable code, or a variable whose contents are displayed in the format of the picture token declared instead of string text.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

FONT	Specifies the font used to display the text.

LEFT	Specifies that the text is left justified within the area specified by the AT attribute.

RIGHT	Specifies that the text is right justified within the area specified by the AT attribute.

CENTER	Specifies that the text is centered within the area specified by the AT attribute.

DECIMAL	Specifies that the text is aligned on the decimal point within the area specified by the AT attribute.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

TRN	Specifies the text or USE variable characters transparently display over the background.

The STRING control places the text on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.

If the text parameter is a picture token instead of a string constant, the contents of the variable named in the USE attribute are formatted to that display picture, at the position and size specified by the AT attribute.  This makes the STRING with a USE variable a "display-only" control for the variable.

There is a difference between ampersand (&) use in STRING and PROMPT controls.  An ampersand in a STRING displays as part of the text, while an ampersand in a PROMPT defines the prompt's "hot" letter.

A STRING with the TRN attribute displays characters transparently, without obliterating the background.  This means only the pixels required to create each character are written to screen.  This allows the STRING to be placed directly on top of an IMAGE without destroying the background picture.

This control cannot receive input focus and does not generate events.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  STRING('String Constant'),AT(10,0,20,20),USE(?S1)

  STRING(@S30),AT(10,20,20,20),USE(StringVar1)

  STRING(@S30),AT(10,20,20,20),USE(StringVar2),CURSOR(CURSOR:Wait)

  STRING(@S30),AT(10,20,20,20),USE(StringVar3),FONT('Arial',12)

END


TEXT  (declare a multi-line data entry control)

TEXT ,AT( ) [,CURSOR( )] [,USE( )] [,DISABLE] [,KEY( )] [,MSG( )]
[,HLP( )] [,SKIP] [,FONT( )] [,REQ] [,FULL] [,SCROLL] [,ALRT( )] [,HIDE]
[,READONLY] [DROPID( )] [UPR]
[,	 INS	 ] [,	 HSCROLL	 ] [,	 LEFT	 ]
 OVR	 	 VSCROLL	 	 RIGHT
 HVSCROLL	 	 CENTER

TEXT	Places a multi-line data entry field on the WINDOW or TOOLBAR.

AT	Specifies the initial size and location of the control.  If omitted, default values are selected by the runtime library.

CURSOR	Specifies a mouse cursor to display when the mouse is positioned over the control.  If omitted, the WINDOW's CURSOR attribute is used, else the Windows default cursor is used.

USE	The label of the variable that receives the value entered into the control by the user.

DISABLE	Specifies the control appears dimmed when the WINDOW or APPLICATION is first opened.

KEY	Specifies an integer constant or keycode equate that immediately gives focus to the control.

MSG	Specifies a string constant containing the text to display in the status bar when the control has focus.

HLP	Specifies a string constant containing the help system identifier for the control.

SKIP	Specifies the control receives input focus to enter text only with the mouse or accelerator key and does not retain focus.

FONT	Specifies the display font for the control.

REQ	Specifies the control may not be left blank or zero.

FULL	Specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

SCROLL	Specifies the control scrolls with the window.

ALRT	Specifies "hot" keys active for the control.

HIDE	Specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.

READONLY	Specifies the control does not allow data entry.

DROPID	Specifies the control may serve as a drop target for drag-and-drop actions.

INS / OVR	Specifies Insert or Overwrite entry mode (valid only on windows with the MASK attribute).

UPR	Specifies all upper case entry.

HSCROLL	Specifies that a horizontal scroll bar is automatically added to the text field when any portion of the data lies horizontally outside the visible area.

VSCROLL	Specifies that a vertical scroll bar is automatically added to the text field when any of the data lies vertically outside the visible area.

HVSCROLL	Specifies that both vertical and horizontal scroll bars are automatically added to the text field when any portion of the data lies outside the visible area.

LEFT	Specifies that the text is left justified within the area specified by the AT attribute.

RIGHT	Specifies that the text is right justified within the area specified by the AT attribute.

CENTER	Specifies that the text is centered within the area specified by the AT attribute.

The TEXT control places a multi-line data entry field on the WINDOW (or TOOLBAR) at the position and size specified by its AT attribute.  The variable specified in the USE attribute receives the data entered when the user has completed data entry and moves on to another control.

Events Generated:

EVENT:Selected

The control has received input focus.

EVENT:Accepted

The user has completed data entry in the control.

EVENT:PreAlert

The user pressed an ALRT attribute hot key.

EVENT:AlertKey

The user pressed an ALRT attribute hot key.

EVENT:Drop

A successful drag-and-drop to the control.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  TEXT,AT(0,0,40,40),USE(E1),ALRT(F10Key),CENTER

  TEXT,AT(20,0,40,40),USE(E2),KEY(F10Key),HLP('Text4Help')

  TEXT,AT(40,0,40,40),USE(E3),SCROLL,OVR,UPR

  TEXT,AT(60,0,40,40),USE(E4),CURSOR(CURSOR:Wait),RIGHT

  TEXT,AT(80,0,40,40),USE(E5),DISABLE,FONT('Arial',12)

  TEXT,AT(100,0,40,40),USE(E6),HVSCROLL,LEFT

  TEXT,AT(120,0,40,40),USE(E7),REQ,INS,CAP,MSG('Text Field 7')

END


Control Field Attributes

ALRT  (set control "hot" keys)

AT  (set control position and size in window)

BOXED  (set window controls group border)

CAP, UPR  (set display case)

CHECK  (set on/off ITEM)

CLASS  (set .VBX custom control class)

COLOR  (set control display color)

COLUMN  (set list box highlight bar)

CURSOR  (set control mouse cursor type)

DEFAULT  (set enter key button)

DISABLE  (set control dimmed at open)

DROP  (set list box behavior)

DRAGID  (set drag-and-drop host signatures)

DROPID  (set drag-and-drop target signatures)

FILL  (set display fill color)

FIRST, LAST  (set MENU or ITEM position)

FONT  (set control font)

FORMAT  (set LIST or COMBO layout)

FROM  (set window listbox data source)

FULL  (set full-screen)

HIDE  (set control hidden at open)

HLP  (set control's on-line help identifier)

HSCROLL, VSCROLL, HVSCROLL  (set control scroll bars)

ICON  (set control icon)

IMM  (set immediate event notification)

INS, OVR  (set typing mode)

KEY  (set control execution keycode)

LEFT, RIGHT, CENTER, DECIMAL  (set display justification)

MARK  (set multiple selection mode)

MSG  (set control status bar message)

NOBAR  (set no highlight bar)

PASSWORD  (set data non-display)

RANGE  (set SPIN range limits)

READONLY  (set display-only)

REQ  (set required entry)

RIGHT  (set MENU position)

ROUND  (set round-cornered window BOX)

SCROLL  (set scrolling control)

SEPARATOR  (set separator line ITEM)

SKIP  (set Tab key skip)

STD  (set standard behavior)

STEP  (set SPIN increment)

TRN  (set transparent window string)

USE  (set control variable or equate label)

VCR  (set VCR control)


ALRT  (set control "hot" keys)

ALRT(keycode)

ALRT	Specifies a "hot" key active while the control has focus.

keycode	A numeric constant keycode or keycode EQUATE.

The ALRT attribute specifies a "hot" key active while the control has focus.  When the user presses an ALRT "hot" key for a control, two field-specific events, EVENT:PreAlert and EVENT:AlertKey, are generated.  EVENT:PreAlert allows you the opportunity to "shortstop" the library's default action on an alerted keypress for the control.

You may have multiple ALRT attributes on one control.  The ALERT statement and the ALRT attribute of a window or control are completely separate.  This means that clearing ALERT keys has no effect on any keys alerted by ALRT attributes.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  ENTRY,AT(6,40),USE(SomeVar),ALRT(F10Key)	!F10 alerted for control

  ENTRY,AT(60,40),USE(SomeVar1),ALRT(F9Key)	!F9 alerted for control

END

  CODE

  OPEN(WinOne)

  ACCEPT

    IF EVENT() = EVENT:AlertKey

      CASE KEYCODE()

      OF F9Key	!Check for the "hot" key

        DO F9Routine

      OF F10Key	!Check for the "hot" key

        DO F10Routine

      END

    END

  END


AT  (set control position and size in window)

AT([x] [,y] [,width] [,height])

AT	Defines the position and size of a control.

x	An integer constant or constant expression that specifies the horizontal position of the top left corner.  If omitted, the runtime library provides a default value (zero).

y	An integer constant or constant expression that specifies the vertical position of the top left corner.  If omitted, the runtime library provides a default value (zero).

width	An integer constant or constant expression that specifies the width.  If omitted, the runtime library provides a default value.

height	An integer constant or constant expression that specifies the height.  If omitted, the runtime library provides a default value.

The AT attribute defines the position and size of a control.  If any parameter is omitted, the runtime library provides a default value.

The values contained in the x, y, width, and height parameters default to dialog units unless the THOUS, MM, or POINTS attribute is also present on the window containing the control.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the window.  This measurement is based on the font specified in the FONT attribute of the window, or the system default font specified by Windows.

Example:

!Measurement in dialog units

WinOne	WINDOW,AT(0,0,160,400)

  ENTRY,AT(8,40,80,8)	!Approx. 2 characters in, 5 down, 20 wide, 1 high

END

!Measurement in Tousandths of an Inch

WinOne	WINDOW,AT(0,0,160,400)

  ENTRY,AT(1000,1000,2000,250)	!1" in & down, 2" wide, 1/4" high

END

!Measurement in Millimeters

WinOne	WINDOW,AT(0,0,160,400)

  ENTRY,AT(100,100,200,50)	!1 cm in and down, 2 cm wide, 50 mm high

END

!Measurement in Points

WinOne	WINDOW,AT(0,0,160,400)

  ENTRY,AT(72,72,144,18)	!1" in & down, 2" wide, 1/4" high

END


BOXED  (set window controls group border)

BOXED

The BOXED attribute specifies a single-track border around a GROUP or OPTION structure.  The text parameter of the GROUP or OPTION control appears in a gap at the top of the border box.  If BOXED is omitted, the text parameter of the GROUP or OPTION control is not displayed on screen.


CAP, UPR  (set display case)

CAP
UPR

The CAP and UPR attributes specify the automatic case of text entered into ENTRY or TEXT controls.  UPR specifies all upper case; CAP specifies "Proper Name Capitalization," where the first letter of each word is capitalized and all other letters are lower case.


CHECK  (set on/off ITEM)

CHECK

The CHECK attribute specifies an ITEM that may be either ON or OFF.  When ON, a check appears to the left of the menu selection and the USE variable receives the value one (1).  When OFF, the check to the left of the menu selection disappears and the USE variable receives the value zero (0).


CLASS  (set .VBX custom control class)

CLASS(file [,name] )

CLASS	The specifies the filename and type of .VBX custom control.

file	A string constant containing the name of the .VBX file (including the .VBX extension) in which the custom control is implemented.

name	A string constant containing the name of the custom control type from the .VBX file.  If omitted, the first control type defined in the .VBX file is used.

The CLASS attribute specifies the filename and type of .VBX custom control.

Example:

!

WinOne	WINDOW,AT(0,0,160,400)

  CUSTOM,AT(0,0,120,320),CLASS('graph.vbx','graph'),'graphstyle'('2')

END


COLOR  (set control display color)

COLOR(rgb)

COLOR	Specifies display color.

rgb	A LONG or ULONG integer constant, or constant EQUATE, containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2), or an EQUATE for a standard Windows color value.

The COLOR attribute specifies the display color of a BOX, LINE, ELLIPSE, or REGION control.  On a BOX, ELLIPSE, or REGION, the color specified is the color used for the border.

EQUATEs for Windows' standard colors are contained in the EQUATES.CLW file.  Windows automatically finds the closest match to the specified rgb color value for the hardware on which the program is run.

Windows standard colors may be reconfigured by the user in the Windows Control Panel.  Any control using a Windows standard color is automatically repainted with the new color when this occurs.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  BOX,AT(20,20,20,20),COLOR(COLOR:ACTIVEBORDER)

!Windows' active border color

  BOX,AT(100,100,20,20),COLOR(00FF0000h)	!Blue

  BOX,AT(140,140,20,20),COLOR(0000FF00h)	!Green

  BOX,AT(180,180,20,20),COLOR(000000FFh)	!Red

END


COLUMN  (set list box highlight bar)

COLUMN

The COLUMN attribute specifies a field-by-field highlight bar on a LIST or COMBO control with multiple display columns.


CURSOR  (set control mouse cursor type)

CURSOR(file)

CURSOR	Specifies a mouse cursor to display for the control.

file	A string constant containing the name of a .CUR file, or an EQUATE naming a Windows-standard mouse cursor.  The .CUR file is linked into the .EXE as a resource.

The CURSOR attribute specifies a mouse cursor to be displayed when the mouse is positioned over the control.

EQUATE statements for the Windows-standard mouse cursors are contained in the EQUATES.CLW file.  The following list is a representative sample of these (see EQUATES.CLW for the complete list):

CURSOR:None	No mouse cursor

CURSOR:Arrow	Normal windows arrow cursor

CURSOR:IBeam	Capital "I" like a steel I-beam

CURSOR:Wait	Hourglass

CURSOR:Cross	Large plus sign

CURSOR:UpArrow	Vertical arrow

CURSOR:Size	Four-headed arrow

CURSOR:Icon	Box within a box

CURSOR:SizeNWSE	Double-headed arrow slanting left

CURSOR:SizeNESW	Double-headed arrow slanting right

CURSOR:SizeWE	Double-headed horizontal arrow

CURSOR:SizeNS	Double-headed vertical arrow

CURSOR:DragWE	Double-headed horizontal arrow

Example:

WinOne	WINDOW,AT(0,0,160,400)

  REGION,AT(20,20,20,20),CUSOR(CURSOR:IBeam)

  REGION,AT(100,100,20,20),CURSOR('Custom.CUR')

END


DEFAULT  (set enter key button)

DEFAULT

The DEFAULT attribute specifies a BUTTON that is automatically pressed when the user presses the ENTER key.  Only one active BUTTON on a window should have this attribute.


DISABLE  (set control dimmed at open)

DISABLE

The DISABLE attribute specifies a control that is disabled when the WINDOW or APPLICATION is opened.  The disabled control may be activated with the ENABLE statement.


DROP  (set list box behavior)

DROP(count)

DROP	Specifies the list appears only when the user presses an arrow cursor key or clicks on the drop icon.

count	An integer constant that specifies the number of elements displayed.

The DROP attribute specifies that the selection list appears only when the user presses an arrow cursor key or clicks on the drop icon to the right of the currently selected value display.  Once it drops into view, the list displays count number of elements.  If the DROP attribute is omitted, the LIST or COMBO control always displays the number of data items specified by the height parameter of the control's AT of the selection list.

The DROP attribute does not work on a WINDOW with the MODAL attribute and should not be used.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?L7),FROM(Que1),DROP(6)

  COMBO(@S8),AT(120,120,20,20),USE(?C7),FROM(Que2),DROP(8)

END


DRAGID  (set drag-and-drop host signatures)

DRAGID( signature [, signature] )

DRAGID	Specifies a LIST or REGION control that can serve as a drag-and-drop host.

signature	A string constant containing an identifier used to indicate valid drop targets.  Any signature that begins with a tilde (~) indicates that the information can also be dragged to an external (Clarion) program.  A single DRAGID may contain up to 16 signatures.

The DRAGID attribute specifies a LIST or REGION control that can serve as a drag-and-drop host.  DRAGID works in conjunction with the DROPID attribute.  The DRAGID signature strings (up to 16) define validation keys to match against the signature parameters of the target control's DROPID.  This provides control over where successful drag-and-drop operations are allowed.

A drag-and-drop operation occurs when the user drags information from a control with the DRAGID attribute to a control with the DROPID attribute.  For a successful drag-and-drop operation, both controls must have at least one identical signature string in their respective DRAGID and DROPID attributes.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?List1),FROM(Que1),DRAGID('FromList1')

!Allows drags, but not drops

  LIST,AT(120,120,20,20),USE(?List2),FROM(Que2),DROPID('FromList1')

!Allows drops from List1, but no drags

END

  CODE

  OPEN(WinOne)

  ACCEPT

    CASE EVENT()

    OF EVENT:Drag	!When a drag event is attempted

      IF DRAGID()	! check for success

        SETDROPID(Que1)	! and setup info to pass

      END

    OF EVENT:Drop	!When drop event is successful

      Que2 = DROPID()	! get dropped info

      ADD(Que2)	! and add it to the queue

    END

  END

See Also:

DROPID


DROPID  (set drag-and-drop target signatures)

DROPID( signature [, signature] )

DROPID	Specifies a control that can serve as a drag-and-drop target.

signature	A string constant containing an identifier used to indicate valid drag hosts.  A single DROPID may contain up to 16 signatures.  Any signature that begins with a tilde (~) indicates that the information can also be dropped from an external (Clarion) program.  A DROPID signature of '~FILE' indicates the target accepts a comma-delimited list of filenames dragged from the Windows File Manager.

The DROPID attribute specifies a control that can serve as a drag-and-drop target.  DROPID works in conjunction with the DRAGID attribute.  The DROPID signature strings (up to 16) define validation keys to match against the signature parameters of the host control's DRAGID.  This provides control over where successful drag-and-drop operations are allowed.

A drag-and-drop operation occurs when the user drags information from a control with the DRAGID attribute to a control with the DROPID attribute.  For a successful drag-and-drop operation, both controls must have at least one identical signature string in their respective DRAGID and DROPID attributes.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?List1),FROM(Que1),DRAGID('FromList1')

!Allows drags, but not drops

  LIST,AT(120,120,20,20),USE(?List2),FROM(Que2),DROPID('FromList1','~FILE')

!Allows drops from List1 or the Window File Manager, but no drags

END

  CODE

  OPEN(WinOne)

  ACCEPT

    CASE EVENT()

    OF EVENT:Drag	!When a drag event is attempted

      IF DRAGID()	! check for success

        SETDROPID(Que1)	! and setup info to pass

      END

    OF EVENT:Drop	!When drop event is successful

      Que2 = DROPID()	! get dropped info

      ADD(Que2)	! and add it to the queue

    END

  END

See Also:

DRAGID


FILL  (set display fill color)

FILL(rgb)

FILL	Specifies display fill color.

rgb	A LONG or ULONG integer constant, or constant EQUATE, containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.

The FILL attribute specifies the display fill color of a BOX, ELLIPSE, or REGION control.  If omitted, the control is not filled with color.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  BOX,AT(20,20,20,20),FILL(COLOR:ACTIVEBORDER)

!Windows' active border color

  BOX,AT(100,100,20,20),FILL(00FF0000h)	!Blue

  BOX,AT(140,140,20,20),FILL(0000FF00h)	!Green

  BOX,AT(180,180,20,20),FILL(000000FFh)	!Red

END


FIRST, LAST  (set MENU or ITEM position)

FIRST
LAST

The FIRST and LAST attributes specify menu selection positioning within the global pulldown menu, when a WINDOW's MENUBAR is merged into the global menu.  The order of priorities is:

Global selections with FIRST attribute

Local selections with FIRST attribute

Global selections without FIRST or LAST attributes

Local selections without FIRST or LAST attributes

Global selections with LAST attribute

Local selections with LAST attribute


FONT  (set control font)

FONT([typeface] [,size] [,color] [,style])

FONT	Specifies the display font for a control.

typeface	A string constant containing the name of the font.  If omitted, the default font is used.

size	An integer constant containing the size (in points) of the font.  If omitted, the system default font size is used.

color	A LONG integer constant containing the red, green, and blue values for the color of the font in the low-order three bytes, or an EQUATE for a standard Windows color value.  If omitted, the default font color is used.

style	An integer constant, constant expression, or EQUATE specifying the strike weight and style of the font.  If omitted, the default font weight is used.

The FONT attribute specifies the display font for the control, overriding any FONT specified on the WINDOW.

The typeface may name any font registered in the Windows system.  The EQUATES.CLW file contains EQUATE values for standard style values.  A style on the range zero (0) to one thousand (1000) specifies the strike weight of the font.  You may add to that values that indicate italic, underline, or strikeout text.  The following EQUATES are in EQUATES.CLW:

  FONT:thin 	EQUATE (100)

  FONT:regular 	EQUATE (400)

  FONT:bold 	EQUATE (700)

  FONT:italic 	EQUATE (01000h)

  FONT:underline 	EQUATE (02000h)

  FONT:strikeout 	EQUATE (04000h)

Example:

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?L7),FROM(Que1),FONT('Arial',14,0FFh)

!14 point Arial typeface, Red, normal

  LIST,AT(120,120,20,20),USE(?C7),FROM(Que2),FONT('Arial',14,0,700)

!14 point Arial typeface, Black, Bold

  LIST,AT(120,240,20,20),USE(?C7),FROM(Que2),FONT('Arial',14,0,700+01000h)

!14 point Arial typeface, Black, Bold Italic

END


FORMAT  (set LIST or COMBO layout)

FORMAT(format string)

FORMAT	Specifies the display format of the data in the LIST or COMBO control.

format

 string	A string constant specifying the column or multi-column display format.

The FORMAT attribute specifies the display format of the data in the LIST or COMBO control.  The format string contains the information for single or multi-column formatting of the data.

The format string contains "field-specifiers" which map to the fields of the QUEUE, and/or "region-specifiers" that group together one or more fields to be displayed as a unit.  Only the fields in the QUEUE for which there are "field-specifiers" are included in the display.  This means that, if there are two fields specified in the format string and three fields in the QUEUE, only the two specified in the format string are displayed in the LIST or COMBO control.

The following describes the components allowed in a format string:

"Field-specifier" format:  width  justification  [(indent)]  [modifiers]

width	An integer defining the width of the field in dialog units unless overridden by the THOUS, MM, or POINTS attribute.  Required.

justification	A single capital letter (L , R , C , or D) that specifies Left, Right, Center, or Decimal justification.  One is required.

indent	An optional integer, enclosed in parentheses, that specifies an indent from the justification.  This is measured in dialog units and may be negative.  With left (L) justification, indent defines a left margin; with  right (R) or decimal (D), it defines a right margin; and with center (C), it defines an indent from the center of the field.

modifiers	Optional special characters (listed below) to modify the display format of the field.  Multiple modifiers may be used on one field.

     _ 	An underscore underlines the field.

     | 	A vertical bar places a vertical line to the right of the field.

     / 	A slash causes the next field to appear on a new line (can only be used within a "region-specifier").

     ~header~ [justification] [(indent)]

A header string enclosed in tildes, followed by optional justification and/or indent, displays the header at the top of the list.   The header uses the same justification and indent as the field, if not specifically overidden.

     @picture@[E]

A picture token formats the field for display.  The trailing @ is required to define the end of the picture token, so that picture tokens like @N12~Kr~ may be used in the format string without creating ambiguity.  If the trailing @ is followed by an 'E', the field can be directly edited in the list box, and the appropriate QUEUE entry is automatically updated with the edited value.

     ?	A question mark defines the locator field for a COMBO list box with a selector field.  For a drop-down multi-column list box, this is the value displayed in the current-selection box.

     #number#

A number enclosed in pound signs (#) indicates the QUEUE field to display.  Following fields in the format string without an explicit #number# are taken from the fields following the #number# field.  For example, #2# on the first field in the format string indicates starting with the second field in the QUEUE, skipping the first.  If the number of fields specified in the format string are >= the number of fields in the QUEUE, the last fields "wrap around" to use the first fields in the QUEUE.

"Region-specifier" format:  [ multiple field-specifiers ] [modifiers]

A "region-specifier" differs from a "field-specifier" in that it relates to groups of fields.  The required square brackets ( [ ] ) that enclose the fields cause them to be treated as a single display unit.

modifiers	The "region-specifier" modifiers act on the entire group of fields.

     _ 	An underscore underlines the group of fields.

     | 	A vertical bar places a vertical line to the right of the group of fields.

     ~header~ [justification] [(indent)]

A header string enclosed in tildes, followed by optional justification and/or indent, displays the header at the top of the list.   The header is centered unless a justification is defined.

     F 	An F creates a fixed column in the list that stays on screen when the user horizontally pages through the fields (by the HSCROLL attribute).  Fixed regions must be at the start of the list.

     M 	An M allows the group of fields to be dynamically re-sized at runtime.  This allows the right vertical bar to be dragged.

     S(integer)

An S followed by an integer in parentheses adds a scroll bar to the group.  The integer defines the total number of dialog units to scroll for the group of fields.  This allows large fields to be displayed in a small column width.

Example:

!This example code demonstrates a number of format strings that the user

! can select at runtime to format the listbox display

StrLists        PROCEDURE

ThisFormat      STRING(200),AUTO  !Current selected display format string

TQ              QUEUE,AUTO	!Display formats list box FROM queue

TT                STRING(200)

                END

TD              QUEUE,AUTO	!Data list box FROM queue

FName             STRING(20)

LName             STRING(20)

Init              STRING(4)

Wage              REAL

Address           STRING(40)

State             STRING(10)

                END

Win	WINDOW('List Boxes'),AT(0,0,366,181),SYSTEM,DOUBLE,MDI

  LIST,AT(13,6,346,12),USE(ThisFormat),FROM(TQ),FORMAT('400L'),DROP(6)

  LIST,AT(0,34,366,146),FORMAT('80L80L16L60L160L40L'),FROM(TD),USE(?Show)|

,HVSCROLL

END

  CODE

  TT = '80L80L16L60L160L40L'	!Build a queue of display formats

!Single-row data without headers

  ThisFormat = TT

  ADD(TQ)

  TT = '80C~First Name~80C~Last Name~16L~Intls~60R~Wage~160C~Address~40C~State~|'

!Single-row data with headers

  ADD(TQ)

  TT = '80C~First Name~80C~Last Name~16L~Intls~60D(10)~Wage~160C~Address~40C~State~|'

!With headers and aligned decimal

  ADD(TQ)

  TT = '[80C80C16L]~Name~M[60D(10)@N$12.2@]~Wage~M[160C40C]~Address~|'

!Added vertical size bars between columns

  ADD(TQ)

  TT = '[80L~ForeName~/80L~Surname~16R~Init~]M[60D(10)]~Wage~M[160C40C]~Address~|'

!Vertical size bars and multi-line name column

  ADD(TQ)

  TT = '[80L~ForeName~/80L~Surname~16R~Init~]S(60)F|[60D(10)]~Wage~M[160C40C]~Address~|'

!Fixed Multi-line name column with Horiz scroll bar

  ADD(TQ)

  OPEN(Win)

  ACCEPT

    CASE ACCEPTED()

    OF ?ThisFormat	!When user selects a format

      ?Show{PROP:format} = ThisFormat	! change FORMAT attribute to new format

    END

  END


FROM  (set window listbox data source)

FROM(source)

FROM	Specifies the source of the data elements displayed in a LIST, COMBO, or SPIN.

source	The label of a QUEUE, a field within a QUEUE, or a string constant containing the data items to display in the list.

The FROM attribute specifies the source of the data elements displayed in a LIST, COMBO, or SPIN.

For a SPIN control, the source would usually be a QUEUE field or string.  If the source is a QUEUE with multiple fields, only the first field is displayed in the SPIN.

For LIST and COMBO controls, the data elements are formatted for display according to the information in the FORMAT attribute.  If the label of a QUEUE is specified as the source, all fields in the QUEUE are displayed.  If the label of one field in a QUEUE is specified as the source, only that field is displayed.

If a string constant is specified as the source, the individual data elements to display in the LIST must be delimited by a vertical bar (|) character.  To include a vertical bar as part of one data element, place two adjacent vertical bars in the string (||), and only one will be displayed.  To indicate that an element is empty, place at least one blank space between the two vertical bars delimiting the elements (|  |).

Example:

Que1	QUEUE,PRE(Q1)

F1	  LONG

F2	  STRING(8)

END

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?L1),FROM(Que1),FORMAT('5C~List~15L~Box~'),COLUMN

  COMBO(@S8),AT(120,120,20,20),USE(?C1),FROM(Q1:F2)

  SPIN(@N8.2),AT(280,0,20,20),USE(SpinVar1),FROM(Q1:F1)

  SPIN(@S4),AT(280,0,20,20),USE(SpinVar2),FROM('Mr.|Mrs.|Ms.|Dr.')

END


FULL  (set full-screen)

FULL

The FULL attribute specifies the control expands to occupy the entire size of the WINDOW for any missing AT attribute width or height parameter.

FULL may not be specified for TOOLBAR controls.


HIDE  (set control hidden at open)

HIDE

The HIDE attribute specifies the control does not appear when the WINDOW or APPLICATION is first opened.  UNHIDE must be used to display it.


HLP  (set control's on-line help identifier)

HLP(helpID)

HLP	Specifies the helpID for the control.

helpID	A string constant specifying the key used to access the Help system.  This may be either a Help keyword or a "context string."

The HLP attribute specifies the helpID for the control.  Help, if available, is automatically displayed by Windows whenever the user presses F1.  If the user presses F1 to request help when the control has input focus, the library uses the control's helpID to search the help file until an object with that helpID is found.  The helpID may contain a Help keyword or a "context string."  A Help keyword is a keyword or phrase that is displayed in the Help Search dialog.  When the user presses F1, if only one topic in the help file specifies this keyword, the help file is opened at that topic; if more than one topic specifies the keyword, the search dialog is opened for the user.

A "context string" is identified by a leading tilde (~) in the helpID, followed by a unique identifier (no spaces allowed) associated with exactly one help topic.  If the tilde is missing, the helpID is assumed to be a help keyword.  When the user presses F1, the help file is opened at the specific topic associated with that "context string."

Example:

Win1	WINDOW

!A control with a help context string:

  ENTRY(@s30),USE(SomeVariable),HLP('~Entry1Help')

!A control with a help keyword:

  ENTRY(@s30),USE(SomeVariable),HLP('Control Two Help')

END


HSCROLL, VSCROLL, HVSCROLL  (set control scroll bars)

HSCROLL
VSCROLL
HVSCROLL

The HSCROLL, VSCROLL, and HVSCROLL attributes place scroll bars on a COMBO, LIST, IMAGE, or TEXT control.  HSCROLL adds a horizontal scroll bar to the bottom; VSCROLL adds a vertical scroll bar on the right side, and HVSCROLL adds both.

The vertical scroll bar allows a mouse to scroll the control's display up or down.  The horizontal scroll bar allows a mouse to scroll the control's display left or right.  The scroll bars appear whenever any scrollable portion of the control lies outside the visible area on screen.


ICON  (set control icon)

ICON( [file] )

ICON	Specifies an icon to display as the control.

file	A string constant or EQUATE containing the name of an .ICO file or Windows standard icon to display.  The .ICO file is linked intot he .EXE as a resource.

The ICON attribute specifies an icon to display as the control.  The icon is displayed on the button face of the control.  The ICON attribute may be specified on a BUTTON, RADIO, or CHECK control.  For RADIO and CHECK controls, the ICON attribute creates "latched" pushbuttons, where the control button appears "down" when on and "up" when off.

EQUATE statements for the Windows-standard icons are contained in the EQUATES.CLW file.  The following list is a representative sample of these (see EQUATES.CLW for the complete list):

ICON:None	No icon

ICON:Application

ICON:Question	?

ICON:Exclamation	!

ICON:Asterisk	*

ICON:VCRtop	>>|

ICON:VCRrewind	<<

ICON:VCRback	<

ICON:VCRplay	>

ICON:VCRfastforward	>>

ICON:VCRbottom	|<<

ICON:VCRlocate	?

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  OPTION('Option'),USE(OptVar)

    RADIO('Radio 1'),AT(120,0,20,20),USE(?R1),ICON('Radio1.ICO')

    RADIO('Radio 2'),AT(140,0,20,20),USE(?R2),ICON('Radio2.ICO')

  END

  CHECK('&A'),AT(0,120,20,20),USE(?C7),ICON(ICON:Asterisk)

  BUTTON('&1'),AT(120,0,20,20),USE(?B7),ICON(ICON:Question)

END


IMM  (set immediate event notification)

IMM

The IMM attribute specifies immediate generation of an event.

On a REGION control, the IMM attribute generates an event whenever the mouse enters, moves within, or leaves the area specified by the REGION's AT attribute.  The exact position of the mouse can be deteremined by the MOUSEX and MOUSEY functions.

On a BUTTON control, the IMM attribute indicates the BUTTON generates an event when the left mouse button is pressed down on the control, instead of on its release.  The event is continuously generated as along as the user keeps the mouse button pressed.

The IMM attribute specifies immediate event generation each time the user presses any keystroke on a LIST or COMBO control, usually requiring the QUEUE to be re-filled.  When the user presses a printable character, EVENT:AlertKey is generated.  It does the same thing on an ENTRY or SPIN control.


INS, OVR  (set typing mode)

INS
OVR

The INS and OVR attributes specify the typing mode for an ENTRY or TEXT control.  INS specifies insert mode while OVR specifies overwrite mode.  These modes are only active on windows with the MASK attribute.


KEY  (set control execution keycode)

KEY(keycode)

KEY	Specifies a "hot" key for the control

keycode	A Clarion Keycode or keycode equate label.

The KEY attribute specifies a "hot" key to immediately give focus to the control or execute the control's associated action.

The following controls receive focus:

COMBO

CUSTOM

ENTRY

GROUP

LIST

OPTION

PROMPT

SPIN

TEXT

The following controls both receive focus and immediately execute:

BUTTON

CHECK

CUSTOM

RADIO

Example:

WinOne	WINDOW,AT(0,0,160,400)

  COMBO(@S8),AT(120,120,20,20),USE(?C1),FROM(Q1:F2),KEY(F1Key)

  LIST,AT(120,0,20,20),USE(?L1),FROM(Que1),KEY(F2Key)

  SPIN(@N8.2),AT(280,0,20,20),USE(SpinVar1),FROM(Q),KEY(F3Key)

  TEXT,AT(20,0,40,40),USE(E2),KEY(F4Key)

  PROMPT('Enter &Data in E2:'),AT(10,200,20,20),USE(?P2),KEY(F5Key)

  ENTRY(@S8),AT(100,200,20,20),USE(E2),KEY(F6Key)

  BUTTON('&1'),AT(120,0,20,20),USE(?B7),KEY(F7Key)

  CHECK('&A'),AT(0,120,20,20),USE(?C7),KEY(F8Key)

  OPTION('Option'),USE(OptVar),KEY(F9Key)

    RADIO('Radio 1'),AT(120,0,20,20),USE(?R1),KEY(F10Key)

    RADIO('Radio 2'),AT(140,0,20,20),USE(?R2),KEY(F11Key)

  END

END


LEFT, RIGHT, CENTER, DECIMAL  (set display justification)

LEFT( [indent] )
RIGHT( [indent] )
CENTER( [indent] )
DECIMAL( [indent] )

indent	An integer constant specifying the amount of offset from the justification point.  This is in dialog units unless overridden by the THOUS, MM, or POINTS attribute.

The LEFT, RIGHT, CENTER, and DECIMAL attributes specify the justification of data displayed.  LEFT specifies left justification, RIGHT specifies right justification, CENTER specifies centered text, and DECIMAL specifies numeric data aligned on the decimal point.

The indent parameter on the CENTER attribute specifies an offset from the center.  On the DECIMAL attribute, indent specifies the offset of the decimal point from the right.

The CHECK and RADIO controls allow LEFT or RIGHT only (without an indent parameter).  The TEXT control allows only LEFT(indent), RIGHT(indent), or CENTER(indent).

The following controls allow LEFT(indent), RIGHT(indent), CENTER(indent), or DECIMAL(indent):

COMBO

ENTRY

LIST

SPIN

STRING

Example:

WinOne	WINDOW,AT(0,0,160,400)

  COMBO(@S8),AT(120,120,20,20),USE(?C1),FROM(Q1:F2),RIGHT(4)

  LIST,AT(120,0,20,20),USE(?L1),FROM(Que1),CENTER

  SPIN(@N8.2),AT(280,0,20,20),USE(SpinVar1),FROM(Q),DECIMAL(8)

  TEXT,AT(20,0,40,40),USE(E2),LEFT(8)

  ENTRY(@S8),AT(100,200,20,20),USE(E2),LEFT(4)

  CHECK('&A'),AT(0,120,20,20),USE(?C7),LEFT

  OPTION('Option'),USE(OptVar)

    RADIO('Radio 1'),AT(120,0,20,20),USE(?R1),LEFT

    RADIO('Radio 2'),AT(140,0,20,20),USE(?R2),RIGHT

  END

END


MARK  (set multiple selection mode)

MARK(flag)

MARK	Enables multiple items selection.

flag	The label of a QUEUE field or array.

The MARK attribute enables multiple items selection from a LIST or COMBO control.  When an item in the LIST is selected, the appropriate flag element is set to true (1).  Each marked entry is highlighted in the LIST or COMBO.  Changing the value of an element of the flag also changes the screen display for the related LIST or COMBO entry.

If the MARK attribute is specified on the LIST or COMBO, the IMM attribute may not be.

Example:

Que1	QUEUE,PRE(Q1)

MarkFlag	  BYTE

F1	  LONG

F2	  STRING(8)

END

MarkArray	BYTE,DIM(20)

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?L1),FROM(Q1:F1),MARK(Q1:MarkFlag)

  COMBO(@S8),AT(120,120,20,20),USE(?C1),FROM(Q1:F2),MARK(MarkArray)

END


MSG  (set control status bar message)

MSG(text)

MSG	Specifies text to display in the status bar.

text	A string constant containing the message to display in the status bar.

The MSG attribute specifies the text to display in the first zone of the status bar when the control has focus.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  COMBO(@S8),AT(120,120,20,20),USE(?C1),FROM(Q1:F2),MSG('Enter or Select')

  LIST,AT(120,0,20,20),USE(?L1),FROM(Que1),MSG('Select One')

  SPIN(@N8.2),AT(280,0,20,20),USE(SpinVar1),FROM(Q),MSG('Choose One')

  TEXT,AT(20,0,40,40),USE(E2),MSG('Enter Text')

  ENTRY(@S8),AT(100,200,20,20),USE(E2),MSG('Enter Data')

  CHECK('&A'),AT(0,120,20,20),USE(?C7),MSG('On or Off')

  OPTION('Option 1'),USE(OptVar),MSG('Pick One or Two')

    RADIO('Radio 1'),AT(120,0,20,20),USE(?R1)

    RADIO('Radio 2'),AT(140,0,20,20),USE(?R2)

  END

  OPTION('Option'),USE(OptVar)

    RADIO('Radio 1'),AT(120,40,20,20),USE(?R1),MSG('Pick One')

    RADIO('Radio 2'),AT(140,40,20,20),USE(?R2),MSG('Pick Two')

  END

END


NOBAR  (set no highlight bar)

NOBAR

The NOBAR attribute specifies the currently selected element in the LIST is only highlighted when the LIST control has focus.


PASSWORD  (set data non-display)

PASSWORD

The PASSWORD attribute specifies non-display of the data entered in the ENTRY control.  When the user types in data, asterisks are displayed on screen for each character entered.


RANGE  (set SPIN range limits)

RANGE(lower,upper)

RANGE	Specifies the valid range of data values the user may select in a SPIN control.

lower	A numeric constant that specifies the lower inclusive limit of valid data.

upper	A numeric constant that specifies the upper inclusive limit of valid data.

The RANGE attribute specifies the valid range of data values the user may select in a SPIN control.  This attribute works in conjunction with the STEP attribute to provide the user with choices in the SPIN control.  When RANGE and STEP are used, the SPIN control's FROM attribute is not.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  SPIN(@N4.2),AT(280,0,20,20),USE(SpinVar1),RANGE(.05,9.95),STEP(.05)

  SPIN(@n3),AT(280,0,20,20),USE(SpinVar2),RANGE(5,995),STEP(5)

END


READONLY  (set display-only)

READONLY

The READONLY attribute specifies a display-only COMBO, ENTRY, SPIN or TEXT control.  The control may receive input focus with the mouse, but may noy enter data.  If the user attempts to change the displayed value, a beep warns the user that data entry is not allowed.


REQ  (set required entry)

REQ

The REQ attribute specifies an ENTRY or TEXT control that may not be left blank or zero.  The REQ attribute on an ENTRY or TEXT control is not checked until a BUTTON with the REQ attribute is pressed, or the INCOMPLETE() function is called.

When a BUTTON with the REQ attribute is pressed, or the INCOMPLETE() function is called, all ENTRY and TEXT controls with the REQ attribute are checked to ensure they contain data.  The first control encountered in this check that does not contain data inmediately receives input focus.


RIGHT  (set MENU position)

RIGHT

The RIGHT attribute specifies the MENU is placed at the right end of the action bar.


ROUND  (set round-cornered window BOX)

ROUND

The ROUND attribute specifies a BOX control with rounded corners.


SCROLL  (set scrolling control)

SCROLL

The SCROLL attribute specifies a control that moves with the window when the WINDOW scrolls.  This allows "virtual" windows larger than the physical video display.

The presence of the SCROLL attribute means that the control stays fixed at a position in the window relative to the top left corner of the virtual window, whether that position is currently in view or not.  This means that the control appears to move as the window scrolls.

If the SCROLL attribute is omitted, the control stays fixed at a position in the window relative to the top left corner of the currently visible portion of the window.  This means that the control appears to stay in the same position on screen while the rest of the window scrolls.  This is useful for controls which should stay visible to the user at all times (such as Ok or Cancel buttons).

Mixing controls with and without the SCROLL attribute on the same WINDOW can result in multiple controls appearing to occupy the same screen position.  This occurs because the controls with SCROLL move and the controls without SCROLL do not.  This condition is temporary and scrolling the window will correct the situation.  The situation can be avoided entirely by careful placement of controls in the window.  For example, you can place all controls without SCROLL at the bottom of the window then place all controls with SCROLL above them extending to the right and left.  This would create a window that only scrolls horizontally.


SEPARATOR  (set separator line ITEM)

SEPARATOR

The SEPARATOR attribute specifies an ITEM in a MENU that displays a horizontal line to group ITEMs within the MENU.  No other attributes may be specified for the ITEM.


SKIP  (set Tab key skip)

SKIP

The SKIP attribute specifies the control may only be accessed with the mouse or an accelerator key.  Controls that allow data entry receive input focus only during data entry and the control does not retain focus.  Controls that do not allow data entry do not receive or retain input focus.  The effect of this is to create the same behavior as a control in a toolbar.  When the mouse cursor is over a control with the SKIP attribute, the control's MSG attribute is displayed in the status bar.


STD  (set standard behavior)

STD(behavior)

STD	Specifies standard Windows behavior.

behavior	An integer constant or EQUATE specifying the identifier of a standard windows behavior.

The STD attribute specifies the control activates some standard Windows action.  This action is automatically executed by the runtime library and does not generate an event.

EQUATE statements for the standard Windows actions are contained in the EQUATES.CLW file.  The following list is a representative sample of these (see EQUATES.CLW for the complete list):

STD:WindowList	List of open MDI windows

STD:TileWindow	Tile Windows

STD:CascadeWindow	Cascade Windows

STD:ArrangeIcons	Arrange Icons

STD:HelpIndex	Help Contents

STD:HelpSearch	Help Search dialog

Example:

MDIChild	WINDOW('Child One'),MDI,SYSTEM,MAX

  MENUBAR

    MENU('Edit'),USE(?EditMenu)

      ITEM('Undo'),USE(?UndoText),KEY(CtrlZ),STD(STD:Undo)

      ITEM('Cu&t'),USE(?CutText),KEY(CtrlX),STD(STD:Cut)

      ITEM('Copy'),USE(?CopyText),KEY(CtrlC),STD(STD:Copy)

      ITEM('Paste'),USE(?PasteText),KEY(CtrlV),STD(STD:Paste)

    END

  END

  TOOLBAR

    BUTTON('Cut'),USE(?OpenButton),ICON(ICON:Cut),STD(STD:Cut)

    BUTTON('Copy'),USE(?OpenButton),ICON(ICON:Copy),STD(STD:Copy)

    BUTTON('Paste'),USE(?OpenButton),ICON(ICON:Paste),STD(STD:Paste)

  END

END


STEP  (set SPIN increment)

STEP(count)

STEP	Specifies a SPIN control RANGE attribute's increment/decrement value.

count	A numeric constant specifying the amount to increment or decrement.

The STEP attribute specifies the amount by which a SPIN control's value is incremented or decremented within its valid RANGE.  The default STEP value is 1.0.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  SPIN(@N4.2),AT(280,0,20,20),USE(SpinVar1),RANGE(.05,9.95),STEP(.05)

  SPIN(@n3),AT(280,0,20,20),USE(SpinVar2),RANGE(5,995),STEP(5)

END


TRN  (set transparent window string)

TRN

The TRN attribute on a STRING control specifies the characters display transparently, without obliterating the background over which the STRING is placed.  Only the pixels required to create each character are written to the screen.  This allows the STRING to be placed directly on top of an IMAGE without destroying the background picture.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  IMAGE('PIC.BMP'),USE(?I1),FULL	!Full window image

  STRING('String Constant'),AT(10,0,20,20),USE(?S1),TRN

!Transparent string on image

END


USE  (set control variable or equate label)

USE(	 label	 [,number] )
 variable

USE	Specifies a variable or field equate label for the control.

label	A field equate label to reference the control in executable code.

variable	The label of a variable to receive the value entered into the control.

number	An integer constant that specifies the number the compiler equates to the field equate label for the control.

The USE attribute specifies a variable or field equate label for the control.  USE with a label parameter simply provides a mechanism for executable source code statements to reference the control.  Some controls only allow a field equate label as the USE parameter, not a variable.  These controls are:  PROMPT, IMAGE, LINE, BOX, ELLIPSE, GROUP, RADIO, REGION, MENU, and BUTTON.  USE with a variable parameter supplies the control with a variable to update by operator entry.  This is applicable to an ITEM with the CHECK attribute, or an ENTRY, OPTION, SPIN, TEXT, LIST, COMBO, CHECK, or CUSTOM.

All controls in an APPLICATION or WINDOW are automatically assigned numbers by the compiler.  For an APPLICATION's MENUBAR controls, these numbers start at negative one (-1) and decrement by one (1) for each MENU and ITEM in the MENUBAR.  On a WINDOW, these numbers start at one (1) and increment by one (1) for each control in the WINDOW structure.

The USE attribute's number parameter allows you to specify the actual field number the compiler assigns to the control.  This number also is used as the new starting point for subsequent field numbering for fields without a number parameter in their USE attribute.  Subsequent controls without a number parameter in their USE attribute are incremented (or decremented) relative to the last number assigned.

Two or more controls with exactly the same USE variable in one WINDOW or APPLICATION structure would create the same Field Equate Label for all, therefore, when the compiler encounters this condition, all Field Equate Labels for that USE variable are discarded.  This makes it impossible to reference any of these controls in executable code, preventing confusion about which control you really want to reference.  It also allows you to deliberately create this condition to display the contents of the variable in multiple controls with different display pictures.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  COMBO(@S8),AT(120,120,20,20),USE(?C1),FROM(Q1:F2)

  ENTRY(@S8),AT(100,200,20,20),USE(E2)

END


VCR  (set VCR control)

VCR( [field] )

VCR	Places Video Cassette Recorder (VCR) style buttons on a LIST or COMBO control.

field	A field equate label that specifies the ENTRY control to use as a locator for a LIST (not valid on a COMBO).

The VCR attribute places Video Cassette Recorder (VCR) style buttons on a LIST or COMBO control.  The VCR style buttons affect the scrolling characteristics of the data displayed in the LIST or COMBO.

There are six buttons displayed as the VCR:

|<	Top of list

<<	Page Up

 <	Entry Up

 >	Entry Down

>>	Page Down

>|	Bottom of list

On a LIST control's VCR(field), there also appears a button with a question mark (?) in the middle of the other buttons.  This is the locator button that gives focus to the control specified by the field parameter.  When the user enters data and then presses TAB on the locator field, the LIST scrolls to its closest matching entry.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  LIST,AT(140,0,20,20),USE(?L8),FROM(Que),HVSCROLL,VCR

  ENTRY(@S8),AT(100,200,20,20),USE(E2)

  LIST,AT(140,100,20,20),USE(?L8),FROM(Que),HVSCROLL,VCR(?E2)

END


Window Commands

Event Processing

Event-driven programming

ACCEPT  (the event processor)

ALERT  (set event generation key)

EVENT  (return event number)

POST  (post user-defined event)

YIELD  (allow event processing)

Multi-Threaded Applications

Multi-Threading and MDI

Multi-Threading vs. Multi-Tasking

START  (return new execution thread)

THREAD  (return current execution thread)

Window Procedures

CHANGE  (change control field value)

CLOSE  (close window)

CREATE  (create new control)

DISABLE  (dim a control)

DISPLAY  (write USE variables to screen)

ENABLE  (re-activate dimmed control)

ERASE  (clear screen control and USE variables)

GETFONT  (get font information)

GETPOSITION  (get control position)

HELP  (help window access)

HIDE  (blank a control)

OPEN  (open window for processing)

SELECT  (select next control to process)

SET3DLOOK  (set 3D window look)

SETCURSOR  (set temporary mouse cursor)

SETFONT  (specify font)

SETPOSITION  (specify new control position)

SETTARGET  (set current window or report)

UNHIDE  (show hidden control)

UPDATE  (write from screen to USE variables)

Window Functions

ACCEPTED  (return control just completed)

CHOICE  (return relative item position)

CONTENTS  (return contents of USE variable)

FIELD  (return control with focus)

FIRSTFIELD  (return first window control)

FOCUS  (return control with focus)

INCOMPLETE  (return empty REQ control)

LASTFIELD  (return last window control)

MESSAGE  (return message box response)

MOUSEX  (return mouse horizontal position)

MOUSEY  (return mouse vertical position)

SELECTED  (return control that has received focus)

Keyboard Procedures

ASK  (get one keystroke)

PRESS  (put characters in the buffer)

PRESSKEY  (put a keystroke in the buffer)

SETKEYCODE  (specify keycode)

Keyboard Functions

KEYBOARD  (return keystroke waiting)

KEYCHAR  (return ASCII code)

KEYCODE  (return last keycode)

Windows Standard Dialog Functions

COLORDIALOG  (return chosen color)

FILEDIALOG  (return chosen file)

FONTDIALOG  (return chosen font)

PRINTERDIALOG  (return chosen printer)

Drag and Drop Processing

CLIPBOARD  (return windows clipboard contents)

DRAGID  (return matching drag-and-drop signature)

DROPID  (return drag-and-drop string)

SETCLIPBOARD  (set windows clipboard contents)

SETDROPID  (set DROPID return string)

Maintaining INI Files

GETINI  (return INI file entry)

PUTINI  (set INI file entry)


Event Processing

Event-driven programming

ACCEPT  (the event processor)

ALERT  (set event generation key)

EVENT  (return event number)

POST  (post user-defined event)

YIELD  (allow event processing)


Event-driven programming

Windows programs are generally event-driven.  This means the user causes an event by clicking the mouse on a screen control or pressing a key.  Every user action in the program results in Windows sending a message to the program which owns the window telling it what the user has done.  Once Windows has sent the message signaling an event to the program, the program has the opportunity to handle the event in the appropriate manner.  This basically means the Windows programming paradigm is exactly opposite from the DOS programming paradigm the operating system (Windows) tells the program what to do, instead of the program telling the operating system what to do.

Writing a Windows program in a programming language other than Clarion becomes very complex, because the program must be coded to explicitly handle every message from Windows.  Common tasks, such as re-drawing graphics that have been overwritten by a window that was open and is now closed, must be explicitly coded in the program.

These common tasks could be handled automatically by writing generic procedures to accomplish the task and call them every time the need arises.  Of course, in other programming languages, you would have to write these procedures yourself.  In Clarion for Windows, they are already written and included as part of our runtime library.  The Clarion language, therefore, has persistent graphics commands that do not require an explicit re-draw each time they are overwritten (unlike other languages).

In Clarion Windows programs, most of the messages from Windows are automatically handled internally by the ACCEPT event processor.  These are the common events handled by the runtime library.  Only those events that actually require program action are passed on by ACCEPT to your Clarion code.  The net effect of this is to make your programming job easier by removing the low-level "drudgery" code from your program, allowing you to concentrate on the high-level aspects of programming, instead.

There are two types of events passed on to the program by ACCEPT: Fieldspecific and Fieldindependent events.

     _	A Fieldspecific event occurs when the user presses a key that may require the program to perform a specific action related to that control.

     _	A Fieldindependent event does not relate to any one control but requires some program action (for example, to close a window, quit the program, or change execution threads).  Most of these events cause the system to become modal, since they require a response before the program may continue.


ACCEPT  (the event processor)

ACCEPT
  statements
END

ACCEPT	The event handler.

statements	Executable code statements.

The ACCEPT loop is the event handler that processes events generated by Windows for the APPLICATION or WINDOW structures.  An ACCEPT loop and a window are bound together, in that, when the window is opened, the next ACCEPT loop encountered will process all events for that window.

ACCEPT operates in the same manner as a LOOP--the BREAK and CYCLE statements can be used within it.  The ACCEPT loop cycles for every event that requires program action.  ACCEPT waits until the Clarion runtime library sends it an event that the program should process, then cycles through to execute its statements.  During the time ACCEPT is waiting, the Clarion runtime library has control, automatically handling common events from Windows that do not need specific program action (such as screen re-draws).

The current contents of all STRING control USE variables (in the top window of each thread) automatically displayed on screen each time the ACCEPT loop cycles to the top.  This eliminates the need to explicitly issue a DISPLAY statement to update the video display for display-only data. USE variable contents for any other control automatically display on screen for any event generated for that control, unless PROP:Auto is turned on to automatically display all USE variables each time through the ACCEPT loop.

Within the ACCEPT loop, the program determines what happened by using the following functions:

  EVENT()	returns a value indicating what happened.  Symbolic constants for events are in the EQUATES.CLW file.

  FIELD()	returns the field number for the control to which the event refers, if the event is a field-specific event.

  ACCEPTED()	returns the field number for the control to which the event refers, if the event is the EVENT:Accepted field-specific event.

  SELECTED()	returns the field number for the control to which the event refers, if the event is the EVENT:Selected field-specific event.

  FOCUS()	returns the field number of the control on the current window that has input focus, no matter what event occurred.

  MOUSEX()	returns the x-coordinate of the mouse cursor at the time of the event.

  MOUSEY()	returns the y-coordinate of the mouse cursor at the time of the event.

Two events cause an implicit BREAK from the ACCEPT loop.  These are the events that signal the close of a window or close of a program.  The program's code need not check for these events as they are handled automatically.  However, the program code may check for them and execute some specific action, such as displaying a "You sure?" window or handling some housekeeping details (a CYCLE statement at that point would return to the top of the ACCEPT loop without exit).

Example:

  CODE

  OPEN(Window)

  ACCEPT

    CASE EVENT()

    OF EVENT:Selected

      CASE SELECTED()

      OF ?field1

          ! pre-edit code for field1

      OF ?field2

          ! pre-edit code for field2

      END

    OF EVENT:Accepted

      CASE ACCEPTED()

      OF ?field1

          ! completion code for field1

      OF ?field2

          ! completion code for field2

      END

    OF EVENT:NewSelection

      CASE FIELD()

      OF ?ListField1

          ! new selection code

      OF ?ListField2

          ! new selection code

      END

    OF EVENT:Suspend

      CASE FOCUS()

      OF ?Field1

          !Save some stuff

      OF ?Field2

          !Save some stuff

      END

    OF EVENT:Resume

      CASE FOCUS()

      OF ?Field1

          !Restore the stuff

      OF ?Field2

          !Restore the stuff

      END

    END

  END

See Also:

EVENT

FIELD

FOCUS

ACCEPTED

SELECTED


ALERT  (set event generation key)

ALERT([first-keycode] [,last-keycode])

ALERT 	Specifies keys that generate an event.

first-keycode	A numeric keycode or keycode equate label.  This may be the lower limit in a range of keycodes.

last-keycode	The upper limit keycode, or keycode equate label, in a range of keycodes.

ALERT specifies a key, or an inclusive range of keys, as event generation keys.  Two field-independent events, EVENT:PreAlert and EVENT:AlertKey, are generated generated when the user presses the ALERTed key.  EVENT:PreAlert allows you the opportunity to "shortstop" the library's default action on an alerted keypress.

The ALERT statement with no parameters clears all ALERT keys.  Any key with a keycode may be used as the parameter of an ALERT statement.  ALERT generates field-independent events, since it is not associated with any particular control.  When EVENT:AlertKey is generated by an ALERT key, the USE variable of the control that currently has input focus is not automatically updated (use UPDATE if this is required).

The ALERT statement alerts its keys separately from the ALRT attribute of a window or control.  This means that clearing all ALERT keys has no effect on any keys alerted by ALRT attributes.

Example:

  ALERT	!Turn off all alerted keys

  ALERT(F1Key,F12Key)	!Alert all function keys

  ALERT(279)	!Alert the Ctrl-Esc key

See Also:

UPDATE


EVENT  (return event number)

EVENT( )

The EVENT function returns a number indicating what caused ACCEPT to alert the program that something has happened that it may need to handle.  There are EQUATEs listed in EQUATES.CLW for all the events the program may need to handle.

There are two types of events generated by ACCEPT: field-specific and field-indepedent events.  Field-specific events affect a single control, while field-independent events affect the window or program.  The type of event can be determined by the values returned by the ACCEPTED, SELECTED, and FIELD functions.  If you need to know which field has on a field-independent events, use the FOCUS function.

For fieldspecific events:

The FIELD function returns the field number of the control on which the event occurred.  The ACCEPTED function returns the field number if the event is EVENT:Accepted.  The SELECTED function returns the field number if the event is EVENT:Selected.

For fieldindependent events:

The FIELD, ACCEPTED, and SELECTED functions all return zero (0).

Return Data Type:  SHORT

Example:

ACCEPT

  CASE EVENT()

  OF EVENT:Selected

    CASE SELECTED()

    OF ?Control1

      !Pre-edit code here

    OF ?Control2

      !Pre-edit code here

    END

  OF EVENT:Accepted

    CASE ACCEPTED()

    OF ?Control1

      !Post-edit code here

    OF ?Control2

      !Post-edit code here

    END

  OF EVENT:Suspend

      !Save some stuff

  OF EVENT:Resume

      !Restore the stuff

  END

END


POST  (post user-defined event)

POST( event [,control] [,thread] )

POST	Posts an event.

event	An integer constant, variable, expression, or EQUATE containing an event number.  A value in the range 400h to 0FFFh is a User-defined event.

control	An integer constant, EQUATE, or variable containing the field number of the control affected by the event.  If omitted, the event is field-independent.

thread	An integer constant, EQUATE, or variable containing the execution thread number whose ACCEPT loop is to process the event.  If omitted, the event is posted to the current thread.

POST posts an event to the currently active ACCEPT loop of the specified thread.  This may be User-defined events, or any other event.  User-defined event numbers can be defined as any integer between 400h and 0FFFh.  Any event posted with a control specified is a field-specific event, while those without are field-independent events.

Example:

Win1     WINDOW('Tools'),AT(156,46,32,28),TOOLBOX

           BUTTON('Date'),AT(0,0,,),USE(?Button1)

           BUTTON('Time'),AT(0,14,,),USE(?Button2)

         END

  CODE

  OPEN(Win1)

  ACCEPT

    IF EVENT() = EVENT:User THEN BREAK. !Detect user-defined event

    CASE ACCEPTED()

    OF ?Button1

      POST(EVENT:User,,UseToolsThread)  !Post field-independent event to other thread

    OF ?Button2

      POST(EVENT:User)  	!Post field-independent event to this thread

    END

  END

  CLOSE(Win1)


YIELD  (allow event processing)

YIELD

YIELD temporarily gives program control to Windows to allow other concurrently executing windows applications to process any events they need to handle.  YIELD also allows control to pass to EVENT:Timer events in other execution threads within the same application.  This is used to ensure that long batch processing in a Clarion application does not completely "lock out" other applications from completing their tasks.

Example:

SET(File)	!Set up a batch process

LOOP

  NEXT(File)

    IF ERRORCODE() THEN BREAK.

  !Perform some batch processing code

  YIELD	!Yield control to other applications

END


Multi-Threaded Applications

Multi-Threading and MDI

Multi-Threading vs. Multi-Tasking

START  (return new execution thread)

THREAD  (return current execution thread)


Multi-Threading and MDI

A multi-threaded application allows the user the ability to switch between multiple execution threads at runtime, as they choose.  This makes the Windows Multiple Document Interface (MDI) approach to programming possible.  A single Windows application may have a maximum of 64 execution threads concurrently available.

The first execution thread in any program is the main program code.  This opens an APPLICATION structure as the MDI "parent" window, containing the main menu selections for the application.

The menu selections in the APPLICATION's MENUBAR call the START function to begin each subsequent execution thread.  The procedures called by START usually open an MDI "child" WINDOW, as a document window or dialog box.  These windows allow the user to perform the tasks the application is designed to perform.

The last MDI "child" WINDOW opened (and not closed) in any execution thread is the "top" window in the thread and has input focus when that thread is executing.  The user can switch between execution threads by using the mouse to CLICK on the top window of another execution thread.  Thread switching can also be accomplished by selecting an open window from an MDI window list in the main menu, if the APPLICATION's menu contains this standard Windows menu item.


Multi-Threading vs. Multi-Tasking

Multi-threading should not be confused with the ability to have the computer perform multiple tasks concurrently.  Multi-threading does not necessarily imply multi-tasking, because only one thread normally executes at a time.

Windows allows non-preemptive multi-tasking between separately executing applications in any mode, and preemptive multi-tasking in 386 enhanced mode.  Preemptive multi-tasking is based on "time slicing" between the applications and the amount of time each simultaneously executing application receives is governed by the end user's Windows configuration.  See your Windows documentation for an explanation of Windows' multi-tasking settings.

A form of cooperative non-preemptive multi-threading (similar to inter-application multi-tasking) can be accomplished within a single Clarion application by using the TIMER attribute.  This is not based on "time slicing" between execution threads.  Instead, each execution thread gains control and does not relinquish it until it executes an ASK or ACCEPT statement.

When the top window of an execution thread has the TIMER attribute, a timer event (EVENT:Timer) is periodically generated to cycle its ACCEPT loop to process the event.  This occurs even if the thread does not currently have input focus.  Therefore, if you want to perform this type of multi-threading, you must ensure that any lengthy execution code includes YIELD statements that occasionally execute to allow the timer events in other threads to generate and execute.


START  (return new execution thread)

START(procedure [,stack] )

START	Begins a new execution thread.

procedure	The label of the first PROCEDURE to call on the new execution thread.  The procedure must have been prototyped not to receive any parameters.

stack	An integer constant or variable containing the size of the stack to allocate to the new execution thread.  If omitted, the default stack is 10,000 bytes.

The START function begins a new execution thread, calling the procedure and returning the number assigned to the new thread.  The returned thread number number is used by procedures and functions whose action may be performed on any execution thread, such as SETWINDOW.  The maximum number of simultaneously available execution threads in a single application is 64.

The first execution thread in any program is the main program code, which is always numbered one (1).  Therefore, the lowest value START can return is two (2), when the first START function is executed in a program.  START may return zero (0), which indicates failure to open the thread.  This can occur by attempting to START a 65th thread, or by running out of memory, or by starting a thread when the system is modal.

Return Data Type:  LONG

Example:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    MENU('&File'),USE(?FileMenu)

      ITEM('Selection &1...'),USE(?MenuSelection1)

      ITEM('Selection &2...'),USE(?MenuSelection2)

    END

  END

END

SaveThread1    LONG	!Declare thread number save variable

SaveThread2    LONG	!Declare thread number save variable

  CODE

  OPEN(MainWin)	!Open the APPLICATION

  ACCEPT	!Handle Global events

    CASE ACCEPTED()

    OF ?MenuSelection1

      SaveThread1 = START(NewProc1)	!Start a new thread

    OF ?MenuSelection2

      SaveThread2 = START(NewProc2)	!Start a new thread

    OF ?Exit

      RETURN

    END


THREAD  (return current execution thread)

THREAD( )

The THREAD function returns the currently executing thread number.  The returned thread number number can be used by procedures and functions whose action may be performed on any execution thread, such as SETWINDOW.

The maximum number of simultaneously available execution threads in a single application is 64.  The first execution thread in any program is the main program code, which is always thread number one (1).  Therefore, THREAD always returns a value in the range of one (1) to sixty-four (64).

Return Data Type:  LONG

Example:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    MENU('&File'),USE(?FileMenu)

      ITEM('Selection &1...'),USE(?MenuSelection1)

      ITEM('Selection &2...'),USE(?MenuSelection2)

    END

  END

END

SaveThread     LONG	!Declare thread number save variable

SaveThread1    LONG	!Declare thread number save variable

SaveThread2    LONG	!Declare thread number save variable

  CODE

  SaveThread = THREAD()	!Save thread number

  OPEN(MainWin)	!Open the APPLICATION

  ACCEPT	!Handle Global events

    CASE ACCEPTED()

    OF ?MenuSelection1

      SaveThread1 = START(NewProc1)	!Start a new thread

    OF ?MenuSelection2

      SaveThread2 = START(NewProc2)	!Start a new thread

    OF ?Exit

      RETURN

    END


Window Procedures

CHANGE  (change control field value)

CLOSE  (close window)

CREATE  (create new control)

DISABLE  (dim a control)

DISPLAY  (write USE variables to screen)

ENABLE  (re-activate dimmed control)

ERASE  (clear screen control and USE variables)

GETFONT  (get font information)

GETPOSITION  (get control position)

HELP  (help window access)

HIDE  (blank a control)

OPEN  (open window for processing)

SELECT  (select next control to process)

SET3DLOOK  (set 3D window look)

SETCURSOR  (set temporary mouse cursor)

SETFONT  (specify font)

SETPOSITION  (specify new control position)

SETTARGET  (set current window or report)

UNHIDE  (show hidden control)

UPDATE  (write from screen to USE variables)


CHANGE  (change control field value)

CHANGE(control,value)

control	Field number or field equate label of a window control field.

value	A constant or variable containing the control's new value.

The CHANGE statement changes the value displayed in a control in an APPLICATION or WINDOW structure.  CHANGE updates the control's USE variable with the value, and then displays that new value in the control field.

Example:

Screen	WINDOW,PRE(Scr)

  ENTRY(@N3),USE(Ctl:Code)

  ENTRY(@S30),USE(Ctl:Name)

  BUTTON('OK'),USE(?OkButton),KEY(EnterKey)

  BUTTON('Cancel'),USE(?CanxButton),KEY(EscKey)

END

  CODE

  OPEN(Screen)

  ACCEPT

    CASE EVENT()

    OF EVENT:Selected

      CASE SELECTED()

      OF ?Ctl:Code

        CHANGE(?Ctl:Code,4)	!Change Ctl:Code to 4 and display it

      OF ?Ctl:Name

        CHANGE(?Ctl:Name,'ABC Company')

!Change Ctl:Name to ABC Company and display

      END

    OF EVENT:Accepted

      CASE ACCEPTED()

      OF ?OkButton

        BREAK

      OF ?CanxButton

        CLEAR(Ctl:Record)

        BREAK

      END

    END


CLOSE  (close window)

CLOSE(label)

CLOSE	Closes the active APPLICATION or WINDOW structure.

label	The label of an APPLICATION or WINDOW structure.

CLOSE terminates processing on the active APPLICATION or WINDOW structure.  Memory used by the active window is released when it is closed and the underlying screen is automatically re-drawn.

When a window is closed, if it is not the top-most window on its execution thread, all windows opened subsequent to the window being closed are automatically closed first.  This occurs in the reverse order from which they were opened.

An APPLICATION or WINDOW that is declared local to (within) a PROCEDURE or FUNCTION is automatically closed when the program RETURNs from the procedure.

Example:

  CLOSE(MenuScr)	!Close the  menu screen

  CLOSE(CustEntry)	!Close customer data entry screen


CREATE  (create new control)

CREATE( control ,type [,parent] )

CREATE	Creates a new control.

control	A field number or field equate label for the control to create.

type	An integer constant, expression, EQUATE, or variable that specifies the type of control to create.

parent	A field number or field equate label.  This specifies an OPTION, GROUP, or MENU to contain the new control.

CREATE dynamically creates a new control in the currently active APPLICATION or WINDOW.  When first created, the new control is initially hidden, so its properties can be set using the runtime property assignment syntax, SETPOSITION, and SETFONT.  It appears on screen only by issuing an UNHIDE statement for the control.  To place the new control on the toolbar, add CREATE:TOOLBAR to the equate for the new control's type.

EQUATE statements for the type parameter are contained in the EQUATES.CLW file.  The following list is a comprehensive sample of these (see EQUATES.CLW for the complete list):

CREATE:sstring     	STRING(picture),USE(variable)

CREATE:string      	STRING(constant)

CREATE:image       	IMAGE()

CREATE:region      	REGION()

CREATE:line        	LINE()

CREATE:box         	BOX()

CREATE:ellipse     	ELLIPSE()

CREATE:entry       	ENTRY()

CREATE:button      	BUTTON()

CREATE:prompt      	PROMPT()

CREATE:option      	OPTION()

CREATE:radio       	RADIO()

CREATE:check       	CHECK()

CREATE:group       	GROUP()

CREATE:list        	LIST()

CREATE:combo       	COMBO()

CREATE:spin        	SPIN()

CREATE:text        	TEXT()

CREATE:custom      	CUSTOM()

CREATE:droplist    	LIST(),DROP()

CREATE:dropcombo   	COMBO(),DROP()

CREATE:menu        	MENU()

CREATE:item        	ITEM()

Example:

Screen	WINDOW,PRE(Scr)

  ENTRY(@N3),USE(Ctl:Code)

  ENTRY(@S30),USE(Ctl:Name)

  BUTTON('OK'),USE(?OkButton),KEY(EnterKey)

  BUTTON('Cancel'),USE(?CanxButton),KEY(EscKey)

END

X	SHORT

Y	SHORT

Width	SHORT

Height	SHORT

Code4Entry	STRING(10)

  CODE

  OPEN(Screen)

  ACCEPT

    CASE ACCEPTED()

    OF ?Ctl:Code

      IF Ctl:Code = 4

        CREATE(?Code4Entry,CREATE:entry)	!Create the control

        ?Code4Entry{PROP:use} = 'Code4Entry'	!Set USE variable

        ?Code4Entry{PROP:text} = '@s10'	!Set entry picture

        GETPOSITION(?Ctl:Code,X,Y,Width,Height)

        ?Code4Entry{PROP:at[1]} = X + Width + 40	!Set x position

        ?Code4Entry{PROP:at[2]} = Y 	!Set y position

        UNHIDE(?Code4Entry)	!Display the new control

      END

    OF ?OkButton

      BREAK

    OF ?CanxButton

      CLEAR(Ctl:Record)

      BREAK

    END

  END

  CLOSE(Screen)

  RETURN


DISABLE  (dim a control)

DISABLE(first control [,last control] )

DISABLE	Dims controls on the window.

first control	Field number or field equate label of a control, or the first control in a range of controls.

last control	Field number or field equate label of the last control in a range of controls.

The DISABLE statement disables a control or a range of controls on an APPLICATION or WINDOW structure.  When disabled, the control appears dimmed on screen.

Example:

Screen	WINDOW,PRE(Scr)

  ENTRY(@N3),USE(Ctl:Code)

  ENTRY(@S30),USE(Ctl:Name)

  BUTTON('OK'),USE(?OkButton),KEY(EnterKey)

  BUTTON('Cancel'),USE(?CanxButton),KEY(EscKey)

END

  CODE

  OPEN(Screen)

  DISABLE(?Ctl:Code)    	!Disable a control

  DISABLE(?Ctl:Code,?Ctl:Name)  	!Disable range of controls

  DISABLE(2)      	!Disable the second control

See Also:

ENABLE

HIDE

UNHIDE


DISPLAY  (write USE variables to screen)

DISPLAY( [first control] [,last control] )

DISPLAY	Writes the contents of USE variables to their associated controls.

first control	Field number or field equate label of a control, or the first control in a range of controls.

last control	Field number or field equate label of the last control in a range of controls.

DISPLAY writes the contents of the USE variables to their associated controls on the active window.  DISPLAY with no parameters writes the USE variables for all controls on the screen.  Using first control alone, as the parameter of DISPLAY, writes a specific USE variable to the screen.  Both first control and last control parameters are used to display the USE variables for an inclusive range of controls on the screen.

The current contents of the USE variables of all controls are automatically displayed on screen each time the ACCEPT loop cycles.  This eliminates the need to explicitly issue a DISPLAY statement to update the video display.  Of course, if your application performs some operation that takes a long tiome and you want to indicate to the user that something is happening without cycling back to the top of the ACCEPT loop, you should DISPLAY some variable that you have updated.

Example:

DISPLAY	!Display all controls on the screen

DISPLAY(2)	!Display control number 2

DISPLAY(3,7)	!Display controls 3 through 7

DISPLAY(?MenuControl)	!Display the menu control

DISPLAY(?TextBlock,?Ok)	!Display range of controls

See Also:

Field Equate Labels

UPDATE

ERASE


ENABLE  (re-activate dimmed control)

ENABLE(first control [,last control] )

ENABLE	Reactivates disabled controls.

first control	Field number or field equate label of a control, or the first control in a range of controls.

last control	Field number or field equate label of the last control in a range of controls.

The ENABLE statement reactivates a control, or range of controls, that were dimmed by the DISABLE statement, or were declared with the DISABLE attribute.  Once reactivated, the control is again available to the operator for selection.

Example:

  CODE

  OPEN(Screen)

  DISABLE(?Control2)	!Control2 is deactivated

  IF Ctl:Password = 'Supervisor'

    ENABLE(?Control2)	!Re-activate Control2

  END

See Also:

DISABLE

HIDE

UNHIDE


ERASE  (clear screen control and USE variables)

ERASE( [first control] [,last control] )

ERASE	Blanks controls and clears their USE variables.

first control	Field number or field equate label of a control, or the first control in a range of controls.

last control	Field number or field equate label of the last control in a range of controls.

The ERASE statement erases the data from controls in the window and clears their corresponding USE variables.  ERASE with no parameters erases all controls in the window.  Using first control alone, as the parameter of ERASE, clears a specific USE variable and its associated control.  Both first control and last control parameters are used to clear the USE variables and associated controls for an inclusive range of controls in the window.

Example:

ERASE(?)	!Erase the currently selected control

ERASE	!Erase all controls on the screen

ERASE(3,7)	!Erase controls 3 through 7

ERASE(?Name,?Zip)	!Erase controls from name through zip

ERASE(?City,?City+2)	!Erase City and 2 controls following City

See Also:

Field Equate Labels


GETFONT  (get font information)

GETFONT( control ,typeface , size ,color ,style)

GETFONT	Gets display font information.

control	A field number or field equate label for the control from which to get the information.  If control is zero (0), it specifies the WINDOW.

typeface	A string variable to receive the name of the font.

size	An integer variable to receive the size (in points) of the font.

color	A LONG integer variable to receive the red, green, and blue values for the color of the font in the low-order three bytes.  If the value is negative, the color represents a system color.

style	An integer variable to receive the strike weight and style of the font.

GETFONT gets the display font information for the control.  If the control parameter is zero (0), GETFONT gets the default display font for the window.

Example:

TypeFace	LONG

Size	BYTE

Color	LONG

Style	LONG

  CODE

  OPEN(Screen)

  GETFONT(0,TypeFace,Size,Color,Style)	!Get font info for the window

See Also:

SETFONT


GETPOSITION  (get control position)

GETPOSITION( control ,x , y ,width ,height)

GETPOSITION	Gets the position and size of an APPLICATION, WINDOW, or control.

control	A field number or field equate label for the control from which to get the information.  If control is zero (0), it specifies the window.

x	An integer variable to receive the horizontal position of the top left corner.

y	An integer variable to receive the vertical position of the top left corner.

width	An integer variable to receive the width.

height	An integer variable to receive the height.

GETPOSITION gets the position and size of an APPLICATION, WINDOW, or control.  The position and size values are dependent upon the presence or absence of the SCROLL attribute on the control.  If SCROLL is present, the values are relative to the virtual window.  If SCROLL is not present, the values are relative to the top left corner of the currently visible portion of the window.  Thgis means the values returned always match those specified in the AT attribute or most recent SETPOSITION.

The values in the x, y, width, and height parameters default to dialog units unless the THOUS, MM, or POINTS attribute is set for the window.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the window.  This measurement is based on the font specified in the FONT attribute of the window, or the system default font specified by Windows.

Example:

Screen	WINDOW,PRE(Scr)

  ENTRY(@N3),USE(Ctl:Code)

  ENTRY(@S30),USE(Ctl:Name)

  BUTTON('OK'),USE(?OkButton),KEY(EnterKey)

  BUTTON('Cancel'),USE(?CanxButton),KEY(EscKey)

END

X	SHORT

Y	SHORT

Width	SHORT

Height	SHORT

  CODE

  OPEN(Screen)

  GETPOSITION(?Ctl:Code,X,Y,Width,Height)

See Also:

SETPOSITION


HELP  (help window access)

HELP([helpfile] [,window-id])

HELP	Opens a help file and activates a help window.

helpfile	A string constant or the label of a STRING variable that has the DOS directory file specification for the help file.  If the file specification does not contain a complete path and filename, the help file is assumed to be in the current directory.  If the file extension is omitted, ".HLP" is assumed.  If the helpfile parameter is omitted, a comma is required to hold its position.

window-id	A string constant or the label of a STRING variable that contains the key used to access the help system.  This may be either a help keyword or a "context string."

The HELP statement opens a designated helpfile, and activates the window named by the window-id.  While an ASK or ACCEPT is controlling program execution, the active help window is displayed when the operator presses F1 (the "Help" key).

If the window-id parameter is omitted, the helpfile is nominated but not opened.  If the helpfile parameter is omitted, the current help file is opened, and the window identified by window-id is activated.  If both parameters are omitted, the current helpfile is opened at the current topic.

The window-ID may contain a Help keyword.  This is a keyword that is displayed in the Help Search dialog.  When the user presses F1, if only one topic in the help file specifies this keyword, the help file is opened at that topic; if more than one topic specifies the keyword, the search dialog is opened for the user.

A "context string" is identified by a leading tilde (~) in the window-ID, followed by a unique identifier associated with exactly one help topic.  If the tilde is missing, the window-ID is assumed to be a help keyword.  When the user presses F1, the help file is opened at the specific topic associated with that "context string."

Help windows are also activated by the HLP attribute of an APPLICATION, WINDOW, or control.

Example:

HELP('C:\HLPDIR\LEDGER.HLP')	!Open the gen ledger help file

HELP(,'~CustUpd')	!Activate customer update help window

HELP	!Display the help window

See Also:

ASK

ACCEPT

HLP


HIDE  (blank a control)

HIDE(first control [,last control] )

HIDE	Hides window controls.

first control	Field number or field equate label of a control, or the first control in a range of controls.

last control	Field number or field equate label of the last control in a range of controls.

The HIDE statement hides a control, or range of controls, on an APPLICATION or WINDOW structure.  When hidden, the control does not appear on screen.

Example:

Screen	WINDOW,PRE(Scr)

  ENTRY(@N3),USE(Ctl:Code)

  ENTRY(@S30),USE(Ctl:Name)

  BUTTON('OK'),USE(?OkButton),KEY(EnterKey)

  BUTTON('Cancel'),USE(?CanxButton),KEY(EscKey)

END

  CODE

  OPEN(Screen)

  HIDE(?Ctl:Code)    	!Hide a control

  HIDE(?Ctl:Code,?Ctl:Name)  	!Hide range of controls

  HIDE(2)      	!Hide the second control

See Also:

UNHIDE

ENABLE

DISABLE


OPEN  (open window for processing)

OPEN(label)

OPEN	Opens a window.

label	The label of an APPLICATION or WINDOW structure.

OPEN activates an APPLICATION or WINDOW for processing.  However, nothing is displayed until a DISPLAY statement or the ACCEPT loop is encountered.  This allows an opportunity to execute pre-display code to customize the display.

Example:

OPEN(MenuScr)	!Open the menu screen

OPEN(CustEntry)	!Open customer data entry screen


SELECT  (select next control to process)

SELECT(control [,position] [,endposition] )

SELECT	Sets the next control to receive input focus.

control	A field number or field equate label of the next control to process. If ommitted, the SELECT statement initiates AcceptAll mode.

position	Specifies a position within the control to place the cursor.  For an ENTRY or TEXT, SPIN, or COMBO control, this is a character position, or a beginning character position for a marked block.  For an OPTION structure, this is the selection number within the OPTION.  For a LIST control, this is the QUEUE entry number.

endposition	Specifies an ending character position within an ENTRY, TEXT, SPIN, or COMBO control.  The character position specified by position and endposition are marked as a block, available for cut and paste operations.

SELECT overrides the normal TAB key sequence control selection order of an APPLICATION or WINDOW.  Its action affects the next ACCEPT statement that executes.  The control parameter determines which control the ACCEPT loop will process next.  If control specifies a control which cannot rceive focus because a DISABLE or HIDE statment has been issued, focus goes to the next control following it in the window's source code that can receive focus.

SELECT with position and endposition parameters specifies a marked block in the control which is available for cut and paste operations.

SELECT with no parameters initiates AcceptAll mode.  This is a field edit mode in which each control in the window is processed in TAB key sequence by generating EVENT:Accepted for each.  This allows data entry validation code to execute for all controls, including those that the user has not touched.  AcceptAll mode terminates when any of the following conditions is met:

A SELECT(?) statement selects the same control for the user to edit.  This code usually indicates the value it contains is invalid and the user must re-enter data.

The Window{PROP:AcceptAll} property is set to zero (0).  This property contains one (1) when AcceptAll mode is active.  Assigning values to this property can also be used to initiate and terminate AcceptAll mode.

A control with the REQ attribute is blank or zero.  AcceptAll mode terminates with the control highlighted for user entry, without processing any more fields in the TAB key sequence.

All controls have been processed.  EVENT:Completed is posted to the window.

Example:

Screen	WINDOW,PRE(Scr)

  ENTRY(@N3),USE(Ctl:Code)

  ENTRY(@S30),USE(Ctl:Name)

  BUTTON('OK'),USE(?OkButton),KEY(EnterKey)

  BUTTON('Cancel'),USE(?CanxButton),KEY(EscKey)

END

  CODE

  OPEN(Screen)

  SELECT(?Ctl:Code)	!Start with Ctl:Code

  ACCEPT

    CASE ACCEPTED()

    OF ?Ctl:Code

      IF Ctl:Code > 150	!If data entered is invalid

        BEEP	! alert the user and

        SELECT(?)	! make them re-enter the data

      END

    OF ?Ctl:Name

      SELECT(?Ctl:Name,1,5)	!Mark first five characters as a block

    OF ?OkButton

      SELECT	!Initiate AcceptAll mode

    END

    IF EVENT() = EVENT:Completed THEN BREAK.

!AcceptAll mode terminated

  END

See Also:

ACCEPT


SET3DLOOK  (set 3D window look)

SET3DLOOK( [switch] )

SET3DLOOK	Toggles three-dimensional look and feel.

switch	An integer constant switching the 3D look off (0) and on (1).  If omitted, the default is one (1).

The SET3DLOOK procedure sets up the program to display a three-dimensional look and feel.  The default program setting is 3D enabled.  On a WINDOW, the GRAY attribute causes the controls to display with a three-dimensional appearance.  Controls in the TOOLBAR are always displayed with the three-dimensional look, unless disabled by SET3DLOOK.  When three-dimensional look is disabled by SET3DLOOK, the GRAY attribute has no effect.

SET3DLOOK(0) turns off the three-dimensional look and feel.  SET3DLOOK(1) turns on the three-dimensional look and feel.  Values other than zero or one are reserved for future use.

Example:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    MENU('&File'),USE(?FileMenu)

      ITEM('&Open...'),USE(?OpenFile)

      ITEM('&Close'),USE(?CloseFile),DISABLE

      ITEM('Turn off 3D Look'),USE(?Toggle3D),CHECK

      ITEM('E&xit'),USE(?MainExit)

    END

  END

END

  CODE

  OPEN(MainWin)

  ACCEPT

    CASE ACCEPTED()

    OF ?Toggle3D	!

      IF MainWin$?Toggle3D{PROP:text} = 'Turn off 3D Look'	!If on

        SET3DLOOK(0)	!Turn off

        MainWin$?Toggle3D{PROP:text} = 'Turn on 3D Look'	! and change text

      ELSE	!Else

        SET3DLOOK(1)	!Turn on

        MainWin$?Toggle3D{PROP:text} = 'Turn off 3D Look'	! and change text

      END

    OF ?OpenFile

      START(OpenFileProc)

    OF ?MainExit

      BREAK

    END

  END

  CLOSE(MainWin)


SETCURSOR  (set temporary mouse cursor)

SETCURSOR( [cursor] )

SETCURSOR	Specifies a temporary mouse cursor to display.

cursor	An EQUATE naming a Windows-standard mouse cursor.  If omitted, turns off the temporary cursor.

The SETCURSOR statement specifies a temporary mouse cursor to display until a SETCURSOR statement without a cursor parameter turns it off.  This cursor overrides all CURSOR attributes.  When SETCURSOR without a cursor parameter is encountered, all CURSOR attributes once again take effect.  SETCURSOR is generally used to display the hourglass while your program is doing some "behind the scenes" work that the user should not break into.

EQUATE statements for the Windows-standard mouse cursors are contained in the EQUATES.CLW file.  The following list is a representative sample of these (see EQUATES.CLW for the complete list):

CURSOR:None	No mouse cursor

CURSOR:Arrow	Normal windows arrow cursor

CURSOR:IBeam	Capital "I" like a steel I-beam

CURSOR:Wait	Hourglass

CURSOR:Cross	Large plus sign

CURSOR:UpArrow	Vertical arrow

CURSOR:Size	Four-headed arrow

CURSOR:Icon	Box within a box

CURSOR:SizeNWSE	Double-headed arrow slanting left

CURSOR:SizeNESW	Double-headed arrow slanting right

CURSOR:SizeWE	Double-headed horizontal arrow

CURSOR:SizeNS	Double-headed vertical arrow

Example:

MainWin	APPLICATION('My Application'),SYSTEM,MAX,ICON('MyIcon.ICO'),STATUS |

  ,HVSCROLL,RESIZE

  MENUBAR

    ITEM('Batch Update'),USE(?Batch)

  END

END

  CODE

  OPEN(MainWin)

  ACCEPT

    CASE ACCEPTED()

    OF ?Batch

      SETCURSOR(CURSOR:Wait)	!Turn on hourglass mouse cursor

      BatchUpdate	! and call the batch update procedure

    END

  END


SETFONT  (specify font)

SETFONT( control ,typeface , size ,color ,style)

SETFONT	Dynamically sets the display font for a control.

control	A field number or field equate label for the control to affect.  If control is zero (0), it specifies the WINDOW.

typeface	A string constant or variable containing the name of the font.  If omitted, the system font is used.

size	An integer constant or variable containing the size (in points) of the font.  If omitted, the system default font size is used.

color	A LONG integer constant or variable containing the red, green, and blue values for the color of the font in the low-order three bytes, or an EQUATE for a standard Windows color value.  If omitted, black is used.

style	An integer constant, constant expression, EQUATE, or variable specifying the strike weight and style of the font.  If omitted, the weight is normal.

SETFONT dynamically specifies the display font for the control, overriding any FONT attribute previously specified.  If the control parameter is zero (0), SETFONT specifies the default display font for the window.

SETFONT allows you to specify all parameters of a font change at once, instead of one at a time as runtime property assignment allows.  This has the advantage of implementing all changes at once, whereas runtime property assignment would change each individually, displaying each separate change as it occurs.

The typeface may name any font registered in the Windows system.  The EQUATES.CLW file contains EQUATE values for standard style values.  A style on the range zero (0) to one thousand (1000) specifies the strike weight of the font.  You may also add values that indicate italic, underline, or strikeout text.  The following EQUATES are in EQUATES.CLW:

  FONT:thin 	EQUATE (100)

  FONT:regular 	EQUATE (400)

  FONT:bold 	EQUATE (700)

  FONT:italic 	EQUATE (01000H)

  FONT:underline 	EQUATE (02000H)

  FONT:strikeout 	EQUATE (04000H)

Example:

  SETFONT(0,'Arial',14,,FONT:thin+FONT:Italic)	!14 pt. Arial black thin italic

See Also:

GETFONT


SETPOSITION  (specify new control position)

SETPOSITION( control ,x , y ,width ,height)

SETPOSITION	Dynamically specifies the position and size of an APPLICATION, WINDOW, or control.

control	A field number or field equate label for the control to affect.  If control is zero (0), it specifies the window.

x	An integer constant, expression, or variable that specifies the horizontal position of the top left corner.  If omitted, the x position is not changed.

y	An integer constant, expression, or variable that specifies the vertical position of the top left corner.  If omitted, the y position is not changed.

width	An integer constant, expression, or variable that specifies the width.  If omitted, the width is not changed.

height	An integer constant, expression, or variable that specifies the height.  If omitted, the height is not changed.

SETPOSITION dynamically specifies the position and size of an APPLICATION, WINDOW, or control.  If any parameter is omitted, the value is not changed.

The values contained in the x, y, width, and height parameters default to dialog units unless the THOUS, MM, or POINTS attribute is specified on the APPLICATION or WINDOW.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the window.  This measurement is based on the font specified in the FONT attribute of the window, or the system default font specified by Windows.

Using SETPOSITION produces a "smoother" control appearance change than using property expressions to change the AT attribute's parameter values.  This is because SETPOSITION changes all four parameters at once.  Property expressions must change one parameter at a time.  Since each individual parameter change would be immediately visible on screen, this would cause the control to appear to "jump."

Example:

        CREATE(?Code4Entry,CREATE:entry,?Ctl:Code)	!Create a control

        ?Code4Entry{PROP:use} = 'Code4Entry'	!Set USE variable

        ?Code4Entry{PROP:text} = '@s10'	!Set entry picture

        GETPOSITION(?Ctl:Code,X,Y,Width,Height)	!Get Ctl:Code position

        SETPOSITION(?Code4Entry,X+Width+40,Y)	!Set position 40 past Ctl:Code

        UNHIDE(?Code4Entry)	!Display the new control

See Also:

GETPOSITION


SETTARGET  (set current window or report)

SETTARGET( [target] [,thread] )

SETTARGET	Sets the current window (or report) for drawing graphics and other window-interaction statements.

target	The label of an APPLICATION, WINDOW or REPORT structure.  If omitted, the last window opened and not yet closed in the specified thread is used.

thread	The number of the execution thread in which the target structure is contained in the topmost procedure or function.  If omitted, the current execution thread is used.

The SETTARGET procedure makes the target the structure which is current for drawing with the graphics primitives functions.  SETTARGET also sets the target for runtime property assignment, and the CREATE, SETPOSITION, GETPOSITION, SETFONT, GETFONT, DISABLE, HIDE, CONTENTS, DISPLAY, ERASE, and UPDATE statements.  Using these statements with SETTARGET allows you to manipulate the window display in the topmost window of any execution thread.

This target will receive any graphics drawn with the graphics procedures and functions described in the Graphics Commands chapter.  This allows you to draw graphics to the topmost window, or report, in any execution thread.

SETTARGET sets the "built-in" variable, TARGET (also set when a window is opened), which may be used in any statement which requires the label of the current window or report.  A REPORT data structure is never the default target.  Therefore, SETTARGET must be used before using the graphics primitives functions to draw graphics on a REPORT.

SETTARGET does not change procedures, and it does not change which ACCEPT loop receives the events generated by Windows.  SETTARGET without any parameters resets to the procedure and execution thread with the currently active ACCEPT loop.

Example:

Report	REPORT

  !Report structure controls

END

  CODE

  OPEN(Report)

  SETTARGET(Report)	!Make the report the current target

  TARGET{PROP:Landscape} = 1	! and turn on landscape mode


UNHIDE  (show hidden control)

UNHIDE(first control [,last control] )

UNHIDE	Displays previously hidden controls.

first control	Field number or field equate label of a control, or the first control in a range of controls.

last control	Field number or field equate label of the last control in a range of controls.

The UNHIDE statement reactivates a control or range of controls, that were hidden by the HIDE statement.  Once un-hidden, the control is again visible on screen.

Example:

  CODE

  OPEN(Screen)

  HIDE(?Control2)	!Control2 is hidden

  IF Ctl:Password = 'Supervisor'

    UNHIDE(?Control2)	!Unhide Control2

  END

See Also:

HIDE

ENABLE

DISABLE


UPDATE  (write from screen to USE variables)

UPDATE( [first control] [,last control] )

UPDATE	Writes the contents of a control to its USE variable.

first control	Field number or field equate label of a control, or the first control in a range of controls.

last control	Field number or field equate label of the last control in a range of controls.

UPDATE writes the contents of a screen control to its USE variable.  This takes the value displayed on screen and places it in the variable specified by the control's USE attribute.

USE variables are updated automatically by ACCEPT as each control is accepted.  However, certain events (such as an ALERTed key press) do not automatically update USE variables.  This is the purpose of the UPDATE statement.

  UPDATE

Updates all controls on the screen.

  UPDATE(first control)

Updates a specific USE variable from its associated screen control.

  UPDATE(first control,last control)

Updates the USE variables of an inclusive range of screen controls.

Example:

UPDATE(?)	!Update the currently selected control

UPDATE	!Update all controls on the screen

UPDATE(?Address)	!Update the address control

UPDATE(3,7)	!Update controls 3 through 7

UPDATE(?Name,?Zip)	!Update controls from name through zip

UPDATE(?City,?City+2)	!Update city and 2 controls following

See Also:

Field Equate Labels


Window Functions

ACCEPTED  (return control just completed)

CHOICE  (return relative item position)

CONTENTS  (return contents of USE variable)

FIELD  (return control with focus)

FIRSTFIELD  (return first window control)

FOCUS  (return control with focus)

INCOMPLETE  (return empty REQ control)

LASTFIELD  (return last window control)

MESSAGE  (return message box response)

MOUSEX  (return mouse horizontal position)

MOUSEY  (return mouse vertical position)

SELECTED  (return control that has received focus)


ACCEPTED  (return control just completed)

ACCEPTED( )

The ACCEPTED function returns the field number of the control on which an EVENT:Accepted event occurred.  ACCEPTED returns zero (0) for all other events.

Positive field numbers are assigned by the compiler to all WINDOW controls, in the order their declarations occur in the WINDOW structure.  Negative field numbers are assigned to all APPLICATION controls.  In executable code statements, field numbers are usually represented by field equate labels the label of the USE variable preceded by a question mark (?FieldName).

Return Data Type:  SHORT

Example:

CASE ACCEPTED()	!Process post-edit code

OF ?Cus:Company

  !Edit field value

OF ?Cus:CustType

  !Edit field value

END

See Also:

ACCEPT

EVENT


CHOICE  (return relative item position)

CHOICE( [control] )

CHOICE	Retuns a user selection number.

control	A field equate label of a LIST, COMBO, or OPTION control.

The CHOICE function returns the sequence number of a selected item in an OPTION structure, LIST box, or COMBO control.  With no parameter, CHOICE returns the sequence number of the selected item in the last control (LIST, OPTION, or COMBO) that generated a Field-specific event to cycle the ACCEPT loop.  CHOICE(control) returns the current selection number of any LIST, OPTION, or COMBO in the currently active window.

CHOICE returns the sequence number of the selected RADIO control within an OPTION structure.  The sequence number is determined by relative position within the OPTION.  The first control listed in the OPTION structure's code is relative position 1, the second is 2, etc.

CHOICE returns the memory QUEUE entry number of the selected item when a LIST or COMBO box is completed.

Return Data Type:  LONG

Example:

  CODE

  ACCEPT

    EXECUTE CHOICE()	!Perform menu option

      AddRec	!  procedure to add record

      PutRec	!  procedure to change record

      DelRec	!  procedure to delete record

      RETURN	!  return to caller

    END

  END


CONTENTS  (return contents of USE variable)

CONTENTS(control)

CONTENTS	Returns the value in the USE variable of a control.

control	A field number or field equate label.

The CONTENTS function returns a string containing the value in the USE variable of an ENTRY, OPTION RADIO, or TEXT control.

A USE variable may be longer than its associated control field display picture OR may contain fewer characters than its total capacity.  The CONTENTS function always returns the full length of the USE variable.

Return Data Type:  STRING

Example:

IF CONTENTS(?LastName) = '' AND CONTENTS(?FirstName) = ''

!If first and last name are blank

  MessageField = 'Must Enter a First or Last Name'	!  display error message

END


FIELD  (return control with focus)

FIELD( )

The FIELD function returns the field number of the control which has focus at the time of any field-specific event.  This includes both the EVENT:Selected and EVENT:Accepted events.  FIELD returns zero (0) for field-independent events.

Positive field numbers are assigned by the compiler to all WINDOW controls, in the order their declarations occur in the WINDOW structure.  Negative field numbers are assigned to all APPLICATION controls.  In executable code statements, field numbers are usually represented by field equate labels the label of the USE variable preceded by a question mark (?FieldName).

Return Data Type:  LONG

Example:

Screen	WINDOW

  ENTRY(@N4),USE(Control1)

  ENTRY(@N4),USE(Control2)

  ENTRY(@N4),USE(Control3)

  ENTRY(@N4),USE(Control4)

END

  CODE

  ACCEPT

    IF NOT ACCEPTED() THEN CYCLE.

    CASE FIELD()	!Control edit control

    OF ?Control1	! Field number 1

      IF Control1 = 0	!  if no entry

        BEEP	!    sound alarm

        SELECT(?)	!    stay on control

      .

    OF ?Control2 	! Field number 2

      IF Control2 > 4	!  if status is more than 4

        Scr:Message = 'Control must be less than 4'

        ERASE(?)	!    clear control

        SELECT(?)	!    edit the control again

      ELSE	!  value is valid

        CLEAR(Scr:Message)	!    clear message

    OF ?Control4	! Field number 4

      BREAK	!  exit processing loop

  . .	!  end case, end loop


FIRSTFIELD  (return first window control)

FIRSTFIELD( )

The FIRSTFIELD function returns the lowest field number in the currently active window.

Return Data Type:  LONG

Example:

DISABLE(FIRSTFIELD(),LASTFIELD())	!Dim all control fields


FOCUS  (return control with focus)

FOCUS( )

The FOCUS function returns the field number of the control which has input focus at any time any event occurs.

Positive field numbers are assigned by the compiler to all WINDOW controls, in the order their declarations occur in the WINDOW structure.  Negative field numbers are assigned to all APPLICATION controls.  In executable code statements, field numbers are usually represented by field equate labels the label of the USE variable preceded by a question mark (?FieldName).

Return Data Type:  LONG

Example:

Screen	WINDOW

  ENTRY(@N4),USE(Control1)

  ENTRY(@N4),USE(Control2)

  ENTRY(@N4),USE(Control3)

  ENTRY(@N4),USE(Control4)

END

  CODE

  ACCEPT

    CASE EVENT()

    OF EVENT:LoseFocus

    OROF EVENT:CloseWindow

      CASE FOCUS()	!Control edit control

      OF ?Control1	! Field number 1

        UPDATE(?Control1)

      OF ?Control2 	! Field number 2

        UPDATE(?Control2)

      OF ?Control4	! Field number 4

        UPDATE(?Control4)

      END

    END

  END

See Also:

ACCEPTED

SELECTED

EVENT

FIELD


INCOMPLETE  (return empty REQ control)

INCOMPLETE( )

The INCOMPLETE function returns the field number of the first control with the REQ attribute in the currently active window that has been left zero or blank, and gives input focus to that control.  If all REQ controls in the window contain data, INCOMPLETE returns zero (0) and leaves input focus on the control that already had it.

The INCOMPLETE function duplicates the action performed by the REQ attribute on a BUTTON control.

Return Data Type:  LONG

Example:

  CODE

  OPEN(Screen)

  ACCEPT

    CASE ACCEPTED()

    OF ?OkBUtton

      IF INCOMPLETE()	!Any REQ fields empty?

        SELECT(INCOMPLETE())	! if so, go to it

        CYCLE

      ELSE

        BREAK	!If not, go on

      END

    END

  END


LASTFIELD  (return last window control)

LASTFIELD( )

The LASTFIELD function returns the highest field number in the currently active window.

Return Data Type:  LONG

Example:

DISABLE(FIRSTFIELD(),LASTFIELD())	!Dim all control fields


MESSAGE  (return message box response)

MESSAGE( text [,caption] [,icon] [,buttons] [,default] [,style] )

MESSAGE	Displays a message dialog box and returns the button the user pressed.

text	A string constant or variable containing the text to display in the message box.

caption	The dialog box title.  If omitted, the dialog has no title.

icon	A string constant, variable, or EQUATE for a Windows standard icon.  If omitted, no icon is displayed on the dialog box.

buttons	An integer constant, variable, EQUATE, or expression which indicates Windows standard buttons to place on the dialog box.  If omitted, the dialog displays an Ok button.

default	An integer constant, variable, EQUATE, or expression which indicates the default button on the dialog box.  If omitted, the first button is the default.

style	An integer constant or variable which specifies the window is Application Modal (0) or System Modal (1).  If omitted, the window is Application Modal.

The MESSAGE function displays a Windows-standard message box, typically requiring only a Yes or No response, or no specific response at all.  The function returns the number of the button the user presses to exit the dialog box.

The style parameter determines whether the message window is Application Modal or System Modal.  An Application Modal window must be closed before the user is allowed to do anything else in the application, but does not prevent the user from switching to another Windows application.  A System Modal window must be closed before the user is allowed to do anything else in Windows.

Return Data Type:  USHORT

Example:

CASE MESSAGE('Quit?','Editor',ICON:Question,BUTTON:Yes+BUTTON:No,BUTTON:No,1)

!A ? icon with Yes and No buttons, the default button is No

!  the window is System Modal

OF BUTTON:No

OF BUTTON:Yes

  MESSAGE('Goodbye')	!A message with only an Ok button.

  RETURN

END


MOUSEX  (return mouse horizontal position)

MOUSEX( )

The MOUSEX function returns a numeric value corresponding to the current horizontal position of the mouse cursor at the time of the event.  The position is relative to the origin of that window.

The return value is in dialog units, unless the THOUS, MM, or POINTS parameter is on the currently active window.

Return Data Type:  SHORT

Example:

SaveMouseX = MOUSEX()	!Save mouse position


MOUSEY  (return mouse vertical position)

MOUSEY( )

The MOUSEY function returns a numeric value corresponding to the current vertical position of the mouse cursor at the time of the event.  The position is relative to the origin of that window.

The return value is in dialog units, unless the THOUS, MM, or POINTS parameter is on the currently active window.

Return Data Type:  SHORT

Example:

SaveMouseY = MOUSEY()	!Save mouse position


SELECTED  (return control that has received focus)

SELECTED( )

The SELECTED function returns the field number of the control receiving input focus when an EVENT:Selected event occurs.  SELECTED returns zero (0) for all other events.

Positive field numbers are assigned by the compiler to all WINDOW controls, in the order their declarations occur in the WINDOW structure.  Negative field numbers are assigned to all APPLICATION controls.  In executable code statements, field numbers are usually represented by field equate labels the label of the USE variable preceded by a question mark (?FieldName).

Return Data Type:  SHORT

Example:

CASE SELECTED()	!Process pre-edit code

OF ?Cus:Company

  !Pre-load field value

OF ?Cus:CustType

  !Pre-load field value

END

See Also:

ACCEPT

SELECT


Keyboard Procedures

ASK  (get one keystroke)

PRESS  (put characters in the buffer)

PRESSKEY  (put a keystroke in the buffer)

SETKEYCODE  (specify keycode)


ASK  (get one keystroke)

ASK

ASK reads a single keystroke from the keyboard buffer.  Program execution stops to wait for a keystroke.  If there is already a keystroke in the keyboard buffer, ASK gets one keystroke without waiting.

The ASK statement also allows any TIMER attribute events to generate and cycle their own ACCEPT loop.  This means any batch processing code can allow other threads to execute their TIMER attribute tasks during the batch process.

Example:

ASK	!Wait for a keystroke

LOOP WHILE KEYBOARD()	!Empty the keyboard buffer

  ASK	!  without processing keystrokes

END


PRESS  (put characters in the buffer)

PRESS(string)

PRESS	Places characters in the keyboard input buffer.

string	A string constant, variable, or expression.

PRESS places characters in the Windows keyboard input buffer.  The entire string is placed in the buffer.  Once placed in the keyboard buffer, the string is processed just as if the user had typed in the data.

Example:

IF Action = 'AddRecord'	!On the way into a memo on adding a record

  TempStrong = FORMAT(TODAY(),@D1) & ' ' & FORMAT(CLOCK(),@T4)

  PRESS(TempString)	!Pre-load first line of memo with date and time

END


PRESSKEY  (put a keystroke in the buffer)

PRESSKEY(keycode)

PRESSKEY	Places one keystroke in the keyboard input buffer.

keycode	An integer constant or keycode EQUATE label.

PRESSKEY places one keystroke in the Windows keyboard input buffer.  Once placed in the keyboard buffer, the keycode is processed just as if the user had pressed the key.

Example:

IF Action = 'Add'	!On the way into a memo control on an add record

  Cus:MemoControl = FORMAT(TODAY(),@D1) & ' ' & FORMAT(CLOCK(),@T4)

!Pre-load first line of memo with date and time

  PRESSKEY(EnterKey)	!  and position user on second line

END


SETKEYCODE  (specify keycode)

SETKEYCODE(keycode)

SETKEYCODE	Sets the keycode returned by the KEYCODE function.

keycode	An integer constant or keycode EQUATE label.

SETKEYCODE sets the internal keycode returned by the KEYCODE function.  The keycode is not put into the keyboard buffer.

Example:

SETKEYCODE(999)	!Set up the keycode function to return 999

See Also:

KEYCODE Equate Labels

KEYCODE


Keyboard Functions

KEYBOARD  (return keystroke waiting)

KEYCHAR  (return ASCII code)

KEYCODE  (return last keycode)


KEYBOARD  (return keystroke waiting)

KEYBOARD( )

The KEYBOARD function returns the keycode of the first keystroke in the keyboard buffer.  It is used to determine if there are keystrokes waiting to be processed by an ASK or ACCEPT statement.

Return Data Type:  LONG

Example:

LOOP UNTIL KEYBOARD()	!Wait for any key

  ASK

  IF KEYCODE() = EscKey THEN BREAK.	!On esc key, break the loop

END

See Also:

ASK

ACCEPT

KEYCODE Equate Labels


KEYCHAR  (return ASCII code)

KEYCHAR( )

The KEYCHAR function returns the ASCII value of the last key pressed at the time the event occurred.

Return Data Type:  LONG

Example:

ACCEPT	!Wait for an event

  CASE KEYCHAR()	!Process the last keystroke

  OF 'A' TO 'Z' 	!  upper case?

    DO ProcessUpper

  OF 'a' TO 'z' 	!  lower case?

    DO ProcesLower

  END

END

See Also:

ASK

ACCEPT

SELECT

KEYCODE Equate Labels


KEYCODE  (return last keycode)

KEYCODE( )

The KEYCODE function returns the keycode of the last key pressed at the time the event occurred, or the last keycode value set by the SETKEYCODE procedure.

Return Data Type:  LONG

Example:

ACCEPT	!Loop on the display

  CASE KEYCODE()	!Process the keystroke

  OF UpKey	!  up arrow

    DO GetRecordUp	!    get a record

  OF DownKey	!  down arrow

    DO GetRecordDn	!    get a record

  END

END

See Also:

ASK

ACCEPT

SELECT

KEYCODE Equate Labels


Windows Standard Dialog Functions

COLORDIALOG  (return chosen color)

FILEDIALOG  (return chosen file)

FONTDIALOG  (return chosen font)

PRINTERDIALOG  (return chosen printer)


COLORDIALOG  (return chosen color)

COLORDIALOG( [title] [,rgb] )

COLORDIALOG	Displays the Windows standard color choice dialog box to allow the user to choose a color.

title	A string constant or variable containing the title to place on the color choice dialog.  If omitted, a default title is supplied by Windows.

rgb	A LONG integer variable to receive the selected color.

The COLORDIALOG function displays the Windows standard color choice dialog box and returns the color chosen by the user in the rgb parameter.  Any existing value in the rgb parameter sets the default color choice presented to the user in the color choice dialog.

COLORDIALOG returns zero (0) if the user pressed the Cancel button, or one (1) if the user pressed the Ok button on the color choice dialog.

Return Data Type:  SHORT

Example:

MDIChild1	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

ColorNow	LONG

  CODE

  IF NOT COLORDIALOG('Choose Box Color',ColorNow)

    ColorNow = 000000FFh	!Default to Blue if user pressed Cancel

  END

  OPEN(MDIChild1)

  BOX(100,50,100,50,ColorNow)	!User-defined color for box


FILEDIALOG  (return chosen file)

FILEDIALOG( [title] [,file] [,extensions] [,flag] )

FILEDIALOG	Displays the Windows standard file choice dialog box to allow the user to choose a file.

title	A string constant or variable containing the title to place on the file choice dialog.  If omitted, a default title is supplied by Windows.

file	A string variable to receive the selected filename.

extensions	A string constant or variable containing the available file extension selections for the List Files of Type drop list.  If omitted, the default is all files (*.*).

flag	An integer constant or variable to indicate type of file action to perform.  If omitted, or zero (0), the Open... dialog is displayed and the user is warned if the file they choose does not exist (the file is not automatically opened).  If one (1), the Save... dialog is displayed and the user is warned if the file does exist (the file is not automatically saved).

The FILEDIALOG function displays the Windows standard file choice dialog box and returns the file chosen by the user in the file parameter.  Any existing value in the file parameter sets the default file choice presented to the user in the file choice dialog.

The extensions parameter string must contain a description followed by the file mask.  All elements in the string must be delimited by the vertical bar (|) character.  For example, the extensions string 'All Files | *.* | Clarion Source | *.CLW' defines two selections for the List Files of Type drop list.  The first extension listed in the extensions string is the default.

FILEDIALOG returns zero (0) if the user pressed the Cancel button, or one (1) if the user pressed the Ok button on the file choice dialog.

Return Data Type:  SHORT

Example:

ViewTextFile PROCEDURE

ViewQue	QUEUE	!LIST control display queue

  STRING(255)

END

FileName	STRING(64),STATIC	!Filename variable

ViewFile	FILE,DRIVER('ASCII'),NAME(FileName),PRE(Vew)

Record	  RECORD

    STRING(255)

  END

END

MDIChild1	WINDOW('View Text File'),AT(0,0,320,200),MDI,SYSTEM,HVSCROLL

  LIST,AT(0,0,320,200),USE(?L1),FROM(ViewQue),HVSCROLL

END

  CODE

  IF NOT FILEDIALOG('Choose File to View',FileName,'Text|*.TXT|Source|*.CLW',0)

    RETURN	!Return if no file chosen

  END

  OPEN(ViewFile)	!Open the file

    IF ERRORCODE() THEN RETURN.	! aborting on any error

  SET(ViewFile)	!Start at top of file

  LOOP

    NEXT(ViewFile)	!Reading each line of text

      IF ERRORCODE() THEN BREAK.	!Break loop at end of file

    ViewQue = Vew:Record	!Assign text to queue

    ADD(ViewQue)	! and add a queue entry

  END

  CLOSE(ViewFile)	!Close the file

  OPEN(MDIChild1)	! and open the window

  ACCEPT	!Allow the user to read the text and

  END	! break out of ACCEPT loop only from

! system menu close option

  FREE(ViewQue)	!Free the queue memory

  RETURN	! and return to caller


FONTDIALOG  (return chosen font)

FONTDIALOG([title] [,typeface] [,size] [,color] [,style])

FONTDIALOG	Displays the standard Windows font choice dialog box to allow the user to choose a font.

title	A string constant or variable containing the title to place on the font choice dialog.  If omitted, a default title is supplied by Windows.

typeface	A string variable to receive the name of the chosen font.

size	An integer variable to receive the size (in points) of the chosen font.

color	A LONG integer variable to receive the red, green, and blue values for the color of the chosen font in the low-order three bytes.

style	An integer variable to receive the strike weight and style of the chosen font.

The FONTDIALOG function displays the Windows standard font choice dialog box to allow the user to choose a font.  When called, any values in the parameters set the default font values presented to the user in the font choice dialog.  They also receive the user's choice when the user presses the Ok button on the dialog.

FONTDIALOG returns zero (0) if the user pressed the Cancel button, or one (1) if the user pressed the Ok button.

Return Data Type:  SHORT

Example:

MDIChild1	WINDOW('View Text File'),AT(0,0,320,200),MDI,SYSTEM,HVSCROLL

!window controls

END

Typeface	STRING(20)

FontSize	LONG

FontColor	LONG

FontStyle	LONG

  CODE

  OPEN(MDIChild1)	! and open the window

  IF FONTDIALOG('Choose Display Font',Typeface,FontSize,FontColor,FontStyle)

    SETFONT(0,Typeface,FontSize,FontColor,FontStyle)	!Set window font

  ELSE

    SETFONT(0,'Arial',12)	!Set default font

  END

  ACCEPT

    !Window handling code

  END


PRINTERDIALOG  (return chosen printer)

PRINTERDIALOG( [title] )

PRINTERDIALOG	Displays the Windows standard printer choice dialog box to allow the user to choose a file.

title	A string constant or variable containing the title to place on the file choice dialog.  If omitted, a default title is supplied by Windows.

The PRINTERDIALOG function displays the Windows standard printer choice dialog box and returns the printer chosen by the user in the PRINTER "built-in" variable in the internal library.  This sets the default printer used for the next REPORT opened.  Properties of the chosen printer may be set and queried using the runtime property assignment syntax, specifying PRINTER as the target.

PRINTERDIALOG returns zero (0) if the user pressed the Cancel button, or one (1) if the user pressed the Ok button on the printer choice dialog.

Return Data Type:  SHORT

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS,FONT('Arial',12),PRE(Rpt)

  !Report structures and controls

END	!End report declaration

  CODE

  IF NOT PRINTERDIALOG('Choose Printer')

    RETURN	!Abort if user pressed Cancel

  END

  OPEN(CustRpt)


Drag and Drop Processing

Drag-and-drop is a very powerful Windows tool that allows a user to copy or move data from one control to another (or even within the same control).  These controls may be in the same window, separate windows in the same application, or even separately executing Clarion applications.

Implementing drag-and-drop in a Clarion application involves two processes:

       _	Specifying drag host and drop target controls.

       _	Performing the data exchange when the user initiates drag-and-drop by handling the drag-and-drop events.

To specify a drag host, you place the DRAGID attribute on a LIST or REGION control with a set of "signatures" that verify valid drop targets for the data.  To specify a drop target, you place the DROPID attribute on a control to list the set of valid drag "signatures" from which the control will accept data.  Drag-and-drop operations only occur between controls with matching "signatures" in their respective DRAGID and DROPID attributes.

A successful drag-and-drop operation occurs when the user drags information from a control with the DRAGID attribute to a control with the DROPID attribute and both controls have at least one identical signature string in their respective DRAGID and DROPID attributes.  When the user initiates drag-and-drop, EVENT:Dragging is posted to the host control whenever the mouse is over a potential target control (valid or not).  EVENT:Drag is posted to the host control when the user releases the mouse button over a potential target control (valid or not).  EVENT:Drop is posted to the target control only if it is a valid match.

The DRAGID() function detects the successful drop.  The DROPID() function can also detect a successful drop, or can pass the exchanged data as a string, if its value is set by the SETDROPID procedure.  The actual data exchange between the controls can be accomplished several ways:

       _	If the two controls are in the same window, you can exchange data using local or global variables, the DROPID function can exchange the data, or you can use the Windows clipboard.

       _	If the two controls are in the same application, you can exchange data using global variables, the DROPID function can exchange the data, or you can use the Windows clipboard.

       _	If the controls are in separate Clarion applications, you must use SETDROPID to have the DROPID function exchange the data, or use the Windows clipboard.

You can copy or move the data to the target control, depending upon how you write the data exchange code.  Also, you should write the data exchange code for the most difficult coding circumstance.  Therefore, if the drag host might be an external program's control, you could pass the data through the DROPID() function (using SETDROPID), or through the Windows clipboard.  If the drag host could be a control in any window within the program, you should either pass the data through the DROPID() function, or use global variables.  Only for those instances where the drag host and drop target are always going to be in the same procedure should you use local variables.

CLIPBOARD  (return windows clipboard contents)

DRAGID  (return matching drag-and-drop signature)

DROPID  (return drag-and-drop string)

SETCLIPBOARD  (set windows clipboard contents)

SETDROPID  (set DROPID return string)


CLIPBOARD  (return windows clipboard contents)

CLIPBOARD( )

The CLIPBOARD function returns the current contents of the windows clipboard.

Return Data Type:  STRING

Example:

Que1	QUEUE

  STRING(30)

END

Que2	QUEUE

  STRING(30)

END

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?List1),FROM(Que1),DRAGID('List1')

!Allows drags, but not drops

  LIST,AT(120,120,20,20),USE(?List2),FROM(Que2),DROPID('List1','~FILE')

!Allows drops from List1, but no drags

END

  CODE

  OPEN(WinOne)

  ACCEPT

    CASE EVENT()

    OF EVENT:Drag	!When a drag event is attempted

      IF DRAGID()	! check for success

        SETCLIPBOARD(Que1)	! and setup info to pass

      END

    OF EVENT:Drop	!When drop event is successful

      Que2 = CLIPBOARD()	! get dropped info

      ADD(Que2)	! and add it to the queue

    END

  END

See Also:

SETCLIPBOARD  (set windows clipboard contents)


DRAGID  (return matching drag-and-drop signature)

DRAGID( [thread] [, control] )

DRAGID	Returns matching host and target signatures on a successful drag-and-drop operation.

thread	The label of a numeric variable to receive the thread number of the host control.  If the host control is in an external program, thread receives zero (0).

control	The label of a numeric variable to receive the field equate label of the host control.

The DRAGID function returns the matching host and target control signatures on a successful drag-and-drop operation.  If the user aborted the operation, DRAGID returns an empty string (''), otherwise it returns the first signature that matched between the two controls.

Return Data Type:  STRING

Example:

Que1	QUEUE

  STRING(30)

END

Que2	QUEUE

  STRING(30)

END

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?List1),FROM(Que1),DRAGID('List1')

!Allows drags, but not drops

  LIST,AT(120,120,20,20),USE(?List2),FROM(Que2),DROPID('List1','~FILE')

!Allows drops from List1, but no drags

END

  CODE

  OPEN(WinOne)

  ACCEPT

    CASE EVENT()

    OF EVENT:Drag	!When a drag event is attempted

      IF DRAGID()	! check for success

        SETDROPID(Que1)	! and setup info to pass

      END

    OF EVENT:Drop	!When drop event is successful

      Que2 = DROPID()	! get dropped info

      ADD(Que2)	! and add it to the queue

    END

  END

See Also:

DROPID

SETDROPID


DROPID  (return drag-and-drop string)

DROPID( [thread] [, control] )

DROPID	Returns matching host and target signatures on a successful drag-and-drop operation.

thread	The label of a numeric variable to receive the thread number of the target control.  If the target control is in an external program, thread receives zero (0).

control	The label of a numeric variable to receive the field equate label of the target control.

The DROPID function returns the matching host and target control signatures on a successful drag-and-drop operation (just as DRAGID does), or the specific string set by the SETDROPID procedure.  The DROPID function returns a comma-delimited list of filenames dragged from the Windows File Manager when '~FILE' is the DROPID attribute.

Return Data Type:  STRING

Example:

Que1	QUEUE

  STRING(30)

END

Que2	QUEUE

  STRING(30)

END

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?List1),FROM(Que1),DRAGID('List1')

!Allows drags, but not drops

  LIST,AT(120,120,20,20),USE(?List2),FROM(Que2),DROPID('List1','~FILE')

!Allows drops from List1 or the Windows File Manager, no drags

END

  CODE

  OPEN(WinOne)

  ACCEPT

    CASE EVENT()

    OF EVENT:Drag	!When a drag event is attempted

      IF DRAGID()	! check for success

        SETDROPID(Que1)	! and setup info to pass

      END

    OF EVENT:Drop	!When drop event is successful

      Que2 = DROPID()	! get dropped info, from List1 or File Manager

      ADD(Que2)	! and add it to the queue

    END

  END

See Also:

DRAGID

SETDROPID


SETCLIPBOARD  (set windows clipboard contents)

SETCLIPBOARD( string )

SETCLIPBOARD

Puts information in the Windows clipboard.

string	A string constant or variable containing the information to place in the Windows clipboard.

The SETCLIPBOARD procedure places the contents of the string into the Windows clipboard.

Example:

Que1	QUEUE

  STRING(30)

END

Que2	QUEUE

  STRING(30)

END

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?List1),FROM(Que1),DRAGID('List1')

!Allows drags, but not drops

  LIST,AT(120,120,20,20),USE(?List2),FROM(Que2),DROPID('List1','~FILE')

!Allows drops from List1, but no drags

END

  CODE

  OPEN(WinOne)

  ACCEPT

    CASE EVENT()

    OF EVENT:Drag	!When a drag event is attempted

      IF DRAGID()	! check for success

        SETCLIPBOARD(Que1)	! and setup info to pass

      END

    OF EVENT:Drop	!When drop event is successful

      Que2 = CLIPBOARD()	! get dropped info

      ADD(Que2)	! and add it to the queue

    END

  END

See Also:

CLIPBOARD


SETDROPID  (set DROPID return string)

SETDROPID( string )

SETDROPID	Sets the DROPID function's return value.

string	A string constant or variable containing the value the DROPID function will return.

The SETDROPID procedure sets the DROPID function's return value.  This allows the DROPID function to pass the data in a drag-and-drop operation.  When drag-and-drop operations are performed between separate Clarion applications, this is the mechanism to use to pass the data.

Example:

Que1	QUEUE

  STRING(30)

END

Que2	QUEUE

  STRING(30)

END

WinOne	WINDOW,AT(0,0,160,400)

  LIST,AT(120,0,20,20),USE(?List1),FROM(Que1),DRAGID('List1')

!Allows drags, but not drops

  LIST,AT(120,120,20,20),USE(?List2),FROM(Que2),DROPID('List1','~FILE')

!Allows drops from List1 or the Windows File Manager, no drags

END

  CODE

  OPEN(WinOne)

  ACCEPT

    CASE EVENT()

    OF EVENT:Drag	!When a drag event is attempted

      IF DRAGID()	! check for success

        SETDROPID(Que1)	! and setup info to pass

      END

    OF EVENT:Drop	!When drop event is successful

      Que2 = DROPID()	! get dropped info, from List1 or File Manager

      ADD(Que2)	! and add it to the queue

    END

  END

See Also:

DRAGID

DROPID


Maintaining INI Files

GETINI  (return INI file entry)

PUTINI  (set INI file entry)


GETINI  (return INI file entry)

GETINI( section ,entry [,default] [,file] )

GETINI	Returns the value for an INI file entry.

section	A string constant or variable containing the name of the portion of the INI file which contains the entry.

entry	A string constant or variable containing the name of the specific setting for which to return the value.

default	A string constant or variable containing the default value to return if the entry does not exist.  If omitted, GETINI returns an empty string.

file	A string constant or variable containing the name of the INI file to search.  If omitted, GETINI searches the WIN.INI file.

The GETINI function returns the value of an entry in a Windows-standard INI file.  A Windows-standard INI file is an ASCII text file with the following format:

[some section name]

entry=value

next entry=another value

For example, WIN.INI contains entries such as:

[intl]

sLanguage=enu

sCountry=United States

iCountry=1

The GETINI function searches the specified file for the entry within the section you specify.  It returns everything on the entry's line of text that appears to the right of the equal sign (=).

Return Data Type:  STRING

Example:

Value    STRING(30)

  CODE

  Value = GETINI('intl','sLanguage')	!Get the language entry

See Also:

PUTINI


PUTINI  (set INI file entry)

PUTINI( section ,entry ,value [,file] )

PUTINI	Sets the value for an INI file entry.

section	A string constant or variable containing the name of the portion of the INI file which contains the entry.

entry	A string constant or variable containing the name of the specific entry to set.

value	A string constant or variable containing the setting to place in the entry.

file	A string constant or variable containing the name of the INI file to search.  If omitted, PUTINI places the entry in the WIN.INI file.

The PUTINI procedure places the value into an entry in a Windows-standard INI file.  A Windows-standard INI file is an ASCII text file with the following format:

[some section name]

entry=value

next entry=another value

For example, WIN.INI contains entries such as:

[windows]

spooler=yes

load=nwpopup.exe

[intl]

sLanguage=enu

sCountry=United States

iCountry=1

The PUTINI function searches the specified file for the entry within the section you specify.  It replaces the current entry value with the value you specify.  If necessary, the section and entry are created.

Example:

  CODE

  PUTINI('MyApp','SomeSetting','Initialized')	!Add settings to WIN.INI

See Also:

GETINI


Reports

Reports in Windows

Page Overflow

Report Structure

REPORT  (declare a report structure)

AT  (set detail print area)

FONT  (set report default font)

PRE  (set report label prefix)

PREVIEW  (set report output to metafiles)

LANDSCAPE  (set page orientation)

THOUS, MM, POINTS  (set report coordinate measure)

Print Structures

BREAK  (declare group break structure)

DETAIL  (report detail line structure)

FOOTER  (page or group footer structure)

FORM  (page layout structure)

HEADER  (page or group header structure)

Print Structure Attributes

ABSOLUTE  (set fixed-position printing)

ALONE  (set to print without page header, footer, or form)

AT  (set print structure position and size)

FONT  (set print structure default font)

PAGEAFTER  (set page break after)

PAGEBEFORE  (set page break first)

USE  (set structure equate label)

WITHNEXT  (set widow elimination)

WITHPRIOR  (set orphan elimination)

Report Controls

BOX  (declare a report box control)

CHECK  (declare a report checkbox control)

CUSTOM  (declare a report .VBX custom control)

ELLIPSE  (declare a report ellipse control)

GROUP  (declare a group of report controls)

IMAGE  (declare a report graphic image control)

LINE  (declare a report line control)

LIST  (declare a report list control)

OPTION  (declare a group of report RADIO controls)

RADIO  (declare a report radio button control)

STRING  (declare a report string control)

TEXT  (declare a multi-line text control)

Control Attributes

AT  (set control position and size in report)

AVE  (set total average)

BOXED  (set report controls group border)

CAP, UPR  (set print case)

CNT  (set total count)

COLOR  (set color)

FILL  (set print fill color)

FONT  (set default font)

FORMAT  (set LIST print format)

FROM  (set report listbox data source)

HIDE  (set control non-print)

LEFT, RIGHT, CENTER, DECIMAL  (set print justification)

MAX  (set total maximum)

META  (set .VBX to print as .WMF)

MIN  (set total minimum)

PAGE  (set page total reset)

PAGENO  (set page number print)

RESET  (set total reset)

ROUND  (set round-cornered report BOX)

SUM  (set total)

TRN  (set transparent report string)

USE  (set code reference name)

Report Procedures

CLOSE  (close an active report structure)

ENDPAGE  (force page overflow)

OPEN  (open a report structure for processing)

PRINT  (print a report structure)


Reports in Windows

Clarion Database Developer for Windows reports use a page-based printing paradigm instead of a line-based paradigm.  Instead of printing each line as it's values are generated, nothing is sent to the printer until an entire page is ready to print.  This means that the "print engine" in the Clarion runtime library can do a lot of work for you, based on the attributes you specify in the REPORT structure.

Some of the things that the "print engine" in the Clarion runtime library does for you are:

     _	Prints "pre-printed" forms on each page, that are then filled in by the data

     _	Calculates totals (count, sum, average, minimum, maximum)

     _	Provides automatic page break handling, including page headers and footers

     _	Provides automatic group break handling, including group headers and footers

     _	Provides complete widow/orphan control.

This automatic functionality makes the executable code required to print a complex report very small, making your programming job easier.

Since the "print engine" is page-based, the concepts of headers and footers lose their context indicating both page positioning and print sequence, and only retain their meaning of print sequence.  Headers are printed at the beginning of a print sequence, and footers are printed at the end their actual positioning on the page is irrelevant.  For example, you could position the page footer, containing page totals, to print at the top of the page.


Page Overflow

Page Overflow occurs when the PRINT statement cannot fit a DETAIL structure on a page.  This may be due to a lack of space, or the presence of the PAGEBEFORE or PAGEAFTER attribute on a DETAIL structure.

The following steps occur during page overflow, in this sequence:

       1.	If the REPORT has a page FOOTER, it is printed at the position specified by its AT attribute.

       2.	The page counter is incremented.

       3.	If the REPORT has a FORM structure, it is printed at the position specified by its AT attribute.

       4.	If the REPORT has a page HEADER, it is printed at the position specified by its AT attribute.


Report Structure

REPORT  (declare a report structure)

AT  (set detail print area)

FONT  (set report default font)

PRE  (set report label prefix)

PREVIEW  (set report output to metafiles)

LANDSCAPE  (set page orientation)

THOUS, MM, POINTS  (set report coordinate measure)


REPORT  (declare a report structure)

label	REPORT([jobname]) AT( ) [FONT( )] [PRE( )] [LANDSCAPE] [PREVIEW]
[	 THOUS	 ]
 MM
 POINTS
[FORM
    controls
 END ]
[HEADER
    controls
 END ]
label	 DETAIL
    controls
 END
label	[BREAK( )
    group break structures
 END ]
[FOOTER
    controls
 END ]
END

REPORT	Declares the beginning of a report data structure.

label	The name by which the structure is addressed in executable code.

jobname	Names the print job for the Windows Print Manager.  If omitted, the REPORT's label is used.

AT	Specifies the size and location, relative to the top left corner of the page, of the area devoted to printing report detail.

FONT	Specifies the default font for all controls in this report.  If omitted, the Windows system font is used.

PRE	Specifies the label prefix for the report or structure.

LANDSCAPE	Specifies printing in landscape mode.  If omitted, printing defaults to portrait mode.

THOUS	Specifies thousandths of an inch as the measurement unit used for all attributes which use coordinates.

MM	Specifies millimeters as the measurement unit used for all attributes which use coordinates.

POINTS	Specifies points as the measurement unit used for all attributes which use coordinates.  There are 72 points per inch, vertically and horizontally.

PREVIEW	Specifies report output to Windows metafiles (.WMF); one file per report page.

FORM	Page layout structure defining pre-printed items on every page.

controls	Report output controls.

HEADER	Page header structure, printed at the beginning of each page.

DETAIL	Report detail structure.

BREAK	A group break structure, defining the variable which causes a group break to occur when its value changes.

group break

 structures	Group break HEADER, FOOTER, and DETAIL structures, and/or other nested BREAK structures.

FOOTER	Page footer structure, printed at the end of each page.

The REPORT statement declares the beginning of a report data structure.  A REPORT structure must be terminated with a period or END statement.  Within the REPORT, the FORM, HEADER, DETAIL, FOOTER, and BREAK structures are the components that format the output of the report.  A REPORT must be explicitly opened with the OPEN statement.

A REPORT with the PREVIEW attribute sends the report output to Windows metafiles (.WMF) containing one report page per file.  The PREVIEW attribute names a QUEUE to receive the names of the metafiles.  You can then create a window to display the report in an IMAGE control, using the QUEUE field contents (the file names) to set the IMAGE control's {PROP:text} property.  This allows the end user to view the report before printing.

Only DETAIL structures can (and must) be printed with the PRINT statement.  All other report structures (HEADER, FOOTER, and FORM) are automatically printed for you at the appropriate place in the report.

The REPORT's AT attribute defines the area of each page devoted to printing DETAIL structures.  This includes any HEADERs and FOOTERs that are contained within a BREAK structure (group headers and footers).

The FORM structure is printed on every page except pages containing DETAIL structures with the ALONE attribute.  Its format is determined once at the beginning of the report.  This makes it the logical place to design a pre-printed form template, which is filled in by the subsequent HEADER, DETAIL, and FOOTER structures.

The page HEADER and FOOTER structures are not within a BREAK structure.  They are automatically printed whenever a page break occurs.

The BREAK structure defines a group break.  It may contain its own HEADER, FOOTER, and DETAIL structures, and/or other nested BREAK structures.  It may also contain multiple DETAIL structures.  The HEADER and FOOTER structures that are within a BREAK structure are the group header and footer.  They are automatically printed when the value in a specified group break variable changes.

A REPORT data structure never defaults as the current target for runtime property assignment the way the most recently opened WINDOW or APPLICATION structure does.  Therefore, the REPORT label must be explicitly named as the target, or the SETTARGET statement must be used to make the REPORT the current target, before using runtime property assignment to a REPORT control.  Since the graphics commands draw graphics only to the current target, the SETTARGET statement must be used to make the REPORT the current target before using the graphics functions on a REPORT.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS,FONT('Arial',12),PRE(Rpt)

  FORM,AT(1000,1000,6500,9000)

    IMAGE('LOGO.BMP'),AT(0,0,1200,1200),USE(?I1)

    STRING(@n3),AT(6000,500,500,500),PAGENO

  END

  HEADER,AT(1000,1000,6500,1000)

    STRING('ABC Company'),AT(3000,500,1500,500),FONT('Arial',18)

  END

  BREAK(Pre:Key1)

    HEADER,AT(0,0,6500,1000)

      STRING('Group Head'),AT(3000,500,1500,500),FONT('Arial',18)

    END

Detail	    DETAIL,AT(0,0,6500,1000)

      STRING(@N$11.2'),AT(6000,1500,500,500),USE(Pre:F1)

    END

    FOOTER,AT(0,0,6500,1000)

      STRING('Group Total:'),AT(5500,500,1500,500)

      STRING(@N$11.2'),AT(6000,500,500,500),USE(Pre:F1),SUM,RESET(Pre:Key1)

    END

  END

  FOOTER,AT(1000,1000,6500,1000)

    STRING('Page Total:'),AT(5500,1500,1500,500)

    STRING(@N$11.2'),AT(6000,1500,500,500),USE(Pre:F1),SUM,PAGE

  END

END	!End report declaration

  CODE

  OPEN(CustReport)

  SET(DataFile)

  LOOP

    NEXT(DataFile)

      IF ERRORCODE() THEN BREAK.

    PRINT(Rpt:Detail)

  END

  CLOSE(CustReport)


AT  (set detail print area)

AT([x] [,y] [,width] [,height])

AT	Defines the position and size of the area of the page devoted to printing report detail.

x	An integer constant or constant expression that specifies the horizontal position of the top left corner of the detail area.

y	An integer constant or constant expression that specifies the vertical position of the top left corner of the detail area.

width	An integer constant or constant expression that specifies the width of the detail area.

height	An integer constant or constant expression that specifies the height of the detail area.

The AT attribute on a REPORT structure defines the position and size of the area of the page devoted to printing report detail.  This includes the area to print all DETAIL structures and any group HEADER and FOOTER structures contained within BREAK structures.

The values contained in the x, y, width, and height parameters default to dialog units unless the THOUS, MM, or POINTS attribute is also present.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the report.  This measurement is based on the font specified in the FONT attribute of the report, or the printer's system default font.

Example:

CustRpt1	REPORT,AT(1000,1000,6500,9000),THOUS	!1" margins all around for detail

! area on 8.5" x 11" paper

  !report declarations

END

CustRpt2	REPORT,AT(72,72,468,648),POINTS	!1" margins all around for detail

! area on 8.5" x 11" paper

  !report declarations

END


FONT  (set report default font)

FONT([typeface] [,size] [,color] [,style])

FONT	Specifies the default print font.

typeface	A string constant containing the name of the font.  If omitted, the printer's default font is used.

size	An integer constant containing the size (in points) of the font.  If omitted, the printer's default font size is used.

color	A LONG integer constant containing the red, green, and blue values for the color of the font in the low-order three bytes, or an EQUATE for a standard Windows color value.  If omitted, black is used.

style	An integer constant or constant expression or EQUATE specifying the strike weight and style of the font.  If omitted, the weight is normal.

The FONT attribute on a REPORT structure specifies the default print font for all controls in the REPORT.  This font is used when the control does not have a FONT attribute or its own, and the print structure it is in also has no FONT attribute.

The typeface may name any font registered in the Windows system which the printer driver supports.  This includes the TrueType fonts for most printers.  The EQUATES.CLW file contains EQUATE values for standard style values.  A style on the range zero (0) to one thousand (1000) specifies the strike weight of the font.  You may add to that values that indicate italic, underline, or strikeout text.  The following EQUATES are in EQUATES.CLW:

  FONT:thin 	EQUATE (100)

  FONT:regular 	EQUATE (400)

  FONT:bold 	EQUATE (700)

  FONT:italic 	EQUATE (01000H)

  FONT:underline 	EQUATE (02000H)

  FONT:strikeout 	EQUATE (04000H)

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS,FONT('Arial',12)

  !report declarations

END	!End report declaration


PRE  (set report label prefix)

PRE(prefix)

PRE	Provides a label prefix for structures in the report.

prefix	A string constant containing the prefix for labels within the REPORT.  Acceptable characters are alphabet letters, numerals 0 through 9, and the underscore character.  A prefix must start with an alphabet character and must not be a reserved word.

The PRE attribute on a REPORT provides a label prefix for DETAIL and BREAK structures.  It is used to distinguish between identical variable names that occur in different structures.  When referenced in executable statements, the prefix is attached to a label by a colon (Pre:Label).

Example:

Report	REPORT,PRE('Rpt')

DetailOne	  DETAIL	!Always referenced as Rpt:DetailOne

!Report controls

  END	!  in executable code

END

See Also:

Reserved Words


PREVIEW  (set report output to metafiles)

PREVIEW(queue)

PREVIEW	Specifies report output goes to Windows metafiles (.WMF) containing one report page per file.

queue	The label of a QUEUE or a field in a QUEUE to receive the names of the metafiles.

The PREVIEW attribute on a REPORT sends the report output to Windows metafiles (.WMF) containing one report page per file.  The PREVIEW attribute names a queue to receive the names of the metafiles.  The filenames are temporary filenames internally created by the Clarion library and are complete file specifications (up to 64 characters, including drive and path).  These temporary files are deleted from disk when you CLOSE the REPORT.

You can create a window to display the report in an IMAGE control, using the queue containing the file names to set the IMAGE control's {PROP:text} property.  This allows the end user to view the report before printing.  A runtime-only property, {PROP:flushpreview}, when set to ON, flushes the metafiles to the printer.

Example:

SomeReport	PROCEDURE

WMFQue	QUEUE	!Queue to contain .WMF filenames

  STRING(64)

END

NextEntry	BYTE(1)	!Queue entry counter variable

Report	REPORT,PREVIEW(WMFQue)	!Report with PREVIEW attribute

DetailOne	  DETAIL

!Report controls

  END

END

ViewReport	WINDOW('View Report'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  IMAGE(''),AT(0,0,320,180),USE(?ImageField)

  BUTTON('View Next Page'),AT(0,180,60,20),USE(?NextPage),DEFAULT

  BUTTON('Print Report'),AT(80,180,60,20),USE(?PrintReport)

  BUTTON('Exit Without Printing'),AT(160,180,60,20),USE(?ExitReport)

END

  CODE

  OPEN(Report)

  SET(SomeFile)	!Code to generate the report

  LOOP

    NEXT(SomeFile)

      IF ERRORCODE() THEN BREAK.

    PRINT(DetailOne)

  END

  ENDPAGE(Report)

  OPEN(ViewReport)	!Open report preview window

  GET(WMFQue,NextEntry)	!Get first queue entry

  ?ImageField{PROP:text} = WMFQue	!Load first report page

  ACCEPT

    CASE ACCEPTED()

    OF ?NextPage

      NextEntry += 1	!Increment entry counter

      IF NextEntry > RECORDS(WMFQue) THEN CYCLE. !Check for end of report

      GET(WMFQue,NextEntry)	!Get next queue entry

      ?ImageField{PROP:text} = WMFQue	!Load next report page

      DISPLAY	! and display it

    OF ?PrintReport

      Report{PROP:flushpreview} = ON	!Flush files to printer

      BREAK	! and exit procedure

    OF ?ExitReport

      BREAK	!Exit procedure

    END

  END

  CLOSE(ViewReport)	!Close window

  FREE(WMFQue)	!Free the queue memory

  CLOSE(Report)	!Close report (deleting all .WMF files)

  RETURN	! and return to caller


LANDSCAPE  (set page orientation)

LANDSCAPE

The LANDSCAPE attribute on a REPORT indicates the report is to print in landscape mode by default.  If the LANDSCAPE attribute is omitted, printing defaults to portrait mode.

Example:

Report	REPORT,PRE('Rpt'),LANDSCAPE	!Defaults to landscape mode

!Report structure declarations

END


THOUS, MM, POINTS  (set report coordinate measure)

THOUS
MM
POINTS

The THOUS, MM, and POINTS attributes specify the coordinate measures used to position controls on the REPORT.

THOUS specifies thousandths of an inch, MM specifies millimeters, and POINTS specifies points (there are seventy-two points per inch, both vertically and horizontally).

If all these attributes are omitted, the measurements default to dialog units.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the report.  This measurement is based on the font specified in the FONT attribute of the REPORT, or the system default font specified by Windows.


Print Structures

BREAK  (declare group break structure)

DETAIL  (report detail line structure)

FOOTER  (page or group footer structure)

FORM  (page layout structure)

HEADER  (page or group header structure)


BREAK  (declare group break structure)

label	BREAK(variable)
group break structures
END

BREAK	Declares a group break structure.

label	The name by which the structure is addressed in executable code.

variable	The variable whose change in value signals the group break.

group break

 structures	Group break HEADER, FOOTER, and DETAIL structures, and/or other nested BREAK structures.

The BREAK structure declares the variable which signals a group break when the value in the variable changes.  A BREAK structure must be terminated with a period or END statement.  It may contain its own HEADER, FOOTER, and DETAIL structures, and/or other nested BREAK structures.  Only one HEADER and FOOTER are allowed in a BREAK structure; it may contain multiple DETAIL and/or BREAK structures.

The HEADER and FOOTER structures that are within a BREAK structure are the group header and footer.  They are automatically printed when the value in the group break variable changes.

Example:

CustRpt	REPORT	!Declare customer report

Break1	  BREAK(SomeVariable)

    HEADER	!  begin group header declaration

      !report controls

    END	!  end header declaration

GroupDet	    DETAIL	!

      !report controls

    END	!  end detail declaration

    FOOTER	!  begin group footer declaration

      !report controls

    END	!  end footer declaration

  END	!  end group break declaration

END	!End report declaration


DETAIL  (report detail line structure)

label	DETAIL ,AT( ) [,FONT( )] [,ALONE] [,ABSOLUTE] [,PAGEBEFORE( )]
[,PAGEAFTER( )] [,WITHPRIOR( )] [,WITHNEXT( )] [,USE( )]
controls
END

DETAIL	Declares items to be printed as the body of the report.

label	The name by which the structure is addressed in executable code.

AT	Specifies the offset and minimum width and height of the DETAIL, relative to the size of the area specified by the REPORT's AT attribute.

FONT	Specifies the default font for all controls in this structure.  If omitted, the REPORT's FONT attribute (if present) is used, or else the printer's default font is used.

ALONE	Declares the DETAIL structure must be printed on a page without FORM, (page) HEADER, or (page) FOOTER structures.

ABSOLUTE	Declares the DETAIL prints at a fixed position relative to the page.

PAGEBEFORE	Declares the DETAIL prints at the start of a new page, after normal page overflow actions.

PAGEAFTER	Declares the DETAIL prints, and then starts a new page by activating normal page overflow actions.

WITHPRIOR	Declares the DETAIL prints on the same page as the DETAIL, group HEADER, or FOOTER that immediately precedes it.

WITHNEXT	Declares the DETAIL prints on the same page as the DETAIL, group HEADER, or FOOTER that immediately follows it.

USE	A field equate label to reference the DETAIL structure in executable code.

controls	Report output control fields.

The DETAIL structure declares items to be printed as the body of the report.  A DETAIL structure must be terminated with a period or END statement.  A REPORT may have multiple DETAIL structures.

A DETAIL structure is never automatically printed, therefore DETAIL structures are always explicitly printed by the PRINT statement.  This means that a label is required for each DETAIL you wish to PRINT.

The DETAIL structure may be printed whenever necessary.  Since you may have multiple DETAIL structures, they provide the ability to optionally print alternate print formats.  This is determined by the logic in the executable code which prints the report.

Example:

CustRpt	REPORT	!Declare customer report

  HEADER	!  begin page header declaration

    !structure elements

  END	!  end header declaration

CustDetail1	  DETAIL	!  begin detail declaration

    !structure elements

  END	!  end detail declaration

CustDetail2	  DETAIL	!  begin detail declaration

    !structure elements

  END	!  end detail declaration

END	!End report declaration

  CODE

  OPEN(CustRpt)

  SET(SomeFile)

  LOOP

    NEXT(SomeFile)

      IF ERRORCODE() THEN BREAK.

    IF SomeCondition

      PRINT(CustDetail1)

    ELSE

      PRINT(CustDetail2)

    END

  END

  CLOSE(CustRpt)

See Also:

PRINT


FOOTER  (page or group footer structure)

FOOTER ,AT( ) [,FONT( )] [,ABSOLUTE] [,PAGEBEFORE( )] [,PAGEAFTER( )]
[,WITHPRIOR( )] [,WITHNEXT( )] [,ALONE] [,USE( )]
controls
END

FOOTER	Declares a page or group footer structure.

AT	Specifies the size and location of the FOOTER.

FONT	Specifies the default font for all controls in this structure.  If omitted, the REPORT's FONT attribute (if present) is used, or else the printer's default font is used.

ABSOLUTE	Declares the FOOTER prints at a fixed position relative to the page.  Valid only on a FOOTER within a BREAK structure (page FOOTER position is always fixed).

PAGEBEFORE	Declares the FOOTER prints at the start of a new page, after normal page overflow actions.  Valid only on a FOOTER within a BREAK structure.

PAGEAFTER	Declares the FOOTER prints, and then starts a new page by activating normal page overflow actions.  Valid only on a FOOTER within a BREAK structure.

WITHPRIOR	Declares the FOOTER prints on the same page as the DETAIL, group HEADER, or FOOTER that immediately precedes it.  Valid only on a FOOTER within a BREAK structure.

WITHNEXT	Declares the FOOTER prints on the same page as the DETAIL, group HEADER, or FOOTER that immediately follows it.  Valid only on a FOOTER within a BREAK structure.

ALONE	Declares the (group) FOOTER structure must be printed on a page without FORM, (page) HEADER, or (page) FOOTER structures.

USE	A field equate label to reference the FOOTER structure in executable code.

controls	Report output control fields.

The FOOTER structure declares the output which prints at the end of each page or group.  A FOOTER structure must be terminated with a period or END statement.

A FOOTER structure that is not within a BREAK structure is a page footer.  Only one page FOOTER is allowed in a REPORT.  The page FOOTER is automatically printed whenever a page break occurs, at the page-relative position specified by its AT attribute.

The BREAK structure defines a group break.  It may contain its own HEADER, FOOTER, and DETAIL structures, and/or other nested BREAK structures.  It may also contain multiple DETAIL structures.  The HEADER and FOOTER structures that are within a BREAK structure are the group header and footer.  They are automatically printed when the value in a specified group break variable changes, at the next position available in the detail print area (specified by the REPORT's AT attribute).  Only one FOOTER is allowed in a BREAK structure.

Example:

CustRpt	REPORT	!Declare customer report

  FOOTER	!  begin page FOOTER declaration

    !report controls

  END	!  end FOOTER declaration

Break1	  BREAK(SomeVariable)

GroupDet	    DETAIL	!

      !report controls

    END	!  end detail declaration

    FOOTER	!  begin group footer declaration

      !report controls

    END	!  end footer declaration

  END	!  end group break declaration

END	!End report declaration


FORM  (page layout structure)

FORM ,AT( ) [,FONT( )] [,USE( )]
  controls
END

FORM	Declares a report structure which prints on each page.

AT	Specifies the size and location, relative to the top left corner of the page, of the FORM.

FONT	Specifies the default font for all controls in this report structure.  If omitted, the REPORT's FONT attribute (if present) is used, or else the printer's default font is used.

USE	A field equate label to reference the FORM structure in executable code.

controls	Report output control fields.

FORM declares a report structure which prints on every page of the report (except pages containing DETAIL structures with the ALONE attribute).  A FORM structure must be terminated with a period or END statement.  Only one FORM is allowed in a REPORT structure.  The FORM structure automatically prints during page overflow.

The printed output of the FORM is determined only once at the beginning of the report.  The page positioning of the FORM does not affect the page positioning of any other report structure.  Once printed, all other structures may "overwrite" the FORM.  Therefore, FORM is most aften used to design pre-printed forms which are filled in by the subsequent HEADER, DETAIL, and FOOTER structures. It may also be used to generate "watermarks" or page border graphics.

Example:

CustRpt	REPORT	!Declare customer report

  FORM

    IMAGE('LOGO.BMP'),AT(0,0,1200,1200),USE(?I1)

    STRING(@N3),AT(6000,500,500,500),PAGENO

  END

GroupDet	  DETAIL

      !report controls

  END

END	!End report declaration


HEADER  (page or group header structure)

HEADER ,AT( ) [,FONT( )] [,ABSOLUTE] [,PAGEBEFORE( )] [,PAGEAFTER( )]
[,WITHPRIOR( )] [,WITHNEXT( )] [,ALONE] [,USE( )]
controls
END

HEADER	Declares a page or group header structure.

AT	Specifies the size and location of the HEADER.

FONT	Specifies the default font for all controls in this structure.  If omitted, the REPORT's FONT attribute (if present) is used, or else the printer's default font is used.

ABSOLUTE	Declares the HEADER prints at a fixed position relative to the page.  Valid only on a HEADER within a BREAK structure (page HEADER position is always fixed).

PAGEBEFORE	Declares the HEADER prints at the start of a new page after normal page overflow actions.  Valid only on a HEADER within a BREAK structure.

PAGEAFTER	Declares the HEADER prints, and then starts a new page by activating normal page overflow actions.  Valid only on a HEADER within a BREAK structure.

WITHPRIOR	Declares the HEADER prints on the same page as the DETAIL, group HEADER, or FOOTER that immediately precedes it.  Valid only on a HEADER within a BREAK structure.

WITHNEXT	Declares the HEADER prints on the same page as the DETAIL, group HEADER, or FOOTER that immediately follows it.  Valid only on a HEADER within a BREAK structure.

ALONE	Declares the (group) HEADER structure must be printed on a page without FORM, (page) HEADER, or (page) FOOTER structures.

USE	A field equate label to reference the HEADER structure in executable code.

controls	Report output control fields.

The HEADER structure declares the output which prints at the beginning of each page or group.  A HEADER structure must be terminated with a period or END statement.

A HEADER structure that is not within a BREAK structure is a page header.  Only one page HEADER is allowed in a REPORT.  The page HEADER is automatically printed whenever a page break occurs, at the page-relative position specified by its AT attribute.

The BREAK structure defines a group break.  It may contain its own HEADER, FOOTER, and DETAIL structures, and/or other nested BREAK structures.  It may also contain multiple DETAIL structures.  The HEADER and FOOTER structures that are within a BREAK structure are the group header and footer.  They are automatically printed when the value in a specified group break variable changes, at the next position available in the detail print area (specified by the REPORT's AT attribute).  Only one HEADER is allowed in a BREAK structure.

Example:

CustRpt	REPORT	!Declare customer report

  HEADER	!  begin page header declaration

    !report controls

  END	!  end header declaration

Break1	  BREAK(SomeVariable)

    HEADER	!  begin group header declaration

      !report controls

    END	!  end header declaration

GroupDet	    DETAIL	!

      !report controls

    END	!  end detail declaration

  END	!  end group break declaration

END	!End report declaration


Print Structure Attributes

ABSOLUTE  (set fixed-position printing)

ALONE  (set to print without page header, footer, or form)

AT  (set print structure position and size)

FONT  (set print structure default font)

PAGEAFTER  (set page break after)

PAGEBEFORE  (set page break first)

USE  (set structure equate label)

WITHNEXT  (set widow elimination)

WITHPRIOR  (set orphan elimination)


ABSOLUTE  (set fixed-position printing)

ABSOLUTE

The ABSOLUTE attribute ensures that the DETAIL, or group HEADER or FOOTER structure (contained within a BREAK structure), always prints at a fixed position on the page.  When ABSOLUTE is present, the position specified by the x and y parameters of the structure's AT attribute is relative to the top left corner of the page.

Example:

CustRpt	REPORT	!Declare customer report

  HEADER	!  begin page header declaration

    !structure elements

  END	!  end header declaration

CustDetail1	  DETAIL	!  begin detail declaration

    !structure elements

  END	!  end detail declaration

CustDetail2	  DETAIL,ABSOLUTE	!  fixed position detail

    !structure elements

  END	!  end detail declaration

  FOOTER	!  begin page footer declaration

    !structure elements

  END	!  end footer

END	!  end report


ALONE  (set to print without page header, footer, or form)

ALONE

The ALONE attribute specifies that the DETAIL, or group HEADER or FOOTER structure (contained within a BREAK structure), is to be printed on the page without any FORM, page HEADER or FOOTER (not within a BREAK structure).  The normal use is for report title and grand total pages.

Example:

CustRpt	REPORT	!Declare customer report

TitlePage	  DETAIL,ALONE	!Title page detail structure

    !structure elements

  END	!  end detail declaration

CustDetail	  DETAIL	!  begin detail declaration

    !structure elements

  END	!  end detail declaration

  FOOTER	!  begin page footer declaration

    !structure elements

  END	!  end footer

END	!  end report


AT  (set print structure position and size)

AT([x] [,y] [,width] [,height])

AT	Defines the position and size at which the structure prints.

x	An integer constant or constant expression that specifies the horizontal position of the top left corner of the print structure.

y	An integer constant or constant expression that specifies the vertical position of the top left corner of the print structure.

width	An integer constant or constant expression that specifies the minumum width of the print structure.

height	An integer constant or constant expression that specifies the minimum height of the print structure.

The AT attribute on print structures performs two different functions, depending upon the structure on which it is placed.

When placed on a FORM, or page HEADER or FOOTER (not within a BREAK structure), the AT attribute defines the position and size on the page at which the structure is printed.  The position specified by the x and y parameters is relative to the top left corner of the page.

When placed on a DETAIL, or group HEADER or FOOTER (contained within a BREAK structure) the print structure is printed according to the following rules (unless the ABSOLUTE attribute is also present):

     _	The width and height parameters of the AT attribute specify the minimum print size of the structure.

     _	The structure is actually printed at the next available position within the detail print area (specified by the REPORT's AT attribute).

     _	The position specified by the x and y parameters of the structure's AT attribute is an offset from the next available print position within the detail print area.

     _	The first print structure on the page is printed at the top left corner of the detail print area (at the offset specified by its AT attribute).

     _	Next and subsequent print structures are printed relative to the ending position of the previous print structure:

_	If there is room to print the next structure beside the previous structure, it is printed there.

_	If not, it is printed below the previous.

The values contained in the x, y, width, and height parameters default to dialog units unless the THOUS, MM, or POINTS attribute is also present.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the report.  This measurement is based on the font specified in the FONT attribute of the report, or the printer's default font.

Example:

CustRpt	REPORT,AT(1000,2000,6500,7000),THOUS	!1" margins all around

  HEADER,AT(1000,1000,6500,1000)	!Page relative position

    !structure elements	!1" band across top of page

  END

CustDetail1	  DETAIL,AT(0,0,6500,1000)	!Detail relative position

    !structure elements	!1" band across page

  END

CustDetail2	  DETAIL,ABSOLUTE,AT(1000,8000,6500,1000)	!Page relative position

    !structure elements	!1" band near page bottom

  END

  FOOTER,AT(1000,9000,6500,1000)	!Page relative position

    !structure elements	!1" band across page bottom

  END

END


FONT  (set print structure default font)

FONT([typeface] [,size] [,color] [,style])

FONT	Specifies the default print font.

typeface	A string constant containing the name of the font.  If omitted, the printer's default font is used.

size	An integer constant containing the size (in points) of the font.  If omitted, the printer's default font size is used.

color	A LONG integer constant containing the red, green, and blue values for the color of the font in the low-order three bytes, or an EQUATE for a standard Windows color value.  If omitted, black is used.

style	An integer constant or constant expression or EQUATE specifying the strike weight and style of the font.  If omitted, the weight is normal.

The FONT attribute on FORM, DETAIL, HEADER, and FOOTER structures specifies the default print font for all controls in the structures that do not have a FONT attribute.

The typeface may name any font registered in the Windows system which the printer driver supports.  This includes the TrueType fonts for most printers.  The EQUATES.CLW file contains EQUATE values for standard style values.  A style on the range zero (0) to one thousand (1000) specifies the strike weight of the font.  You may add to that values that indicate italic, underline, or strikeout text.  The following EQUATES are in EQUATES.CLW:

  FONT:thin 	EQUATE (100)

  FONT:regular 	EQUATE (400)

  FONT:bold 	EQUATE (700)

  FONT:italic 	EQUATE (01000H)

  FONT:underline 	EQUATE (02000H)

  FONT:strikeout 	EQUATE (04000H)

Example:

CustRpt	REPORT,FONT('Arial',12)	!Default font: 12 point Arial

  HEADER,FONT('Arial',18,,FONT:bold)	!18 point bold Arial for the header

    !structure elements

  END

CustDetail1	  DETAIL	!Detail uses the default font

    !structure elements

  END

  FOOTER,FONT('Arial',12,00FF0000h)	!12 point Red Arial for the footer

    !structure elements

  END

END


PAGEAFTER  (set page break after)

PAGEAFTER( [newpage] )

PAGEAFTER	Specifies the structure is printed, then initiates page overflow.

newpage	An integer constant or constant expression that specifies the page number to print on the next page.  If omitted, the current page number is incremented during page overflow.

The PAGEAFTER attribute specifies that the DETAIL, or group HEADER or FOOTER structure (contained within a BREAK structure), initiates page overflow after it is printed.  This means that the print structure on which the PAGEAFTER attribute is present is printed, followed by the page FOOTER, and then the FORM and page HEADER.

The newpage parameter, if present, resets automatic page numbering at the number specified.

Example:

CustRpt	REPORT	!Declare customer report

  HEADER	!Page header

    !structure elements

  END	!

  BREAK(SomeVariable)

    HEADER 	!Group Header

      !structure elements

    END	!

CustDetail	    DETAIL 	!Line item detail

      !structure elements

    END	!

    FOOTER,PAGEAFTER	!Group Footer, initiates page overflow

      !structure elements

    END	!

  END	!  end group break structure

  FOOTER	!

      !structure elements

  END	!  end footer

END	!  end report


PAGEBEFORE  (set page break first)

PAGEBEFORE( [newpage] )

PAGEBEFORE	Specifies the structure is printed on a new page, after page overflow.

newpage	An integer constant or constant expression that specifies the page number to print on the new page.  If omitted, the current page number is incremented during page overflow.

The PAGEBEFORE attribute specifies that the DETAIL, or group HEADER or FOOTER structure (contained within a BREAK structure), is printed on a new page, after page overflow.  This means that first, the page FOOTER is printed, then the FORM and page HEADER.  The print structure on which the PAGEBEFORE attribute is present is printed only after these page overflow actions are complete.

The newpage parameter, if present, resets automatic page numbering at the number specified.

Example:

CustRpt	REPORT	!Declare customer report

  HEADER	!Page header

    !structure elements

  END	!

  BREAK(SomeVariable)

    HEADER,PAGERBEFORE	!Group Header, initiates page overflow

      !structure elements

    END	!

CustDetail	    DETAIL 	!Line item detail

      !structure elements

    END	!

    FOOTER,PAGEAFTER	!Group Footer

      !structure elements

    END	!

  END	!  end group break structure

  FOOTER	!

      !structure elements

  END	!  end footer

END	!  end report


USE  (set structure equate label)

USE( label [,number] )

USE	Specifies a field equate label for the structure.

label	A field equate label to reference the structure in executable code.

number	An integer constant that specifies the number the compiler equates to the field equate label for the structure.

The USE attribute on a FORM, DETAIL, HEADER, or FOOTER structure specifies a field equate label for the structure.  This provides a mechanism for executable source code statements to reference the structure.

The print structures in a REPORT are treated just as controls in a WINDOW; they are automatically assigned positive numbers by the compiler.

The USE attribute's number parameter allows you to specify the actual field number the compiler assigns to the structure.  This number also is used as the new starting point for subsequent field equate numbering for all structures and controls without a number parameter in their USE attribute.  Subsequent structures or controls without a number parameter in their USE attribute are incremented (or decremented) relative to the last number assigned.

Example:

BuildRpt	PROCEDURE

CustRpt	REPORT

  HEADER,USE(?PageHeader)	!Page header

    !structure elements

  END

CustDetail	  DETAIL,USE(?Detail)	!Line item detail

    !structure elements

  END	!

  FOOTER,USE(?PageFooter)	!Page footer

    !structure elements

  END

END

  CODE

  PrintRpt(CustRpt,?Detail)	!Pass report and detail equate to print proc

PrintRpt	PROCEDURE(RptToPrint,DetailNumber)

  CODE

  OPEN(RptToPrint)	!Open passed report

  PRINT(RptToPrint,DetailNumber)	!Print its detail

  CLOSE(RptToPrint)	!Close passed report


WITHNEXT  (set widow elimination)

WITHNEXT( [siblings] )

WITHNEXT	Specifies the structure is always printed on the same page as print structures PRINTed immediately following it.

siblings	An integer constant or constant expression that specifies the number of following print structures to print on the same page.  If omitted, the default value is one.

The WITHNEXT attribute specifies that the DETAIL, or group HEADER or FOOTER structure (contained within a BREAK structure), is always printed on the same page as the specified number of print structures PRINTed immediately following it.  This ensures that the structure is never printed on a page by itself, eliminating "widow" print structures.  A "widow" print structure is defined as a group header, or first detail item in a related group of items, printed on the preceding page, separated from the rest of its related items.

The siblings parameter, if present, sets the number of following print structures that must be printed on the same page with the structure.  To be counted, the following print structures must come from the same, or nested, BREAK structures.  They must be related items.  Any print structures not within the same, or nested, BREAK structures are printed but not counted as part of the required number of siblings.

Example:

CustRpt	REPORT	!Declare customer report

  BREAK(SomeVariable)	!Group Break structure

    HEADER,WITHNEXT(2)	!Always print with 2 siblings

      !structure elements

    END	!

CustDetail	    DETAIL,WITHNEXT()	 	!Always print with 1 sibling

      !structure elements

    END	!

    FOOTER

      !structure elements

    END	!

  END	!  end footer

END	!  end report


WITHPRIOR  (set orphan elimination)

WITHPRIOR( [siblings] )

WITHPRIOR	Specifies the structure is always printed on the same page as print structures PRINTed immediately preceding it.

siblings	An integer constant or constant expression that specifies the number of preceding print structures to print on the same page.  If omitted, the default value is one.

The WITHPRIOR attribute specifies that the DETAIL, or group HEADER or FOOTER structure (contained within a BREAK structure), is always printed on the same page as the specified number of print structures PRINTed immediately preceding it.  This ensures that the structure is never printed on a page by itself, eliminating "orphan" print structures.  An "orphan" print structure is defined as a group footer, or last detail item in a related group of items, that is printed on the following page separated from the rest of its related items.

The siblings parameter, if present, sets the number of preceding print structures that must be printed on the same page with the structure.  To be counted, the preceding print structures must come from the same, or nested, BREAK structures.  They must be related items.  Any print structures not within the same, or nested, BREAK structures are printed, but not counted as part of the required number of siblings.

Example:

CustRpt	REPORT	!Declare customer report

  BREAK(SomeVariable)	!Group Break structure

    HEADER 	!Group Header

      !structure elements

    END	!

CustDetail	    DETAIL,WITHPRIOR()	 	!Always print with 1 sibling

      !structure elements

    END	!

    FOOTER,WITHPRIOR(2)	!Always print with 2 siblings

      !structure elements

    END	!

  END	!  end footer

END	!  end report


Report Controls

BOX  (declare a report box control)

CHECK  (declare a report checkbox control)

CUSTOM  (declare a report .VBX custom control)

ELLIPSE  (declare a report ellipse control)

GROUP  (declare a group of report controls)

IMAGE  (declare a report graphic image control)

LINE  (declare a report line control)

LIST  (declare a report list control)

OPTION  (declare a group of report RADIO controls)

RADIO  (declare a report radio button control)

STRING  (declare a report string control)

TEXT  (declare a multi-line text control)


BOX  (declare a report box control)

BOX ,AT( ) [,USE( )] [,COLOR( )] [,FILL( )] [,ROUND] [,HIDE]

BOX	Places a rectangular box in the REPORT.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

USE	Specifies a field equate label for the control.

COLOR	Specifies the color for the border of the control.  If omitted, the border is black.

FILL	Specifies the fill color for the control.  If omitted, the box is not filled with color.

ROUND	Specifies the box corners are rounded.  If omitted, the corners are square.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

The BOX control places a rectangular box in the REPORT at the position and size specified by its AT attribute, relative to the top left corner of the print structure containing the BOX.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    BOX,AT(0,0,20,20),USE(?B1)	!Unfilled, black border

    BOX,AT(20,20,20,20),ROUND	!Unfilled, rounded, black border

    BOX,AT(40,40,20,20),FILL(COLOR:ACTIVEBORDER)

!Filled, black border

    BOX,AT(60,60,20,20),COLOR(COLOR:ACTIVEBORDER)

!Unfilled, active border color border

  END

END


CHECK  (declare a report checkbox control)

CHECK(text) ,AT( ) [,USE( )] [,FONT( )] [,HIDE] [,DISABLE] [,	LEFT	 ]
 	RIGHT

CHECK	Places a check box in the REPORT.

text	A string constant containing the text to display for the check box.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

USE	The label of a numeric variable containing the value of the check box, zero (0 = OFF) or one (1 = ON).

FONT	Specifies the display font for the control.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

DISABLE	Specifies the control appears dimmed in the REPORT.

LEFT	Specifies that the text appears to the left of the check box.

RIGHT	Specifies that the text appears to the right of the check box (the default position).

The CHECK control places a check box in the REPORT at the position and size specified by its AT attribute, relative to the top left corner of the print structure containing the CHECK.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    CHECK('1'),AT(0,0,20,20),USE(C1)

    CHECK('2'),AT(20,80,20,20),USE(C2),LEFT

    CHECK('3'),AT(0,100,20,20),USE(C3),FONT('Arial',12)

  END

END


CUSTOM  (declare a report .VBX custom control)

CUSTOM(text) ,AT( ) [,CLASS( )] [,USE( )] [,DISABLE] [,FONT( )] [,META]
[,property( value )]

CUSTOM	Places a Visual Basic .VBX control on the REPORT.

text	A string constant containing the title for the control.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the library.

CLASS	Specifies the .VBX filename and type of control.

USE	The label of a variable to supply the value of the control.

DISABLE	Specifies the control appears dimmed in the REPORT.

FONT	Specifies the display font for the control.

META	Specifies printing as a Windows metafile (.WMF).

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

property	A string constant containing the name of a custom property setting for the control.

value	A string constant containing the property value number or EQUATE for the property.

The CUSTOM control places a Visual Basic .VBX control in the report at the position and size specified by its AT attribute.

The property attribute allows you to specify any additional property settings the .VBX control may require.  These are properties that need to be set for the .VBX control to properly function, and are not standard Clarion properties (such as AT or USE).  The custom control should only receive values for these properties that are defined for that control.  Valid properties and values for those properties would be defined in the custom control's documentation.  You may have multiple property attributes on a single CUSTOM control.

Example:

Report	REPORT

DetailOne	  DETAIL

    CUSTOM,AT(0,0,120,320),CLASS('graph.vbx','graph'),'graphstyle'('2')

  END

END


ELLIPSE  (declare a report ellipse control)

ELLIPSE ,AT( ) [,USE( )] [,COLOR( )] [,FILL( )] [,HIDE]

ELLIPSE	Places a "circular" figure in the REPORT.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

USE	Specifies a field equate label for the control.

COLOR	Specifies the color for the border of the ellipse.  If omitted, the ellipse has a black border.

FILL	Specifies the fill color for the control.  If omitted, the ellipse is not filled with color.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

The ELLIPSE control places a "circular" figure in the REPORT at the position and size specified by its AT attribute.  The ellipse is drawn inside a "bounding box" defined by the x, y, width, and height parameters of its AT attribute.  The x and y parameters specify the starting point, relative to the top left corner of the print structure containing it, and the width and height parameters specify the horizontal and vertical size of the "bounding box."

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    ELLIPSE,AT(0,0,20,20)	!Unfilled, black border

    ELLIPSE,AT(0,20,20,20),USE(?Ellipse1),DISABLE

!Unfilled, black border, dimmed

    ELLIPSE,AT(20,20,20,20),ROUND	!Unfilled, rounded, black border

    ELLIPSE,AT(40,40,20,20),FILL(COLOR:ACTIVEBORDER)

!Filled, black border

    ELLIPSE,AT(60,60,20,20),COLOR(COLOR:ACTIVEBORDER)

!Unfilled, active border color border

  END

END


GROUP  (declare a group of report controls)

GROUP(text) ,AT( ) [,USE( )] [,FONT( )] [,BOXED] [,HIDE]
  controls
END

GROUP	Declares a group of controls that may be referenced as one entity.

text	A string constant containing the prompt for the group of controls.  The text is printed only if the BOXED attribute is also present.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

USE	Specifies a field equate label for the control.

FONT	Specifies the display font for the control and the default for all the controls in the GROUP.

BOXED	Specifies a single-track border around the group of controls with the text at the top of the border.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

controls	Control declarations that may be referenced as the GROUP.

The GROUP control declares a group of controls that may be referenced as one entity.  This control allows you to design reports that look the same on paper as on the screen.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    GROUP('Group 1'),USE(!G1),AT(80,0,20,20),BOXED

      STRING(@S8),AT(80,0,20,20),USE(E5)

      STRING(@S8),AT(100,0,20,20),USE(E6)

    END

    GROUP('Group 2'),USE(?G2),FONT('Arial',12)

      STRING(@S8),AT(120,0,20,20),USE(E7)

      STRING(@S8),AT(140,0,20,20),USE(E8)

    END

  END

END


IMAGE  (declare a report graphic image control)

IMAGE(file) ,AT( ) [,USE( )] [,HIDE]

IMAGE	Places a graphic image on the REPORT.

file	A string constant containing the name of the file to print.  The file is linked into the .EXE as a resource.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

USE	Specifies a field equate label for the control.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

The IMAGE control places a graphic image on the REPORT at the position and size specified by its AT attribute.  This may be a bitmap (.BMP), icon (.ICO), or windows metafile (.WMF).

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    IMAGE('PIC.BMP'),AT(0,0,20,20),USE(?I1)

    IMAGE('PIC.WMF'),AT(40,0,20,20),USE(?I2)

    IMAGE('PIC.ICO'),AT(60,0,20,20),USE(?I3)

  END

END


LINE  (declare a report line control)

LINE ,AT( ) [,USE( )] [,COLOR( )] [,HIDE]

LINE	Places a straight line in the REPORT.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

USE	Specifies a field equate label for the control.

COLOR	Specifies the color for the line.  If omitted, the color is black.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

The LINE control places a straight line in the REPORT at the position and size specified by its AT attribute.

The x and y parameters of the AT attribute specify the starting point of the line.  The width and height parameters of the AT attribute specify the horizontal and vertical distance to the end point of the line.  If these are both positive numbers, the line slopes to the right and down from its starting point.  If the width parameter is negative, the line slopes left; if the height parameter is negative, the line slopes left.  If either the width or height parameter is zero, the line is horizontal or vertical.

Width	Height	Result

    	positive	positive	right and down from start point

negative	positive	left and down from start point

positive	negative	right and up from start point

negative	negative	left and up from start point

zero	positive	vertical, down from start point

zero	negative	vertical, up from start point

positive	zero	horizontal, right from start point

negative	zero	horizontal, left from start point

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    LINE,AT(60,60,20,20),COLOR(COLOR:ACTIVEBORDER)  !Border color

    LINE,AT(480,180,20,20),USE(?L2)

  END

END


LIST  (declare a report list control)

LIST ,FROM( ) ,AT( ) [,FONT( )] [,USE( )] [,HIDE]
[,	 FORMAT( )	 ]
 LEFT
 RIGHT
 CENTER
 DECIMAL

LIST	Places the current item of a list of data items in the REPORT.

FROM	Specifies the origin of the data displayed in the list.

AT	Specifies the size and location of the control.  If omitted, the runtime library chooses a value.

FONT	Specifies the display font for the control.

USE	Specifies a field equate label for the control.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

FORMAT	Specifies the print format of the data.

LEFT	Specifies that the data is left justified within the LIST.

RIGHT	Specifies that the data is right justified within the LIST.

CENTER	Specifies that the data is centered within the LIST.

DECIMAL	Specifies that the data is aligned on the decimal point within the LIST.

The LIST control places the current item of a list of data items in the REPORT at the position and size specified by its AT attribute.  LIST is valid only in a DETAIL structure.  Its purpose is to allow the report format to duplicate the screen appearance of the LIST's FORMAT setting.  When the first instance of the DETAIL structure containing the LIST is printed, any headers in the FORMAT attribute are printed along with the current FROM attribute entry.  When the last DETAIL structure containing the LIST is printed, the LIST footers are printed along with the current FROM attribute entry.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    LIST,AT(80,0,20,20),USE(?L1),FROM(Q),FORMAT('5C~List~15L~Box~'),COLUMN

  END

END


OPTION  (declare a group of report RADIO controls)

OPTION(text) ,AT( ) [,USE( )] [,BOXED]  [,HIDE]
  radios
END

OPTION	Prints a group of RADIO controls.

text	A string constant containing the prompt for the group of controls.  The text is printed only if the BOXED attribute is also present.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

USE	The label of a string variable containing the value of the RADIO selected by the user.

BOXED	Specifies a single-track border around the RADIO controls with the text at the top of the border.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

radios	Multiple RADIO control declarations.

The OPTION control prints a group of RADIO controls that display a list of choices.  The multiple RADIO controls in the OPTION structure define the choices.  The selected choice is identified by a filled RADIO button.

No RADIO button selected is a valid option.  This occurs only when the OPTION structure's USE variable does not contain a value duplicated in a RADIO text parameter.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    OPTION('Option'),USE(OptVar),AT(80,0,20,20),BOXED

      RADIO('Radio 1'),AT(80,0,20,20),USE(?R1)

      RADIO('Radio 2'),AT(100,0,20,20),USE(?R2)

    END

  END

END


RADIO  (declare a report radio button control)

RADIO(text) ,AT( ) [,FONT( )] [,	 LEFT	 ] [,USE( )]  [,HIDE]
 RIGHT

RADIO	Places a radio button in the REPORT.

text	A string constant containing the text to display for the radio button.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

FONT	Specifies the display font for the control.

LEFT	Specifies that the text appears to the left of the radio button.

RIGHT	Specifies that the text appears to the right of the radio button (the default position).

USE	Specifies a field equate label for the control.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

The RADIO control places a radio button in the REPORT at the position and size specified by its AT attribute.  A RADIO control may only be placed within an OPTION control.  The RADIO selected by the user (the value in the OPTION's USE variable) is displayed as a filled RADIO button.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    OPTION('Option'),USE(OptVar),AT(80,0,20,20),BOXED

      RADIO('Radio 1'),AT(80,0,20,20),USE(?R1)

      RADIO('Radio 2'),AT(100,0,20,20),USE(?R2)

      RADIO('Radio 3'),AT(100,0,20,20),USE(?R2),LEFT

    END

  END

END


STRING  (declare a report string control)

STRING(text),AT( ) [,FONT( )] [,HIDE] [,TRN] [,USE( )]
[,	 LEFT	 ] [,	 PAGENO	 ]
 RIGHT	 CNT	[,RESET( )/PAGE]
 CENTER	 SUM	[,RESET( )/PAGE]
 DECIMAL	 AVE	[,RESET( )/PAGE]
 MIN	[,RESET( )/PAGE]
 MAX	[,RESET( )/PAGE]

STRING	Places the text in the REPORT.

text	A string constant containing the text to display, or a display picture token to format the variable specified in the USE attribute.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

FONT	Specifies the font used to display the text.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

TRN	Specifies the text or USE variable characters transparently print over the background.

USE	Specifies a variable whose contents are printed in the format of the picture token declared instead of string text.

LEFT	Specifies that the text is left justified within the area specified by the AT attribute.

RIGHT	Specifies that the text is right justified within the area specified by the AT attribute.

CENTER	Specifies that the text is centered within the area specified by the AT attribute.

DECIMAL	Specifies that the text is aligned on the decimal point within the area specified by the AT attribute.

PAGENO	Specifies the current page number is printed in the format of the picture token declared instead of string text.

CNT	Specifies the number of details printed is printed in the format of the picture token declared instead of string text.

SUM	Specifies the sum of the USE variable is printed in the format of the picture token declared instead of string text.

AVE	Specifies the average value of the USE variable is printed in the format of the picture token declared instead of string text.

MIN	Specifies the mimimum value of the USE variable is printed in the format of the picture token declared instead of string text.

MAX	Specifies the maximum value of the USE variable is printed in the format of the picture token declared instead of string text.

RESET	Specifies the CNT, SUM, AVE, MIN, or MAX is reset when the specified group break occurs.

PAGE	Specifies the CNT, SUM, AVE, MIN, or MAX is reset to zero when the page break occurs.

The STRING control places the text in the REPORT at the position and size specified by its AT attribute.  If the text parameter is a picture token instead of a string constant or variable, the contents of the variable named in the USE attribute are formatted to that display picture, at the position and size specified by the AT attribute.

A STRING with the TRN attribute prints characters transparently, without obliterating the background.  This means only the dots required to create each character are printed.  This allows the STRING to be placed directly on top of an IMAGE without destroying the background picture.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

  BREAK(Pre:Key1)

    HEADER,AT(0,0,6500,1000)

      STRING('Group Head'),AT(3000,500,1500,500),FONT('Arial',18)

    END

Detail	    DETAIL,AT(0,0,6500,1000)

      STRING(@N$11.2'),AT(6000,1500,500,500),USE(Pre:F1)

    END

    FOOTER,AT(0,0,6500,1000)

      STRING('Group Total:'),AT(5500,500,1500,500)

      STRING(@N$11.2'),AT(6000,500,500,500),USE(Pre:F1),SUM,RESET(Pre:Key1)

    END

  END

END


TEXT  (declare a multi-line text control)

TEXT ,AT( ) [,USE( )] ,FONT( )] [,	 CAP	 ] [,	 LEFT	 ]  [,HIDE]
 UPR	 	 RIGHT
 CENTER

TEXT	Places a multi-line print field in the REPORT.

AT	Specifies the size and location of the control.  If omitted, default values are selected by the runtime library.

USE	The label of the variable that contains the value to print.

FONT	Specifies the display font for the control.

UPR / CAP	Specifies all upper case or proper name capitalization (First Letter Of Each Word Capitalized).

LEFT	Specifies that the text is left justified within the area specified by the AT attribute.

RIGHT	Specifies that the text is right justified within the area specified by the AT attribute.

CENTER	Specifies that the text is centered within the area specified by the AT attribute.

HIDE	Specifies the control is not printed unless UNHIDE is used to allow it to print.

The TEXT control places a multi-line print field in the REPORT at the position and size specified by its AT attribute.  The variable specified in the USE attribute contains the data to print.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

Detail	  DETAIL,AT(0,0,6500,1000)

    TEXT,AT(0,0,40,40),USE(E1)

    TEXT,AT(100,0,40,40),USE(E6),FONT('Arial',12)

    TEXT,AT(120,0,40,40),USE(E7),CAP

    TEXT,AT(140,0,40,40),USE(E8),UPR

    TEXT,AT(160,0,40,40),USE(E9),LEFT

    TEXT,AT(180,0,40,40),USE(E10),RIGHT

    TEXT,AT(200,0,40,40),USE(E11),CENTER

  END

END


Control Attributes

AT  (set control position and size in report)

AVE  (set total average)

BOXED  (set report controls group border)

CAP, UPR  (set print case)

CNT  (set total count)

COLOR  (set color)

FILL  (set print fill color)

FONT  (set default font)

FORMAT  (set LIST print format)

FROM  (set report listbox data source)

HIDE  (set control non-print)

LEFT, RIGHT, CENTER, DECIMAL  (set print justification)

MAX  (set total maximum)

META  (set .VBX to print as .WMF)

MIN  (set total minimum)

PAGE  (set page total reset)

PAGENO  (set page number print)

RESET  (set total reset)

ROUND  (set round-cornered report BOX)

SUM  (set total)

TRN  (set transparent report string)

USE  (set code reference name)


AT  (set control position and size in report)

AT([x] [,y] [,width] [,height])

AT	Defines the position and size of a control.

x	An integer constant or constant expression that specifies the initial horizontal position of the top left corner of the control, relative to the top left corner of the print structure containing it.  If omitted, the runtime library provides a default value.

y	An integer constant or constant expression that specifies the initial vertical position of the top left corner of the control, relative to the top left corner of the print structure containing it.  If omitted, the runtime library provides a default value.

width	An integer constant or constant expression that specifies the width of the control.  If omitted, the runtime library provides a default value.

height	An integer constant or constant expression that specifies the height of the control.  If omitted, the runtime library provides a default value.

The AT attribute defines the position and size of a control, relative to the top left corner of the print structure containing it.  If any parameter is omitted, the runtime library provides a default value.

The values contained in the x, y, width, and height parameters default to dialog units unless the THOUS, MM, or POINTS attribute is also present.  Dialog units are defined as one-quarter the average character width by one-eighth the average character height.  The size of a dialog unit is dependent upon the size of the default font for the report.  This measurement is based on the font specified in the FONT attribute of the REPORT, or the printer's default font.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS	!AT specifies detail print area

Detail	  DETAIL,AT(0,0,6500,1000)	!At specifies band size and

! relative position offset from

! last printed detail

    STRING('String Constant'),AT(500,500,1500,500)

!AT specifies control size and

! offset within the detail band

  END

END


AVE  (set total average)

AVE

The AVE attribute specifies the average (arithmetic mean) of the STRING controls' USE variable is printed.

     _	An AVE field in a DETAIL structure is calculated each time the DETAIL structure containing the control is PRINTed.

     _	An AVE field in a group FOOTER structure is calculated each time any DETAIL structure in the BREAK structure containing the control is PRINTed.

     _	An AVE field in a page FOOTER structure is calculated each time any DETAIL structure in any BREAK structure is PRINTed.

     _	An AVE field in a HEADER is meaningless, since no DETAIL structures will have been printed at the time the HEADER is printed.

The average is reset only if the RESET or PAGE attribute is also specified.  The STRING control using this attribute would usually be placed in a group or page FOOTER.


BOXED  (set report controls group border)

BOXED

The BOXED attribute specifies a single-track border around a GROUP or OPTION structure.  The text parameter of the GROUP or OPTION control appears in a gap at the top of the border box.  If BOXED is omitted, the text parameter of the GROUP or OPTION control is not printed.


CAP, UPR  (set print case)

CAP
UPR

The CAP and UPR attributes specify the automatic case of text printed in a TEXT control.  UPR specifies all upper case;  CAP specifies "Proper Name Capitalization," where the first letter of each word is capitalized and all other letters are lower case.


CNT  (set total count)

CNT

The CNT attribute specifies an automatic count of the number of times DETAIL structures have been printed.

     _	A CNT field in a DETAIL structure is incremented each time the DETAIL structure containing the control is PRINTed.  This provides a "running" count.

     _	A CNT field in a group FOOTER structure is incremented each time any DETAIL structure in the BREAK structure containing the control is PRINTed.  This provides a total of the number of DETAIL structures printed in the group.

     _	A CNT field in a page FOOTER structure is incremented each time any DETAIL structure in any BREAK structure is PRINTed.  This provides a total of the number of DETAIL structures printed on the page (or report).

     _	A CNT field in a HEADER is meaningless, since no DETAIL structures will have been printed at the time the HEADER is printed.

The CNT tally is reset only if the RESET or PAGE attribute is also specified.


COLOR  (set color)

COLOR(rgb)

COLOR	Specifies the print color of a BOX, LINE, or ELLIPSE control.

rgb	A LONG or ULONG integer constant containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2), or an EQUATE for a standard Windows color value.

The COLOR attribute specifies the print color of a BOX, LINE, or ELLIPSE control.  On a BOX or ELLIPSE, the color specified is the color used for the border.  EQUATEs for Windows' standard colors are contained in the EQUATES.CLW file.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    ELLIPSE,AT(60,60,200,200),COLOR(COLOR:ACTIVEBORDER)	!Color EQUATE

    BOX,AT(360,60,200,200),COLOR(00FF0000h)	!Pure Red

  END

END


FILL  (set print fill color)

FILL(rgb)

FILL	Specifies the print fill color of a BOX or ELLIPSE control.

rgb	A LONG or ULONG integer constant containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.

The FILL attribute specifies the print fill color of a BOX or ELLIPSE control.  If omitted, the control is not filled with color.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    ELLIPSE,AT(60,60,200,200),FILL(COLOR:ACTIVEBORDER)	!Color EQUATE

    BOX,AT(360,60,200,200),FILL(00FF0000h)	!Pure Red

  END

END


FONT  (set default font)

FONT([typeface] [,size] [,color] [,style])

FONT	Specifies the print font for the control.

typeface	A string constant containing the name of the font.  If omitted, the print structure's FONT attribute is used (if present), or the REPORT structure's FONT attribute is used (if present), or else the printer's default font is used.

size	An integer constant containing the size (in points) of the font.  If omitted, the printer's default font size is used.

color	A LONG integer constant containing the red, green, and blue values for the color of the font in the low-order three bytes, or an EQUATE for a standard Windows color value.  If omitted, black is used.

style	An integer constant, constant expression, or EQUATE specifying the strike weight and style of the font.  If omitted, the weight is normal.

The FONT attribute specifies the print font for the control, overriding any FONT specified on the REPORT or print structure.

The typeface may name any font registered in the Windows system which the printer driver supports.  This includes the TrueType fonts for most printers.  The EQUATES.CLW file contains EQUATE values for standard style values.  A style on the range zero (0) to one thousand (1000) specifies the strike weight of the font.  You may add to that values that indicate italic, underline, or strikeout text.  The following EQUATES are in EQUATES.CLW:

  FONT:thin 	EQUATE (100)

  FONT:regular 	EQUATE (400)

  FONT:bold 	EQUATE (700)

  FONT:italic 	EQUATE (01000H)

  FONT:underline 	EQUATE (02000H)

  FONT:strikeout 	EQUATE (04000H)

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    STRING('Text'),AT(0,0),FONT('Arial',14,00FF0000h)

    STRING('Text'),AT(160,160),FONT('Arial',12,,FONT:italic)

  END

END


FORMAT  (set LIST print format)

FORMAT(format string)

FORMAT	Specifies the print format for the data.

format

 string	A string constant specifying the column or multi-column print format.

The FORMAT attribute specifies the print format for the data in the LIST control.  The format string contains the information for single or multi-column formatting of the data.

The format string contains "field-specifiers" with a one-to-one mapping to the fields of the QUEUE or GROUP, and/or "region-specifiers" that group together one or more fields to be printed as a unit.  Only the fields in the QUEUE for which there are "field-specifiers" are printed.  This means that, if there are two fields specified in the format string and three fields in the QUEUE, only the two specified in the format string are printed in the LIST control.

The following describes the components allowed in a format string:

"Field-specifier" format:  width  justification  [(indent)]  [modifiers]

width	An integer defining the width of the field in dialog units unless overridden by the THOUS, MM, or POINTS attribute.  Required.

justification	A single capital letter (L , R , C , or D) that specifies Left, Right, Center, Or decimal justification.  One is required.

indent	An optional integer, enclosed in parentheses, that specifies an indent from the justification.  This is measured in dialog units and may be negative.  With left (L) justification, indent defines a left margin; with  right (R) or decimal (D), it defines a right margin; and with center (C), it defines an indent from the center of the field.

modifiers	Optional special characters (listed below) to modify the display format of the field.  Multiple modifiers may be used on one field.

     _ 	An underscore underlines the field.

     | 	A vertical bar places a vertical line to the right of the field.

     / 	A slash causes the next field to appear on a new line (can only be used within a "region-specifier").

     ~header~ [justification] [(indent)]

A header string enclosed in tildes, followed by optional justification and/or indent, displays the header at the top of the list.   The header uses the same justification and indent as the field, if not specifically overidden.

     @picture@

A picture token formats the field for display.  The trailing @ is required to define the end of the picture token, so that picture tokens like @N12~Kr~ may be used in the format string without creating ambiguity.

     #number#

A number enclosed in pound signs (#) indicates the QUEUE field to display.  Following fields in the format string without an explicit #number# are taken from the fields following the #number# field.  For example, #2# on the first field in the format string indicates starting with the second field in the QUEUE, skipping the first.  If the number of fields specified in the format string are >= the number of fields in the QUEUE, the last fields "wrap around" to use the first fields in the QUEUE.

"Region-specifier" format:  [ multiple field-specifiers ] [modifiers]

A "region-specifier" differs from a "field-specifier" in that it relates to groups of fields.  The required square brackets ( [ ] ) that enclose the fields cause them to be treated as a single display unit.

modifiers	The "region-specifier" modifiers act on the entire group of fields.

     _ 	An underscore underlines the group of fields.

     | 	A vertical bar places a vertical line to the right of the group of fields.

     ~header~ [justification] [(indent)]

A header string enclosed in tildes, followed by optional justification and/or indent, displays the header at the top of the list.   The header is centered unless a justification is defined.

Example:

TD     	QUEUE,AUTO

FName  	  STRING(20)

LName  	  STRING(20)

Init  	  STRING(4)

Wage  	  REAL

   	END

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    LIST,AT(0,34,366,146),FORMAT(''),FROM(TD),USE(?Show)

  END

END

  CODE

  OPEN(CustRpt)

  SETTARGET(CustRpt)

  IF SomeCondition

    ?Show{PROP:format} = '80C~First Name~80C~Last Name~16L~Intls~60R~Wage~|'

  ELSE

    ?Show{PROP:format} = '80C~First Name~80C~Last Name~16L~Intls~60D(10)~Wage~|'

  END


FROM  (set report listbox data source)

FROM(source)

FROM	Specifies the source of the data printed in a LIST control.

source	The label of a QUEUE, or any variable (normally a GROUP) containing the data items to print in the LIST.

The FROM attribute specifies the source of the data elements printed in a LIST control.  The data elements are formatted for display according to the information in the FORMAT attribute.

If the label of a QUEUE is specified as the source, all fields in the QUEUE are printed.  If the label of one field in a QUEUE is specified as the source, only that field is printed.  Only the current QUEUE entry in the queue's data buffer is printed in the LIST.

If a string constant or variable is specified as the source, the entire string is printed in the LIST.

Example:

TD     	QUEUE,AUTO

FName  	  STRING(20)

LName  	  STRING(20)

Init  	  STRING(4)

Wage  	  REAL

   	END

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    LIST,AT(0,34,366,146),FORMAT('80L80L16L60L'),FROM(TD),USE(?Show1)

    LIST,AT(0,200,100,146),FORMAT('80L'),FROM(Fname),USE(?Show2)

  END

END


HIDE  (set control non-print)

HIDE

The HIDE attribute specifies the control does not print unless the UNHIDE statement is used to allow it to print.


LEFT, RIGHT, CENTER, DECIMAL  (set print justification)

LEFT( [indent] )
RIGHT( [indent] )
CENTER( [indent] )
DECIMAL( [indent] )

indent	An integer constant specifying the amount of margin left after justification.  This is in dialog units unless overridden by the THOUS, MM, or POINTS attribute.

The LEFT, RIGHT, CENTER, and DECIMAL attributes specify the justification of data printed.  LEFT specifies left justification, RIGHT specifies right justification, CENTER specifies centered text, and DECIMAL specifies numeric data aligned on the decimal point.

The indent parameter on the CENTER attribute specifies an offset from the center.  On the DECIMAL attribute, indent specifies the position of the decimal point.

The following controls allow LEFT or RIGHT only (without an indent parameter):

CHECK

GROUP

OPTION

RADIO

The following controls allow LEFT(indent), RIGHT(indent), CENTER(indent), or DECIMAL(indent):

LIST

STRING

The TEXT control allows LEFT, RIGHT, and CENTER (without an indent parameter).

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

CustDetail	  DETAIL,AT(0,0,6500,1000)

    LIST,AT(0,20,100,146),FORMAT('800L'),FROM(Fname),USE(?Show2),LEFT(100)

  END

END


MAX  (set total maximum)

MAX

The MAX attribute specifies printing the maximum value the STRING control's USE variable has contained so far.

     _	A MAX field in a DETAIL structure is evaluated each time the DETAIL structure containing the control is PRINTed.  This provides a "running" maximum value.

     _	A MAX field in a group FOOTER structure is evaluated each time any DETAIL structure in the BREAK structure containing the control is PRINTed.  This provides the maximum value of the variable in the group.

     _	A MAX field in a page FOOTER structure is evaluated each time any DETAIL structure in any BREAK structure is PRINTed.  This the maximum value of the variable in the page (or report to date).

     _	A MAX field in a HEADER is meaningless, since no DETAIL structures will have been printed at the time the HEADER is printed.

The MAX value is reset only if the RESET or PAGE attribute is also specified.


META  (set .VBX to print as .WMF)

META

The META attribute specifies printing a .VBX custom control as a .WMF windows metafile.  This will print the control as a graphic image on the report.


MIN  (set total minimum)

MIN

The MIN attribute specifies printing the minimum value the STRING control's USE variable has contained so far.

     _	A MIN field in a DETAIL structure is evaluated each time the DETAIL structure containing the control is PRINTed.  This provides a "running" minimum value.

     _	A MIN field in a group FOOTER structure is evaluated each time any DETAIL structure in the BREAK structure containing the control is PRINTed.  This provides the minimum value of the variable in the group.

     _	A MIN field in a page FOOTER structure is evaluated each time any DETAIL structure in any BREAK structure is PRINTed.  This the minimum value of the variable in the page (or report to date).

     _	A MIN field in a HEADER is meaningless, since no DETAIL structures will have been printed at the time the HEADER is printed.

The MIN value is reset only if the RESET or PAGE attribute is also specified.


PAGE  (set page total reset)

PAGE

The PAGE attribute specifies the CNT, SUM, AVE, MIN, or MAX is reset to zero (0) when page break occurs.


PAGENO  (set page number print)

PAGENO

The PAGENO attribute specifies the STRING control prints the current page number.


RESET  (set total reset)

RESET(breaklevel)

RESET	Resets the CNT, SUM, AVE, MIN, or MAX to zero (0).

breaklevel	The label of a BREAK structure.

The RESET attribute specifies the group break at which the CNT, SUM, AVE, MIN, or MAX is reset to zero (0).

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

  BREAK(Pre:Key1)

    HEADER,AT(0,0,6500,1000)

      STRING('Group Head'),AT(3000,500,1500,500),FONT('Arial',18)

    END

Detail	    DETAIL,AT(0,0,6500,1000)

      STRING(@N$11.2'),AT(6000,1500,500,500),USE(Pre:F1)

    END

    FOOTER,AT(0,0,6500,1000)

      STRING('Group Total:'),AT(5500,500,1500,500)

      STRING(@N$11.2'),AT(6000,500,500,500),USE(Pre:F1),SUM,RESET(Pre:Key1)

    END

  END

END


ROUND  (set round-cornered report BOX)

ROUND

The ROUND attribute specifies a BOX control with rounded corners.


SUM  (set total)

SUM

The SUM attribute specifies printing the sum of the values contained in the STRING control's USE variable.

     _	A SUM field in a DETAIL structure is incremented each time the DETAIL structure containing the control is PRINTed.  This provides a "running" total.

     _	A SUM field in a group FOOTER structure is incremented each time any DETAIL structure in the BREAK structure containing the control is PRINTed.  This provides the sum of the value contained in the variable in the group.

     _	A SUM field in a page FOOTER structure is incremented each time any DETAIL structure in any BREAK structure is PRINTed.  This the sum of the values contained in the variable in the page.

     _	A SUM field in a HEADER is meaningless, since no DETAIL structures will have been printed at the time the HEADER is printed.

The SUM value is reset only if the RESET or PAGE attribute is also specified.


TRN  (set transparent report string)

TRN

The TRN attribute on a STRING control specifies the characters print transparently, without obliterating the background over which the STRING is placed.  Only the dots required to create each character are printed.  This allows the STRING to be placed directly on top of an IMAGE without destroying the background picture.

Example:

WinOne	WINDOW,AT(0,0,160,400)

  IMAGE('PIC.BMP'),USE(?I1),FULL	!Full window image

  STRING('String Constant'),AT(10,0,20,20),USE(?S1),TRN

!Transparent string on image

END


USE  (set code reference name)

USE( variable )

USE	Specifies the data to print in the control or a field equate label with which to reference the control.

variable	The label of a variable or a field equate label.

The USE attribute specifies the variable containing the data to print in the control or a field equate label with which to reference the control.

Example:

CustRpt	REPORT,AT(1000,1000,6500,9000),THOUS

Detail	  DETAIL,AT(0,0,6500,1000)

    STRING('Group Total:'),AT(5500,500,1500,500),USE(?Constant)

!Field equate label

    STRING(@N$11.2'),AT(6000,1500,500,500),USE(Pre:F1)	!USE variable

  END

END


Report Procedures

CLOSE  (close an active report structure)

ENDPAGE  (force page overflow)

OPEN  (open a report structure for processing)

PRINT  (print a report structure)


CLOSE  (close an active report structure)

CLOSE(report)

CLOSE	Deactivates a REPORT structure.

report	The label of a REPORT structure.

CLOSE prints the last page FOOTER, (unless the last structure printed has the ALONE attribute), and closes the REPORT.  If the REPORT has the PREVIEW attribute, all the temporary metafiles are deleted.

RETURN from a procedure in which a REPORT is opened automatically closes the REPORT.

Example:

CLOSE(CustRpt)	!Close the report


ENDPAGE  (force page overflow)

ENDPAGE(report)

ENDPAGE	Forces page overflow.

report	The label of a REPORT structure.

The ENDPAGE statement initiates page overflow and flushes the print engine's print structure buffer.  If the REPORT has the PREVIEW attribute, this has the effect of ensuring that the entire report is available to view.

Example:

SomeReport	PROCEDURE

WMFQue	QUEUE	!Queue to contain .WMF filenames

  STRING(64)

END

NextEntry	BYTE(1)	!Queue entry counter variable

Report	REPORT,PREVIEW(WMFQue)	!Report with PREVIEW attribute

DetailOne	  DETAIL

!Report controls

  END

END

ViewReport	WINDOW('View Report'),AT(0,0,320,200),MDI,MAX,HVSCROLL

  IMAGE(''),AT(0,0,320,180),USE(?ImageField)

  BUTTON('View Next Page'),AT(0,180,60,20),USE(?NextPage),DEFAULT

  BUTTON('Print Report'),AT(80,180,60,20),USE(?PrintReport)

  BUTTON('Exit Without Printing'),AT(160,180,60,20),USE(?ExitReport)

END

  CODE

  OPEN(Report)

  SET(SomeFile)	!Code to generate the report

  LOOP

    NEXT(SomeFile)

      IF ERRORCODE() THEN BREAK.

    PRINT(DetailOne)

  END

  ENDPAGE(Report)	!Flush the buffer

  OPEN(ViewReport)	!Open report preview window

  GET(WMFQue,NextEntry)	!Get first queue entry

  ?ImageField{PROP:text} = WMFQue	!Load first report page

  ACCEPT

    CASE ACCEPTED()

    OF ?NextPage

      NextEntry += 1	!Increment entry counter

      IF NextEntry > RECORDS(WMFQue) THEN CYCLE. !Check for end of report

      GET(WMFQue,NextEntry)	!Get next queue entry

      ?ImageField{PROP:text} = WMFQue	!Load next report page

      DISPLAY	! and display it

    OF ?PrintReport

      Report{PROP:flushpreview} = ON	!Flush files to printer

      BREAK	! and exit procedure

    OF ?ExitReport

      BREAK	!Exit procedure

    END

  END

  CLOSE(ViewReport)	!Close window

  FREE(WMFQue)	!Free the queue memory

  CLOSE(Report)	!Close report (deleting all .WMF files)

  RETURN	! and return to caller

See Also:

Page Overflow

PREVIEW


OPEN  (open a report structure for processing)

OPEN(report)

OPEN	Activates a REPORT structure.

report	The label of a REPORT structure.

OPEN activates a REPORT structure.  You must OPEN a REPORT before any of the structures may be printed.

Example:

OPEN(CustRpt)	!Open the report


PRINT  (print a report structure)

PRINT(	 structure	 )
 report ,number

PRINT	Prints a DETAIL structure.

structure	The label of a DETAIL structure.

report	The label of a REPORT structure.

number	The number or EQUATE label of a DETAIL structure to print (only valid with a report parameter).

The PRINT statement prints a DETAIL structure to the destination specified by the user in the Windows Print... dialog.  PRINT automatically activates group breaks and page overflow as needed.

Example:

PRINT(OrderDtl)	!Print order detail line

PRINT(CustRpt,?CustDtl)	!Print order detail line

See Also:

Page Overflow

BREAK


Graphics Commands

Graphics Overview

The Current Target

Graphics Coordinates

Graphics Procedures

ARC  (draw an arc of an ellipse)

BLANK  (erase graphics)

BOX  (draw a rectangle)

CHORD  (draw a section of an ellipse)

ELLIPSE  (draw an ellipse)

IMAGE  (draw a graphic image)

LINE  (draw a straight line)

PIE  (draw a pie chart)

POLYGON  (draw a multi-sided figure)

ROUNDBOX  (draw a box with round corners)

SETPENCOLOR  (set line draw color)

SETPENSTYLE  (set line draw style)

SETPENWIDTH  (set line draw thickness)

SHOW  (write to screen)

TYPE  (write string to screen)

Graphics Functions

PENCOLOR  (return line draw color)

PENSTYLE  (return line draw style)

PENWIDTH  (return line draw thickness)


Graphics Overview

Clarion supplies the set of "graphics primitives" defined in this chapter to allow drawing in windows and reports.

Controls always appear on top of any graphics drawn to the window.  This means the graphics appear to underly any controls in the window, so they don't get in the way of the controls the user needs to access.


The Current Target

Graphics are always drawn to the "current target."  Unless overridden with SETTARGET, the "current target" is the last window opened (and not yet closed) on the current execution thread and is the window with input focus.  Drawings in a window are persistent redraws are handled automatically by the runtime library.

Graphics can also be drawn to a report.  To do this, SETTARGET must be used to nominate the REPORT as the "current target."

Every window or report has its own current pen width, color, and style.  Therefore, to consistently use the same pen (which does not use the default settings) across multiple windows, the SETPENWIDTH, SETPENCOLOR, and SETPENSTYLE statements should be issued for each window.


Graphics Coordinates

The graphics coordinate system starts with the x,y coordinates (0,0) at the top left corner of the window.  The coordinates are specified in dialog units unless overridden by the THOUS, MM, or POINTS attributes.  A dialog unit is defined as one-quarter the average character width and one-eighth the average character height of the font specified in the window's FONT attribute (or the system font, if no FONT attribute is specified on the window).

Graphics drawn outside the currently visible portion of the window will appear if the window is scrolled.  The size of the virtual screen over which the window may scroll automatically expands to include all graphics drawn to the window.  Drawing graphics outside the visible portion of the window automatically causes the scroll bars to appear (if the window has the HSCROLL, VSCROLL, or HVSCROLL attribute).


Graphics Procedures

ARC  (draw an arc of an ellipse)

BLANK  (erase graphics)

BOX  (draw a rectangle)

CHORD  (draw a section of an ellipse)

ELLIPSE  (draw an ellipse)

IMAGE  (draw a graphic image)

LINE  (draw a straight line)

PIE  (draw a pie chart)

POLYGON  (draw a multi-sided figure)

ROUNDBOX  (draw a box with round corners)

SETPENCOLOR  (set line draw color)

SETPENSTYLE  (set line draw style)

SETPENWIDTH  (set line draw thickness)

SHOW  (write to screen)

TYPE  (write string to screen)


ARC  (draw an arc of an ellipse)

ARC( x ,y ,width ,height ,startangle ,endangle )

ARC	Draws an arc of an ellipse on the current window or report.

x	An integer expression that specifies the horizontal position of the starting point.

y	An integer expression that specifies the vertical position of the starting point.

width	An integer expression that specifies the width.

height	An integer expression that specifies the height.

startangle	An integer expression that specifies the starting point of the arc, in tenths of degrees (10 = 1 degree) measured counter-clockwise from three o'clock.

endangle	An integer expression that specifies the ending point of the arc, in tenths of degrees (10 = 1 degree) measured counter-clockwise from three o'clock.

The ARC procedure places an arc of an ellipse on the current window or report.

The ellipse is drawn inside a "bounding box" defined by the x, y, width, and height parameters.  The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the "bounding box."

The startangle and endangle parameters specify what sector of the ellipse will be drawn, as an arc.

The border color is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text.  The border width is the current width set by SETPENWIDTH; the default width is one pixel.  The border style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  ARC(100,50,100,50,0,900)	!Draw 90 degree arc from 3 to 12 o'clock, as

! the top-right quadrant of ellipse


BLANK  (erase graphics)

BLANK( [x] [,y] [,width] [,height] )

BLANK	Erases all graphics written to the specified area of the current window or report.

x	An integer expression that specifies the horizontal position of the starting point.  If omitted, the default is zero.

y	An integer expression that specifies the vertical position of the starting point.  If omitted, the default is zero.

width	An integer expression that specifies the width.  If omitted, the default is the width of the window.

height	An integer expression that specifies the height.  If omitted, the default is the height of the window.

The BLANK procedure erases all graphics written to the specified area of the current window or report.  Controls are not erased.  BLANK with no parameters erases the entire window or report.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  ARC(100,50,100,50,0,900)	!Draw arc

  BLANK	!The erase it


BOX  (draw a rectangle)

BOX( x ,y ,width ,height [,fill] )

BOX	Draws a rectangular box on the current window or report.

x	An integer expression that specifies the horizontal position of the starting point.

y	An integer expression that specifies the vertical position of the starting point.

width	An integer expression that specifies the width.

height	An integer expression that specifies the height.

fill	A LONG or ULONG integer constant, constant EQUATE, or variable containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.

The BOX procedure places a rectangular box on the current window or report.  The position and size of the box are specified by x, y, width, and height parameters.

The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the box.  The box extends to the right and down from its starting point.

The border color is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text.  The border width is the current width set by SETPENWIDTH; the default width is one pixel.  The border style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  BOX(100,50,100,50,00FF0000h)	!Red box


CHORD  (draw a section of an ellipse)

CHORD( x ,y ,width ,height ,startangle ,endangle [,fill] )

CHORD	Draws a closed sector of an ellipse on the current window or report.

x	An integer expression that specifies the horizontal position of the starting point.

y	An integer expression that specifies the vertical position of the starting point.

width	An integer expression that specifies the width.

height	An integer expression that specifies the height.

startangle	An integer expression that specifies the starting point of the chord, in tenths of degrees (10 = 1 degree) measured counter-clockwise from three o'clock.

endangle	An integer expression that specifies the ending point of the chord, in tenths of degrees (10 = 1 degree) measured counter-clockwise from three o'clock.

fill	A LONG or ULONG integer constant, constant EQUATE, or variable containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.

The CHORD procedure places a closed sector of an ellipse on the current window or report.  The ellipse is drawn inside a "bounding box" defined by the x, y, width, and height parameters.  The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the "bounding box."  The startangle and endangle parameters specify what sector of the ellipse will be drawn, as an arc.  The two end points of the arc are also connected with a straight line.

The border color is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text.  The border width is the current width set by SETPENWIDTH; the default width is one pixel.  The border style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  CHORD(100,50,100,50,0,900,00FF0000h)	!Red 90 degree crescent


ELLIPSE  (draw an ellipse)

ELLIPSE( x ,y ,width ,height [,fill] )

ELLIPSE	Draws an ellipse on the current window or report.

x	An integer expression that specifies the horizontal position of the starting point.

y	An integer expression that specifies the vertical position of the starting point.

width	An integer expression that specifies the width.

height	An integer expression that specifies the height.

fill	A LONG or ULONG integer constant, constant EQUATE, or variable containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.

The ELLIPSE procedure places an ellipse on the current window or report.  The ellipse is drawn inside a "bounding box" defined by the x, y, width, and height parameters.  The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the "bounding box."

The border color is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text.  The border width is the current width set by SETPENWIDTH; the default width is one pixel.  The border style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  ELLIPSE(100,50,100,50,00FF0000h)	!Red ellipse


IMAGE  (draw a graphic image)

IMAGE( x ,y ,width ,height ,filename )

IMAGE	Places a graphic image on the current window or report.

x	An integer expression that specifies the horizontal position of the starting point.

y	An integer expression that specifies the vertical position of the starting point.

width	An integer expression that specifies the width.  This may be a negative number.

height	An integer expression that specifies the height.  This may be a negative number.

filename	A string constant or variable containing the name of the file to display.

The IMAGE procedure places a graphic image on the current window or report at the position and size specified by its x, y, width, and height parameters.  This may be a bitmap (.BMP), icon (.ICO), or Windows metafile (.WMF).

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  IMAGE(100,50,100,50,'LOGO.BMP')	!Draw graphic image


LINE  (draw a straight line)

LINE( x ,y ,width ,height )

LINE	Draws a straight line on the current window or report.

x	An integer expression specifying the horizontal position of the starting point.

y	An integer expression specifying the vertical position of the starting point.

width	An integer expression specifying the width.  This may be a negative number.

height	An integer expression specifying the height.  This may be a negative number.

The LINE procedure places a straight line on the current window or report.  The starting position, slope, and length of the line are specified by x, y, width, and height parameters.  The x and y parameters specify the starting point of the line.  The width and height parameters specify the horizontal and vertical distance to the end point of the line.  If these are both positive numbers, the line slopes to the right and down from its starting point.  If the width parameter is negative, the line slopes left; if the height parameter is negative, the line slopes left.  If either the width or height parameter is zero, the line is horizontal or vertical.

Width	Height	Result

    	positive	positive	right and down from start point

negative	positive	left and down from start point

positive	negative	right and up from start point

negative	negative	left and up from start point

zero	positive	vertical, down from start point

zero	negative	vertical, up from start point

positive	zero	horizontal, right from start point

negative	zero	horizontal, left from start point

The line color is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text.  The width is the current width set by SETPENWIDTH; the default width is one pixel.  The line's style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  LINE(100,50,100,50)	!Draw line


PIE  (draw a pie chart)

PIE( x ,y ,width ,height ,slices ,colors [,depth] [,wholevalue] [,startangle] )

PIE	Draws a pie chart on the current window or report.

x	An integer expression that specifies the horizontal position of the starting point.

y	An integer expression that specifies the vertical position of the starting point.

width	An integer expression that specifies the width.

height	An integer expression that specifies the height.

slices	An array of numeric values that specify the relative size of each slice of the pie.

colors	An integer array that specifies the fill color for each slice.

depth	An integer expression that specifies the depth of the three-dimensional pie chart.  If omitted, the chart is two-dimensional.

wholevalue	A numeric constant or variable that specifies the total value required to create a complete pie chart.  If omitted, the sum of the slices array is used.

startangle	A numeric constant or variable that specifies the starting point of the first slice of the pie, measured as a fraction of the wholevalue.  If omitted (or zero), the first slice starts at the twelve o'clock position.

The PIE procedure creates a pie chart on the current window or report.  The pie (an ellipse) is drawn inside a "bounding box" defined by the x, y, width, and height parameters.  The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the "bounding box."

The slices of the pie are created clockwise from the startangle parameter as a fraction of the wholevalue.  Supplying a wholevalue parameter that is greater than the sum of all the slices array elements creates a pie chart with a piece missing.

The color of the lines is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text.  The width of the lines is the current width set by SETPENWIDTH; the default width is one pixel.  The line style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

SliceSize	BYTE,DIM(4)

SliceColor	LONG,DIM(4)

  CODE

  SliceSize[1] = 90

  SliceColor[1] = 0	!Black

  SliceSize[2] = 90

  SliceColor[2] = 00FF0000h	!Red

  SliceSize[3] = 90

  SliceColor[3] = 0000FF00h	!Green

  SliceSize[4] = 90

  SliceColor[4] = 000000FFh	!Blue

  OPEN(MDIChild)

  PIE(100,50,100,50,SliceSize,SliceColor)

!Draw pie chart containing

! four equal slices, starting at 12 o'clock

! drawn counter-clockwise - Black, Red, Green, and Blue


POLYGON  (draw a multi-sided figure)

POLYGON( array [,fill] )

POLYGON	Draws a multi-sided figure on the current window or report.

array	An array of integers that specify the x and y coordinates of each "corner point" of the polygon.

fill	A LONG or ULONG integer constant, constant EQUATE, or variable containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.

The POLYGON procedure places a multi-sided figure on the current window or report.  The polygon is always closed.

The array parameter contains the x and y coordinates of each "corner point" of the polygon.  The polygon will have as many corner points as the total number of array elements divided by two.  For each corner point in turn, its x coordinate is taken from the odd-numbered array element and the y coordinate from the immediately following even-numbered element.

The border color is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text.  The border width is the current width set by SETPENWIDTH; the default width is one pixel.  The line's style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

Corners	SHORT,DIM(8)

  CODE

  Corners[1] = 0	!1st x position

  Corners[2] = 90	!1st y position

  Corners[3] = 90	!2nd x position

  Corners[4] = 190	!2nd y position

  Corners[5] = 100	!3rd x position

  Corners[6] = 200	!3rd y position

  Corners[7] = 50	!4th x position

  Corners[8] = 60	!4th y position

  OPEN(MDIChild)

  POLYGON(Corners,000000FFh)	!Blue filled four-sided polygon


ROUNDBOX  (draw a box with round corners)

ROUNDBOX( x ,y ,width ,height [,fill] )

ROUNDBOX	Draws a rectangular box with rounded corners on the current window or report.

x	An integer expression that specifies the horizontal position of the starting point.

y	An integer expression that specifies the vertical position of the starting point.

width	An integer expression that specifies the width.

height	An integer expression that specifies the height.

fill	A LONG or ULONG integer constant, constant EQUATE, or variable containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.

The ROUNDBOX procedure places a rectangular box with rounded corners on the current window or report.  The position and size of the box are specified by x, y, width, and height parameters.

The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the box.  The box extends to the right and down from its starting point.

The border color is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text.  The border width is the current width set by SETPENWIDTH; the default width is one pixel.  The border style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  ROUNDBOX(100,50,100,50,00FF0000h)	!Red round-cornered box


SETPENCOLOR  (set line draw color)

SETPENCOLOR( [color] )

SETPENCOLOR	Sets the current pen color.

color	A LONG or ULONG integer constant, constant EQUATE, or variable containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.  If omitted, the Windows system color for window text is set.

The SETPENCOLOR procedure sets the current pen color for use by all graphics procedures.  The default color is the Windows system color for window text.

Every window has its own current pen color.  Therefore, to consistently use the same pen (which does not use the default color setting) across multiple windows, the SETPENCOLOR statement should be issued for each window.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  SETPENCOLOR(000000FFh)	!Set blue pen color

  ROUNDBOX(100,50,100,50,00FF0000h)	!Red round-cornered box with blue border


SETPENSTYLE  (set line draw style)

SETPENSTYLE( [style] )

SETPENSTYLE	Sets the current pen style.

style	An integer constant, constant EQUATE, or variable that specifies the pen's style.  If omitted, a solid line is set.

The SETPENSTYLE procedure sets the current line draw style for use by all graphics procedures.  The default is a solid line.

Every window has its own current pen style.  Therefore, to consistently use the same pen (which does not use the default style setting) across multiple windows, the SETPENSTYLE statement should be issued for each window.

EQUATE statements for the pen styles are contained in the EQUATES.CLW file.  The following list is a representative sample of these (see EQUATES.CLW for the complete list):

PEN:solid	Solid line

PEN:dash	Dashed line

PEN:dot	Dotted line

PEN:dashdot	Mixed dashes and dots

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  SETPENCOLOR(000000FFh)	!Set blue pen color

  SETPENSTYLE(PEN:dash)	!Set dashes for line style

  ROUNDBOX(100,50,100,50,00FF0000h)	!Red round-cornered box with blue dashed border


SETPENWIDTH  (set line draw thickness)

SETPENWIDTH( [width] )

SETPENWIDTH	Sets the current pen width.

width	An integer expression that specifies the pen's thickness, measured in dialog units unless overridden by the THOUSINCH, MILLIMETERS, or POINTS attributes.  If omitted, the default (one pixel) is set.

The SETPENWIDTH procedure sets the current line draw thickness for use by all graphics procedures.  The default is one pixel, which may be set with a width of zero (0).

Every window has its own current pen width.  Therefore, to consistently use the same pen (which does not use the default width setting) across multiple windows, the SETPENWIDTH statement should be issued for each window.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  SETPENCOLOR(000000FFh)	!Set blue pen color

  SETPENSTYLE(PEN:dash)	!Set dashes for line style

  SETPENWIDTH(2)	!Set two dialog unit thickness

  BOX(100,50,100,50,00FF0000h)	!Red box with thick blue dashed border


SHOW  (write to screen)

SHOW( x ,y ,string )

SHOW	Writes a string to the current window or report.

x	An integer expression that specifies the horizontal position of the starting point, in dialog units.

y	An integer expression that specifies the vertical position of the starting point, in dialog units.

string	A string constant, variable, or expression containing the formatted text to place on the current window or report.

SHOW writes the string text to the current window or report.  The font used is the current font for the window or report.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  SHOW(100,100,FORMAT(TODAY(),@D3))	!Display the date

  SHOW(20,20,'Press Any Key to Continue')	!Display a message


TYPE  (write string to screen)

TYPE(string)

TYPE	Writes a string to the current window or report.

string	A string constant, variable, or expression.

TYPE writes a string to the current window or report.  The string appears on the window or report at the current cursor position, and "wraps around" if the string length extends beyond the right edge.  The font used is the current font for the window or report.  The SHOW statement may be used to position the cursor before output from TYPE.

Example:

MDIChild	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild)

  TYPE(Cus:Notes)	!Type the notes field

See Also:

SETCURSOR


Graphics Functions

PENCOLOR  (return line draw color)

PENSTYLE  (return line draw style)

PENWIDTH  (return line draw thickness)


PENCOLOR  (return line draw color)

PENCOLOR( )

The PENCOLOR function returns the current pen color set by SETPENCOLOR.

Return Data Type:  LONG

Example:

Proc1	PROCEDURE

MDIChild1	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild1)

  SETPENCOLOR(000000FFh)	!Set blue pen color

  Proc2	!Call another procedure

Proc2	PROCEDURE

MDIChild2	WINDOW('Child Two'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

ColorNow	LONG

  CODE

  ColorNow = PENCOLOR()	!Get current pen color

  OPEN(MDIChild2)

  SETPENCOLOR(ColorNow)	!Set same pen color

  SETPENSTYLE(PEN:dash)	!Set dashes for line style

  SETPENWIDTH(2)	!Set two dialog unit thickness

  BOX(100,50,100,50,00FF0000h)	!Red box with thick blue dashed border


PENSTYLE  (return line draw style)

PENSTYLE( )

The PENSTYLE function returns the current line draw style set by SETPENSTYLE.

EQUATE statements for the pen styles are contained in the EQUATES.CLW file.  The following list is a representative sample of these (see EQUATES.CLW for the complete list):

PEN:solid	Solid line

PEN:dash	Dashed line

PEN:dot	Dotted line

PEN:dashdot	Mixed dashes and dots

Return Data Type:  LONG

Example:

Proc1	PROCEDURE

MDIChild1	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild1)

  SETPENCOLOR(000000FFh)	!Set blue pen color

  SETPENSTYLE(PEN:dash)	!Set dashes for line style

  Proc2	!Call another procedure

Proc2	PROCEDURE

MDIChild2	WINDOW('Child Two'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

ColorNow	LONG

StyleNow	LONG

  CODE

  ColorNow = PENCOLOR()	!Get current pen color

  StyleNow = PENSTYLE()	!Get current pen style

  OPEN(MDIChild2)

  SETPENCOLOR(ColorNow)	!Set same pen color

  SETPENSTYLE(StyleNow)	!Set same pen style

  SETPENWIDTH(2)	!Set two dialog unit thickness

  BOX(100,50,100,50,00FF0000h)	!Red box with thick blue dashed border


PENWIDTH  (return line draw thickness)

PENWIDTH( )

The PENWIDTH function returns the current line draw thickness set by SETPENWIDTH.  The return value is dialog units unless overridden by the THOUS, MM, or POINTS attributes.

Return Data Type:  LONG

Example:

Proc1	PROCEDURE

MDIChild1	WINDOW('Child One'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

  CODE

  OPEN(MDIChild1)

  SETPENCOLOR(000000FFh)	!Set blue pen color

  SETPENSTYLE(PEN:dash)	!Set dashes for line style

  SETPENWIDTH(2)	!Set two dialog unit thickness

  Proc2	!Call another procedure

Proc2	PROCEDURE

MDIChild2	WINDOW('Child Two'),AT(0,0,320,200),MDI,MAX,HVSCROLL

!window controls

END

ColorNow	LONG

StyleNow	LONG

WidthNow	LONG

  CODE

  ColorNow = PENCOLOR()	!Get current pen color

  StyleNow = PENSTYLE()	!Get current pen style

  WidthNow = PENWIDTH()	!Get current pen width

  OPEN(MDIChild2)

  SETPENCOLOR(ColorNow)	!Set same pen color

  SETPENSTYLE(StyleNow)	!Set same pen style

  SETPENWIDTH(WidthNow)	!Set same pen width

  BOX(100,50,100,50,00FF0000h)	!Red box with thick blue dashed border


Data Files

Data File Structures

FILE  (declare a data file structure)

CREATE  (allow data file creation)

DRIVER  (specify data file type)

NAME  (set filename)

ENCRYPT  (encrypt data file)

OWNER  (declare password for data encryption)

RECLAIM  (reuse deleted record space)

PRE  (set file label prefix)

BINDABLE  (set runtime expression string RECORD variables)

File Structure Statements

INDEX  (declare static file access index)

KEY  (declare dynamic file access index)

MEMO  (declare a text field)

RECORD  (declare record structure)

INDEX, KEY and MEMO Attributes

BINARY  (MEMO contains binary data)

DUP  (allow duplicate KEY entries)

NOCASE  (case insensitive KEY or INDEX)

OPT  (exclude null KEY or INDEX entries)

NAME  (set external name)

File Commands

BUILD  (build keys and indexes)

CLOSE  (close a data file)

COPY  (copy a data file)

CREATE  (create an empty data file)

EMPTY  (empty a data file)

FLUSH  (flush DOS buffers)

LOCK  (exclusive file access)

OPEN  (open a data file)

PACK  (remove deleted records)

REMOVE  (erase the data file)

RENAME  (change data file directory name)

SHARE  (open a data file)

STREAM  (enable DOS buffering)

UNLOCK  (unlock a locked data file)

Record Access Commands

ADD  (add a new file record)

APPEND  (add a new file record)

DELETE  (delete a file record)

GET  (read a file record by direct access)

HOLD  (exclusive file record access)

NEXT  (read next file record in sequence)

NOMEMO  (read file record without reading memo)

PREVIOUS  (read previous file record in sequence)

PUT  (write record back to file)

RELEASE  (release a held file record)

REGET  (reget file record)

RESET  (reset file record sequence position)

SET  (initiate sequential file processing)

SKIP  (bypass file records in sequence)

WATCH  (automatic file concurrency check)

File Functions

BOF  (beginning of file function)

BYTES  (return size in bytes)

DUPLICATE  (check for duplicate key entries)

EOF  (end of file function)

POINTER  (return relative record position)

POSITION  (return file record sequence position)

RECORDS  (return number of file or key records)

SEND  (send message to file driver)

Transaction Processing

COMMIT  (terminate successful transaction)

LOGOUT  (begin transaction)

ROLLBACK  (terminate unsuccessful transaction)

Null Data Processing

NULL  (return null file field)

SETNULL  (set file field null)

SETNONNULL  (set file field non-null)


Data File Structures

FILE  (declare a data file structure)

CREATE  (allow data file creation)

DRIVER  (specify data file type)

NAME  (set filename)

ENCRYPT  (encrypt data file)

OWNER  (declare password for data encryption)

RECLAIM  (reuse deleted record space)

PRE  (set file label prefix)

BINDABLE  (set runtime expression string RECORD variables)


FILE  (declare a data file structure)

label	FILE,DRIVER( ) [,CREATE] [,RECLAIM] [,OWNER( )] [,ENCRYPT] [,NAME()]
[,PRE( )] [,BINDABLE]
label	  [INDEX( )]
label	  [KEY( )]
label	  [MEMO( )]
[label]	  RECORD
    fields
  END
END

FILE	Declares a data file.

DRIVER	Specifies the data file type.  The DRIVER attribute is required on all FILE structure declarations.

CREATE	Allows the file to be created with the CREATE statement during program execution.

RECLAIM	Specifies reuse of deleted record space.

OWNER	Specifies the password for data encryption.

ENCRYPT	Encrypt the data file.

NAME	Set DOS filename specification.

PRE	Declare a label prefix for the structure.

BINDABLE	Specify all variables in the RECORD structure may be used in dynamic expressions.

INDEX	Declare a static file access index which must be built at run time.

KEY	Declare a dynamically updated file access index.

MEMO	Declare a variable length text field up to 64K in length.

RECORD	Declare a record structure for the fields.  A RECORD structure is required in all FILE structure declarations.

fields	Data elements in the RECORD structure.

FILE declares a data file structure which is an exact description of a data file residing on disk.  The label of the FILE structure is used in file processing statements and functions to effect operations on the disk file.  The FILE structure must be terminated by a period or the END statement.

All attributes of the FILE, KEY, INDEX, MEMO, data declaration statements, and the data types which a FILE may contain, are dependent upon the support of the file driver.  Anything in the FILE declaration which is not supported by the file system specified in the DRIVER attribute will cause a file driver error message when the FILE is opened.  Attribute and/or data type exclusions for a specific file system are listed in the file driver's documentation.

At run-time, the RECORD structure is assigned memory for a data buffer where records from the disk file may be processed by executable statements.  A RECORD structure is required in a FILE structure.  Memory for a data buffer for any MEMO fields is allocated only when the FILE is opened, and de-allocated when the FILE is closed.

A FILE with the BINDABLE attribute declares all the variables within the RECORD structure as available for use in a dynamic expression.  The contents of each variable's NAME attribute is the logical name used in the dynamic expression.  If no NAME attribute is present, the label of the variable (including prefix) is used.  Space is allocated in the .EXE for the names of all of the variables in the structure.  This creates a larger program that uses more memory than it normally would.  Therefore, the BINDABLE attribute should only be used when a large proportion of the constituent fields are going to be used.

Example:

Names	FILE,DRIVER('Clarion')	!Declare a file structure

Rec	  RECORD	!Required record structure

Name	    STRING(20)	! containing one or more data elements

. .	!End file and record declaration


CREATE  (allow data file creation)

CREATE

The CREATE attribute of a FILE declaration allows a disk file to be created by the CREATE statement from within the PROGRAM where the FILE is declared.

FILE declarations without the CREATE attribute may be created with the Clarion Data Dictionary Editor.

Example:

Names	FILE,DRIVER('Clarion'),CREATE	!Declare a file, allow create

Rec	  RECORD

Name	    STRING(20)

. .	!End file declaration


DRIVER  (specify data file type)

DRIVER(filetype [,driver string])

DRIVER	Specifies the file system the file uses.

filetype	A string constant containing the name of the file manager (Btrieve, Clarion, etc.).

driver string	A string constant or variable containing any additional instructions to the file driver.

The DRIVER attribute specifies which file driver is used to access the data file.  DRIVER is a required attribute of all FILE declarations.

Clarion programs use file drivers for physical file access.  A file driver acts as a translator between a Clarion program and the file system, eliminating different access commands for each file system.  File drivers allow access to files from different file systems without changes in the Clarion syntax.

The specific implementation method of each Clarion file access command is dependent on the file driver.  Some commands may not be available in a file driver due to limitations in the file system.  Each file driver is documented separately.  Any unsupported file access commands, FILE declaration attributes, data types, and/or file system idiosyncracies are listed there.

Example:

Names	FILE,DRIVER('Clarion') 	!Begin file declaration

Record	  RECORD

Name	    STRING(20)

. .	!End file declaration


NAME  (set filename)

NAME([	 constant	 ])
 variable

NAME 	Specifies the DOS filename of the file.

constant	A string constant.

variable	The label of a static string variable.  This may be declared as Global data, Module data, or Local data with the STATIC attribute.

The NAME attribute on a FILE statement specifies the DOS filename for the file driver.  If the constant or variable does not contain a drive and path, the current drive and directory are assumed.  If the extension is omitted, the directory entry assumes the file driver's default value.

Some file drivers require that KEYs, INDEXes, or MEMOs be in separate files.  Therefore, a NAME may also be placed on a KEY, INDEX, or MEMO.  A NAME attribute without a constant or variable defaults to the label of the declaration statement on which it is placed (including any specified prefix).

NAME(constant) may be used on any field declared within the RECORD structure.  This provides the file driver with the name of a field as it may be used in that driver's file system.

Example:

Cust	FILE,PRE(Cus),NAME(CustName)	!Filename in CustName variable

CustKey	  KEY('Name'),NAME('c:\data\cust.idx')	!Declare key, cust.idx

Record	  RECORD

Name	    STRING(20),NAME	!Default NAME to 'Cus:Name'

. .	!End file declaration

See Also:

FILE

KEY

INDEX


ENCRYPT  (encrypt data file)

ENCRYPT

The ENCRYPT attribute is used in conjunction with the OWNER attribute to disguise the information in a data file.  ENCRYPT is only valid with an OWNER attribute.  Even with a "hex-dump" utility, the data in an encrypted file is extremely difficult to decipher.

Example:

Names	FILE,DRIVER('Clarion'),OWNER('Clarion'),ENCRYPT

Record	  RECORD

Name	    STRING(20)

. .

See Also:

OWNER


OWNER  (declare password for data encryption)

OWNER(password)

OWNER	Specifies a file encryption password.

password	A string constant or variable.

The OWNER attribute specifies the password which is used by the ENCRYPT attribute to encrypt the data.  Exact implementation of what is encrypted is file driver dependent.

Example:

Customer	FILE,DRIVER('Clarion'),OWNER('abCdeF'),ENCRYPT

!Encrypt data password "abCdeF"

Record	  RECORD

Name	    STRING(20)

. .

See Also:

ENCRYPT


RECLAIM  (reuse deleted record space)

RECLAIM

The RECLAIM attribute specifies that the file driver adds new records to the file in the space previously used by a record that has been deleted, if available.  Otherwise, the record is added at the end of the file.  Implementation of RECLAIM is file driver specific and may not be supported in all file systems.

Example:

Names	FILE,DRIVER('Clarion'),RECLAIM	!Reuse deleted record space

Record	  RECORD

Name	    STRING(20)

. .


PRE  (set file label prefix)

PRE(prefix)

PRE 	Provides a label prefix for complex data structures.

prefix	Acceptable characters are alphabet letters, numerals 0 through 9, and the underscore character.  A prefix must start with an alphabet character and must not be a reserved word.

The PRE attribute provides a label prefix for complex data structures.  It is used to distinguish between identical variable names that occur in different structures.  When referenced in executable statements, assignments, and parameter lists, a prefix is attached to a label by a colon (Pre:Label).  PRE may be used with the following data structures:

FILE	REPORT

GROUP	RECORD

QUEUE	VIEW

Example:

MasterFile	FILE,DRIVER('Clarion'),PRE(Mst)	!Declare master file layout

Record	  RECORD

AcctNumber	    LONG

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

Record	  RECORD

AcctNumber	    LONG

. .

GROUP,PRE(Mem)	!Declare some memory variables

Message	  STRING(30)

Page	  LONG

Line	  LONG

Device	  STRING(30)

END

  CODE

  IF Dtl:AcctNumber <> Mst:AcctNumber	!Is it a new account

    Mem:Message = 'New Account'	!  display message

    DO MatchMaster	!  get new record

  END

See Also:

Reserved Words


BINDABLE  (set runtime expression string RECORD variables)

BINDABLE

The BINDABLE attribute on a FILE statement declares a RECORD structure whose constituent variables are all available for use in a dynamic expression.  The contents of each variable's NAME attribute is the logical name used in the dynamic expression.  If no NAME attribute is present, the label of the variable (including prefix) is used.  Space is allocated in the .EXE for the names of all of the variables in the structure.  This creates a larger program that uses more memory than it normally would.  Therefore, the BINDABLE attribute should only be used when a large proportion of the constituent fields are going to be used.

The BIND(group) form of the BIND statement must still be used in the executable code before the individual fields in the RECORD structure may be used.

Example:

Names	FILE,DRIVER('Clarion'),BINDABLE	!Bindable Record structure

Record	  RECORD

Name	    STRING(20)

FileName	    STRING(8),NAME('FILE')	!Dynamic name: FILE

Dot	    STRING(1)	!Dynamic name: Dot

Extension	    STRING(3),NAME('EXT')	!Dynamic name: EXT

. .

  CODE

  OPEN(Names)

  BIND(Names)

See Also:

BIND

UNBIND

EVALUATE


File Structure Statements

INDEX  (declare static file access index)

KEY  (declare dynamic file access index)

MEMO  (declare a text field)

RECORD  (declare record structure)


INDEX  (declare static file access index)

label	INDEX([-/+][field],...,[-/+][field]) [,NAME( )] [,NOCASE] [,OPT]

INDEX	Declares a static index into the data file.

-/+	The - (minus sign) preceding an index component field specifies descending order for that component.  If omitted, or + (plus sign) the component is sorted in ascending order.

field	The label of a field in the RECORD structure of the FILE in which the INDEX is declared.  The field is an index component.  A field declared with the DIM attribute (an array) may not be used as an index component.

NAME	Specifies the disk file specification for the INDEX.

OPT	Excludes, from the INDEX, those records with null values (zero or blank) in all index component fields.

NOCASE	Specifies case insensitive sort order.

INDEX declares a "static key" for a FILE structure.  An INDEX is updated only by the BUILD statement.  It is used to access records in a different logical order than the "physical order" of the file.  An INDEX may be used for either sequential file processing or direct random access.  An INDEX always allows duplicate entries.  An INDEX may have more than one component field.  The order of the components determines the sort sequence of the index.  The first component is the most general, and the last component is the most specific.  Generally, a data file may have up to 255 indexes (and/or keys) and each index may be up to 255 bytes, but the exact numbers are file driver dependent.  An INDEX declared without a field creates a "dynamic index."  A dynamic index may use any field (or fields) in the RECORD as components (except arrays).  The component fields of a dynamic index are defined at run time in the second parameter of the BUILD statement.  The same dynamic index declaration may be built and re-built using different component fields each time.

Example:

Names	FILE,DRIVER('Clarion'),PRE(Nam)

NameNdx	  INDEX(Nam:Name),NOCASE	!Declare the name index

NbrNdx	  INDEX(Nam:Number),OPT	!Declare the number index

DynamicNdx	  INDEX()	!Declare a dynamic index

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .

See Also:

KEY

BUILD


KEY  (declare dynamic file access index)

label	KEY([-/+]field,...,[-/+][field]) [,DUP] [,NAME( )] [,NOCASE] [,OPT]

KEY	Declares a dynamically maintained index into the data file.

-/+	The - (minus sign) preceding a key component field specifies descending order for that component.  If omitted, or + (plus sign), the component is sorted in ascending order.

field	The label of a field in the RECORD structure of the FILE in which the KEY is declared.  The field is a key component.  A field declared with the DIM attribute (an array) may not be used as a key component.

NAME	Specifies the disk file specification of the KEY.

DUP	Allows multiple records with duplicate values in their key component fields.

OPT	Excludes, from the KEY, those records with null (zero or blank) values in all key component fields.

NOCASE	Specifies case insensitive sort order.

A KEY is an index into the data file which is automatically updated whenever records are added, changed, or deleted.  It is used to access records in a different logical order than the "physical order" of the file.  A KEY may be used for either sequential file processing or direct random access.

A KEY may have more than one component field.  The order of the components determines the sort sequence of the key.  The first component is the most general, and the last component is the most specific.  Generally, a data file may have up to 255 keys (and indexes) and each key may be up to 255 bytes, but the exact numbers are file driver dependent.

Example:

Names	FILE,DRIVER('Clarion'),PRE(Nam)

NameKey	  KEY(Nam:Name),NOCASE,DUP	!Declare the name key

NbrKey	  KEY(Nam:Number),OPT	!Declare the number key

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .

  CODE

  Nam:Name = 'Clarion Software'	!Initialize key field

  GET(Names,Nam:NameKey)	!Get the record

  SET(Nam:NbrKey)	!Set sequential by number

See Also:

SET

GET

INDEX


MEMO  (declare a text field)

label	MEMO(length) [,BINARY] [,NAME( )]

MEMO	Declares a fixed-length string which is stored variable-length on disk.

length	A numeric constant that determines the maximum number of characters.  The range is from 1 to 65,520 bytes.

BINARY	Declares the MEMO a storage area for binary data.

NAME	Specifies the disk filename for the MEMO field.  (Use of this parameter is file driver dependent.)

MEMO declares a fixed-length string field which is stored variable-length on disk.  The length parameter defines the maximum size of a memo.  A MEMO must be declared before the RECORD structure.  Memory is allocated for a MEMO field's buffer when the file is opened, and is de-allocated when the file is closed.

Generally, up to 255 MEMO fields may be declared in a FILE structure.  The exact number of MEMO fields and their manner of storage on disk is file driver dependent.  MEMO fields are usually displayed in TEXT fields in SCREEN and REPORT structures.

Example:

Names	FILE,DRIVER('Clarion'),PRE(Nam)

NameKey	  KEY(Nam:Name)

NbrKey	  KEY(Nam:Number)

Notes	  MEMO(4800)	!Memo, 4800 bytes

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .


RECORD  (declare record structure)

[label]	RECORD [,PRE( )] [,NAME( )]
  fields
END

RECORD	Declares the beginning of the data structure within the FILE declaration.

fields	Multiple variable declarations.

PRE	Specify a label prefix for the structure.

NAME	Specifies an external name for the RECORD structure.  (Use of this parameter is file driver dependent.)

The RECORD statement declares the beginning of the data structure within the FILE declaration.  A RECORD structure is required in a FILE declaration.  Each field is an element of the RECORD structure.  The length of a RECORD structure is the sum of the length of its fields.  When the label of a RECORD structure is used in an assignment statement, expression, or parameter list, it is treated as a GROUP data type.

At run time, static memory is allocated as a data buffer for the RECORD structure.  The fields in the record buffer are available whether the file is open or closed.  If the fields contain variable declarations with initial values, that initial value is only used to determine the size of the variable, the record buffer is not initialized to the value.

Records from the data file on disk are read into the data buffer with the NEXT, PREVIOUS, or GET statements.  Data in the fields are processed, then written to the data file as a single RECORD unit by the ADD, PUT, or DELETE statements.

Example:

Names	FILE,DRIVER('Clarion')	!Declare a file structure

Record	  RECORD	!  begin record declaration

Name	    STRING(20)	!    declare name field

Number	    SHORT	!    declare number field

. .	!End file, end record declaration


INDEX, KEY and MEMO Attributes

BINARY  (MEMO contains binary data)

DUP  (allow duplicate KEY entries)

NOCASE  (case insensitive KEY or INDEX)

OPT  (exclude null KEY or INDEX entries)

NAME  (set external name)


BINARY  (MEMO contains binary data)

BINARY

The BINARY attribute of a MEMO declaration specifies the MEMO field will receive data that is not just ASCII characters.  This attribute is normally used to store small graphic images for display in an IMAGE field on screen.

Example:

Names	FILE,DRIVER('Clarion'),PRE(Nam)

NameKey	  KEY(Nam:Name)

NbrKey	  KEY(Nam:Number)

Picture	  MEMO(48000),BINARY	!Binary memo - 48,000 bytes

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .

See Also:

MEMO

IMAGE


DUP  (allow duplicate KEY entries)

DUP

The DUP attribute of a KEY declaration allows multiple records with the same key value to occur in a file.  If the DUP attribute is omitted, attempting to ADD or PUT records with duplicate key values will cause the "Creates Duplicate Key" error, and the record will not be written to the file.  During sequential processing using the KEY, records with duplicate key values are accessed in the physical order their entries appear in the KEY file.  The GET and SET statements access the first record in a set of duplicates.  The DUP attribute is unnecessary on INDEX declarations because an INDEX always allows duplicate entries.

Example:

Names	FILE,DRIVER('Clarion'),PRE(Nam)

NameKey	KEY(Nam:Name),DUP	!Declare name key, allow duplicate names

NbrKey	KEY(Nam:Number)	!Declare number key, no duplicates allowed

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .


NOCASE  (case insensitive KEY or INDEX)

NOCASE

The NOCASE attribute of a KEY or INDEX declaration makes the sorted sequence of alphabetic characters insensitive to the ASCII upper/lower case sorting convention.  All alphabetic characters in key fields are converted to upper case as they are written to the KEY.  This case conversion has no affect on the case of the stored data.  The NOCASE attribute has no effect on non-alphabetic characters.

Example:

Names	FILE,DRIVER('Clarion'),PRE(Nam)

NameKey	KEY(Nam:Name),NOCASE	!Declare name key, make case insensitive

NbrKey	KEY(Nam:Number)	!Declare number key

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .

See Also:

INDEX

KEY


OPT  (exclude null KEY or INDEX entries)

OPT

The OPT attribute excludes entries in the KEY or INDEX for records with "null" values in all fields comprising the KEY or INDEX.  For the purpose of this attribute, a "null" value is defined as zero in a numeric field or all blank spaces in a string field.

Example:

Names	FILE,DRIVER('Clarion'),PRE(Nam)	!Declare a file structure

NameKey	KEY(Nam:Name),OPT	!Declare name key, exclude blanks

NbrKey	KEY(Nam:Number),OPT	!Declare number key, exclude zeroes

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .

See Also:

INDEX

KEY


NAME  (set external key name)

NAME([	 constant	 ])
 variable

NAME 	Specifies an "external" name for the file driver.

constant	A string constant.

variable	The label of a static string variable.  This may be declared as Global data, Module data, or Local data with the STATIC attribute.

The NAME attribute on a KEY or INDEX or MEMO statement specifies an "external" name for the key or memo for the file driver.  Some file drivers require that KEYs, INDEXes, or MEMOs be in separate files, which is specified in the NAME attribute.

NAME(constant) may be used on any field declared within the RECORD structure.  This provides the file driver with the name of a field as it may be used in that driver's file system.

A NAME attribute without a constant or variable defaults to the label of the declaration statement on which it is placed (including any specified prefix).

Example:

Cust	FILE,PRE(Cus),NAME(CustName)	!Filename in CustName variable

CustKey	  KEY('Cus:Name'),NAME('c:\data\cust.idx')	!Declare key, cust.idx

Record	  RECORD

Name	    STRING(20),NAME	!Default NAME to 'Cus:Name'

. .	!End file declaration

See Also:

FILE

KEY

INDEX


File Commands

BUILD  (build keys and indexes)

CLOSE  (close a data file)

COPY  (copy a data file)

CREATE  (create an empty data file)

EMPTY  (empty a data file)

FLUSH  (flush DOS buffers)

LOCK  (exclusive file access)

OPEN  (open a data file)

PACK  (remove deleted records)

REMOVE  (erase the data file)

RENAME  (change data file directory name)

SHARE  (open a data file)

STREAM  (enable DOS buffering)

UNLOCK  (unlock a locked data file)


BUILD  (build keys and indexes)

 key
BUILD(	index	 [,components])
 file

BUILD	Builds keys and indexes.

key	The label of a KEY declaration.

index	The label of an INDEX declaration.

file	The label of a FILE declaration.

components	A string constant or variable containing the list of the component fields on which to BUILD the dynamic INDEX.  If the file has the CREATE attribute, field labels may be used in the components parameter.  Without the CREATE attribute, the contents of each field's NAME attribute must be used.  The fields must be separated by commas, with leading plus (+) or minus (-) to indicate ascending or descending sequence (if supported by the file driver).

The BUILD statement builds keys and indexes.  BUILD(key), BUILD(index), and BUILD(file) require exclusive access to the file.  Therefore, the file must LOCKed or opened with access mode set to 12h (Read/Write Deny All) or 22h (Read/Write Deny Write).  BUILD(index,components) does not require exclusive access to the file.

  BUILD(key) or BUILD(index)

Builds only that KEY or INDEX.  The file must be closed, LOCKed, or opened with access mode set to 12h or 22h.

  BUILD(file)

Builds all the KEYs declared for the file.  The file must be closed, LOCKed, or opened with access mode set to 12h or 22h.

  BUILD(index,components)

Allows you to BUILD a dynamic INDEX.  This form of BUILD does not require exclusive access to the file, however, the file must be open (with any valid access mode).  The dynamic INDEX is created as a temporary file, exclusive to the user who BUILDs it.  The temporary file is automatically deleted when the file is closed.

Errors Posted:

37	File Not Open

40	Creates Duplicate Key

63	Exclusive Access Required

76	Invalid Index String

Example:

Names	FILE,DRIVER('Clarion'),PRE(Nam)	!Declare a file structure

NameKey	  KEY(Nam:Name),OPT	!Declare name key

NbrNdx	  INDEX(Nam:Number),OPT	!Declare number index

DynNdx	  INDEX()	!Declare a dynamic index

Rec	  RECORD

Name	    STRING(20),NAME('Nam:Name')

Number	    SHORT,NAME('Nam:Number')

. .

  CODE

  OPEN(Names,12h)	!Open file, exclusive read/write

  BUILD(Names)	!Build all keys on Names file

  BUILD(Nam:NbrNdx)	!Build the number index

  BUILD(Nam:DynNdx,'+Nam:Number,+Nam:Name')

!Build dynamic index ascending number, ascending name

See Also:

OPEN

SHARE


CLOSE  (close a data file)

CLOSE(file)

CLOSE	Closes a FILE.

file	The label of a FILE.

The CLOSE statement closes a FILE.  Generally, this flushes DOS buffers and frees any memory used by the open file other than the RECORD structure's data buffer.  The exact action CLOSE takes is file driver dependent.

Example:

CLOSE(Customer)	!Close the customer file


COPY  (copy a data file)

COPY(file,new file)

COPY	Duplicates a FILE.

file	The label of the FILE to copy.

new file	A string constant or a STRING variable containing a DOS directory file specification.  If the file specification does not contain a drive and path, the current drive and directory are assumed.  If only the path is specified, the filename and extension of the original file are used for the new file.

The COPY statement duplicates a FILE and enters the specification for the new file in the DOS directory.  The file to be copied must be closed, or the "File Already Open" error is posted.  If the file specification of the new file is identical to the original file, the COPY statement is ignored.

Since some file drivers use multiple physical disk files for one logical FILE structure, the default filename and extension assumptions are file driver dependent.  If any error is posted, the file is not copied.

Errors Posted:

02	File Not Found

03	Path Not Found

05	Access Denied

52	File Already Open

Example:

COPY(Names,'A:\')	!Copy Names file to floppy

COPY(CompText,Filename)	!Copy the text file to another file


CREATE  (create an empty data file)

CREATE(file)

CREATE	Creates an empty data file.

file	The label of the FILE to be created.

The CREATE statement adds an empty data file to the DOS directory.  If the file already exists, it is deleted and recreated as an empty file.  The file must be closed, or the "File Already Open" error is posted.  CREATE does not open the file for access.

Errors Posted:

03	Path Not Found

04	Too Many Open Files

05	Access Denied

52	File Already Open

54	No Create Attribute

Example:

CREATE(Master)	!Create a new master file

CREATE(Detail)	!Create a new detail file


EMPTY  (empty a data file)

EMPTY(file)

EMPTY	Deletes all records from a FILE.

file	The label of a FILE.

EMPTY deletes all records from the specified file.  EMPTY requires exclusive access to the file.  Therefore, the file must be opened with access mode set to 12h (Read/Write Deny All) or 22h (Read/Write Deny Write).

Errors Posted:

63	Exclusive Access Required

Example:

OPEN(Master,18)	!Open the master file

EMPTY(Master)	!  and start a new one

See Also:

OPEN

SHARE


FLUSH  (flush DOS buffers)

FLUSH(file)

FLUSH	Terminates a STREAM operation, flushing the DOS buffers.

file	The label of a FILE.

The FLUSH statement terminates a STREAM operation.  It flushes the DOS buffers, which updates the DOS directory entry for that file.  Support for this statement is dependent upon the file system and its specific action is described in the file driver documentation.

Example:

STREAM(History)	!Use DOS buffering

SET(Current)	!Set to top of current file

LOOP UNTIL EOF(Current)

  NEXT(Current)

  His:Record = Cur:Record

  ADD(History)

END 	!End loop

FLUSH(History)	!End streaming, flush buffers

See Also:

STREAM


LOCK  (exclusive file access)

LOCK(file [,seconds])

LOCK	Locks a data file.

file	The label of a FILE opened for shared access.

seconds	A numeric constant or variable which specifies the maximum wait time in seconds.

The LOCK statement locks a file against access by other workstations in a multi-user environment.  Generally, this excludes other users from writing to or reading from the file.  The specific action LOCK takes is file driver dependent.

  LOCK(file)

Attempts to lock the file until it is successful.  If it is already locked by another workstation, LOCK will wait until the other workstation unlocks it.

  LOCK(file,seconds)

Posts the "File Is Already Locked" error after unsuccessfully trying to lock the file for the specified number of seconds.

The most common problem to avoid when locking files is referred to as "deadly embrace."  This condition occurs when two workstations attempt to lock the same set of files in two different orders and both are using the LOCK(file) form of LOCK.  One workstation has already locked a file that the other is trying to LOCK, and vice versa.  This problem may be avoided by using the LOCK(file,seconds) form of LOCK, and always locking files in the same order.

Errors Posted:

32	File Is Already Locked

Example:

LOOP	!Loop to avoid "deadly embrace"

  LOCK(Master,1)	!Lock the master file, try 1 second

  IF ERRORCODE() = 32 	!If someone else has it

    BEEP(0,100)	!  pause for 1 second

    CYCLE	!  and try again

  END

  LOCK(Detail,1)	!Lock the detail file, try 1 second

  IF ERRORCODE() = 32 	!If someone else has it

    UNLOCK(Master)	!  unlock the locked file

    BEEP(0,100)	!  pause for 1 second

    CYCLE	!  and try again

. .	!End if, end loop


OPEN  (open a data file)

OPEN(file [,access mode])

OPEN	Opens a FILE structure for processing.

file	The label of a FILE declaration.

access mode	A numeric constant, variable, or expression which determines the level of access granted to both the user opening the file, and other users in a multi-user system.  If omitted, the default value is 22h (Read/Write + Deny Write).

The OPEN statement opens a FILE structure for processing and sets the access mode.  Support for various access modes are file driver dependent.  All files must be explicitly opened before they may be accessed.  The access mode is a bitmap which tells the operating system what access to grant the user opening the file and what access to deny to others using the file.  The actual values for each access level are:

Dec.	Hex.	Access

User Access:	  0	  0h	Read Only

  1	  1h	Write Only

  2	  2h	Read/Write

Other's Access:	  0	  0h	Any Access (FCB compatibility mode)

 16	 10h	Deny All

 32	 20h	Deny Write

 48	 30h	Deny Read

 64	 40h	Deny None

Errors Posted:

02	File Not Found

04	Too Many Open Files

05	Access Denied

52	File Already Open

75	Invalid Field Type Descriptor

Example:

ReadOnly	EQUATE(0)	!Access mode equates

WriteOnly	EQUATE(1)

ReadWrite	EQUATE(2)

DenyAll	EQUATE(10h)

DenyWrite	EQUATE(20h)

DenyRead	EQUATE(30h)

DenyNone	EQUATE(40h)

  CODE

  OPEN(Names,ReadWrite+DenyNone)	!Open fully shared access

See Also:

SHARE


PACK  (remove deleted records)

PACK(file)

PACK	Removes deleted records from a data file and rebuilds its keys.

file	The label of a FILE declaration.

The PACK statement removes deleted records from a data file and rebuilds its keys.  The resulting data files are as compact as possible.  PACK requires at least twice the disk space that the file, keys, and memos occupy to perform the process.  New files are created from the old, and the old files are deleted only after the process is complete.  PACK requires exclusive access to the file.  Therefore, the file must be opened with access mode set to 12h (Read/Write Deny All) or 22h (Read/Write Deny Write).

Errors Posted:

63	Exclusive Access Required

Example:

OPEN(Trans,12h)	!Open the file in exclusive mode

PACK(Trans)	!  and pack it

See Also:

OPEN

SHARE


REMOVE  (erase the data file)

REMOVE(file)

REMOVE	Deletes a FILE.

file	The label of the FILE to be removed.

The REMOVE statement erases a file specification from the DOS directory in the same manner as the DOS Delete command.  The file must be closed, or the "File Already Open" error is posted.  If any error is posted, the file is not removed.

Errors Posted:

02	File Not Found

05	Access Denied

52	File Already Open

Example:

REMOVE(OldFile)	!Delete the old file

REMOVE(Changes)	!Delete the changes file


RENAME  (change data file directory name)

RENAME(file,new file)

RENAME	Renames a FILE.

file	The label of the FILE to be renamed.

new file	A string constant or a STRING variable containing a DOS directory file specification.  If the file specification does not contain a drive and path, the current drive and directory are assumed.  If only the path is specified, the filename and extension of the original file are used for the new file.  Files cannot be renamed to a new drive.

The RENAME statement changes the file specification to the specification for the new file in the directory.  The file to be renamed must be closed, or the "File Already Open" error is posted.  If the file specification of the new file is identical to the original file, the RENAME statement is ignored.  If any error is posted, the file is not renamed.

Since some file drivers use multiple physical disk files for one logical FILE structure, the default filename and extension assumptions are file driver dependent.

Errors Posted:

02	File Not Found

03	Path Not Found

05	Access Denied

52	File Already Open

Example:

RENAME(Text,'text.bak')	!Make it the backup

RENAME(Master,'\newdir')	!Move it to another directory


SHARE  (open a data file)

SHARE(file [,access mode])

SHARE	Opens a FILE structure for processing.

file	The label of a FILE declaration.

access mode	A numeric constant, variable, or expression which determines the level of access granted to both the user opening the file, and other users in a multi-user system.  If omitted, the default value is 42h (Read/Write, Deny None).

The SHARE statement opens a FILE structure for processing and sets the access mode.  The SHARE statement is the same as the OPEN statement, with the exception of the default value of access mode.  The access mode is a bitmap which tells the operating system what access to grant the user opening the file and what access to deny to others using the file.  The actual values for each access level are:

Dec.	Hex.	Access

User Access:	  0	  0h	Read Only

  1	  1h	Write Only

  2	  2h	Read/Write

Other's Access:	  0	  0h	Any Access (FCB compatibility mode)

 16	 10h	Deny All

 32	 20h	Deny Write

 48	 30h	Deny Read

 64	 40h	Deny None

Errors Posted:

02	File Not Found

04	Too Many Open Files

05	Access Denied

52	File Already Open

75	Invalid Field Type Descriptor

Example:

ReadOnly	EQUATE(0)	!Access mode equates

WriteOnly	EQUATE(1)

ReadWrite	EQUATE(2)

DenyAll	EQUATE(10h)

DenyWrite	EQUATE(20h)

DenyRead	EQUATE(30h)

DenyNone	EQUATE(40h)

  CODE

  SHARE(Master,ReadOnly+DenyWrite)	!Open read only mode

See Also:

OPEN


STREAM  (enable DOS buffering)

STREAM(file)

STREAM	Disables automatic FILE flushing.

file	The label of a FILE.

Some file systems flush the DOS buffers on each disk write.  The STREAM statement disables this automatic flushing operation.  DOS buffers are allocated by the BUFFERS= statement in the Config.Sys file.  They store disk writes until the buffers are full, then write the buffers to disk all at once.  The directory entries for the file are updated only when the buffers are written to disk (flushed).  A STREAM operation is terminated by closing the file, which automatically flushes the buffers, or by issuing a FLUSH statement.

Support for this statement is dependent upon the file system and is described in its file driver's documentation.

Example:

STREAM(History)	!Use DOS buffering

SET(Current)	!Set to top of current file

LOOP UNTIL EOF(Current)

  NEXT(Current)

  His:Record = Cur:Record

  ADD(History)

END	!End loop

FLUSH(History)	!End streaming, flush buffers

See Also:

FLUSH


UNLOCK  (unlock a locked data file)

UNLOCK(file)

UNLOCK	Unlocks a previously locked data file.

file	The label of a FILE declaration.

The UNLOCK statement unlocks a previously LOCKed data file.  It will not unlock a file locked by another user.  If the file is not locked, or is locked by another user, UNLOCK is ignored.  UNLOCK posts no errors.  The specific action UNLOCK takes is file driver dependent.

Example:

LOOP	!Loop to avoid "deadly embrace"

  LOCK(Master,1)	!Lock the master file, try for 1 second

  IF ERRORCODE() = 32	!If someone else has it

    BEEP(0,100)	!  pause for 1 second

    CYCLE	!  and try again

  END

  LOCK(Detail,1)	!Lock the detail file, try for 1 second

  IF ERRORCODE() = 32	!If someone else has it

    UNLOCK(Master)	!  unlock the locked file

    BEEP(0,100)	!  pause for 1 second

    CYCLE	!  and try again

. .	!End if, end loop


Record Access Commands

ADD  (add a new file record)

APPEND  (add a new file record)

DELETE  (delete a file record)

GET  (read a file record by direct access)

HOLD  (exclusive file record access)

NEXT  (read next file record in sequence)

NOMEMO  (read file record without reading memo)

PREVIOUS  (read previous file record in sequence)

PUT  (write record back to file)

RELEASE  (release a held file record)

REGET  (reget file record)

RESET  (reset file record sequence position)

SET  (initiate sequential file processing)

SKIP  (bypass file records in sequence)

WATCH  (automatic file concurrency check)


ADD  (add a new file record)

ADD(file [,length])

ADD	Writes a new record to a FILE.

file	The label of a FILE declaration.

length	An integer constant, variable, or expression which contains the number of bytes to write to the file.  The length must be greater than zero and not greater than the length of the RECORD.  If omitted or out of range, length defaults to the length of the RECORD structure.

The ADD statement writes a new record from the RECORD structure data buffer to the data file.  All KEYs associated with the file are also updated during each ADD.  If an error is posted, no record is added to the file.  The specific action ADD takes is file driver dependent.

If there is no room for the record on disk, the "Access Denied" error is posted.

Errors Posted:

05	Access Denied

37	File Not Open

40	Creates Duplicate Key

Example:

ADD(Customer)	!Add a new customer record

  IF ERRORCODE() THEN STOP(ERROR()).	!  and check for errors


APPEND  (add a new file record)

APPEND(file [,length])

APPEND	Writes a new record to a FILE.

file	The label of a FILE declaration.

length	An integer constant, variable, or expression which contains the number of bytes to write to the file.  The length must be greater than zero and not greater than the length of the RECORD.  If omitted or out of range, length defaults to the length of the RECORD structure.

The APPEND statement writes a new record from the RECORD structure data buffer to the data file.  No KEYs associated with the file are updated during an APPEND.  After APPENDing records, the KEYs must be rebuilt with the BUILD command.  APPEND is usually used in batch adding a number of records at one time.

If an error is posted, no record is added to the file.  The specific action APPEND takes is file driver dependent.  If there is no room for the record on disk, the "Access Denied" error is posted.

Errors Posted:

05	Access Denied

37	File Not Open

Example:

LOOP 	!Process an input file

  NEXT(InFile)	!  getting each record in turn

    IF ERRORCODE() THEN BREAK. 	!  break loop on error

  Cus:Record = Inf:Record	!Copy the data to Customer file

  APPEND(Customer)	! and APPEND a customer record

    IF ERRORCODE() THEN STOP(ERROR()).	!   check for errors

END	!End Process loop

BUILD(Customer)	!Re-build Keys

See Also:

BUILD


DELETE  (delete a file record)

DELETE(file)

DELETE	Removes a record from a FILE.

file	The label of a FILE declaration.

The DELETE statement removes the last record accessed by NEXT, PREVIOUS, GET, ADD, or PUT.  The key entries for that record are also removed from the KEYs.  DELETE does not clear the record buffer.  Therefore, data values from the record just deleted still exist and are available for use until the record buffer is overwritten.

If no record was previously accessed, or the record is held by another workstation, DELETE posts the "Record Not Available" error and no record is deleted.  The specific action DELETE takes is file driver dependent.

Errors Posted:

05	Access Denied

33	Record Not Available

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)

NameKey	  KEY(Cus:Name),OPT

NbrKey	  KEY(Cus:Number),OPT

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .

  CODE

  Cus:Number = 12345	!Initialize key field

  GET(Customer,Cus:NbrKey)	!Get that record

    IF ERRORCODE() THEN STOP(ERROR()).

  DELETE(Customer)	!Delete the customer record

See Also:

ADD

GET

HOLD

NEXT

PREVIOUS

PUT


GET  (read a file record by direct access)

file,key
GET(	file,filepointer [,length]	)
key,keypointer

GET	Retrieves a specific record from a FILE.

file	The label of a FILE declaration.

key	The label of a KEY or INDEX declaration.

filepointer	A numeric constant, variable, or expression for the value returned by the POINTER(file) function.  The specific value is file driver dependent.

keypointer	A numeric constant, variable, or expression for the value returned by the POINTER(key) function.  The specific value is file driver dependent.

length	An integer constant, variable, or expression which contains the number of bytes to read from the file.  The length must be greater than zero and not greater than the RECORD length.  If omitted or out of range, length defaults to the length of the RECORD structure.

The GET statement locates a specific record in the data file and reads it into the RECORD structure data buffer.  Direct access to the record is achieved by relative record position within the file, or by matching key values.

  GET(file,key)

Gets the first record from the file (as listed in the key) which contains values matching the values in the component fields of the key.

  GET(file,filepointer [,length])

Gets a record from the file based on the filepointer relative position within the file.  If filepointer is zero, the current record pointer is cleared and no record is retrieved.

  GET(key,keypointer)

Gets a record from the file based on the keypointer relative position within the key.

The values for filepointer and keypointer are file driver dependent.  They could be: record number; relative byte position within the file; or, some other kind of "seek position" within the file.  If the filepointer or keypointer value is out of range, or there are no matching key values in the data file, the "Record Not Found" error is posted.

Errors Posted:

35	Record Not Found

37	File Not Open

43	Record Is Already Held

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)

NameKey	  KEY(Cus:Name),OPT

NbrKey	  KEY(Cus:Number),OPT

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .

  CODE

  Cus:Name = 'Clarion'	!Initialize key field

  GET(Customer,Cus:NameKey)	! get record with matching value

    IF ERRORCODE() THEN STOP(ERROR()).

  GET(Customer,3)	!Get 3rd rec in physical file order

    IF ERRORCODE() THEN STOP(ERROR()).

  GET(Cus:NameKey,3)	!Get 3rd rec in keyed order

    IF ERRORCODE() THEN STOP(ERROR()).

See Also:

POINTER

DUPLICATE


HOLD  (exclusive file record access)

HOLD(file [,seconds])

HOLD	Arms record locking.

file	The label of a FILE opened for shared access.

seconds	A numeric constant or variable which specifies the maximum wait time in seconds.

The HOLD statement arms record locking for a following GET, NEXT, or PREVIOUS statement in a multi-user environment.  The GET, NEXT, or PREVIOUS flags the record as "held" when it successfully gets the record.  Generally, this excludes other users from writing to, but not reading, the record.  The specific action HOLD takes is file driver dependent.

  HOLD(file)

Arms the process so that the following GET, NEXT, or PREVIOUS attempts to hold the record until it is successful.  If it is held by another workstation, GET, NEXT, or PREVIOUS will wait until the other workstation releases it.

  HOLD(file,seconds)

Arms the process for the following GET, NEXT, or PREVIOUS to post the "Record Is Already Held" error after unsuccessfully trying to hold the record for seconds.

A user may HOLD one record at a time in each file.  If a second record is accessed in the same file, the previously held record in that file is automatically released.  A common problem to avoid is "deadly embrace."  This occurs when two workstations attempt to hold the same set of records in two different orders and both are using the HOLD(file) form of HOLD.  One workstation has already held a record that the other is trying to HOLD, and vice versa.  This problem may be avoided by using the HOLD(file,seconds) form of HOLD, and trapping for the "Record Is Already Held" error.

Example:

LOOP	!Loop to avoid "deadly embrace"

  HOLD(Master,1)	!Arm Hold on master file, try for 1 second

  GET(Master,1)	!Get and hold the record

  IF ERRORCODE() = 43 	!If someone else has it

    BEEP(0,100); CYCLE	!  pause for 1 second and try again

  END

  HOLD(Detail,1)	!Lock the detail file, try for 1 second

  GET(Detail,1)	!Get and hold the record

  IF ERRORCODE() = 43	!If someone else has it

    RELEASE(Master)	!  release the held record

    BEEP(0,100); CYCLE	!  pause for 1 second and try again

  END	!End if

  BREAK

END

See Also:

RELEASE

GET

NEXT

PREVIOUS


NEXT  (read next file record in sequence)

NEXT(file)

NEXT	Reads the next record in sequence from a FILE.

file	The label of a FILE declaration.

NEXT reads the next record in sequence from a data file and places it in the RECORD structure data buffer.  The SET statement determines the sequence in which records are read.  The first NEXT following a SET reads the record at the position specified by the SET statement.  Subsequent NEXT statements read subsequent records in that sequence.  The sequence is not effected by any GET, ADD, PUT, or DELETE.

Executing NEXT without a preceding SET, or attempting to read past the end of file posts the "Record Not Available" error.

Errors Posted:

33	Record Not Available

37	File Not Open

43	Record Is Already Held

Example:

SET(Cus:NameKey)	!Beginning of file in keyed sequence

LOOP 	!Read all records through end of file

  NEXT(Customer)	!  read a record sequentially

    IF ERRORCODE() THEN BREAK.	!  break on end of file

  DO PostTrans	!  call transaction posting routine

END	!End loop

See Also:

SET

EOF

HOLD

PREVIOUS


NOMEMO  (read file record without reading memo)

NOMEMO(file)

NOMEMO	Arms "memoless" record retrieval.

file	The label of a FILE.

The NOMEMO statement arms "memoless" record retrieval for the next GET, NEXT, or PREVIOUS statement encountered.  The following GET, NEXT, or PREVIOUS gets the record but does not get any associated MEMO field(s) for the record.  Generally, this speeds up access to the record when the contents of the MEMO field(s) are not needed by the procedure.

Example:

SET(Master)

LOOP

  NOMEMO(Master)	!Arm "memoless" access

  NEXT(Master)	!Get record without memo

    IF ERRORCODE() THEN BREAK.

  Queue = Mst:Record	!Fill memory queue

  ADD(Queue)

    IF ERRORCODE() THEN STOP(ERROR()).

. .	!End if, end loop

DISPLAY(?ListBox)	!Display the queue

See Also:

GET

NEXT

PREVIOUS


PREVIOUS  (read previous file record in sequence)

PREVIOUS(file)

PREVIOUS	Reads the previous record in sequence from a FILE.

file	The label of a FILE declaration.

PREVIOUS reads the previous record in sequence from a data file and places it in the RECORD structure data buffer.  The SET statement determines the sequence in which records are read.  The first PREVIOUS following a SET reads the record at the position specified by the SET statement.  Subsequent PREVIOUS statements read subsequent records in reverse sequence.  The sequence is not effected by any GET, ADD, PUT, or DELETE.

Executing PREVIOUS without a preceding SET, or attempting to read past the beginning of file posts the "Record Not Available" error.

Errors Posted:

33	Record Not Available

37	File Not Open

43	Record Is Already Held

Example:

SET(Trn:DateKey)	!End/Beginning of file in keyed sequence

LOOP 	!Read all records in reverse order

  PREVIOUS(Trans)	!  read a record sequentially

    IF ERRORCODE() THEN BREAK.	!  break at beginning of file

  DO LastInFirstOut	!  call last in first out routine

END	!End loop

See Also:

SET

HOLD

NEXT

BOF


PUT  (write record back to file)

PUT(file [,filepointer] [,length])

PUT	Writes a record back to a FILE.

file	The label of a FILE declaration.

filepointer	A numeric constant, variable, or expression for the value returned by the POINTER(file) function.  The specific value is file driver dependent.

length	An integer constant, variable, or expression containing the number of bytes to write to the file.  This must be greater than zero and not greater than the RECORD length.  If omitted or out of range, the RECORD length is used.

The PUT statement writes the current values in the RECORD structure data buffer to a previously accessed record in the file.

  PUT(file)

Writes back the last record accessed with NEXT, PREVIOUS, GET, or ADD.  If the values in the key variables were changed, the KEYs are updated.

  PUT(file,filepointer)

Writes the record to the filepointer location in the file and the KEYs are updated.

  PUT(file,filepointer,length)

Writes length bytes to the filepointer location in the file and the KEYs are updated.

If a record was not accessed with NEXT, PREVIOUS, GET, ADD, or was deleted, the "Record Not Available" error is posted.  PUT also posts the "Creates Duplicate Key" error.  If any error is posted, the record is not written to the file.

Errors Posted:

05	Access Denied

33	Record Not Available

40	Creates Duplicate Key

Example:

SET(Trn:DateKey)	!End/Beginning of file in keyed sequence

LOOP 	!Read all records in reverse order

  PREVIOUS(Trans)	!  read a record sequentially

    IF ERRORCODE() THEN BREAK.	!  break at beginning of file

  DO LastInFirstOut	!Call last in first out routine

  PUT(Trans)	!Write transaction record back to the file

    IF ERRORCODE() THEN STOP(ERROR()).

END	!End loop

See Also:

ADD

GET

NEXT

PREVIOUS


RELEASE  (release a held file record)

RELEASE(file)

RELEASE	Releases the held record.

file	The label of a FILE declaration.

The RELEASE statement releases a previously held record.  It will not release a record held by another user.  If the record is not held, or is held by another user, RELEASE is ignored.

Example:

LOOP	!Loop to avoid "deadly embrace"

  HOLD(Master,1)	!Arm Hold on master file, try for 1 second

  GET(Master,1)	!Get and hold the record

  IF ERRORCODE() = 43 	!If someone else has it

    BEEP(0,100)	!  pause for 1 second

    CYCLE	!  and try again

  END

  HOLD(Detail,1)	!Lock the detail file, try for 1 second

  GET(Detail,1)	!Get and hold the record

  IF ERRORCODE() = 43	!If someone else has it

    RELEASE(Master)	!  release the held record

    BEEP(0,100)	!  pause for 1 second

    CYCLE	!  and try again

  END	!End if

  BREAK

END

See Also:

HOLD


REGET  (reget file record)

REGET(file,string)

RESET	Regets a specific record in the FILE.

file	The label of a FILE declaration.

string	The string returned by the POSITION function.

The REGET reads the record identified by the string returned by the POSITION function.  The value contained in the string returned by the POSITION function, and its length, are file driver dependent.

Errors Posted:

33	Record Not Available

Example:

RecordQue	QUEUE,PRE(Dsp)

QueFields	  LIKE(Trn:Record),PRE(Dsp)

END

SavPosition	STRING(260)

  CODE

  SET(Trn:DateKey)	!Top of file in keyed sequence

  LOOP	!Read all records in file

    NEXT(Trans)	!  read a record sequentially

      IF ERRORCODE() THEN BREAK.

    RecordQue = Trn:Record	!Move record into queue

    ADD(RecordQue)	!  and add it

      IF ERRORCODE() THEN STOP(ERROR()).

    IF RECORDS(RecordQue) = 20 OR EOF(Trans)  !20 records in queue or end of file?

      SavPosition = POSITION(Trn:DateKey)	!Save record position

      DO DisplayQue	!Display the queue

      FREE(RecordQue)	!  and free it

      REGET(Trans,SavPosition)	! and get the record again

  . .	!End loop

See Also:

POSITION

RESET


RESET  (reset file record sequence position)

RESET(sequence,string)

RESET	Resets the sequential processing pointer to a specific record in the FILE.

sequence	The label of a FILE, KEY, or INDEX declaration.

string	The string returned by the POSITION function.

RESET restores the record pointer to the record identified by the string returned by the POSITION function.  Once RESET has restored the record pointer, either NEXT or PREVIOUS will read that record.

The value contained in the string returned by the POSITION function, and its length, are file driver dependent.  RESET is used in conjunction with POSITION to temporarily suspend and resume sequential file processing.

Example:

RecordQue	QUEUE,PRE(Dsp)

QueFields	  LIKE(Trn:Record),PRE(Dsp)

END

SavPosition	STRING(260)

  CODE

  SET(Trn:DateKey)	!Top of file in keyed sequence

  LOOP	!Read all records in file

    NEXT(Trans)	!  read a record sequentially

      IF ERRORCODE() THEN BREAK.

    RecordQue = Trn:Record	!Move record into queue

    ADD(RecordQue)	!  and add it

      IF ERRORCODE() THEN STOP(ERROR()).

    IF RECORDS(RecordQue) = 20 OR EOF(Trans)  !20 records in queue or end of file?

      SavPosition = POSITION(Trn:DateKey)	!Save record position

      DO DisplayQue	!Display the queue

      FREE(RecordQue)	!  and free it

      RESET(Trn:DateKey,SavPosition)	!Reset the record pointer

      NEXT(Trans)	! and get the record again

  . .	!End loop

See Also:

POSITION

NEXT

PREVIOUS


SET  (initiate sequential file processing)

          file
SET(	       file,key	)
    file,filepointer
          key
        key,key
      key,keypointer
   key,key,filepointer

SET	Initializes sequential processing of a FILE.

file	The label of a FILE declaration.  This parameter specifies processing in the physical order in which records occur in the data file.

key	The label of a KEY or INDEX declaration.  When used in the first parameter position, key specifies processing in the sort sequence of the KEY or INDEX.

filepointer	A numeric constant, variable, or expression for the value returned by the POINTER(file) function.  The specific value is file driver dependent.

keypointer	A numeric constant, variable, or expression for the value returned by the POINTER(key) function.  The specific value is file driver dependent.

SET initializes sequential processing of a data file.  SET does not get a record, but only sets up processing order and starting point for the following NEXT or PREVIOUS statements.  The first parameter determines the order in which records are processed.  The second and third parameters determine the starting point within the file.  If omitted, processing begins at the beginning (or end) of the file.

  SET(file)

Specifies physical record order processing and positions to the beginning (SET...NEXT) or end (SET...PREVIOUS) of the file.

  SET(file,key)

Specifies physical record order processing and positions to the first record which contains values matching the values in the component fields of the key.

  SET(file,filepointer)

Specifies physical record order processing and positions to the filepointer record within the file.

  SET(key)

Specifies keyed sequence processing and positions to the beginning (SET...NEXT) or end (SET...PREVIOUS) of the file in that sequence.

  SET(key,key)

Specifies keyed sequence processing and positions to the first or last record which contains values matching the values in the component fields of the key.  Both key parameters must be the same.

  SET(key,keypointer)

Specifies keyed sequence processing and positions to the keypointer record within the key.

  SET(key,key,filepointer)

Specifies keyed sequence processing and positions to a record which contains values matching the values in the component fields of the key at the exact record number specified by filepointer.  Both key parameters must be the same.

When key is the second parameter, processing begins at the first or last record containing values matching the values in the component fields of the KEY or INDEX.  If an exact match is found, NEXT will read the first matching record while PREVIOUS will read the last matching record.  If no exact match is found, the record with the next greater value is read by NEXT, the record with next lesser value is read by PREVIOUS.

The values for filepointer and keypointer are file driver dependent.  They could be a record number, the relative byte position within the file, or some other kind of "seek position" within the file.  These parameters are used to begin processing at a specific record within the file.

For all file drivers, an attempt to SET past the end of the file will set the EOF function to true, and an attempt to SET before the beginning of the file will set the BOF function to true.

Example:

SET(Customer)	!Physical file order, beginning of file

Cus:Name = 'Smith'

SET(Customer,Cus:NameKey)	!Physical file order, first record where Name = 'Smith'

SavePtr = POINTER(Customer)

SET(Customer,SavePtr)	!Physical file order, physical record number = SavePtr

SET(Cus:NameKey)	!NameKey order, beginning of file (relative to the key)

SavePtr = POINTER(Cus:NameKey)

SET(Cus:NameKey,SavePtr)	!NameKey order, key-relative record number = SavePtr

Cus:Name = 'Smith'

SET(Cus:NameKey,Cus:NameKey) !NameKey order, first record where Name = 'Smith'

Cus:Name = 'Smith'

SavePtr = POINTER(Customer)

SET(Cus:NameKey,Cus:NameKey,SavePtr)

!NameKey order, Name = 'Smith' and rec number = SavePtr

See Also:

NEXT

PREVIOUS

KEY

RECORD

POINTER


SKIP  (bypass file records in sequence)

SKIP(file,count)

SKIP	Bypasses records during sequential file processing.

file	The label of a FILE declaration.

count	A numeric constant or variable.  The count specifies the number of records to bypass.  If the value is positive, records are skipped in forward (NEXT) sequence.  If count is negative, records are skipped in reverse (PREVIOUS) sequence.

The SKIP statement is used to bypass records during sequential file processing.  It bypasses records, in the sequence specified by the SET statement, by moving the file pointer count records. SKIP is more efficient than NEXT or PREVIOUS for skipping past records because it does not move records into the RECORD structure data buffer.

If SKIP reads past the end or beginning of file, the EOF( ) and BOF( ) functions return true.  If no SET has been issued, SKIP is ignored.

Example:

SET(Itm:InvoiceKey)	!Start at beginning of Items file

LOOP UNTIL EOF(Items)	!Process all records

  NEXT(Items)	!  Get a record

    IF ERRORCODE() THEN STOP(ERROR()).

  IF Itm:InvoiceNo <> SavInvNo	!  Check for first item in order

    Hea:InvoiceNo = Itm:InvoiceNo	!    Initialize key field

    GET(Header,Hea:InvoiceKey)	!    Get the associated header record

      IF ERRORCODE() THEN STOP(ERROR()).

    IF Hea:InvoiceStatus = 'Cancel'	!    Is it a canceled order?

      SKIP(Items,Hea:ItemCount-1)	!      SKIP rest of the items

      CYCLE	!      and process next order

  . .	!  end ifs

  DO ItemProcess	! process the item

  SavInvNo = Itm:InvoiceNo	! save the invoice number

END	!End loop


WATCH  (automatic file concurrency check)

WATCH(file)

WATCH	Arms automatic optimistic concurrency checking.

file	The label of a FILE declaration.

The WATCH statement arms automatic optimistic concurrency checking by the file driver for a following GET, NEXT, or PREVIOUS statement in a multi-user environment.  Generally, the file driver retains a copy of the retrieved record on the GET, NEXT, or PREVIOUS when it successfully gets the record.  When the retrieved record is PUT to the file, the record on disk is compared to the original record retrieved.  An error is returned by the PUT statement if the record has been changed by another user.  The specific action HOLD takes is file driver dependent.

Example:

SET(Itm:InvoiceKey)	!Start at beginning of Items file

LOOP 	!Process all records

  WATCH(Items)	!Arm concurrency check

  NEXT(Items)	!  Get a record

    IF ERRORCODE() THEN BREAK.

  DO ItemProcess	! process the item

  PUT(Items)	! and put it back

    IF ERRORCODE() THEN STOP(ERROR()).	!Stop on any error, including

!  record changed by another user

END	!End loop


File Functions

BOF  (beginning of file function)

BYTES  (return size in bytes)

DUPLICATE  (check for duplicate key entries)

EOF  (end of file function)

POINTER  (return relative record position)

POSITION  (return file record sequence position)

RECORDS  (return number of file or key records)

SEND  (send message to file driver)


BOF  (beginning of file function)

BOF(file)

BOF	Flags the beginning of the FILE during sequential processing.

file	The label of a FILE declaration.

The BOF function returns a non-zero value (true) when the first record in relative file sequence has been read by PREVIOUS or passed by SKIP.  Otherwise, the return value is zero (false).

The BOF function is most often used as a LOOP UNTIL condition.  Since a LOOP condition is evaluated at the top of the LOOP, BOF returns true after the last record has been read and processed in reverse order.

The BOF function may not be supported by all file drivers.  Check the driver documentation before using this function.

Return Data Type:  LONG

Example:

SET(Trn:DateKey)	!End/Beginning of file in keyed sequence

LOOP UNTIL BOF(Trans)	!Process file backwards

  PREVIOUS(Trans)	!  read a record sequentially

    IF ERRORCODE() THEN STOP(ERROR()).

  DO LastInFirstOut	!  call last in first out routine

END 	!End loop

See Also:

PREVIOUS

SKIP

LOOP


BYTES  (return size in bytes)

BYTES(file)

BYTES	Returns number of bytes in FILE, or most recently read.

file	The label of a FILE.

The BYTES function returns the size of a FILE in bytes or the number of bytes in the last record accessed.  Following an OPEN statement, BYTES returns the size of the file.  After the file has been accessed by GET, NEXT, ADD, or PUT, the BYTES function returns the number of bytes accessed in the RECORD.  The BYTES function may be used to return the number of bytes read in a variable length record.

Example:

OPEN(DosFile)	!Open the file

IF (BYTES(DosFile) % 80) > 0	!Check for short record

  SavPtr = INT(BYTES(DosFile) % 80) + 1	!  compute short record pointer

ELSE

  SavPtr = BYTES(DosFile) / 80	!  compute last record pointer

END

GET(DosFile,SavPtr)	!Get the last record

LastRec = BYTES(DosFile)	!Save size of the short record


DUPLICATE  (check for duplicate file key entries)

DUPLICATE(	key	)
file

DUPLICATE	Checks duplicate entries in unique keys.

key	The label of a KEY declaration.

file	The label of a FILE declaration.

The DUPLICATE function returns a non-zero value (true) if writing the current record to the data file would post the "Creates Duplicate Key" error.  With a key parameter, the specified KEY is checked.  With a file parameter, all KEYs declared without a DUP attribute are checked.

The DUPLICATE function assumes that the contents of the RECORD structure data buffer are duplicated at the current record pointer location.  Therefore, when using DUPLICATE prior to ADDing a record, the record pointer should be cleared with: GET(file,0).

Return Data Type:  LONG

Example:

IF Action = 'ADD' THEN GET(Vendor,0).	!If adding, clear the file pointer

IF DUPLICATE(Vendor)	!If this vendor already exists

  SCR:MESSAGE = 'Vendor Number already assigned'	!  display message

  SELECT(?)	!  stay on the field

END	!End if

See Also:

GET


EOF  (end of file function)

EOF(file)

EOF	Flags the end of the FILE during sequential processing.

file	The label of a FILE declaration.

The EOF function returns a non-zero value (true) when the last record in relative file sequence has been read by NEXT or passed by SKIP.  Otherwise, the return value is zero (false).  The EOF function is most often used as a LOOP UNTIL condition.  Since a LOOP condition is evaluated at the top of the LOOP, EOF returns true after the last record has been read and processed.

The EOF function may not be supported by all file drivers.  Check the driver documentation before using this function.

Return Data Type:  LONG

Example:

SET(Trn:DateKey)	!Beginning of file in keyed sequence

LOOP UNTIL EOF(Trans)	!Process all records

  NEXT(Trans)	!  read a record sequentially

    IF ERRORCODE() THEN STOP(ERROR()).

  DO LastInFirstOut	!  call last in first out routine

END	!End loop

See Also:

NEXT

SKIP

LOOP


POINTER  (return relative record position)

POINTER(	file	)
key

POINTER	Returns relative record position.

file	The label of a FILE declaration.  This specifies physical record order within the file.

key	The label of a KEY or INDEX declaration.  This specifies the entry order within the KEY or INDEX file.

POINTER returns the relative record position within the data file (in file sequence), or the relative record position within the KEY or INDEX file (in key sequence) of the last record accessed.  The value returned by the POINTER function is file driver dependent.  It may be a record number, the relative byte position within the file, or some other kind of "seek position" within the file.

Return Data Type:  LONG

Example:

SavePtr# = POINTER(Customer)	!Save file pointer

See Also:

SET


POSITION  (return file record sequence position)

POSITION(sequence)

POSITION	Identifies a record's unique position in the FILE.

sequence	The label of a FILE, KEY, or INDEX declaration.

POSITION returns a STRING which identifies a record's unique position within the sequence.  POSITION returns the position of the last record accessed in the file (the record currently in the file's record buffer).  POSITION is used in conjunction with RESET to temporarily suspend and resume sequential file processing.

The value contained in the returned STRING and the length of that STRING are file driver dependent.  As a general rule, for file systems that have record numbers, the size of the STRING returned by POSITION(file) is 4 bytes.  The return string from POSITION(key) is 4 bytes plus the sum of the sizes of the fields in the key.  For file systems that do not have record numbers the size of the STRING returned by POSITION(file) is the sum of the sizes of the fields in the Primary Key (the first KEY on the FILE that does not have the DUP or OPT attribute).  The return string from POSITION(key) is the sum of the sizes of the fields in the Primary Key plus the sum of the sizes of the fields in the key.

Return Data Type:  STRING

Example:

RecordQue	QUEUE,PRE(Dsp)

QueFields	  LIKE(Trn:Record),PRE(Dsp)

END

SavPosition	STRING(260)

  CODE

  SET(Trn:DateKey)	!Top of file in keyed sequence

  LOOP	!Read all records in file

    NEXT(Trans)	!  read a record sequentially

      IF ERRORCODE() THEN BREAK.

    RecordQue = Trn:Record	!Move record into queue

    ADD(RecordQue)	!  and add it

      IF ERRORCODE() THEN STOP(ERROR()).

    IF RECORDS(RecordQue) = 20 OR EOF(Trans)

!20 records in queue?

      SavPosition = POSITION(Trn:DateKey)	!Save record position

      DO DisplayQue	!Display the queue

      FREE(RecordQue)	!  and free it

      RESET(Trn:DateKey,SavPosition)	!Reset the record pointer

      NEXT(Trans)	! and get record

  . .	!End loop

See Also:

RESET


RECORDS  (return number of file or key records)

RECORDS(	file	)
key

RECORDS	Returns the number of records.

file	The label of a FILE declaration.

key	The label of a KEY or INDEX declaration.

The RECORDS function returns the number of records in a file or key.  Since the OPT attribute of a KEY or INDEX excludes "null" entries, RECORDS may return a smaller number for the KEY or INDEX than the FILE.

Return Data Type:  LONG

Example:

SaveCount = RECORDS(Master)	!Save the record count

SaveNameCount = RECORDS(Nam:NameKey)	!Number of records with names filled in

See Also:

KEY

INDEX

OPT


SEND  (send message to file driver)

SEND(file,message)

SEND	Sends a message to the file driver.

file	The label of a FILE declaration.  The FILE's DRIVER attribute identifies the file driver to receive the message.

message	A string constant or variable containing the information to supply to the file driver.

The SEND function allows the program to pass any parameters specific to a file driver during program execution.  Specific examples of valid SEND messages are listed in the file driver's documentation.

Return Data Type:  STRING

Example:

FileCheck = SEND(ClarionFile,'RECOVER=120')	!Arm recover for a Clarion data file


Transaction Processing

COMMIT  (terminate successful transaction)

LOGOUT  (begin transaction)

ROLLBACK  (terminate unsuccessful transaction)


COMMIT  (terminate successful transaction)

COMMIT

The COMMIT statement terminates an active transaction.  Execution of a COMMIT statement assumes that the transaction was completely successful and no ROLLBACK is necessary.  Once COMMIT has been executed, ROLLBACK of the transaction is impossible.

COMMIT informs the file driver involved in the transaction that the temporary files containing the information necessary to restore the database to its previous state may be deleted.  The file driver then performs the actions necessary to its file system to successfully terminate a transaction.

Example:

  LOGOUT(.1,OrderHeader,OrderDetail)	!Begin Transaction

    DO ErrHandler	!  always check for errors

  ADD(OrderHeader)	!Add Parent record

    DO ErrHandler	!  always check for errors

  LOOP X# = 1 TO RECORDS(DetailQue)	!Process stored detail records

    GET(DetailQue,X#)	! Get one from the QUEUE

      DO ErrHandler	!  always check for errors

    Det:Record = DetailQue	! Assign to record buffer

    ADD(OrderDetail)	! and add it to the file

      DO ErrHandler	!  always check for errors

  END

  COMMIT	!Terminate successful transaction

ErrHandler	ROUTINE	!Error routine

  IF NOT ERRORCODE() THEN EXIT.	!Bail out if no error

  ROLLBACK	!Rollback the aborted transaction

  BEEP	!Alert the user

  MESSAGE('Transaction Error - ' & ERROR())

  RETURN	!  and get out

See Also:

LOGOUT

ROLLBACK


LOGOUT  (begin transaction)

LOGOUT(timeout ,file [,file,...,file])

LOGOUT	Initiates transaction processing.

timeout	A numeric constant or variable which specifies the number of seconds to attempt to begin the transaction for a file before aborting the transaction and returning an error.

file	The label of a FILE declaration.  There may be multiple file parameters, separated by commas, in the parameter list.  All files that will be in the transaction set must be listed.

The LOGOUT statement initiates transaction processing for a specified set of files.  All files in the transaction set must have the same file driver.  LOGOUT informs the file driver that a transaction is beginning.  The file driver then performs the actions necessary to that file system to initiate transaction processing for the specified set of files.  If the file system requires that the files be locked for transaction processing, LOGOUT automatically locks the files.

Only one LOGOUT transaction may be active at a time.  A second LOGOUT statement without a prior COMMIT or ROLLBACK halts the program with an error message, returning the user to DOS.

Errors Posted:

32	File Is Already Locked

Example:

  LOGOUT(.1,OrderHeader,OrderDetail)	!Begin Transaction

    DO ErrHandler	!  always check for errors

  ADD(OrderHeader)	!Add Parent record

    DO ErrHandler	!  always check for errors

  LOOP X# = 1 TO RECORDS(DetailQue)	!Process stored detail records

    GET(DetailQue,X#)	! Get one from the QUEUE

      DO ErrHandler	!  always check for errors

    Det:Record = DetailQue	! Assign to record buffer

    ADD(OrderDetail)	! and add it to the file

      DO ErrHandler	!  always check for errors

  END

  COMMIT	!Terminate successful transaction

ErrHandler	ROUTINE	!Error routine

  IF NOT ERRORCODE() THEN EXIT.	!Bail out if no error

  ROLLBACK	!Rollback the aborted transaction

  BEEP	!Alert the user

  MESSAGE('Transaction Error - ' & ERROR())

  RETURN	!  and get out

See Also:

COMMIT

ROLLBACK


ROLLBACK  (terminate unsuccessful transaction)

ROLLBACK

The ROLLBACK statement terminates an active transaction.  Execution of a ROLLBACK statement assumes that the transaction was unsuccessful and the database must be restored to the state it was in before the transaction began.

ROLLBACK informs the file driver involved in the transaction that the temporary files containing the information necessary to restore the database to its previous state must be used to restore the database.  The file driver then performs the actions necessary to its file system to roll back the transaction.

Example:

  LOGOUT(.1,OrderHeader,OrderDetail)	!Begin Transaction

    DO ErrHandler	!  always check for errors

  ADD(OrderHeader)	!Add Parent record

    DO ErrHandler	!  always check for errors

  LOOP X# = 1 TO RECORDS(DetailQue)	!Process stored detail records

    GET(DetailQue,X#)	! Get one from the QUEUE

      DO ErrHandler	!  always check for errors

    Det:Record = DetailQue	! Assign to record buffer

    ADD(OrderDetail)	! and add it to the file

      DO ErrHandler	!  always check for errors

  END

  COMMIT	!Terminate successful transaction

ErrHandler	ROUTINE	!Error routine

  IF NOT ERRORCODE() THEN EXIT.	!Bail out if no error

  ROLLBACK	!Rollback the aborted transaction

  BEEP	!Alert the user

  MESSAGE('Transaction Error - ' & ERROR())

  RETURN	!  and get out

See Also:

LOGOUT

COMMIT


Null Data Processing

The concept of a null "value" in a field of a FILE or VIEW indicates that the user has never entered data into the field.  Null actually means "value not known" for the field.  This is completely different from a blank or zero value, and makes it possible to detect the difference between a field which has never had data, and a field which has a (true) blank or zero value.

In expressions, null does not equal blank or zero.  Therefore, any expression which compares the value of a field from a FILE or VIEW with another value will always evaluate as unknown if the field is null.  This is true even if the value of both elements in the expression are unknown (null) values.  For example, the conditional expression Pre:Field1 = Pre:Field2 will evaluate as true only if both fields contain known values.  If both fields are null, the result of the expression is also unknown.

Known = Known	!Evaluates as True or False

Known = Unknown	!Evaluates as unknown

Unknown = Unknown	!Evaluates as unknown

Unknown <> 10 	!Evaluates as unknown

1 + Unknown 	!Evaluates as unknown

The only four exceptions to this rule are boolean expressions using OR and AND where only one portion of the entire expression in unknown and the other protion of the expression meets the expression criteria:

Unknown OR True 	!Evaluates as True

True OR Unknown 	!Evaluates as True

Unknown AND False 	!Evaluates as False

False AND Unknown 	!Evaluates as False

Support for null "values" in a FILE or VIEW is entirely dependent upon the file driver.  Some file drivers support the null field concept (SQL drivers, for the most part), while others do not.  Consult the documentation for the specific file driver to determine whether or not your file system's driver supports nulls.

NULL  (return null file field)

SETNULL  (set file field null)

SETNONNULL  (set file field non-null)


NULL  (return null file field)

NULL(field)

NULL	Determines null "value" of a field.

field	The label (including prefix) of a field in a FILE or VIEW structure.

The NULL function returns a non-zero value (true) if the field is null, and zero (false) if the field contains any known value (including blank or zero).  Support for null "values" in a FILE or VIEW is entirely dependent upon the file driver.

Return Data Type:  LONG

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

CSZ	    STRING(35)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCSZ	    STRING(35)

. .

  CODE

  OPEN(Header)

  OPEN(Customer)

  SET(Hea:AcctKey)

  LOOP

    NEXT(Header)

      IF ERRORCODE() THEN BREAK.

    IF NULL(Hea:ShipToName)	!Check for null ship-to address

      Cus:AcctNumber = Hea:AcctNumber

      GET(Customer,Cus:AcctKey)	!Get Customer record

        IF ERRORCODE() THEN CLEAR(Cus:Record).

      Hea:ShipToName  = Cus:Name	! and assign customer address

      Hea:ShipToAddr  = Cus:Addr	!  as the ship-to address

      Hea:ShipToCSZ   = Cus:CSZ

    END

    PUT(Header)	!Put Header record back

  END


SETNULL  (set file field null)

SETNULL(field)

SETNULL	Assigns null "value" to a field.

field	The label (including prefix) of a field in a FILE or VIEW structure.

The SETNULL statement assigns a null "value" to a field in a FILE or VIEW structure.  Support for null "values" in a FILE or VIEW is entirely dependent upon the file driver.

Return Data Type:  LONG

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

CSZ	    STRING(35)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCSZ	    STRING(35)

. .

  CODE

  OPEN(Header)

  OPEN(Customer)

  SET(Hea:AcctKey)

  LOOP

    NEXT(Header)

      IF ERRORCODE() THEN BREAK.

    Cus:AcctNumber = Hea:AcctNumber

    GET(Customer,Cus:AcctKey)	!Get Customer record

      IF ERRORCODE() THEN CLEAR(Cus:Record).

    IF NOT NULL(Hea:ShipToName) AND Hea:ShipToName = Cus:Name !Check ship-to address

      SETNULL(Hea:ShipToName)	! and assign null "values"

      SETNULL(Hea:ShipToAddr) 	!  to ship-to address

      SETNULL(Hea:ShipToCSZ)

    END

    PUT(Header)	!Put Header record back

  END


SETNONNULL  (set file field non-null)

SETNONNULL(field)

SETNONNULL	Assigns non-null value (blank or zero) to a field.

field	The label (including prefix) of a field in a FILE or VIEW structure.

The SETNONNULL statement assigns a non-null value (blank or zero) to a field in a FILE or VIEW structure.  Support for null "values" in a FILE or VIEW is entirely dependent upon the file driver.

Return Data Type:  LONG

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

. .

  CODE

  OPEN(Header)

  OPEN(Customer)

  SET(Hea:AcctKey)

  LOOP

    NEXT(Header)

      IF ERRORCODE() THEN BREAK.

    Cus:AcctNumber = Hea:AcctNumber

    GET(Customer,Cus:AcctKey)	!Get Customer record

      IF ERRORCODE() THEN CLEAR(Cus:Record).

    IF NULL(Hea:ShipToName) OR Hea:ShipToName = Cus:Name  !Check same ship-to address

      Hea:ShipToName = 'Same as Customer Address'         ! flag the record

      SETNONNULL(Hea:ShipToAddr) 	!  and blank out ship-to address

      SETNONNULL(Hea:ShipToCSZ)

    END

    PUT(Header)	!Put Header record back

  END

See Also:

NULL

SETNULL


File Views

View Structures

VIEW  (declare a "virtual" file)

PRE  (set view label prefix)

FILTER  (set view filter expression)

BINDABLE  (set runtime expression string variables)

FROM  (set field data origination)

JOIN  (declare a "join" operation)

View Commands

CLOSE  (close a VIEW)

OPEN  (open a VIEW)

SHARE  (open a VIEW)

View Access Commands

ADD  (add a new view record)

APPEND  (add a new view record)

DELETE  (delete a view record)

GET  (read a view record by direct access)

HOLD  (exclusive view record access)

LOAD  (load view from current primary record)

NEXT  (read next view record in sequence)

NOMEMO  (read view record without reading memo)

PREVIOUS  (read previous view record in sequence)

PUT  (write record back to VIEW)

RELEASE  (release a held view record)

REGET  (reget view record)

RESET  (reset view record sequence position)

SET  (initiate sequential VIEW processing)

SKIP  (bypass view records in sequence)

WATCH  (automatic view concurrency check)

View Functions

DUPLICATE  (check for duplicate key entries)

POSITION  (return view record sequence position)


View Structures

VIEW  (declare a "virtual" file)

PRE  (set view label prefix)

FILTER  (set view filter expression)

BINDABLE  (set runtime expression string variables)

FROM  (set field data origination)

JOIN  (declare a "join" operation)


VIEW  (declare a "virtual" file)

label	VIEW(primary file) [,PRE( )] [,FILTER( )] [,BINDABLE]
primary memos [FROM( )]
primary fields [FROM( )]
[JOIN( )
secondary memos [FROM( )]
secondary fields [FROM( )]
[JOIN( )
secondary memos [FROM( )]
secondary fields [FROM( )]
 END]
 END]
END

VIEW	Declares a "virtual" file as a composite of related files.

label	The name of the VIEW.

primary file	The label of the primary FILE of the VIEW.  This may also be a string constant containing direct statements (usually SQL) for the file driver to execute.

PRE	Declares a prefix for the VIEW structure.

FILTER	Declares an expression used to filter valid records for the VIEW.

BINDABLE	Specifies all variables in the VIEW structure may be used in dynamic expressions.

primary memos	The MEMO fields in the primary file that the VIEW will retrieve.

FROM	An optional attribute specifying the label (including prefix) of the FILE field from which the field's information comes.  This resolves naming conflicts when multiple fields in the VIEW have the same FILE structure label.

primary fields	The fields in the primary file that the VIEW will retrieve.

JOIN	Declares a secondary related file.

secondary

 memos	The MEMO fields in the secondary file that the VIEW will retrieve.

secondary fields	The fields in the secondary file that the VIEW will retrieve.

VIEW declares a "virtual" file as a composite of related data files.  The data elements declared in a VIEW do not physically exist in the VIEW, because the VIEW structure is a logical construct.  VIEW is a separate method of addressing data physically residing in multiple, related FILE structures.  At run-time, the VIEW structure is assigned memory for a data buffer, so the fields in the VIEW may be processed by executable statements.  The data buffer is not initialized, therefore you must first use CLEAR if you need to detect an empty field in the view data buffer.

The primary fields and secondary fields in the VIEW structure must be declared exactly the same as the FILE fields from which they are derived, with the possible addition of the FROM attribute.  MEMO fields may also be included in the VIEW.

The VIEW data structure is designed to facilitate database access on client-server systems.  It accomplishes two relational operations at once: the relational "Join" and "Project" operations.  On client-server systems, these operations are performed on the file server, and only the result of the operation is sent to the client.  This can dramatically improve performance of network applications.

A relational "Join" retrieves data from multiple files, based upon the relationships defined between the files.  The JOIN structure in a VIEW structure defines the relational "Join" operation.  There may be multiple JOIN structures within a VIEW, and they may be nested within each other to perform multiple-level "Join" operations.

A relational "Project" operation retrieves only specified data elements from the files involved, not their entire record structure.  Only those primary fields and secondary fields explicitly declared in the VIEW structure are retrieved.  Therefore, the relational "Project" operation is automatically implemented by the VIEW structure.

A VIEW "inherits" all the KEYs declared in its primary file.  This means the VIEW can be SET and processed in any KEY sequence defined for its primary file.

The FILTER attribute restricts the VIEW to a sub-set of records.  The FILTER expression may include any of the primary fields and secondary fields explicitly declared in the VIEW structure and restrict the VIEW based upon the contents of any of the fields.  This makes the FILTER operate across all levels of the "Join" operation.

If the primary file is a string constant containing statements for the file driver to execute, then the VIEW structure may not have any attributes or contain any JOIN structures, only primary fields.  These primary fields then become the receiving fields for whatever action the statements have the file driver execute.

A VIEW with the BINDABLE attribute declares all the variables within the structure as available for use in a dynamic expression.  The contents of each variable's NAME attribute is the logical name used in the dynamic expression.  If no NAME attribute is present, the label of the variable (including prefix) is used.  Space is allocated in the .EXE for the names of all of the variables in the structure.  This creates a larger program that uses more memory than it would normally.  Therefore, the BINDABLE attribute should only be used when a large proportion of the constituent fields are going to be used.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END


PRE  (set view label prefix)

PRE(prefix)

PRE 	Provides a label prefix for the VIEW structure.

prefix	Acceptable characters are alphabet letters, numerals 0 through 9, and the underscore character.  A prefix must start with an alphabet character and must not be a reserved word.

The PRE attribute provides a label prefix for the VIEW structures.  It is used to distinguish between identical variable names that occur in different structures.  When referenced in executable statements, assignments, and parameter lists, a prefix is attached to a label by a colon (Pre:Label).

Example:

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

  CODE

  SET(ViewOrder)

  LOOP

    NEXT(ViewOrder)

      IF ERRORCODE() THEN BREAK.

    IF Vew:AcctNumber = 9999 	!Is it an unknown account?

      MESSAGE('Unknown Account')	!  display message

    END

  END

See Also:

Reserved Words


FILTER  (set view filter expression)

FILTER(expression)

FILTER 	Specifies a filter expression used to evaluate records included in the VIEW.

expression	A string constant containing a logical expression.

The FILTER attribute specifies a filter expression used to evaluate records included in the VIEW.  The expression may reference any field in the VIEW, at all levels of JOIN structures.  The entire expression must evaluate as true for a record to be included in the VIEW.

Example:

!Get only orders for customer 9999 since order number 100

ViewOrder	VIEW(Customer),PRE(Vew) |

,FILTER('Vew:AcctNumber = 9999 AND Vew:OrderNumber > 100')

AcctNumber	  LONG

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)

OrderNumber	    LONG

    JOIN(Dtl:OrderKey,Hea:OrderNumber)

Item	      LONG

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)

Description	        STRING(20)

Price	        DECIMAL(9,2)

      END

    END

  END

END


BINDABLE  (set runtime expression string variables)

BINDABLE

The BINDABLE attribute on a VIEW statement declares that the constituent variables can all be available for use in a dynamic expression.  The contents of each variable's NAME attribute is the logical name used in the dynamic expression.  If no NAME attribute is present, the label of the variable (including prefix) is used.  Space is allocated in the .EXE for the names of all of the variables in the structure.  This creates a larger program that uses more memory than it would normally.  Therefore, the BINDABLE attribute should only be used when a large proportion of the constituent fields are going to be used.

The BIND(group) form of the BIND statement must still be used in the executable code before the individual fields in the VIEW structure may be used.

Example:

ViewOrder	VIEW(Customer),PRE(Vew),BINDABLE

!All fields may be used in dynamic expressions

AcctNumber	  LONG

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)

OrderNumber	    LONG

    JOIN(Dtl:OrderKey,Hea:OrderNumber)

Item	      LONG

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)

Description	        STRING(20)

Price	        DECIMAL(9,2)

      END

    END

  END

END

  CODE

  OPEN(ViewOrder)

  BIND(ViewOrder)

See Also:

BIND

UNBIND

EVALUATE


FROM  (set field data origination)

FROM( field )

FROM	Declares the data's originating field.

field	The label of a FILE variable (including prefix).

The FROM attribute on a declaration in a VIEW structure declares the label of the FILE variable (including prefix) from which the data in the VIEW field is to come.  This attribute is used to resolve name conflicts when several fields in the VIEW, coming from separate FILE structures, have the same label in their respective FILE declarations.

Example:

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

Description	    STRING(20)	!Line item comment

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)	!Product description

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Detail),PRE(Vew)

OrderNumber	  LONG

Item	  LONG

Description	  STRING(20)

  JOIN(Pro:ItemKey,Det:Item)

ProdDesc	    STRING(20),FROM(Pro:Description)	!FROM resolves name conflict

Price	    DECIMAL(9,2)

  END

END


JOIN  (declare a "join" operation)

JOIN(secondary key,linking fields)
secondary fields
[JOIN( )
secondary fields
 END]
END

JOIN	Declares a secondary file for a relational "Join" operation.

secondary key	The label of a KEY which defines the secondary FILE and its access key.

linking fields	A list of fields in the related file that contain the values the secondary key uses to access records.  Each linking field in the list must be separated by a comma.

secondary fields	The fields in the secondary file that the VIEW will retrieve.

The JOIN structure declares a secondary file for a relational "Join" operation.  A relational "Join" retrieves data from multiple files, based upon the relationships defined between the files.  There may be multiple JOIN structures within a VIEW, and they may be nested within each other to perform multiple-level "Join" operations.

The secondary key defines the access key for the secondary file.  The linking fields name the fields in the file to which the secondary file is related, that contain the values used to retrieve the related records.  For a JOIN directly within the VIEW, these fields come from the VIEW's primary file.  For a nested JOIN, these fields come from the secondary file of the JOIN in which it is nested.  Non-linking fields in the secondary key are allowed as long as they appear in the list of the key's component fields after all the linking fields.

When data is retrieved, if there are no matching secondary file records for a primary file record, null values are supplied in the secondary fields.

Example:

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:AcctNumber,Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:AcctNumber,Dtl:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Header),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Header file

OrderNumber	  LONG

  JOIN(Dtl:OrderKey,Hea:AcctNumber,Hea:OrderNumber)	!Join Detail file

Item	    LONG

Quantity	    SHORT

    JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	      STRING(20)

Price	      DECIMAL(9,2)

    END

  END

END


View Commands

CLOSE  (close a VIEW)

OPEN  (open a VIEW)

SHARE  (open a VIEW)


CLOSE  (close a VIEW)

CLOSE(view)

CLOSE	Closes a VIEW.

view	The label of a VIEW.

The CLOSE statement closes a VIEW.  Generally, this frees any memory used by the VIEW other than the structure's data buffer.  If the VIEW is declared as Procedure Local data, its data buffer is de-allocated from the stack upon RETURN from the procedure.  A VIEW declared within a procedure is implicitly closed upon RETURN from the procedure, if it has not already been explicitly CLOSEd.

CLOSE(View) also closes the files used in the VIEW if they were opened by an OPEN(View) statement.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

ViewCust	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

END

  CODE

  OPEN(ViewCust)	!Open the customer view

  READ ViewCust	!Do something with it

!executable statements

  END

  CLOSE(ViewCust)	!and close it again


OPEN  (open a VIEW)

OPEN(view [,access mode])

OPEN	Opens a VIEW structure for processing.

view	The label of a VIEW declaration.

access mode	A numeric constant, variable, or expression which determines the level of access granted to both the user opening the VIEW, and other users in a multi-user system.  If omitted, the default value is 22h (Read/Write + Deny Write).

The OPEN statement opens a VIEW structure for processing.  A VIEW must be explicitly opened before it may be accessed.

If the files in the VIEW are not already open, the OPEN(view) statement also opens the files and sets the access mode for the opened files.  Support for various access modes are file driver dependent.  The access mode is a bitmap which tells the operating system what access to grant the user opening the file and what access to deny to others using the VIEW.  The actual values for each access level are:

Dec.	Hex.	Access

User Access:	  0	  0h	Read Only

  1	  1h	Write Only

  2	  2h	Read/Write

Other's Access:	  0	  0h	Any Access (FCB compatibility mode)

 16	 10h	Deny All

 32	 20h	Deny Write

 48	 30h	Deny Read

 64	 40h	Deny None

Errors Posted:

02	File Not Found

04	Too Many Open Files

05	Access Denied

52	File Already Open

75	Invalid Field Type Descriptor

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

ReadOnly	EQUATE(0)	!Access mode equates

WriteOnly	EQUATE(1)

ReadWrite	EQUATE(2)

DenyAll	EQUATE(10h)

DenyWrite	EQUATE(20h)

DenyRead	EQUATE(30h)

DenyNone	EQUATE(40h)

  CODE

  OPEN(ViewOrder,ReadWrite+DenyNone)	!Open fully shared access

See Also:

SHARE


SHARE  (open a VIEW)

SHARE(view [,access mode])

SHARE	Opens a VIEW structure for processing.

view	The label of a VIEW declaration.

access mode	A numeric constant, variable, or expression which determines the level of access granted to both the user opening the VIEW, and other users in a multi-user system.  If omitted, the default value is 42h (Read/Write, Deny None).

The SHARE statement opens a VIEW structure for processing.  The SHARE statement is the same as the OPEN statement, with the exception of the default value of access mode.  A VIEW must be explicitly opened before it may be accessed.

If the files in the VIEW are not already open, the SHARE(view) statement also opens the files and sets the access mode for the opened files.  Support for various access modes are file driver dependent.  The access mode is a bitmap which tells the operating system what access to grant the user opening the file and what access to deny to others using the VIEW.  The actual values for each access level are:

Dec.	Hex.	Access

User Access:	  0	  0h	Read Only

  1	  1h	Write Only

  2	  2h	Read/Write

Other's Access:	  0	  0h	Any Access (FCB compatibility mode)

 16	 10h	Deny All

 32	 20h	Deny Write

 48	 30h	Deny Read

 64	 40h	Deny None

Errors Posted:

02	File Not Found

04	Too Many Open Files

05	Access Denied

52	File Already Open

75	Invalid Field Type Descriptor

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

ReadOnly	EQUATE(0)	!Access mode equates

WriteOnly	EQUATE(1)

ReadWrite	EQUATE(2)

DenyAll	EQUATE(10h)

DenyWrite	EQUATE(20h)

DenyRead	EQUATE(30h)

DenyNone	EQUATE(40h)

  CODE

  SHARE(ViewOrder,ReadOnly+DenyWrite)	!Open read only mode

See Also:

OPEN


View Access Commands

ADD  (add a new view record)

APPEND  (add a new view record)

DELETE  (delete a view record)

GET  (read a view record by direct access)

HOLD  (exclusive view record access)

LOAD  (load view from current primary record)

NEXT  (read next view record in sequence)

NOMEMO  (read view record without reading memo)

PREVIOUS  (read previous view record in sequence)

PUT  (write record back to VIEW)

RELEASE  (release a held view record)

REGET  (reget view record)

RESET  (reset view record sequence position)

SET  (initiate sequential VIEW processing)

SKIP  (bypass view records in sequence)

WATCH  (automatic view concurrency check)


ADD  (add a new view record)

ADD(view)

ADD	Writes a new record to the primary file of a VIEW.

view	The label of a VIEW declaration.

The ADD statement writes a new record from the VIEW data buffer to the primary file of the VIEW.  Any fields in the primary file that are not in the VIEW will receive blank or zero values.  ADD does not write to any secondary JOIN files in the VIEW.

ADD only writes to the primary file in the VIEW because the VIEW structure performs both relational Project and Join operations at the same time.  Therefore, it is possible to create a VIEW structure that, if all its component files were updated, would violate the Referential Integrity rules set for the database.  The common solution to this problem in SQL-based database products is to write only to the Primary file.  Therefore, Clarion has adopted this same industry standard solution.

All KEYs associated with the primary file are also updated during each ADD.  If an error is posted, no record is added to the file.  The specific action ADD performs on the data file is file driver dependent.

If there is no room for the record on disk, the "Access Denied" error is posted.

Errors Posted:

05	Access Denied

37	File Not Open

40	Creates Duplicate Key

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

  CODE

  OPEN(ViewOrder)	!Open the view

  Vew:AcctNUmber = 123	!Place data in view buffer

  Vew:Name = 'ABC Company'

  ADD(ViewOrder)	!Add a new customer record

    IF ERRORCODE() THEN STOP(ERROR()).	!  and check for errors


APPEND  (add a new view record)

APPEND(view)

APPEND	Writes a new record to the primary file of a VIEW.

view	The label of a VIEW declaration.

The APPEND statement writes a new record from the VIEW data buffer to the primary file of the VIEW.  Any fields in the primary file that are not also in the VIEW receive blank or zero values.  APPEND does not write to any secondary JOIN files in the VIEW.

APPEND only writes to the primary file in the VIEW because the VIEW structure performs both relational Project and Join operations at the same time.  Therefore, it is possible to create a VIEW structure that, if all its component files were updated, would violate the Referential Integrity rules set for the database.  The common solution to this problem in SQL-based database products is to write only to the Primary file.  Therefore, Clarion has adopted this same industry standard solution.

No KEYs are updated during an APPEND.  After the records are APPENDed, the KEYs must be rebuilt with the BUILD command.  APPEND is usually used in batch process, which adds a number of records at one time.  If an error is posted, no record is added to the file.  The specific action APPEND takes on the data file is file driver dependent.  If there is no room for the record on disk, the "Access Denied" error is posted.

Errors Posted:

05	Access Denied

37	File Not Open

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

. .

CustView	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

END

  CODE

  OPEN(CustView)

  LOOP 	!Process an input file

    NEXT(InFile)	!  getting each record in turn

      IF ERRORCODE() THEN BREAK. 	!  break loop on error

    CustView :=: Inf:Record	!Deep assign data to Customer file

    APPEND(CustView)	! and APPEND a customer record

      IF ERRORCODE() THEN STOP(ERROR()).	!   check for errors

  END	!End Process loop

  BUILD(Customer)	!Re-build Keys

See Also:

BUILD


DELETE  (delete a view record)

DELETE(view)

DELETE	Removes a primary file record from a VIEW.

view	The label of a VIEW declaration.

The DELETE statement removes the last record in the VIEW's primary file that was accessed by a NEXT, PREVIOUS, GET, ADD, or PUT statement.  The key entries for that record are also removed from the KEYs.  DELETE does not remove records from any secondary JOIN files in the VIEW.

DELETE only deletes the primary file record in the VIEW because the VIEW structure performs both relational Project and Join operations at the same time.  Therefore, it is possible to create a VIEW structure that, if all its component files were updated, would violate the Referential Integrity rules set for the database.  The common solution to this problem in SQL-based database products is to write only to the Primary file.  Therefore, Clarion has adopted this same industry standard solution.

DELETE also does not clear the VIEW data buffer.  Therefore, data values from the record just deleted still exist and are available for use until the buffer is overwritten.

If no record was previously accessed, or the record is held by another workstation, DELETE posts the "Record Not Available" error and no record is deleted.  The specific action DELETE takes in the file is file driver dependent.

Errors Posted:

05	Access Denied

33	Record Not Available

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

CustView	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

END

  CODE

  Vew:AcctNumber = 12345	!Initialize key field

  GET(CustView,Cus:AcctKey)	!Get that record

    IF ERRORCODE() THEN STOP(ERROR()).

  DELETE(CustView)	!Delete the customer record

See Also:

ADD

GET

HOLD

NEXT

PREVIOUS

PUT


GET  (read a view record by direct access)

GET(view,key)

GET	Retrieves a specific record from a VIEW.

view	The label of a VIEW declaration.

key	The label of a KEY or INDEX declaration in the VIEW's Primary file.

The GET statement locates a specific record in the data VIEW, based upon the value of the component fields of the Primary file key, and reads it into the view structure data buffer.  Direct access to the record is achieved by matching key values.  If there are no matching key values in the data VIEW, the "Record Not Found" error is posted.

Errors Posted:

35	Record Not Found

37	File Not Open

43	Record Is Already Held

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

Customer	FILE,DRIVER('Clarion'),PRE(Cus)

NameKey	  KEY(Cus:Name),OPT

NbrKey	  KEY(Cus:Number),OPT

Rec	  RECORD

Name	    STRING(20)

Number	    SHORT

. .

  CODE

  Cus:Name = 'Clarion'	!Initialize key field

  GET(Customer,Cus:NameKey)	! get record with matching value

    IF ERRORCODE() THEN STOP(ERROR()).

  GET(Customer,3)	!Get 3rd rec in physical file order

    IF ERRORCODE() THEN STOP(ERROR()).

  GET(Cus:NameKey,3)	!Get 3rd rec in keyed order

    IF ERRORCODE() THEN STOP(ERROR()).

See Also:

POINTER

DUPLICATE


HOLD  (exclusive view record access)

HOLD(view [,seconds])

HOLD	Arms record locking.

view	The label of a VIEW opened for shared access.

seconds	A numeric constant or variable which specifies the maximum wait time in seconds.

The HOLD statement arms record locking for the primary file in the VIEW in a multi-user environment.  The following GET, NEXT, or PREVIOUS flags the primary file record as "held" when it successfully gets the record.  Generally, this excludes other users from writing to the record, although it does not prevent them from reading the record.  The specific action HOLD takes is file driver dependent.

  HOLD(view)

Arms the process so that the following GET, NEXT, or PREVIOUS attempts to hold the record until it is successful.  If it is held by another workstation, GET, NEXT, or PREVIOUS will wait until the other workstation releases it.

  HOLD(view,seconds)

Arms the process so that the following GET, NEXT, or PREVIOUS posts the "Record Is Already Held" error after unsuccessfully trying to hold the record for seconds.

A user may only HOLD one record at a time in the VIEW.  If a second record is to be accessed in the same file, the previously held record must be released (see RELEASE).

As with LOCK, a common problem to avoid when holding records is "deadly embrace."  This condition occurs when two workstations attempt to hold the same set of records in two different orders and both are using the HOLD(view) form of HOLD.  One workstation has already held a record that the other is trying to HOLD, and vice versa.  This problem may be avoided by using the HOLD(view,seconds) form of HOLD, and trapping for the "Record Is Already Held" error.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

CSZ	    STRING(35)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCSZ	    STRING(35)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

  CODE

  SHARE(ViewOrder)

  SET(ViewOrder)

  LOOP	!Process records Loop

    LOOP	!Loop to avoid "deadly embrace"

      HOLD(ViewOrder,1)	!Arm Hold on view, try for 1 second

      NEXT(ViewOrder)	!Get and hold the record

      IF ERRORCODE() = 43 	!If someone else has it

        BEEP(0,100)	!  pause for 1 second

        CYCLE	! and try again

      ELSE

        BREAK	!Break if not held

      END

    END

    IF ERRORCODE() THEN BREAK.	!Check for end of file

!Process the records

    RELEASE(ViewOrder)	!release held records

  END

See Also:

RELEASE

GET

NEXT

PREVIOUS


LOAD  (load view from current primary record)

LOAD(view)

LOAD	Loads the VIEW with the primary file currently in memory.

view	The label of a VIEW declaration.

LOAD places the primary file record currently in memory into the appropriate fields in the VIEW structure's data buffer, along with all its related secondary file records.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

  CODE

  SET(Customer)	!Set to first customer record

  NEXT(Customer)	!Get first customer record

  LOAD(ViewOrder)	!Load the view


NEXT  (read next view record in sequence)

NEXT(view)

NEXT	Reads the next record(s) in sequence for a VIEW.

view	The label of a VIEW declaration.

NEXT reads the next record(s) in sequence from a VIEW and places the appropriate fields in the VIEW structure's data buffer.  If the VIEW contains a JOIN on a secondary child file, NEXT returns the next child and its associated parent record from the primary file.

The SET statement determines the sequence in which records are read.  The first NEXT following a SET, reads the record at the position specified by the SET statement.  Subsequent NEXT statements read subsequent records in that sequence.  The sequence is not affected by GET, ADD, PUT, or DELETE statements.

Executing NEXT without a preceding SET, or attempting to read past the end of the primary file in the VIEW posts the "Record Not Available" error.

Errors Posted:

33	Record Not Available

37	File Not Open

43	Record Is Already Held

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

  CODE

  SET(ViewOrder)	!Beginning of view

  LOOP 	!Read all records through end of file

    NEXT(ViewOrder)	!  read a record sequentially

      IF ERRORCODE() THEN BREAK.	!  break on end of file

    DO PostTrans	!  call transaction posting routine

  END	!End loop

See Also:

SET

HOLD

PREVIOUS


NOMEMO  (read view record without reading memo)

NOMEMO(view)

NOMEMO	Arms "memoless" record retrieval.

view	The label of a VIEW.

The NOMEMO statement arms "memoless" record retrieval for the next GET, NEXT, or PREVIOUS statement encountered.  The following GET, NEXT, or PREVIOUS gets the record but does not get any associated MEMO field(s) for the record.  Generally, this speeds up access to the record when the contents of the MEMO field(s) are not needed by the procedure.

Example:

SET(Master)

LOOP

  NOMEMO(Master)	!Arm "memoless" access

  NEXT(Master)	!Get record without memo

    IF ERRORCODE() THEN BREAK.

  Queue = Mst:Record	!Fill memory queue

  ADD(Queue)

    IF ERRORCODE() THEN STOP(ERROR()).

. .	!End if, end loop

DISPLAY(?ListBox)	!Display the queue

See Also:

GET

NEXT

PREVIOUS


PREVIOUS  (read previous view record in sequence)

PREVIOUS(view)

PREVIOUS	Reads the previous record in sequence from a VIEW.

view	The label of a VIEW declaration.

PREVIOUS reads the previous record(s) in sequence from a VIEW and places the appropriate fields in the VIEW structure's data buffer.  If the VIEW contains a JOIN on a secondary child file, PREVOUS returns the previous child and its associated parent record from the primary file.

The SET statement determines the sequence in which records are read.  The first PREVIOUS following a SET reads the record at the position specified by the SET statement.  Subsequent PREVIOUS statements read subsequent records in reverse sequence.  The sequence is not affected by GET, ADD, PUT, or DELETE statements.

Executing PREVIOUS without a preceding SET, or attempting to read past the beginning of the primary file in the VIEW posts the "Record Not Available" error.

Errors Posted:

33	Record Not Available

37	VIEW Not Open

43	Record Is Already Held

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

  CODE

  SET(ViewOrder)	!Beginning of view

  LOOP 	!Read all records through beginning of file

    PREVOUS(ViewOrder)	!  read a record sequentially

      IF ERRORCODE() THEN BREAK.	!  break on end of file

    DO PostTrans	!  call transaction posting routine

  END	!End loop

See Also:

SET

HOLD

NEXT


PUT  (write record back to VIEW)

PUT(view)

PUT	Writes a primary file record back to a VIEW.

view	The label of a VIEW declaration.

The PUT statement writes the current values in the VIEW structure's data buffer to a previously accessed primary file record in the view.  If the record was held, it is automatically released.

  PUT(view)

Writes to the last record accessed with NEXT, PREVIOUS, GET, or ADD statements.  If the values in the key variables were changed, then the KEYs are updated.

PUT only writes to the primary file in the VIEW because the VIEW structure performs both relational Project and Join operations at the same time.  Therefore, it is possible to create a VIEW structure that, if all its component files were updated, would violate the Referential Integrity rules set for the database.  The common solution to this problem in SQL-based database products is to write only to the Primary file.  Therefore, Clarion has adopted this same industry standard solution.

If a record was not accessed with NEXT, PREVIOUS, GET, or ADD statements, or was deleted, then the "Record Not Available" error is posted.  PUT also posts the "Creates Duplicate Key" error.  If any error is posted, then the record is not written to the VIEW.

Errors Posted:

05	Access Denied

33	Record Not Available

40	Creates Duplicate Key

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

SET(Trn:DateKey)	!End/Beginning of file in keyed sequence

LOOP 	!Read all records in reverse order

  PREVIOUS(Trans)	!  read a record sequentially

    IF ERRORCODE() THEN BREAK.	!  break at beginning of file

  DO LastInFirstOut	!Call last in first out routine

  PUT(Trans)	!Write transaction record back to the file

    IF ERRORCODE() THEN STOP(ERROR()).

END	!End loop

See Also:

ADD

GET

NEXT

PREVIOUS


RELEASE  (release a held view record)

RELEASE(view)

RELEASE	Releases the held record(s).

view	The label of a VIEW declaration.

The RELEASE statement releases a previously held record in a VIEW.  It will not release a record held by another user in a multi-user environment.  If the record is not held, or is held by another user, RELEASE is ignored.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

  CODE

  SHARE(ViewOrder)

  SET(ViewOrder)

  LOOP	!Process records Loop

    LOOP	!Loop to avoid "deadly embrace"

      HOLD(ViewOrder,1)	!Arm Hold on view, try for 1 second

      NEXT(ViewOrder)	!Get and hold the record

      IF ERRORCODE() = 43 	!If someone else has it

        BEEP(0,100)	!  pause for 1 second

        CYCLE	! and try again

      ELSE

        BREAK	!Break if not held

      END

    END

    IF ERRORCODE() THEN BREAK.	!Check for end of file

!Process the records

    RELEASE(ViewOrder)	!release held records

  END

See Also:

HOLD


REGET  (reget view record)

REGET(view,string)

REGET	Re-gets a specific record in the VIEW.

view	The label of a VIEW declaration.

string	The string returned by the POSITION function.

The REGET reads the record identified by the string returned by the POSITION function.  The value contained in the string returned by the POSITION function, and its length, are file driver dependent.

Errors Posted:

33	Record Not Available

Example:

RecordQue	QUEUE,PRE(Dsp)

QueFields	  LIKE(Trn:Record),PRE(Dsp)

END

SavPosition	STRING(260)

  CODE

  SET(Trn:DateKey)	!Top of file in keyed sequence

  LOOP	!Read all records in file

    NEXT(Trans)	!  read a record sequentially

      IF ERRORCODE() THEN BREAK.

    RecordQue = Trn:Record	!Move record into queue

    ADD(RecordQue)	!  and add it

      IF ERRORCODE() THEN STOP(ERROR()).

    IF RECORDS(RecordQue) = 20 OR EOF(Trans)  !20 records in queue or end of file?

      SavPosition = POSITION(Trn:DateKey)	!Save record position

      DO DisplayQue	!Display the queue

      FREE(RecordQue)	!  and free it

      REGET(Trans,SavPosition)	! and get the record again

  . .	!End loop

See Also:

POSITION

RESET


RESET  (reset view record sequence position)

RESET(sequence,string)

RESET	Resets the sequential processing pointer to a specific record in the VIEW.

sequence	The label of a VIEW, KEY, or INDEX declaration.

string	The string returned by the POSITION function.

RESET restores the record pointer to the record identified by the string that was returned by the POSITION function.  Once RESET has restored the record pointer, either NEXT or PREVIOUS will read that record.

The value contained in the string (returned by the POSITION function) and its length, are file driver dependent.  RESET is used in conjunction with POSITION to temporarily suspend and resume sequential VIEW processing.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

RecordQue	QUEUE,PRE(Dsp)

QueFields	  LIKE(ViewOrder),PRE(Dsp)

END

SavPosition	STRING(260)

  CODE

  SET(ViewOrder)	!Top of file in keyed sequence

  LOOP	!Read all records in file

    NEXT(ViewOrder)	!  read a record sequentially

      IF ERRORCODE() THEN BREAK.

    RecordQue = ViewOrder	!Move record into queue

    ADD(RecordQue)	!  and add it

      IF ERRORCODE() THEN STOP(ERROR()).

    IF RECORDS(RecordQue) = 20 OR EOF(ViewOrder)  !20 records in queue or end of file?

      SavPosition = POSITION(ViewOrder)	!Save record position

      DO DisplayQue	!Display the queue

      FREE(RecordQue)	!  and free it

      RESET(ViewOrder,SavPosition)	!Reset the record pointer

      NEXT(ViewOrder)	! and get the record again

  . .	!End loop

See Also:

POSITION

NEXT

PREVIOUS


SET  (initiate sequential VIEW processing)

 view
SET(	 view,key	)
 key
 key,key

SET	Initializes sequential processing of a VIEW.

view	The label of a VIEW declaration.  This parameter specifies processing in the physical order in which records occur in the data file.

key	The label of a KEY declaration in the VIEW structure's primary file (including the VIEW structure's prefix).  When used in the first parameter position, key specifies processing in the sort sequence of the KEY.  All the primary file's KEYs are automatically inherited by the VIEW.

SET initializes sequential processing of a VIEW.  SET does not get records; it only sets up the processing order and starting point for the following NEXT or PREVIOUS statements.  The first parameter determines the order in which records are processed.  The second parameter determines the starting point within the VIEW.  If the second parameter is omitted, processing begins at the beginning (or end) of the VIEW.

  SET(view)

Specifies physical record order processing and positions to the beginning (SET...NEXT) or end (SET...PREVIOUS) of the VIEW.

  SET(view,key)

Specifies physical record order processing and positions to the first record which contains values matching the values in the component fields of the key.

  SET(key)

Specifies keyed sequence processing and positions to the beginning (SET...NEXT) or end (SET...PREVIOUS) of the VIEW in that sequence.

  SET(key,key)

Specifies keyed sequence processing and positions to the first record which contains values matching the values in the component fields of the key.  Both key parameters must be the same.

When key is the second parameter, processing begins at the first record containing values matching the values in the component fields of the KEY.  If an exact match is found, either NEXT or PREVIOUS will read that record.  If no exact match is found, the record with the next greater value is read by NEXT, the record with the next lesser value is read by PREVIOUS.

For all file drivers: an attempt to SET past the end of the VIEW will set the EOF function to true; an attempt to SET before the beginning of the VIEW will set the BOF function to true.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

NameKey	  KEY(Cus:Name)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

CSZ	    STRING(35)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToAddr	    STRING(20)

ShipToCSZ	    STRING(35)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

. . . .

  CODE

  SET(ViewOrder)	!Physical order, beginning of file

  SET(Vew:NameKey)	!NameKey order, beginning of file (relative to key)

  Cus:Name = 'Smith'

  SET(ViewOrder,Vew:NameKey)	!Physical order, first record where Name = 'Smith'

  SET(Vew:NameKey,Vew:NameKey) 	!NameKey order, first record where Name = 'Smith'

See Also:

NEXT

PREVIOUS

KEY


SKIP  (bypass view records in sequence)

SKIP(view,count)

SKIP	Bypasses records during sequential VIEW processing.

view	The label of a VIEW declaration.

count	A numeric constant or variable.  The count specifies the number of records to bypass.  If the value is positive, records are skipped in forward (NEXT) sequence; if count is negative, records are skipped in reverse (PREVIOUS) sequence.

The SKIP statement is used to bypass records during sequential VIEW processing.  It bypasses records (in the sequence specified by the SET statement) by moving the file pointer count records.  SKIP is more efficient than NEXT or PREVIOUS for skipping past records because it does not move records into the VIEW structure data buffer.

If SKIP reads past the end or beginning of VIEW, the EOF and BOF functions return true.  If no SET has been issued, SKIP is ignored.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

ItemCount	    SHORT

OrderStatus	    STRING(10)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!Header file fields

ItemCount	    SHORT

OrderStatus	    STRING(10)

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

  SavOrderNo	LONG

  CODE

  SET(ViewOrder)	!Start at beginning of view

  LOOP 	!Process all records

    NEXT(ViewOrder)	!  Get a record

      IF ERRORCODE() THEN BREAK.

    IF Vew:OrderNumber <> SavOrderNo	!  Check for first item in order

      IF Vew:OrderStatus = 'Cancel'	!    Is it a canceled order?

        SKIP(Items,Vew:ItemCount-1)	!      SKIP rest of the items

        CYCLE	!      and process next order

    . .	!  end ifs

    DO ItemProcess	! process the item

    SavInvNo = Vew:OrderNUmber	! save the invoice number

  END	!End loop


WATCH  (automatic view concurrency check)

WATCH(view)

WATCH	Arms automatic optimistic concurrency checking.

view	The label of a VIEW declaration.

The WATCH statement arms automatic optimistic concurrency checking by the file driver for a following GET, NEXT, or PREVIOUS statement in a multi-user environment.  Generally, the file driver retains a copy of the retrieved fields from each file on the GET, NEXT, or PREVIOUS when it successfully gets the view.  When the fields are PUT to the view, the fields on disk are compared to the original data retrieved.  An error is returned by the PUT statement if the data has been changed by another user.  The specific action HOLD takes is file driver dependent.

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

CustView	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

END

  CODE

  SET(ViewOrder)	!Start at beginning of view

  LOOP 	!Process all records

    WATCH(ViewOrder)	!Arm concurrency check

    NEXT(ViewOrder)	!  Get a record

      IF ERRORCODE() THEN BREAK.

    DO ItemProcess	! process the item

    PUT(ViewOrder)	! and put it back

      IF ERRORCODE() THEN STOP(ERROR()).	!Stop on any error, including

!  record changed by another user

  END	!End loop


View Functions

DUPLICATE  (check for duplicate key entries)

POSITION  (return view record sequence position)


DUPLICATE  (check for duplicate key entries)

DUPLICATE(view)

DUPLICATE	Checks duplicate entries in unique keys.

view	The label of a VIEW declaration.

The DUPLICATE function returns a non-zero value (true) if writing the current record of the primary file in the VIEW would post the "Creates Duplicate Key" error.  All KEYs declared in the view's primary file without a DUP attribute are checked.

The DUPLICATE function assumes that the contents of the VIEW structure data buffer are duplicated at the current record pointer location.  Therefore, when using DUPLICATE prior to ADDing a record, the record pointer should be cleared (de-referenced) with the statement: GET(view,0).

Return Data Type:  LONG

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

CustView	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

END

  CODE

  OPEN(CustView)

!Data editing code goes here

  IF Action = 'ADD' THEN GET(CustView,0).	!If adding, clear the file pointer

  IF DUPLICATE(CustView)	!If this vendor already exists

    MESSAGE('Customer Number already assigned')	!  display message

    SELECT(?)	!  stay on the field

  END	!End if

See Also:

GET


POSITION  (return view record sequence position)

POSITION(sequence)

POSITION	Identifies a record's unique position in the VIEW.

sequence	The label of a VIEW, KEY, or INDEX declaration.

POSITION returns a STRING which identifies a record's unique position within the sequence.  POSITION returns the position of the last record accessed in the VIEW, which is the record currently in the VIEW's data buffer.  POSITION is used with RESET to temporarily suspend and resume sequential file processing.

When POSITION is used with a VIEW, the return string contains the return value for the primary file key and all secondary file linking keys.  The value contained in the returned STRING and the length of that STRING are file driver dependent.  As a general rule, for file systems that have record numbers, the size of the STRING returned by POSITION(file) is 4 bytes.  The return string from POSITION(key) is 4 bytes plus the sum of the sizes of the fields in the key.  For file systems that do not have record numbers the size of the STRING returned by POSITION(file) is the sum of the sizes of the fields in the Primary Key (the first KEY on the FILE that does not have the DUP or OPT attribute).  The return string from POSITION(key) is the sum of the sizes of the fields in the Primary Key plus the sum of the sizes of the fields in the key.

Return Data Type:  STRING

Example:

Customer	FILE,DRIVER('Clarion'),PRE(Cus)	!Declare customer file layout

AcctKey	  KEY(Cus:AcctNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

Name	    STRING(20)

Addr	    STRING(20)

City	    STRING(20)

State	    STRING(20)

Zip	    STRING(20)

. .

Header	FILE,DRIVER('Clarion'),PRE(Hea)	!Declare header file layout

AcctKey	  KEY(Hea:AcctNumber)

OrderKey	  KEY(Hea:OrderNumber)

Record	  RECORD

AcctNumber	    LONG

OrderNumber	    LONG

ShipToName	    STRING(20)

ShipToAddr	    STRING(20)

ShipToCity	    STRING(20)

ShipToState	    STRING(20)

ShipToZip	    STRING(20)

. .

Detail	FILE,DRIVER('Clarion'),PRE(Dtl)	!Declare detail file layout

OrderKey	  KEY(Dtl:OrderNumber)

Record	  RECORD

OrderNumber	    LONG

Item	    LONG

Quantity	    SHORT

. .

Product	FILE,DRIVER('Clarion'),PRE(Pro)	!Declare product file layout

ItemKey	  KEY(Pro:Item)

Record	  RECORD

Item	    LONG

Description	    STRING(20)

Price	    DECIMAL(9,2)

. .

ViewOrder	VIEW(Customer),PRE(Vew)	!Declare VIEW structure

AcctNumber	  LONG	!Fields from Customer file

Name	  STRING(20)

  JOIN(Hea:AcctKey,Cus:AcctNumber)	!Join Header file

OrderNumber	    LONG	!One Header file field

    JOIN(Dtl:OrderKey,Hea:OrderNumber)	!Join Detail file

Item	      LONG	!Fields from Detail file

Quantity	      SHORT

      JOIN(Pro:ItemKey,Dtl:Item)	!Join Product file

Description	        STRING(20)	!Fields from Product file

Price	        DECIMAL(9,2)

      END

    END

  END

END

RecordQue	QUEUE,PRE(Dsp)

QueFields	  LIKE(ViewOrder),PRE(Dsp)

END

SavPosition	STRING(260)

  CODE

  SET(ViewOrder)	!Top of file in keyed sequence

  LOOP	!Read all records in file

    NEXT(ViewOrder)	!  read a record sequentially

      IF ERRORCODE() THEN BREAK.

    RecordQue = ViewOrder	!Move record into queue

    ADD(RecordQue)	!  and add it

      IF ERRORCODE() THEN STOP(ERROR()).

    IF RECORDS(RecordQue) = 20 OR EOF(ViewOrder)  !20 records in queue or end of file?

      SavPosition = POSITION(ViewOrder)	!Save record position

      DO DisplayQue	!Display the queue

      FREE(RecordQue)	!  and free it

      RESET(ViewOrder,SavPosition)	!Reset the record pointer

      NEXT(ViewOrder)	! and get the record again

  . .	!End loop

See Also:

RESET


Memory Queues

Queue Structure

QUEUE  (declare a memory QUEUE structure)

PRE  (set label prefix)

STATIC  (set local queue static)

THREAD  (set thread-specific static queue)

NAME  (set external queue name)

Queue Procedures

ADD  (add an entry)

DELETE  (delete an entry)

FREE  (delete all entries)

GET  (read an entry)

PUT  (write an entry)

SORT  (sort entries)

Queue Functions

POINTER  (return last entry position)

RECORDS  (return number of entries)


Queue Structure

QUEUE  (declare a memory QUEUE structure)

PRE  (set label prefix)

STATIC  (set local queue static)

THREAD  (set thread-specific static queue)

NAME  (set external queue name)


QUEUE  (declare a memory QUEUE structure)

label	QUEUE [,PRE] [,STATIC] [,THREAD]
fieldlabel	  variable [,NAME( )]
END

QUEUE	Declares a memory queue structure.

label	The name of the QUEUE.

PRE	Declare a fieldlabel prefix for the structure.

STATIC	Declares a QUEUE, local to a PROCEDURE or FUNCTION, whose buffer is allocated in static memory.

THREAD	Specify memory for the queue is allocated once for each execution thread.  Must be used with the STATIC attribute on Procedure Local data.

fieldlabel	The name of the variables in the queue.

variable	Data declaration.  The sum of the memory required for all declared variables in the QUEUE must not be greater than 65,000 bytes.

QUEUE declares a memory QUEUE structure.   A QUEUE is a doubly-linked list; each entry has a chain pointer to the entry before and after it.  The label of the QUEUE structure is used in queue processing statements and functions.  When used in assignment statements, expressions, or parameter lists, a QUEUE is treated like a GROUP data type.

A QUEUE may be thought of as a "memory file."  When a QUEUE is declared, a data buffer is assigned.  The maximum allowable size of a QUEUE data buffer is 65,000 bytes.

The data buffer for a Procedure local QUEUE (declared in the data section of a PROCEDURE or FUNCTION) is allocated on the stack (unless it has the STATIC attribute).  The memory allocated to the entries in a Procedure local QUEUE without the STATIC attribute is allocated only until you FREE the QUEUE, or you RETURN from the PROCEDURE or FUNCTION the QUEUE is automatically FREEd upon RETURN.

For a Global data, Module data, or Local data QUEUE with the STATIC attribute, the data buffer is allocated static memory and the data in the buffer is persistent between procedure calls.  The memory allocated to the entries in the QUEUE is allocated until you FREE the QUEUE.

The variables in the QUEUE's data buffer are not automatically initialized to any value, they must be explicitly assigned values.  Do not assume that they contain blanks or zero before your program's first assignment to them.

As entries are added to the QUEUE, memory for the entry is dynamically allocated and the data is copied from the buffer to the entry.  As entries are deleted from the QUEUE, the memory used by the deleted entry is freed.  The maximum number of entries in a QUEUE is 65,535.

Generally, the memory used by each entry in the QUEUE is equal to the total of the field sizes plus 28 bytes overhead (system and pointers), rounded up to the nearest number evenly divisible by 16.  For example: a QUEUE with a LONG and a SHORT (6 bytes total) occupies 48 bytes per entry (6 + 28 = 34, which rounds up to 48).  The rounding is due to memory allocation for each entry always beginning at a 16-byte "paragraph boundary."  However, before the entry is assigned its memory, any trailing spaces in the data buffer are automatically "clipped."  This is more efficient, allowing more entries in less memory.  Because of this, a good QUEUE design practice would be to place long STRING variables at the end of the data buffer.

In addition to the data buffer and memory for each entry, there is also a small amount of system "overhead" memory for the QUEUE.  This is allocated when the QUEUE is first accessed and de-allocated only by the FREE statement.

Example:

NameQue	QUEUE,PRE(Nam)	!Declare a queue

Name	  STRING(20)

Zip	  DECIMAL(5,0),NAME('SortField')

END	!End queue structure

See Also:

PRE

STATIC

NAME

FREE

THREAD


PRE  (set label prefix)

PRE(prefix)

PRE 	Provides a label prefix for variables declared in the QUEUE.

prefix	Acceptable characters are alphabet letters, numerals 0 through 9, and the underscore character.  A prefix must start with an alphabet character and must not be a reserved word.

The PRE attribute provides a label prefix for variables declared in the QUEUE.  It is used to distinguish between identical variable names that occur in different structures.  When referenced in executable statements, assignments, and parameter lists, a prefix is attached to a label by a colon (Pre:Label).

Example:

SaveQueue	QUEUE,PRE(Sav)

Field1	  LONG	!Referenced as Sav:Field1

Field2	  STRING	!Referenced as Sav:Field2

END

See Also:

Reserved Words


STATIC  (set local queue static)

STATIC

The STATIC attribute allows the data buffer of a QUEUE declared within a PROCEDURE or FUNCTION to be allocated static memory instead of stack memory.  This makes any value contained in the data buffer "persistent" from one instance of the procedure to the next.

Example:

SomeProc	PROCEDURE

SaveQueue	QUEUE,STATIC	!Static QUEUE data buffer

Field1	  LONG	!Value retained between

Field2	  STRING	! procedure calls

END

See Also:

Data Declarations amd Memory Allocation


THREAD  (set thread-specific static queue)

THREAD

The THREAD attribute declares a static QUEUE which is allocated memory separately for each execution thread in the program.  This makes the values contained in the QUEUE dependent upon which thread is executing.  Whenever a new execution thread is begun, a new instance of the QUEUE, specific to that thread, is created.

The THREAD attribute implies a static QUEUE, so the STATIC attribute is unnecessary on a Procedure Local QUEUE.  This attribute creates a lot of runtime "overhead," particularly on Global or Module data.  Therefore, it should be used only when absolutely necessary.

Example:

SomeProc	PROCEDURE

SaveQueue	QUEUE,THREAD	!Static QUEUE data buffer

Field1	  LONG	!Thread-specific QUEUE

Field2	  STRING

END

See Also:

Data Declarations amd Memory Allocation


NAME  (set external queue name)

NAME( [name] )

NAME 	Specifies an "external" name for queue processing.

name	A string constant containing the "external" name of the variable.

The NAME attribute on a variable declared in a QUEUE structure specifies an "external" name for queue processing.  The name is an alternate method of addressing the variables in the QUEUE used by the SORT, GET, PUT, and ADD statements.

Example:

SortQue	QUEUE,PRE(Que)

Field1	  STRING(10),NAME('FirstField')	!QUEUE SORT NAME

Field2	  LONG,NAME('SecondField')	!QUEUE SORT NAME

END

See Also:

QUEUE

SORT

GET

PUT

ADD


Queue Procedures

ADD  (add an entry)

DELETE  (delete an entry)

FREE  (delete all entries)

GET  (read an entry)

PUT  (write an entry)

SORT  (sort entries)


ADD  (add an entry)

pointer
ADD(queue [,	[+]key,...,[-]key]	])
name

ADD	Writes a new entry to the QUEUE.

queue	The label of a QUEUE structure, or the label of a passed QUEUE parameter.

pointer	A numeric constant, variable, or numeric expression.  The pointer must be in the range from 1 to the number of entries in the memory queue.

+ -	The leading plus or minus sign specifies the key is sorted in ascending or descending sequence.

key	The label of a field declared within the QUEUE structure.  If the QUEUE has a PRE attribute, the key must include the prefix.

name	A string constant, variable, or expression containing the NAME attribute of QUEUE fields, separated by commas, and optional leading + or - signs for each attribute.  This parameter is case sensitive.

ADD writes a new entry from the QUEUE structure data buffer to the QUEUE.  If there is not enough memory to ADD a new entry, the "Insufficient Memory" error is posted.

  ADD(queue)

Appends a new entry to the end of the QUEUE.

  ADD(queue,pointer)

Places a new entry at the relative position specified by the pointer parameter.  If there is an entry already at the relative pointer position, it is "pushed down" to make room for the new entry.  All following pointers are readjusted to account for the new entry.  For example, an entry added at position 10 pushes entry 10 to position 11, entry 11 to position 12, etc.  If pointer is zero or greater than the number of entries in the QUEUE, the entry is added at the end.

  ADD(queue,key)

Inserts a new entry in a sorted memory queue.  Multiple key parameters may be used (up to 16), separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence.  The entry is inserted immediately after all other entries with matching key values.  If there are no entries, ADD(queue,key) may be used to build the QUEUE in sorted order.

  ADD(queue,name)

Inserts a new queue entry in a sorted memory queue.  The name string must contain the NAME attributes of the fields, separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence.  The entry is inserted immediately after all other entries with matching field values.  If there are no entries, ADD(queue,name) may be used to build the QUEUE in sorted order.

Errors Posted:

08	Insufficient Memory

75	Invalid Field Type Descriptor

Example:

NameQue	QUEUE,PRE(Que)

Name	  STRING(20),NAME('FirstField')

Zip	  DECIMAL(5,0),NAME('SecondField')

END

  CODE

  ADD(NameQue)	!Add an entry at the end of the QUEUE

  ADD(NameQue,1)	!Add an entry at position 1

  Que:Name = 'Jones'	!Initialize fields

  Que:Zip = 12345

  ADD(NameQue,+Que:Name,-Que:Zip)	!Ascending name, descending zip order

  Que:Name = 'Smith'	!Initialize fields

  Que:Zip = 12345

  ADD(NameQue,'+FirstField,-SecondField')

!Add in name, descending zip order


DELETE  (delete an entry)

DELETE(queue)

DELETE	Removes a QUEUE entry.

queue	The label of a QUEUE structure, or the label of a passed QUEUE parameter.

DELETE removes the QUEUE entry at the position of the last successful GET or ADD and de-allocates its memory.  If no previous GET or ADD was executed, the "Queue Entry Not Found" error is posted.  All forward and backward chain pointers are automatically adjusted to compensate for the deleted entry.

Errors Posted:

08	Insufficient Memory

30	Entry Not Found

Example:

Que:Name = 'Jones'	!Initialize the key

GET(NameQue,Que:Name)	!Get the matching record

DELETE(NameQue)  	!Delete the entry


FREE  (delete all entries)

FREE(queue)

FREE	Deletes all entries from a QUEUE.

queue	The label of a QUEUE structure, or the label of a passed QUEUE parameter.

FREE deletes all entries from a QUEUE and de-allocates the memory they occupied.  It also de-allocates the memory used by the QUEUE's "overhead."  FREE does not clear the QUEUE's data buffer.

Errors Posted:

08	Insufficient Memory

Example:

FREE(Location)	!Free the location queue

FREE(NameQue)	!Free the name queue


GET  (read an entry)

pointer
GET(queue 	[+]key,...,[-]key]	)
name

GET	Retrieves a specific QUEUE entry.

queue	The label of a QUEUE structure, or the label of a passed QUEUE parameter.

pointer	A numeric constant, variable, or numeric expression.  The pointer must be in the range from 1 to the number of entries in the memory queue.

+ -	The leading plus or minus sign specifies the key is sorted in ascending or descending sequence.

key	The label of a field declared within the QUEUE structure.  If the QUEUE has a PRE attribute, the key must include the prefix.

name	A string constant, variable, or expression containing the NAME attribute of QUEUE fields, separated by commas, and optional leading + or - signs for each attribute.  This parameter is case sensitive.

GET reads an entry into the QUEUE structure data buffer for processing.  If GET does not find a match, the "Queue Entry Not Found" error is posted.

  GET(queue,pointer)

Retrieves the entry at the relative entry position specified by the pointer value.

  GET(queue,key)

Searches for a QUEUE entry that matches the value in the key field(s).  Multiple key parameters may be used (up to 16), separated by commas.  The QUEUE must already be sorted on the field(s) used as the key parameter(s).

  GET(queue,name)

Searches for a QUEUE entry that matches the value in the name field(s).   The name string must contain the NAME attributes of the fields, separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence.  The QUEUE must already be sorted on the field(s) listed in the name parameter.

Errors Posted:

08	Insufficient Memory

30	Entry Not Found

75	Invalid Field Type Descriptor

Example:

NameQue	QUEUE,PRE(Que)

Name	  STRING(20),NAME('FirstField')

Zip	  DECIMAL(5,0),NAME('SecondField')

END

  CODE

    !code to build the queue goes here

  GET(NameQue,1)	!Get the first entry

    IF ERRORCODE() THEN STOP(ERROR()).

  Que:Name = 'Jones'	!Initialize key field

  GET(NameQue,Que:Name)	!Get the matching record

    IF ERRORCODE() THEN STOP(ERROR()).

  Que:Name = Fil:Name	!Initialize to value in Fil:Name

  GET(NameQue,Que:Name)	!Get the matching record

    IF ERRORCODE() THEN STOP(ERROR()).

  Que:Name = 'Smith'	!Initialize the key fields

  Que:Zip = 12345

  GET(NameQue,'FirstField,SecondField')	!Get the matching record

    IF ERRORCODE() THEN STOP(ERROR()).

See Also:

SORT


PUT  (write an entry)

PUT(queue 	[+]key,...,[-]key]	)
name

PUT	Writes an entry back to the QUEUE.

queue	The label of a QUEUE structure, or the label of a passed QUEUE parameter.

+ -	The leading plus or minus sign specifies the key is sorted in ascending or descending sequence.

key	The label of a field declared within the QUEUE structure.  If a the QUEUE has a PRE attribute, the key must include the prefix.

name	A string constant, variable, or expression containing the NAME attribute of QUEUE fields, separated by commas, and optional leading + or - signs for each attribute.  This parameter is case sensitive.

PUT writes the contents of the data buffer back to the QUEUE after a successful GET or ADD.  If no previous GET or ADD was executed, the "Queue Entry Not Found" error is posted.

  PUT(queue)

Writes the data buffer back to the same relative position within the QUEUE of the last successful GET or ADD.

  PUT(queue,key)

Returns an entry to a sorted memory queue after a successful GET or ADD, maintaining the sort order if any key fields have changed value.  Multiple key parameters may be used (up to 16), separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence.  The entry is inserted immediately after all other entries with matching key values.

  PUT(queue,name)

Returns an entry to a sorted memory queue after a successful GET or ADD, maintaining the sort order if any key fields have changed value.  The name string must contain the NAME attributes of the fields, separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence.  The entry is inserted immediately after all other entries with matching field values.

Errors Posted:

08	Insufficient Memory

30	Entry Not Found

75	Invalid Field Type Descriptor

Example:

NameQue	QUEUE,PRE(Que)

Name	  STRING(20),NAME('FirstField')

Zip	  DECIMAL(5,0),NAME('SecondField')

EBD

  CODE

      !code to build the queue goes here

  Que:Name = 'Jones'	!Initialize key field

  GET(NameQue,Que:Name)	!Get the matching record

    IF ERRORCODE() THEN STOP(ERROR()).

  Que:Zip = 12345	!Change the zip

  PUT(NameQue)	!Write the changes to the queue

    IF ERRORCODE() THEN STOP(ERROR()).

  Que:Name = 'Jones'	!Initialize key field

  GET(NameQue,Que:Name)	!Get the matching record

    IF ERRORCODE() THEN STOP(ERROR()).

  Que:Name = 'Smith'	!Change key field

  PUT(NameQue,Que:Name)	!Write changes to the queue

    IF ERRORCODE() THEN STOP(ERROR()).

  Que:Name = 'Smith' 	!Initialize key field

  GET(NameQue,'FirstField')	!Get the matching record

    IF ERRORCODE() THEN STOP(ERROR()).

  Que:Name = 'Jones'	!Change key field

  PUT(NameQue,'FirstField')	!Write changes to the queue

    IF ERRORCODE() THEN STOP(ERROR()).


SORT  (sort entries)

SORT(queue,	[+]key,...,[-]key]	)
name

SORT	Reorders entries in a QUEUE.

queue	The label of a QUEUE structure, or the label of a passed QUEUE parameter.

+ -	The leading plus or minus sign specifies the key will be sorted in ascending or descending sequence.

key	The label of a field declared within the QUEUE structure.  If the QUEUE has a PRE attribute, the key must include the prefix.

name	A string constant, variable, or expression containing the NAME attribute of QUEUE fields, separated by commas, and optional leading + or - signs for each attribute.  This parameter is case sensitive.

SORT reorders the entries in a QUEUE.  QUEUE entries with identical key values maintain their relative position.  SORT does not move data, it rearranges the pointers between the entries.

  SORT(queue,key)

Reorders the QUEUE in the sequence specified by the key.  Multiple key parameters may be used (up to 16), separated by commas, with optional leading plus or minus signs to indicate ascending or descending sequence.

  SORT(queue,name)

Reorders the QUEUE in the sequence specified by the name string.  The name string must contain the NAME attributes of the fields, separated by commas, with leading plus or minus signs to indicate ascending or descending sequence.

Errors Posted:

08	Insufficient Memory

75	Invalid Field Type Descriptor

Example:

Location	QUEUE,PRE(Loc)

Name	  STRING(20),NAME('FirstField')

City	  STRING(10),NAME('SecondField')

State	  STRING(2)

Zip 	  DECIMAL(5,0)

END

  CODE

  SORT(Location,Loc:State,Loc:City,Loc:Zip)	!Sort by zip in city in state

  SORT(Location,+Loc:State,-Loc:Zip)	!Sort descending by zip in state

  SORT(Location,'FirstField,-SecondField')	!Sort descending by city in name


Queue Functions

POINTER  (return last entry position)

RECORDS  (return number of entries)


POINTER  (return last entry position)

POINTER(queue)

POINTER	Returns the entry number of the last entry accessed in a QUEUE.

queue	The label of a QUEUE structure, or the label of a passed QUEUE parameter.

The POINTER function returns a LONG integer specifying the entry number of the last QUEUE entry accessed by ADD or GET.

Return Data Type:  LONG

Example:

Que:Name = 'Jones'	!Initialize key field

GET(NameQue,Que:Name)	!Get the entry

  IF ERRORCODE() THEN STOP(ERROR()).	!  and check for errors

SavPoint = POINTER(NameQue)	 	!Save the pointer


RECORDS  (return number of entries)

RECORDS(queue)

RECORDS	Returns the number of entries in a QUEUE.

queue	The label of a QUEUE structure, or the label of a passed QUEUE parameter.

The RECORDS function returns a LONG integer containing the number of entries in the queue.

Return Data Type:  LONG

Example:

Entries# = RECORDS(Location)	!Determine number of entries

LOOP I# = 1 TO Entries#	!Loop through QUEUE

  GET(Location,I#)	! getting each entry

    IF ERRORCODE() THEN STOP(ERROR()).

  DO SomeProcess	!  process the entry

END	!End loop


Miscellaneous Procedures and Functions

Mathematical Functions

ABS  (return absolute value)

INRANGE  (check number within range)

INT  (truncate fraction)

LOGE  (return natural logarithm)

LOG10  (return base 10 logarithm)

RANDOM  (return random number)

ROUND  (return rounded number)

SQRT  (return square root)

Trigonometric Functions

SIN  (return sine)

COS  (return cosine)

TAN  (return tangent)

ASIN  (return arcsine)

ACOS  (return arccosine)

ATAN  (return arctangent)

String Functions

ALL  (return repeated characters)

CENTER  (return centered string)

CHR  (return character from ASCII)

CLIP  (return string without trailing spaces)

DEFORMAT  (remove formatting from numeric string)

FORMAT  (format numbers into a picture)

INLIST  (search for entry in list)

INSTRING  (search for substring)

LEFT  (return left justified string)

LEN  (return length of string)

LOWER  (return lower case)

NUMERIC  (check numeric string)

RIGHT  (return right justified string)

SUB  (return substring of string)

UPPER  (return upper case)

VAL  (return ASCII value)

Bit Manipulation Functions

BAND  (return bitwise AND)

BOR  (return bitwise OR)

BXOR  (return bitwise exclusive OR)

BSHIFT  (return shifted bits)

Date / Time Procedures and Functions

Standard Date

Standard Time

TODAY  (return system date)

SETTODAY  (set system date)

CLOCK  (return system time)

SETCLOCK  (set system time)

DATE  (return standard date)

DAY  (return day of month)

MONTH  (return month of date)

YEAR  (return year of date)

AGE  (return age from base date)

DOS Procedures and Functions

COMMAND  (return command line)

MEMORY  (return available memory)

PATH  (return current DOS directory)

RUNCODE  (return DOS exit code)

SETCOMMAND  (set command line parameters)

SETPATH  (change current drive and directory)

Miscellaneous Procedures and Functions

ADDRESS  (return a memory address)

BEEP  (sound tone on speaker)

ERROR  (return error message)

ERRORCODE  (return error code number)

ERRORFILE  (return error filename)

FILEERROR  (return file driver error message)

FILEERRORCODE  (return file driver error code number)

MAXIMUM  (return maximum subscript value)

NAME  (return DOS file or device name)

OMITTED  (check omitted parameters)


Mathematical Functions

ABS  (return absolute value)

INRANGE  (check number within range)

INT  (truncate fraction)

LOGE  (return natural logarithm)

LOG10  (return base 10 logarithm)

RANDOM  (return random number)

ROUND  (return rounded number)

SQRT  (return square root)


ABS  (return absolute value)

ABS(expression)

ABS	Returns absolute value.

expression	A constant, variable, or expression.

The ABS function returns the absolute value of an expression.  The absolute value of a number is always positive (or zero).

Return Data Type:  REAL

Example:

C = ABS(A - B)	!C is absolute value of the difference

IF B < 0 THEN B = ABS(B).	!If b is negative make it positive


INRANGE  (check number within range)

INRANGE(expression,low,high)

INRANGE	Return number in valid range.

expression	A numeric constant, variable, or expression.

low	A numeric constant, variable, or expression of the lower boundary of the range.

high	A numeric constant, variable, or expression of the upper boundary of the range.

The INRANGE function compares a numeric expression to an inclusive range of numbers.  If the value of the expression is within the range, the function returns the value 1 for "true."  If the expression is greater than the high parameter, or less than the low parameter, the function returns a zero for "false."

Return Data Type:  LONG

Example:

IF INRANGE(Date % 7,1,5)	!If this is a week day

  DO WeekdayRate	!  use the weekday rate

ELSE	!Otherwise

  DO WeekendRate 	!  use the weekend rate

END	!End if


INT  (truncate fraction)

INT(expression)

INT	Return integer.

expression	A numeric constant, variable, or expression.

The INT function returns the integer portion of a numeric expression.  No rounding is performed, and the sign remains unchanged.

Return Data Type:  REAL

Example:

INT(8.5)	returns 8

INT(-5.9)	returns -5


LOGE  (return natural logarithm)

LOGE(expression)

LOGE	Returns the natural logarithm.

expression	A numeric constant, variable, or expression.  If the value of the expression is less than zero, the return value is zero.  The natural logarithm is undefined for values less than zero.

The LOGE (pronounced "log-e") function returns the natural logarithm of a numeric expression.  The natural logarithm of a value is the power to which e must be raised to equal that value.  The value of e is 2.71828182846.

Return Data Type:  REAL

Example:

LOGE(2.71828182846)	returns 1

LOGE(1) 	returns 0

LogVal = LOGE(Val)	!Get the natural log of Val


LOG10  (return base 10 logarithm)

LOG10(expression)

LOG10	Returns base 10 logarithm.

expression	A numeric constant, variable, or expression.  If the value of the expression is zero or less, the return value will be zero.  The base 10 logarithm is undefined for values less than or equal to zero.

The LOG10 (pronounced "log ten") function returns the base 10 logarithm of a numeric expression.  The base 10 logarithm of a value is the power to which 10 must be raised to equal that value.

Return Data Type:  REAL

Example:

LOG10(10)	returns 1

LOG10(1)	returns 0

LogStore = LOG10(Var)	!Store the log 10 of var


RANDOM  (return random number)

RANDOM(low,high)

RANDOM	Returns random integer.

low	A numeric constant, variable, or expression for the lower boundary of the range.

high	A numeric constant, variable, or expression for the upper boundary of the range.

The RANDOM function returns a random integer between the low and high parameter values, inclusively.  The low and high parameters may be any numeric expression, but only their integer portion is used for the inclusive range.

Return Data Type:  LONG

Example:

LOOP X# = 1 TO 6

  LottoNbr[X#] = RANDOM(1,49)	!Pick numbers for Lotto

END


ROUND  (return rounded number)

ROUND(expression,order)

ROUND	Returns rounded value.

expression	A numeric constant, variable, or expression.

order	A numeric expression with a value equal to a power of ten, such as 1, 10, 100, 0.1, 0.001, etc.  If the value is not an even power of ten, the next lowest power is used; 0.55 will use 0.1 and 155 will use 100.

The ROUND function returns the value of an expression rounded to a power of ten.

Return Data Type:  REAL

Example:

ROUND(5163,100)	returns 5200

ROUND(657.50,1)	returns 658

ROUND(51.63594,.01)	returns 51.64

Commission = ROUND(Price / Rate,.01)	!Round the commission to the nearest cent


SQRT  (return square root)

SQRT(expression)

SQRT	Returns square root.

expression	A numeric constant, variable, or expression.  If the value of the expression is less than zero, the return value is zero.

The SQRT function returns the square root of the expression.  If X represents any positive real number, the square root of X is a number that, when multiplied by itself, produces a product equal to X.

Return Data Type:  REAL

Example:

Length = SQRT(X^2 + Y^2)	!Find the distance from 0,0 to x,y (pythagorean theorem)


Trigonometric Functions

Trigonometric functions return values representing angles and ratios of the sides of a right triangle (a triangle containing a 90-degree angle).  The hypotenuse is the side of the triangle opposite the right (90-degree) angle.  For either of the other two angles, the adjacent side forms the angle with the hypotenuse, and the opposite side is opposite the angle.  (See any good Trigonometry text for further explanation of these terms.)

Angles are expressed in radians.  PI is a constant which represents the ratio of the circumference and radius of a circle.  There are 2*PI radians (or 360 degrees) in a circle.

The following equates provide high precision constants for PI and the conversion factors between degrees and radians.

PI	EQUATE(3.1415926535898)	!The value of PI

Rad2Deg	EQUATE(57.295779513082)	!Number of degrees in a radian

Deg2Rad	EQUATE(.0174532925199)	!Number of radians in a degree

SIN  (return sine)

COS  (return cosine)

TAN  (return tangent)

ASIN  (return arcsine)

ACOS  (return arccosine)

ATAN  (return arctangent)


SIN  (return sine)

SIN(radians)

SIN	Returns sine.

radians	A numeric constant, variable or expression for the angle expressed in radians.

The SIN function returns the trigonometric sine of an angle measured in radians.  The sine is the ratio of the length of the angle's opposite side divided by the length of the hypotenuse.

Return Data Type:  REAL

Example:

Angle = 45 * Deg2Rad	!Translate 45 degrees to Radians

SineAngle = SIN(Angle)	!Get the sine of 45 degree angle


COS  (return cosine)

COS(radians)

COS	Returns cosine.

radians	A numeric constant, variable or expression for the angle in radians.

The COS function returns the trigonometric cosine of an angle measured in radians.  The cosine is the ratio of the length of the angle's adjacent side divided by the length of the hypotenuse.

Return Data Type:  REAL

Example:

Angle = 45 * Deg2Rad	!Translate 45 degrees to Radians

CosineAngle = COS(Angle)	!Get the cosine of 45 degree angle


TAN  (return tangent)

TAN(radians)

TAN	Returns tangent.

radians	A numeric constant, variable or expression for the angle in radians.

The TAN function returns the trigonometric tangent of an angle measured in radians.  The tangent is the ratio of the angle's opposite side divided by its adjacent side.

Return Data Type:  REAL

Example:

Angle = 45 * Deg2Rad	!Translate 45 degrees to Radians

TangentAngle = TAN(Angle)	!Get the tangent of 45 degree angle


ASIN  (return arcsine)

ASIN(expression)

ASIN	Returns inverse sine.

expression	A numeric constant, variable, or expression for the value of the sine.

The ASIN function returns the inverse sine.  The inverse of a sine is the angle that produces the sine.  The return value is the angle in radians.

Return Data Type:  REAL

Example:

InvSine = ASIN(SineAngle)	!Get the Arcsine

See Also:

SIN


ACOS  (return arccosine)

ACOS(expression)

ACOS	Returns inverse cosine.

expression	A numeric constant, variable, or expression for the value of the cosine.

The ACOS function returns the inverse cosine.  The inverse of a cosine is the angle that produces the cosine.  The return value is the angle in radians.

Return Data Type:  REAL

Example:

InvCosine = ACOS(CosineAngle)	!Get the Arccosine

See Also:

COS


ATAN  (return arctangent)

ATAN(expression)

ATAN	Returns inverse tangent.

expression	A numeric constant, variable, or expression for the value of the tangent.

The ATAN function returns the inverse tangent.  The inverse of a tangent is the angle that produces the tangent.  The return value is the angle in radians.

Return Data Type:  REAL

Example:

InvTangent = ATAN(TangentAngle)	!Get the Arctangent

See Also:

TAN


String Functions

ALL  (return repeated characters)

CENTER  (return centered string)

CHR  (return character from ASCII)

CLIP  (return string without trailing spaces)

DEFORMAT  (remove formatting from numeric string)

FORMAT  (format numbers into a picture)

INLIST  (search for entry in list)

INSTRING  (search for substring)

LEFT  (return left justified string)

LEN  (return length of string)

LOWER  (return lower case)

NUMERIC  (check numeric string)

RIGHT  (return right justified string)

SUB  (return substring of string)

UPPER  (return upper case)

VAL  (return ASCII value)


ALL  (return repeated characters)

ALL(string [,length])

ALL	Returns repeated characters.

string	A string expression containing the character sequence to be repeated.

length	The length of the return string.  If omitted the length of the return string is 255 characters.

The ALL function returns a string containing repetitions of the character sequence string.

Return Data Type:  STRING

Example:

Starline = ALL('*',25)	!Get 25 asterisks

Dotline = ALL('.')	!Get 255 dots


CENTER  (return centered string)

CENTER(string [,length])

CENTER	Returns centered string.

string	A string constant, variable or expression.

length	The length of the return string.  If omitted, the length of the string parameter is used.

The CENTER function first removes leading and trailing spaces from a string, then pads it with leading and trailing spaces to center it within the length, and returns a centered string.

Return Data Type:  STRING

Example:

!CENTER('ABC',5)	returns ' ABC '

!CENTER('ABC  ')	returns ' ABC '

!CENTER('  ABC')	returns ' ABC '

  Message = CENTER(Message)	!Center the message

  Rpt:Title = CENTER(Name,60)	!Center the name


CHR  (return character from ASCII)

CHR(code)

CHR	Returns the display character.

code	A numeric expression containing a numeric ASCII character code.

The CHR function returns the character represented by the ASCII character code parameter.

Return Data Type:  STRING

Example:

Stringvar = CHR(122)	!Get lower case z

Stringvar = CHR(65)	!Get upper case A


CLIP  (return string without trailing spaces)

CLIP(string)

CLIP	Removes trailing spaces.

string	A string expression.

The CLIP function removes trailing spaces from a string.  The return string is a substring with no trailing spaces.  CLIP is frequently used with the concatenation operator in string expressions.

Return Data Type:  STRING

Example:

Name = CLIP(Last) & ', ' & CLIP(First) & Init & '.'	!Full name in military order


DEFORMAT  (remove formatting from numeric string)

DEFORMAT(string [,picture])

DEFORMAT	Removes formatting characters from a numeric string.

string	A string expression containing a numeric string.

picture	A picture token or the label of a CSTRING, STRING, or PSTRING variable containing a picture token (CSTRING is more efficient than STRING or PSTRING).  If omitted, the picture for the string parameter is used.  If the string parameter was not declared with a picture token, the return value will contain only characters that are valid for a numeric constant.

The DEFORMAT function removes formatting characters from a numeric string, returning only the numbers contained in the string.

Return Data Type:  STRING

Example:

DialString = 'ATDT1' & DEFORMAT(Phone,@P(###)###-####P) & '<13,10>'

!Get phone number for modem to dial

ClarionDate = DEFORMAT(dBaseDate,@D12)	!Clarion Standard date from yyyymmdd string


FORMAT  (format numbers into a picture)

FORMAT(value,picture)

FORMAT	Returns a formatted numeric string.

value	A numeric expression for the value to be formatted.

picture	A picture token or the label of a STRING, CSTRING, or PSTRING variable containing a picture token (CSTRING is more efficient than STRING or PSTRING).

The FORMAT function returns a numeric string formatted according to the picture parameter.

Return Data Type:  STRING

Example:

Rpt:SocSecNbr = FORMAT(Emp:SSN,@P###-##-####P)

!Format the soc-sec-nbr

Phone = FORMAT(DEFORMAT(Phone,@P###-###-####P),@P(###)###-####P)

!Change phone format from dashes to parens

DateString = FORMAT(DateLong,@D1)	!Format a date as a string


INLIST  (search for entry in list)

INLIST(searchstring,liststring,liststring [,liststring...])

INLIST	Returns item in a list.

searchstring	A constant, variable, or expression that contains the value for which to search.  If the value is numeric, it is converted to a string before comparisons are made.

liststring	The label of a variable or constant value to compare against the searchstring.  If the value is numeric, it is converted to a string before comparisons are made.  There may be any number of liststring parameters, but there must be at least two.

The INLIST function compares the contents of the searchstring against the values contained in each liststring parameter.  If a matching value is found, the function returns the number of the liststring parameter containing the matching value (relative to the first liststring parameter).  If the searchstring is not found in any liststring parameter, INLIST returns zero.

Return Data Type:  LONG

Example:

!INLIST('D','A','B','C','D','E')	returns 4

!INLIST('B','A','B','C','D','E')	returns 2

  EXECUTE INLIST(Emp:Status,'Fulltime','Parttime','Retired','Consultant')

    Scr:Message = 'All Benefits'	!Full timer

    Scr:Message = 'Holidays Only'	!Part timer

    Scr:Message = 'Medical/Dental Only' 	!Retired

    Scr:Message = 'No Benefits'	!Consultant

  END


INSTRING  (search for substring)

INSTRING(substring,string [,step] [,start])

INSTRING	Searches for a substring in a string.

substring	A string constant, variable, or expression that contains the string for which to search.

string	A string constant, or the label of the STRING, CSTRING, or PSTRING variable to be searched.

step	A numeric constant, variable, or expression which specifies the step length of the search.  A step of 1 searches for the substring beginning at every character in the string, a step of 2 starts at every other character, and so on.  If step is omitted, the step length defaults to the length of the substring.

start	A numeric constant, variable, or expression which specifies where to begin the search of the string.  If omitted, the search starts at the first character position.

The INSTRING function steps through a string, searching for the occurrence of a substring.  If the substring is found, the function returns the step number on which the substring was found.  If the substring is not found in the string, INSTRING returns zero.

Return Data Type:  LONG

Example:

!INSTRING('DEF','ABCDEFGHIJ',1,1)	returns 4

!INSTRING('DEF','ABCDEFGHIJ',2,1)	returns 0

!INSTRING('DEF','ABCDEFGHIJ',2,2)	returns 2

!INSTRING('DEF','ABCDEFGHIJ',3,1)	returns 2

  Extension = SUB(FileSpec,INSTRING('.',FileSpec) + 1,3)

!Extract extension from file spec

  IF INSTRING(Search,Cus:Notes,1,1)	!If search variable found

    Scr:Message = 'Found'	!  display message

  END


LEFT  (return left justified string)

LEFT(string [,length])

LEFT	Left justifies a string.

string	A string constant, variable, or expression.

length	A numeric constant, variable, or expression for the length of the return string.  If omitted, length defaults to the length of the string.

The LEFT function returns a left justified string.  Leading spaces are removed from the string.

Return Data Type:  STRING

Example:

CompanyName = LEFT(CompanyName)	!Left justify the company name


LEN  (return length of string)

LEN(string)

LEN	Returns length of a string.

string	A string constant, variable, or expression.

The LEN function returns the length of a string.  If the string parameter is the label of a variable, the function will return the declared length of the variable.  Numeric variables are automatically converted to STRING intermediate values.

Return Data Type:  LONG

Example:

IF LEN(CLIP(Title) & ' ' & CLIP(First) & ' ' & CLIP(Last)) > 30

!If full name won't fit

  Rpt:Name = CLIP(Title) & ' ' & SUB(First,1,1) & '. ' & Last

!  use first initial

ELSE

  Rpt:Name = CLIP(Title) & ' ' & CLIP(First) & ' ' & CLIP(Last)

!  else use full name

END

Rpt:Title = CENTER(Cus:Name,LEN(Rpt:Title))	!Center the name in the title


LOWER  (return lower case)

LOWER(string)

LOWER	Converts a string to all lower case.

string	A string constant, variable, or expression for the string to be converted.

The LOWER function returns a string with all letters converted to lower case.

Return Data Type:  STRING

Example:

Name = SUB(Name,1,1) & LOWER(SUB(Name,2,19))

!Make the rest of the name lower case


NUMERIC  (check numeric string)

NUMERIC(string)

NUMERIC	Validates all numeric string.

string	A string constant, variable, or expression.

The NUMERIC function returns the value 1 (true) if the string contains a valid numeric value.  It returns zero (false) if the string contains non-numeric characters.  Valid numeric characters are the digits 0 through 9, a leading minus sign, and a decimal point.

Return Data Type:  LONG

Example:

IF NOT NUMERIC(PartNumber)	!If part number is not numeric

  DO ChkValidPart	!  check for valid part number

END	!End if


RIGHT  (return right justified string)

RIGHT(string [,length])

RIGHT	Right justifies a string.

string	A string constant, variable, or expression.

length	A numeric constant, variable, or expression for the length of the return string.  If omitted, the length is set to the length of the string.

The RIGHT function returns a right justified string.  Trailing spaces are removed, then the string is right justified and returned with leading spaces.

Return Data Type:  STRING

Example:

Message = RIGHT(Message)	!Right justify the message


SUB  (return substring of string)

SUB(string,position,length)

SUB	Returns a portion of a string.

string	A string constant, variable or expression.

position	A integer constant, variable, or expression.  If positive, it points to a character position relative to the beginning of the string.  If negative, it points to the character position relative to the end of the string (i.e., a position value of -3 points to a position 3 characters from the end of the string).

length	A numeric constant, variable, or expression of number of characters to return.

The SUB function parses out a sub-string from a string by returning length characters from the string, starting at position.

The SUB function is similar to the "string slicing" operation on STRING, CSTRING, and PSTRING variables, but is less flexible and efficient.  "String slicing" is more flexible because it may be used on both the destination and source sides of an assignment statement, while the SUB function can only be used as the source.  It is more efficient because it takes less memory than individual character assignments or the SUB function.

To take a "slice" of a string, the beginning and ending character numbers are separated by a colon (:) and placed in the implicit array dimension position within the square brackets ([]) of the string.  The position numbers may be integer constants, variables, or expressions.  If variables are used, there must be at least one blank space between the variable name and the colon separating the beginning and ending number (to prevent PREfix confusion).

Return Data Type:  STRING

Example:

!SUB('ABCDEFGHI',1,1)	returns 'A'

!SUB('ABCDEFGHI',-1,1)	returns 'I'

!SUB('ABCDEFGHI',4,3)	returns 'DEF'

  Extension = SUB(FileName,INSTRING('.',FileName,1,1)+1,3)

!Get the file extension using SUB function

  Extension = FileName[(INSTRING('.',FileName,1,1)+1) : (INSTRING('.',FileName,1,1)+3)]

!The same operation using string slicing

See Also:

INSTRING

STRING

CSTRING

PSTRING


UPPER  (return upper case)

UPPER(string)

UPPER	Returns all upper case string.

string	A string constant, variable, or expression for the string to be converted.

The UPPER function returns a string with all letters converted to upper case.

Return Data Type:  STRING

Example:

Name = UPPER(Name)	!Make the name upper case


VAL  (return ASCII value)

VAL(character)

VAL	Returns ASCII code.

character	A one-byte string containing a character.

The VAL function returns the ASCII code of a character.

Return Data Type:  LONG

Example:

VAL('A')	returns 65

VAT('z')	returns 122

CharVal = VAL(StrChar)	!Get the ASCII value of the string character


Bit Manipulation Functions

BAND  (return bitwise AND)

BOR  (return bitwise OR)

BXOR  (return bitwise exclusive OR)

BSHIFT  (return shifted bits)


BAND  (return bitwise AND)

BAND(value,mask)

BAND	Performs bitwise AND operation.

value	A numeric constant, variable, or expression for the bit value to be compared to the bit mask.  The value is converted to a LONG data type prior to the operation, if necessary.

mask	A numeric constant, variable, or expression for the bit mask.  The mask is converted to a LONG data type prior to the operation, if necessary.

The BAND function compares the value to the mask, performing a Boolean AND operation on each bit.  The return value is a LONG integer with a one (1) in the bit positions where the value and the mask both contain one (1), and zeroes in all other bit positions.

BAND is usually used to determine whether an individual bit, or multiple bits, are on (1) or off (0) within a variable.

Return Data Type:  LONG

Example:

BAND(0110b,0010b)	returns 0010b	!0110b = 6, 0010b = 2

RateType	BYTE	!Type of rate

Female 	EQUATE(0001b)	!Female mask

Male	EQUATE(0010b)	!Male mask

Over25 	EQUATE(0100b)	!Over age 25 mask

  CODE

  IF BAND(RateType,Female)	|	!If female

      AND BAND(RateType,Over25)	! and over 25

    DO BaseRate	!  use base premium

  ELSIF BAND(RateType,Male)	!If male

    DO AdjBase	!  adjust base premium

  END	!End if


BOR  (return bitwise OR)

BOR(value,mask)

BOR	Performs bitwise OR operation.

value	A numeric constant, variable, or expression for the bit value to be compared to the bit mask.  The value is converted to a LONG data type prior to the operation, if necessary.

mask	A numeric constant, variable, or expression for the bit mask.  The mask is converted to a LONG data type prior to the operation, if necessary.

The BOR function compares the value to the mask, performing a Boolean OR operation on each bit.  The return value is a LONG integer with a one (1) in the bit positions where the value, or the mask, or both, contain a one (1), and zeroes in all other bit positions.

BOR is usually used to unconditionally turn on (set to one), an individual bit, or multiple bits, within a variable.

Return Data Type:  LONG

Example:

BOR(0110b,0010b)	returns 0110b	!0110b = 6, 0010b = 2

RateType	BYTE	!Type of rate

Female 	EQUATE(0001b)	!Female mask

Male 	EQUATE(0010b)	!Male mask

Over25 	EQUATE(0100b)	!Over age 25 mask

  CODE

  RateType = BOR(RateType,Over25)	!Turn on over 25 bit

  RateType = BOR(RateType,Male)	!Set rate to male


BXOR  (return bitwise exclusive OR)

BXOR(value,mask)

BXOR	Performs bitwise exclusive OR operation.

value	A numeric constant, variable, or expression for the bit value to be compared to the bit mask.  The value is converted to a LONG data type prior to the operation, if necessary.

mask	A numeric constant, variable, or expression for the bit mask.  The mask is converted to a LONG data type prior to the operation, if necessary.

The BXOR function compares the value to the mask, performing a Boolean XOR operation on each bit.  The return value is a LONG integer with a one (1) in the bit positions where either the value or the mask contain a one (1), but not both.  Zeroes are returned in all bit positions where the bits in the value and mask are alike.

BXOR is usually used to toggle on (1) or off (0) an individual bit, or multiple bits, within a variable.

Return Data Type:  LONG

Example:

BXOR(0110b,0010b)	returns 0100b	!0110b = 6, 0100b = 4, 0010b = 2

RateType	BYTE	!Type of rate

Female 	EQUATE(0001b)	!Female mask

Male 	EQUATE(0010b)	!Male mask

Over25 	EQUATE(0100b)	!Over age 25 mask

Over65 	EQUATE(1100b)	!Over age 65 mask

  CODE

  RateType = BXOR(RateType,Over65)	!Toggle over 65 bits


BSHIFT  (return shifted bits)

BSHIFT(value,count)

BSHIFT	Perfroms bit shift operation.

value	A numeric constant, variable, or expression.  The value is converted to a LONG data type prior to the operation, if necessary.

count	A numeric constant, variable, or expression for the number of bit positions to be shifted.  If count is positive, value is shifted left.  If count is negative, value is shifted right.

The BSHIFT function shifts a bit value by a bit count.  The bit value may be shifted left (toward the high order), or right (toward the low order).  Zero bits are supplied to fill vacated bit positions when shifting.

Return Data Type:  LONG

Example:

BSHIFT(0110b,1)	returns 1100b

BSHIFT(0110b,-1)	returns 0011b

Varswitch = BSHIFT(20,3)	!Multiply by eight

Varswitch = BSHIFT(Varswitch,-2)	!Divide by four


Date / Time Procedures and Functions

Standard Date

Standard Time

TODAY  (return system date)

SETTODAY  (set system date)

CLOCK  (return system time)

SETCLOCK  (set system time)

DATE  (return standard date)

DAY  (return day of month)

MONTH  (return month of date)

YEAR  (return year of date)

AGE  (return age from base date)


Standard Date

A Clarion standard date is the number of days that have elapsed since December 28, 1800.  The range of accessible dates is from January 1, 1801 (standard date 4) to December 31, 2099 (standard date 109,211).  Date functions will not return correct values outside the limits of this range.  The standard date calendar also adjusts for each leap year within the range of accessible dates.  Dividing a standard date by modulo 7 gives you the day of the week: zero = Sunday, one = Monday, etc.

The LONG data type with a date format (@D) display picture is normally used for a standard date.  The DATE data type is a data format used in the Btrieve Record Manager.  A DATE field is internally converted to LONG containing the Clarion standard date before any mathematical or date function operation is performed.  Therefore, DATE should be used for external Btrieve file compatibility, and LONG should normally be used for other dates.


Standard Time

A Clarion standard time is the number of hundredths of a second that have elapsed since midnight, plus one (1).  The valid range is from 1 (defined as midnight) to 8,640,000 (defined as 11:59:59:99).  A standard time of one is exactly equal to midnight (which allows a zero value to be used to detect no time entered).  Although time is expressed to the nearest hundredth of a second, the system clock is only updated 18.2 times a second (approximately every 5.5 hundredths of a second).

The LONG data type with a time format (@T) display picture is normally used for a standard time.  The TIME data type is a data format used in the Btrieve Record Manager.  A TIME field is internally converted to LONG containing the Clarion standard time before any mathematical or time function operation is performed.  Therefore, TIME should be used for external Btrieve file compatibility, and LONG should normally be used for other times.


TODAY  (return system date)

TODAY( )

The TODAY function returns the DOS system date as a standard date.  The range of possible dates is from January 1, 1801 (standard date 4) to December 31, 2099 (standard date 109,211).

Return Data Type:  LONG

Example:

  OrderDate = TODAY()	!Set the order date to system date


SETTODAY  (set system date)

SETTODAY(date)

SETTODAY	Sets the DOS system date.

date	A numeric constant, variable, or expression for a standard date.

The SETTODAY statement sets the DOS system date.

Example:

SETTODAY(TODAY() + 1)	!Set the date ahead one day


CLOCK  (return system time)

CLOCK( )

The CLOCK function returns the time of day from the DOS system time in standard time (expressed as hundredths of a second since midnight).  Although the time is expressed to the nearest hundredth of a second, the system clock is only updated 18.2 times a second (approximately every 5.5 hundredths of a second).

Return Data Type:  LONG

Example:

Time = CLOCK()	!Save the system time


SETCLOCK  (set system time)

SETCLOCK(time)

SETCLOCK	Sets the DOS system clock.

time	A numeric constant, variable, or expression for a standard time (expressed as hundredths of a second since midnight plus one).

The SETCLOCK statement sets the DOS system time of day.

Example:

SETCLOCK(1)	!Set clock to midnight


DATE  (return standard date)

DATE(month,day,year)

DATE	Return standard date.

month	A numeric constant, variable, or expression for the month.

day	A numeric constant, variable, or expression for the day of the month.

year	A numeric constant, variable or expression for the year.  The valid range for a year value is 00 through 99 (which assumes the range 1900 - 1999), or 1801 through 2099.

The DATE function returns a standard date for a given month, day, and year.  The month and day parameters allow out-of-range values.  A month value of 13 is interpreted as January of the next year.  A day value of 32 in January is interpreted as the first of February.  Consequently, DATE(12,32,87), DATE(13,1,87), and DATE(1,1,88) all produce the same result.

Return Data Type:  LONG

Example:

HireDate = DATE(Hir:Month,Hir:Day,Hir:Year)	!Compute hire date

See Also:

Standard Date


DAY  (return day of month)

DAY(date)

DAY	Returns day of month.

date	A numeric constant, variable, expression, or the label of a STRING, CSTRING, or PSTRING variable declared with a date picture token.  The date must be a standard date.  A variable declared with a date picture token is automatically converted to a standard date intermediate value.

The DAY function computes the day of the month (1 to 31) for a given standard date.

Return Data Type:  LONG

Example:

OutDay = DAY(TODAY())	!Get the day from today's date

DueDay = DAY(TODAY()+2)	!Calculate the return day

See Also:

Standard Date


MONTH  (return month of date)

MONTH(date)

MONTH	Returns month in year.

date	A numeric constant, variable, expression, or the label of a STRING, CSTRING, or PSTRING variable declared with a date picture token.  The date must be a standard date.  A variable declared with a date picture token is automatically converted to a standard date intermediate value.

The MONTH function returns the month of the year (1 to 12) for a given standard date.

Return Data Type:  LONG

Example:

PayMonth = MONTH(DueDate)	!Get the month from the date

See Also:

Standard Date


YEAR  (return year of date)

YEAR(date)

YEAR	Returns the year.

date	A numeric constant, variable, expression, or the label of a string variable declared with a date picture, xcontaining a standard date.  A variable declared with a date picture is automatically converted to a standard date intermediate value.

The YEAR function returns a four digit number for the year of a standard date (1801 to 2099).

Return Data Type:  LONG

Example:

IF YEAR(LastOrd) < YEAR(TODAY())	!If last order date not from this year

  DO StartNewYear	!  start new year to date totals

END

See Also:

Standard Date


AGE  (return age from base date)

AGE(birthdate [,base date])

AGE	Returns elapsed time.

birthdate	A numeric expression for a standard date.

base date	A numeric expression for a standard date.  If this parameter is omitted, the system date from DOS is used for the computation.

The AGE function returns a string containing the time elapsed between two dates.  The age return string is in the following format:

1 to 60 days	- 'nn DAYS'

61 days to 24 months	- 'nn MOS'

2 years to 999 years	- 'nnn YRS'

Return Data Type:  STRING

Example:

Message = Emp:Name & 'is ' & AGE(Emp:DOB,TODAY()) & ' old today.'


DOS Procedures and Functions

COMMAND  (return command line)

MEMORY  (return available memory)

PATH  (return current DOS directory)

RUNCODE  (return DOS exit code)

SETCOMMAND  (set command line parameters)

SETPATH  (change current drive and directory)


COMMAND  (return command line)

COMMAND(flag [,operation])

COMMAND	Returns command line parameters or environment variables.

flag	A string constant or variable containing the parameter for which to search, or the number of the command line parameter to return.

operation	An integer constant or variable in the range of 0 to 3.  If omitted, the default is zero.

The COMMAND function returns the value of the flag parameter from the command line, a configuration file, or the environment.  If the flag is not found, COMMAND returns an empty string.  If the flag is multiply defined, only the first occurrence encountered is returned.

The operation specifies a search of:

3	command line

2	configuration file

1	environment

0	all three, in 3-2-1 order

COMMAND searches for flag=value and returns value.  There must be no blanks between flag, the equal sign, and value.  In the configuration file or environment, everything to the right of the equal sign is returned.  From the command line, the return value terminates at the first comma or blank space.  If a blank or comma is desired in a command line parameter, everything to the right of the equal sign must be enclosed in double quotes (flag="value").

COMMAND will also search the command line for a flag containing a leading slash (/).  If found, COMMAND returns the value of flag without the slash.  If the flag only contains a number, COMMAND returns the parameter at that numbered position on the command line.  A flag of '0' returns the minimum path DOS used to find the command.  This minimum path always includes the command (without command line parameters) but may not include the path (if DOS found it in the current directory).  A flag containing '1' returns the first command line parameter.  If flag is a null string ('') and the operation is 3, all command parameters are returned as entered on the command line, appended to a leading space.

A configuration file allows runtime customization of a program.  It is an ASCII text file which contains any parameters you wish to be able to check at runtime.  Each parameter in the configuration file must be on its own line in the file.  The default filename is the name of the program with an .INI extension.  This may be changed on the command line using CLAINI=newfilename.  CLAINI may not be set using SETCOMMAND.

Return Data Type:  STRING

Example:

C:\>MYPROG CLAVM="EMS,.,16,3,6"	!Command line parameter including commas

C:\>MYPROG CLAINI=INITFILE.INI	!Specify initfile.ini instead of myprog.ini

RUN(COMMAND('COMSPEC',1) & '/C DIR /P')	!Get location of command.com

!  and run DOS command

IF COMMAND('/N',3)	!Was /N on the command line?

  DO SomeProcess

END

IF UPPER(COMMAND('CLAVM',0)) = 'OFF'	!Was virtual memory turned off anywhere?

  DO NoVirtualMem	!  set up program for no virtual memory

ELSE

  DO VirtualMem	!  do some memory intensive pre-processing

END

CommandString = COMMAND('',3)	!Get all command parameters

CommandItself = COMMAND('0',3)	!Get the command itself

SecondParm = COMMAND('2',3)	!Get second parameter from command line

See Also:

SETCOMMAND


MEMORY  (return available memory)

MEMORY([n])

MEMORY	Returns amount of available memory.

n	A numeric constant, variable, or expression.  The valid range is 0 to 4, inclusive.  If omitted, the default value is 0.

The MEMORY function returns the amount of unused memory available, in bytes.  An n value of 0 or 1 returns the amount of conventional memory available, 2 returns the amount of EMS memory available, 3 returns total unused virtual memory, and 4 returns the largest virtual block of memory available.  An out-of-range n value causes a return value of zero.

Return Data Type:  LONG

Example:

SysMem = MEMORY()	!Return amount of unused conventional memory

SysMem = MEMORY(0)	!Return amount of unused conventional memory

SysMem = MEMORY(1)	!Return amount of unused conventional memory

SysMem = MEMORY(2)	!Return amount of unused EMS

SysMem = MEMORY(3)	!Return total unused virtual memory

SysMem = MEMORY(4)	!Return largest virtual block


PATH  (return current DOS directory)

PATH( )

The PATH function returns a string containing the current drive and directory.

Return Data Type:  STRING

Example:

IF PATH() = 'C:\'	!If in the root

  MESSAGE('You are in the Root Directory')	!  display message

END

See Also:

SETPATH


RUNCODE  (return DOS exit code)

RUNCODE( )

The RUNCODE function returns the exit code passed to DOS from the command executed by the RUN statement.  This is the exit code passed by the HALT statement in Clarion programs and is the same as the DOS ERRORLEVEL.  The RUNCODE function's return value is a LONG and may be any value that is returned to DOS as an exit code by the child program.

The child program may only supply DOS with a BYTE value as an exit code, therefore negative values are not possible as DOS exit codes.  This fact allows RUNCODE to reserve these values to handle situations in which an exit code is not available:

 0	normal termination

-1	program terminated with Ctrl-C

-2	program terminated with Critical error

-3	TSR exit

-4	program did not run (check ERROR())

Return Data Type:  LONG

Example:

RUN('Nextprog.exe')	!Run next program

IF RUNCODE() = -4

  IF ERROR() = 'Not Enough Memory'	!If program didn't run for lack of memory

    MESSAGE('Insufficient memory')	!  display a message

    RETURN	!  and terminate the procedure

  ELSE

    STOP(ERROR())	!  terminate program

. .

See Also:

RUN

HALT


SETCOMMAND  (set command line parameters)

SETCOMMAND(commandline)

SETCOMMAND	Internally sets command line parameters.

commandline	A string constant, variable, or expression containing the new command line parameters.

SETCOMMAND allows the program to internally specify command line parameters that may be read by the COMMAND function.  SETCOMMAND overwrites any previous command line flag of the same value.  To turn off a leading slash flag, append an equal sign (=) to it in the commandline.

SETCOMMAND may not be used to set system level switches which must be specified when the program is loaded.  Switches like virtual memory (CLAVM=), or the program's configuration file (CLAINI=) must be set at load time and may not be set with SETCOMMAND.  The temporary files directory switch (CLATMP=) may be set with SETCOMMAND.

Example:

SETCOMMAND(' /N')	!Add /N parameter

SETCOMMAND(' /N=')	!Turn off /N parameter

See Also:

COMMAND


SETPATH  (change current drive and directory)

SETPATH(path)

SETPATH	Changes the current DOS drive and directory.

path	A string constant or the label of a STRING, CSTRING, or PSTRING variable containing a new drive and/or directory specification.

SETPATH changes the current DOS drive and directory.  If the drive and path entry is invalid, the "Path Not Found" error is posted, and the current directory is not changed.

If the drive letter and colon are omitted from the path, the current drive is assumed.  If only a drive letter and colon are in the path, SETPATH changes to the DOS current directory of that drive.

Errors Posted:

03	Path Not Found

Example:

SETPATH('C:\LEDGER')	!Change to the ledger directory

SETPATH(UserPath)	!Change to the user's directory


ADDRESS  (return a memory address)

ADDRESS(	 segment,offset 	 )
 variable
 procedure

ADDRESS	Returns memory address of a variable.

segment	The label of a data element, or an integer variable or constant containing the segment portion of a segment:offset real-mode absolute memory address.

offset	An integer variable or constant containing the offset portion of a segment:offset real-mode absolute memory address.

variable	The label of a data element.

procedure	The label of a PROCEDURE or FUNCTION.

The ADDRESS function returns a LONG integer containing a memory address.  In real mode, the address is returned in the standard segment:offset format. In protected mode, the address of the variable or procedure parameter is returned in selector:offset format, where the selector is a reference into the protected mode lookup table.  The return value (in both modes) may be used by the PEEK and POKE statements.

  ADDRESS(segment,offset)

Returns the protected mode selector:offset for the real mode address specified by the segment and offset parameters.  This allows protected mode direct memory access without incurring a protection violation.

  ADDRESS(variable)

Returns the real or protected mode address of the data element specified by the variable parameter.

  ADDRESS(procedure)

Returns the real or protected mode address of the PROCEDURE or FUNCTION specified by the procedure parameter.

Tha ADDRESS function allows you to pass the address of a variable or procedure to external libraries written in other languages.  If the program is overlaid, the ADDRESS returned will no longer be correct after a RETURN from the procedure/function in which it is used.  This is due to the overlay loader's automatic data segment swapping.

Return Data Type:  LONG

Example:

MAP

  MODULE('External.Obj')	!An external library

    ClarionProc	!A Clarion language procedure

    ExternVarProc(LONG)	!C function receiving variable address

    ExternProc(LONG)	!C function receiving procedure address

. .

Var1	CSTRING(10)	!Define a null-terminated string

DestVar	USHORT	!Destination variable for PEEK

  CODE

  ExternVarProc(ADDRESS(Var1))	!Pass address of Var1 to external procedure

  ExternProc(ADDRESS(ClarionProc))	!Pass address of ClarionProc

  PEEK(ADDRESS(0040h,0017h),DestVar)	!Get keyboard status byte

ClarionProc	PROCEDURE	!A Clarion language procedure

  CODE

  RETURN


BEEP  (sound tone on speaker)

BEEP([frequency] [,duration])

BEEP	Generates a tone through the system speaker.

frequency	A numeric constant, variable, or expression for the frequency of the tone.  If frequency is omitted, the default is 150hz.

duration	A numeric constant, variable, or expression for the length of time (in hundredths of a second) that the tone is generated.  If omitted, the default duration is 16 hundredths of a second.

The BEEP statement generates a tone through the system speaker.  If given a frequency of zero (no sound), BEEP becomes an effective, hardware independent, specific-time pause.

*** ONLY SUPPORTED WITHOUT PARAMETERS AT PRESENT

Example:

IF ERRORCODE()	!If unexpected error

  BEEP(200,100)	!  sound a long beep

  STOP(ERROR())	!  stop for the error

END	!End if

BEEP(0,200)	!Pause for two seconds


ERROR  (return error message)

ERROR( )

The ERROR function returns a string containing a description of any error that was posted.  If no error was posted, ERROR returns an empty string.

Return Data Type:  STRING

Example:

PUT(NameQueue)	!Write the record

IF ERROR() = 'Queue Entry Not Found'	!If not found

  ADD(NameQueue)	!  add new entry

    IF ERRORCODE() THEN STOP(ERROR()).	!Check for unexpected error

END

See Also:

Clarion Keycodes


ERRORCODE  (return error code number)

ERRORCODE( )

The ERRORCODE function returns the code number for any error that was posted.  If no error was posted, ERRORCODE returns zero.

Return Data Type:  LONG

Example:

ADD(Location)	!Add new entry

IF ERRORCODE() = 8	!If not enough memory

  MESSAGE('Out of Memory')	!  display message

END

See Also:

Clarion Keycodes


ERRORFILE  (return error filename)

ERRORFILE( )

The ERRORFILE function returns the filename of the file for which an error was posted.  If the file is open, the full DOS file specification is returned.  If the file is not open, the contents of the FILE statement's NAME attribute is returned.  If the file is not open and the file has no NAME attribute, the label of the FILE statement is returned.  If no error was posted, or the posted error did not involve a file, ERRORFILE returns an empty string.

Return Data Type:  STRING

Example:

ADD(Location)	!Add new entry

IF ERRORCODE()

  MESSAGE('Error with ' & ERRORFILE())	!Display error filename

END

See Also:

Clarion Keycodes


FILEERROR  (return file driver error message)

FILEERROR( file )

The FILEERROR function returns a string containing the "native" error message from the file system (file driver) being used to access a data file.  If no error was posted, FILEERROR returns an empty string.

Return Data Type:  STRING

Example:

PUT(NameFile)	!Write the record

IF FILEERROR()

  MESSAGE(FILERROR())

  RETURN

END

See Also:

FILEERRORCODE


FILEERRORCODE  (return file driver error code number)

FILEERRORCODE( )

The FILEERRORCODE function returns a string containing the code number for the "native" error message from the file system (file driver) being used to access a data file.  If no error was posted, FILEERRORCODE returns an empty string.

Return Data Type:  STRING

Example:

PUT(NameFile)	!Write the record

IF FILEERROR()

  MESSAGE(FILERRORCODE())

  RETURN

END

See Also:

FILEERROR


MAXIMUM  (return maximum subscript value)

MAXIMUM(variable,subscript)

MAXIMUM	Returns maximum subscript value.

variable	The label of a variable declared with a DIM attribute.

subscript	A numeric constant, variable, or expression for the subscript number.  The subscript identifies which array dimension is passed to the function.

The MAXIMUM function returns the maximum subscript value for an explicitly dimensioned variable.  MAXIMUM does not operate on the implicit array dimension of STRING, CSTRING, or PSTRING variables.  This is usually used to determine the size of an array passed as a parameter to a procedure or function.

Return Data Type:  LONG

Example:

Array	BYTE,DIM(10,12)	!Define a two-dimensional array

For the above Array:	MAXIMUM(Array,1)	returns 10

MAXIMUM(Array,2)	returns 12

LOOP X# = 1 TO MAXIMUM(Array,1) 	!Loop until end of 1st dimension

  LOOP Y# = 1 TO MAXIMUM(Array,2) 	!  Loop until end of 2nd dimension

    Array[X#,Y#] = 27	!    Initialize each element to default

. .	!End both loops

See Also:

DIM

Passing Arrays as Parameters


NAME  (return DOS file or device name)

NAME(label)

NAME	Returns name of a file.

label	The label of a FILE declaration.

The NAME function returns a string containing the DOS device name for the structure identified by the label.  For FILE structures, if the file is OPEN, the complete DOS file specification (drive, path, name, and extension) is returned.  If the FILE is closed, the contents of the NAME attribute on the FILE are returned.

Return Data Type:  STRING

Example:

OpenFile = NAME(Customer)	!Save the name of the open file


OMITTED  (check omitted parameters)

OMITTED(position)

OMITTED	Tests for unpassed parameters.

position	An integer constant or variable which specifies the parameter to test.

The OMITTED function tests whether a parameter of a PROCEDURE or FUNCTION was actually passed.  The return value is 1 (true) if the parameter in the specified position was omitted.  The return value is zero (false) if the parameter was passed.  Any position past the last parameter passed is considered omitted.

A parameter may only be omitted if its data type is enclosed in angle brackets ( < > ) in the PROCEDURE or FUNCTION prototype in the MAP structure.

Return Data Type:  LONG

Example:

PROGRAM

MAP

  SomeProc(STRING,<LONG>,STRING)	!Procedure prototype

  SomeFunction(STRING,<LONG>),STRING	!Function prototype

END

  CODE

  SomeProc(Field1,,Field3)

!For this statement:

!	OMITTED(1)	returns 0

!	OMITTED(2)	returns 1

!	OMITTED(3)	returns 0

!	OMITTED(4)	returns 1

SomeProc	PROCEDURE(Field1,Date,Field3)

  CODE

  IF OMITTED(2)	!If date parameter was omitted

    Date = TODAY()	!  substitute the system date

  END

See Also:

FUNCTION and  PROCEDURE Prototypes


DDE Library Reference

Dynamic Data Exchange

Overview

DDE Events

DDE Functions

DDESERVER  (return DDE server channel)

DDECLIENT  (return DDE client channel)

DDEQUERY  (return registered DDE servers)

DDECHANNEL  (return DDE channel number)

DDEAPP  (return server application)

DDEITEM  (return server item)

DDETOPIC  (return server topic)

DDE Procedures

DDEREAD  (get data from DDE server)

DDEWRITE  (provide data to DDE client)

DDEEXECUTE  (send command to DDE server)

DDECLOSE  (terminate DDE server link)


Dynamic Data Exchange

Overview

DDE Events


Overview

Dynamic Data Exchange (DDE) is a very powerful Windows tool that allows a user to access data from another separately executing Windows application.  This allows the user to work with the data in its native format (in the originating application), while ensuring that the application in which the data is used always has the most current values.

DDE is based upon establishing "conversations" (links) between two concurrently executing Windows applications.  One of the applications acts as the DDE server to provide the data, and the other is the DDE client that receives the data.  A single application may be both a DDE client and server, getting data from other applications and providing data to other applications.  Multiple DDE "conversations" can occur concurrently between any given DDE server and client.

To be a DDE server, a Clarion application must:

       _	Open at least one window, since all DDE servers must be associated with a window.

       _	Register with Windows as a DDE server, using the DDESERVER function.

       _	Provide the requested data to the client, using the DDEWRITE statement.

       _	When DDE is no longer required, terminate the link by using the DDECLOSE statement.  You can also allow it to terminate automatically when the user closes the server application or the window that started the link.

To be a DDE client, a Clarion application must:

       _	Open a link to a DDE server as its client, using the DDECLIENT function.

       _	Ask the server for data, using the DDEREAD stateemnt, or ask the server for a service using the DDEEXECUTE statement.

       _	When DDE is no longer required, terminate the link by using the DDECLOSE statement.  You can also allow it to terminate automatically when the user closes the client window or application.

The DDE process posts DDE-specific field-independent events to the ACCEPT loop of the window that opened the link between applications, either as a server or client.


DDE Events

The DDE process is governed by several field-independent events specific to DDE.  These events are posted to the ACCEPT loop of the window that opened the link between applications, either as a server or client.

The following events are posted only to a Clarion server application:

EVENT:DDErequest

A client has requested a data item.

EVENT:DDEadvise

A client has requested continuous updates of a data item.

EVENT:DDEcommand

A client has executed a DDEEXECUTE statement.

The following events are posted only to a Clarion client application:

EVENT:DDEdata

A server has supplied an updated data item.

EVENT:DDEclose

A server has terminated the DDE link.

When one of these DDE events occur there are several functions that tell you what posted the event:

       _	DDECHANNEL() returns the handle of the DDE server or client.

       _	DDEITEM() returns the item or command string passed to the server by the DDEREAD or DDEEXECUTE statements.

       _	DDEPAPP() returns the name of the application.

       _	DDETOPIC() returns the name of the topic.

When a Clarion program creates a DDE server, external clients can link to this server and request data.  Each data request is accompanied by a string (in some specific format which the server program knows) indicating the required data item.  If the Clarion server already knows the value for a given item, it supplies it to the client automatically without generating any events.  If it doesn't, an EVENT:DDErequest or EVENT:DDEadvise event is posted to the server window's ACCEPT loop.

When a Clarion program creates a DDE client, it can link to external servers which can provide data.  When the server first provides the value for a given item, it supplies it to the client automatically without generating any events.  If the client has established a "hot" link with the server, an EVENT:DDEdata event is posted to the client window's ACCEPT loop whenever the server posts a new value for the data item.


DDE Functions

DDESERVER  (return DDE server channel)

DDECLIENT  (return DDE client channel)

DDEQUERY  (return registered DDE servers)

DDECHANNEL  (return DDE channel number)

DDEAPP  (return server application)

DDEITEM  (return server item)

DDETOPIC  (return server topic)


DDESERVER  (return DDE server channel)

DDESERVER( [ application ] [, topic ] )

DDESERVER	Returns a new DDE server channel number.

application	A string constant or variable containing the name of the application.  Usually, this is the name of the application.  If omitted, the filename of the application (without extension) is used.

topic	A string constant or variable containing the name of the application-specific topic.  If omitted, the application will respond to any data request.

The DDESERVER function returns a new DDE server channel number for the application and topic.  The channel number specifies a topic for which the application will provide data.  This allows a single Clarion application to register as a DDE server for multiple topics.

Return Data Type:  LONG

Example:

DDERetVal	STRING(20)

WinOne	WINDOW,AT(0,0,160,400)

  ENTRY(@s20),USE(DDERetVal)

END

MyServer	LONG

  CODE

  OPEN(WinOne)

  MyServer = DDESERVER('MyApp','DataEntered')  !Open as server

  ACCEPT

    CASE EVENT()

    OF EVENT:DDErequest	!As server for data requested once

      DDEWRITE(MyServer,DDE:manual,'DataEntered',DDERetVal)  !Provide data once

    OF EVENT:DDEadvise	!As server for constant update request

      DDEWRITE(MyServer,15,'DataEntered',DDERetVal)

!Check for change every 15 seconds

!  and provide data whenever changed

    END

  END

See Also:

DDECLIENT

DDEWRITE


DDECLIENT  (return DDE client channel)

DDECLIENT( [ application ] [, topic ] )

DDECLIENT	Returns a new DDE client channel number.

application	A string constant or variable containing the name of the server application to link to.  Usually, this is the name of the application.  If omitted, the first DDE server application available is used.

topic	A string constant or variable containing the name of the application-specific topic.  If omitted, the first topic available in the application is used.

The DDECLIENT function returns a new DDE client channel number for the application and topic.  If the application is not currently executing, DDECLIENT returns zero (0).

Typically, when opening a DDE channel as the client, the application is the name of the server application.  The topic is a string that the application has either registered with Windows as a valid topic for the application, or represents some value that tells the application what data to provide.  You can use the DDEQUERY function to determine the applications and topics currently registered with Windows.

Return Data Type:  LONG

Example:

DDEReadVal	REAL

WinOne	WINDOW,AT(0,0,160,400)

  ENTRY(@s20),USE(DDEReadVal)

END

ExcelServer	LONG

  CODE

  OPEN(WinOne)

  ExcelServer = DDECLIENT('Excel','MySheet.XLS')  !Open as client to Excel spreadsheet

  IF NOT ExcelServer	!If the server is not running

    MESSAGE('Please start Excel')  	!alert the user to start it

    RETURN	! and try again

  END

  DDEREAD(ExcelServer,DDE:auto,'R5C5',DDEReadVal)

  ACCEPT

    CASE EVENT()

    OF EVENT:DDEdata	!As changed data comes from Excel

      PassedData(DDEReadVal)	! process the new data

    END

  END

See Also:

DDEQUERY

DDEWRITE

DDESERVER


DDEQUERY  (return registered DDE servers)

DDEQUERY( [ application ] [, topic ] )

DDEQUERY	Returns currently executing DDE servers.

application	A string constant or variable containing the name of the application to query.  For most applications, this is the name of the application.  If omitted, all registered applications registered with the specified topic are returned.

topic	A string constant or variable containing the name of the application-specific topic to query.  If omitted, all topics for the application are returned.

The DDEQUERY function returns a string containing the names of the currently available DDE server applications and their topics.

If the topic parameter is omitted, all topics for the specified application are returned.  If the application parameter is omitted, all registered applications registered with the specified topic are returned.  If both parameters are omitted, DDEQUERY returns all currently available DDE servers.

The format of the data in the return string is application:topic and it can contain multiple application and topic pairs delimited by commas (for example, 'Excel:MySheet.XLS,ClarionApp:DataFile.DAT').

Return Data Type:  STRING

Example:

!This example code does not handle DDEADVISE

WinOne	WINDOW,AT(0,0,160,400)

END

SomeServer	LONG

ServerString STRING(200)

  CODE

  OPEN(WinOne)

  LOOP

    ServerString = DDEQUERY()	!Return all registered servers

    IF NOT INSTRING('SomeApp:MyTopic',ServerString,1,1)

      MESSAGE('Open SomeApp, Please')

    ELSE

      BREAK

    END

  END

  SomeServer = DDECLIENT('SomeApp','MyTopic')  !Open as client

  ACCEPT

  END

  DDECLOSE(SomeServer)


DDECHANNEL  (return DDE channel number)

DDECHANNEL( )

The DDECHANNEL function returns a LONG integer containing the channel number of the DDE client or server application that has just posted a DDE event.  This is the same value returned by the DDESERVER or DDECLIENT function when the DDE channel is established.

Return Data Type:  LONG

Example:

WinOne	WINDOW,AT(0,0,160,400)

END

TimeServer	LONG

DateServer	LONG

FormatTime	STRING(5)

FormatDate	STRING(8)

  CODE

  OPEN(WinOne)

  TimeServer = DDESERVER('SomeApp','Time')  !Open as server

  DateServer = DDESERVER('SomeApp','Date')  !Open as server

  ACCEPT

    CASE EVENT()

    OF EVENT:DDErequest

      CASE DDECHANNEL()

      OF TimeServer

        FormatTime = FORMAT(CLOCK(),@T1)

        DDEWRITE(TimeServer,DDE:manual,'Time',FormatTime)

      OF DateServer

        FormatDate = FORMAT(TODAY(),@D1)

        DDEWRITE(DateServer,DDE:manual,'Date',FormatDate)

      END

    END

  END


DDEAPP  (return server application)

DDEAPP( )

The DDEAPP function returns a string containing the application name in the DDE channel that has just posted a DDE event.  This is usually the same as the first parameter to the DDESERVER or DDECLIENT function when the DDE channel is established.

Return Data Type:  STRING

Example:

ClientApp	STRING(20)

WinOne	WINDOW,AT(0,0,160,400)

  STRING(@S20),AT(5,5,90,20),USE(ClientApp)

END

TimeServer	LONG

DateServer	LONG

FormatTime	STRING(5)

FormatDate	STRING(8)

  CODE

  OPEN(WinOne)

  TimeServer = DDESERVER('SomeApp','Time')  !Open as server

  DateServer = DDESERVER('SomeApp','Date')  !Open as server

  ACCEPT

    CASE EVENT()

    OF EVENT:DDErequest

      CASE DDECHANNEL()

      OF TimeServer

        ClientApp = DDEAPP()	!Get client's name

        DISPLAY	! and display on screen

        FormatTime = FORMAT(CLOCK(),@T1)

        DDEWRITE(TimeServer,DDE:manual,'Time',FormatTime)

      OF DateServer

        ClientApp = DDEAPP()	!Get client's name

        DISPLAY	! and display on screen

        FormatDate = FORMAT(TODAY(),@D1)

        DDEWRITE(DateServer,DDE:manual,'Date',FormatDate)

      END

    END

  END


DDEITEM  (return server item)

DDEITEM( )

The DDEITEM function returns a string containing the name of the item for the current DDE event.  This is the item requested by a DDEREAD, or the command to execute from a DDEEXECUTE statement.

Return Data Type:  STRING

Example:

WinOne	WINDOW,AT(0,0,160,400)

END

Server	LONG

FormatTime	STRING(5)

FormatDate	STRING(8)

  CODE

  OPEN(WinOne)

  Server = DDESERVER('SomeApp','Clock')  !Open as server for my topic

  ACCEPT

    CASE EVENT()

    OF EVENT:DDErequest

      CASE DDEITEM()

      OF 'Time'

        FormatTime = FORMAT(CLOCK(),@T1)

        DDEWRITE(Server,DDE:manual,'Time',FormatTime)

      OF 'Date'

        FormatDate = FORMAT(TODAY(),@D1)

        DDEWRITE(Server,DDE:manual,'Date',FormatDate)

      END

    OF EVENT:DDEadvise

      CASE DDEITEM()

      OF 'Time'

        FormatTime = FORMAT(CLOCK(),@T1)

        DDEWRITE(Server,1,'Time',FormatTime)

      OF 'Date'

        FormatDate = FORMAT(TODAY(),@D1)

        DDEWRITE(Server,60,'Date',FormatDate)

      END

    END

  END

See Also:

DDEREAD

DDEEXECUTE


DDETOPIC  (return server topic)

DDETOPIC( )

The DDETOPIC function returns a string containing the topic name for the DDE channel that has just posted a DDE event.

Return Data Type:  STRING

Example:

WinOne	WINDOW,AT(0,0,160,400)

END

TimeServer	LONG

DateServer	LONG

FormatTime	STRING(5)

FormatDate	STRING(8)

  CODE

  OPEN(WinOne)

  TimeServer = DDESERVER('SomeApp')	!Open as server

  ACCEPT

    CASE EVENT()

    OF EVENT:DDErequest

      CASE DDETOPIC()	!Get requested topic

      OF 'Time'

        FormatTime = FORMAT(CLOCK(),@T1)

        DDEWRITE(TimeServer,DDE:manual,'Time',FormatTime)

      OF 'Date'

        FormatDate = FORMAT(TODAY(),@D1)

        DDEWRITE(DateServer,DDE:manual,'Date',FormatDate)

      END

    END

  END

See Also:

DDEREAD


DDE Procedures

DDEREAD  (get data from DDE server)

DDEWRITE  (provide data to DDE client)

DDEEXECUTE  (send command to DDE server)

DDECLOSE  (terminate DDE server link)


DDEREAD  (get data from DDE server)

DDEREAD( channel, mode, item [, variable ] )

DDEREAD	Gets data from a previously opened DDE client channel.

channel	A LONG integer constant or variable containing the client channel the value returned by the DDECLIENT function.

mode	An EQUATE defining the type of data link: DDE:auto, DDE:manual, or DDE:remove (defined in EQUATES.CLW).

item	A string constant or variable containing the application-specific name of the data item to retrieve.

variable	The name of the variable to receive the retrieved data.  If omitted and mode is DDE:remove, all links to the item are canceled.

The DDEREAD procedure allows a DDE client program to read data from the channel into the variable.  The type of update is determined by the mode parameter.  The item parameter supplies some string value to the server application that tells it what specific data item is being requested.  The format and structure of the item string is dependent upon the server application.

If the mode is DDE:auto, the variable is continually updated by the server (a "hot" link).  If the mode is DDE:manual, the variable is updated once and another DDEREAD request must be sent to the server to check for any changed value (a "cold" link).  If the mode is DDE:remove, a previous "hot" link to the variable is terminated.  If the mode is DDE:remove and variable is omitted, all previous "hot" links to the item are terminated, no matter what variables were linked.  This means the client must send another DDEREAD request to the server to check for any changed value.

Errors Posted:

*** WHAT ERRORS DOES IT POST??

Events Generated:

  These events are posted to the client application:

EVENT:DDEdata

A server has supplied an updated data item for a hot link.

EVENT:DDEclose

A server has terminated the DDE link.

Example:

WinOne	WINDOW,AT(0,0,160,400)

END

ExcelServer	LONG(0)

DDEReadVal	REAL

  CODE

  OPEN(WinOne)

  ExcelServer = DDECLIENT('Excel','MySheet.XLS')  !Open as client to Excel spreadsheet

  IF NOT ExcelServer	!If the server is not running

    MESSAGE('Please start Excel')	! alert the user to start it

    CLOSE(WinOne)

    RETURN

  END

  END

  DDEREAD(ExcelServer,DDE:auto,'R5C5',DDEReadVal) !Request continual update from server

  ACCEPT

    CASE EVENT()

    OF EVENT:DDEdata	!As changed data comes from Excel

      PassedData(DDEReadVal)	! call proc to process the new data

    END

  END

See Also:

DDEQUERY

DDEWRITE


DDEWRITE  (provide data to DDE client)

DDEWRITE( channel, mode, item [, variable ] )

DDEWRITE	Provide data to an open DDE server channel.

channel	A LONG integer constant or variable containing the server channel the value returned by the DDESERVER function.

mode	An integer constant or variable containing the interval (in seconds) to poll for changes to the variable, or an EQUATE defining the type of data link: DDE:auto, DDE:manual, or DDE:remove (defined in EQUATES.CLW).

item	A string constant or variable containing the application-specific name of the data item to provide.

variable	The name of the variable providing the data.  If omitted and mode is DDE:remove, all links to the item are canceled.

The DDEWRITE procedure allows a DDE server program to provide the variable's data to the client.  The item parameter supplies a string value that identifies the specific data item being provided.  The format and structure of the item string is dependent upon the server application.  The type of update performed is determined by the mode parameter.

If the mode is DDE:auto, the client program receives the current value of the variable and the internal libraries continue to provide that value whenever the client (or any other client) asks for it again.  If the client requested a "hot" link, any changes to the variable should be tracked by the Clarion program so it can issue a new DDEWRITE statement to update the client with the new value.

If the mode is DDE:manual, the variable is updated only once.  If the client requested a "hot" link, any changes to the variable should be tracked by the Clarion program so it can issue a new DDEWRITE statement to update the client with the new value.

If the mode is a positive integer, the internal libraries check the value of the variable whenever the specified number of seconds has passed.  If the value has changed, the client is automatically updated with the new value by the internal libraries (without the need for any further Clarion code).  This can incur significant overhead, depending upon the data, and so should be used only when necessary.

If the mode is DDE:remove, any previous "hot" link to the variable is terminated.  If the mode is DDE:remove and variable is omitted, all previous "hot" links to the item are terminated, no matter what variables were linked.  This means the client must send another DDEREAD request to the server to check for any changed value.

Events Generated:

EVENT:DDErequest

A client has requested a data item (a "cold" link).

EVENT:DDEadvise

A client has requested continuous updates of a data item (a "hot" link).

Example:

DDERetVal	STRING(20)

WinOne	WINDOW,AT(0,0,160,400)

  ENTRY(@s20),USE(DDERetVal)

END

MyServer	LONG

  CODE

  OPEN(WinOne)

  MyServer = DDESERVER('MyApp','DataEntered')  !Open as server

  ACCEPT

    CASE EVENT()

    OF EVENT:DDErequest	!As server for data requested once

      DDEWRITE(MyServer,DDE:manual,'DataEntered',DDERetVal)  !Provide data once

    OF EVENT:DDEadvise	!As server for constant update request

      DDEWRITE(MyServer,15,'DataEntered',DDERetVal)

!Check for change every 15 seconds

!  and provide data whenever changed

    END

  END

See Also:

DDEQUERY

DDEREAD


DDEEXECUTE  (send command to DDE server)

DDEEXECUTE( channel, command )

DDEEXECUTE	Sends a command string to an open DDE client channel.

channel	A LONG integer constant or variable containing the client channel the value returned by the DDECLIENT function.

command	A string constant or variable containing the application-specific command for the server to execute.

The DDEEXECUTE procedure allows a DDE client program to communicate a command to the server.  The command must be in a format the server application can recognize and act on.  The server does not need to be a Clarion program.  A Clarion server can use the DDEITEM() function to determine what the client has sent.

There are some conventions:  *** PUT IN THE COMMAND CONVENTIONS HERE AND RE-WRIT THE EXAMPLE CODE.

Events Generated:

EVENT:DDEcommand

A client has sent a command.

Example:

!The server application's code contains:

WinOne	WINDOW,AT(0,0,160,400)

END

SomeServer	LONG

DDEChannel	LONG

  CODE

  OPEN(WinOne)

  DDEChannel = DDECLIENT('PROGMAN','PROGMAN')

!Open a channel to Windows Program Manager

  DDEEXECUTE(DDEChannel,'[CreateGroup(Clarion Applications)]')

!Create a new program group

  DDEEXECUTE(DDEChannel,'[ShowGroup(1)]')

!Display it

  DDEEXECUTE(DDEChannel,'[AddItem(MYAPP.EXE,My Program,PROGMAN.EXE,2)]')

!Create new item in the group

! using second icon in progman.exe


DDECLOSE  (terminate DDE server link)

DDECLOSE( channel )

DDECLOSE	Closes an open DDE channel.

channel	The label of the LONG integer variable containing the channel number the value returned by the DDESERVER or DDECLIENT function.

The DDECLOSE procedure allows a DDE client program to terminate the specified channel.  A channel is automatically terminated when the window which opened the channel is closed.

Example:

WinOne	WINDOW,AT(0,0,160,400)

END

SomeServer	LONG

  CODE

  OPEN(WinOne)

  SomeServer = DDECLIENT('SomeApp','MyTopic')  !Open as client

  ACCEPT

  END

  DDECLOSE(SomeServer)


  Keycodes

Clarion Keycodes

Windows Keycode Mapping Format

KEYCODES.CLW


Clarion Keycodes

Windows Keycode Mapping Format

KEYCODES.CLW


Windows Keycode Mapping Format

Each key on the keyboard is assigned a keycode.  Keycodes are 16-bit values where the low-order 8 bits (values from 0 to 255) represent the key that was pressed, and the high-order 8 bits indicate the state of the Shift, Ctrl, and Alt keys.  Keycodes are returned by the KEYCODE() and KEYBOARD() functions, and use the following format:

Bits:   10   9   8  7         0

 ..

CODE 	- The Key pressed

A 	- Alt key bit

 	C 	- Ctrl key bit

 	S 	- Shift key bit

Calculating a keycode's numeric value is generally unnecessary, since most of the possible key combinations are listed as EQUATES in KEYCODES.CLW (INCLUDE this file and use the equates instead of the numbers).  The contents of KEYCODES.CLW are listed in Appendix A.


KEYCODES.CLW

Keycode equate labels assign mnemonic labels to Clarion keycodes.  The keycode equates file (KEYCODES.CLW) is a Clarion source file which contains an EQUATE statement for each keycode.  This file is located in the directory in which you installed Clarion Database Developer.  It may be merged into a source PROGRAM with the statement:  INCLUDE('KEYCODES.CLW').

This file contains EQUATE statements for all the keycodes:

Key0             EQUATE(0030H)                    !0 Key

Key1             EQUATE(0031H)                    !1 Key

Key2             EQUATE(0032H)                    !2 Key

Key3             EQUATE(0033H)                    !3 Key

Key4             EQUATE(0034H)                    !4 Key

Key5             EQUATE(0035H)                    !5 Key

Key6             EQUATE(0036H)                    !6 Key

Key7             EQUATE(0037H)                    !7 Key

Key8             EQUATE(0038H)                    !8 Key

Key9             EQUATE(0039H)                    !9 Key

AKey             EQUATE(0041H)                    !A Key

BKey             EQUATE(0042H)                    !B Key

CKey             EQUATE(0043H)                    !C Key

DKey             EQUATE(0044H)                    !D Key

EKey             EQUATE(0045H)                    !E Key

FKey             EQUATE(0046H)                    !F Key

GKey             EQUATE(0047H)                    !G Key

HKey             EQUATE(0048H)                    !H Key

IKey             EQUATE(0049H)                    !I Key

JKey             EQUATE(004AH)                    !J Key

KKey             EQUATE(004BH)                    !K Key

LKey             EQUATE(004CH)                    !L Key

MKey             EQUATE(004DH)                    !M Key

NKey             EQUATE(004EH)                    !N Key

OKey             EQUATE(004FH)                    !O Key

PKey             EQUATE(0050H)                    !P Key

QKey             EQUATE(0051H)                    !Q Key

RKey             EQUATE(0052H)                    !R Key

SKey             EQUATE(0053H)                    !S Key

TKey             EQUATE(0054H)                    !T Key

UKey             EQUATE(0055H)                    !U Key

VKey             EQUATE(0056H)                    !V Key

WKey             EQUATE(0057H)                    !W Key

XKey             EQUATE(0058H)                    !X Key

YKey             EQUATE(0059H)                    !Y Key

ZKey             EQUATE(005AH)                    !Z Key

F1Key            EQUATE(0070H)                    !F1 Key

F2Key            EQUATE(0071H)                    !F2 Key

F3Key            EQUATE(0072H)                    !F3 Key

F4Key            EQUATE(0073H)                    !F4 Key

F5Key            EQUATE(0074H)                    !F5 Key

F6Key            EQUATE(0075H)                    !F6 Key

F7Key            EQUATE(0076H)                    !F7 Key

F8Key            EQUATE(0077H)                    !F8 Key

F9Key            EQUATE(0078H)                    !F9 Key

F10Key           EQUATE(0079H)                    !F10 Key

F11Key           EQUATE(007AH)                    !F11 Key

F12Key           EQUATE(007BH)                    !F12 Key

AstKey           EQUATE(006AH)                    !Asterisk Key

BSKey            EQUATE(0008H)                    !Backspace Key

CapsLockKey      EQUATE(0014H)                    !CapsLock Key

DecimalKey       EQUATE(006EH)                    !Decimal Key

DeleteKey        EQUATE(002EH)                    !Delete Key

DivideKey        EQUATE(006FH)                    !Divide Key

DownKey          EQUATE(0028H)                    !Cursor Down Key

EndKey           EQUATE(0023H)                    !End Key

EnterKey         EQUATE(000DH)                    !Enter Key

EscKey           EQUATE(001BH)                    !Esc Key

HomeKey          EQUATE(0024H)                    !Home Key

InsertKey        EQUATE(002DH)                    !Insert Key

LeftKey          EQUATE(0025H)                    !Cursor Left Key

MinusKey         EQUATE(006DH)                    !Minus Key

PauseKey         EQUATE(0013H)                    !Pause Key

PgDnKey          EQUATE(0022H)                    !PgDn Key

PgUpKey          EQUATE(0021H)                    !PgUp Key

PlusKey          EQUATE(006BH)                    !Plus Key

PrintKey         EQUATE(002CH)                    !PrintScreen Key

RightKey         EQUATE(0027H)                    !Cursor Right Key

SlashKey         EQUATE(006FH)                    !Slash Key

SpaceKey         EQUATE(0020H)                    !Spacebar

TabKey           EQUATE(0009H)                    !Tab Key

UpKey            EQUATE(0026H)                    !Cursor Up Key

KeyPad0          EQUATE(0060H)                    !0 on numeric keypad

KeyPad1          EQUATE(0061H)                    !1 on numeric keypad

KeyPad2          EQUATE(0062H)                    !2 on numeric keypad

KeyPad3          EQUATE(0063H)                    !3 on numeric keypad

KeyPad4          EQUATE(0064H)                    !4 on numeric keypad

KeyPad5          EQUATE(0065H)                    !5 on numeric keypad

KeyPad6          EQUATE(0066H)                    !6 on numeric keypad

KeyPad7          EQUATE(0067H)                    !7 on numeric keypad

KeyPad8          EQUATE(0068H)                    !8 on numeric keypad

KeyPad9          EQUATE(0069H)                    !9 on numeric keypad

MouseLeft        EQUATE(0001H)                    !Left mouse button

MouseRight       EQUATE(0002H)                    !Right mouse button

MouseCenter      EQUATE(0004H)                    !Middle mouse button

Alt0             EQUATE(0430H)                    !Alt0 Key

Alt1             EQUATE(0431H)                    !Alt1 Key

Alt2             EQUATE(0432H)                    !Alt2 Key

Alt3             EQUATE(0433H)                    !Alt3 Key

Alt4             EQUATE(0434H)                    !Alt4 Key

Alt5             EQUATE(0435H)                    !Alt5 Key

Alt6             EQUATE(0436H)                    !Alt6 Key

Alt7             EQUATE(0437H)                    !Alt7 Key

Alt8             EQUATE(0438H)                    !Alt8 Key

Alt9             EQUATE(0439H)                    !Alt9 Key

AltA             EQUATE(0441H)                    !AltA Key

AltB             EQUATE(0442H)                    !AltB Key

AltC             EQUATE(0443H)                    !AltC Key

AltD             EQUATE(0444H)                    !AltD Key

AltE             EQUATE(0445H)                    !AltE Key

AltF             EQUATE(0446H)                    !AltF Key

AltG             EQUATE(0447H)                    !AltG Key

AltH             EQUATE(0448H)                    !AltH Key

AltI             EQUATE(0449H)                    !AltI Key

AltJ             EQUATE(044AH)                    !AltJ Key

AltK             EQUATE(044BH)                    !AltK Key

AltL             EQUATE(044CH)                    !AltL Key

AltM             EQUATE(044DH)                    !AltM Key

AltN             EQUATE(044EH)                    !AltN Key

AltO             EQUATE(044FH)                    !AltO Key

AltP             EQUATE(0450H)                    !AltP Key

AltQ             EQUATE(0451H)                    !AltQ Key

AltR             EQUATE(0452H)                    !AltR Key

AltS             EQUATE(0453H)                    !AltS Key

AltT             EQUATE(0454H)                    !AltT Key

AltU             EQUATE(0455H)                    !AltU Key

AltV             EQUATE(0456H)                    !AltV Key

AltW             EQUATE(0457H)                    !AltW Key

AltX             EQUATE(0458H)                    !AltX Key

AltY             EQUATE(0459H)                    !AltY Key

AltZ             EQUATE(045AH)                    !AltZ Key

AltF1            EQUATE(0470H)                    !AltF1 Key

AltF2            EQUATE(0471H)                    !AltF2 Key

AltF3            EQUATE(0472H)                    !AltF3 Key

AltF4            EQUATE(0473H)                    !AltF4 Key

AltF5            EQUATE(0474H)                    !AltF5 Key

AltF6            EQUATE(0475H)                    !AltF6 Key

AltF7            EQUATE(0476H)                    !AltF7 Key

AltF8            EQUATE(0477H)                    !AltF8 Key

AltF9            EQUATE(0478H)                    !AltF9 Key

AltF10           EQUATE(0479H)                    !AltF10 Key

AltF11           EQUATE(047AH)                    !AltF11 Key

AltF12           EQUATE(047BH)                    !AltF12 Key

AltAst           EQUATE(046AH)                    !AltAsterisk Key

AltBS            EQUATE(0408H)                    !AltBackspace Key

AltDecimal       EQUATE(046EH)                    !AltDecimal Key

AltDelete        EQUATE(042EH)                    !AltDelete Key

AltDivide        EQUATE(046FH)                    !AltDivide Key

AltDown          EQUATE(0428H)                    !AltCursor Down Key

AltEnd           EQUATE(0423H)                    !AltEnd Key

AltEnter         EQUATE(040DH)                    !AltEnter Key

AltEsc           EQUATE(041BH)                    !AltEsc Key

AltHome          EQUATE(0424H)                    !AltHome Key

AltInsert        EQUATE(042DH)                    !AltInsert Key

AltLeft          EQUATE(0425H)                    !AltCursor Left Key

AltMinus         EQUATE(046DH)                    !AltMinus Key

AltPause         EQUATE(0413H)                    !AltPause Key

AltPgDn          EQUATE(0422H)                    !AltPgDn Key

AltPgUp          EQUATE(0421H)                    !AltPgUp Key

AltPlus          EQUATE(046BH)                    !AltPlus Key

AltPrint         EQUATE(042CH)                    !AltPrintScreen Key

AltRight         EQUATE(0427H)                    !AltCursor Right Key

AltSlash         EQUATE(046FH)                    !AltSlash Key

AltSpace         EQUATE(0420H)                    !AltSpacebar

AltTab           EQUATE(0409H)                    !AltTab Key

AltUp            EQUATE(0426H)                    !AltCursor Up Key

AltPad0          EQUATE(0460H)                    !Alt0 on numeric keypad

AltPad1          EQUATE(0461H)                    !Alt1 on numeric keypad

AltPad2          EQUATE(0462H)                    !Alt2 on numeric keypad

AltPad3          EQUATE(0463H)                    !Alt3 on numeric keypad

AltPad4          EQUATE(0464H)                    !Alt4 on numeric keypad

AltPad5          EQUATE(0465H)                    !Alt5 on numeric keypad

AltPad6          EQUATE(0466H)                    !Alt6 on numeric keypad

AltPad7          EQUATE(0467H)                    !Alt7 on numeric keypad

AltPad8          EQUATE(0468H)                    !Alt8 on numeric keypad

AltPad9          EQUATE(0469H)                    !Alt9 on numeric keypad

AltMouseLeft     EQUATE(0401H)                    !AltLeft mouse button

AltMouseRight    EQUATE(0402H)                    !AltRight mouse button

AltMouseCenter   EQUATE(0404H)                    !AltMiddle mouse button

Ctrl0            EQUATE(0230H)                    !Ctrl0 Key

Ctrl1            EQUATE(0231H)                    !Ctrl1 Key

Ctrl2            EQUATE(0232H)                    !Ctrl2 Key

Ctrl3            EQUATE(0233H)                    !Ctrl3 Key

Ctrl4            EQUATE(0234H)                    !Ctrl4 Key

Ctrl5            EQUATE(0235H)                    !Ctrl5 Key

Ctrl6            EQUATE(0236H)                    !Ctrl6 Key

Ctrl7            EQUATE(0237H)                    !Ctrl7 Key

Ctrl8            EQUATE(0238H)                    !Ctrl8 Key

Ctrl9            EQUATE(0239H)                    !Ctrl9 Key

CtrlA            EQUATE(0241H)                    !CtrlA Key

CtrlB            EQUATE(0242H)                    !CtrlB Key

CtrlC            EQUATE(0243H)                    !CtrlC Key

CtrlD            EQUATE(0244H)                    !CtrlD Key

CtrlE            EQUATE(0245H)                    !CtrlE Key

CtrlF            EQUATE(0246H)                    !CtrlF Key

CtrlG            EQUATE(0247H)                    !CtrlG Key

CtrlH            EQUATE(0248H)                    !CtrlH Key

CtrlI            EQUATE(0249H)                    !CtrlI Key

CtrlJ            EQUATE(024AH)                    !CtrlJ Key

CtrlK            EQUATE(024BH)                    !CtrlK Key

CtrlL            EQUATE(024CH)                    !CtrlL Key

CtrlM            EQUATE(024DH)                    !CtrlM Key

CtrlN            EQUATE(024EH)                    !CtrlN Key

CtrlO            EQUATE(024FH)                    !CtrlO Key

CtrlP            EQUATE(0250H)                    !CtrlP Key

CtrlQ            EQUATE(0251H)                    !CtrlQ Key

CtrlR            EQUATE(0252H)                    !CtrlR Key

CtrlS            EQUATE(0253H)                    !CtrlS Key

CtrlT            EQUATE(0254H)                    !CtrlT Key

CtrlU            EQUATE(0255H)                    !CtrlU Key

CtrlV            EQUATE(0256H)                    !CtrlV Key

CtrlW            EQUATE(0257H)                    !CtrlW Key

CtrlX            EQUATE(0258H)                    !CtrlX Key

CtrlY            EQUATE(0259H)                    !CtrlY Key

CtrlZ            EQUATE(025AH)                    !CtrlZ Key

CtrlF1           EQUATE(0270H)                    !CtrlF1 Key

CtrlF2           EQUATE(0271H)                    !CtrlF2 Key

CtrlF3           EQUATE(0272H)                    !CtrlF3 Key

CtrlF4           EQUATE(0273H)                    !CtrlF4 Key

CtrlF5           EQUATE(0274H)                    !CtrlF5 Key

CtrlF6           EQUATE(0275H)                    !CtrlF6 Key

CtrlF7           EQUATE(0276H)                    !CtrlF7 Key

CtrlF8           EQUATE(0277H)                    !CtrlF8 Key

CtrlF9           EQUATE(0278H)                    !CtrlF9 Key

CtrlF10          EQUATE(0279H)                    !CtrlF10 Key

CtrlF11          EQUATE(027AH)                    !CtrlF11 Key

CtrlF12          EQUATE(027BH)                    !CtrlF12 Key

CtrlAst          EQUATE(026AH)                    !CtrlAsterisk Key

CtrlBS           EQUATE(0208H)                    !CtrlBackspace Key

CtrlDecimal      EQUATE(026EH)                    !CtrlDecimal Key

CtrlDelete       EQUATE(022EH)                    !CtrlDelete Key

CtrlDivide       EQUATE(026FH)                    !CtrlDivide Key

CtrlDown         EQUATE(0228H)                    !CtrlCursor Down Key

CtrlEnd          EQUATE(0223H)                    !CtrlEnd Key

CtrlEnter        EQUATE(020DH)                    !CtrlEnter Key

CtrlEsc          EQUATE(021BH)                    !CtrlEsc Key

CtrlHome         EQUATE(0224H)                    !CtrlHome Key

CtrlInsert       EQUATE(022DH)                    !CtrlInsert Key

CtrlLeft         EQUATE(0225H)                    !CtrlCursor Left Key

CtrlMinus        EQUATE(026DH)                    !CtrlMinus Key

CtrlPause        EQUATE(0213H)                    !CtrlPause Key

CtrlPgDn         EQUATE(0222H)                    !CtrlPgDn Key

CtrlPgUp         EQUATE(0221H)                    !CtrlPgUp Key

CtrlPlus         EQUATE(026BH)                    !CtrlPlus Key

CtrlPrint        EQUATE(022CH)                    !CtrlPrintScreen Key

CtrlRight        EQUATE(0227H)                    !CtrlCursor Right Key

CtrlSlash        EQUATE(026FH)                    !CtrlSlash Key

CtrlSpace        EQUATE(0220H)                    !CtrlSpacebar

CtrlTab          EQUATE(0209H)                    !CtrlTab Key

CtrlUp           EQUATE(0226H)                    !CtrlCursor Up Key

CtrlPad0         EQUATE(0260H)                    !Ctrl0 on numeric keypad

CtrlPad1         EQUATE(0261H)                    !Ctrl1 on numeric keypad

CtrlPad2         EQUATE(0262H)                    !Ctrl2 on numeric keypad

CtrlPad3         EQUATE(0263H)                    !Ctrl3 on numeric keypad

CtrlPad4         EQUATE(0264H)                    !Ctrl4 on numeric keypad

CtrlPad5         EQUATE(0265H)                    !Ctrl5 on numeric keypad

CtrlPad6         EQUATE(0266H)                    !Ctrl6 on numeric keypad

CtrlPad7         EQUATE(0267H)                    !Ctrl7 on numeric keypad

CtrlPad8         EQUATE(0268H)                    !Ctrl8 on numeric keypad

CtrlPad9         EQUATE(0269H)                    !Ctrl9 on numeric keypad

CtrlMouseLeft    EQUATE(0201H)                    !CtrlLeft mouse button

CtrlMouseRight   EQUATE(0202H)                    !CtrlRight mouse button

CtrlMouseCenter  EQUATE(0204H)                    !CtrlMiddle mouse button

Shift0           EQUATE(0130H)                    !Shift0 Key

Shift1           EQUATE(0131H)                    !Shift1 Key

Shift2           EQUATE(0132H)                    !Shift2 Key

Shift3           EQUATE(0133H)                    !Shift3 Key

Shift4           EQUATE(0134H)                    !Shift4 Key

Shift5           EQUATE(0135H)                    !Shift5 Key

Shift6           EQUATE(0136H)                    !Shift6 Key

Shift7           EQUATE(0137H)                    !Shift7 Key

Shift8           EQUATE(0138H)                    !Shift8 Key

Shift9           EQUATE(0139H)                    !Shift9 Key

ShiftA           EQUATE(0141H)                    !ShiftA Key

ShiftB           EQUATE(0142H)                    !ShiftB Key

ShiftC           EQUATE(0143H)                    !ShiftC Key

ShiftD           EQUATE(0144H)                    !ShiftD Key

ShiftE           EQUATE(0145H)                    !ShiftE Key

ShiftF           EQUATE(0146H)                    !ShiftF Key

ShiftG           EQUATE(0147H)                    !ShiftG Key

ShiftH           EQUATE(0148H)                    !ShiftH Key

ShiftI           EQUATE(0149H)                    !ShiftI Key

ShiftJ           EQUATE(014AH)                    !ShiftJ Key

ShiftK           EQUATE(014BH)                    !ShiftK Key

ShiftL           EQUATE(014CH)                    !ShiftL Key

ShiftM           EQUATE(014DH)                    !ShiftM Key

ShiftN           EQUATE(014EH)                    !ShiftN Key

ShiftO           EQUATE(014FH)                    !ShiftO Key

ShiftP           EQUATE(0150H)                    !ShiftP Key

ShiftQ           EQUATE(0151H)                    !ShiftQ Key

ShiftR           EQUATE(0152H)                    !ShiftR Key

ShiftS           EQUATE(0153H)                    !ShiftS Key

ShiftT           EQUATE(0154H)                    !ShiftT Key

ShiftU           EQUATE(0155H)                    !ShiftU Key

ShiftV           EQUATE(0156H)                    !ShiftV Key

ShiftW           EQUATE(0157H)                    !ShiftW Key

ShiftX           EQUATE(0158H)                    !ShiftX Key

ShiftY           EQUATE(0159H)                    !ShiftY Key

ShiftZ           EQUATE(015AH)                    !ShiftZ Key

ShiftF1          EQUATE(0170H)                    !ShiftF1 Key

ShiftF2          EQUATE(0171H)                    !ShiftF2 Key

ShiftF3          EQUATE(0172H)                    !ShiftF3 Key

ShiftF4          EQUATE(0173H)                    !ShiftF4 Key

ShiftF5          EQUATE(0174H)                    !ShiftF5 Key

ShiftF6          EQUATE(0175H)                    !ShiftF6 Key

ShiftF7          EQUATE(0176H)                    !ShiftF7 Key

ShiftF8          EQUATE(0177H)                    !ShiftF8 Key

ShiftF9          EQUATE(0178H)                    !ShiftF9 Key

ShiftF10         EQUATE(0179H)                    !ShiftF10 Key

ShiftF11         EQUATE(017AH)                    !ShiftF11 Key

ShiftF12         EQUATE(017BH)                    !ShiftF12 Key

ShiftAst         EQUATE(016AH)                    !ShiftAsterisk Key

ShiftBS          EQUATE(0108H)                    !ShiftBackspace Key

ShiftDecimal     EQUATE(016EH)                    !ShiftDecimal Key

ShiftDelete      EQUATE(012EH)                    !ShiftDelete Key

ShiftDivide      EQUATE(016FH)                    !ShiftDivide Key

ShiftDown        EQUATE(0128H)                    !ShiftCursor Down Key

ShiftEnd         EQUATE(0123H)                    !ShiftEnd Key

ShiftEnter       EQUATE(010DH)                    !ShiftEnter Key

ShiftEsc         EQUATE(011BH)                    !ShiftEsc Key

ShiftHome        EQUATE(0124H)                    !ShiftHome Key

ShiftInsert      EQUATE(012DH)                    !ShiftInsert Key

ShiftLeft        EQUATE(0125H)                    !ShiftCursor Left Key

ShiftMinus       EQUATE(016DH)                    !ShiftMinus Key

ShiftPause       EQUATE(0113H)                    !ShiftPause Key

ShiftPgDn        EQUATE(0122H)                    !ShiftPgDn Key

ShiftPgUp        EQUATE(0121H)                    !ShiftPgUp Key

ShiftPlus        EQUATE(016BH)                    !ShiftPlus Key

ShiftPrint       EQUATE(012CH)                    !ShiftPrintScreen Key

ShiftRight       EQUATE(0127H)                    !ShiftCursor Right Key

ShiftSlash       EQUATE(016FH)                    !ShiftSlash Key

ShiftSpace       EQUATE(0120H)                    !ShiftSpacebar

ShiftTab         EQUATE(0109H)                    !ShiftTab Key

ShiftUp          EQUATE(0126H)                    !ShiftCursor Up Key

ShiftPad0        EQUATE(0160H)                    !Shift0 on numeric keypad

ShiftPad1        EQUATE(0161H)                    !Shift1 on numeric keypad

ShiftPad2        EQUATE(0162H)                    !Shift2 on numeric keypad

ShiftPad3        EQUATE(0163H)                    !Shift3 on numeric keypad

ShiftPad4        EQUATE(0164H)                    !Shift4 on numeric keypad

ShiftPad5        EQUATE(0165H)                    !Shift5 on numeric keypad

ShiftPad6        EQUATE(0166H)                    !Shift6 on numeric keypad

ShiftPad7        EQUATE(0167H)                    !Shift7 on numeric keypad

ShiftPad8        EQUATE(0168H)                    !Shift8 on numeric keypad

ShiftPad9        EQUATE(0169H)                    !Shift9 on numeric keypad

ShiftMouseLeft   EQUATE(0101H)                    !ShiftLeft mouse button

ShiftMouseRight  EQUATE(0102H)                    !ShiftRight mouse button

ShiftMouseCenter EQUATE(0104H)                    !ShiftMiddle mouse button

AltShift0        EQUATE(0530H)                    !AltShift0 Key

AltShift1        EQUATE(0531H)                    !AltShift1 Key

AltShift2        EQUATE(0532H)                    !AltShift2 Key

AltShift3        EQUATE(0533H)                    !AltShift3 Key

AltShift4        EQUATE(0534H)                    !AltShift4 Key

AltShift5        EQUATE(0535H)                    !AltShift5 Key

AltShift6        EQUATE(0536H)                    !AltShift6 Key

AltShift7        EQUATE(0537H)                    !AltShift7 Key

AltShift8        EQUATE(0538H)                    !AltShift8 Key

AltShift9        EQUATE(0539H)                    !AltShift9 Key

AltShiftA        EQUATE(0541H)                    !AltShiftA Key

AltShiftB        EQUATE(0542H)                    !AltShiftB Key

AltShiftC        EQUATE(0543H)                    !AltShiftC Key

AltShiftD        EQUATE(0544H)                    !AltShiftD Key

AltShiftE        EQUATE(0545H)                    !AltShiftE Key

AltShiftF        EQUATE(0546H)                    !AltShiftF Key

AltShiftG        EQUATE(0547H)                    !AltShiftG Key

AltShiftH        EQUATE(0548H)                    !AltShiftH Key

AltShiftI        EQUATE(0549H)                    !AltShiftI Key

AltShiftJ        EQUATE(054AH)                    !AltShiftJ Key

AltShiftK        EQUATE(054BH)                    !AltShiftK Key

AltShiftL        EQUATE(054CH)                    !AltShiftL Key

AltShiftM        EQUATE(054DH)                    !AltShiftM Key

AltShiftN        EQUATE(054EH)                    !AltShiftN Key

AltShiftO        EQUATE(054FH)                    !AltShiftO Key

AltShiftP        EQUATE(0550H)                    !AltShiftP Key

AltShiftQ        EQUATE(0551H)                    !AltShiftQ Key

AltShiftR        EQUATE(0552H)                    !AltShiftR Key

AltShiftS        EQUATE(0553H)                    !AltShiftS Key

AltShiftT        EQUATE(0554H)                    !AltShiftT Key

AltShiftU        EQUATE(0555H)                    !AltShiftU Key

AltShiftV        EQUATE(0556H)                    !AltShiftV Key

AltShiftW        EQUATE(0557H)                    !AltShiftW Key

AltShiftX        EQUATE(0558H)                    !AltShiftX Key

AltShiftY        EQUATE(0559H)                    !AltShiftY Key

AltShiftZ        EQUATE(055AH)                    !AltShiftZ Key

AltShiftF1       EQUATE(0570H)                    !AltShiftF1 Key

AltShiftF2       EQUATE(0571H)                    !AltShiftF2 Key

AltShiftF3       EQUATE(0572H)                    !AltShiftF3 Key

AltShiftF4       EQUATE(0573H)                    !AltShiftF4 Key

AltShiftF5       EQUATE(0574H)                    !AltShiftF5 Key

AltShiftF6       EQUATE(0575H)                    !AltShiftF6 Key

AltShiftF7       EQUATE(0576H)                    !AltShiftF7 Key

AltShiftF8       EQUATE(0577H)                    !AltShiftF8 Key

AltShiftF9       EQUATE(0578H)                    !AltShiftF9 Key

AltShiftF10      EQUATE(0579H)                    !AltShiftF10 Key

AltShiftF11      EQUATE(057AH)                    !AltShiftF11 Key

AltShiftF12      EQUATE(057BH)                    !AltShiftF12 Key

AltShiftAst      EQUATE(056AH)                    !AltShiftAsterisk Key

AltShiftBS       EQUATE(0508H)                    !AltShiftBackspace Key

AltShiftDecimal  EQUATE(056EH)                    !AltShiftDecimal Key

AltShiftDelete   EQUATE(052EH)                    !AltShiftDelete Key

AltShiftDivide   EQUATE(056FH)                    !AltShiftDivide Key

AltShiftDown     EQUATE(0528H)                    !AltShiftCursor Down Key

AltShiftEnd      EQUATE(0523H)                    !AltShiftEnd Key

AltShiftEnter    EQUATE(050DH)                    !AltShiftEnter Key

AltShiftEsc      EQUATE(051BH)                    !AltShiftEsc Key

AltShiftHome     EQUATE(0524H)                    !AltShiftHome Key

AltShiftInsert   EQUATE(052DH)                    !AltShiftInsert Key

AltShiftLeft     EQUATE(0525H)                    !AltShiftCursor Left Key

AltShiftMinus    EQUATE(056DH)                    !AltShiftMinus Key

AltShiftPause    EQUATE(0513H)                    !AltShiftPause Key

AltShiftPgDn     EQUATE(0522H)                    !AltShiftPgDn Key

AltShiftPgUp     EQUATE(0521H)                    !AltShiftPgUp Key

AltShiftPlus     EQUATE(056BH)                    !AltShiftPlus Key

AltShiftPrint    EQUATE(052CH)                    !AltShiftPrintScreen Key

AltShiftRight    EQUATE(0527H)                    !AltShiftCursor Right Key

AltShiftSlash    EQUATE(056FH)                    !AltShiftSlash Key

AltShiftSpace    EQUATE(0520H)                    !AltShiftSpacebar

AltShiftTab      EQUATE(0509H)                    !AltShiftTab Key

AltShiftUp       EQUATE(0526H)                    !AltShiftCursor Up Key

AltShiftPad0     EQUATE(0560H)                    !AltShift0 on numeric keypad

AltShiftPad1     EQUATE(0561H)                    !AltShift1 on numeric keypad

AltShiftPad2     EQUATE(0562H)                    !AltShift2 on numeric keypad

AltShiftPad3     EQUATE(0563H)                    !AltShift3 on numeric keypad

AltShiftPad4     EQUATE(0564H)                    !AltShift4 on numeric keypad

AltShiftPad5     EQUATE(0565H)                    !AltShift5 on numeric keypad

AltShiftPad6     EQUATE(0566H)                    !AltShift6 on numeric keypad

AltShiftPad7     EQUATE(0567H)                    !AltShift7 on numeric keypad

AltShiftPad8     EQUATE(0568H)                    !AltShift8 on numeric keypad

AltShiftPad9     EQUATE(0569H)                    !AltShift9 on numeric keypad

AltShiftMouseLeft     EQUATE(0501H)               !AltShiftLeft mouse button

AltShiftMouseRight    EQUATE(0502H)               !AltShiftRight mouse button

AltShiftMouseCenter   EQUATE(0504H)               !AltShiftMiddle mouse button

CtrlShift0       EQUATE(0330H)                    !CtrlShift0 Key

CtrlShift1       EQUATE(0331H)                    !CtrlShift1 Key

CtrlShift2       EQUATE(0332H)                    !CtrlShift2 Key

CtrlShift3       EQUATE(0333H)                    !CtrlShift3 Key

CtrlShift4       EQUATE(0334H)                    !CtrlShift4 Key

CtrlShift5       EQUATE(0335H)                    !CtrlShift5 Key

CtrlShift6       EQUATE(0336H)                    !CtrlShift6 Key

CtrlShift7       EQUATE(0337H)                    !CtrlShift7 Key

CtrlShift8       EQUATE(0338H)                    !CtrlShift8 Key

CtrlShift9       EQUATE(0339H)                    !CtrlShift9 Key

CtrlShiftA       EQUATE(0341H)                    !CtrlShiftA Key

CtrlShiftB       EQUATE(0342H)                    !CtrlShiftB Key

CtrlShiftC       EQUATE(0343H)                    !CtrlShiftC Key

CtrlShiftD       EQUATE(0344H)                    !CtrlShiftD Key

CtrlShiftE       EQUATE(0345H)                    !CtrlShiftE Key

CtrlShiftF       EQUATE(0346H)                    !CtrlShiftF Key

CtrlShiftG       EQUATE(0347H)                    !CtrlShiftG Key

CtrlShiftH       EQUATE(0348H)                    !CtrlShiftH Key

CtrlShiftI       EQUATE(0349H)                    !CtrlShiftI Key

CtrlShiftJ       EQUATE(034AH)                    !CtrlShiftJ Key

CtrlShiftK       EQUATE(034BH)                    !CtrlShiftK Key

CtrlShiftL       EQUATE(034CH)                    !CtrlShiftL Key

CtrlShiftM       EQUATE(034DH)                    !CtrlShiftM Key

CtrlShiftN       EQUATE(034EH)                    !CtrlShiftN Key

CtrlShiftO       EQUATE(034FH)                    !CtrlShiftO Key

CtrlShiftP       EQUATE(0350H)                    !CtrlShiftP Key

CtrlShiftQ       EQUATE(0351H)                    !CtrlShiftQ Key

CtrlShiftR       EQUATE(0352H)                    !CtrlShiftR Key

CtrlShiftS       EQUATE(0353H)                    !CtrlShiftS Key

CtrlShiftT       EQUATE(0354H)                    !CtrlShiftT Key

CtrlShiftU       EQUATE(0355H)                    !CtrlShiftU Key

CtrlShiftV       EQUATE(0356H)                    !CtrlShiftV Key

CtrlShiftW       EQUATE(0357H)                    !CtrlShiftW Key

CtrlShiftX       EQUATE(0358H)                    !CtrlShiftX Key

CtrlShiftY       EQUATE(0359H)                    !CtrlShiftY Key

CtrlShiftZ       EQUATE(035AH)                    !CtrlShiftZ Key

CtrlShiftF1      EQUATE(0370H)                    !CtrlShiftF1 Key

CtrlShiftF2      EQUATE(0371H)                    !CtrlShiftF2 Key

CtrlShiftF3      EQUATE(0372H)                    !CtrlShiftF3 Key

CtrlShiftF4      EQUATE(0373H)                    !CtrlShiftF4 Key

CtrlShiftF5      EQUATE(0374H)                    !CtrlShiftF5 Key

CtrlShiftF6      EQUATE(0375H)                    !CtrlShiftF6 Key

CtrlShiftF7      EQUATE(0376H)                    !CtrlShiftF7 Key

CtrlShiftF8      EQUATE(0377H)                    !CtrlShiftF8 Key

CtrlShiftF9      EQUATE(0378H)                    !CtrlShiftF9 Key

CtrlShiftF10     EQUATE(0379H)                    !CtrlShiftF10 Key

CtrlShiftF11     EQUATE(037AH)                    !CtrlShiftF11 Key

CtrlShiftF12     EQUATE(037BH)                    !CtrlShiftF12 Key

CtrlShiftAst     EQUATE(036AH)                    !CtrlShiftAsterisk Key

CtrlShiftBS      EQUATE(0308H)                    !CtrlShiftBackspace Key

CtrlShiftDecimal EQUATE(036EH)                    !CtrlShiftDecimal Key

CtrlShiftDelete  EQUATE(032EH)                    !CtrlShiftDelete Key

CtrlShiftDivide  EQUATE(036FH)                    !CtrlShiftDivide Key

CtrlShiftDown    EQUATE(0328H)                    !CtrlShiftCursor Down Key

CtrlShiftEnd     EQUATE(0323H)                    !CtrlShiftEnd Key

CtrlShiftEnter   EQUATE(030DH)                    !CtrlShiftEnter Key

CtrlShiftEsc     EQUATE(031BH)                    !CtrlShiftEsc Key

CtrlShiftHome    EQUATE(0324H)                    !CtrlShiftHome Key

CtrlShiftInsert  EQUATE(032DH)                    !CtrlShiftInsert Key

CtrlShiftLeft    EQUATE(0325H)                    !CtrlShiftCursor Left Key

CtrlShiftMinus   EQUATE(036DH)                    !CtrlShiftMinus Key

CtrlShiftPause   EQUATE(0313H)                    !CtrlShiftPause Key

CtrlShiftPgDn    EQUATE(0322H)                    !CtrlShiftPgDn Key

CtrlShiftPgUp    EQUATE(0321H)                    !CtrlShiftPgUp Key

CtrlShiftPlus    EQUATE(036BH)                    !CtrlShiftPlus Key

CtrlShiftPrint   EQUATE(032CH)                    !CtrlShiftPrintScreen Key

CtrlShiftRight   EQUATE(0327H)                    !CtrlShiftCursor Right Key

CtrlShiftSlash   EQUATE(036FH)                    !CtrlShiftSlash Key

CtrlShiftSpace   EQUATE(0320H)                    !CtrlShiftSpacebar

CtrlShiftTab     EQUATE(0309H)                    !CtrlShiftTab Key

CtrlShiftUp      EQUATE(0326H)                    !CtrlShiftCursor Up Key

CtrlShiftPad0    EQUATE(0360H)                    !CtrlShift0 on numeric keypad

CtrlShiftPad1    EQUATE(0361H)                    !CtrlShift1 on numeric keypad

CtrlShiftPad2    EQUATE(0362H)                    !CtrlShift2 on numeric keypad

CtrlShiftPad3    EQUATE(0363H)                    !CtrlShift3 on numeric keypad

CtrlShiftPad4    EQUATE(0364H)                    !CtrlShift4 on numeric keypad

CtrlShiftPad5    EQUATE(0365H)                    !CtrlShift5 on numeric keypad

CtrlShiftPad6    EQUATE(0366H)                    !CtrlShift6 on numeric keypad

CtrlShiftPad7    EQUATE(0367H)                    !CtrlShift7 on numeric keypad

CtrlShiftPad8    EQUATE(0368H)                    !CtrlShift8 on numeric keypad

CtrlShiftPad9    EQUATE(0369H)                    !CtrlShift9 on numeric keypad

CtrlShiftMouseLeft    EQUATE(0301H)               !CtrlShiftLeft mouse button

CtrlShiftMouseRight   EQUATE(0302H)               !CtrlShiftRight mouse button

CtrlShiftMouseCenter  EQUATE(0304H)               !CtrlShiftMiddle mouse button

CtrlAlt0         EQUATE(0630H)                    !CtrlAlt0 Key

CtrlAlt1         EQUATE(0631H)                    !CtrlAlt1 Key

CtrlAlt2         EQUATE(0632H)                    !CtrlAlt2 Key

CtrlAlt3         EQUATE(0633H)                    !CtrlAlt3 Key

CtrlAlt4         EQUATE(0634H)                    !CtrlAlt4 Key

CtrlAlt5         EQUATE(0635H)                    !CtrlAlt5 Key

CtrlAlt6         EQUATE(0636H)                    !CtrlAlt6 Key

CtrlAlt7         EQUATE(0637H)                    !CtrlAlt7 Key

CtrlAlt8         EQUATE(0638H)                    !CtrlAlt8 Key

CtrlAlt9         EQUATE(0639H)                    !CtrlAlt9 Key

CtrlAltA         EQUATE(0641H)                    !CtrlAltA Key

CtrlAltB         EQUATE(0642H)                    !CtrlAltB Key

CtrlAltC         EQUATE(0643H)                    !CtrlAltC Key

CtrlAltD         EQUATE(0644H)                    !CtrlAltD Key

CtrlAltE         EQUATE(0645H)                    !CtrlAltE Key

CtrlAltF         EQUATE(0646H)                    !CtrlAltF Key

CtrlAltG         EQUATE(0647H)                    !CtrlAltG Key

CtrlAltH         EQUATE(0648H)                    !CtrlAltH Key

CtrlAltI         EQUATE(0649H)                    !CtrlAltI Key

CtrlAltJ         EQUATE(064AH)                    !CtrlAltJ Key

CtrlAltK         EQUATE(064BH)                    !CtrlAltK Key

CtrlAltL         EQUATE(064CH)                    !CtrlAltL Key

CtrlAltM         EQUATE(064DH)                    !CtrlAltM Key

CtrlAltN         EQUATE(064EH)                    !CtrlAltN Key

CtrlAltO         EQUATE(064FH)                    !CtrlAltO Key

CtrlAltP         EQUATE(0650H)                    !CtrlAltP Key

CtrlAltQ         EQUATE(0651H)                    !CtrlAltQ Key

CtrlAltR         EQUATE(0652H)                    !CtrlAltR Key

CtrlAltS         EQUATE(0653H)                    !CtrlAltS Key

CtrlAltT         EQUATE(0654H)                    !CtrlAltT Key

CtrlAltU         EQUATE(0655H)                    !CtrlAltU Key

CtrlAltV         EQUATE(0656H)                    !CtrlAltV Key

CtrlAltW         EQUATE(0657H)                    !CtrlAltW Key

CtrlAltX         EQUATE(0658H)                    !CtrlAltX Key

CtrlAltY         EQUATE(0659H)                    !CtrlAltY Key

CtrlAltZ         EQUATE(065AH)                    !CtrlAltZ Key

CtrlAltF1        EQUATE(0670H)                    !CtrlAltF1 Key

CtrlAltF2        EQUATE(0671H)                    !CtrlAltF2 Key

CtrlAltF3        EQUATE(0672H)                    !CtrlAltF3 Key

CtrlAltF4        EQUATE(0673H)                    !CtrlAltF4 Key

CtrlAltF5        EQUATE(0674H)                    !CtrlAltF5 Key

CtrlAltF6        EQUATE(0675H)                    !CtrlAltF6 Key

CtrlAltF7        EQUATE(0676H)                    !CtrlAltF7 Key

CtrlAltF8        EQUATE(0677H)                    !CtrlAltF8 Key

CtrlAltF9        EQUATE(0678H)                    !CtrlAltF9 Key

CtrlAltF10       EQUATE(0679H)                    !CtrlAltF10 Key

CtrlAltF11       EQUATE(067AH)                    !CtrlAltF11 Key

CtrlAltF12       EQUATE(067BH)                    !CtrlAltF12 Key

CtrlAltAst       EQUATE(066AH)                    !CtrlAltAsterisk Key

CtrlAltBS        EQUATE(0608H)                    !CtrlAltBackspace Key

CtrlAltDecimal   EQUATE(066EH)                    !CtrlAltDecimal Key

CtrlAltDelete    EQUATE(062EH)                    !CtrlAltDelete Key

CtrlAltDivide    EQUATE(066FH)                    !CtrlAltDivide Key

CtrlAltDown      EQUATE(0628H)                    !CtrlAltCursor Down Key

CtrlAltEnd       EQUATE(0623H)                    !CtrlAltEnd Key

CtrlAltEnter     EQUATE(060DH)                    !CtrlAltEnter Key

CtrlAltEsc       EQUATE(061BH)                    !CtrlAltEsc Key

CtrlAltHome      EQUATE(0624H)                    !CtrlAltHome Key

CtrlAltInsert    EQUATE(062DH)                    !CtrlAltInsert Key

CtrlAltLeft      EQUATE(0625H)                    !CtrlAltCursor Left Key

CtrlAltMinus     EQUATE(066DH)                    !CtrlAltMinus Key

CtrlAltPause     EQUATE(0613H)                    !CtrlAltPause Key

CtrlAltPgDn      EQUATE(0622H)                    !CtrlAltPgDn Key

CtrlAltPgUp      EQUATE(0621H)                    !CtrlAltPgUp Key

CtrlAltPlus      EQUATE(066BH)                    !CtrlAltPlus Key

CtrlAltPrint     EQUATE(062CH)                    !CtrlAltPrintScreen Key

CtrlAltRight     EQUATE(0627H)                    !CtrlAltCursor Right Key

CtrlAltSlash     EQUATE(066FH)                    !CtrlAltSlash Key

CtrlAltSpace     EQUATE(0620H)                    !CtrlAltSpacebar

CtrlAltTab       EQUATE(0609H)                    !CtrlAltTab Key

CtrlAltUp        EQUATE(0626H)                    !CtrlAltCursor Up Key

CtrlAltPad0      EQUATE(0660H)                    !CtrlAlt0 on numeric keypad

CtrlAltPad1      EQUATE(0661H)                    !CtrlAlt1 on numeric keypad

CtrlAltPad2      EQUATE(0662H)                    !CtrlAlt2 on numeric keypad

CtrlAltPad3      EQUATE(0663H)                    !CtrlAlt3 on numeric keypad

CtrlAltPad4      EQUATE(0664H)                    !CtrlAlt4 on numeric keypad

CtrlAltPad5      EQUATE(0665H)                    !CtrlAlt5 on numeric keypad

CtrlAltPad6      EQUATE(0666H)                    !CtrlAlt6 on numeric keypad

CtrlAltPad7      EQUATE(0667H)                    !CtrlAlt7 on numeric keypad

CtrlAltPad8      EQUATE(0668H)                    !CtrlAlt8 on numeric keypad

CtrlAltPad9      EQUATE(0669H)                    !CtrlAlt9 on numeric keypad

CtrlAltMouseLeft      EQUATE(0601H)               !CtrlAltLeft mouse button

CtrlAltMouseRight     EQUATE(0602H)               !CtrlAltRight mouse button

CtrlAltMouseCenter    EQUATE(0604H)               !CtrlAltMiddle mouse button


Future Enhancements

Here is a short list of the more commonly requested improvements to the Clarion for Windows user environment that we intend to implement before the final version.

•	Editor Keys will be re-definable (from the INI file).

•	Editor will support Keyboard macros (single window text and editor command sequences invoked by a single key).

•	Embedded editing (e.g. from the application generator) will be improved, with fully modal windows for editor and screen and report formatters.

•	Screen and report formatting will have font name/size/style setting from the toolbar.

•	You will also be able to set the use variable from the toolbar.

•	Control property dialogs in screen and report formatters will be improved, and the More/Less buttons removed (with dialogs fully expanded).

•	You will be able to change working directory, to maintain different projects in different directories.

•	There will be automatic session saving which will be application/project based. (This will save current working directory and redirection file).

•	New and Open file types will be more intuitively ordered and user redefinable. The user will be able to add new file extension mappings.

•	Control templates, field prompts and improved embedded source entry will be supported within the application generator. Also it will be possible to insert a new field from within the screen and report formatters.

•	Printing will be supported from the editor

•	You will be able to choose other (monospaced) fonts for the editor.

•	File redirection will work on open dialogs if file not found in specified directory.

•	Syntax coloring in editor will be improved and will support template files.

•	Global replace in editor will not update the screen until finished.

•	Error editing will cross multiple files, and will errors will be highlighted more effectively.

•	The list box editing dialog will be substantially improved (hopefully making it more intuitive to use)

•	There also will be a picture editing dialog accessible from the 'more' button (...) next to picture entry fields.


File Drivers

Clarion for Windows incorporates database independence via its built-in driver technology, enabling you to access data from virtually any file system. Many file drivers are available and more are being added.

Many of the commands for accessing data from different files are transparent; simply choose the correct driver within your Data Dictionary, and dont worry about it. There are various settings you can specify, via driver strings, to optimize the way your application creates, reads, and writes data files given a specific driver. This appendix explains how use the drivers.

Often, your applications main concern is to access data that already exists in a predefined file format. For those times, you just plug in a driver. For the times when youre not locked into a particular file format, this appendix also provides tips on what drivers are best suited for different jobs. You can choose the right tool depending on the type, size and nature of the data files necessary for your application.

Clarion for Windows provides the following file drivers:

ASCII Files 	Reads and writes standard ASCII files with no field delimiters. Records are delimited by a carriage-return / line-feed.

Basic Files 	Reads and writes comma-quote delimited ASCII files. Records are delimited by a carriage-return/line-feed.

Btrieve Files	Reads and writes Btrieve files, using low-level direct access.

Clarion Files	Reads and writes files created with Clarion Professional Developer 2.1 and Clarion 3.0s proprietary file system.

Clipper Files	Reads and writes Clipper 5.0 and Clipper Summer 87 compatible data and index files.

dBase III Files	Reads and writes dBase III compatible data and index files.

dBase IV Files	Reads and writes dBase IV compatible data and index files.

DOS Files	Reads and writes any  binary, byte-addressable file.

FoxPro Files	Reads and writes FoxPro 2.0 compatible data and index files.

Paradox Files	Reads and writes Paradox keyed and non-keyed tables for versions of Paradox prior to v. 4.0.

TopSpeed Driver	Reads and writes a new Clarion proprietary format which is fast, secure, and stores multiple data and key files in a single DOS file.


ASCII Files

The ASCII driver reads and writes standard ASCII files without field delimiters. A carriage-return/line-feed delimits records. The ASCII driver does not support keys.

Files:	CDDWASC.LIB	Windows Export Library

CDDWASC.DLL	Windows Dynamic Link Library

Tip:	Due to its lack of relational features and security (anyone can view and change an ASCII file using Notepad), its unlikely youll use the ASCII driver to store large data files. But it can help you create a text file viewer--use it to open a file, and throw it in a multi-line edit control!


ASCII Driver Strings

/FILEBUFFERS=n	Specifies a value for the number of buffers used to read and write to the file. The ASCII driver allocates internal buffers of 512 bytes, or the size of the record, whichever is larger. The default number of buffers is 2 for files opened denying write access to other users, and 1 for all other open modes. Use the optional driver string to increase the buffers should you find access to records is slow.

/TAB= n	The ASCII driver expands TABs (ASCII character 9) to spaces. The value indicates the number of spaces with which to replace the tab, subject to the guidelines below. The default value is 8.

If n > 0 , spaces replace each tab until the character pointer moves to the next multiple of n. For example, with the default of 8, if the TAB character is the third character in the record, 6 spaces replace the TAB.

If n = 0, the driver removes tabs without replacement.

If n < 0, the driver removes tabs with the positive value of n spaces. For example, TAB=-4 causes 4 spaces to replace every tab, regardless of the position of the tab in the record.

If n = -100, tabs remain as tabs; the driver does not replace them with spaces.

Tip:	TAB-delimited values are a common format compatible with the Windows clipboard.

/ENDOFRECORD=n,<m>	Specifies the end of record delimiter. n represents the number of characters that make up the end-of-record separator. m represents the ASCII code(s) for the end-of-record characters, separated by commas. The default is 2,13,10, indicating 2 characters mark the end-of-record, namely, carriage return (13) and line feed (10).

/QUICKSCAN=on|off	The ASCII driver reads a buffer at a time (not a record), allowing for fast access. In a multi-user environment these buffers are not 100% trustworthy for subsequent access, because another user may change the database between accesses. As a safeguard, the driver rereads the buffers before each record access. To disable the reread, set QUICKSCAN to ON. The default is ON for files opened denying write access to other users, and OFF for all other open modes.

/CLIP=on|off	The driver automatically removes trailing spaces from a record before writing it to file. To disable this feature, set CLIP to OFF. The default is ON.

Using the Send Command


ASCII Supported Data Types

STRING

GROUP


ASCII File Specifications/Maximums
ASCII: File Specifications/Maximums

File Size	:	4,294,967,295

Records per File	:	4,294,967,295

Record Size	:	65,520 bytes

Field Size	:	65,520 bytes

Fields per Record	:	65,520 bytes

Keys/Indexes per File	:	n/a

Key Size 	:	n/a

Memo fields per File	:	0

Memo Field Size	:	n/a

Open Data Files	:	Operating system dependent


ASCII Unsupported Functions and Attributes
ASCII: Unsupported Functions and Attributes

Memos:	NOMEMO()

Transaction Processing:	COMMIT(), LOGOUT(), ROLLBACK()

Key Processing:	BUILD(key), BUILD(index), GET(file,key), GET(key,keypointer), RESET(key,string), SET(file,key), SET(key), SET(key,key), SET(key,keypointer), SET(key,key,filepointer), DUPLICATE(), POINTER(key), POSITION(key), RECORDS(key), RESET(key), REGET(key)

Record Locking:	HOLD(), RELEASE()

File Buffering:	STREAM()

File Information:	RECORDS(file)

Sequential Processing:	PREVIOUS(), BOF(), SKIP()

File Manipulation:	BUILD(), DELETE(), PACK(), WATCH(), REGET()


Basic Files

Reads and writes comma separated value ASCII files. Quotes surround strings; carriage-return/line-feeds delimit records. The original BASIC programming language defined this file format. The Basic driver does not support keys.

Tip:	The Basic file format provides a good a common file format for sharing data with spreadsheet programs. A common file extension used for these files is *.CSV, which stands for comma separated values.


Basic: Driver Strings

/FILEBUFFERS=n	Specifies a value for the number of buffers used to read and write to the file. The Basic driver allocates internal buffers of 512 bytes, or the size of your record, whichever is larger, to store the retrieved data. The default number of buffers is 2 for files opened denying write access to other users, and 1 for all other open modes. Use the optional driver string to increase the buffers should you find access to records is slow.

/ENDOFRECORD=n,<m>	Specifies the end of record delimiter. n represents the number of characters of the end-of-record separator. m represents the ASCII code(s) for the end-of-record characters, separated by commas. The default is 2,13,10 indicating 2 characters mark the end-of-record, namely, carriage return (13) and line feed (10).

/QUICKSCAN=on|off	The Basic driver reads a buffer at a time (not a record), allowing for fast access. In a multi-user environment these buffers are not 100% trustworthy for subsequent access, because another user may change the database between accesses. As a safeguard, the driver rereads the buffers before each record access. To disable the reread, set QUICKSCAN to ON. The default is ON for files opened denying write access to other users, and OFF for all other open modes.

/FIELDDELIMITER=n,<m>	Specifies the end-of-field separator. n represents the number of characters that make up the end-of-field separator. m represents the ASCII code(s) for the end-of-field characters, separated by commas. The default is 1,44, which indicates the comma character.

/COMMA=n	Specifies a single character end-of-field separator. n represents the ASCII code for the end-of-field character. The default is 44, which is equivalent to /FIELDDELIMITER=1,44.

/QUOTE=n	Specifies a single character string delimiter. n represents the ASCII code. The default is 34, the ASCII value for the quotation mark character.

/ALWAYSQUOTE=on|off	For compatibility with Basic format data files created by products which do not place string values in quotes, set ALWAYSQUOTE to off.

When the contents of a string field includes the comma or quote character(s), and ALWAYSQUOTE is off, the Basic driver automatically places quotes around the string when writing to file. This also applies to delimiter characters specified with FIELDDELIMITER, or COMMA. For example, with the defaults in use and ALWAYSQUOTE off, a STRING field containing the value 1313 Mockingbird Lane, Apt. 33 is automatically stored as: "123 Mockingbird Lane, Apt. 33"

Using the Send Command


Basic: Supported Data Types

BYTE	DECIMAL

SHORT	PDECIMAL

USHORT	STRING

LONG	CSTRING

ULONG	PSTRING

SREAL	DATE

REAL	TIME

BFLOAT	GROUP


Basic: File Specifications/Maximums

File Size	:	4,294,967,295

Records per File	:	4,294,967,295

Record Size	:	65,520 bytes

Field Size	:	65,520 bytes

Fields per Record	:	65,520 bytes

Keys/Indexes per File	:	n/a

Key Size	:	n/a

Memo fields per File	:	0

Memo Field Size	:	n/a

Open Data Files	:	Operating system dependent


Basic: Unsupported Functions and Attributes

Memos:	NOMEMO()

Transaction Processing:	COMMIT(), LOGOUT(), ROLLBACK()

Key Processing:	BUILD(key), BUILD(index), GET(file,key), GET(key,keypointer), RESET(key,string), SET(file,key), SET(key), SET(key,key), SET(key,keypointer), SET(key,key,filepointer), DUPLICATE(), POINTER(key), POSITION(key), RECORDS(key), REGET(key) RESET(key)

Record Locking:	HOLD(), RELEASE()

File Buffering:	STREAM()

File Information:	RECORDS(file)

Sequential Processing:	PREVIOUS(), BOF(), SKIP()

File Manipulation:	BUILD(), DELETE(), PACK(), WATCH(), REGET()


Basic: Miscellaneous

The following documents two popular mailmerge file formats:

•	Microsoft Word for Windows Mail Merge:

/ALWAYSQUOTE=OFF

/FIELDDELIMITER=2,13,7

/QUOTE=255

/ENDOFRECORD=4,13,7,13,7

•	WordPerfect 5.1 Mail Merge file:

/FIELDDELIMITER=9,222,49,4,0,4,0,49,222,10

ALWAYSQUOTE=OFF

QUOTE=255

ENDOFRECORD=22,0,0,0,0,0,0,0,0,0,48,42,48,42,48,42,176,4,28,0,0,212,12

The end-of-record marker in WordPerfect 5.1 includes the record number. The example above only covers the fixed part of this marker. To add the variable part, add to the end of your record structure two fields:

EndOfRecord    STRING(18)

NextRecNo      BYTE

EndOfRecord must hold the string <222,52,6,0,3,0,6,0,52,222,212, 0,28,0,0,22,144,1>, and NextRecNo should hold the record number + 1.


Btrieve Files

This file driver reads and writes Btrieve files, using low-level direct access.

***	Client/Server TBD

***	AS OF BETA 3 YOU MUST LOAD BTRIEVE.EXE

A single file holds the data and all keys. Data filenames default to a file extension of .DAT. By default, the driver stores memos in a separate file, or optionally in the data file itself, given the appropriate driver string.

KEYs are dynamic, and automatically update when the data file changes. The driver creates keys as Btrieve supplemental keys. Therefore, the BUILD statement may rebuild one KEY without requiring all the KEYs to be rebuilt. INDEXes are stored separately from data files. INDEX files receive a temporary file name, and are deleted when the program terminates normally. INDEXes are static--they do not automatically update when the data file changes. The BUILD statement creates or updates index files.

The Btrieve file format stores minimal file structure information in the file. The driver validates your description against the information in the file. It is possible to successfully open a Btrieve file that has key definitions that do not exactly match your definition. You must make certain that your file and key definitions accurately match the Btrieve file.

Files:	CDDWBTRV.LIB    Windows Export Library

CDDWBTRV.DLL    Windows Dynamic Link Library

An Owner Name is similar to a password. An encrypted Btrieve file uses the owner name as the encryption key.


Btrieve: Data Types

Clarion 	Btrieve internal data type

BYTE	STRING (1 byte)

SHORT 	INTEGER (2 bytes)

LONG	INTEGER (4 bytes)

SREAL	FLOAT (4 bytes)

REAL	FLOAT (8 bytes)

BFLOAT4 	BFLOAT (4 bytes)

BFLOAT8 	BFLOAT (8 bytes)

PDECIMAL	DECIMAL

STRING	STRING

CSTRING 	ZSTRING

PSTRING 	LSTRING

DATE	DATE

TIME	TIME

USHORT	UNSIGNED BINARY (2 bytes)

ULONG 	UNSIGNED BINARY (4 bytes)

MEMO	STRING,LVAR or NOTE (see below)

DECIMAL

Notes:

•	You can store Clarion DECIMAL types in a Btrieve file. You cannot, however, build a key or index using the field.

•	The driver does not directly support the Btrieve data types LOGICAL, MONEY, and NUMERIC. It indirectly supports them:

LOGICAL may be declared as a BYTE or USHORT:

LogicalField1  BYTE	!One byte LOGICAL

LogicalField2  USHORT	!Two byte LOGICAL

MONEY may be declared as a PDECIMAL(x,2), where x is the total number of digits to be stored:

MoneyField	PDECIMAL(7,2)	!Store up to 99999.99

If it only contains positive numbers, NUMERIC may be declared as a STRING(@N0x), where x is the total number of digits in the number.

NumericField	STRING(@N07)	!Store up to 9999999

If it contains negative numbers, a STRING(1) must be declared for the sign. This must follow the STRING(@N0x), where x is one less than the total number of digits in the number (including the sign). The Btrieve driver does not automatically maintain the sign field. The application must directly handle it. The sign STRING(1) may contain the following values to indicate positive or negative values:

Positive:  1 2 3 4 5 6 7 8 9 0

Positive:  A B C D E F G H I {

Negative:  J K L M N O P Q R }


Btrieve: File Specifications/Maximums:

File Size:	4 Gigabytes
(approximately 4 billion bytes)

Records per File:	Limited by the size of the file

Record Size

Client-based:	65,520 bytes variable length

Server based:	54K variable length

Field Size 	:	65,520 bytes

Fields per Record	:	65,520 bytes

Keys/Indexes per File	:	24 with NLM5 or BTRIEVE.EXE or 256 with NLM6. This is the total number of components. If you have a multi-component key built from three fields, this counts as three indexes when counting the number of allowed indexes.

Key Size	:	245 bytes

Memo fields per File	:	System memory dependent

Memo field size	:	65,520 bytes

Open Files	:	Operating system dependent


Btrieve: Driver Strings

/MEMO=SINGLE	To access existing Btrieve files created with the Btrieve LEM from Clarion 2.1, or files with variable length records set MEMO to SINGLE.

/MEMO=LVAR	To access a file with variable length records, use a SINGLE style MEMO whose size equals the maximum size of the variable length component of the record. To add/put records to this style file with binary data stored in the variable length section, use the ADD(file,length), APPEND(file,length) and PUT(file,pos,length) functions. The driver ignores the pos parameter in the PUT function, but initialize it to 0 (zero) for future compatibility. The ADD, APPEND or PUT functions will remove all trailing spaces for text memos and NULL characters for binary memos before storing the record.

/MEMO=NOTE,<delimiter>	To access Xtrieve data files that have data type of Note or LVar, set the driver string to NOTE and LVAR respectively. With the NOTE data type, specify the end-of-field delimiter. Specify the ASCII value for the delimiter. NOTE and LVAR memos do not require the use of the size variants of ADD, APPEND and PUT, when storing records. The end of record marker is not necessary for a NOTE style memo. The driver automatically adds the end of record marker before storing the record and removes it before putting the memo data into the memo buffer.

As an example, /MEMO=NOTES,141 indicates a file with an Xtrieve Notes field using CR/LF as the delimiter. For more information on the Xtrieve data types refer to the documentation supplied by Novell.

/PAGESIZE=<size>	Optionally sets the Btrieve Page size at file creation time. The keyword must be upper case. It must always be a multiple of 512, with a maximum of 4096. Larger page sizes usually result in more efficient disk storage. Do not add spaces before or after the equal sign.

/ALLOWREAD=[ON|OFF]	By default, a Btrieve file created with an owner name may be accessed only in read-only mode when the owner name is not known. To prevent all access to the file without the owner name, set ALLOWREAD to OFF.

/VALIDATE=[ON|OFF]	It is possible to open a Btrieve file using a different file definition than the one was used to create the file. The file header contains a partial description of the file structure. The driver can compare the physical file against your definition of the file. Set VALIDATE to ON to use the file header information to verify your definition against the file header. By default, this switch is set to OFF.

/COMPRESS=[ON|OFF]	Btrieve allows you to compress the data before storage. This allows for a smaller storage requirement, but reduces performance. When COMPRESS is ON, CREATE creates a compressed Btrieve file.

/PREALLOCATE=n	When creating a Btrieve file, you can preallocate n pages of disk space for the file. The default is zero.

/FREESPACE=[0|10|20|30]	Specifies the percentage of free space to maintain on variable length pages. The default is zero.

/MODIFIABLE=[TRUE|FALSE]	Btrieve allows you to create a key which can not be changed once created. To do so, use the name attribute on the key to set MODIFIABLE to TRUE. It defaults to FALSE.

Using the Send Command


Btrieve: Unsupported/Modified Functions and Attributes

•	Key Attribute:  NOCASE

NLM 5 does not support case insensitive indexing. When necessary, you must supply an alternate collating sequence which implements case insensitive sorting.

Btrieve supports an alternate collating sequence. However, NLM 6 does not support both NOCASE and an alternate collating sequence. If you specify both, the NOCASE attribute takes precedence. No error is returned from such a SEND command.

•	Buffering Control:  STREAM, FLUSH

There is no buffering control within the Btrieve driver.

•	File Locking:  LOCK()

Btrieve does not support file locking. The driver does not return any error if you call it. If you require file locking, use LOGOUT.

•	Record Access:  GET(file, fileptr, len)

•	File information: BYTES()

•	File updates:  PUT(file, fileptr)

•	SET(file, filepointer), SET(key, keypointer)

If a file or key pointer has a value of zero, or any other value that does not exist in the file, the driver ignores the pointer parameter. Processing is set to either file or key order, and the record pointer is set to the first element.

•	SET(key, key, filepointer)

If the filepointer has a value of zero, or any other value that does not exist in the file, processing starts at the first key value whose position is greater than (or less than for PREVIOUS) the filepointer. Not passing a valid pointer is inefficient.

Tip:	A common practice for finding the last duplicate is to call Set(key,key2,filepointer) with filepointer set to a large number. This causes every record that matches key2 to be read. Set (key,key2+1,filepointer); next(file); previous(file) usually requires less disk access.

•	EOF(file), BOF(file)

These functions are supported, but not recommended. They cause more disk I/O than ERRORCODE(). Btrieve returns eof when reading past the last record. This requires the driver must read the next record, then the next to see if its at the end of file, then goes back to the record you want.

•	ADD(file), PUT(file)

When using the LVAR and NOTE memo type,make certain that the memo has the appropriate structure. If the structure is incorrect and the driver calculates a length greater than the maximum memo size defined for that file, these functions fail and set errorcode to 57 - Invalid Memo File.

•	DELETE(file) when stepping through in record order

Btrieves DELETE destroys positioning information when processing in file order. The driver attempts to reposition to the appropriate record. This is not always possible and may require the driver to read from the start of the file. Using key order processing avoids this possible slow down.


Btrieve: Miscellaneous

•	The driver stores records less than 4K as fixed length. It stores records greater than  4K as variable length. The minimum record length is 4 bytes. One record can be held in each open file by each user.

•	The driver ignores any NAME attribute on a MEMO field. MEMO fields can reside either in a separate file, or in the data file if the driver string MEMO is set to SINGLE, LVAR or NOTE. If the driver string MEMO is not set, the separate MEMO file name is MEM, preceded by the first five characters of the files label, plus the file extension DAT. Setting the driver string MEMO restricts you to one memo field per file.

•	Btrieve allows you to open a file in five different formats: NORMAL, ACCELERATED, READ-ONLY, VERIFY or EXCLUSIVE. The equivalent Clarion OPEN() states are:

Btrieve State	Clarion OPEN/SHARE access mode

ACCELERATED	Read/Write with FCB compatibility mode (2H)

READ-ONLY	Read Only  (0H,10H,20H,30H,40H)

VERIFY	Write Only with FCB compatibility mode (1H)

EXCLUSIVE	Write Only with any Deny flag (11H,21H,31H,41H); Read/Write with Deny All, Read or Write (12H,22H,32H)

NORMAL	Read/Write with Deny None (42H)

•	Btrieve allows a file to have a specified owner. See the driver string /READONLY for details on setting this flag. The file may also be encrypted. This is set with the ENCRYPT attribute. A file can only be encrypted when an owner name is supplied.

•	Btrieve uses an unsigned long for its internal record pointer; negative values are stripped of their sign. We recommend the ULONG data type for your record pointer.

•	 Calculating Page Size:

To determine the the physical record length, add 8 bytes for each KEY that allows duplicates. Add 4 bytes if the file allows variable record lengths. Finally, allow 6 bytes for overhead per page.

For example: If the record size is 300 bytes and the file has three KEYs that allow Duplicates, the total record size is:

     	300	record size

x	24	overhead for three KEYs with the DUP attribute

324	physical record length

A page size of 512 would only hold one such record, and 182 bytes per page would go unused (512 - 6 - 324). If the page size were 1024, three records could be stored per page and only 46 bytes would go unused (1024 - 6 - (324 * 3)).


DOS Files

The DOS file driver reads and writes binary, byte-addressable files. Neither fields nor records are delimited. When reading a record, the driver reads the number of bytes defined in the files RECORD structure, unless a length parameter is specified in the GET statement.

The DOS driver supports the length parameter for the ADD, APPEND, GET, and PUT statements; this allows for variable length records in a DOS file.

The POINTER function returns the relative byte position within the file of the beginning of the last record accessed by an ADD, APPEND, GET, or NEXT statement.

This file driver performs forward sequential processing only. No key or transaction processing functions are supported, and the PREVIOUS statement is not supported.

Tip:	Due to its limitations, the main function of this driver is as a disk editor for binary files.


DOS: Driver Strings

/FILEBUFFERS=n	Specifies a value for the number of buffers used to read and write to the file.

The DOS driver allocates internal buffers of 512 bytes, or the size of your record, whichever is larger, to store the retrieved file. The default number of buffers is 2 for files opened denying write access to other users, and 1 for all other open modes. Use the optional driver string to increase the buffers should you find access to records is slow.

/QUICKSCAN=on|off	The DOS driver reads a buffer at a time (not a record), allowing for fast access. In a multi-user environment these buffers are not 100% trustworthy for subsequent access, because another user may change the database between accesses. As a safeguard, the driver re-reads the buffers before each record access. To disable the re-read, set QUICKSCAN to ON. The default is ON for files opened denying write access to other users, and OFF for all other open modes.

Using the Send Command


DOS: Data Types

BYTE	DECIMAL

SHORT	PDECIMAL

USHORT	STRING

LONG	CSTRING

ULONG	PSTRING

SREAL	DATE

REAL	TIME

BFLOAT4	GROUP


DOS: File Specifications/Maximums

File Size:              Unsigned Long (4,294,967,295)

Records per File:       Unsigned Long (4,294,967,295)

Record Size:            64K

Field Size:             64K

Fields per Record:      64K

Keys/Indexes per File:  n/a

Key Size:               n/a

Memo fields per File:   0

Memo Field Size:        n/a

Open Data Files:        Operating system dependent


DOS: Unsupported Functions and Attributes

Memos:	NOMEMO()

Transaction Processing:	COMMIT(), LOGOUT(), ROLLBACK()

Key Processing:	BUILD(key), BUILD(index), GET(file,key), GET(key,keypointer), RESET(key,string), SET(file,key), SET(key), SET(key,key), SET(key,keypointer), SET(key,key,filepointer), DUPLICATE(), POINTER(key), POSITION(key), RECORDS(key), RESET(key), REGET(key)

Record Locking:	HOLD(), RELEASE()

File Buffering:	STREAM()

File Information:	RECORDS(file)

Sequential Processing:	PREVIOUS(), BOF(), SKIP()

File Manipulation:	BUILD(), DELETE(), PACK(), WATCH(), REGET()


Clarion Files

The Clarion file driver is compatible with the file system used by Clarion Database Developer 3.0 and Clarion Professional Developer (v. 2.1).

Keys and Indexes exist as separate files from the data file. Keys are dynamic--they automatically update as the data file changes. The default file extension for a key file is *.K##. Indexes are static--they do not automatically update, but instead require the BUILD statement for updating.

The driver stores records as fixed length. It stores memo fields in a separate file. The memo file defaults to the first eight characters of the File Label plus an extension of .MEM,.

Files:	CDDWC21.LIB 	Windows Export Library

CDDWC21.DLL	Windows Dynamic Link Library

Tip:	By avoiding the ASCII-only file formats of many other popular PC database application development systems, the Clarion file format provides a more secure means of storing data.


Clarion: Data Types

BYTE	DECIMAL

SHORT	STRING (255 byte maximum)

LONG	MEMO

REAL	GROUP


Clarion: Maximum File Specifications:

File Size	:	limited only by disk space

Records per File	:	4,294,967,295

Record Size	: 	65,520 bytes

Field Size	:	65,520 bytes

Fields per Record	: 	65,520 bytes

Keys/Indexes per File	: 	251

Key Size 	: 	245 bytes

Memo fields per File	:	1

Memo Field Size	: 	65,520 bytes

Open Data Files	:	Operating system dependent


Clarion: Driver Strings

/RECOVER	 may not be used as a DRIVER string--you may only use it with the SEND function.

RECOVER=n	The RECOVER string, when n is greater than 0, UNLOCKs a data file, or RELEASEs a held record in order to recover from a system crash. n represents the number os seconds to wait before invoking the recovery. When n is equal to 1, the recovery process is invoked immediately.  When n is equal to 0, the recovery process is disarmed. The SEND function returns a blank string.

To RELEASE a held record, you must read that record into memory. If there are multiple held records, loop through the entire file after SENDing the RECOVER= message to the driver.

Using the Send Command


Clarion: Unsupported Functions and Attributes

••Record Access:	GET(file, fileptr, len), ADD(file, len), APPEND(file, len)

The driver does not support variable length records.

••File updates:   PUT(file, fileptr, len)

The driver does not support variable length records.

••EOF(file), BOF(file)

Although the driver supports these functions, we do not recommend their use. These functions must physically access the files in order to operate, adding considerable overhead. Instead, test the value returned by ERRORCODE() after each sequential access. NEXT() or PREVIOUS() post Error 33 (Record Not Available) if an attempt is made to access a record beyond the end or beginning of the file.


Clipper Files

The Clipper file driver is compatible with Clipper Summer 87 and Clipper 5.0. There are slight differences between the two, which are documented below. The default data file extension is *.DBF.

Keys and Indexes exist as separate files from the data file. Keys are dynamic--they automatically update as the data file changes. Indexes are static--they do not automatically update, but instead require the BUILD statement for updating. The default file extension for the index file is *.NTX.

The driver stores records as fixed length. It stores memo fields in a separate file. The memo file name takes the first eight characters of the File Label plus an extension of .DBT.

Files:	CDDWCLIP.LIB	Windows Export Library

CDDWCLIP.DLL	Windows Dynamic Link Library

Tip:	As a popular Xbase database application development system, Clipper provides a common file format for a huge base of installed business applications and the data files created by them. Use the Clipper driver to access these files.


Clipper: Data Types

The file format stores all data as ASCII strings. You may either specify STRING types with pictures for each field, or specify native Clarion types, the driver converts automatically.

Clipper data type	Clarion data type	STRING w/ picture

Date	DATE	STRING(@D12)

*Numeric	REAL	STRING(@N_p.d)

*Logical	BYTE	STRING(1)

Character	STRING 	STRING

*Memo	MEMO	MEMO

If your application creates a Clipper file, you may need to specify additional information for the Clipper types marked with an asterisk.

•	To create a numeric field, using the data dictionary, choose the REAL data type and specify the number of decimal places in the Field Properties dialog.

If youre hand coding a native Clarion data type, add the NAME attribute: NAME(Number = N(9,2)), where Number is the field name. If youre handcoding a STRING with picture, STRING(@N_9.2), NAME(Number), where Number is the field name.

•	To create a logical field, using the data dictionary, choose the BYTE data type. There are no special steps; however, see the miscellaneous section, below, for tips on reading the data from the field.

If youre hand coding a STRING with picture, add the NAME attribute: STRING(1), NAME(LogFld = L).

•	To create a date field, using the data dictionary, choose the DATE data type, rather than LONG, which you usually use for the TopSpeed or Clarion file formats.

If youre hand coding a native Clarion data type, add the NAME attribute: NAME(TheDay), where TheDay is the field name. If youre handcoding a STRING with picture, STRING(@D12), NAME(TheDate), where TheDate is the field name.

o	MEMO field declarations require the a pointer field in the .DBF files record structure. Declare the pointer field as a STRING(10) or a LONG. This field will be stored in the .DBF file containing the offset of the memo in the .DBT file. The MEMO declaration must have a NAME() attribute naming the pointer field. An example file declaration follows:

File	FILE, DRIVER(Clipper)

Memo1	MEMO(200), NAME(Notes)

Memo2	MEMO(200), NAME(Text)

Rec	RECORD

Mem1Ptr	LONG, NAME(Notes)

Mem2Ptr	STRING(10), NAME(Text)

END

END


Clipper: File Specifications/Maximums

File Size	:	2 Gigabytes (about 2 billion bytes)

Records per File	:	1 Gigabyte (about 1 billion)

Record Size:Clipper 5.0:	8,192 bytes

Clipper 87	:	4,000 bytes

Field Size

Character

 Clipper 5.0	:	2048 bytes

 Clipper 87	:	254 bytes

Date	:	8 bytes

Logical	:	1 byte

Numeric	:	20 bytes including decimal point

Memo	:	65,520

Fields per Record	:	255

Keys/Indexes per File:	No Limit

Key Sizes

Character	:	100 bytes

Numeric,Date	:	8 bytes

Memo fields per File:	Dependent on available memory

Open Files	:	Operating system dependent


Clipper: Driver Strings

/BUFFERS=n	Specifies a value for the number of buffers used to read and write to the file.

The Clipper driver utilizes DOS buffering. The default is three buffers of 1024 bytes each. Increasing the number of buffers does not increase performance when a file is shared by multiple users.

/EXTERRORS=on|off	Use only for debugging.

***	The above driver string may not be implemented anymore!!!

/RECOVER	Equivalent to the Xbase RECALL command, which recovers records marked for deletion. When using the Clipper driver, the DELETE() function flags a record as inactive. The driver does not physically remove the record until you call the PACK() function.

/RECOVER is evaluated each time the file is opened when you add the driver string to the data dictionary. When the driver recovers the records previously marked for deletion, you must manually rebuild keys and indexes with the BUILD() function.

Using the Send Command


Clipper: Unsupported/Modified Functions and Attributes

•	Memos: BINARY

Clipper supports only text memos.

•	Keys: NOCASE, OPT

•	File: ENCRYPT, OWNER, RECLAIM

The Clipper driver cannot read files encrypted by Clipper. To reclaim space from deleted records,  call PACK(file).

•	Transaction Processing: COMMIT(), LOGOUT(), ROLLBACK()

The Clipper driver does not support transaction logging.

•	Record Access:  GET(file, fileptr, len), ADD(file, len), APPEND(file, len)

Clipper does not support variable length records

•	File updates:   PUT(file, fileptr, len)

Clipper does not support variable length records

•	EOF(file), BOF(file)

Although the driver supports these functions, we do not recommend their use. They must physically access the files, adding considerable overhead. Instead, test the value returned by ERRORCODE() after each sequential access. NEXT() or PREVIOUS() post Error 33 (Record Not Available) if an attempt is made to access a record beyond the end or beginning of the file.

•	ADD(file) vs. APPEND(file)

The ADD() function tests for duplicate keys before modifying the data file or its associated KEY files. Consequently, it is slower than APPEND(), which performs no checks and does not update KEYs. When adding large amounts of data to a database use APPEND() and BUILD() in preference to ADD().

•	BUILD(key, str)

When building dynamic indexes, the str component may take one of two forms:••BUILD(DynNdx, '+Pre:FLD1, -Pre:FLD2')

This form specifies the names of the fields on which to build the index. The field names must appear exactly as specified in the fields NAME() attribute if supplied, or must be the label name. A prefix may be used for compatibility with the Clarion conventions but is ignored.

BUILD(DynNdx, 'T[Expression]')

This form specifies the type and Expression for building the index; see the Misccellaneous section, below.

•	COPY(file, newname)

The COPY() command copies data and memo files to newname, which may specify a new file name or directory path. Key or index files are copied if newname is a subdirectory specification. To copy an index file to a new file, a special syntax is required:

COPY(file,'<index>|<newname>')

This returns File Not Found if an invalid index is passed. In this case the COPY() command assumes a default extension of ".NTX" for both the source and the target file names if none is specified. If you require a filename without an extension, terminate the name with a period. Given the file structure:

Clar2	FILE,CREATE,DRIVER('Clipper')

NumKey	KEY(Num),DUP

StrKey	KEY(Str1)

StrKey2	KEY(Str2)

AMemo	MEMO(100), NAME('mem')

Record	RECORD

Num 	STRING(@n_9.2)

STR1	STRING(2)

STR2	STRING(2)

Mem 	STRING(10)

END

END

The commands to copy this file definition to A: would be:

COPY(Clar2,'A:\CLAR2')

COPY(Clar2,'StrKey|A:\STRKEY')

COPY(Clar2,'StrKey2|A:\STRKEY2')

COPY(Clar2,'NumKey|A:\NUMKEY')

The following files would subsequently exist on drive A: CLAR2.DBF, CLAR2.DBT, STRKEY.NTX, STRKEY2.NTX, and NUMKEY.NTX.

•	DELETE(file)

When deleting a record from a Clipper database, the driver does not physically remove the record, but instead marks it inactive. Memo fields are not physically removed from the memo file, however they will cannot be retrieved when they refer to an inactive record. Key values are removed from the index files. To remove records and memo fields permanently, execute a PACK(file).

Tip:	To those programmers familiar with Xbase languages, this driver processes deleted records consistent with the way Clipper processes them after the SET DELETED ON command is issued. Records marked for deletion are ignored from processing by executable code statements, but remain in the data file.

•	POINTER(file), POINTER(key)

There is no distinction between file pointers and key pointers. They both contain the same value for any given record.

•	POSITION(file), POSITION(key)

There is no distinction between file positions and key positions. They both contain the same value for any given record.

•	RECORDS(file), RECORDS(key)

The RECORDS() function reports the same number of records for the data file, its keys and indexes. Usually there will be no difference in the number of records unless a given INDEX is out of date. Because records are not removed by the DELETE() function, the number of records reported by the RECORDS() function includes these inactive records. Exercise care when using this function.

•	RENAME(file, newname)

The RENAME() command copies the data and memo files using newname which may specify a new file name or directory path. Rename Key and index files using the same notation as described for the COPY() command above.


Clipper: Miscellaneous

•	Clipper allows a logical field to accept one of nine possible values (y,Y,n,N,t,T,f,F or a space character). The space character is neither true nor false. If you use a logical field from a preexisting database in a logical expression, plan for all possible values. Remember that when an expression is evaluated as true or false, it is true if it contains any data and false if it is equal to zero or blank. Therefore, to evaluate a Logical fields truth, the expression is true if the field contains any of the true characters (T,t,Y, or y). For example, if a Logical field were used to specify a product as taxable or nontaxable, the expression to evaluate its truth would be:

(If Condition):

Taxable=T OR Taxable=t OR Taxable=Y OR Taxable=y

•	Clarion for Windows supports MEMO fields up to a maximum of 64K. If a preexisting file includes a memo greater than 64K, you can use the file but not modify the large MEMOs.

You can detect an oversized MEMO when the memo pointer variable is non-blank, but the memo appears to be blank. An error 47 (Bad Record Declaration) is posted, and any modification to the MEMO field is ignored.

•	Clipper supports a maximum of 10 characters in a field name. If you require more characters, use an External Name.

•	Clipper supports the use of expressions to define keys. Within the Dictionary Editor, you can place the expression in the external name field in the Key Properties dialog. The general format of the external name is :

        FileName=T[Expression]

Where FileName represents the name of the index file (which can contain a path and file extension), and T represents the type of the index. Valid types are: C = character, D = date, and N = numeric. If the type is D or N then the Expression can name only one field.

The expression may refer to multiple fields in the record, and contain xBase functions. Square brackets must enclose the expression. The currently supported functions appear below. If the driver encounters an unsupported function in a preexisting file, error 76 Invalid Index String appears when the file is opened for keys and static indexes.

String expressions may use the + operator to concatenate multiple string arguments. Numeric expressions use the + or - operators with their conventional meanings. The maximum length of a Clipper expression is 250 characters.

CTOD(string)	converts a string key to a date. The string format is mm/dd/yy; the resultant date takes the form yyyymmdd. The yyyy element defaults to the twentieth century. Specifying an invalid date results in a blank date key.

DESCEND(string|date|numeric)	inverts the argument, and creates descending Clipper indexes.

DTOC(date)	converts a date key to the string format mm/dd/yy

DTOS(date)	converts a date key to the string format yyyymmdd

FIXED(float)	converts a float key to a numeric.

FLOAT(numeric)	converts a numeric key to a float.

LEFT(string, n)	returns the leftmost n characters of the string key as a string of length n.

RIGHT(string, n)	returns the rightmost n characters of the string key as a string of length n.

STR(numeric [, length [, decimal places]])	converts a numeric key to a string. The length of the string and the number of decimal places are optional. The default string length is 10, and the number of decimal places is 0.

SUBSTR(string, offset, n)	returns a substring of the string key starting at offset, of n characters in length.

VAL(string)	converts a string key to a numeric.


dBase III Files

The dBase3 file driver is compatible with dBase III. The default file extension is *.DBF.

Keys and Indexes exist as separate files from the data file. Keys are dynamic--they automatically update as the data file changes. Indexes are static--they do not automatically update, but instead require the BUILD statement for updating. The default file extension for the index file is *.NTX.

The driver stores records as fixed length. It stores memo fields in a separate file. The memo file name takes the first eight characters of the File Label plus an extension of .DBT.

Files:	CDDWDB3.LIB    Windows Export Library

CDDWDB3.DLL  Windows Dynamic Link Library

Tip:	dBase III is probably the most widely used file format for PC database applications. These days, even desktop publishing programs can even import dBase III compatible .DBF files. If the main task of your application is to make data files available for other applications about which you know nothing about, you should consider this driver.


dBase III: Data Types

The file format stores all data as ASCII strings. You may either specify STRING types with pictures for each field, or specify native dBase III types, which will be converted automatically.

dBase data type	Clarion data type	STRING w/ picture

Date	DATE	STRING(@D12)

*Numeric	REAL	STRING(@N_p.d)

*Logical	BYTE	STRING(1)

Character	STRING 	STRING

*Memo	MEMO	MEMO

If your application creates a dBase III file, you may require additional information for the dBase III types marked with an asterisk.

•	To create a numeric field, using the data dictionary, choose the REAL data type and specify the number of decimal places in the Field Properties dialog.

If youre hand coding a native Clarion data type, add the NAME attribute: NAME(Number = N(9,2)), where Number is the field name. If youre handcoding a STRING with picture, STRING(@N_9.2), NAME(Number), where Number is the field name.

•	To create a logical field, using the data dictionary, choose the BYTE data type. There are no special steps; however, see the miscellaneous section, below, for tips on reading the data from the field.

If youre hand coding a STRING with picture, add the NAME attribute: STRING(1), NAME(LogFld = L).

•	To create a date field, using the data dictionary, choose the DATE data type, rather than LONG, which you usually use for the TopSpeed or Clarion file formats.

If youre hand coding a native Clarion data type, add the NAME attribute: NAME(TheDay), where TheDay is the field name. If youre handcoding a STRING with picture, STRING(@D12), NAME(TheDay), where TheDay is the field name.

•	MEMO field declarations require the a pointer field in the .DBF files record structure. Declare the pointer field as a STRING(10) or a LONG. This field will be stored in the .DBF file containing the offset of the memo in the .DBT file. The MEMO declaration must have a NAME() attribute naming the pointer field. An example file declaration follows:

File	FILE, DRIVER(dBase3)

Memo1	MEMO(200), NAME(Notes)

Memo2	MEMO(200), NAME(Text)

Rec	RECORD

Mem1Ptr	LONG, NAME(Notes)

Mem2Ptr	STRING(10), NAME(Text)

        END

END


dBase III: File Specifications/Maximums

File Size:              2GBytes

Records per File:       1GByte

Record Size:            4,000 bytes

Field Size

     Character:         254 bytes

     Date:              8 bytes

     Logical:           1 byte

     Numeric:           20 bytes including decimal point

     Memo:              64K (see note)

Fields per Record:      255

Keys/Indexes per File:  No Limit

Key Sizes

     Character:         100 bytes

     Numeric, Date:     8 bytes

Memo fields per File:   Dependent on available memory

Open Files:             Operating system dependent


dBase III: Driver Strings

/BUFFERS=n	Specify a value for the number of buffers used to read and write to the file.

The dBase III driver utilizes DOS buffering. The default is three buffers of 1024 bytes each. Increasing the number of buffers will not increase performance when a file is shared by multiple users.

/EXTERRORS=on|off	Use only for debugging.

***	The above driver string may no longer be implemented.

/RECOVER	Equivalent to the Xbase RECALL command, which recovers records marked for deletion. When using the dBase III driver, the DELETE() function flags a record as inactive. The driver does not remove the record until the PACK() function is invoked.

/RECOVER is evaluated each time you open the file if you add the driver string to the data dictionary. When the driver recovers the records previously marked for deletion, you must manually rebuild keys and indexes with the BUILD() function.

   /OMNIS	To specify OMNIS file header and file delimiter compatibility.

Using the Send Command


dBase III: Unsupported/Modified Functions and Attributes

•	Memos: BINARY

dBase III supports only text memos.

•	Keys: DUP, NOCASE, OPT, ascending|descending

•	File: ENCRYPT, OWNER, RECLAIM

The dBase III driver cannot read files encrypted by dBase III. To reclaim space from deleted records, call PACK(file).

•	Transaction Processing: COMMIT(), LOGOUT(), ROLLBACK()

The dBase III driver does not support any transaction logging.

•	Record Access:  GET(file, fileptr, len), ADD(file, len), APPEND(file, len)

dBase III does not support variable length records

•	File updates:   PUT(file, fileptr, len)

dBase III does not support variable length records

•	EOF(file), BOF(file)

Although the driver supports these functions, we do not recommend their use. They must physically access the files and add overhead. Instead, test the value returned by ERRORCODE() after each sequential access. NEXT() or PREVIOUS() post Error 33 (Record Not Available) if an attempt is made to access a record beyond the end or beginning of the file.

•	ADD(file) vs. APPEND(file)

The ADD() function tests for duplicate keys before modifying the data file or its associated KEY files. Consequently it is slower than APPEND() which performs no checks and does not update KEYs. When adding large amounts of data to a database use APPEND()...BUILD() in preference to ADD().

•	BUILD(key, str)

When building dynamic indexes, the str component may take one of two forms:

BUILD(DynNdx, '+Pre:FLD1, -Pre:FLD2')

This form specifies the names of the fields on which to build the index. The field names must appear as specified in the fields NAME() attribute if supplied, or must be the label name. A prefix may be used for compatibility with the Clarion conventions but is ignored.

BUILD(DynNdx, 'T[Expression]')

This form specifies the type and Expression used to build an index, see the miscellaneous section, below.

•	COPY(file, newname)

The COPY() command copies data and memo files using newname, which may specify a new file name or directory. Key or index files are copied if the newname is a subdirectory specification. To copy an index file to a new file, use a special form of the copy command:

COPY(file,'<index>|<newname>')

This returns File Not Found if an invalid index is passed. The COPY() command assumes a default extension of ".NTX" for both the source and the target file names if none is specified. If you require a filename without an extension, terminate the name with a period. Given the file structure:

Clar2	FILE,CREATE,DRIVER('dBase3')

NumKey	KEY(Num),DUP

StrKey	KEY(Str1)

StrKey2	KEY(Str2)

AMemo	MEMO(100), NAME('mem')

Record	RECORD

Num	STRING(@n_9.2)

STR1 	STRING(2)

STR2	STRING(2)

Mem	STRING(10)

END

END

The following commands copy this file definition to A:

COPY(Clar2,'A:\CLAR2')

COPY(Clar2,'StrKey|A:\STRKEY')

COPY(Clar2,'StrKey2|A:\STRKEY2')

COPY(Clar2,'NumKey|A:\NUMKEY')

After these calls, the following files would exist on drive A: CLAR2.DBF, CLAR2.DBT, STRKEY.NTX, STRKEY2.NTX, and NUMKEY.NTX.

•	DELETE(file)

When the driver deletes a record from a dBase III database, the record is not physically removed, instead the driver marks it inactive. Memo fields are not physically removed from the memo file, however they cannot be retrieved if they refer to an inactive record. Key values are removed from the index files. To remove records and memo fields permanently, execute a PACK(file).

Tip:	To those programmers familiar with dBase III, this driver processes deleted records consistent with the way dBase III processes them after the SET DELETED ON command is issued. Records marked for deletion are ignored from processing by executable code statements, but remain in the data file.

•	HOLD(file), HOLD(file, timeout)

dBase III performs record locking by locking the entire record within the data file. This prevents read access to other processes. Therefore we recommend minimizing the amount of time for which a record is held.

•	POINTER(file), POINTER(key)

There is no distinction between file pointers and key pointers; they both contain the same value for any given record.

•	POSITION(file), POSITION(key)

There is no distinction between file positions and key positions; they both contain the same value for any given record.

•	RECORDS(file), RECORDS(key)

Under dBase III the RECORDS() function reports the same number of records for the data file and its keys and indexes. Usually there will be no difference in the number of records unless the INDEX is out of date. Because the DELETE() function does not physically remove records, the number of records reported by the RECORDS() function includes inactive records. Exercise care when using this function.

•	RENAME(file, newname)

The RENAME() command copies the data and memo files using newname, which may specify a new file name or directory path. Key and index files must be renamed using the same syntax as the COPY() command, above.


dBase III: Miscellaneous

•	dBase III allows a maximum of 254 characters to a character field.

•	dBase III allows a logical field to accept one of nine possible values (y,Y,n,N,t,T,f,F or a space character). The space character is neither true nor false. When using a logical field from a preexisting database in a logical expression, account for all these possibilities. Remember that when an expression is evaluated as true or false, it is true if it contains any data and false if it is equal to zero or blank. Therefore, to evaluate a Logical fields truth, the expression should be true if the field contains any of the true characters (T,t,Y, or y). For example, if a Logical field were used to specify a product as taxable or nontaxable, the expression to evaluate its truth would be:

(If Condition):

Taxable=T OR Taxable=t OR Taxable=Y OR Taxable=y

•	Clarion for Windows supports MEMO fields up to a maximum of 64K. If you have an existing file which includes a memo greater than 64K, you can use the file but not modify the large MEMOs.

You can determine when your application encounters a large MEMO by detecting when the memo pointer variable is non-blank, but the memo appears to be blank. An error 47 (Bad Record Declaration) is posted, and any modification to the MEMO field is ignored.

•	dBase III supports a maximum of 10 characters in a field name. If you require more characters, use an External Name with ten characters or less.

•	dBase III supports the use of expressions to define keys. Within the Dictionary Editor, you can place the expression in the external name field in the Key Properties dialog. The general format of the external name is :

        FileName=T[Expression]

Where FileName represents the name of the index file (which can contain a path and file extension), and T represents the type of the index. Valid types are: C = character, D = date, and N = numeric. If the type is D or N then Expression can name only one field.

The expression may refer to multiple fields in the record, and contain xBase functions. Square brackets must enclose the expression. The currently supported functions appear below. If the driver encounters an unsupported Xbase function in a preexisting file, it posts error 76 Invalid Index String when the file is opened for keys and static indexes.

String expressions may use the + operator to concatenate multiple string arguments. Numeric expressions use the + or - operators with their conventional meanings. The maximum length of a dBase III expression is 250 characters.

CTOD(string)	converts a string key to a date. The string format mm/dd/yy; the result takes the form yyyymmdd. The yyyy element of the date defaults to the twentieth century. An invalid date results in a key containing blanks.

DESCEND(string|date|numeric)	inverts the argument, and creates descending dBase III indexes.

DTOC(date)	converts a date key to string format mm/dd/yy

DTOS(date)	converts a date key to string format yyyymmdd

FIXED(float)	converts a float key to a numeric.

FLOAT(numeric)	converts a numeric key to a float.

LEFT(string, n)	returns the leftmost n characters of the string key as a string of length n.

RIGHT(string, n)	returns the rightmost n characters of the string key as a string of length n.

STR(numeric [, length [, decimal places]])	converts a numeric to a string. The length of the string and the number of decimal places are optional. The default string length is 10, and the number of decimal places is 0.

SUBSTR(string, offset, n)	returns a substring of the string key starting at offset and of n characters in length.

VAL(string)	converts a string key to a numeric.


dBase IV Files

The dBase4 file driver is compatible with dBase IV. The default file extension is *.DBF. Because of the similarities between dBase III and dBase IV, this section only notes the differences between the two. For basic information about dBase IV files, please refer to the previous section on dBase III.

dBase IV supports multiple index files, whose default extension is *.MDX. The miscellaneous section, below, documents the procedures for using the .MDX files.

Files:	CDDWDB4.LIB    Windows Export Library

CDDWDB4.DLL  Windows Dynamic Link Library

Tip:	dBase IV was never as widely adopted a file format as dBase III. Choose this driver when you require compatibility specifically for sharing data with an end user using dBase IV.


dBase IV: Data Types

The file format stores all data as ASCII strings. You may either specify STRING types with pictures for each field, or specify native dBase IV types, which will be converted automatically.

dBase data type	Clarion data type	STRING w/ picture

Date	DATE	STRING(@D12)

*Numeric	REAL	STRING(@N_p.d)

*Logical	BYTE	STRING(1)

Character	STRING 	STRING

*Memo	MEMO	MEMO

If your application creates a dBase IV file, you may require additional information for the dBase IV types marked with an asterisk.

•	To create a numeric field, using the data dictionary, choose the REAL data type and specify the number of decimal places in the Field Properties dialog.

If youre hand coding a native Clarion data type, add the NAME attribute: NAME(Number = N(9,2)), where Number is the field name. If youre handcoding a STRING with picture, STRING(@N_9.2), NAME(Number), where Number is the field name.

•	To create a logical field, using the data dictionary, choose the BYTE data type. There are no special steps; however, see the miscellaneous section, below, for tips on reading the data from the field.

If youre hand coding a STRING with picture, add the NAME attribute: STRING(1), NAME(LogFld = L).

•	To create a date field, using the data dictionary, choose the DATE data type, rather than LONG, which you usually use for the TopSpeed or Clarion file formats.

If youre hand coding a native Clarion data type, add the NAME attribute: NAME(TheDay), where TheDay is the field name. If youre handcoding a STRING with picture, STRING(@D12), NAME(TheDay), where TheDay is the field name.

•	MEMO field declarations require the a pointer field in the .DBF files record structure. Declare the pointer field as a STRING(10) or a LONG. This field will be stored in the .DBF file containing the offset of the memo in the .DBT file. The MEMO declaration must have a NAME() attribute naming the pointer field. An example file declaration follows:

File	FILE, DRIVER(dBase4)

Memo1	MEMO(200), NAME(Notes)

Memo2	MEMO(200), NAME(Text)

Rec	RECORD

Mem1Ptr	LONG, NAME(Notes)

Mem2Ptr	STRING(10), NAME(Text)

        END

END


dBase IV: File Specifications/Maximums

File Size:              2GBytes

Records per File:       1GByte

Record Size:            4,000 bytes

Field Size

     Character:         254 bytes

     Date:              8 bytes

     Logical:           1 byte

     Numeric:           20 bytes including decimal point

     Float:             20 bytes including decimal point

     Memo:              64K (see note)

Fields per Record:      255

Keys/Indexes per File:  No Limit

Key Sizes

     Character:         100 bytes

     Numeric,Date:      8 bytes

Memo fields per File:   Dependent on available memory

Open Files:             Operating system dependent


dBase IV: Driver Strings

/BUFFERS=n	Specify a value for the number of buffers used to read and write to the file.

The dBase III driver utilizes DOS buffering. The default is three buffers of 1024 bytes each. Increasing the number of buffers will not increase performance when a file is shared by multiple users.

/EXTERRORS=on|off	Use only for debugging.

***	The above driver string may no longer be implemented.

/RECOVER	Equivalent to the Xbase RECALL command, which recovers records marked for deletion. When using the dBase III driver, the DELETE() function flags a record as inactive. The driver does not remove the record until the PACK() function is invoked.

/RECOVER is evaluated each time you open the file if you add the driver string to the data dictionary. When the driver recovers the records previously marked for deletion, you must manually rebuild keys and indexes with the BUILD() function.

Using the Send Command


dBase IV: Unsupported/Modified Functions and Attributes

•	Memos: BINARY

dBase IV supports only text memos.

•	Keys: DUP, NOCASE, OPT, ascending|descending

•	File: ENCRYPT, OWNER, RECLAIM

The dBase IV driver cannot read files encrypted by dBase IV. To reclaim space from deleted records, call PACK(file).

•	Transaction Processing: COMMIT(), LOGOUT(), ROLLBACK()

The dBase IV driver does not support any transaction logging.

•	Record Access:  GET(file, fileptr, len), ADD(file, len), APPEND(file, len)

dBase IV does not support variable length records

•	File updates:   PUT(file, fileptr, len)

dBase IV does not support variable length records

•	EOF(file), BOF(file)

Although the driver supports these functions, we do not recommend their use. They must physically access the files and add overhead. Instead, test the value returned by ERRORCODE() after each sequential access. NEXT() or PREVIOUS() post Error 33 (Record Not Available) if an attempt is made to access a record beyond the end or beginning of the file.

•	ADD(file) vs. APPEND(file)

The ADD() function tests for duplicate keys before modifying the data file or its associated KEY files. Consequently it is slower than APPEND() which performs no checks and does not update KEYs. When adding large amounts of data to a database use APPEND()...BUILD() in preference to ADD().

•	BUILD(key, str)

When building dynamic indexes, the str component may take one of two forms:

BUILD(DynNdx, '+Pre:FLD1, -Pre:FLD2')

This form specifies the names of the fields on which to build the index. The field names must appear as specified in the fields NAME() attribute if supplied, or must be the label name. A prefix may be used for compatibility with the Clarion conventions but is ignored.

BUILD(DynNdx, 'T[Expression]')

This form specifies the type and Expression used to build an index, see the miscellaneous section, below.

•	COPY(file, newname)

The COPY() command copies data and memo files using newname, which may specify a new file name or directory. Key or index files are copied if the newname is a subdirectory specification. To copy an index file to a new file, use a special form of the copy command:

COPY(file,'<index>|<newname>')

This returns File Not Found if an invalid index is passed. The COPY() command assumes a default extension of ".NTX" for both the source and the target file names if none is specified. If you require a filename without an extension, terminate the name with a period. Given the file structure:

Clar2	FILE,CREATE,DRIVER('dBase4')

NumKey	KEY(Num),DUP

StrKey	KEY(Str1)

StrKey2	KEY(Str2)

AMemo	MEMO(100), NAME('mem')

Record	RECORD

Num	STRING(@n_9.2)

STR1 	STRING(2)

STR2	STRING(2)

Mem	STRING(10)

END

END

The following commands copy this file definition to A:

COPY(Clar2,'A:\CLAR2')

COPY(Clar2,'StrKey|A:\STRKEY')

COPY(Clar2,'StrKey2|A:\STRKEY2')

COPY(Clar2,'NumKey|A:\NUMKEY')

After these calls, the following files would exist on drive A: CLAR2.DBF, CLAR2.DBT, STRKEY.NTX, STRKEY2.NTX, and NUMKEY.NTX.

•	DELETE(file)

When the driver deletes a record from a dBase IV database, the record is not physically removed, instead the driver marks it inactive. Memo fields are not physically removed from the memo file, however they cannot be retrieved if they refer to an inactive record. Key values are removed from the index files. To remove records and memo fields permanently, execute a PACK(file).

Tip:	To those programmers familiar with dBase IV, this driver processes deleted records consistent with the way dBase IV processes them after the SET DELETED ON command is issued. Records marked for deletion are ignored from processing by executable code statements, but remain in the data file.

•	HOLD(file), HOLD(file, timeout)

dBase IV performs record locking by locking the entire record within the data file. This prevents read access to other processes. Therefore we recommend minimizing the amount of time for which a record is held.

•	POINTER(file), POINTER(key)

There is no distinction between file pointers and key pointers; they both contain the same value for any given record.

•	POSITION(file), POSITION(key)

There is no distinction between file positions and key positions; they both contain the same value for any given record.

•	RECORDS(file), RECORDS(key)

Under dBase IVthe RECORDS() function reports the same number of records for the data file and its keys and indexes. Usually there will be no difference in the number of records unless the INDEX is out of date. Because the DELETE() function does not physically remove records, the number of records reported by the RECORDS() function includes inactive records. Exercise care when using this function.

•	RENAME(file, newname)

The RENAME() command copies the data and memo files using newname, which may specify a new file name or directory path. Key and index files must be renamed using the same syntax as the COPY() command, above.


dBase IV: Miscellaneous

•	Multiple-index (.MDX) files require the NAME() attribute on a KEY or INDEX to specify the storage type of the key and any expression used to generate the key values. The general format of the NAME() attribute on a KEY or INDEX is:

    NAME(TagName|FileName[PageSize]=T[Expression],FOR[Expression])

The following documents the parameters for the NAME() attribute:

    TagName 	Specifies the name of an index tag within a multiple index file. If omitted the driver creates a dBase III style .NDX file using the name specified in FileName.

    FileName	Specifies the name of the index file, which may contain a path and extension.

    PageSize	Specifies that when creating a .MDX file, (if a TagName is specified),  a number in the range 2-32 specifying the number of 512-byte blocks in each index page. This value is only used when creating the file. If you specify multiple values via declarations for different tags in the same .MDX file, the largest value will be selected. The default value is 2.

    T	Specifies the type of the index,. Legal types are C = character, D = date, N = numeric. If the type is D or N then Expression may name only one field.

    Expression	Specifies an expression to generate the index. It may refer to multiple fields, and invoke multiple xBase functions. The functions currently supported are listed below. Square brackets must enclose the expression.

Elements of the NAME() attribute may be omitted from the right. When specifying an Expression, you must also specify the type and name. If the Expression is omitted, the driver determines the Expression from the key fields when the file is created, or from the index file when opened.

If the type is omitted, the driver determines the index type from the first key component when the file is created, or from the index file when opened.

If the NAME() attribute is omitted altogether, the index file name is determined from the key label. The path defaults to the same location as the .DBF.

Tag names are limited to 9 characters in length. If the supplied name is too long it is automatically truncated.

Specify all field names in the NAME() attribute without a prefix.

•	dBase IV logical fields support all the possible values listed for dBase III, plus, they may also hold byte values of 1 and 0.

•	dBase IV additionally supports the use of the Xbase FOR statement in expressions to define keys. The expressions supported in the FOR condition must be a simple condition of the form:

    expression comparison_op expression

comparison_op may be one of the following: <, <=, =<, <>, =, =>, >= or >.

•	All functions supported by the dBase III driver are also supported by the dBase IV driver, except DESCEND().


FoxPro Files

The FoxPro file driver is compatible with FoxPro 2.x. The default file extension is *.DBF. The default index file extension is *.IDX. The default memo file extension is *.FBT.

Because of the similarities between dBase III and FoxPro, this section only notes the differences between the two. For basic information about FoxPro files, please refer to the previous section on dBase III.

FoxPro supports multiple index files, whose default extension is *.CDX. The miscellaneous section, below, documents the procedures for using the .CDX files.

Files:	CDDWFOX.LIB    Windows Export Library

CDDWFOX.DLL  Windows Dynamic Link Library

Tip:	The FoxPro index file format is the backbone of its vaunted Rushmore technology. The old saying theres no free lunch, however, applies. Adding and appending records to a large database is a slower process than in other Xbase file formats, due to the time required to update the index file.


FoxPro: Data Types

The file format stores all data as ASCII strings. You may either specify STRING types with pictures for each field, or specify native FoxPro types, which will be converted automatically.

FoxPro type	Clarion data type	STRING w/ picture

Date	DATE	STRING(@D12)

*Numeric	REAL	STRING(@N_p.d)

*Logical	BYTE	STRING(1)

Character	STRING 	STRING

*Memo	MEMO	MEMO

If your application creates a FoxPro file, you may require additional information for the FoxPro types marked with an asterisk.

•	To create a numeric field, using the data dictionary, choose the REAL data type and specify the number of decimal places in the Field Properties dialog.

If youre hand coding a native Clarion data type, add the NAME attribute: NAME(Number = N(9,2)), where Number is the field name. If youre handcoding a STRING with picture, STRING(@N_9.2), NAME(Number), where Number is the field name.

•	To create a logical field, using the data dictionary, choose the BYTE data type. There are no special steps; however, see the miscellaneous section, below, for tips on reading the data from the field.

If youre hand coding a STRING with picture, add the NAME attribute: STRING(1), NAME(LogFld = L).

•	To create a date field, using the data dictionary, choose the DATE data type, rather than LONG, which you usually use for the TopSpeed or Clarion file formats.

If youre hand coding a native Clarion data type, add the NAME attribute: NAME(TheDay), where TheDay is the field name. If youre handcoding a STRING with picture, STRING(@D12), NAME(TheDay), where TheDay is the field name.

•	MEMO field declarations require the a pointer field in the .DBF files record structure. Declare the pointer field as a STRING(10) or a LONG. This field will be stored in the .DBF file containing the offset of the memo in the .DBT file. The MEMO declaration must have a NAME() attribute naming the pointer field. An example file declaration follows:

File	FILE, DRIVER(FoxPro)

Memo1	MEMO(200), NAME(Notes)

Memo2	MEMO(200), NAME(Text)

Rec	RECORD

Mem1Ptr	LONG, NAME(Notes)

Mem2Ptr	STRING(10), NAME(Text)

        END

END


FoxPro: File Specifications/Maximums

File Size:              2GBytes

Records per File:       1GByte

Record Size:            4,000 bytes

Field Size

     Character:         254 bytes

     Date:              8 bytes

     Logical:           1 byte

     Numeric:           20 bytes including decimal point

     Float:             20 bytes including decimal point

     Memo:              64K (see note)

Fields per Record:      255

Keys/Indexes per File:  No Limit

Key Sizes

     Character:         100 bytes

     Numeric,Date:      8 bytes

Memo fields per File:   Dependent on available memory

Open Files:             Operating system dependent


FoxPro: Driver Strings

/BUFFERS=n	Specify a value for the number of buffers used to read and write to the file.

The FoxPro driver utilizes DOS buffering. The default is three buffers of 1024 bytes each. Increasing the number of buffers will not increase performance when a file is shared by multiple users.

/EXTERRORS=on|off	Use only for debugging.

***	The above driver string may no longer be implemented.

/RECOVER	Equivalent to the Xbase RECALL command, which recovers records marked for deletion. When using the FoxPro driver, the DELETE() function flags a record as inactive. The driver does not remove the record until the PACK() function is invoked.

/RECOVER is evaluated each time you open the file if you add the driver string to the data dictionary. When the driver recovers the records previously marked for deletion, you must manually rebuild keys and indexes with the BUILD() function.

Using the Send Command


FoxPro: Unsupported or Modified Functions and Attributes

•	Memos: BINARY

FoxPro supports only text memos.

•	Keys: DUP, NOCASE, OPT, ascending|descending

•	File: ENCRYPT, OWNER, RECLAIM

The FoxPro driver cannot read files encrypted by FoxPro. To reclaim space from deleted records, call PACK(file).

•	Transaction Processing: COMMIT(), LOGOUT(), ROLLBACK()

The FoxPro driver does not support any transaction logging.

•	Record Access:  GET(file, fileptr, len), ADD(file, len), APPEND(file, len)

FoxPro does not support variable length records

•	File updates:   PUT(file, fileptr, len)

FoxPro does not support variable length records

•	EOF(file), BOF(file)

Although the driver supports these functions, we do not recommend their use. They must physically access the files and add overhead. Instead, test the value returned by ERRORCODE() after each sequential access. NEXT() or PREVIOUS() post Error 33 (Record Not Available) if an attempt is made to access a record beyond the end or beginning of the file.

•	ADD(file) vs. APPEND(file)

The ADD() function tests for duplicate keys before modifying the data file or its associated KEY files. Consequently it is slower than APPEND() which performs no checks and does not update KEYs. When adding large amounts of data to a database use APPEND()...BUILD() in preference to ADD().

•	BUILD(key, str)

When building dynamic indexes, the str component may take one of two forms:

BUILD(DynNdx, '+Pre:FLD1, -Pre:FLD2')

This form specifies the names of the fields on which to build the index. The field names must appear as specified in the fields NAME() attribute if supplied, or must be the label name. A prefix may be used for compatibility with the Clarion conventions but is ignored.

BUILD(DynNdx, 'T[Expression]')

This form specifies the type and Expression used to build an index, see the miscellaneous section, below.

•	COPY(file, newname)

The COPY() command copies data and memo files using newname, which may specify a new file name or directory. Key or index files are copied if the newname is a subdirectory specification. To copy an index file to a new file, use a special form of the copy command:

COPY(file,'<index>|<newname>')

This returns File Not Found if an invalid index is passed. The COPY() command assumes a default extension of ".NTX" for both the source and the target file names if none is specified. If you require a filename without an extension, terminate the name with a period. Given the file structure:

Clar2	FILE,CREATE,DRIVER('FoxPro)

NumKey	KEY(Num),DUP

StrKey	KEY(Str1)

StrKey2	KEY(Str2)

AMemo	MEMO(100), NAME('mem')

Record	RECORD

Num	STRING(@n_9.2)

STR1 	STRING(2)

STR2	STRING(2)

Mem	STRING(10)

END

END

The following commands copy this file definition to A:

COPY(Clar2,'A:\CLAR2')

COPY(Clar2,'StrKey|A:\STRKEY')

COPY(Clar2,'StrKey2|A:\STRKEY2')

COPY(Clar2,'NumKey|A:\NUMKEY')

After these calls, the following files would exist on drive A: CLAR2.DBF, CLAR2.DBT, STRKEY.NTX, STRKEY2.NTX, and NUMKEY.NTX.

•	DELETE(file)

When the driver deletes a record from a FoxPro database, the record is not physically removed, instead the driver marks it inactive. Memo fields are not physically removed from the memo file, however they cannot be retrieved if they refer to an inactive record. Key values are removed from the index files. To remove records and memo fields permanently, execute a PACK(file).

Tip:	To those programmers familiar with FoxPro, this driver processes deleted records consistent with the way FoxPro processes them after the SET DELETED ON command is issued. Records marked for deletion are ignored from processing by executable code statements, but remain in the data file.

•	HOLD(file), HOLD(file, timeout)

FoxPro performs record locking by locking the entire record within the data file. This prevents read access to other processes. Therefore we recommend minimizing the amount of time for which a record is held.

•	POINTER(file), POINTER(key)

There is no distinction between file pointers and key pointers; they both contain the same value for any given record.

•	POSITION(file), POSITION(key)

There is no distinction between file positions and key positions; they both contain the same value for any given record.

•	RECORDS(file), RECORDS(key)

Under FoxPro the RECORDS() function reports the same number of records for the data file and its keys and indexes. Usually there will be no difference in the number of records unless the INDEX is out of date. Because the DELETE() function does not physically remove records, the number of records reported by the RECORDS() function includes inactive records. Exercise care when using this function.

•	RENAME(file, newname)

The RENAME() command copies the data and memo files using newname, which may specify a new file name or directory path. Key and index files must be renamed using the same syntax as the COPY() command, above.


FoxPro: Miscellaneous

•	Multiple-index (.CDX) files require the NAME() attribute on a KEY or INDEX to specify the storage type of the key and any expression used to generate the key values. The general format of the NAME() attribute on a KEY or INDEX is:

    NAME(TagName|FileName[PageSize]=T[Expression],COMPRESSED)

The following documents the parameters for the NAME() attribute:

TagName	Names an index tag within a multiple index file. If the TagName is omitted the driver creates an .IDX file with the name specified in FileName.

FileName	Names the index file, and optionally contains a path and extension.

PageSize	May only be specified when creating a .CDX file (if a TagName is specified). It is a number in the range 2-32 specifying the number of 512-byte blocks in each index page. This value is only used when creating the file. If multiple values are specified via declarations for different tags in the same .MDX file, the largest value will be selected. The default value is 2.

T	Specifies the type of the index; legal types are C = character, D = date, N = numeric. If the type is D or N then Expression may name only one field.

Expression	Specifies the expression used to generate the index. The expression may refer to multiple fields, and invoke multiple of xBase functions. The functions currently supported are listed below. Square brackets must enclose the expression.

COMPRESSED	When specified, the FoxPro Driver creates a FoxPro 2 compatible compressed .IDX file.

Elements of the NAME() attribute may be omitted from the right. When specifying an Expression, the type and name must also be specified. If the Expression is omitted, the driver determines the Expression from the key fields when the file is created, or from the index file when opened.

If the type is omitted, the driver determines the index type from the first key component when the file is created, or from the index file when opened.

If the NAME() attribute is omitted altogether, the index file name is determined from the key label. The path defaults to the same location as the .DBF.

Tag names are limited to 9 characters in length; if the supplied name is too long it is automatically truncated.

All field names in the NAME() attribute must be specified without a prefix.


Paradox Files

The Paradox3 file driver is compatible with the file system used by Paradox prior to version 4.0. Clarion for Windows reads Paradox files only from a local disk drive--it cannot read Paradox files from a network drive. If you need to access data files across a network, first copy them to a local disk drive.

The driver reads Paradox keyed and non-keyed tables. Keyed tables contain a primary key which is a KEY defined on the first field (and possibly subsequent adjacent fields) in the record. All INDEXes defined for a keyed table are incremental and are updated in the same way as KEYs. All KEYs and INDEXes other than the primary key are mapped to Paradox secondary indexes. Non-keyed tables are tables which do not define a KEY on the first field. Any KEYs defined for fields other than the first in the record are mapped to Paradox secondary indexes.

The Paradox table (data file) defaults to the *.DB file extension. A *. PX file contains the primary key. Secondary key files (indexes) default to the extensions .X## and .Y##, where ## denotes the number of the field used in the key.

All updates to a keyed table result in the primary key and all secondary keys (KEYs and INDEXes) index file being updated. There is a 1:1 relationship between the records in a keyed table and its key and index files.

The driver stores records as fixed length. The Paradox driver does not support MEMO fields.

Files:	CDDWPDX3.LIB    Windows Export Library

CDDWPDX3.DLL    Windows Dynamic Link Library

Tip:	The Paradox file format requires physically resorting the file upon an update to a key. Avoid using this driver for large databases which the end user frequently adds records to, or changes the primary key on.


Paradox: Data Types

Clarion Data Type	Paradox data type

STRING	ALPHANUMERIC

REAL 	NUMERIC

REAL 	CURRENCY

DATE 	DATE

SHORT	SHORT

The internal representation of the Clarion REAL, SHORT, and DATE is slightly different from the Paradox NUMERIC, CURRENCY, SHORT, and DATE storage formats. The driver automatically handles the conversion between Clarion and Paradox types.


Paradox: File Specifications/Maximums:

File Size:              4 billion bytes

Records per File:       2 billion

Record Size:

    Non-keyed table:    4,000 bytes

    Keyed table:        1,350 bytes

Field Size

     Alphanumeric:

        Non-keyed:      4,000 bytes

        Primary key:    1,350 bytes

        Index:          263 bytes

     Date:              8 bytes

     Currency:          8 bytes

     Numeric:           8 bytes

     Short:             2 bytes

Fields per Record:      255

Keys/Indexes per File:  255

Key Sizes:              Same as field size

Open Files:             Operating system dependent


Paradox: Driver Strings

USERID=<UserId>	see PARADOX.NET

PARADOX.NET=<Path>	Utilizing the driver in a network setting requires initialization before using any of the Network support functions. Prior to opening a Paradox file on a Network, the location for the PARADOX.NET file and a user ID must be supplied using the SEND() function, e.g:

str = SEND(file, USERID=JOHN_DOE)

str = SEND(file, PARADOX.NET=Z:\PARADOX\DATA)

SHARE(file)

The user ID may contain up to 15 characters; longer strings are truncated. Both these SEND() commands may be used to query the current status by omitting the assignment in the string.

See the Using the SEND Command section, below.

LOCKID=	If an attempt to access a Paradox file fails because another user has locked the file, or a record within the file, the LOCKID SEND() command can return the user ID of the user who is blocking access.

See the Using the SEND Command section, below.

SORTORDER=<SortSeq>	The Paradox driver supports international sort sequences using a set of internal tables. The supported sort sequences are:

ASCII   Standard ASCII sort order

INTL    Sorts characters irrespective of case and accents

NORDAN  Norwegian/Danish sort order:

 !#$%&()*+,-.0123456789:;<=>?@a…ƒAbBc‡C€dDe‰‚ŠˆE�f FgGhHi‹¡� ŒIjJkKlLmMn¤N¥o¢OpPqQrRsStTu£UvVwWxXy�˜ YšzZ[\]^_`{|}~†�„Žœ›�™žŸ¦§¨©ª«¬­®¯°±²³´µ¶·¸¹º»¼½¾¿ ÀÁÂÃ{BMC ARROW.BMP}ÅÆ ÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâã [image] åæçèéêëìíîï ðñòóôõö ÷øùúûüýþ

SWEDFIN Swedish/Finnish sort order:

!#$%&()*+,-.0123456789:;<=>?@a …ƒAbBc‡C€dDe‰‚ŠˆE�f FgGhHi‹¡�ŒIjJkKlLmMn¤N¥o¢OpPqQrRsStTu£--UvVwWxXy˜Y zZ[\]^_`{|}~†„Ž�™�š›œ�žŸ¦§¨©ª«¬­®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃ{BMC ARROW.BMP}ÅÆÇÈÉÊËÌÍÎÏÐÑÒÓ ÔÕÖ×ØÙÚÛÜÝÞßàáâã [image] åæçèéêëìíîïðñòóôõö÷øùúûüýþ

The sort order is established when the file is created. When creating a file to support a sort order other than ASCII the sort order must be specified using the /SORTORDER driver string.

If you try to open a file created with a sort order different from that specified by the /SORTORDER driver string, an Access Denied error occurs. Use the PDXREC utility (a DOS utility) to determine a Clarion FILE declaration for use with a given Paradox table.

To determine the current sort order for a given file, use the SEND() command. This returns ASCII, INTL, NORDAN or SWEDFIN as appropriate. The file does not have to be open; if the file does not exist or some other error occurs, the command returns a blank string.

/EXTERRORS=on|off	Use only for debugging.

***	The above driver string may no longer be implemented.

Using the Send Command


Paradox: Unsupported/Modified Functions and Attributes

•	Keys: NOCASE, OPT

•	File: ENCRYPT, OWNER, RECLAIM

The Paradox driver does not support encryption, nor does it read files encrypted by Paradox. RECLAIM is ignored since Paradox performs its own packing.

•	Transaction Processing: COMMIT(), LOGOUT(), ROLLBACK()

The Paradox driver does not support transaction logging.

•	Buffering Control: STREAM(), FLUSH()

There is no buffering control within the Paradox driver.

•	Record Access:  GET(file, fileptr, len), ADD(file, len), APPEND(file, len)

The Paradox driver does not support variable length records.

•	File updates:   PUT(file, ptr), PUT(file, fileptr, len)

The Paradox driver does not support updating any record other than the current record.

•	EOF(file), BOF(file)

Although the driver supports these functions, we do not recommend them. They must physically access the files in order to operate and add overhead. Instead, test the value returned by ERRORCODE() after each sequential access. NEXT() or PREVIOUS() post Error 33 (Record Not Available) if an attempt is made to access a record beyond the end or beginning of the file.

•	ADD(file) vs. APPEND(file)

For keyed tables these functions operate identically, updating the data file and associated key and index files.

•	BUILD(key, str)

When building dynamic indexes, str may contain one field only. The driver builds a secondary index; for keyed-tables this will be maintained as a KEY.

•	DUPLICATE(file),  DUPLICATE(key)

Paradox secondary keys explicitly allow duplicates, for this reason a duplicate key error will only be generated for a primary key. The DUPLICATE() functions do not check for duplicate key values in secondary keys.

•	POINTER()

Paradox keyed files and keys are always reordered whenever a record is written to the file (as if PACK() were called after each update). This means that values returned by the POINTER() function may not be valid after an ADD(), PUT(), or DELETE(), use POSITION() instead.

•	POSITION()

When accessing a keyed table the string returned by the POSITION() function contains the value for the primary key for the current record. For a non-keyed table, POSITION(file) returns the current record number, and POSITION(key) returns the value of the specified key for the current record.

v	PUT(), DELETE() and sequential processing

Paradox keyed tables are maintained in primary key order. When a record is deleted or inserted during sequential processing, the driver must compensate for any change in the sequence. Unpredictable results may occur if PUT() or DELETE() are called between a SET() or RESET(), and a subsequent NEXT(), PREVIOUS() or SKIP().


Paradox: Miscellaneous

The Paradox primary key must contain the first field (or fields) in the record structure. If the primary key contains multiple fields, they MUST be contiguous fields at the beginning of the RECORD structure, and the components of the KEY must appear in the same order as they do in the record. In addition, the primary key declaration must appear before all other KEY and INDEX declarations in the FILE structure.

Secondary keys are created for any key fields other than the first field in a record. The driver automatically updates these if the table contains a primary key; otherwise they are only updated when BUILD() is called. A Secondary key may not contain multiple component fields.

IMPORTANT: When creating code to update existing Paradox Tables, ensure that the record structure exactly matches that used by Paradox. If the Paradox Table has a primary key, ensure that a key exists for the first field in the record structure, otherwise it may be possible to enter records which create duplicate keys. You may use the suppled PDXREC utility (a DOS program) to build an include file containing a record definition for a specified table. Type PDXREC with no parameters for usage instructions.


TopSpeed Driver

The new TopSpeed driver is a high-performance, high-security, proprietary Clarion file driver. It is not compatible with Clarion 2.1 and 3.0 files. Data, keys, indexes and memos can all be stored together in a single DOS file. The default file extension is *.TPS. A separate Transaction Control File takes the *.TCF extension.

The TopSpeed driver can optionally store multiple Clarion files in a single DOS file. This allows you to open as many data files, keys and indexes as necessary using a single DOS file handle. This feature may be especially useful when there are a large number of small tables, or when a group of related files are normally accessed together.

Files:	CDDWTPS.LIB     Windows Export Library

    	CDDWTPS.DLL   Windows Dynamic Link Library

Tip:	This new driver offers speed, security, flexibility, and takes up fewer resources on the end users system.


TopSpeed: Data Types

BYTE	DECIMAL

SHORT	STRING

LONG	CSTRING

ULONG	PSTRING

FLOAT	MEMO

REAL	GROUP


TopSpeed: Maximum File Specifications

File Size:              Limited only by disk space

Records per File:       Unsigned Long (4,294,967,295)

Record Size:            64K

Field Size:             64K

Fields per Record:

Keys/Indexes per File:  240

Key Size:

Memo fields per File:   255

Memo Field Size:        64K

Open Data Files:        Operating system dependent


TopSpeed: Driver Strings

PNM=<previous name>	For use in a SEND command only. Enumerates the names of the files in a group (a DOS file containing multiple Clarion files). The file must first be open to a representative of the group. The output takes the form of a string, with individual file names separated by commas, in alphabetic order.

TCF=<transaction file name>	Specifies a transaction control file other than the default \TOPSPEED.TCF. The file holds all multi-file commits until the program terminates or a SEND(TCF=<transaction file name>) executes.

Using the Send Command


TopSpeed: Unsupported Functions and Attributes

•	Record Access:	GET(file, fileptr, len), ADD(file, len), APPEND(file, len)

 The TopSpeed Driver does not support variable length records

•	File updates:   PUT(file, fileptr, len)

 The TopSpeed Driver does not support variable length records

•	APPEND()

APPEND() is recommended over ADD() if the total size of the keys exceeds the amount of RAM available, if there is more than one key, or when adding a large number of records. The size of a key (for this purpose) is the number of entries times (the sum of key fields + 10 bytes). If the records being added are already in an approximate key order, then you can discount that key for the purposes of the above calculation.

 As an example, if a file has two 40 byte keys and 2 Megabytes of RAM are available, then ADD() becomes (relatively) slow when the database size exceeds about 2,000,000 / (40 + 10 + 40 + 10) = 20,000 records.

•	BUILD(file), BUILD(key)

The Topspeed driver implements incremental building; this means that building a key only reads records starting from the first record appended since the key was last built. The driver merges the new keys with the existing key. Thus building a large key where only a few recently added records have been modified should be fast. Building an index is similar, but must start at the minimum physical record whose position in the index has changed since the index was last built.

Dynamic indexes are not retained, so cannot be built incrementally.

•	LOCK(file)

LOCK() only affects other LOCK() calls. The only effect of a successful call to LOCK() is that other processes will get an error FLALLK when they call LOCK().

•	LOGOUT(), COMMIT(), ROLLBACK()

A transaction control file is used to ensure that transactions which update more than one DOS file are committed atomically. By default the transaction control file (TCF) has the name \TOPSPEED.TCF.  A SEND() command allows you to change this.

The TCF file must be accessible when any files controlled by it are accessed. If a transaction involves updating more than one shared network file, you should specify a transaction control file on the network. It is not necessary to use the same TCF file for all transactions; however, it must reside where it can be read by everyone accessing the file. If not, after a crash/power-fail during a COMMIT(), some files may be updated, and others not. (The files will not be corrupted - they may just not be consistent with one another)

A .TCF file can be deleted only if all files controlled by it may have been opened (for writing) since a crash/power-fail.

•	POINTER(key)

The value returned by POINTER(key) corresponds to a physical data record. Consequently when that record is removed by a call to DELETE() the pointer becomes invalid. Any subsequent access using the pointer fails. If you require fuzzy matching whereby the nearest record is returned, use the POSITION() function and appropriate access functions.

•	STREAM(), FLUSH()

When reading a large number of records, use STREAM() or open the file in a deny write mode e.g. OPEN(f) rather than SHARE(f). After the records have been read, call FLUSH() to allow other users access.

It is very important to use STREAM() when adding/appending/putting a large number of records. STREAM() will typically make processing about 20 times faster. For example, adding 1000 records might take nearly 2 minutes without STREAM(), but only 5 seconds with STREAM. It is not necessary to use STREAM() or FLUSH() on a logged out file (performance on logged out files is always good).


TopSpeed: Miscellaneous

•	SHARE and open access modes:

The following open access modes are supported           Share required

34 (12h) Read/Write, deny write (default for OPEN)	Yes

66 (42h) Read/Write, deny none (default for SHARE)	Yes

64 (40h) Read Only,  deny none	Yes

18 (12h) Read/Write, deny all	No

16 (10h) Read Only,  deny all	No

32 (20h) Read Only,  deny write	No

For the modes indicated, SHARE.EXE (which implements DOS record locking) must be loaded in AUTOEXEC.BAT or CONFIG.SYS. The following example loads SHARE in AUTOEXEC.BAT, providing 500 maximum file locks, and the default 2048 bytes for the storage area.

C:\DOS\SHARE.EXE /L:500

If SHARE.EXE is required but not loaded, the program generates a runtime error when OPEN or SHARE is called (deny none modes), or when an update is attempted (deny write modes).

•	Storing multiple Clarion files in a single DOS file

By using the special escape sequence \! in the NAME() attribute of a TopSpeed file declaration, you can specify that a single DOS file shall store more than one Clarion file. For example, to declare a single DOS file s&p.tps which is to contain 3 logical Clarion files, called supp, part and ship:

FILE,DRIVER(TopSpeed),PRE(Supp),CREATE,NAME(S&P\!Supp)

    ...

Part    FILE,DRIVER(TopSpeed),PRE(Part),CREATe,NAME(S&P\!Part)

    ...

Ship    FILE,DRIVER(TopSpeed),PRE(Ship),CREATE,NAME(S&P\!Ship)

    ...

The Clarion files share a single DOS file handle, opened when the first file is opened, and closed when the last file is closed. The first open mode determines the open mode for all the other files. If the first open mode is read-only, then no updates of any kind can be performed successfully (ACCDNID will be returned).

If one file in a group is logged out, then all the files in the group are effectively logged out.

If one file in a group is flushed, then all files in the group are flushed.

This feature is especially useful when there are a large number of small tables, or when the application must normally access group of related files together.

If no escape sequence is specified, then a default table name unnamed is supplied, so that the following are all equivalent

foo     FILE,DRIVER(TopSpeed)

foo     FILE,DRIVER(TopSpeed),NAME(foo)

foo     FILE,DRIVER(TopSpeed),NAME(foo\!unnamed)

A SEND() command allows the programmer to determine the names of the files within a group. Files can be renamed within a group; for example, given the above declarations the following command will rename the file called Supp to Old_Supp:

RENAME(Supp,S&P\!Old_Supp)

Renaming to another existing group normally involves copying/removal, so is less efficient.


Using the Send Command

Most of the driver strings can be sent to the driver by placing the SEND function in your executable code.

string = SEND(file, message)

file	Specify the label of a FILE declaration.

message	Specify the entire driver string, enclosed by single quotes.

The function always returns a string. The driver string descriptions, above, specify the situations in which the return string may be blank.

When embedding a driver string in source code, embed the SEND function at the procedure setup point in the Embedded Source dialog.