The Semware Editor Professional

4.42.00

Generated Manual

© SemWare Corporation.

See the liberal License Agreement for specifics.

This manual was generated on 7 March 2022 at 20:52:45 from TSE's interactive Help system using version 3.0.2 of the Hlp2txt macro from eCarlo.nl/tse.

The manual contains the topics from TSE's Help Index and those they refer to. Indexed topics are therefore listed and described alphabetically, with added at the bottom a few topics that are indirectly referred to. Menu-specific Help topics that are not also indexed topics are not included. The manual probably contains all topics that formerly occurred in book form in The User's Guide and The Macro Reference Guide. The generated manual's topic's contents are exactly the same as those of TSE's Help, which has not been significantly updated since TSE 4.4 (2005).

For versions after TSE Pro 4.4 you can find additional Help-type info in TSE's read.me file and in TSE Pro Undocumented Features.

This HTML manual was tested with the Windows versions of Chrome and Firefox.

Visit Semware.com and eCarlo.nl/tse for lots more TSE info, or to join the mailing lists to exchange info with TSE users worldwide.

Note: The date time below is the last time Semware updated the Help.



              The SemWare Editor HelpSystem 03 Jan 2022  7:59 am


  ┌──────────────────────┬───────────────────────────┬────────────────────┐
  │ Using HelpSemWare License AgreementMacros             │
  │ Basic Concepts       ├───────────────────────────┤   Compiled Macros  │
  │ Key AssignmentsWhat's New in Version 4.5KeyBoard Macros  │
  ├──────────────────────┼───────────────────────────┼────────────────────┤
  │ FilesBlocksSpecial Features   │
  │ MouseBookMarksASCII Chart      │
  │ WindowsClipBoardsCompiling        │
  ├──────────────────────┤ Cursor MovementCompress View    │
  │ ConfiguringDeleting/Inserting TextFunction List    │
  ├──────────────────────┤ PrintingLine Drawing     │
  │ Editing ModesSearch & ReplacePotpourri        │
  │   SyntaxHilite modeRegular ExpressionsSpell Checking   │
  │   Hex/Binary modeIncremental SearchTemplates        │
  │   AutoIndent modeSpeed Search            │                    │
  │   WordWrap modeSorting                   ├────────────────────┤
  │   Language-SpecificTabsAppendixes         │
  └──────────────────────┴───────────────────────────┴────────────────────┘





┌──────────────────────────────────────────────────────────────────────────────┐
│ A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X  Y  Z │
└──────────────────────────────────────────────────────────────────────────────┘


_MAXPATH_
   Subtopic of: Pre-Defined Constants
#define
   Subtopic of: Conditional Compilation Directives
#else
   Subtopic of: Conditional Compilation Directives
#endif
   Subtopic of: Conditional Compilation Directives
#if
   Subtopic of: Conditional Compilation Directives
#ifdef
   Subtopic of: Conditional Compilation Directives
#ifexist
   Subtopic of: Conditional Compilation Directives
#ifndef
   Subtopic of: Conditional Compilation Directives
#ifnexist
   Subtopic of: Conditional Compilation Directives

--- A ---

A Walk-Through of Window Commands
AbandonEditor()
AbandonFile()
About
Abs()
Accessing Sub-Menu Commands and Options
Accessing the Pop-Up Ascii Chart
Activating Editing Modes
   Subtopic of: Working in the Editor
Activating the Pull-Down Menu
AddAutoLoadMacro()
AddFFInfoToBuffer()
AddFileToRing()
AddHistoryStr()
Adding a Variable
   Subtopic of: Some Simple Macro Examples
Adding an External Macro to the Potpourri
   Subtopic of: Customization Using Sal Compiled Macros
Adding Files to the Ring:  Specifying and Opening Files
Adding Macros to the User-Interface (UI) Macro File
   Subtopic of: Customization Using Sal Compiled Macros
Adding More Functionality
   Subtopic of: Customization Using Sal Compiled Macros
Adding or Changing Key Assignments
   Subtopic of: Customization Using Sal Compiled Macros
Adding Your Own Commands
   Subtopic of: Customization Using Sal Compiled Macros
Additional Options Available at Startup
   Subtopic of: Starting an Editing Session
Additional Regular Expression Examples
   Subtopic of: Searching With Regular Expressions
AddLine()
Addr()
AddTrailingSlash()
AdjPtr()
Affects
   Subtopic of: Editor Variables
Alarm()
Alternate Methods for Expanding a Template
   Subtopic of: Template Mode
Alternative Modes For Viewing Files
and
   Subtopic of: Statements
Appendix A:  Technical Specifications
Appendix B:  Command Implementation
Appendix C:  Commands By Category
Appendix C:  Standard Key Assignments
Appendix D:  Variables By Category
Appendix E:  Command Implementation
Appendix F:  Standard Configuration Settings
Appendixes
Arguments - Passing and Retrieving Parameters
   Subtopic of: Macro Procedures
Arithmetic Operators
   Subtopic of: Statements
Asc()
Ask()
AskFilename()
AskNumeric()
Assigning a Macro to a Key
   Subtopic of: Some Simple Macro Examples
Assigning Macros and Commands to Keys
Associating a SyntaxHilite Mapping Set with a Group of Files
   Subtopic of: Syntaxhilite Mode
Attr
Augment Load Dir
   Subtopic of: Command-Line Options
Augmenting the Editor Load Directory
AutoIndent
Autoindent Mode
autoload file
   Subtopic of: Startup Processing

--- B ---

BackSpace()
BackupExt
BackupPath
Basic Concepts
Basic Find and Replace Options
Basic Operation of Template Mode
   Subtopic of: Template Mode
Beep
BegFile()
BegLine()
BegLineTog()
BegWindow()
BegWord()
Behavior of WrapPara within a Block
   Subtopic of: Commands to Format Text
Binary Load
   Subtopic of: Command-Line Options
Binary Mode
   Subtopic of: Alternative Modes For Viewing Files
BinaryMode()
Bitwise Logical Operators
   Subtopic of: Statements
Block Operations
Block-Marking Commands
   Subtopic of: Marking and Manipulating a Block of Text
BlockAttr
   Subtopic of: COLOR Set
BlockBegCol
BlockBegLine
BlockEndCol
BlockEndLine
BlockId
Bookmark Commands
Bookmark Shortcut
Bookmarks
Boolean Expressions
   Subtopic of: Statements
Break
break statement
   Subtopic of: Statements
BreakHookChain()
Breaking Out of Run-Away Macros
Browse Load
   Subtopic of: Command-Line Options
Browse Mode
   Subtopic of: Alternative Modes For Viewing Files
BrowseMode()
BufferFlags
Buffering Screen Output
   Subtopic of: Video Output Commands
Buffers
BufferType()
BufferVideo()
BuildPickBufferEx()
by
   Subtopic of: Statements

--- C ---

C Mode
   Subtopic of: Special Programming-Language Modes
Capture()
CaptureId
case
   Subtopic of: Statements
CenterFinds
ChainCmd()
ChangeCurrFilename()
ChangedFilesExist()
ChangeShellPrompt
Changing Position by Multiple Characters or Lines
   Subtopic of: Changing Position in a File
Changing Position by One Character or Line
   Subtopic of: Changing Position in a File
Changing Position in a File
Changing Settings for Editing Options Using IConfig
   Subtopic of: Simple Customization from Within the Editor
Changing the Case of Characters in a Block
   Subtopic of: Marking and Manipulating a Block of Text
Changing the HelpLines
   Subtopic of: Customization Using Sal Compiled Macros
Changing Window Size and Orientation
ChDir()
CheckDefaultExt()
Checking Your Spelling
ChooseFont()
Chr()
ChrSet()
ClearBit()
ClearBufferDaTmAttr()
Clearing Portions of the Screen
   Subtopic of: Video Output Commands
ClearUndoRedoList()
ClipBoardId
ClipBoards
   Subtopic of: Manipulating Blocks Via Clipboards
ClosePrint()
CloseWindow()
Closing Editing Windows
ClrEol()
ClrScr()
CmpiStr()
Color()
COLOR Set
COLOR VARIABLES
Command Prompts
Command Prompts and Keydefs
Command Prompts and Picklists
Command-Line Options
Command/Format Options
   Subtopic of: Configuration Options Available Interactively
Commands and Features That Allow Recovery of Text
Commands to Add Text
Commands to Copy Text
Commands to Delete Text
Commands to Exit from the Editor
   Subtopic of: Saving and Closing Files, and Exiting from the Editor
Commands to Format Text
Commands to Move Text
Commands to Save and/or Close Files
   Subtopic of: Saving and Closing Files, and Exiting from the Editor
Comments
Compiling Macro Source
   Subtopic of: Introduction to External Compiled Macros
Compiling Macros
Compiling Macros (Overview)
Compiling Macros from Inside the Editor
   Subtopic of: Compiling Macros (Overview)
Compiling Macros from Outside the Editor
   Subtopic of: Compiling Macros (Overview)
Compiling Programs from Within the Editor
Concatenation Operators
   Subtopic of: Statements
Conditional Compilation Directives
Conditional Execution ... if and iif
   Subtopic of: Statements
Config
   Subtopic of: External Macros Vs. the User-Interface Macro
Configuration Options Available Interactively
Configure SyntaxHilite Mapping Sets
   Subtopic of: Configuration Options Available Interactively
Configuring the Editor Interactively
constant
   Subtopic of: Constants
Constant Expressions
   Subtopic of: Statements
Constants
Context-Sensitive Help
   Subtopic of: The Helpsystem
Control Statements
   Subtopic of: Statements
Copy()
CopyAppend()
CopyAppendToWinClip()
CopyBlock()
CopyFile()
CopyToWinClip()
CreateBuffer()
CreateTempBuffer()
Creating a Custom User-Interface (UI) Macro File
   Subtopic of: Customization Using Sal Compiled Macros
Creating a Menu
   Subtopic of: Some Simple Macro Examples
Creating a TSEStart Macro File
   Subtopic of: Customization Using Sal Compiled Macros
Creating an External Compiled Macro
   Subtopic of: Customization Using Sal Compiled Macros
Creating and Using Compiled Macros
   Subtopic of: Introduction to External Compiled Macros
Creating and Using Macros
Creating Buffers
   Subtopic of: Buffers
Creating Keyboard Macros
   Subtopic of: Simple Customization from Within the Editor
Creating Macros
Creating Macros (Overview)
Creating Templates/Abbreviations
   Subtopic of: Simple Customization from Within the Editor
Creating View Port Windows
   Subtopic of: Video Output Commands
Creating Your Own Template
   Subtopic of: Template Mode
CReturn()
CurrChar()
CurrCol()
CurrDir()
CurrExt()
CurrFilename()
CurrHistoryList
CurrLine()
CurrLineLen()
CurrMacroFilename()
CurrPos()
CurrRow()
CurrVideoMode
CurrWinBorderAttr
   Subtopic of: COLOR Set
CurrWinBorderType
CurrXoffset()
Cursor
CursorAttr
   Subtopic of: COLOR Set
CursorInBlockAttr
   Subtopic of: COLOR Set
CursorTabWidth
Customization Using Sal Compiled Macros
Customizing the Editor
Cut()
CutAppend()
CutAppendToWinClip()
CutToWinClip()

--- D ---

Datadef
DateFormat
DateSeparator
Debugging Compiled Macros
   Subtopic of: Introduction to External Compiled Macros
Debugging Macros
Declaring Global Integers
   Subtopic of: Variables
Declaring Global Strings
   Subtopic of: Variables
Declaring Local Integers
   Subtopic of: Variables
Declaring Local Strings
   Subtopic of: Variables
Default
   Subtopic of: Editor Variables
DefaultExt
Defining a Menubar
   Subtopic of: Menus
Defining a Pull-Down or Pop-Up Menu
   Subtopic of: Menus
DelAllBookMarks()
DelAnyChar()
DelAnyCharOrBlock()
DelAutoLoadMacro()
Delay()
DelBlock()
DelBookMark()
DelBufferVar()
DelChar()
DelCharOrBlock()
Deleting an Existing Template
   Subtopic of: Template Mode
DelGlobalVar()
DelHistory()
DelHistoryStr()
DelLeftWord()
DelLine()
DelRightWord()
DelStr()
DelToEol()
DelWindow()
DetabOnLoad
Directive tokens
   Subtopic of: Syntaxhilite Mode
Directive1Attr
   Subtopic of: COLOR Set
Directive2Attr
   Subtopic of: COLOR Set
Directive3Attr
   Subtopic of: COLOR Set
Disable()
Display/Color Options
   Subtopic of: Configuration Options Available Interactively
DisplayBoxed
DisplayMode()
DistanceToTab()
DLL Parameters and Return Values
   Subtopic of: Macro Procedures
do
   Subtopic of: Statements
Dos()
DosCmdLine
DosIOResult()
Down()
downto
   Subtopic of: Statements
DrawBox()
Drawing Lines in the Text
DupLine()

--- E ---

EditAutoLoadList()
EditBuffer()
EditFile()
Editing Modes
Editing Multiple Files and Displaying Multiple Windows
   Subtopic of: Working in the Editor
Editor Commands
Editor Files and Directories
Editor Startup Processing
Editor Variables
EDITOR_VERSION
   Subtopic of: Pre-Defined Constants
EditThisFile()
Effects of Expandtabs
Element Classes Recognized by SyntaxHilite Mode
   Subtopic of: Syntaxhilite Mode
else
   Subtopic of: Statements
elseif
   Subtopic of: Statements
EmptyBuffer()
EmptyWinClip()
Enable()
end
   Subtopic of: Macro Procedures
endcase
   Subtopic of: Statements
EndConfig
   Subtopic of: External Macros Vs. the User-Interface Macro
enddo
   Subtopic of: Statements
EndFile()
endfor
   Subtopic of: Statements
endif
   Subtopic of: Statements
EndLine()
EndLineTog()
endloop
   Subtopic of: Statements
EndProcess()
endwhile
   Subtopic of: Statements
EndWindow()
EndWord()
EntabCurrLine()
EntabOnSave
EOFMarkerAttr
   Subtopic of: COLOR Set
EOFType
EOLType
EquateEnhancedKbd
EquiStr()
EraseDiskFile()
Escape()
Event Macros
Event Macros Defined by the User
   Subtopic of: Event Macros
Event Macros with Predefined Names
   Subtopic of: Event Macros
Examples
   Subtopic of: Editor Commands
ExecHook()
ExecLoadedMacro()
ExecMacro()
ExecScrapMacro()
Execute Macro
   Subtopic of: Command-Line Options
Executing Commands
   Subtopic of: Working in the Editor
Executing External Commands from Within the Editor
Executing Macros (Overview)
Executing Supplemental Macros from the Potpourri
ExistBufferVar()
ExistGlobalVar()
Exit()
Exiting from the Menu System
ExpandPath()
ExpandTabs
ExpandTabsToSpaces()
Expressions
   Subtopic of: Statements
Expressions in Control Statements
   Subtopic of: Statements
Extending a Block
   Subtopic of: Marking and Manipulating a Block of Text
External Macro Files
   Subtopic of: External Macros Vs. the User-Interface Macro
External Macros Vs. the User-Interface Macro

--- F ---

FALSE
   Subtopic of: Pre-Defined Constants
fClose()
fCreate()
fDup()
fDup2()
FFAttribute()
FFDate()
FFDateStr()
FFName()
FFSize()
FFTime()
FFTimeStr()
File PickList Settings
   Subtopic of: Configuration Options Available Interactively
FileChanged()
FileExists()
FileLocking
Files Needed By Iconfig
Files Needed By Spellcheck
Files Needed by the HelpSystem
   Subtopic of: The Helpsystem
FillBlock()
Find()
FindFileClose()
FindFirstFile()
FindHistoryStr()
FindNextFile()
FindOptions
FindThisFile()
Flip()
Flow of Control
   Subtopic of: Some Simple Macro Examples
FlushProfile()
FontFlags
FontName
FontSize
fOpen()
for
   Subtopic of: Statements
Format()
Formatting Print Output
forward
   Subtopic of: Macro Procedures
Forward Procedures
   Subtopic of: Macro Procedures
fRead()
fReadFile()
fSeek()
Full Configuration
   Subtopic of: Methods For Interactively Configuring the Editor
FullWindow()
Fully Customizing the Editor
Function Call Statements
   Subtopic of: Statements
fWrite()
fWriteFile()

--- G ---

General Use of the Mouse
GetBit()
GetBookMarkInfo()
GetBufferDaTmAttr()
GetBufferId()
GetBufferInt()
GetBufferStr()
GetCharWidthHeight()
GetClipBoardBlockType()
GetClockTicks()
GetColorTableValue()
GetDate()
GetDateStr()
GetDir()
GetDrive()
GetEnvStr()
GetFileToken()
GetFont()
GetFoundText()
GetFreeHistory()
GetGlobalInt()
GetGlobalStr()
GetHistoryStr()
GetHookState()
GetKey()
GetKeyFlags()
GetMarkedText()
GetMaxRowsCols()
GetNextProfileItem()
GetNextProfileSectionName()
GetPositionInfo()
GetProfileInt()
GetProfileStr()
GetStr()
GetStrAttr()
GetStrAttrXY()
GetStrFromWinClip()
GetStrXY()
GetSynFilename()
GetSynLanguageType()
GetSynMultiLnDlmt()
GetSynToEOL()
GetText()
GetTime()
GetTimeStr()
Getting Help
   Subtopic of: Working in the Editor
Getting Help in the Editor
Getting User Input
GetToken()
GetWheelScrollLines()
GetWindowTitle()
GetWinHandle()
GetWord()
Global vs. Local Variables
   Subtopic of: Macro Procedures
GlobalUnDelete()
Go To Line/Column Number
   Subtopic of: Command-Line Options
goto
   Subtopic of: Statements
GotoBlockBegin()
GotoBlockBeginCol()
GotoBlockEnd()
GotoBlockEndCol()
GotoBufferId()
GotoColumn()
GotoLine()
GotoMark()
GotoMouseCursor()
GotoPos()
GotoRow()
GotoWindow()
GotoXoffset()
GotoXY()
GUIStartupFlags

--- H ---

halt
   Subtopic of: Statements
Help()
HelpBoldAttr
   Subtopic of: COLOR Set
Helpdef
HelpInfoAttr
   Subtopic of: COLOR Set
HelpItalicsAttr
   Subtopic of: COLOR Set
HelpLine bars
   Subtopic of: The Customizable Helpline
HelpLineDelay
Helplines
HelpLinkAttr
   Subtopic of: COLOR Set
HelpSelectAttr
   Subtopic of: COLOR Set
HelpSystem Color Variables
   Subtopic of: COLOR Set
HelpTextAttr
   Subtopic of: COLOR Set
Hex Load
   Subtopic of: Command-Line Options
Hex Mode
   Subtopic of: Alternative Modes For Viewing Files
HexEdit()
HiByte()
HideMouse()
HiLiteAttr
   Subtopic of: COLOR Set
HiLiteFoundText()
History Buffer for Prompt Boxes
   Subtopic of: Command Prompts
HiWord()
Hook()
HWindow()

--- I ---

Identifiers
IdleTime
if
   Subtopic of: Statements
iif
   Subtopic of: Statements
in
   Subtopic of: Statements
include
   Subtopic of: Include Files
Include Files
IncompleteQuoteAttr
   Subtopic of: COLOR Set
Incrementalsearch Feature
Indexing Operators
   Subtopic of: Statements
Info->BOOLEAN
Info->Console
Info->CONSTANT STRING
Info->GUI
Info->initialization file
Info->INTEGER
Info->KEYDEF
Info->MAXINT
Info->MAXLINELEN
Info->MAXSTRINGLEN
Info->MENU
Info->MENUBAR
Info->MININT
Info->PROCEDURE
Info->StartMenuExit
Info->StartMenuFileManager
Info->StartMenuListRecent
Info->StartMenuNewFile
Info->StartMenuOpen
Info->StartMenuPickFile
Info->StartMenuRestoreState
Info->StartMenuWhere
Info->STRING
Info->VAR INTEGER
Info->VAR STRING
InitSynhiCurrFile()
Insert
Insert Mode
InsertCursorSize
InsertData()
InsertFile()
Inserting the Date and Time Into the Text
InsertLine()
InsertLineBlocksAbove
InsertText()
InsStr()
Installation of the Semware Editor Professional
Installation Steps
Installing a User-Interface (UI) Macro File
   Subtopic of: Customization Using Sal Compiled Macros
Integer
   Subtopic of: Variables
Integer Variables
   Subtopic of: Variables
Introduction
Introduction to External Compiled Macros
is32BitApp()
isAlpha()
isAlphaNum()
isAutoLoaded()
isBlockInCurrFile()
isBlockMarked()
isBookMarkSet()
isCharDevice()
isCurrLineInBlock()
isCursorInBlock()
isDigit()
isFullScreen()
isGUI()
isHexDigit()
isKeyAssigned()
isLower()
isMacroLoaded()
isScrapMacro()
isTrailingSlash()
isTypeableKey()
isUpper()
isWhite()
isWildPath()
isWinClipAvailable()
isWord()
isZoomed()
Iterative Statements ... while, repeat, for, do, and loop
   Subtopic of: Statements

--- J ---

JoinLine()
Jump Statement ... goto
   Subtopic of: Statements

--- K ---

KbdMacroRecording
KbdMacroRunning
KbdPath
KeepUndoBeyondSave
KeepWinOnTop
Key
Key Assignments Displayed on the Menu
Keyboard Macros
Keyboard/Mouse Options
   Subtopic of: Configuration Options Available Interactively
KeyCode()
Keydef
KeyName()
KeyPressed()
Keyword tokens
   Subtopic of: Syntaxhilite Mode
Keyword Wordset
   Subtopic of: Syntaxhilite Mode
KeyWords1Attr
   Subtopic of: COLOR Set
KeyWords2Attr
   Subtopic of: COLOR Set
KeyWords3Attr
   Subtopic of: COLOR Set
KeyWords4Attr
   Subtopic of: COLOR Set
KeyWords5Attr
   Subtopic of: COLOR Set
KeyWords6Attr
   Subtopic of: COLOR Set
KeyWords7Attr
   Subtopic of: COLOR Set
KeyWords8Attr
   Subtopic of: COLOR Set
KeyWords9Attr
   Subtopic of: COLOR Set
KillBlock()
KillFile()
KillLine()
KillLocation()
KillMax
KillPosition()
KillToEol()

--- L ---

LastKey
LastMouseKey
LastMouseX
LastMouseY
lDos()
Left()
LeftMargin
LeftStr()
Length()
lFind()
Limits
   Subtopic of: Editor Variables
LineDraw()
LineDrawChar
LineDrawing
LineDrawType
LineNumbersAttr
   Subtopic of: COLOR Set
LineTypeMenu()
LinkSynFile()
List()
ListFooter()
ListHeader()
Listing All Occurrences of a Specified Text String
Literal()
lList()
Load All
   Subtopic of: Command-Line Options
load directory
   Subtopic of: Augmenting the Editor Load Directory
Load Keyboard Macro
   Subtopic of: Command-Line Options
Load Macro
   Subtopic of: Command-Line Options
LoadBuffer()
LoadDir()
LoadHistory()
Loading and Executing Compiled Macros
   Subtopic of: Introduction to External Compiled Macros
Loading Keyboard Macros Saved in a Previous Session
   Subtopic of: Keyboard Macros
Loading, Processing, and Saving Files
Loading/Executing Macros
LoadKeyMacro()
LoadMacro()
LoadProfileSection()
LoadProfileSectionNames()
LoadStartupMacros()
LoadSynhiAssoc()
LoadWildFromDOS
LoadWildFromInside
LoByte()
LockCurrentFile()
Locking Files
LogDrive()
Logical Operators
   Subtopic of: Statements
LongestLineInBuffer()
loop
   Subtopic of: Statements
Lower()
LoWord()
lRead()
lReadNumeric()
lRepeatFind()
lReplace()
lShowEntryScreen()
LTrim()
lVersion()

--- M ---

macro file search order
   Subtopic of: Introduction to External Compiled Macros
Macro File Search Order and the Tsepath Variable
Macro Language Syntax
Macro Procedures
Macro Source Files Vs. Macro Object Files
Macro Syntax
MacroCmdLine
Macros
MacroStackAvail()
Main
   Subtopic of: Macro Procedures
Main macro
   Subtopic of: Event Macros
Maintaining a Macro Autoload File
   Subtopic of: Customization Using Sal Compiled Macros
MakeBackups
MakeTempName()
Making Changes to the Pull-Down Menu
   Subtopic of: Customization Using Sal Compiled Macros
Managing Multiple Files and Maintaining the File Ring
Manipulating Blocks Via Clipboards
Manipulating Text
Manipulating Text in a Block
   Subtopic of: Marking and Manipulating a Block of Text
Manipulating Text in Buffers
   Subtopic of: Buffers
Manipulating the Video Output Position and the Visible Cursor
   Subtopic of: Video Output Commands
Mapping SyntaxHilite Tokens to Colors & Setting Other Options
   Subtopic of: Syntaxhilite Mode
Mark()
MarkAll()
MarkBlockBegin()
MarkBlockEnd()
MarkChar()
MarkColumn()
MarkFoundText()
Marking
Marking a Block
Marking and Manipulating a Block of Text
MarkLine()
MarkStream()
MarkToEOL()
MarkWord()
MatchFilename()
Max()
MaxHistoryPerList
MaxHistorySize
Maximum closure
   Subtopic of: Searching With Regular Expressions
MAXINT
   Subtopic of: Pre-Defined Constants
MAXLINELEN
   Subtopic of: Pre-Defined Constants
MaxRecentFiles
MAXSTRINGLEN
   Subtopic of: Pre-Defined Constants
Mega-Conditional Statement ... case
   Subtopic of: Statements
menu
   Subtopic of: Menus
Menu/HelpLine Color Variables
   Subtopic of: COLOR Set
menubar
   Subtopic of: Menus
MenuBorderAttr
   Subtopic of: COLOR Set
MenuGrayAttr
   Subtopic of: COLOR Set
MenuKey()
MenuOption()
Menus
MenuSelectAttr
   Subtopic of: COLOR Set
MenuSelectGrayAttr
   Subtopic of: COLOR Set
MenuSelectLtrAttr
   Subtopic of: COLOR Set
MenuStr()
MenuTextAttr
   Subtopic of: COLOR Set
MenuTextLtrAttr
   Subtopic of: COLOR Set
Message()
Methods For Interactively Configuring the Editor
Min()
Minimum closure
   Subtopic of: Searching With Regular Expressions
Minimum/Maximum Closure
   Subtopic of: Searching With Regular Expressions
MININT
   Subtopic of: Pre-Defined Constants
Miscellaneous Questions
MkDir()
mod
   Subtopic of: Statements
Modifying the Key-Assignment Help Screen
   Subtopic of: Customization Using Sal Compiled Macros
Mouse Equipment
Mouse Symbols and Scrollbars
MouseBlockType
MouseEnabled
MouseHoldTime
MouseHotSpot()
MouseKey
MouseKeyHeld()
MouseMarking()
MouseRepeatDelay
MouseStatus()
MouseWindowId()
MouseX
MouseY
Mousing around the Editor
MoveBlock()
MoveFile()
Moving Around a File
   Subtopic of: Working in the Editor
Moving Between Files in the Ring
Moving Through Text in a File
Moving to the Beginning or End of a Block
   Subtopic of: Marking and Manipulating a Block of Text
MsgAttr
   Subtopic of: COLOR Set
MsgBox()
MsgBoxBuff()
MsgBoxEx()
MsgLevel
Multi-line delimiter tokens
   Subtopic of: Syntaxhilite Mode
MultiLnDlmt1Attr
   Subtopic of: COLOR Set
MultiLnDlmt2Attr
   Subtopic of: COLOR Set
MultiLnDlmt3Attr
   Subtopic of: COLOR Set

--- N ---

Named ClipBoards
   Subtopic of: Manipulating Blocks Via Clipboards
Navigating through the HelpSystem
   Subtopic of: The Helpsystem
NewFile()
NextChar()
NextFile()
NextWindow()
NoOp()
not
   Subtopic of: Statements
Number tokens
   Subtopic of: Syntaxhilite Mode
NumberAttr
   Subtopic of: COLOR Set
Numbers
Numeric Expressions
   Subtopic of: Statements
NumFiles()
NumFileTokens()
NumHistoryItems()
NumLines()
NumTokens()
NumWindows()

--- O ---

Obtaining a File PickList within a Prompt Box
   Subtopic of: Command Prompts
Obtaining HelpSystem Information
   Subtopic of: The Helpsystem
Obtaining Useful Information Within a Macro
   Subtopic of: Some Simple Macro Examples
OFF
   Subtopic of: Pre-Defined Constants
Ofs()
ON
   Subtopic of: Pre-Defined Constants
OneWindow()
Opening and Closing a Block
   Subtopic of: Marking and Manipulating a Block of Text
Opening Windows
Optional Parameters
   Subtopic of: Editor Commands
or
   Subtopic of: Statements
Other Color Variables
   Subtopic of: COLOR Set
Other Special-Purpose Search Features
Other SyntaxHilite Options
   Subtopic of: Syntaxhilite Mode
OtherWinBorderAttr
   Subtopic of: COLOR Set
OtherWinBorderType
otherwise
   Subtopic of: Statements
Overview of the Editor
Overview of the Macro Programming Language
OverwriteCursorSize

--- P ---

PageDown()
PageUp()
ParaEndStyle
Passing and Retrieving Parameters by Reference
   Subtopic of: Macro Procedures
Passing and Retrieving Parameters by Value
   Subtopic of: Macro Procedures
Paste()
PasteFromWinClip()
PasteReplace()
PasteReplaceFromWinClip()
PasteUnDelete()
PBAttribute()
PBDate()
PBDateStr()
PBName()
PBSize()
PBTime()
PBTimeStr()
PeekByte()
PeekLong()
PeekWord()
Performing Editing Tasks
   Subtopic of: Working in the Editor
Performing Other File-Processing Operations
PersistentHistory
PersistentRecentFiles
Pick from List
   Subtopic of: Command-Line Options
PickDrive()
PickFile()
PickFileChangesDir
PickFileFlags
PickFileSortOrder
PlaceMark()
PokeByte()
PokeLong()
PokeWord()
PopBlock()
PopLocation()
PopPosition()
PopWinClose()
PopWinCols
PopWinOpen()
PopWinRows
PopWinX1
PopWinY1
Pos()
PosFirstNonWhite()
Positioning the Cursor and Scrolling Text
PosLastNonWhite()
Potpourri
   Subtopic of: Executing Supplemental Macros from the Potpourri
Pre-Defined Constants
Precedence and Order of Evaluation in Expressions
   Subtopic of: Statements
PressKey()
PrevChar()
PrevFile()
PrevHelp()
PrevPosition()
PrevWindow()
Print Output Options
   Subtopic of: Configuration Options Available Interactively
PrintBlock()
PrintBotMargin
PrintChar()
PrintCopies
PrinterFontFlags
PrinterFontName
PrinterFontSize
PrintFile()
PrintFirstPage
PrintFooter
PrintHeader
Printing from the Editor
PrintLastPage
PrintLeftMargin
PrintLineNumbers
PrintLineSpacing
PrintLinesPerPage
PrintPause
PrintRightMargin
PrintTopMargin
PrintUseScreenFont
Private macros
   Subtopic of: External Macros Vs. the User-Interface Macro
proc
   Subtopic of: Macro Procedures
Process()
Process() and Keydefs
ProcessHotSpot()
Prompt Box
   Subtopic of: Command Prompts
Prompting the User
   Subtopic of: Some Simple Macro Examples
PromptKeys
   Subtopic of: Command Prompts and Keydefs
ProtectedSaves
Ptr()
Public
   Subtopic of: Macro Procedures
Public macros
   Subtopic of: External Macros Vs. the User-Interface Macro
Pull-Down Menu Categories
PurgeKeyMacro()
PurgeMacro()
PurgeSynhi()
Purging Compiled Macros
   Subtopic of: Introduction to External Compiled Macros
Purging Keyboard Macros from the Current Session
   Subtopic of: Keyboard Macros
Purging Macros
PushBlock()
PushKey()
PushKeyStr()
PushLocation()
PushPosition()
PutAttr()
PutAttrXY()
PutChar()
PutCharH()
PutCharHXY()
PutCharV()
PutCharXY()
PutCtrStr()
PutHelpLine()
PutLine()
PutLineXY()
PutNCharAttr()
PutOemStrXY()
PutStr()
PutStrAttr()
PutStrAttrXY()
PutStrEOL()
PutStrEOLXY()
PutStrXY()

--- Q ---

Query()
QueryEditState()
QuickHelp()
QuitFile()
QuitToPrompt
Quote delimiter tokens
   Subtopic of: Syntaxhilite Mode
Quote1Attr
   Subtopic of: COLOR Set
Quote2Attr
   Subtopic of: COLOR Set
Quote3Attr
   Subtopic of: COLOR Set
QuotePath()

--- R ---

Re-Playing Keyboard Macros
   Subtopic of: Keyboard Macros
Read()
Reading from the Screen
   Subtopic of: Video Output Commands
ReadNumeric()
Recording Keyboard Macros
   Subtopic of: Keyboard Macros
RecordKeyMacro()
Redo()
RedoCount()
Referencing and Switching to Buffers
   Subtopic of: Buffers
Referencing Global Integers
   Subtopic of: Variables
Referencing Global Strings
   Subtopic of: Variables
Referencing Local Integers
   Subtopic of: Variables
Referencing Local Strings
   Subtopic of: Variables
Regular Expression Operators
   Subtopic of: Searching With Regular Expressions
Relational Operators for Numeric Expressions
   Subtopic of: Statements
Relational Operators for String Expressions
   Subtopic of: Statements
RemoveProfileItem()
RemoveProfileSection()
RemoveTrailingSlash()
RemoveTrailingWhite
RemoveUnloadedFiles()
RenameAndSaveFile()
RenameDiskFile()
repeat
   Subtopic of: Statements
RepeatCmd()
RepeatFind()
Repeating a Character, Command, Or Macro
Replace()
ReplaceFile()
ReplaceOptions
ReplaceSynFile()
Reserved Words
ResizeFont()
ResizeWindow()
Restore State
   Subtopic of: Command-Line Options
RestoreCursorLine()
Restoring the Current Line
   Subtopic of: Commands and Features That Allow Recovery of Text
Retrieving Text from Buffers
   Subtopic of: Buffers
return
   Subtopic of: Statements
Return Values
   Subtopic of: Editor Commands
ReturnEqNextLine
Returning Values
   Subtopic of: Macro Procedures
Right()
RightMargin
RightStr()
RmDir()
RollDown()
RollLeft()
RollRight()
RollUp()
RPos()
RTrim()
Running Spellcheck

--- S ---

SaveAllAndExit()
SaveAllFiles()
SaveAndQuitFile()
SaveAs()
SaveBlock()
SaveFile()
SaveHistory()
SaveKeyMacro()
SaveSettings()
SaveState
Saving and Closing Files, and Exiting from the Editor
Saving and Restoring State Information
Saving Configuration Settings
Saving Files and Exiting from the Editor
Saving Keyboard Macros for Use in a Later Session
   Subtopic of: Keyboard Macros
Saving Print Options For Future Sessions
Saving/Restoring Entries in the History Buffer
   Subtopic of: Saving/Restoring the Current Editing Session
Saving/Restoring Entries in the Recent Files List
   Subtopic of: Saving/Restoring the Current Editing Session
Saving/Restoring the Current Editing Session
Saving/Restoring the Editing Environment
   Subtopic of: Saving/Restoring the Current Editing Session
Scope
   Subtopic of: Macro Procedures
ScreenCols
ScreenRows
ScrollDown()
Scrolling Forward or Backward in a File
   Subtopic of: Scrolling Text
Scrolling Text
Scrolling the Current Line
   Subtopic of: Scrolling Text
ScrollLeft()
ScrollRight()
ScrollToBottom()
ScrollToCenter()
ScrollToRow()
ScrollToTop()
ScrollUp()
Search Features:  Finding and Replacing Text
Search SubDirs
   Subtopic of: Command-Line Options
SearchHelp()
Searching
Searching With Regular Expressions
SearchPath()
Seg()
Selecting Colors for SyntaxHilite Classes
   Subtopic of: Syntaxhilite Mode
Selecting Files to Edit
Selecting the Tab Type
Selecting the Video Mode
Selection Menu
   Subtopic of: Command Prompts
SelfInsert()
Sending Output and Commands to the Printer
Session-Global Variables
Set()
Set Colors
   Subtopic of: Configuration Options Available Interactively
SetBit()
SetBufferInt()
SetBufferStr()
SetColorTableValue()
SetCursorOff()
SetCursorOn()
SetFileAttr()
SetFont()
SetGlobalInt()
SetGlobalStr()
SetHookState()
SetMenuBar()
SetPrinterFont()
Setting Print Options
Setting Tab Stops
Setting the Option to Display SyntaxHilite Colors
   Subtopic of: Syntaxhilite Mode
SetUndoOff()
SetUndoOn()
SetVideoRowsCols()
SetWindowHeight()
SetWindowTitle()
SetWindowWidth()
Shell()
ShiftText()
shl
   Subtopic of: Statements
ShowEntryScreen()
ShowEOFMarker
ShowHelpLine
ShowLineNumbers
ShowMainMenu
ShowMouse()
ShowStatusLine
ShowSyntaxHilite
shr
   Subtopic of: Statements
SignOn()
Simple Customization from Within the Editor
Single Instance of the Editor Off
   Subtopic of: Command-Line Options
Single Instance of the Editor On
   Subtopic of: Command-Line Options
Single-line delimiter tokens
   Subtopic of: Syntaxhilite Mode
SingleInstance
SingleLnDlmt1Attr
   Subtopic of: COLOR Set
SingleLnDlmt2Attr
   Subtopic of: COLOR Set
SingleLnDlmt3Attr
   Subtopic of: COLOR Set
SizeOf()
Smart Tabs
   Subtopic of: Setting Tab Stops
SmartIndent Mode
   Subtopic of: Special Programming-Language Modes
Soft and Hard Tabs
   Subtopic of: Setting Tab Stops
Some Simple Macro Examples
Sort()
Sorting Lines of Text
Sound()
Special Commands and Features
Special Handling For Certain Types of Text
Special Programming-Language Modes
SpecialEffects
Speedsearch Feature
SplitLine()
SplitPath()
Splitting the Screen Into Windows
SqueezePath()
StartedFromDosPrompt()
Starting an Editing Session
Starting Simple
   Subtopic of: Customization Using Sal Compiled Macros
Starting the Editor
Starting the Editor from the Command Line
Starting the Editor from the Desktop
Starting the Editor With No Command-Line Parameters
StartPgm()
Startup Processing
StartupFlags
StartupVideoMode
Statements
StatusLine Prompt
   Subtopic of: Command Prompts
StatusLineAtTop
StatusLineAttr
   Subtopic of: COLOR Set
StatusLineFillChar
StatusLineRow
StatusLineUpdating
Storing Text in Buffers
   Subtopic of: Buffers
Str()
StrCount()
StrFind()
String
   Subtopic of: Variables
String Expressions
   Subtopic of: Statements
String Length
   Subtopic of: Editor Commands
String Slices
   Subtopic of: Statements
String Variables
   Subtopic of: Variables
Strings
StrReplace()
Sub-Menu Items that Change an Editing Option
   Subtopic of: Accessing Sub-Menu Commands and Options
Sub-Menu Items that Execute a Command
   Subtopic of: Accessing Sub-Menu Commands and Options
SubStr()
Summary List of Regular Expression Operators
   Subtopic of: Searching With Regular Expressions
Summary of Mouse Operations
Summary of New/Enhanced Features in the Semware Editor Professional V4.0
Summary of New/Enhanced Features in the Semware Editor Professional V4.2
Summary of New/Enhanced Features in the Semware Editor Professional V4.4
Summary of New/Enhanced Features in the Semware Editor Professional V4.5
Summary of New/Enhanced Features in the Semware Editor Professional/32 V2.6
Summary of New/Enhanced Features in the Semware Editor Professional/32 V2.8
Summary of New/Enhanced Features in the Semware Editor Professional/32 V3.0
SwapLines()
SwapPosition()
Switching Between Windows
Synchronized Scrolling in Windows
Syntax
   Subtopic of: Editor Commands
SyntaxHilite Color Variables
   Subtopic of: COLOR Set
Syntaxhilite Mode
System ClipBoard
   Subtopic of: Manipulating Blocks Via Clipboards
System/File Options
   Subtopic of: Configuration Options Available Interactively

--- T ---

Tab/Margin Options
   Subtopic of: Configuration Options Available Interactively
Table Of Contents
TabLeft()
TabRight()
TabSet()
TabShiftsBlock
TabType
TabWidth
Template Mode
TemplateExpansion
TerminateEvent()
Terminating the Editor
Termination Statements ... break, return, and halt
   Subtopic of: Statements
Text Color Variables
   Subtopic of: COLOR Set
Text Entry/Block Options
   Subtopic of: Configuration Options Available Interactively
TextAttr
   Subtopic of: COLOR Set
The AutoLoadList Command
   Subtopic of: Introduction to External Compiled Macros
The ClipBoard Copy Commands
   Subtopic of: Manipulating Blocks Via Clipboards
The ClipBoard CopyAppend Commands
   Subtopic of: Manipulating Blocks Via Clipboards
The ClipBoard Cut Commands
   Subtopic of: Manipulating Blocks Via Clipboards
The ClipBoard CutAppend Commands
   Subtopic of: Manipulating Blocks Via Clipboards
The ClipBoard Empty Command
   Subtopic of: Manipulating Blocks Via Clipboards
The ClipBoard Paste Commands
   Subtopic of: Manipulating Blocks Via Clipboards
The ClipBoard PasteOver Commands
   Subtopic of: Manipulating Blocks Via Clipboards
The Customizable Helpline
The Deletion Buffer:  A Safety Net
   Subtopic of: Commands and Features That Allow Recovery of Text
The Editor Design
The Editor Features
The Editor Manuals
The Effective Left Margin
   Subtopic of: Autoindent Mode
The End-of-File Marker
The ExecMacro Command
   Subtopic of: Introduction to External Compiled Macros
The Helpline
The Helpsystem
The LoadMacro Command
   Subtopic of: Introduction to External Compiled Macros
The Macro Reference Guide
   Subtopic of: The Editor Manuals
The Microsoft Windows Clipboard Commands
   Subtopic of: Manipulating Blocks Via Clipboards
The Pull-Down Menu System
The Screen Layout
The Screen Layout With Multiple Windows
The Statusline
The TSELOAD.DAT File
   Subtopic of: Startup Processing
The TSEStart Macro
   Subtopic of: Startup Processing
The User's Guide
   Subtopic of: The Editor Manuals
The User-Defined Word List
The User-Interface Macro File (TSE.UI)
   Subtopic of: External Macros Vs. the User-Interface Macro
TimeFormat
times
   Subtopic of: Statements
TimeSeparator
to
   Subtopic of: Statements
To-EOL delimiter tokens
   Subtopic of: Syntaxhilite Mode
ToEOL1Attr
   Subtopic of: COLOR Set
ToEOL2Attr
   Subtopic of: COLOR Set
ToEOL3Attr
   Subtopic of: COLOR Set
Toggle()
ToggleInsert()
TrackMouseCursor()
Transparency
Trim()
TRUE
   Subtopic of: Pre-Defined Constants
TSELOAD.DAT
   Subtopic of: Startup Processing
TSELOADDIR
   Subtopic of: Augmenting the Editor Load Directory
TSEPath
TSEStart Macro
   Subtopic of: Startup Processing
TSESTART.MAC
   Subtopic of: Startup Processing
Type Conversions within Expressions
   Subtopic of: Statements

--- U ---

UnBufferVideo()
UnDelete()
Understanding User-Interface (UI) Macro Files
   Subtopic of: Customization Using Sal Compiled Macros
Undo()
UndoCount()
UndoMode()
UnHook()
UnLockCurrentFile()
UnMarkAfterPaste
UnMarkBlock()
Unmarking a Block
   Subtopic of: Marking and Manipulating a Block of Text
until
   Subtopic of: Statements
Up()
UpdateBufferDaTmAttr()
UpdateDisplay()
UpdateDisplayFlags()
Upper()
UseCommonDialogs
UseCurrLineIfNoBlock
Using a Mouse
   Subtopic of: Working in the Editor
Using Bookmarks
Using Command Lines in Macros
Using DLLs
   Subtopic of: Macro Procedures
Using Keyboard Macros
   Subtopic of: Working in the Editor
Using Macro Language Features
Using Macros
Using Physical Tabs:  Hard
Using Picklists
Using Positional Tabs:  Soft, Variable, and Smart
Using Tabs
Using the Pop-Up Mouse Menu
Using the Pull-Down Menu System
Using Undo/Redo
   Subtopic of: Commands and Features That Allow Recovery of Text

--- V ---

Val()
Values
   Subtopic of: Editor Variables
var
   Subtopic of: Macro Procedures
Variable Assignment Statements
   Subtopic of: Statements
Variable Tabs
   Subtopic of: Setting Tab Stops
Variables
VarTabs
Version()
VersionStr()
VGotoXY()
VGotoXYAbs()
VHomeCursor()
Video Output Commands
ViewFinds()
ViewFindsId
VWhereX()
VWhereY()
VWindow()

--- W ---

WaitForKeyPressed()
WaitForMouseEvent()
Warn()
What Happens when a File Is Saved
   Subtopic of: Saving and Closing Files, and Exiting from the Editor
when
   Subtopic of: Statements
WhenLoaded macro
   Subtopic of: Event Macros
WhenPurged macro
   Subtopic of: Event Macros
WhereX()
WhereXAbs()
WhereY()
WhereYAbs()
WhichOS()
while
   Subtopic of: Statements
White Characters
WIN32
   Subtopic of: Pre-Defined Constants
Window()
Window Border Variables
   Subtopic of: COLOR Set
WindowCols
WindowFooter()
WindowId()
WindowRows
Windows
WindowX1
WindowY1
WordLeft()
WordRight()
WordSet
WordWrap
Wordwrap Mode
Working in the Editor
Working With Windows
WrapLine()
WrapPara()
Write()
WriteLine()
WriteProfileInt()
WriteProfileStr()
Writing Configuration Settings to a Settings File
Writing to the Screen
   Subtopic of: Video Output Commands

--- X ---

X1

--- Y ---

Y1
YesNo()

--- Z ---

ZeroBasedTab
ZoomWindow()




A Walk-Through of Window Commands

This section walks you through a simple editing session, using window commands
described above.  This guided tour will familiarize you with some of the
commands available for creating and working within windows.

To begin, load a file into the editor.

Now open a horizontal window by pressing <Ctrl O H> (or select "Horizontal"
under the Window Menu).  You now have two horizontal windows on the screen.
The bottom window is the current window and contains the cursor.  This is
window 2.  Notice the color and style of the current window divider line.

Open a vertical window in one of the horizontal windows by pressing <Ctrl O V>
(or select "Vertical" under the Window Menu).  Window 2 splits vertically into
two windows, creating a third window.  Window 3 becomes the current window.

Move between windows by pressing <Alt> and the number key that corresponds to
the window desired.  For example, press <Alt 1> to move to window 1.  Be sure
to use the number keys located above the alphabetic keys.

Next, close a window by using the CloseWindow command.  For example, press
<Alt 3> to go to window 3, and then press <Ctrl O C> (or select "Close" under
the Window Menu).  This closes window 3 and makes window 2 the current window.

Re-open window 3 by pressing <Ctrl O V> (or by selecting "Vertical" under the
Window Menu).

Resize window 3 using the ResizeWindow command.  To do this, press <Ctrl O R>
(or select "Resize" under the Window Menu) while in window 3.  The editor
prompts for the edge to be resized.  Press <CursorLeft> to select the left
window edge.  A resizing bar appears.  Press <CursorRight> and <CursorLeft> to
move the resizing bar left and right to adjust the left edge of the window.
Press <Enter> when complete, to position the left edge of the window according
to the final placement of the resizing bar.

Close a window using the DelWindow command.  For example, in window 3, press
<Ctrl O D>, then press <CursorLeft> to delete the left window.  This closes
window 2, and window 3 expands to fill the area vacated by window 2.  Windows
1 and 3 remain open on the screen.

Zoom window 1 to temporarily make that window fill the screen.  To do this,
press <Alt 1> to go to window 1, and then press <Ctrl O Z> (or select "Zoom"
under the Window Menu).  Window 1 expands to fill the screen.  Unless you are
using a mouse, the window identifier changes from 1 to Z.

To restore windows 1 and 3 to the screen, press <Ctrl O Z> again (or select
"Zoom" under the Window Menu).

Close all windows except window 1.  You can do this from window 1 by pressing
<Ctrl O O> (or select "One" under the Window Menu).  Window 3 is removed, and
window 1 expands to fill the screen.





AbandonEditor()

Terminates the editor without any prompt, discarding all unsaved changes to
files.

Syntax:     AbandonEditor([INTEGER error_level])

            • error_level is the return code passed to the calling program
              (usually the operating system).


Returns:    Nothing.

Notes:      This command exits the editor immediately, WITH NO WARNING AND NO
            REGARD FOR UNSAVED BUFFERS.  For this reason, this command is
            intended for use only in macros (as opposed to a stand-alone
            command) where this type of action might be necessary.

            To save all files before exiting, use one of the following
            commands:  SaveAllFiles(), SaveAllAndExit().

            The QuitToPrompt variable has no effect on this command.

Examples:

            The following macro is an example of an alternative to the
            editor's Exit() command.  If buffers have been changed, instead of
            prompting on each changed buffer, it gives the user the option of
            abandoning all buffers (by selecting "y"), writing all buffers (by
            selecting "w"), or by returning to the editor (by selecting "n" or
            <escape>).

            proc mEmacsExit()
                integer start_file = GetBufferId(),
                    n = NumFiles() + (BufferType() <> _NORMAL_),
                    changed = 0

                // traverse the ring of files, to see if one is modified
                while n
                    if FileChanged()
                        changed = changed + 1
                    endif
                    n = n - 1
                    NextFile(_DONT_LOAD_)
                endwhile
                // return to where we were
                GotoBufferId(start_file)
                if changed == 0
                    AbandonEditor()
                else
                    Message(changed, " buffer(s) have not been saved. " +
                            "Exit [ynw]?")

                    loop
                        case GetKey()
                            when <escape>, <n>, <shift n>
                                UpdateDisplay()
                                break               // break out of loop
                            when <y>, <shift y>
                                AbandonEditor()     // never returns
                                break
                            when <w>, <shift w>
                                SaveAllAndExit()    // never returns
                                break
                        endcase
                    endloop
                endif
            end

See Also:   SaveAllFiles(), SaveAllAndExit(), Exit()





AbandonFile()

Removes the current or specified buffer from the editor, without any prompt,
discarding all unsaved changes.

Syntax:     INTEGER AbandonFile([INTEGER buffer_id])

            • buffer_id is the id number of the buffer to be abandoned.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command discards the current or optionally-specified buffer
            immediately, with no warning and regardless of changes made to the
            buffer.  For this reason, this command is intended for use only in
            macros (as opposed to a stand-alone command) where this type of
            action might be necessary.

            If a buffer_id is specified and the buffer does not exist in the
            editor's Ring of files, zero will be returned; otherwise, non-zero
            will be returned.

            When the last edited file is abandoned from a macro, control is
            not returned to the editor until the macro finishes operation.

            If control is returned to the editor, and the total number of
            files loaded is 0 (for example, NumFiles() == 0), the editor will
            terminate.

            The QuitToPrompt variable has no effect on this command.

Examples:

            See the YesNo() command for an example.

See Also:   FileChanged(), QuitFile(), SaveAndQuitFile(), EmptyBuffer()





About

Displays information about the current version of the editor.





Abs()

Returns the unsigned value of an integer expression.

Syntax:     INTEGER Abs(INTEGER i)

            • i is the integer expression whose absolute value is to be
              returned.

Returns:    The absolute value of the passed integer expression.

Examples:

            i = Abs(-3)       // i is 3

            i = Abs(3)        // i is 3

            i = Abs(0)        // i is 0

            j = 5
            i = Abs(j - 15)   // i is 10

See Also:   Min(), Max()





Accessing Sub-Menu Commands and Options

To display a sub-menu of commands or options for a particular main Menu
category, select the desired category.  Several methods are available to
accomplish this:

    • From the main Menu, press <CursorRight> or <CursorLeft> to move the
      cursor bar directly over the desired main Menu category.  Then press
      either <Enter> or <CursorDown> to display the sub-menu for that
      category.

    • Or, from the main Menu, press the highlighted character, or "quick-key,"
      of the desired Menu category to automatically display the sub-menu for
      that category.

    • From within a sub-menu, you can move to another sub-menu without going
      back to the main Menu.  Simply press <CursorRight> or <CursorLeft> to
      move across the sub-menus until you are in the sub-menu of the desired
      category.  Or, just press <Alt> plus the quick-key of the desired main
      Menu category.

    • For the File and Text Menu categories, Menu hotkeys are available to
      directly access the sub-menus while editing.  Press <Alt F> or <Alt T>,
      respectively, to activate the pull-down Menu and display the associated
      sub-menu.

Within a sub-menu, you can select an item to execute a command or set an
option.  Just press <CursorDown> or <CursorUp> to move the cursor bar over the
desired item.  Then press <Enter> to execute or process that item.
Alternatively, you can press the quick-key (the highlighted character) for an
item to select that item and immediately execute or process it.

Certain sub-menu items may be disabled at various times.  For example, if no
block is currently marked in any file, then "Copy" under the Block menu will
not have any effect; that is, it is temporarily disabled while no block is
marked.  Such disabled items are "grayed" in the sub-menu list to indicate
that they currently have no effect.  No action will occur if a "grayed" item
is selected.

Here is an example of the Menu showing the File sub-menu.

┌───────────────────────────────────────────────────────────────────┐
│▒File▒ Block Text Search Window Clip Macro Print Util Options Help │
└┌─────────────────────────┐────────────────────────────────────────┘
 │▒New▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
 │ Open...         <Alt E> │
 │ Insert...       <Alt R> │
 │ File Manager...         │
 │ Change Dir...           │
 ├─────────────────────────┤
 │ Next            <Alt N> │
 │ Previous        <Alt P> │
 │ List Open...    <Alt 0> │
 │ List Recent... <Ctrl 0> │
 ├───── Current File ──────┤
 │ Save         <Ctrl K S> │
 │ Save As...              │
 │ Save & Close <Ctrl K X> │
 │ Close        <Ctrl K Q> │
 │ Change Name...  <Alt O> │
 │ Show File Info          │
 ├─────── All Files ───────┤
 │ Save All                │
 │ Save All & Exit         │
 │ Exit            <Alt X> │
 └─────────────────────────┘

Here is an example of the Menu showing the Options sub-menu.

┌────────────────────────────────────────────────────────────────────┐
│ File Block Text Search Window Clip Macro Print Util ▒Options▒ Help │
└──────────────────────────────────────┌────────────────────────────┐┘
                                       │▒AutoIndent▒▒▒▒▒▒▒▒[▒▒▒▒On]▒│
                                       │ WordWrap            [ Off] │
                                       │ Right Margin       [   72] │
                                       │ Left Margin        [    0] │
                                       ├────────────────────────────┤
                                       │ Tab Type        [    Soft] │
                                       │ Tab Width          [    8] │
                                       ├────────────────────────────┤
                                       │ Read Only            [Off] │
                                       │ Backups              [ On] │
                                       │ Save State on Exit [  Off] │
                                       ├────────────────────────────┤
                                       │ Full Configuration  ►      │
                                       │ Save Current Settings  ►   │
                                       └────────────────────────────┘

The sub-menus display items that either execute a command (such as "Open"
under the File Menu), or that allow you to specify or toggle an editing option
(such as "AutoIndent" under the Options Menu).  Certain sub-menu commands are
followed by "►" to indicate that the command displays a selection menu of
choices (such as "Full Configuration" under the Options Menu).  Other commands
are followed by "..." to indicate that execution of the command either
displays a prompt box or StatusLine prompt requesting additional information
needed to complete the command (such as "Open" under the File Menu); or
displays a PickList of entries that you can view and select from (such as
"List Open" under the File Menu).  (For more information on prompts, selection
menus, and PickLists, see the chapter on "Command Prompts and PickLists.")


Sub-Menu Items that Execute a Command
─────────────────────────────────────

If the item executes a command, execution begins once the item is selected.
If the editor needs additional input to continue processing a command, it
displays a prompt box, selection menu, or PickList.  Execution of the command
continues when you provide the necessary information or make the desired
selection.  You can press <Escape> within a prompt, selection menu, or
PickList to cancel the operation.  Upon completion or cancellation of the
command, the editing session resumes and the pull-down Menu system is no
longer active.

For example:

    • Selecting "Save All" under the File Menu causes the editor to
      immediately save all files in memory.  The editor then deactivates the
      pull-down Menu and resumes the editing session.

    • Selecting "Open" under the File Menu causes the EditFile command to be
      processed.  The editor first displays the following prompt box to
      request the filename(s) to be opened:

          ┌─────────────────────────────────────────────────────────┐
          │File(s) to edit: [current path]                          │
          │                                                         │
          └─────────────────────────────────────────────────────────┘

      Once you type the desired filename(s) and press <Enter>, the editor
      processes the indicated file(s).  The pull-down Menu is then
      deactivated, and the cursor is placed in the first newly-opened file,
      ready for editing to resume.

    • Selecting "List Open" under the File Menu causes a PickList to be
      displayed that provides a list of all files that are open in the current
      session.  To select a file to edit, move the cursor bar over the desired
      file and press <Enter>.  The command resumes execution based on the
      selection made.  The editor then deactivates the pull-down Menu and
      resumes the editing session.


Sub-Menu Items that Change an Editing Option
────────────────────────────────────────────

If the sub-menu item toggles or changes an editing option, that option is
followed by an indication of its current setting enclosed within [ ].  If the
option has only two states, such as ON and OFF, the state is immediately
toggled when you select that option.  If the option has more than two possible
settings, or allows a user-defined value to be specified, then when you select
that option, it activates the option and allows you to specify the appropriate
setting or value.

After you select an editing option, the sub-menu remains on the screen to
allow you to select other options or commands, or to move to another Menu
category.  To deactivate the pull-down Menu system and resume editing, press
<Escape> twice.

For example:

    • Selecting "Backups" under the Options Menu causes the editor to
      immediately toggle Backups ON (if initially set OFF).  The option
      setting displayed on the sub-menu changes to [ On].  If you select it
      again, it toggles back OFF, and [Off] displays on the sub-menu.  To
      deactivate the pull-down Menu and resume editing, press <Escape> twice.

    • Selecting "AutoIndent" under the Options Menu causes the editor to
      display the following selection menu of available AutoIndent modes:

          ┌────────┐
          │ Off    │
          │▒On▒▒▒▒▒│
          │ Sticky │
          └────────┘

      To choose a setting, move the cursor bar over the desired selection and
      press <Enter>, or simply press the highlighted quick-key for the desired
      selection.  The editor then removes the selection menu from the screen
      and changes to the indicated mode.  The newly-selected setting is
      displayed within [ ] on the sub-menu.  To deactivate the pull-down Menu
      and resume editing, press <Escape> twice.

    • Selecting "Right Margin" under the Options Menu causes the editor to
      activate the area within [ ].  To specify a value for RightMargin, type
      the desired number.  You can use editing commands such as Left, Right,
      BackSpace, DelChar, DelLine, DelToEol, CopyBlock, and Paste, within [ ]
      to input a value.  Press <Enter> to have the editor accept your new
      setting, or press <Escape> to cancel any changes made to the option.
      Then press <Escape> twice to deactivate the pull-down Menu and resume
      editing.





Accessing the Pop-Up Ascii ChartAsciiChart  (<Ctrl A>, or "ASCII Chart" under Util Menu)

  This command pops up an ASCII chart PickList on the screen.  The following
  information is included for each character in the ASCII chart:

    • the decimal representation of the character

    • the hexadecimal representation of the character

    • the display representation of the character

  When the ASCII chart is displayed, the cursor bar is located on the entry
  that corresponds to the character in the text at the cursor position.  If
  the cursor is positioned beyond the end of the line, the cursor bar is
  located on the first item in the ASCII chart (the null character).

  You can scroll through the entries in the ASCII chart the same as you would
  for any PickList.  (For more information on scrolling within a PickList, see
  "Using PickLists" in the chapter on "Command Prompts and PickLists.")

  To place a display character from the ASCII chart into the text, scroll the
  cursor bar to the desired entry and press <Enter>.  The ASCII chart is then
  removed from the screen, and the selected character is placed in the text at
  the cursor position.

  To remove the ASCII chart from the screen without placing a character into
  the text, press <Escape>.





Activating the Pull-Down Menu

While the pull-down Menu is displayed, basic cursor movements and the <Enter>
key can be used to make selections, or "quick-keys" can be pressed to provide
access to Menu options.

The main Menubar lists categories of commands and options, as illustrated
below:

┌───────────────────────────────────────────────────────────────────┐
│▒File▒ Block Text Search Window Clip Macro Print Util Options Help │
└───────────────────────────────────────────────────────────────────┘


In the standard configuration of the editor, the main Menu continually
displays at the top of the screen.  To activate the Menu, press <F10> or <Escape>.

If desired, you can configure the editor so the main Menu will be displayed
only when you activate the Menu by pressing <F10> or <Escape>.  If the
StatusLine or HelpLine is currently displayed at the top of the screen, the
main Menu will overlay it. (For more information on configuring the editor to
display the main Menu only when activated, see "Display Main Menu" under
"Display/Color Options" in the chapter on "Configuring the Editor Interactively.")





AddAutoLoadMacro()

Adds a Compiled Macro file to the list of macro files to be automatically
loaded on editor startup.

Syntax:     INTEGER AddAutoLoadMacro(STRING macro_name)

            • macro_name is the name of the macro file to load.  The name
              can either be a simple name ("mymacro") or may include the
              complete path ("c:\macros\mymacro.mac").

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      The list of macro files to be loaded is maintained in the autoload
            file TSELOAD.DAT.  This file provides a simple, optional mechanism
            for automatically loading macro files at the beginning of each
            editing session.

            If TSELOAD.DAT is used, it is maintained in the editor
            load directory.  On startup, the editor loads any macros found
            in this autoload file, using the LoadMacro() command.

See Also:   DelAutoLoadMacro(), EditAutoLoadList(), LoadMacro(),
            isAutoLoaded()

            Variables: TSEPath





AddFFInfoToBuffer()

Adds the file information gathered from the last FindFirstFile() or
FindThisFile() command to the indicated buffer.

Syntax:     INTEGER AddFFInfoToBuffer([INTEGER buffer_id [, STRING path]])

            • buffer_id is the optional buffer to which the file information
              will be added.  If not passed, the current buffer is assumed.

            • path is an optional path that will be inserted before the
              filename.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      The file information is added after the current line in buffer_id.
            The added line becomes the new current line.

            The PB-type commands, such as PBName() and PBDate(), can be used
            to extract the file information added to the buffer.

            The editor uses this command internally for BuildPickBufferEx()
            processing.

Examples:

            integer h, cur_id, pick_buf

            cur_id = GetBufferId()
            pick_buf = CreateTempBuffer()
            GotoBufferId(cur_id)

            h = FindFirstFile("*.*", _NORMAL_)
            if h <> - 1
                repeat
                    AddFFInfoToBuffer(pick_buf)
                until not FindNextFile(h, _NORMAL_)
                FindFileClose(h)
            endif

See Also:   FindFirstFile(), FindThisFile(), FFAttribute(), FFDate(),
            FFName(), FFSize(), FFTime(), PBAttribute(), PBDate(), PBName(),
            PBSize(), PBTime()





AddFileToRing()

Adds the specified file to the editor's Ring of files, without actually
loading the file.

Syntax:     INTEGER AddFileToRing(
                STRING fn [, INTEGER recsize [, INTEGER display_mode]])

            • fn is the name of the file to add to the Ring.  fn can contain
              wildcards, in which case all matching files are added to the
              Ring.

            • recsize is the optional binary line length to be used for
              each file added to the Ring.  To use normal (non-binary mode),
              specify a recsize of 0, which is the default if recsize is
              not specified.

            • display_mode is the optional display mode to set.  If not
              specified, _DISPLAY_TEXT_ is used.  Supported values for
              display_mode are:

              • _DISPLAY_TEXT_ places the screen display in standard display
                mode.

              • _DISPLAY_HEX_ places the screen display in Hex display mode.

              • _DISPLAY_PICKFILE_ places the screen display in file
                PickList mode.

Returns:    The non-zero id number of the first buffer created if successful;
            otherwise, zero (FALSE).

Notes:      AddFileToRing() is used by the EditFile() and EditThisFile()
            command to add files to the editor's Ring of files.  The last file
            added by this command becomes the current buffer.  A file added by
            AddFileToRing() is not loaded into the editor until that file is
            switched to via NextFile(), PrevFile(), EditFile() or
            EditThisFile().

Examples:

            // Add all "*.c" files to the ring, using non-binary mode
            // The files are not loaded until actually switched to

            PushPosition()
            AddFileToRing("*.c", 0)
            PopPosition()

See Also:   EditFile(), EditThisFile(), CreateBuffer(), BinaryMode(),
            DisplayMode()





AddHistoryStr()

Adds a string to the specified history list.

Syntax:     AddHistoryStr(STRING s, INTEGER history_num)

            • s is the string to be added to the specified history list.

            • history_num is an integer which identifies a specific history
              list.

Returns:    Nothing.

Notes:      The editor maintains a history for all built-in commands that
            prompt the user for a string.  However, when commands are used in
            a non-interactive way (for instance, EditFile("some.fle"), which
            will not prompt the user, but will immediately edit "some.fle"),
            the history is not changed or added to.  This command allows you
            to add to that history or to create your own.  Supported values
            for history_num are:

            • A pre-defined constant value representing one of the built-in
              histories:

                      History Name           Associated Commands
                ________________________    _____________________

                _EDIT_HISTORY_              EditFile(), EditThisFile()
                                            InsertFile(),
                                            SaveBlock(), SaveAs()

                _NEWNAME_HISTORY_           ChangeCurrFilename()

                _EXECMACRO_HISTORY_         ExecMacro()

                _LOADMACRO_HISTORY_         LoadMacro()

                _KEYMACRO_HISTORY_          LoadKeyMacro(),
                                            SaveKeyMacro()

                _GOTOLINE_HISTORY_          GotoLine()

                _GOTOCOLUMN_HISTORY_        GotoColumn()

                _REPEATCMD_HISTORY_         RepeatCmd()

                _DOS_HISTORY_               Dos()

                _FINDOPTIONS_HISTORY_       Find()

                _REPLACEOPTIONS_HISTORY_    Replace()

                _FIND_HISTORY_              Find(), Replace()

                _REPLACE_HISTORY_           Replace()

                _FILLBLOCK_HISTORY_         FillBlock()

            • A number in the range 1..127.

            • A number returned by GetFreeHistory(), which will be in the
              range 1..127.

            The MaxHistorySize variable specifies the maximum number of total
            history items to be maintained.  Note that MaxHistorySize applies
            to all history lists combined, not to any one single history
            list.

            If the number of history items is equal to the MaxHistorySize
            variable, then the oldest item will be removed to make room for
            the new item.

            The MaxHistoryPerList variable specifies the maximum number of
            history items to be maintained in each history list.  If the
            number of history items in a particular history list is equal to
            the MaxHistoryPerList variable, then the oldest item will be
            removed to make room for the new item.

Examples:

            /********************************************************
              Find a string, and, if successful, add the found string
              to the history for the find command. "s" is assumed to
              be a string that is declared and initialized elsewhere.
             ********************************************************/
            if Find(s, "")
                AddHistoryStr(s, _FIND_HISTORY_)
            endif

See Also:   DelHistory(), GetFreeHistory(), DelHistoryStr(),
            FindHistoryStr(), GetHistoryStr(), NumHistoryItems(),
            Ask(), Read()

            Variables:  MaxHistorySize, MaxHistoryPerList, CurrHistoryList





Adding Files to the Ring:  Specifying and Opening Files

Files to be placed in the Ring and opened for editing can be specified when
the editor is initially started.  (For more information on opening files when
starting the editor, see "Selecting Files to Edit" in the chapter on
"Starting the Editor.")

You can also open additional files while in the middle of an editing session.
The EditThisFile, EditFile, and NewFile commands are available for this.

▪ EditThisFile  (<Alt E>, or "Open" under File Menu)

  This command prompts for a file to open by issuing the prompt, "File to
  edit:".  (For informational purposes, the current path is displayed in the
  prompt.)  It then attempts to locate the designated file. The file that
  you specify, is opened and becomes the current file.

When the "File to edit:" prompt is displayed by the editor, you can enter
complete filenames, including full path information, or you can input
abbreviated or relative filename specifications.  You can also include
command-line options within this prompt.  (For more information on available
command-line options, see the chapter on "Starting the Editor.")

Also within the "File to edit:" prompt, you can include long filenames and
UNC network paths; and you can specify filenames with embedded spaces.

To enter multiple distinct filenames into the prompt, at least one of the
filenames must be quoted, for instance:

file1 file2 "file3"

Will cause the loading or creation of files "file1", "file2" and "file3".
However entering:

file1 file2 file3

Will cause the loading or creation of the single file, "file1 file2 file3".

▪ EditFile  (<Alt E>, or "Open" under File Menu)

  This command prompts for one or more files to open by issuing the prompt,
  "File(s) to edit:".  (For informational purposes, the current path is
  displayed in the prompt.)  It then attempts to locate the designated
  file(s). The first (or only) file that you specify, is opened and becomes
  the current file.

When the "File(s) to edit:" prompt is displayed by the editor, you can enter
complete filenames, including full path information, or you can input
abbreviated filename specifications.  You can also include command-line
options within this prompt.  (For more information on available command-line
options, see the chapter on "Starting the Editor.")

Also within the "File(s) to edit:" prompt, you can include long filenames and
UNC network paths; and you can specify filenames with leading or embedded
spaces by enclosing the filename within quotes.

If you type an abbreviated entry, the editor first builds the complete path
for the specification.  If no drive is specified, the current drive is used.
If no directory is specified, the current directory is used.  The editor then
determines the file(s) to select for loading, as follows:

    • If you enter an empty response at the "File(s) to edit:" prompt, a
      PickList of files in the current directory is displayed.  You can then
      select the desired file from the list of files.

      A number of file-related options are available in an EditFile PickList.
      You can sort the entries, select an alternate drive for which to
      display matching files, delete listed files from disk, and select
      multiple files and/or directories to process.  For more information,
      see "Obtaining a File PickList within a Prompt Box" in the chapter on
      "Command Prompts and PickLists.")

    • If you enter the complete filename, that filename is used by the editor.

    • If you enter an ambiguous filename specification (one which includes the
      wildcard characters, "*" or "?"), or you include the "Search SubDirs"
      (-s) command-line option, the editor either presents a PickList of all
      matching files from which you can select the desired file, or the editor
      selects all matching files.  (For more information on the "Search
      SubDirs" option, see "Command-Line Options" in the chapter on
      "Starting the Editor.")

      Whether the editor presents a PickList or selects all matching files, is
      determined as follows:

      • The default behavior is set by the LoadWildFromInside variable. (For
        more information on configuring this variable, see
        "Load Wild from Inside" under "System/File Options" in the chapter on
        "Configuring the Editor Interactively.")

      • The editor can be forced to either select all matching files or to
        present a PickList.  To do this, you precede the filename
        specification with the "Load All" (-a) or the "Pick from List" (-a-)
        command-line option.  (For more information on these options, see
        "Command-Line Options" in the chapter on "Starting the Editor.")

    • You can also generate an ambiguous filename by using the Filename
      Completion option.  (For more information on this option, see
      "Obtaining a File PickList within a Prompt Box" in the chapter on
      "Command Prompts and PickLists.")

    • If you specify a partial filename (one that does not include an
      extension and does not end with a "."), and the partial specification
      does not match an existing file, then the editor attempts to locate a
      matching file using the list of default extensions indicated by the
      DefaultExt variable.  (For more information on configuring the
      DefaultExt variable, see "Default File Extensions" under
      "System/File Options" in the chapter on
      "Configuring the Editor Interactively.")  If a matching filename is
      located, then that file is selected.  If no match is found, the editor
      uses the original filename as entered.

    • If you specify a filename that is not valid, the message, "Open
      error:filename Press <Escape>", is displayed on the StatusLine.  When
      you press <Escape>, the "File(s) to edit:" prompt is re-displayed.

After the specific files to load have been determined, the editor updates the
Ring to include any new filenames.  The editor then moves to the first (or
only) filename that you specified.  That file becomes the current file.  If
the file was not previously opened, the editor opens it at this time, either
by loading the file from disk if the file already exists, or by creating a
new file with the specified name and displaying the message, "Editing new
file...".

NOTE:   When you specify multiple filenames to edit, the editor only adds
        the names of the indicated files to the Ring (if they are not already
        in the Ring).  The editor does not actually open a file (by loading
        an existing file or creating a new file) until the file becomes the
        current file.

        If you specify a filename that is already open in the current editing
        session, the editor DOES NOT re-open that file.  Thus, the editor
        never loads multiple copies of the same file, nor does it re-load a
        file from disk that is already loaded.



▪ NewFile  ("New" under File Menu)

  This command creates a new temporary memory buffer with a name in the format
  <unnamed-#> (where "#" represents an actual number assigned by the editor).
  This temporary buffer becomes the current file.

  Because the file that is created does not have an actual name, it cannot be
  saved as is.  If you want to save the contents of the file, you can either
  execute the SaveAs command (which allows you to specify a name for the
  file); or you can first change the name of the file using the
  ChangeCurrFilename command, and then save the file under the new name.  (The
  SaveAs and ChangeCurrFilename commands are discussed later in this chapter.)

  This command is useful for creating a temporary file without a name, which
  can later be discarded, or given a name so that it can be saved.





AddLine()

Adds a line after the current line.  The cursor is placed on the newly-created
line.  The cursor column does not change.

Syntax:     INTEGER AddLine([STRING text [, INTEGER buffer_id]])

            • text is an optional string to be placed at column 1 of the
              newly-created line.

            • buffer_id is the optional id number of the file where the
              line is to be added.  If not passed, the line is added to the
              current file.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            If the optional buffer_id is specified, the line is added after
            the current line in the specified buffer.  _ON_CHANGING_FILES_
            hooks are NOT invoked by this command.

Examples:

            // Add a blank line after the current line
            AddLine()

            // Add a SAL comment after the current line
            AddLine("//")

            /********************************************************
              Add a line containing the contents of string s, after
              the current line in buffer id, where id is the id
              number of a buffer obtained via GetBufferId().
             ********************************************************/
            AddLine(s, id)

See Also:   InsertLine(), DelLine(), KillLine()





Addr()

Returns the 32-bit address of the specified variable.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER Addr(VAR INTEGER | VAR STRING variable_name)

            • variable_name is either a string or integer variable

Returns:    The 32-bit pointer to the indicated variable.

Notes:      The address of an INTEGER variable is a pointer to a 32-bit long.

            The address of a STRING variable is a pointer to the length
            byte of the string variable.  To point to the contents of the
            string variable, the pointer must be incremented by 2, which
            requires the use of AdjPtr().

Examples:

            integer a, foo

            a = Addr(foo)

See Also:   AdjPtr(), Ofs(), Seg()





AddTrailingSlash()

Adds a trailing slash to a string if the string does not already end with a
slash.

Syntax:     STRING AddTrailingSlash(STRING path)

            • path is a string (typically a directory path) that needs to
              be terminated with a trailing slash.

Returns:    The string specified by path with a trailing slash.

Notes:      If path already has a trailing slash, path is returned
            unchanged.

            This command is typically used when a filename is to be appended
            to a path, and it is unknown whether the path ends in a trailing
            slash.

            This function works with both forward slashes (/) and
            backslashes (\).

Examples:

            Assume dir and fn are strings containing a directory path and a
            filename, respectively:

            EditFile(AddTrailingSlash(dir) + fn)

See Also:   isTrailingSlash(), RemoveTrailingSlash()





AdjPtr()

Adjusts the offset portion of a 32-bit pointer by a specified amount.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER AdjPtr(INTEGER ptr, INTEGER adj)

            • ptr is a 32-bit pointer consisting of a 16-bit segment and a
              16-bit offset.

            • adj is the amount by which to adjust the offset portion of
              ptr.

Returns:    The 32-bit pointer as adjusted by adj.

Notes:      All mathematical operations within SAL are performed as signed
            arithmetic.  Since pointer segments can be equal to or greater
            than 8000h, ordinary signed arithmetic on pointers may yield
            undesirable results.  Always use AdjPtr() to adjust the value of
            a pointer so that the segment will not change when the offset is
            adjusted.

Examples:

            To point to the contents of a STRING variable, the pointer to
            the string itself must be incremented by 2.

            string s[10]
            integer addr_of_string, addr_of_string_contents

            addr_of_string = Addr(s)
            addr_of_string_contents = AdjPtr(addr_of_string, 2)

See Also:   Addr(), Ofs(), Seg()





Alarm()

Produces a short tone on the PC's speaker.

Syntax:     Alarm()

Returns:    Nothing.

Notes:      This is the same sound a failed Find() issues.

            Under WINNT4/2000/XP, the tone is sent to the PC speaker.

            Under WIN95/98/Me, the following action occurs:

            If the system is configured with a sound card, the "default sound
            event" is played; otherwise, the "standard system beep" is sent
            to the PC speaker.

See Also:   Sound(), Delay()





Alternative Modes For Viewing Files

Several alternative modes for viewing and/or editing files are provided in the
editor:  Hex mode, Binary mode, and Browse mode.

You can use these modes separately, or in conjunction with each another.


Hex Mode
────────

When Hex mode is ON, the hexadecimal values for the characters in a file are
displayed on the screen.  When viewing a file in Hex mode, the screen (or
window) containing that file is split into two columns.  16 characters of
each line of the file are displayed in text mode in the left-hand column.  In
the right-hand column, the hexadecimal representation is displayed for each
of the characters on the left.  (If the screen is split into vertical
windows, the hex representation column does not display if the vertical
window is too small to accommodate it.)  Both the text and the hex
representations of the current character are highlighted.

If you select both Hex mode and Binary mode for a file, the left-hand column
will contain the binary representation for the text, and the right-hand
column will contain the hexadecimal representation.

To toggle Hex mode ON and OFF for a file, select "Hex View" under the Util
Menu.  You can also set Hex mode ON at the time a file is initially loaded by
specifying the "Hex Load" (-h) command-line option at the command line or at
the "File(s) to edit:" prompt.  (For more information on specifying the "Hex
Load" command-line option, see "Command-Line Options" in the chapter on
"Starting the Editor.")

While you are in Hex mode, all normal editing functions are available.  You
can edit either the text format of the data (in the text area on the left),
or the hexadecimal format of the data (in the hexadecimal-display area on the
right).  To toggle between the text area and the hexadecimal-display area,
press the <Tab> key.


Binary Mode
───────────

When a file is loaded in Binary mode, the text and data in the file are
displayed exactly as stored on disk.  No translation is made of line or file
termination characters (that is, carriage return, linefeed, and Control-Z), or
of tab characters.  The file is not automatically split into lines at the
occurrence of line-termination characters.  Instead, the file contents are
split at a user-defined length, and wrapped to successive lines.  If the file
is saved, no line or file termination characters are added.

To view a file in Binary mode, precede the filename specification with the
"Binary Load" (-b) command-line option at the time the file is specified for
editing, either at the command line or the "File(s) to edit:" prompt.  The
length at which you want the editor to split lines must be specified at the
same time.  (For more information on specifying the "Binary Load" option, see
"Command-Line Options" in the chapter on "Starting the Editor.")

While viewing a file in Binary mode, all editing functions are available;
however, caution should be taken.  Certain operations, such as execution of
the WrapPara command, could give undesirable results if you save the file.

Browse Mode
───────────

When Browse mode is ON for a file, you can scroll through that file, and
execute any commands that do not change the text; however, you cannot execute
any text-changing commands in that file, and you cannot save the file.

To toggle Browse mode ON and OFF for a file, select "Browse Mode" under the
Options Menu.





Appendix A:  Technical Specifications

In the editor, you can edit multiple files whose total size is limited only
by the amount of virtual memory that Windows allows.  A maximum of
2,147,483,647 files may be loaded at once, given enough memory.

The total amount that is actually available for files you are editing may be
somewhat reduced by the following, if you use them:

    • ClipBoards used (exactly as if each was a file)

    • Macro files loaded

    • Overhead for each file loaded (approximately 0.5k)

    • Deletion Buffer

    • Per file Undo Buffer

The maximum line length accommodated by the editor is 30,000 characters.
Lines longer than this are split at the maximum line length, and wrapped
to the following line.

The configuration file that is installed in the editor can have a maximum size
of 63k bytes, once compiled.  This includes the space for all macros, key
assignments, menus, helpdefs, and datadefs.

A maximum of 60 external Compiled Macro files may be loaded at any one time.

Each external Compiled Macro file may have up to 63k of Compiled Macros.





Appendix B:  Command Implementation

════════════════════════════════════════════════════════════════════════════════

The table in this appendix provides a cross-reference between the editing
commands as documented in the User's Guide (first column of the table), and
the actual native command or enhanced macro by which the editing command is
implemented in the editor (second column of the table).

Editing commands are implemented in a number of ways:

    1.  By invoking a native command without any parameters.  Most of these
        commands have the same name as the editing command, and are indicated
        as the command name followed by "()".  For example, the AddLine
        command described in the User's Guide is implemented as the native
        AddLine() command itself.

        Certain editing commands invoke native commands with different names.
        For example, the Again command is implemented as the native
        RepeatFind() command.

    2.  By invoking a native command that specifies a particular parameter
        for that command.  These are indicated by a value in "()" following
        the command under the second column of the table.  For example, the
        "OverlayColumnBlock" command is implemented via the native
        CopyBlock() command using the parameter "_OVERWRITE_", as
        "CopyBlock(_OVERWRITE_)".

    3.  By invoking either a macro which enhances the behavior of a native
        command, or a macro that provides additional features not included in
        the native commands.  Generally, these are indicated by a macro name
        beginning with an "m" under the second column of the table.  For
        example, the BackSpace command is implemented via a macro named
        "mBackSpace()", which enhances the native BackSpace command; and the
        CompressView command is provided through the mCompressView() macro,
        which is composed of a number of native commands.

        A number of commands are implemented via a macro that specifies a
        particular parameter.  For example, the FunctionList command is
        implemented via the "mCompressView()" macro using the parameter "1",
        as "mCompressView(1)".

        Certain editing commands are implemented via a group of macros in an
        external macro file.  Each of these is indicated by identifying the
        name of the macro file.  For example, the SpellCheck command is
        implemented via a group of macros in the external macro file
        "SPELLCHK.MAC".

        For most commands implemented as macros, the macro source can be
        found (under the indicated macro name) either in the standard SemWare
        Editor Professional user-interface macro file, TSE.UI (located in the
        UI\ editor subdirectory), or in a macro source file in the MAC\
        editor subdirectory.

 ┌──────────────────────────────────────┬────────────────────────────────────┐
 │ Editing Command                      │ Native Command or Enhanced Macro   │
 ├──────────────────────────────────────┼────────────────────────────────────┤
 │ AddLine                              │  AddLine()                         │
 │ Again                                │  RepeatFind()                      │
 │ AgainReverse                         │  RepeatFind(_REVERSE_)             │
 │ AsciiChart                           │ mAsciiChart()                      │
 │ AutoLoadList                         │  EditAutoLoadList()                │
 │ BackSpace                            │ mBackSpace()                       │
 │ BegFile                              │ mBegFile()                         │
 │ BegLine                              │  BegLine()                         │
 │ BegPara                              │ mBegPara                           │
 │ BegWindow                            │  BegWindow()                       │
 │ Book                                 │  external macro file: BOOK.MAC     │
 │ Capitalize                           │  external macro file: CAPITAL.MAC  │
 │ CaptureDosOutput                     │  external macro file: CAPTURE.MAC  │
 │ cCloseCurlyBrace                     │ mCloseBrace()                      │
 │ CD                                   │  external macro file: CD.MAC       │
 │ CenterLine                           │  external macro file: CENTER.MAC   │
 │ ChangeCurrFilename                   │  ChangeCurrFilename()              │
 │ ChangeVideoMode                      │  external macro file: VIDEO.MAC    │
 │ CloseFileAndWindow                   │ mCloseFileAndWindow()              │
 │ CloseWindow                          │  CloseWindow()                     │
 │ CmpFiles                             │  external macro file: CMPFILES.MAC │
 │ Compile                              │  external macro file: COMPILE.MAC  │
 │ CompileCurrFile                      │ mCompileCurrFile()                 │
 │ CompressView                         │ mCompressView(0)                   │
 │ Copy to a Named ClipBoard            │  external macro file: NAMECLIP.MAC │
 │ Copy to the System ClipBoard         │  Copy()                            │
 │ CopyAppend to a Named ClipBoard      │  external macro file: NAMECLIP.MAC │
 │ CopyAppend to the System ClipBoard   │  CopyAppend()                      │
 │ CopyBlock                            │  CopyBlock()                       │
 │ CopyCharAbove                        │ mCopyCharAbove()                   │
 │ CopyCharAboveToEol                   │ mCopyCharAboveToEol()              │
 │ CopyToWinClip                        │  CopyToWinClip()                   │
 │ CReturn                              │ mCReturn()                         │
 │ CUAMark                              │  external macro file: CUAMARK.MAC  │
 │ Cut to a Named ClipBoard             │  external macro file: NAMECLIP.MAC │
 │ Cut to the System ClipBoard          │  Cut()                             │
 │ CutAppend to a Named ClipBoard       │  external macro file: NAMECLIP.MAC │
 │ CutAppend to the System ClipBoard    │  CutAppend()                       │
 │ DateTimeStamp                        │ mDateTimeStamp()                   │
 │ DebugCurrFile                        │ mDebugCurrFile()                   │
 │ DebugMacro                           │  external macro file: DEBUG.MAC    │
 │ DelBlock                             │  DelBlock()                        │
 │ DelChar                              │ mDelChar()                         │
 │ DelLeftWord                          │  DelLeftWord()                     │
 │ DelLine                              │  DelLine()                         │
 │ DelRightWord                         │  DelRightWord()                    │
 │ DelToEol                             │  DelToEol()                        │
 │ DelWindow                            │  DelWindow()                       │
 │ Dos                                  │  Dos()                             │
 └──────────────────────────────────────┴────────────────────────────────────┘

 ┌──────────────────────────────────────┬────────────────────────────────────┐
 │ Editing Command                      │ Native Command or Enhanced Macro   │
 ├──────────────────────────────────────┼────────────────────────────────────┤
 │ Down                                 │  Down()                            │
 │ DupLine                              │  DupLine()                         │
 │ EditFile                             │  EditFile()                        │
 │ EndFile                              │ mEndFile()                         │
 │ EndLine                              │  EndLine()                         │
 │ EndPara                              │ mEndPara()                         │
 │ EndWindow                            │  EndWindow()                       │
 │ ExecMacro                            │  ExecMacro()                       │
 │ ExecScrapMacro                       │  ExecScrapMacro()                  │
 │ Exit                                 │  Exit()                            │
 │ FileManager                          │  external macro file: F.MAC        │
 │ FillBlock                            │  FillBlock()                       │
 │ Find                                 │  Find()                            │
 │ FindAndDo                            │  external macro file: FIND&DO.MAC  │
 │ FindWordAtCursor                     │ mFindWordAtCursor('+')             │
 │ FindWordAtCursorBackwards            │ mFindWordAtCursor('b')             │
 │ FindWordAtCursorGlobally             │ mFindWordAtCursor('g')             │
 │ Flip                                 │ mFlip()                            │
 │ FunctionList                         │ mCompressView(1)                   │
 │ GlobalUnDelete                       │  GlobalUnDelete()                  │
 │ GotoBlockBegin                       │  GotoBlockBegin()                  │
 │ GotoBlockEnd                         │  GotoBlockEnd()                    │
 │ GotoColumn                           │  GotoColumn()                      │
 │ GotoLine                             │  GotoLine()                        │
 │ GotoMark                             │  GotoMark()                        │
 │ GotoWindow                           │  GotoWindow()                      │
 │ GotoWindowNumber                     │  GotoWindow(n)                     │
 │ Help                                 │  Help()                            │
 │ HelpOnKeyAssignments                 │  Help("Key Assignments")           │
 │ HelpOnWordAtCursor                   │ mHelpOnWordAtCursor()              │
 │ HWindow                              │  HWindow()                         │
 │ IncrementalSearch                    │  external macro file: ISRCH.MAC    │
 │ InsertFile                           │  InsertFile()                      │
 │ InsertLine                           │  InsertLine()                      │
 │ JoinLine                             │  JoinLine()                        │
 │ Justify                              │  external macro file: JUSTIFY.MAC  │
 │ KillFile                             │  KillFile()                        │
 │ Left                                 │  Left()                            │
 │ ListOpenFiles                        │  external macro file: LISTOPEN.MAC │
 │ ListRecentFiles                      │ mListRecentFiles()                 │
 │ Literal                              │  Literal()                         │
 │ LoadKeyMacro                         │  LoadKeyMacro()                    │
 │ LoadMacro                            │  LoadMacro()                       │
 │ Lower                                │ mLower()                           │
 │ MainMenu                             │  MainMenu()                        │
 │ MarkChar                             │  MarkChar()                        │
 │ MarkColumn                           │  MarkColumn()                      │
 └──────────────────────────────────────┴────────────────────────────────────┘

 ┌──────────────────────────────────────┬────────────────────────────────────┐
 │ Editing Command                      │ Native Command or Enhanced Macro   │
 ├──────────────────────────────────────┼────────────────────────────────────┤
 │ MarkLine                             │  MarkLine()                        │
 │ MarkParagraph                        │ mMarkPara()                        │
 │ MarkStream                           │  MarkStream()                      │
 │ MarkToEOL                            │  MarkToEOL()                       │
 │ MarkWord                             │  MarkWord()                        │
 │ Match                                │  external macro file: MATCH.MAC    │
 │ MouseMenu                            │  MouseMenu()                       │
 │ MoveBlock                            │  MoveBlock()                       │
 │ NewFile                              │  NewFile()                         │
 │ NextChar                             │  NextChar()                        │
 │ NextFile                             │  NextFile()                        │
 │ NextPara                             │ mNextPara()                        │
 │ NextWindow                           │  NextWindow()                      │
 │ OneWindow                            │  OneWindow()                       │
 │ OpenFileAndWindow                    │ mOpenFileAndWindow()               │
 │ Overlay                              │  external macro file: OVERLAY.MAC  │
 │ OverlayColumnBlock                   │  CopyBlock(_OVERWRITE_)            │
 │ PageDown                             │  PageDown()                        │
 │ PageUp                               │  PageUp()                          │
 │ Paste from a Named ClipBoard         │  external macro file: NAMECLIP.MAC │
 │ Paste from the System ClipBoard      │  Paste()                           │
 │ PasteFromWinClip                     │  PasteFromWinClip()                │
 │ PasteOver from a Named ClipBoard     │  external macro file: NAMECLIP.MAC │
 │ PasteOver from the System ClipBoard  │  Paste(_OVERWRITE_)                │
 │ PasteUnDelete                        │  PasteUnDelete()                   │
 │ PlaceMark                            │  PlaceMark()                       │
 │ Potpourri                            │  external macro file: POTPOURR.MAC │
 │ PrevChar                             │  PrevChar()                        │
 │ PrevFile                             │  PrevFile()                        │
 │ PrevHelp                             │  PrevHelp()                        │
 │ PrevPara                             │ mPrevPara()                        │
 │ PrevPosition                         │  PrevPosition()                    │
 │ PrevWindow                           │  PrevWindow()                      │
 │ PrintBlock                           │  external macro file: PRINT.MAC    │
 │ PrintFile                            │  external macro file: PRINT.MAC    │
 │ PurgeKeyMacro                        │  PurgeKeyMacro()                   │
 │ PurgeMacro                           │  PurgeMacro()                      │
 │ QuitFile                             │  QuitFile()                        │
 │ QuoteLine                            │  external macro file: QUOTE.MAC    │
 │ RecordKeyMacro                       │  RecordKeyMacro()                  │
 │ RedisplayViewPickList                │  ViewFinds()                       │
 │ RepeatCmd                            │  RepeatCmd()                       │
 │ Replace                              │  Replace()                         │
 │ ReplaceFile                          │  ReplaceFile()                     │
 │ ResizeWindow                         │  ResizeWindow()                    │
 │ RestoreCursorLine                    │  RestoreCursorLine()               │
 │ Right                                │  Right()                           │
 │ RollDown                             │  RollDown()                        │
 └──────────────────────────────────────┴────────────────────────────────────┘

 ┌──────────────────────────────────────┬────────────────────────────────────┐
 │ Editing Command                      │ Native Command or Enhanced Macro   │
 ├──────────────────────────────────────┼────────────────────────────────────┤
 │ RollLeft                             │  RollLeft()                        │
 │ RollRight                            │  RollRight()                       │
 │ RollUp                               │  RollUp()                          │
 │ SaveAllAndExit                       │  SaveAllAndExit()                  │
 │ SaveAllFiles                         │  SaveAllFiles()                    │
 │ SaveAndQuitFile                      │  SaveAndQuitFile()                 │
 │ SaveAs                               │  SaveAs()                          │
 │ SaveBlock                            │  SaveBlock()                       │
 │ SaveFile                             │  SaveFile()                        │
 │ SaveKeyMacro                         │  SaveKeyMacro()                    │
 │ ScrollDown                           │  ScrollDown()                      │
 │ ScrollToCenter                       │  ScrollToCenter()                  │
 │ ScrollToTop                          │  ScrollToTop()                     │
 │ ScrollUp                             │  ScrollUp()                        │
 │ Shell                                │  Shell()                           │
 │ Shift                                │ mShift()                           │
 │ ShiftLeft                            │ mShiftBlock(SHIFTLEFT)             │
 │ ShiftRight                           │ mShiftBlock(SHIFTRIGHT)            │
 │ ShowEntryScreen                      │  ShowEntryScreen()                 │
 │ ShowFileInfo                         │  external macro file: FILEINFO.MAC │
 │ Sort                                 │  external macro file: SORT.MAC     │
 │ SpellCheck                           │  external macro file: SPELLCHK.MAC │
 │ SplitLine                            │  SplitLine()                       │
 │ SwapLines                            │ mSwapLines()                       │
 │ TabLeft                              │ mTabLeft()                         │
 │ TabRight                             │ mTabRight()                        │
 │ ToggleAutoIndent                     │ mToggleAutoIndent()                │
 │ ToggleHexView                        │ mToggleHexView()                   │
 │ ToggleInsert                         │  ToggleInsert()                    │
 │ ToggleLineDrawing                    │  Toggle(LineDrawing)               │
 │ ToggleSyncScroll                     │  external macro file: SYNCHSCR.MAC │
 │ ToggleTemplateExpansion              │ mToggleTemplateExpand()            │
 │ ToggleWordWrap                       │ mToggleWordWrap()                  │
 │ UnDelete                             │  UnDelete()                        │
 │ UnMarkBlock                          │  UnMarkBlock()                     │
 │ Up                                   │  Up()                              │
 │ Upper                                │ mUpper()                           │
 │ VWindow                              │  VWindow()                         │
 │ Where                                │  external macro file: WHERE.MAC    │
 │ WordLeft                             │  WordLeft()                        │
 │ WordRight                            │  WordRight()                       │
 │ WrapPara                             │ mWrapPara()                        │
 │ ZoomWindow                           │  ZoomWindow()                      │
 └──────────────────────────────────────┴────────────────────────────────────┘





Appendix C:  Commands By Category

New commands added to version 4.4 are followed by "*".
Existing commands which are "Enhanced" for version 4.4 are followed by "**".

Adding Text              Font                        Position
───────────              ─────                       ────────
                                                     
AddLine                  ChooseFont                  CurrCol
CopyBlock                GetCharWidthHeight          CurrLine
CReturn                  GetFont                     CurrPos
DupLine                  ResizeFont                  CurrRow
InsertData               SetFont                     CurrXoffset
InsertLine                                           GetPositionInfo
InsertText               Help                        KillPosition
Literal                  ────                        PopPosition
Paste                                                PosFirstNonWhite
PasteReplace             Help                        PosLastNonWhite
PasteFromWinClip         PrevHelp                    PushPosition
PasteReplaceFromWinClip  PutHelpLine                 SwapPosition
SelfInsert               QuickHelp                   
SplitLine                SearchHelp                  GotoMark
                                                     PlaceMark
Bits                     History                     
────                     ───────                     KillLocation
                                                     PopLocation
ClearBit                 AddHistoryStr               PushLocation
GetBit                   DelHistory                  
SetBit                   DelHistoryStr               Printing
                         FindHistoryStr              ────────
Blocks                   GetFreeHistory              
──────                   GetHistoryStr               ClosePrint
                         LoadHistory                 PrintBlock
CopyBlock                NumHistoryItems             PrintChar
DelAnyCharOrBlock *      SaveHistory                 PrintFile
DelBlock                                             SetPrinterFont
DelCharOrBlock *         Hooks/Events                
FillBlock                ────────────                Process
GetClipBoardBlockType                                ───────
GotoBlockBegin           BreakHookChain              
GotoBlockBeginCol        ExecHook                    Disable
GotoBlockEnd             GetHookState                Enable
GotoBlockEndCol          Hook                        EndProcess
isBlockInCurrFile        QueryEditState              Process
isBlockMarked            SetHookState                
isCurrLineInBlock        TerminateEvent              Session Global Variables
isCursorInBlock          UnHook                      ────────────────────────
KillBlock                                            
Mark                     Initialization File         DelGlobalVar
MarkBlockBegin *         ───────────────────         ExistGlobalVar
MarkBlockEnd *                                       GetGlobalInt
MarkChar                 FlushProfile                GetGlobalStr
MarkColumn               GetNextProfileItem          SetGlobalInt
MarkFoundText            GetNextProfileSectionName   SetGlobalStr
MarkLine                 GetProfileInt               
MarkStream               GetProfileStr               Strings
MarkToEOL                LoadProfileSection          ───────
MarkWord                 LoadProfileSectionNames     
MoveBlock                RemoveProfileItem           AddTrailingSlash
PopBlock                 RemoveProfileSection        Asc
PrintBlock               WriteProfileInt             Chr
PushBlock                WriteProfileStr             CmpiStr
SaveBlock                                            CurrChar
UnMarkBlock              Keyboard Macros             DelStr
                         ───────────────             EquiStr
Copy                                                 Format
CopyAppend               ExecScrapMacro              GetFileToken
Cut                      LoadKeyMacro                GetFoundText
CutAppend                PurgeKeyMacro               GetMarkedText
Paste                    RecordKeyMacro              GetStrFromWinClip *
PasteReplace             SaveKeyMacro                GetText
                                                     GetToken
CopyToWinClip **         Keyboard                    GetWord
CopyAppendToWinClip **   ────────                    InsStr
CutToWinClip                                         isTrailingSlash
CutAppendToWinClip       Ask                         isWildPath
PasteFromWinClip         AskFilename                 LeftStr *
PasteReplaceFromWinClip  AskNumeric                  Length
                         ChainCmd                    LTrim
Bookmarks                Disable                     MatchFilename
─────────                Enable                      NumFileTokens
                         GetKey                      NumTokens
GotoMark                 GetKeyFlags                 Pos
PlaceMark                isKeyAssigned *             QuotePath
                         isTypeableKey               RemoveTrailingSlash
DelAllBookMarks          KeyCode                     RightStr
DelBookMark              KeyName                     RTrim
GetBookMarkInfo          KeyPressed                  SizeOf
isBookMarkSet            lRead                       Str
                         lReadNumeric                StrCount *
KillPosition             Message                     StrFind *
PopPosition              MsgBox **                   StrReplace *
PrevPosition             MsgBoxBuff                  SubStr
PushPosition             MsgBoxEx                    Trim
                         PressKey                    Val
Buffers                  PushKey                     VersionStr *
───────                  PushKeyStr                  
                         Read                        SyntaxHilite
AbandonFile              ReadNumeric                 ────────────
AddFFInfoToBuffer        WaitForKeyPressed *         
AddFileToRing            Warn                        GetSynFilename
BinaryMode               YesNo                       GetSynLanguageType
BrowseMode                                           GetSynMultiLnDlmt
BufferType               Low Level                   GetSynToEOL
ChangeCurrFilename       ─────────                   InitSynhiCurrFile
CheckDefaultExt                                      LinkSynFile
CreateBuffer             Addr                        LoadSynhiAssoc
CreateTempBuffer         AdjPtr                      PurgeSynhi
CurrExt                  Ofs                         ReplaceSynFile
CurrFilename             Ptr                         
CurrLineLen              Seg                         Tabs
DisplayMode                                          ────
EditBuffer               HiByte                      
EditFile                 HiWord                      DistanceToTab
EmptyBuffer              LoByte                      EntabCurrLine
FileChanged              LoWord                      ExpandTabsToSpaces
GetBufferId                                          TabLeft
GotoBufferId             PeekByte                    TabRight
HexEdit                  PeekLong                    TabSet
InsertFile               PeekWord                    
LoadBuffer               PokeByte                    Termination
LongestLineInBuffer      PokeLong                    ───────────
NewFile                  PokeWord                    
NextFile                                             AbandonEditor
NumFiles                 Macros (Compiled)           Exit
NumLines                 ─────────────────           SaveAllAndExit
PrevFile                                             
PrintFile                AddAutoLoadMacro            UnDelete
QuitFile                 ChainCmd                    ────────
RemoveUnloadedFiles      DelAutoLoadMacro            
ReplaceFile              EditAutoLoadList            GlobalUnDelete
SaveAllFiles             ExecLoadedMacro             PasteUnDelete
SaveAndQuitFile          ExecMacro **                RestoreCursorLine
SaveFile                 isAutoLoaded *              UnDelete
                         isGUI                       
ClearBufferDaTmAttr      isMacroLoaded               Video Commands
GetBufferDaTmAttr        LoadMacro                   ──────────────
UpdateBufferDaTmAttr     LoadStartupMacros           
                         MacroStackAvail             BufferVideo
DelBufferVar             PurgeMacro                  ClrEol
ExistBufferVar                                       ClrScr
GetBufferInt             Menus                       Color
GetBufferStr             ─────                       DrawBox
SetBufferInt                                         FullWindow
SetBufferStr             MenuKey                     GetColorTableValue
                         MenuOption                  GetMaxRowsCols
Buffer Global Variables  MenuStr                     GetStr
───────────────────────  SetMenuBar                  GetStrAttr
                         SizeOf                      GetStrAttrXY
DelBufferVar                                         GetStrXY
ExistBufferVar           Miscellaneous               GotoXY
GetBufferInt             ─────────────               ListFooter
GetBufferStr                                         ListHeader
SetBufferInt             Abs                         PopWinClose
SetBufferStr             ChrSet                      PopWinOpen
                         Escape                      PutAttr
ClipBoards               GetWindowTitle              PutAttrXY
──────────               GetWinHandle                PutChar
                         isAlpha                     PutCharH
Copy                     isAlphaNum                  PutCharHXY
CopyAppend               isDigit                     PutCharV
Cut                      isHexDigit                  PutCharXY
CutAppend                isLower                     PutCtrStr
Paste                    isUpper                     PutLine
PasteReplace             isWhite                     PutLineXY
                         isWord                      PutNCharAttr
CopyToWinClip **         LineDraw                    PutOemStrXY
CopyAppendToWinClip **   LineTypeMenu                PutStr
CutToWinClip             List                        PutStrAttr
CutAppendToWinClip       lList                       PutStrAttrXY
PasteFromWinClip         lVersion                    PutStrEOL
PasteReplaceFromWinClip  Max                         PutStrEOLXY
                         Min                         PutStrXY
EmptyWinClip             NoOp                        SetColorTableValue
GetStrFromWinClip *      RedoCount                   SetCursorOff
isWinClipAvailable       RepeatCmd                   SetCursorOn
                         SaveSettings                SetVideoRowsCols
Date/Time                SetUndoOff                  UnBufferVideo
─────────                SetUndoOn                   VGotoXY
                         SetWindowTitle              VGotoXYAbs
GetClockTicks            SignOn                      VHomeCursor
GetDate                  ToggleInsert                VWhereX
GetDateStr               UndoCount                   VWhereY
GetTime                  UndoMode                    WhereX
GetTimeStr               UpdateDisplay               WhereXAbs
                         UpdateDisplayFlags          WhereY
Deleting Text            Version                     WhereYAbs
─────────────            VersionStr *                Window
                                                     WindowFooter
BackSpace                Mouse                       Write
Cut                      ─────                       WriteLine
DelAnyChar *                                         
DelAnyCharOrBlock *      GetWheelScrollLines         Windows
DelBlock                 GotoMouseCursor             ───────
DelCharOrBlock *         HideMouse                   
DelChar                  MouseHotSpot                CloseWindow
DelLeftWord              MouseKeyHeld                DelWindow
DelLine                  MouseMarking                GotoWindow
DelRightWord             MouseStatus                 HWindow
DelToEol                 MouseWindowId               isZoomed
JoinLine                 ProcessHotSpot              NextWindow
KillBlock                ShowMouse                   NumWindows
KillLine                 TrackMouseCursor            OneWindow
KillToEol                WaitForMouseEvent           PrevWindow
                                                     ResizeWindow
Disk File I/O            Movement                    SetWindowHeight
─────────────            ────────                    SetWindowWidth
                                                     VWindow
fClose                   BegFile                     WindowId
fCreate                  BegLine                     ZoomWindow
fDup                     BegLineTog *                
fDup2                    BegWindow                   
fOpen                    BegWord                     
fRead                    Down                        
fReadFile                EndFile                     
fSeek                    EndLine                     
fWrite                   EndLineTog *                
fWriteFile               EndWindow                   
isCharDevice             EndWord                     
                         GotoBlockBegin              
Editing                  GotoBlockEnd                
───────                  GotoColumn                  
                         GotoLine                    
AddLine                  GotoPos                     
BackSpace                GotoRow                     
ClearUndoRedoList        GotoXoffset                 
CReturn                  Left                        
DelCharOrBlock *         NextChar                    
DelAnyCharOrBlock *      PageDown                    
DelChar                  PageUp                      
DelAnyChar *             PrevChar                    
DelLeftWord              PrevPosition                
DelLine                  Right                       
DelRightWord             RollDown                    
DelToEol                 RollLeft                    
DupLine                  RollRight                   
Flip                     RollUp                      
InsertData               ScrollDown                  
InsertLine               ScrollLeft                  
InsertText               ScrollRight                 
JoinLine                 ScrollToBottom *            
KillLine                 ScrollToCenter              
KillToEol                ScrollToRow                 
Literal                  ScrollToTop                 
Lower                    ScrollUp                    
Redo                     Up                          
SelfInsert               WordLeft                    
ShiftText                WordRight                   
Sort                                                 
SplitLine                OS Access                   
Undo                     ─────────                   
Upper                                                
WrapLine                 Alarm                       
WrapPara                 ChDir                       
                         CurrDir                     
Editor Variables         Delay                       
────────────────         Dos                         
                         DosIOResult                 
Query                    ExpandPath                  
Set                      FileExists                  
Toggle                   GetDir                      
                         GetDrive                    
Files                    GetEnvStr                   
─────                    is32BitApp                  
                         isFullScreen                
AbandonFile              lDos                        
AddFileToRing            LoadDir                     
ChangeCurrFilename       LogDrive                    
ChangedFilesExist        lShowEntryScreen            
CopyFile                 MakeTempName                
CurrExt                  PickDrive                   
CurrFilename             RenameDiskFile              
CurrMacroFilename        SearchPath                  
EditFile                 SetFileAttr                 
EditThisFile             Shell                       
EraseDiskFile            ShowEntryScreen             
FileChanged              Sound                       
InsertFile               SplitPath                   
KillFile                 SqueezePath                 
LockCurrentFile          StartedFromDosPrompt        
MkDir                    StartPgm *                  
MoveFile                 WhichOS **                  
NewFile                                              
NextFile                 BuildPickBufferEx           
NumFiles                 PBAttribute                 
PickFile                 PBDate                      
PrevFile                 PBDateStr                   
PrintFile                PBName                      
QuitFile                 PBSize                      
RemoveUnloadedFiles      PBTime                      
RenameAndSaveFile        PBTimeStr                   
ReplaceFile                                          
RmDir                    FFAttribute                 
SaveAllFiles             FFDate                      
SaveAndQuitFile          FFDateStr                   
SaveAs                   FFName                      
SaveFile                 FFSize                      
UnLockCurrentFile        FFTime                      
                         FFTimeStr                   
Find/Replace             FindFileClose               
────────────             FindFirstFile               
                         FindNextFile                
Find                     FindThisFile                
GetFoundText                                         
HiLiteFoundText                                      
lFind                                                
lRepeatFind                                          
lReplace                                             
MarkFoundText                                        
RepeatFind                                           
Replace                                              
ViewFinds                                            
RepeatFind                                           
Replace                                              
ViewFinds                                            
                                                     
                                                     





Appendix C:  Standard Key Assignments

This appendix identifies the key assignments in the standard editor
configuration.

 FUNCTION KEY          EDITOR COMMAND/MACRO
 ───────────────────   ────────────────────────────────────────

 <F1>                  Help()
 <F2>                  AddLine()
 <F4>                  DupLine()
 <F5>                  ScrollToTop()
 <F6>                  DelToEol()
 <F9>                  Shell()
 <F10>                 MainMenu()
 <F12>                 ExecMacro("SpellChk")

 <Alt F1>              PrevHelp()
 <Alt F2>              InsertLine()
 <Alt F3>              ExecMacro("match")
 <Alt F4>             mLower()
 <Alt F5>              RollLeft()
 <Alt F6>              RollRight()
 <Alt F9>              Dos()
 <Alt F10>             ShowEntryScreen()

 <Ctrl F1>            mHelpOnWordAtCursor()
 <Ctrl F2>            mSwapLines()
 <Ctrl F7>            mShift()
 <Ctrl f9>            mCompileCurrFile()
 <Ctrl F10>            ExecLoadPurge()

 <Shift F1>            Help("Key Assignments")
 <Shift F3>            ExecMacro("sort " + Str(sort_flags))
 <Shift F4>           mUpper()
 <Shift F5>            ScrollToCenter()
 <Shift F7>           mShiftBlock(SHIFTLEFT)
 <Shift F8>           mShiftBlock(SHIFTRIGHT)
 <Shift F9>            ExecMacro("Compile -m")
 <Shift F10>           ExecMacro("Potpourr")

 <AltShift F9>         ExecMacro("Capture")


 SPECIAL-PURPOSE KEY   EDITOR COMMAND/MACRO
 ───────────────────   ────────────────────────────────────────

 <Escape>              MainMenu()

 <BackSpace>          mBackSpace()
 <Alt BackSpace>       Undo()
 <Ctrl BackSpace>      DelLeftWord()
 <AltShift BackSpace>  Redo()

 <Enter>              mCreturn()
 <Ctrl Enter>          ExecScrapMacro()

 <Tab>                mTabRight()
 <Shift Tab>          mTabLeft()

 <CtrlAlt Spacebar>    lVersion


 KEYPAD KEY            EDITOR COMMAND/MACRO
 ───────────────────   ────────────────────────────────────────

 <Ins>                 ToggleInsert()

 <CursorDown>          Down()
 <Ctrl CursorDown>     RollDown()

 <CursorLeft>          Left()
 <Ctrl CursorLeft>     WordLeft()

 <CursorRight>         Right()
 <Ctrl CursorRight>    WordRight()

 <CursorUp>            Up()
 <Ctrl CursorUp>       RollUp()

 <Del>                mDelChar()
 <Alt Del>             DelToEol()
 <Ctrl Del>            DelRightWord()

 <End>                 EndLine()
 <Ctrl End>            EndWindow()

 <Grey*>               Paste()
 <Ctrl Grey*>          Paste(_OVERWRITE_)
 <CtrlShift Grey*>     PasteFromWinClip()

 <Grey+>               Copy()
 <Ctrl Grey+>          Copy(_APPEND_)
 <CtrlShift Grey+>     CopyToWinClip()

 <Grey->               Cut()
 <Ctrl Grey->          Cut(_APPEND_)
 <CtrlShift Grey->     CutToWinClip()

 <Home>                BegLine()
 <Ctrl Home>           BegWindow()

 <PgDn>                PageDown()
 <Alt PgDn>           mNextPara()
 <Ctrl PgDn>          mEndFile()
 <Shift PgDn>         mNextPara()

 <PgUp>                PageUp()
 <Alt PgUp>           mPrevPara()
 <Ctrl PgUp>          mBegFile()
 <Shift PgUp>         mPrevPara()

 <Ctrl PrtSc>          Paste(_OVERWRITE_)


 MOUSE BUTTON          EDITOR COMMAND/MACRO
 ───────────────────   ────────────────────────────────────────

 <LeftBtn>            mLeftBtn()
 <Alt LeftBtn>         MouseMarking(_LINE_)
 <Ctrl LeftBtn>        MouseMarking(_COLUMN_)
 <Shift LeftBtn>      mTrackMouseCursor()

 <RightBtn>            MouseMenu()


 CONTROL KEY           EDITOR COMMAND/MACRO
 ───────────────────   ────────────────────────────────────────

 <Ctrl ->             mCopyCharAbove()
 <Ctrl 0>             mListRecentFiles()
 <Ctrl 2>              PlaceMark()
 <Ctrl 6>              GotoMark()
 <Ctrl 8>              ExecMacro("quote")
 <Ctrl =>             mFindWordAtCursor('b')
 <Ctrl [>              GotoBlockBegin()
 <Ctrl \>             mFindWordAtCursor('g')
 <Ctrl ]>              GotoBlockEnd()
 <Ctrl A>             mAsciiChart()
 <Ctrl B>              ExecMacro("nameclip Named ClipBoards")
 <Ctrl C>              GotoColumn()
 <Ctrl D>              DelLine()
 <Ctrl F>              Find()
 <Ctrl G>             mCompressView(1)
 <Ctrl I>              ExecMacro("isrch")
 <Ctrl J>              GotoLine()
 <Ctrl K><0>           PlaceMark("q")
 <Ctrl K><1>           PlaceMark("r")
 <Ctrl K><2>           PlaceMark("s")
 <Ctrl K><3>           PlaceMark("t")
 <Ctrl K><4>           PlaceMark("u")
 <Ctrl K><5>           PlaceMark("v")
 <Ctrl K><6>           PlaceMark("w")
 <Ctrl K><7>           PlaceMark("x")
 <Ctrl K><8>           PlaceMark("y")
 <Ctrl K><9>           PlaceMark("z")
 <Ctrl K><L>           FillBlock()
 <Ctrl K><Q>           QuitFile()
 <Ctrl K><S>           SaveFile()
 <Ctrl K><T>           MarkWord()
 <Ctrl K><X>           SaveAndQuitFile()
 <Ctrl K><Z>           KillFile()
 <Ctrl L>              RepeatFind()
 <Ctrl M>              RecordKeyMacro()
 <Ctrl N>              InsertLine()
 <Ctrl O><C>           CloseWindow()
 <Ctrl O><D>           DelWindow()
 <Ctrl O><G>           GotoWindow()
 <Ctrl O><H>           HWindow()
 <Ctrl O><N>           NextWindow()
 <Ctrl O><O>           OneWindow()
 <Ctrl O><P>           PrevWindow()
 <Ctrl O><R>           ResizeWindow()
 <Ctrl O><T>           ExecMacro("center")
 <Ctrl O><V>           VWindow()
 <Ctrl O><W>          mToggleWordWrap()
 <Ctrl O><Y>           ExecMacro("synchscr")
 <Ctrl O><Z>           ZoomWindow()
 <Ctrl P>              Literal()
 <Ctrl Q><0>           GotoMark("q")
 <Ctrl Q><1>           GotoMark("r")
 <Ctrl Q><2>           GotoMark("s")
 <Ctrl Q><3>           GotoMark("t")
 <Ctrl Q><4>           GotoMark("u")
 <Ctrl Q><5>           GotoMark("v")
 <Ctrl Q><6>           GotoMark("w")
 <Ctrl Q><7>           GotoMark("x")
 <Ctrl Q><8>           GotoMark("y")
 <Ctrl Q><9>           GotoMark("z")
 <Ctrl Q><I>          mToggleAutoIndent()
 <Ctrl Q><L>           RestoreCursorLine()
 <Ctrl Q><P>           PrevPosition()
 <Ctrl Q><Q>           RepeatCmd()
 <Ctrl R>              Replace()
 <Ctrl T>              DelRightWord()
 <Ctrl U>              GlobalUnDelete()
 <Ctrl V>              Toggle(LineDrawing)
 <Ctrl W>              ScrollUp()
 <Ctrl X>              ExecMacro()
 <Ctrl Y>              DelLine()
 <Ctrl Z>              ScrollDown()

 <CtrlShift 8>         ExecMacro("quote cmt")
 <CtrlShift L>         RepeatFind(_REVERSE_)


 ALT KEY               EDITOR COMMAND/MACRO
 ───────────────────   ────────────────────────────────────────

 <Alt ->              mCopyCharAboveToEol()
 <Alt 0>               ExecMacro("listopen")
 <Alt 1>               GotoWindow(1)
 <Alt 2>               GotoWindow(2)
 <Alt 3>               GotoWindow(3)
 <Alt 4>               GotoWindow(4)
 <Alt 5>               GotoWindow(5)
 <Alt 6>               GotoWindow(6)
 <Alt 7>               GotoWindow(7)
 <Alt 8>               GotoWindow(8)
 <Alt 9>               GotoWindow(9)
 <Alt =>              mFindWordAtCursor('+')
 <Alt A>               MarkStream()
 <Alt B>               ExecMacro("wrappara")
 <Alt C>               CopyBlock()
 <Alt D>               DelLine()
 <Alt E>               EditThisFile()
 <Alt F>               MainMenu('F')
 <Alt G>               DelBlock()
 <Alt I>               MarkChar()
 <Alt J>               JoinLine()
 <Alt K>               MarkColumn()
 <Alt L>               MarkLine()
 <Alt M>               MoveBlock()
 <Alt N>               NextFile()
 <Alt O>               ChangeCurrFilename()
 <Alt P>               PrevFile()
 <Alt R>               InsertFile()
 <Alt S>               SplitLine()
 <Alt T>               MainMenu("T")
 <Alt U>               UnMarkBlock()
 <Alt V>              mCompressView(0)
 <Alt W>               SaveBlock()
 <Alt X>               Exit()
 <ALT Y>               MarkToEOL()
 <Alt Z>               CopyBlock(_OVERWRITE_)

 <AltShift V>          ViewFinds()


 SHIFT KEY             EDITOR COMMAND/MACRO
 ───────────────────   ────────────────────────────────────────

 <}>                  mCloseBrace()





Appendix D:  Variables By Category

New variables added to version 4.4 are followed by "*".
Existing variables which are "Enhanced" for version 4.4 are followed by "**".

Blocks                     History                   SyntaxHilite
──────                     ───────                   ────────────
                                                     
BlockBegCol                CurrHistoryList           Directive1Attr
BlockBegLine               MaxHistoryPerList         Directive2Attr
BlockEndCol                PersistentHistory         Directive3Attr
BlockEndLine               MaxHistorySize            
BlockId                                              KeyWords1Attr
                           Keyboard                  KeyWords2Attr
ClipBoardId                ────────                  KeyWords3Attr
InsertLineBlocksAbove                                KeyWords4Attr
Marking                    EquateEnhancedKbd         KeyWords5Attr
UnMarkAfterPaste                                     KeyWords6Attr
UseCurrLineIfNoBlock       Key                       KeyWords7Attr
                           LastKey                   KeyWords8Attr
BlockAttr                                            KeyWords9Attr
CursorInBlockAttr          KbdMacroRecording         
                           KbdMacroRunning           MultiLnDlmt1Attr
Colors                                               MultiLnDlmt2Attr
──────                     Line Drawing              MultiLnDlmt3Attr
                           ────────────              SingleLnDlmt1Attr
BlockAttr                                            SingleLnDlmt2Attr
CurrWinBorderAttr          LineDrawChar              SingleLnDlmt3Attr
CursorAttr                 LineDrawing               ToEOL1Attr
CursorInBlockAttr          LineDrawType              ToEOL2Attr
EOFMarkerAttr                                        ToEOL3Attr
HelpBoldAttr               Macros                    Quote1Attr
HelpInfoAttr               ──────                    Quote2Attr
HelpLinkAttr                                         Quote3Attr
HelpSelectAttr             IdleTime                  IncompleteQuoteAttr
HelpTextAttr               MacroCmdLine              
HiLiteAttr                                           NumberAttr
LineNumbersAttr *          Menus                     
MenuBorderAttr             ─────                     ShowSyntaxHilite
MenuGrayAttr                                         
MenuSelectAttr             MenuBorderAttr            System Interface
MenuSelectGrayAttr         MenuGrayAttr              ────────────────
MenuSelectLtrAttr          MenuSelectAttr            
MenuTextAttr               MenuSelectGrayAttr        Beep
MenuTextLtrAttr            MenuSelectLtrAttr         ChangeShellPrompt
MsgAttr                    MenuTextAttr              DosCmdLine
OtherWinBorderAttr         MenuTextLtrAttr           EquateEnhancedKbd
StatusLineAttr             ShowMainMenu              FileLocking
TextAttr                                             IdleTime
                           Miscellaneous             KbdPath
Directive1Attr             ─────────────             KeepUndoBeyondSave
Directive2Attr                                       KeepWinOnTop *
Directive3Attr             Break                     Key
IncompleteQuoteAttr        GUIStartupFlags           LastKey
KeyWords1Attr              KillMax                   LoadWildFromDOS
KeyWords2Attr              MaxHistorySize            LoadWildFromInside
KeyWords3Attr              MaxRecentFiles            MacroCmdLine
KeyWords4Attr              MsgLevel                  PickFileChangesDir
KeyWords5Attr              PersistentRecentFiles     SingleInstance *
KeyWords6Attr              SaveState                 TSEPath
KeyWords7Attr              StartupFlags              UseCommonDialogs
KeyWords8Attr              TemplateExpansion         
KeyWords9Attr                                        Tabs
MultiLnDlmt1Attr           Mouse                     ────
MultiLnDlmt2Attr           ─────                     
MultiLnDlmt3Attr                                     CursorTabWidth
NumberAttr                 LastMouseKey              DetabOnLoad
Quote1Attr                 LastMouseX                EntabOnSave
Quote2Attr                 LastMouseY                ExpandTabs
Quote3Attr                 MouseEnabled              TabType
SingleLnDlmt1Attr          MouseHoldTime             TabShiftsBlock
SingleLnDlmt2Attr          MouseKey                  TabWidth
SingleLnDlmt3Attr          MouseRepeatDelay          VarTabs
ToEOL1Attr                 MouseX                    ZeroBasedTab
ToEOL2Attr                 MouseY                    
ToEOL3Attr                                           Video Display
                           PickFile                  ─────────────
Attr                       ────────                  
                                                     CurrVideoMode
Date/Time                  PickFileFlags             CurrWinBorderType
─────────                  PickFileSortOrder         Cursor
                           PickFileChangesDir        DisplayBoxed
DateFormat                                           InsertCursorSize
DateSeparator              Printing                  OtherWinBorderType
TimeFormat                 ────────                  OverwriteCursorSize
TimeSeparator                                        PopWinCols
                           PrintBotMargin            PopWinRows
Files/Buffers              PrintCopies               PopWinX1
─────────────              PrintFirstPage            PopWinY1
                           PrinterFontFlags          StartupVideoMode
BackupExt                  PrinterFontName           Transparency *
BackupPath                 PrinterFontSize           WindowX1
BufferFlags                PrintFooter               WindowY1
DefaultExt                 PrintHeader               X1
EOFType                    PrintLastPage             Y1
EOLType                    PrintLeftMargin           
FileLocking                PrintLineNumbers          ScreenCols
LoadWildFromDOS            PrintLineSpacing          ScreenRows
LoadWildFromInside         PrintLinesPerPage         WindowCols
MakeBackups                PrintPause                WindowRows
ProtectedSaves             PrintRightMargin          
QuitToPrompt               PrintTopMargin            ShowEOFMarker
                           PrintUseScreenFont        ShowHelpLine
Find/Replace                                         ShowLineNumbers *
────────────               StatusLine                
                           ──────────                FontFlags
CenterFinds                                          FontName
FindOptions                ShowStatusLine            FontSize
ReplaceOptions             StatusLineAtTop           SpecialEffects **
ViewFindsId                StatusLineFillChar        
                           StatusLineRow             Word Processing
Help                       StatusLineUpdating        ───────────────
────                                                 
                                                     AutoIndent
HelpBoldAttr                                         Insert
HelpInfoAttr                                         LeftMargin
HelpItalicsAttr                                      ParaEndStyle
HelpLinkAttr                                         RemoveTrailingWhite
HelpSelectAttr                                       ReturnEqNextLine
HelpTextAttr                                         RightMargin
                                                     WordSet
HelpLineDelay                                        WordWrap
ShowHelpLine                                         
                                                     
                                                     





Appendix E:  Command Implementation

════════════════════════════════════════════════════════════════════════════════

The table in this appendix provides a cross-reference between the editing
commands as documented in the User's Guide (first column of the table), and
the actual native command or enhanced macro by which the editing command is
implemented in the editor (second column of the table).

Editing commands are implemented in a number of ways:

    1.  By invoking a native command without any parameters.  Most of these
        commands have the same name as the editing command, and are indicated
        as the command name followed by "()".  For example, the AddLine
        command described in the User's Guide is implemented as the native
        AddLine() command itself.

        Certain editing commands invoke native commands with different names.
        For example, the Again command is implemented as the native
        RepeatFind() command.

    2.  By invoking a native command that specifies a particular parameter
        for that command.  These are indicated by a value in "()" following
        the command under the second column of the table.  For example, the
        "OverlayColumnBlock" command is implemented via the native
        CopyBlock() command using the parameter "_OVERWRITE_", as
        "CopyBlock(_OVERWRITE_)".

    3.  By invoking either a macro which enhances the behavior of a native
        command, or a macro that provides additional features not included in
        the native commands.  Generally, these are indicated by a macro name
        beginning with an "m" under the second column of the table.  For
        example, the BackSpace command is implemented via a macro named
        "mBackSpace()", which enhances the native BackSpace command; and the
        CompressView command is provided through the mCompressView() macro,
        which is composed of a number of native commands.

        A number of commands are implemented via a macro that specifies a
        particular parameter.  For example, the FunctionList command is
        implemented via the "mCompressView()" macro using the parameter "1",
        as "mCompressView(1)".

        Certain editing commands are implemented via a group of macros in an
        external macro file.  Each of these is indicated by identifying the
        name of the macro file.  For example, the SpellCheck command is
        implemented via a group of macros in the external macro file
        "SPELLCHK.MAC".

        For most commands implemented as macros, the macro source can be
        found (under the indicated macro name) either in the standard SemWare
        Editor Professional user-interface macro file, TSE.UI (located in the
        UI\ editor subdirectory), or in a macro source file in the MAC\
        editor subdirectory.

 ┌──────────────────────────────────────┬────────────────────────────────────┐
 │ Editing Command                      │ Native Command or Enhanced Macro   │
 ├──────────────────────────────────────┼────────────────────────────────────┤
 │ AddLine                              │  AddLine()                         │
 │ Again                                │  RepeatFind()                      │
 │ AgainReverse                         │  RepeatFind(_REVERSE_)             │
 │ AsciiChart                           │ mAsciiChart()                      │
 │ AutoLoadList                         │  EditAutoLoadList()                │
 │ BackSpace                            │ mBackSpace()                       │
 │ BegFile                              │ mBegFile()                         │
 │ BegLine                              │  BegLine()                         │
 │ BegPara                              │ mBegPara                           │
 │ BegWindow                            │  BegWindow()                       │
 │ Book                                 │  external macro file: BOOK.MAC     │
 │ Capitalize                           │  external macro file: CAPITAL.MAC  │
 │ CaptureDosOutput                     │  external macro file: CAPTURE.MAC  │
 │ cCloseCurlyBrace                     │ mCloseBrace()                      │
 │ CD                                   │  external macro file: CD.MAC       │
 │ CenterLine                           │  external macro file: CENTER.MAC   │
 │ ChangeCurrFilename                   │  ChangeCurrFilename()              │
 │ ChangeVideoMode                      │  external macro file: VIDEO.MAC    │
 │ CloseFileAndWindow                   │ mCloseFileAndWindow()              │
 │ CloseWindow                          │  CloseWindow()                     │
 │ CmpFiles                             │  external macro file: CMPFILES.MAC │
 │ Compile                              │  external macro file: COMPILE.MAC  │
 │ CompileCurrFile                      │ mCompileCurrFile()                 │
 │ CompressView                         │ mCompressView(0)                   │
 │ Copy to a Named ClipBoard            │  external macro file: NAMECLIP.MAC │
 │ Copy to the System ClipBoard         │  Copy()                            │
 │ CopyAppend to a Named ClipBoard      │  external macro file: NAMECLIP.MAC │
 │ CopyAppend to the System ClipBoard   │  CopyAppend()                      │
 │ CopyBlock                            │  CopyBlock()                       │
 │ CopyCharAbove                        │ mCopyCharAbove()                   │
 │ CopyCharAboveToEol                   │ mCopyCharAboveToEol()              │
 │ CopyToWinClip                        │  CopyToWinClip()                   │
 │ CReturn                              │ mCReturn()                         │
 │ CUAMark                              │  external macro file: CUAMARK.MAC  │
 │ Cut to a Named ClipBoard             │  external macro file: NAMECLIP.MAC │
 │ Cut to the System ClipBoard          │  Cut()                             │
 │ CutAppend to a Named ClipBoard       │  external macro file: NAMECLIP.MAC │
 │ CutAppend to the System ClipBoard    │  CutAppend()                       │
 │ DateTimeStamp                        │ mDateTimeStamp()                   │
 │ DebugCurrFile                        │ mDebugCurrFile()                   │
 │ DebugMacro                           │  external macro file: DEBUG.MAC    │
 │ DelBlock                             │  DelBlock()                        │
 │ DelChar                              │ mDelChar()                         │
 │ DelLeftWord                          │  DelLeftWord()                     │
 │ DelLine                              │  DelLine()                         │
 │ DelRightWord                         │  DelRightWord()                    │
 │ DelToEol                             │  DelToEol()                        │
 │ DelWindow                            │  DelWindow()                       │
 │ Dos                                  │  Dos()                             │
 └──────────────────────────────────────┴────────────────────────────────────┘

 ┌──────────────────────────────────────┬────────────────────────────────────┐
 │ Editing Command                      │ Native Command or Enhanced Macro   │
 ├──────────────────────────────────────┼────────────────────────────────────┤
 │ Down                                 │  Down()                            │
 │ DupLine                              │  DupLine()                         │
 │ EditFile                             │  EditFile()                        │
 │ EndFile                              │ mEndFile()                         │
 │ EndLine                              │  EndLine()                         │
 │ EndPara                              │ mEndPara()                         │
 │ EndWindow                            │  EndWindow()                       │
 │ ExecMacro                            │  ExecMacro()                       │
 │ ExecScrapMacro                       │  ExecScrapMacro()                  │
 │ Exit                                 │  Exit()                            │
 │ FileManager                          │  external macro file: F.MAC        │
 │ FillBlock                            │  FillBlock()                       │
 │ Find                                 │  Find()                            │
 │ FindAndDo                            │  external macro file: FIND&DO.MAC  │
 │ FindWordAtCursor                     │ mFindWordAtCursor('+')             │
 │ FindWordAtCursorBackwards            │ mFindWordAtCursor('b')             │
 │ FindWordAtCursorGlobally             │ mFindWordAtCursor('g')             │
 │ Flip                                 │ mFlip()                            │
 │ FunctionList                         │ mCompressView(1)                   │
 │ GlobalUnDelete                       │  GlobalUnDelete()                  │
 │ GotoBlockBegin                       │  GotoBlockBegin()                  │
 │ GotoBlockEnd                         │  GotoBlockEnd()                    │
 │ GotoColumn                           │  GotoColumn()                      │
 │ GotoLine                             │  GotoLine()                        │
 │ GotoMark                             │  GotoMark()                        │
 │ GotoWindow                           │  GotoWindow()                      │
 │ GotoWindowNumber                     │  GotoWindow(n)                     │
 │ Help                                 │  Help()                            │
 │ HelpOnKeyAssignments                 │  Help("Key Assignments")           │
 │ HelpOnWordAtCursor                   │ mHelpOnWordAtCursor()              │
 │ HWindow                              │  HWindow()                         │
 │ IncrementalSearch                    │  external macro file: ISRCH.MAC    │
 │ InsertFile                           │  InsertFile()                      │
 │ InsertLine                           │  InsertLine()                      │
 │ JoinLine                             │  JoinLine()                        │
 │ Justify                              │  external macro file: JUSTIFY.MAC  │
 │ KillFile                             │  KillFile()                        │
 │ Left                                 │  Left()                            │
 │ ListOpenFiles                        │  external macro file: LISTOPEN.MAC │
 │ ListRecentFiles                      │ mListRecentFiles()                 │
 │ Literal                              │  Literal()                         │
 │ LoadKeyMacro                         │  LoadKeyMacro()                    │
 │ LoadMacro                            │  LoadMacro()                       │
 │ Lower                                │ mLower()                           │
 │ MainMenu                             │  MainMenu()                        │
 │ MarkChar                             │  MarkChar()                        │
 │ MarkColumn                           │  MarkColumn()                      │
 └──────────────────────────────────────┴────────────────────────────────────┘

 ┌──────────────────────────────────────┬────────────────────────────────────┐
 │ Editing Command                      │ Native Command or Enhanced Macro   │
 ├──────────────────────────────────────┼────────────────────────────────────┤
 │ MarkLine                             │  MarkLine()                        │
 │ MarkParagraph                        │ mMarkPara()                        │
 │ MarkStream                           │  MarkStream()                      │
 │ MarkToEOL                            │  MarkToEOL()                       │
 │ MarkWord                             │  MarkWord()                        │
 │ Match                                │  external macro file: MATCH.MAC    │
 │ MouseMenu                            │  MouseMenu()                       │
 │ MoveBlock                            │  MoveBlock()                       │
 │ NewFile                              │  NewFile()                         │
 │ NextChar                             │  NextChar()                        │
 │ NextFile                             │  NextFile()                        │
 │ NextPara                             │ mNextPara()                        │
 │ NextWindow                           │  NextWindow()                      │
 │ OneWindow                            │  OneWindow()                       │
 │ OpenFileAndWindow                    │ mOpenFileAndWindow()               │
 │ Overlay                              │  external macro file: OVERLAY.MAC  │
 │ OverlayColumnBlock                   │  CopyBlock(_OVERWRITE_)            │
 │ PageDown                             │  PageDown()                        │
 │ PageUp                               │  PageUp()                          │
 │ Paste from a Named ClipBoard         │  external macro file: NAMECLIP.MAC │
 │ Paste from the System ClipBoard      │  Paste()                           │
 │ PasteFromWinClip                     │  PasteFromWinClip()                │
 │ PasteOver from a Named ClipBoard     │  external macro file: NAMECLIP.MAC │
 │ PasteOver from the System ClipBoard  │  Paste(_OVERWRITE_)                │
 │ PasteUnDelete                        │  PasteUnDelete()                   │
 │ PlaceMark                            │  PlaceMark()                       │
 │ Potpourri                            │  external macro file: POTPOURR.MAC │
 │ PrevChar                             │  PrevChar()                        │
 │ PrevFile                             │  PrevFile()                        │
 │ PrevHelp                             │  PrevHelp()                        │
 │ PrevPara                             │ mPrevPara()                        │
 │ PrevPosition                         │  PrevPosition()                    │
 │ PrevWindow                           │  PrevWindow()                      │
 │ PrintBlock                           │  external macro file: PRINT.MAC    │
 │ PrintFile                            │  external macro file: PRINT.MAC    │
 │ PurgeKeyMacro                        │  PurgeKeyMacro()                   │
 │ PurgeMacro                           │  PurgeMacro()                      │
 │ QuitFile                             │  QuitFile()                        │
 │ QuoteLine                            │  external macro file: QUOTE.MAC    │
 │ RecordKeyMacro                       │  RecordKeyMacro()                  │
 │ RedisplayViewPickList                │  ViewFinds()                       │
 │ RepeatCmd                            │  RepeatCmd()                       │
 │ Replace                              │  Replace()                         │
 │ ReplaceFile                          │  ReplaceFile()                     │
 │ ResizeWindow                         │  ResizeWindow()                    │
 │ RestoreCursorLine                    │  RestoreCursorLine()               │
 │ Right                                │  Right()                           │
 │ RollDown                             │  RollDown()                        │
 └──────────────────────────────────────┴────────────────────────────────────┘

 ┌──────────────────────────────────────┬────────────────────────────────────┐
 │ Editing Command                      │ Native Command or Enhanced Macro   │
 ├──────────────────────────────────────┼────────────────────────────────────┤
 │ RollLeft                             │  RollLeft()                        │
 │ RollRight                            │  RollRight()                       │
 │ RollUp                               │  RollUp()                          │
 │ SaveAllAndExit                       │  SaveAllAndExit()                  │
 │ SaveAllFiles                         │  SaveAllFiles()                    │
 │ SaveAndQuitFile                      │  SaveAndQuitFile()                 │
 │ SaveAs                               │  SaveAs()                          │
 │ SaveBlock                            │  SaveBlock()                       │
 │ SaveFile                             │  SaveFile()                        │
 │ SaveKeyMacro                         │  SaveKeyMacro()                    │
 │ ScrollDown                           │  ScrollDown()                      │
 │ ScrollToCenter                       │  ScrollToCenter()                  │
 │ ScrollToTop                          │  ScrollToTop()                     │
 │ ScrollUp                             │  ScrollUp()                        │
 │ Shell                                │  Shell()                           │
 │ Shift                                │ mShift()                           │
 │ ShiftLeft                            │ mShiftBlock(SHIFTLEFT)             │
 │ ShiftRight                           │ mShiftBlock(SHIFTRIGHT)            │
 │ ShowEntryScreen                      │  ShowEntryScreen()                 │
 │ ShowFileInfo                         │  external macro file: FILEINFO.MAC │
 │ Sort                                 │  external macro file: SORT.MAC     │
 │ SpellCheck                           │  external macro file: SPELLCHK.MAC │
 │ SplitLine                            │  SplitLine()                       │
 │ SwapLines                            │ mSwapLines()                       │
 │ TabLeft                              │ mTabLeft()                         │
 │ TabRight                             │ mTabRight()                        │
 │ ToggleAutoIndent                     │ mToggleAutoIndent()                │
 │ ToggleHexView                        │ mToggleHexView()                   │
 │ ToggleInsert                         │  ToggleInsert()                    │
 │ ToggleLineDrawing                    │  Toggle(LineDrawing)               │
 │ ToggleSyncScroll                     │  external macro file: SYNCHSCR.MAC │
 │ ToggleTemplateExpansion              │ mToggleTemplateExpand()            │
 │ ToggleWordWrap                       │ mToggleWordWrap()                  │
 │ UnDelete                             │  UnDelete()                        │
 │ UnMarkBlock                          │  UnMarkBlock()                     │
 │ Up                                   │  Up()                              │
 │ Upper                                │ mUpper()                           │
 │ VWindow                              │  VWindow()                         │
 │ Where                                │  external macro file: WHERE.MAC    │
 │ WordLeft                             │  WordLeft()                        │
 │ WordRight                            │  WordRight()                       │
 │ WrapPara                             │ mWrapPara()                        │
 │ ZoomWindow                           │  ZoomWindow()                      │
 └──────────────────────────────────────┴────────────────────────────────────┘





Appendix F:  Standard Configuration Settings

This appendix provides the standard settings for the configuration options
(variables) in the editor.  The variable name is identified on the left,
with the standard setting indicated to the right of the variable name.


┌──────────────────────────────────────────────────────────────────┐
│                       System/File Options                        │
└──────────────────────────────────────────────────────────────────┘

 TSEPath                 = ""
 KbdPath                 = ""
 StartUpFlags            = _STARTUP_MENU_
 GUIStartUpFlags         = _USE_DEFAULT_WIN_POS_|_USE_LAST_SAVED_FONT_|_USE_LAST_SAVED_WIN_SIZE_
 SingleInstance          = Off
 DefaultExt              = "ui s si c cpp h java pas inc bat prg txt doc html asm"
 FileLocking             = _NONE_
 LoadWildFromDos         = On
 LoadWildFromInside      = Off
 PickFileChangesDir      = Off
 PickFileFlags           = _ADD_DIRS_ | _ADD_SLASH_ | _DIRS_AT_TOP_
 PickFileSortOrder       = "f"
 EOLType                 = 0         // 0=As Loaded, 1=^M (CR), 2=^J (LF), 3=^M^J (CR/LF)
 EOFType                 = 2         // 0=nothing, 1=^Z, 2=EOLType, 3=EOLType+^Z
 MakeBackups             = On
 ProtectedSaves          = On
 BackupExt               = ".bak"
 BackupPath              = ""
 SaveState               = Off
 UseCommonDialogs        = Off

┌──────────────────────────────────────────────────────────────────┐
│                      Keyboard/Mouse Options                      │
└──────────────────────────────────────────────────────────────────┘

 EquateEnhancedKBD       = On
 MouseHoldTime           = 9     // 18 approx 1 sec
 MouseRepeatDelay        = 0

┌──────────────────────────────────────────────────────────────────┐
│                      Command/Format Options                      │
└──────────────────────────────────────────────────────────────────┘

 MaxHistoryPerList       = 50
 MaxHistorySize          = 1000
 PersistentHistory       = On
 MaxRecentFiles          = 200
 PersistentRecentFiles   = On
 WordSet                 = ChrSet("0-9A-Z_a-z")
 FindOptions             = "I"
 ReplaceOptions          = ""
 CenterFinds             = Off
 Beep                    = On
 ChangeShellPrompt       = On
 QuitToPrompt            = Off
 KeepUndoBeyondSave      = Off
 DateFormat              = 4     // 1=MM/DD/YY, 2=DD/MM/YY, 3=YY/MM/DD, 4=MM/DD/YYYY, 5=DD/MM/YYYY, 6=YYYY/MM/DD
 DateSeparator           = Asc('/')
 TimeFormat              = 2     // 1=24 hr (HH:MM:SS), 2=12 hr (HH:MM am/pm)
 TimeSeparator           = Asc(':')

┌──────────────────────────────────────────────────────────────────┐
│                     Text Entry/Block Options                     │
└──────────────────────────────────────────────────────────────────┘

 Insert                  = On
 AutoIndent              = On
 WordWrap                = Off
 TemplateExpansion       = Off
 ParaEndStyle            = Off
 ReturnEqNextLine        = Off
 RemoveTrailingWhite     = On
 LineDrawType            = 1         // 1=┌─┐, 2=╒═╕, 3=╓─╖, 4=╔═╗, 5=ASCII, 6=Eraser, 7=User
 LineDrawChar            = Asc('▪')  // used when LineDrawType == 7
 InsertLineBlocksAbove   = Off
 UseCurrLineIfNoBlock    = Off
 UnMarkAfterPaste        = On
 TabShiftsBlock          = Off

┌──────────────────────────────────────────────────────────────────┐
│                        Tab/Margin Options                        │
└──────────────────────────────────────────────────────────────────┘

 TabType                 = _SOFT_
 TabWidth                = 8
 CursorTabWidth          = 0
 ZeroBasedTab            = Off
 VarTabs                 = TabSet("4 8 16 24 40")
 ExpandTabs              = On
 DetabOnLoad             = Off
 EntabOnSave             = Off
 LeftMargin              = 0
 RightMargin             = 72

┌──────────────────────────────────────────────────────────────────┐
│                      Display/Color Options                       │
└──────────────────────────────────────────────────────────────────┘

 StatusLineAtTop         = On
 StatusLineFillChar      = Asc(' ')
 ShowMainMenu            = On
 ShowHelpLine            = On
 HelpLineDelay           = 6
 CurrWinBorderType       = 2     // 1=┌─┐, 2=╒═╕, 3=╓─╖, 4=╔═╗, 5=▐▀▌, 6=█▀█ 7=ASCII 8=3D
 OtherWinBorderType      = 2     // 1=┌─┐, 2=╒═╕, 3=╓─╖, 4=╔═╗, 5=▐▀▌, 6=█▀█ 7=ASCII 8=3D
 DisplayBoxed            = 1     // 0=Never, 1=Mouse, 2=Always
 SpecialEffects          = _USE_3D_CHARS_|_DRAW_SHADOWS_
 Transparency            = 0
 KeepWinOnTop            = Off
 InsertCursorSize        = 4     // 0=no cursor, 1..8=cursor size, 9=vertical bar
 OverwriteCursorSize     = 2     // 0=no cursor, 1..8=cursor size, 9=vertical bar
 ShowEOFMarker           = On
 ShowLineNumbers         = Off
 StartupVideoMode        = _AUTO_DETECT_
 WinPosLeft              = 0
 WinPosTop               = 0
 ShowSyntaxHilite        = On
 FontName                = "Courier New"
 FontSize                = 10        // Point Size
 FontFlags               = _NONE_

┌──────────────────────────────────────────────────────────────────┐
│                            Attributes                            │
└──────────────────────────────────────────────────────────────────┘

 CurrWinBorderAttr       = Color(Intense Black on White)
 OtherWinBorderAttr      = Color(Intense Blue on White)
 MenuTextAttr            = Color(Black on White)
 MenuTextLtrAttr         = Color(Red on White)
 MenuGrayAttr            = Color(Bright Black on White)
 MenuSelectGrayAttr      = Color(White on Blue)
 MenuBorderAttr          = Color(Black on White)
 MenuSelectAttr          = Color(Bright White on Blue)
 MenuSelectLtrAttr       = Color(Bright Red on Blue)
 BlockAttr               = Color(Bright White on Black)
 CursorInBlockAttr       = Color(Black on White)
 CursorAttr              = Color(Intense Black on Cyan)
 HiLiteAttr              = Color(Red on White)
 TextAttr                = Color(Intense Black on White)
 EOFMarkerAttr           = Color(Black on White)
 MsgAttr                 = Color(Black on White)
 StatusLineAttr          = Color(Bright White on Blue)
 LineNumbersAttr         = Color(Black on White)

┌──────────────────────────────────────────────────────────────────┐
│                         Help Attributes                          │
└──────────────────────────────────────────────────────────────────┘

 HelpInfoAttr            = Color(Bright Green on Blue)
 HelpLinkAttr            = Color(Bright Yellow on Blue)
 HelpSelectAttr          = Color(Blue on White)
 HelpBoldAttr            = Color(Bright White on Blue)
 HelpItalicsAttr         = Color(Bright Magenta on Blue)
 HelpTextAttr            = Color(White on Blue)

┌──────────────────────────────────────────────────────────────────┐
│                     SyntaxHilite Attributes                      │
└──────────────────────────────────────────────────────────────────┘

 IncompleteQuoteAttr     = Color(Intense Black on Red)
 NumberAttr              = Color(Intense Magenta on White)
 Directive1Attr          = Color(Intense Red on White)
 Directive2Attr          = Color(Intense Red on White)
 Directive3Attr          = Color(Intense Red on White)
 MultiLnDlmt1Attr        = Color(Intense Green on White)
 MultiLnDlmt2Attr        = Color(Intense Green on White)
 MultiLnDlmt3Attr        = Color(Intense Green on White)
 SingleLnDlmt1Attr       = Color(Intense Green on White)
 SingleLnDlmt2Attr       = Color(Intense Green on White)
 SingleLnDlmt3Attr       = Color(Intense Green on White)
 Quote1Attr              = Color(Intense Magenta on White)
 Quote2Attr              = Color(Intense Magenta on White)
 Quote3Attr              = Color(Intense Magenta on White)
 ToEOL1Attr              = Color(Intense Green on White)
 ToEOL2Attr              = Color(Intense Green on White)
 ToEOL3Attr              = Color(Intense Green on White)
 KeyWords1Attr           = Color(Intense Bright Blue on White)
 KeyWords2Attr           = Color(Intense Yellow on White)
 KeyWords3Attr           = Color(Intense Bright Magenta on White)
 KeyWords4Attr           = Color(Intense Bright Red on White)
 KeyWords5Attr           = Color(Intense Cyan on White)
 KeyWords6Attr           = Color(Intense Cyan on White)
 KeyWords7Attr           = Color(Intense Bright Blue on White)
 KeyWords8Attr           = Color(Intense Bright Blue on White)
 KeyWords9Attr           = Color(Intense Bright Blue on White)

┌──────────────────────────────────────────────────────────────────┐
│                       Print Output Options                       │
└──────────────────────────────────────────────────────────────────┘

 PrintLeftMargin         = 0
 PrintRightMargin        = 0
 PrintLinesPerPage       = 0
 PrintTopMargin          = 0
 PrintBotMargin          = 0
 PrintLineSpacing        = 1         // 1=Single, 2=Double, 3=Triple, etc...
 PrintLineNumbers        = Off
 PrintHeader             = ""        // F=FileName, D=Date, T=Time, P=Page
 PrintFooter             = ""        // F=FileName, D=Date, T=Time, P=Page
 PrintFirstPage          = 0
 PrintLastPage           = 0
 PrintCopies             = 1
 PrintPause              = Off
 PrintUseScreenFont      = On
 PrinterFontName         = "Courier New"
 PrinterFontSize         = 10        // Point Size
 PrinterFontFlags        = _NONE_





Appendixes

             ┌───────────────── User's Guide ────────────────┐
             │                                               │
             │  Appendix A:  Technical Specifications        │
             │  Appendix C:  Standard Key Assignments        │
             │  Appendix E:  Command Implementation          │
             │  Appendix F:  Standard Configuration Settings │
             │                                               │
             ├──────────── Macro Reference Guide ────────────┤
             │                                               │
             │  Appendix B:  Command Implementation          │
             │  Appendix C:  Commands by Category            │
             │  Appendix D:  Variables by Category           │
             │                                               │
             └───────────────────────────────────────────────┘





Asc()

Returns the ASCII integer value for a single character.

Syntax:     INTEGER Asc(STRING s)

            • s is the single character whose ASCII value is returned.

Returns:    The ASCII integer value of the character passed to it.

Notes:      If more than a single character is passed, the first character of
            that string is used.

Examples:

            i = Asc("a")            // i is 97

            i = Asc("def")          // i is 100

See Also:   Chr(), Str(), Val()





Ask()

Allows a macro to get string input from the user.

Syntax:     INTEGER Ask(STRING prompt, VAR STRING reply [, INTEGER
                        history_number])

            • prompt is a string expression by which the user is prompted.

            • reply is a string variable where the reply is placed.

            • history_number is an optional integer specifying which
              history list to use.

Returns:    Non-zero if terminated by pressing <Enter>; zero (FALSE) if
            terminated by pressing <Escape>.

Notes:      Prompts the user with prompt, and stores the user input in
            reply.  reply must be initialized in the macro before Ask() is
            called.

            The contents of reply will be displayed at the prompt, as the
            default initial value.  The displayed value can be edited by the
            user, just like prompts issued by other commands (such as the
            EditFile() or Find() commands).  If reply is set to the empty
            string (""), the initial value displayed will be the last history
            entry, if history is specified; or blank, if history is not
            specified (or if there is no previous history).

Examples:

            proc foo()
                integer ok
                string fn[65] = ""          // Initialize reply

                ok = Ask("File to edit:", fn)
                if ok and Length(fn) > 0    // if ok and
                    EditFile(fn)            // something was entered
                endif
            end

            Using the Boolean nature of Ask() and Length(), the following
            shortcut can be used:

            string fn[65] = ""
            if Ask("File to edit:", fn) and Length(fn)
                EditFile(fn) // If fn was entered, and its length > 0
            endif

            // A macro to go to a line and a column...
            proc GotoLineColumn()
                string reply[20] = ''
                integer line, p

                if Ask("Goto line,col:", reply) and Length(reply)
                    line = Val(reply) //Val stops on first non-numeric
                    if line
                        GotoLine(line)
                    endif
                    p = Pos(',', reply)
                    if p
                        GotoColumn(Val(
                            SubStr(reply, p + 1, Length(reply) - p)))
                    endif
                endif
            end

See Also:   GetKey(), Read(), AddHistoryStr(), AskFilename(),
            AskNumeric()





AskFilename()

Allows a macro to get a filename from the user, with filename completion.

Syntax:     INTEGER AskFilename(STRING prompt, VAR STRING fn
                                [, INTEGER flags [, INTEGER history_number]])

            • prompt is a string expression by which the user is prompted.

            • fn is a string variable where the reply is placed.

            • flags is an optional integer that can be used to modify the
              behavior of this command.  Valid flags are:

              • _FULL_PATH_ instructs the editor to perform ExpandPath()
                on fn.  The results of this are returned, rather than the
                actual fn as entered by the user.

              • _MUST_EXIST_ specifies that fn must be an existing file.
                If fn does not exist, AskFilename() will issue a warning
                message, and prompt again.  For example, LoadMacro() calls
                AskFilename() with this flag, because a macro must exist on
                disk in order to be loaded.

              • _WRITE_ACCESS_ specifies that if fn is an existing file, it
                must not be READ ONLY.  For example, SaveAs() calls
                AskFilename() with this flag, because SaveAs() must be able to
                write to the selected file if it exists.

              Multiple flags can be specified.  To do so, use the bitwise
              logical OR (|) operator.  For example, to specify all three
              flags:

              _FULL_PATH_ | _MUST_EXIST_ | _WRITE_ACCESS_history_number is an optional integer specifying which
              history list to use.

Returns:    Non-zero if terminated by pressing <Enter>; zero (FALSE) if
            terminated by pressing <Escape>.

Notes:      Prompts the user with prompt, and stores the user input in fn.
            You must initialize fn before AskFilename() is called.

            The contents of fn will be displayed at the prompt, as the
            default initial value.  The displayed value can be edited by the
            user, just like prompts issued by other commands (such as the
            EditFile() or Find() commands).  If fn is set to the empty string
            (""), the initial value displayed will be the last history entry,
            if history is specified; or blank, if history is not specified
            (or if there is no previous history).

            This command supports the "Search SubDirs" (-s) option to obtain
            a PickList of all files in the indicated directory and all
            associated subdirectories, that match the filename
            specification.  (For more information on the "Search SubDirs"
            option, see "Command-Line Options" in the chapter on
            "Starting the Editor" in the User's Guide.)

            This command is similar to the Ask() command, and in fact,
            calls Ask() to do the actual work of gathering user input.
            Additionally, AskFilename() allows filename completion (if <Tab>
            is pressed), removes leading and trailing white space from the
            returned fn, and can perform additional tasks depending on the
            value of the flag parameter.

            The editor uses AskFilename() to prompt for files in many
            commands, including InsertFile(), SaveAs(), LoadMacro(),
            ReplaceFile(), ChangeCurrfilename(), and LoadKeyMacro().

Examples:

            string fn[65] = ""          // Initialize reply

            if AskFilename("File to edit:", fn) and Length(fn)
                EditFile(fn) // If fn was entered, and its length > 0
            endif

See Also:   GetKey(), Read(), AddHistoryStr(), Ask(), ExpandPath()





AskNumeric()

Allows a macro to get numeric string input from the user.

Syntax:     INTEGER AskNumeric(STRING prompt, VAR STRING reply
                               [, INTEGER history_number])

            • prompt is a string expression by which the user is prompted.

            • reply is a string variable where the reply is placed.  Only
              numeric (0-9, +,-) input is accepted.

            • history_number is an optional integer specifying which history
              list to use.

Returns:    Non-zero if terminated by pressing <Enter>; zero (FALSE) if
            terminated by pressing <Escape>.

Notes:      Prompts the user with prompt, and stores the user input in reply.
            You must initialize reply before AskNumeric() is called.

            The contents of reply will be displayed at the prompt, as the
            default initial value.  The displayed value can be edited by the
            user, just like prompts issued by other commands (such as the
            GotoLine() or GotoColumn() commands).  If reply is set to the
            empty string (""), the initial value displayed will be the last
            history entry, if history is specified; or blank, if history is
            not specified (or if there is no previous history).

            This command is similar to the Ask() command; however,
            AskNumeric() forces user input to be numeric.

Examples:

            // A macro to go to a line.
            proc mGotoLine()
                string reply[10] = ''
                integer line

                if AskNumeric("Goto line:", reply) and Length(reply)
                    line = Val(reply)
                    if line
                        GotoLine(line)
                    endif
                endif
            end

See Also:   GetKey(), Read(), AddHistoryStr(), Ask(), ReadNumeric(),
            lReadNumeric()





Assigning Macros and Commands to Keys

To assign macros and commands to keys in the macro language, use the
following format:

    <key>   command

where:

    • key may be any of the keys supported by the editor.  The key
      is enclosed within < > characters.


    • command is one of the following:

      • The name of a native command.

      • The name of a procedure declared previously in the macro file (a
        user-written command).

To determine whether a particular single key (including single-shift and
multi-shift keys) is a valid assignable key, you can use the ShowKey macro,
available on the Potpourri menu.  (Select "Potpourri" under the Util Menu, or
press <Shift F10>; then choose "ShowKey".)  In ShowKey, type the desired key.
If the key is assignable, a line is displayed providing information about
that key, including how to identify the key name in a key assignment
(indicated under the column "Key Name").

In key assignments, the key name is not case sensitive.  (For example,
<Shift s> and <Shift S> are equivalent, since "S" and "s" refer to the same
key on the keyboard.)  Note, however, that using <Shift>, <Ctrl>, or <Alt>
with another key name makes that other key name distinct from its "unshifted"
state.  (For example, <Shift S> and <S> are NOT equivalent.)

If a key assignment is made for a macro or command that is included in a menu
definition in the same macro file, the menu will automatically display the key
assignment (unless the menu definition specifies otherwise, using the NoKeys
option).

Following are some sample key definitions, assuming procedures foo, foo1,
and foo2 have been previously defined:

    <f1>  foo()

    <Shift Ins>  foo1()

    <Ctrl BackSpace>  foo2()

    <alt F10>  ShowEntryScreen()

A command can also be assigned to a "two-key" sequence.  The format is:

    <key1><key2>  command

For example:

    <Ctrl Q><Ctrl F>    foo()

    <F1><Alt B>         foo1()

    <Ctrl k><t>         MarkWord()


NOTE:   In two-key assignments, if you use <Ctrl> with the first key of the
        assignment, that key state is also assumed for the second key of the
        assignment if the second key is one of the alphabetic characters, a
        through z (or A through Z), or if the second key is <Shift> plus one
        of the alphabetic characters.  For example, <Ctrl Q><Ctrl F> is
        equivalent to <Ctrl Q><F>; and <Ctrl k><t> is equivalent to <Ctrl
        k><Ctrl t>.  Also, <Ctrl k><t> is equivalent to <Ctrl k><Shift t>.
        However, <Ctrl k><t> is distinct from <Ctrl k><Alt t>.





Attr

Sets the display attribute to be used in subsequent video output commands.

Values:     INTEGER - [0..255]

            The Color() command may be used to generate these values.

Default:    Undefined

Limits:     Cannot be used within a config/endconfig construct.

Notes:      The attribute is used by the video output commands.

            For more information on video output commands, see
            "Video Output Commands" in the chapter on
            "Using Macro Language Features."

Affects:    PutChar(), PutCharV(), PutCharH(), PutLine(), PutStr(), Write(),
            WriteLine(), ClrScr(), ClrEol()

See Also:   Commands:  Color(), PutAttr()





Augmenting the Editor Load Directory

By default, the installation routine places the editor executable program,
along with various configuration and utility files used by the editor, in the
editor "load directory."  Many other supplemental editor files are placed in
a variety of sub-directories off the load directory.  (For example, the
documentation files used by the HelpSystem are placed in a \HELP
subdirectory.)

However, you may find it helpful or necessary to maintain the editor
executable program (g32.exe (GUI version) or e32.exe (Console version)) in
a separate directory from the other files in the editor load directory.  In
order to do this, you will need to augment what the editor views as its load
directory, by extending it to an additional directory.  If you do so, the
extended directory (rather than the actual directory from which the editor is
loaded) will then be used as the load directory in which the editor will write
any necessary configuration files. This will also extend the directory the
editor searches when it is attempting to locate files in the load directory:
the editor will first search the extended load directory, and if the file is
still not found, the editor will then search in the directory from which the
editor was actually started.

You can specify an extended load directory by creating a TSELOADDIR
environment variable that the editor will look for on startup.  This optional
extension of the editor load directory addresses two potential needs:

    • You want to store just the editor executable program in an alternate
      directory on your machine, and leave all the other editor files in the
      editor installation directory.

      For example, suppose you store all of your utility programs in C:\bin
      (which is included in your PATH), so you want to move the editor
      executable program (g32.exe or e32.exe) to C:\bin.  But you do not want
      to move all the other editor files to this directory.  To do this:

        1.  Install the editor in c:\TSEPro (or whatever directory name you
            choose).

        2.  Move g32.exe or e32.exe, as appropriate, to c:\bin.

        3.  Create an environment variable called TSELOADDIR, and assign it
            as follows (assuming you installed the editor in c:\TSEPro):

              set TSELOADDIR=c:\TSEPro

            You would probably want to place this in AUTOEXEC.BAT under
            Windows 95/98, or use the Control Panel to set it under Windows
            NT.

      Now the editor will run from c:\bin, but all configuration information
      will be written to the appropriate files in c:\TSEPro.

    • You are installing the multi-user version of the editor in a network
      environment, and you want to store just one copy of the editor on a
      read-only network drive, but still allow each user to individually
      configure the editor.

      For example, suppose N: is a read-only drive on your network, and
      shared utility programs are maintained in N:\TOOLS.  All users have
      read-only access to N:\TOOLS.  Accordingly, you want to store the
      editor in N:\TOOLS\TSEPro.  To do this:

        1.  Run the installation program for the editor, and select
            N:\TOOLS\TSEPro as the installation directory.  Note that
            N:\TOOLS\TSEPro must be included in each user's PATH.

        2.  Have each user create a private directory to which the user has
            write access, such as c:\TSEPro.  Then copy the following files to
            this private directory:

              N:\TOOLS\TSEPro\*.DAT
              N:\TOOLS\TSEPro\SYNHI\*.SYN
              N:\TOOLS\TSEPro\SPELL\USER.LEX

        3.  Have each user create an environment variable called TSELOADDIR,
            and assign it as follows (assuming you copied the files
            mentioned in the previous step to c:\TSEPro):

              set TSELOADDIR=c:\TSEPro

            You would probably want to place this in AUTOEXEC.BAT under
            Windows 95/98, or use the Control Panel to set it under Windows
            NT.

      Now the editor will run from N:\TOOLS\TSEPro, but all configuration
      information will be written to the files stored in c:\TSEPro.


Instead of setting the TSELOADDIR environment variable as described above, the
extended load directory can alternatively be set (or overridden) when the
editor is started.  To do this, specify the "Augment Load Dir" (-i)
command-line option at the command line on editor startup, and indicate the
appropriate extended load directory (C:\TSEPro in the examples above).  (For
more information on specifying the "Augment Load Dir" command-line option, see
"Command-Line Options" in the chapter on "Starting the Editor.")





AutoIndent

Determines placement of the cursor after issuing the CReturn() command; also
determines the formatting actions taken by the WrapPara() command.

Values:     INTEGER

            • OFF turns AutoIndent OFF.

            • ON turns AutoIndent ON.

            • _STICKY_ enables STICKY AutoIndent.

Default:    ON

Notes:      When AutoIndent is ON or STICKY, the editor automatically indents
            each new line that is created.

            For more information on AutoIndent, see the chapter on
            "Editing Modes" in the User's Guide.

Affects:    WrapPara(), CReturn()

See Also:   WordWrap





Autoindent Mode

AutoIndent mode provides for automatic indentation of text, based on the
effective left margin.  AutoIndent affects positioning of the cursor when you
execute CReturn (that is, you press <Enter>).  It also has an effect on the
behavior of WordWrap mode (as described in the preceding section, "WordWrap
Mode").  In addition, it affects the formatting of text when WrapPara is
executed.

AutoIndent has three settings:  OFF, ON, or STICKY.  To change AutoIndent mode
to one of these settings, select "AutoIndent" under the Options Menu, and then
choose the desired setting.  When AutoIndent mode is ON or STICKY, an "A" is
displayed on the StatusLine.


The Effective Left Margin
─────────────────────────

The effective left margin is the left-hand column at which the cursor is
positioned when you execute CReturn and when you enter text in WordWrap mode.
It is also the column at which text is left-justified when you reformat text
using the WrapPara command.

For CReturn and WordWrap mode, the effective left margin is determined
according to the LeftMargin setting or to the status of AutoIndent, as
follows:

    • If AutoIndent is OFF, the effective left margin is the column specified
      for the LeftMargin setting (or column 1, if LeftMargin is zero).  (To
      set LeftMargin, select "Left Margin" under the Options Menu, and enter
      the desired value.)

    • If AutoIndent is ON, the effective left margin floats, based on existing
      text, as follows.  For purposes of this discussion, a blank line is one
      which is empty, or contains only white (space or tab) characters.

      • On a non-blank line, the effective left margin is the column position
        of the first non-white character on that line.

      • On a line that is blank, but which immediately follows a line that is
        not blank, the effective left margin is the column position under the
        first non-white character of the preceding line.

      • On a line that is blank, and which immediately follows a line that is
        also blank, the effective left margin is the column specified by the
        LeftMargin setting (or column 1, if LeftMargin is zero).

    • If AutoIndent is STICKY, the effective left margin floats just as it
      does when AutoIndent is ON, but with this slight variation:

      • On a line that is blank, and which immediately follows a line that is
        also blank, the editor searches backward until it finds a non-blank
        line.  The effective left margin is then the column position under the
        first non-white character of the previous non-blank line.

For the WrapPara command, the effective left margin is determined as explained
in "Commands to Format Text" in the chapter on "Manipulating Text."





BackSpace()

Deletes the character to the left of the cursor position.  Shifts the cursor
to the left one position, along with the text at and to the right of the
cursor.

Syntax:     INTEGER BackSpace()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If the cursor is at column 1, no action occurs and zero is
            returned.

            To cause <Backspace> to join the current line with the previous
            line when the cursor is at column 1, replace the <Backspace> key
            definition with the following:

            proc mBackSpace()
                if (not BackSpace()) and PrevChar()
                    JoinLine()
                endif
            end

            <Backspace>     mBackSpace()

            To prevent <Backspace> from shifting text when in overwrite mode,
            replace the <Backspace> key definition with the following:

            proc mBackSpace()
                if Query(Insert)
                    BackSpace()
                elseif Left()
                    InsertText(" ", _OVERWRITE_)
                    Left()
                endif
            end

            <Backspace>     mBackSpace()

            To have <Backspace> do both of the above, use the following key
            definition:

            proc mBackSpace()
                if Query(Insert)
                    if (not BackSpace()) and PrevChar()
                        JoinLine()
                    endif
                elseif Left()
                    InsertText(" ", _OVERWRITE_)
                    Left()
                elseif PrevChar()
                    JoinLine()
                endif
            end

            <Backspace> mBackSpace()

See Also:   DelChar()





BackupExt

Allows you to set the name of the extension used for backup files.

Values:     STRING (maximum of 30 characters)

            The leading "." character is not necessary.

Default:    "BAK"

Notes:      When BackupPath is set, BackupExt is ignored.
Affects:    SaveAllAndExit(), SaveAllFiles(), SaveAndQuitFile(), SaveFile()

See Also:   BackupPath, MakeBackups, ProtectedSaves





BackupPath

Determines where backup files are written.

Values:     STRING

Default:    ""

Limits:

Notes:      When BackupPath is set, BackupExt is ignored.

            BackupPath should be set to an existing path.  If the path
            assigned does not exist, a backup file will not be written.

            It is not necessary for BackupPath to be non-ambiguous.  For
            instance, setting BackupPath to "save-here" would cause backup
            files to be written to the directory "save-here", relative to
            the current drive and directory.

            Setting BackupPath to "\save-here" would cause backup files to
            be written to "\save-here", relative to the current drive.

Affects:    BackupExt

            Commands:  Exit(), QuitFile(), RenameAndSaveFile(),
                       SaveAllAndExit(), SaveAllFiles(), SaveAndQuitFile(),
                       SaveFile()

See Also:   BackupExt, MakeBackups, ProtectedSaves

            Commands:  Exit(), QuitFile(), RenameAndSaveFile(),
                       SaveAllAndExit(), SaveAllFiles(), SaveAndQuitFile(),
                       SaveFile()





Basic Concepts

           ┌────────────────────────────────────────────────────┐
           │ Introduction                                       │
           │ Overview of the Editor                             │
           │ Installation of the SemWare Editor Professional    │
           │ Starting the Editor                                │
           │ Command Prompts And PickLists                      │
           │ Editing Modes                                      │
           │ The Pull-Down Menu System                          │
           │ The Screen Layout                                  │
           │ Using Tabs                                         │
           └────────────────────────────────────────────────────┘





Basic Find and Replace Options

Included in the editor are the Find command and the related Replace command,
along with a number of versatile options.  Also included are the Again and
AgainReverse features, which allow you to repeat the previous Find or Replace
operation.




▪ Find  (<Ctrl F>, or "Find" under Search Menu)

  This command searches for a specified string (all on one line).  Unless you
  indicate otherwise, the search is case sensitive, and begins searching at
  the cursor position and moves forward to the end of the current file.  When
  located, the cursor is placed in the text on the first character in the
  string, and the string is highlighted.

  When you execute Find, the editor displays the prompt, "Search for:".  Enter
  the string to be located (or press <CursorUp> or <CursorDown> to pop up and
  select from a History box of previous search strings).  The editor then
  issues the following prompt to obtain any options to use for the Find
  operation:

  ┌───────────────────────────────────────────────────────────────┐
  │Options [BGLIWX] (Back Global Local Ignore-case Words reg-eXp):│
  │I                                                              │
  └───────────────────────────────────────────────────────────────┘

  Note in the prompt box above that the editor's standard setting for the
  initial Find options is "I" (Ignore-case).  (For more information on how to
  change the initial Find options, see "Initial Find Options" under
  "Command/Format Options" in the chapter on
  "Configuring the Editor Interactively.")

  Multiple options can be specified.  Enter the appropriate character for each
  desired option, as follows:

    [B]     Backward.  Search backward from the current cursor position.  The
            search begins one position before the current cursor position.

    [L]     Local.  Limit the search to the block marked in the current file.

    [G]     Global.  Start the search at the beginning of the current file.

            If the [G] and [L] options are specified and a block is marked in
            the current file, the search starts at the beginning of the block.

            If the [G] and [B] options are specified, the search starts at the
            end of the current file.

            If the [G], [L], and [B] options are specified, the search starts
            at the end of the block in the current file.

    [A]     All.  Continue the search through all files in the Ring,
            beginning at the cursor position.  The search continues through
            all files in the Ring, and stops when it returns to the current
            file.

            Text located in the current file before the cursor position is not
            included in the search.  To include the text before the cursor
            position, you must also specify the [G] option; this causes the
            search to start at the beginning of the current file.

            If the [A] and [L] options are specified and a block is marked in
            a file other than the current file, the editor switches to the
            file containing the block, then starts the search at the beginning
            of the block.

            If the [A], [G], [L], and [B] options are specified, the search
            starts at the end of the block, regardless of the file in which
            the block is located.

    [I]     Ignore-case.  Ignore the case of alphabetic characters in the
            search string.

    [W]     Words.  Search for whole words only, as determined by the WordSet
            variable.  (For more information on the characters that comprise
            the WordSet, see "WordSet Characters" under
            "Command/Format Options" in the chapter on
            "Configuring the Editor Interactively.")

    [X]     regular eXpression.  Evaluate the search string according to the
            Regular Expression format and notation (described in the section
            on "Searching with Regular Expressions.")  For a short notation
            list see "Summary List of Regular Expression Operators".

    [C]     Current line.  Limit the search to the current line.

            If the [C] and [G] options are specified, the search starts at the
            beginning of the current line.

    [^]     beginning anchor.  Anchor the search string to the beginning of
            the line (or block).  The search operation attempts to locate a
            matching string that begins in column 1 of a line; or, if the [L]
            option is also specified, it attempts to locate a matching string
            that begins in the first column of the block.

    [$]     ending anchor.  Anchor the search string to the end of the line
            (or block).  The search operation attempts to locate a matching
            string that ends on the last character of a line; or, if the [L]
            option is specified, it attempts to locate a matching string that
            ends on the last character within the block or at the end of the
            line, whichever comes first.

    [+]     next character.  Start the search at the next character in the
            text (rather than at the cursor position).

    [V]     View.  Display (view) a PickList of all lines that contain the
            specified search string.  You can then select the desired line of
            text from the PickList, and the editor will place you in the file
            on the selected line.  For more information on how to use or
            redisplay the view PickList, see the CompressView command under
            "Listing All Occurrences of a Specified Text String" later in this
            chapter.

            When the [V] option is specified, the [G] option is always
            assumed, and the [B] or [C] options (if specified) are ignored.

▪ Replace  (<Ctrl R>, or "Replace" under Search Menu)

  This command searches for a string and replaces it with another string.  As
  an extension of the Find command, Replace searches in the same manner and
  recognizes the same options as Find (except the [V] option), and includes
  additional replacement options.  Unless specified otherwise, Replace prompts
  you, each time the indicated search string is located, to indicate whether
  you want the replacement to be made.

  When you execute Replace, the editor displays the prompt "Search for:".
  Enter the string to be located (or press <CursorUp> or <CursorDown> to pop
  up and select from a History box of previous search strings entered during
  the current session).  The editor then issues the prompt "Replace with:".
  Enter the replacement string.  The following prompt is then issued to obtain
  any options to use for the search and the subsequent Replace operation:

┌─────────────────────────────────────────────────────────────────────────┐
│Options [BGLIWNX] (Back Global Local Ignore-case Words No-promp reg-eXp):│
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

  (Note in the prompt box above that the editor's standard setting does not
  specify an initial Replace option.  For more information on how to change
  the initial Replace options, see "Initial Replace Options" under
  "Command/Format Options" in the chapter on
  "Configuring the Editor Interactively.")

  Enter the appropriate character for each desired option, as described above
  for the Find command, including the following additional Replace options:

    [N]     No prompting.  Do not prompt for replacement confirmation at each
            occurrence of the indicated search string; that is, replace all
            occurrences of the string in the designated text without
            prompting.

    [#]     number of times, where "#" is an actual number.  Enter the number
            of occurrences of the search string to replace, without being
            prompted for replacement confirmation.  For example, if you enter
            "8", the first eight occurrences of the string are automatically
            replaced.

  When Replace locates a string in the text that matches the search string
  (and the [N] or [#] options ARE NOT specified), the text string is
  highlighted, and the prompt, "Replace (Yes/No/Only/Rest/Quit):", is
  displayed.  Press the letter for the desired response, as follows:

    [Y]     Yes.  Make the replacement, then continue to the next occurrence
            of the search string.

    [N]     No.  Do not make the replacement, but continue to the next
            occurrence of the search string.

    [O]     Only.  Make the replacement only to this occurrence, then
            terminate the Replace operation.

    [R]     Rest.  Make the replacement for this occurrence, then replace the
            rest of the occurrences of the search string in the designated
            text WITHOUT further prompting.

    [Q]     Quit.  (Or press <Escape>)  Do not make the replacement, and quit
            the Replace operation.

  Once the Replace operation stops, the number of replacements that were made
  is displayed on the StatusLine with the message, "# change(s) made.", where
  "#" is the actual number of replacements.

▪ Again  (<Ctrl L>, or "Again" under Search Menu)

  This command repeats the last search operation (that is, the last execution
  of a search command such as Find, Replace, FindWordAtCursor, or
  IncrementalSearch).  It begins searching one position after the current
  cursor position if a forward search had previously been performed, or one
  position before the current cursor position if a backward search had
  previously been performed.  All search or Replace options other than [G]
  (Global) that were in effect for the previous execution of the operation,
  are in effect for Again.

▪ AgainReverse  (<CtrlShift L>)

  This command is a variation of the Again command that allows you to repeat
  the last search operation, but in the opposite direction.  If the previous
  search was a forward-seeking search, AgainReverse would search backwards
  from the current position; if the previous search was a backward-seeking
  search, AgainReverse would search forward from the current position.





Beep

Determines if the editor will "sound" the PC speaker when Find() or Replace()
operations fail.

Values:     BOOLEAN

Default:    ON

Notes:      This setting does not affect the Alarm() command.

Affects:    Find(), Replace(), RepeatFind()

See Also:   Commands:  Find(), Replace(), RepeatFind()





BegFile()

Moves the cursor to line 1, column 1, of the current file.

Syntax:     INTEGER BegFile()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Zero is returned if the cursor position does not change.  For
            example, if the cursor is already at the beginning of the first
            line of the file, zero is returned.

            This command is equivalent to the following:

            GotoLine(1)
            BegLine()

Examples:

            In order to maintain the current cursor column when a column
            block is open in the current file, use the following macro
            instead of the BegFile() command:

            proc mBegFile()
                integer col = CurrCol()

                BegFile()
                if Query(Marking) and isBlockInCurrFile() == _COLUMN_
                    GotoColumn(col)
                endif
            end

            <Ctrl PgUp> mBegFile()

See Also:   EndFile()





BegLine()

Moves the cursor to column 1 of the current line.

Syntax:     INTEGER BegLine()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If the cursor is already at the beginning of the current line,
            zero is returned.

            A common alternative for a "BegLine" key, is to have the cursor
            jump between the beginning of the line and the first non-white
            character on the line:

            proc mHome()
               if not BegLine()
                   GotoPos(PosFirstNonWhite())
               endif
            end

            <Home> mHome()

See Also:   BegLineTog(), EndLine(), EndLineTog()





BegLineTog()

Toggles the cursor position between the column 1 and the first non-blank
character on the current line.

Syntax:     BegLineTog()

Returns:    Nothing.

Notes:      If the cursor is already positioned at the first non-blank
            character on the current line, the cursor moves to the beginning
            of the current line, otherwise the cursor moves to the first
            non-blank character on the current line.

See Also:   BegLine(), EndLine(), EndLineTog()





BegWindow()

Moves the cursor to the top line of the current window.  The cursor column is
not changed.

Syntax:     INTEGER BegWindow()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If the cursor is already at the top line of the current window,
            zero is returned.

See Also:   EndWindow()





BegWord()

Positions the cursor at the beginning of the current word.

Syntax:     INTEGER BegWord()

Returns:    Zero (FALSE) if the cursor was not on a word; otherwise, non-zero.

Notes:      The editor uses the WordSet variable to determine what constitutes
            a word.

See Also:   EndWord(), WordRight(), WordLeft()

            Variables:  WordSet





BinaryMode()

Determines whether the current file is in Binary mode.

Syntax:     INTEGER BinaryMode([INTEGER mode_type])

            • mode_type is an optional new Binary mode type to use.
              Supported values for mode_type are:

              • 0 (zero) - effectively takes the current file out of Binary
                mode.

              • 1 (or any value through the maximum line length) - places the
                current file in Binary mode.  If the file is saved in this
                mode, end-of-line characters will NOT be added to each line.
                (Use this mode with caution.  Normally the editor places
                end-of-line character(s) at the end of each line when a file
                is saved.  If a file is in this mode when saved, the only
                end-of-line characters in the file will be those manually
                input to the file by the user.)

              • -1 -  places the current file in Binary mode.  If the file is
                saved in this mode, it will be written with a length byte
                preceding each line.

              • -2 -  places the current file in Binary mode.  If the file is
                saved in this mode, it will be written with a length word (2
                bytes) preceding each line.

Returns:    Zero (FALSE) if the current file is not in Binary mode;
            otherwise, the Binary mode_type value in effect when this command
            is invoked.

Notes:      In Binary mode, the tab character is not displayed as spaces;
            instead, the actual tab character is displayed.

            A file can also be placed in Binary mode when it is initially
            loaded, by including the -b switch ahead of the filename.  A
            mode_type value can be specified by placing the appropriate
            value immediately following -b.

            • If a mode_type value from 1 to the maximum line length is
              specified, this value will be the fixed length at which each
              line is displayed on the screen.

            • If a mode_type value of -1 or -2 is specified, each line will
              be displayed according to the value of its length byte (if
              mode_type is -1) or its length word (if mode_type is -2).

            When a file is LOADED in Binary mode, no character translation
            takes place, as normally occurs with the end-of-line characters
            and the tab character.

Examples:

            // To set Binary mode for the current file:
            BinaryMode(80)

            // To turn off Binary mode for the current file:
            BinaryMode(0)

            // To test whether the current file is in Binary mode:
            if BinaryMode()
                Message("File is in Binary mode")
            endif

See Also:   EditFile(), EditThisFile(), DisplayMode(), AddFileToRing()





Block Operations

During an editing session, you can manipulate a limited portion of a
file by selecting, or "marking," a block of text.  A block can consist of
entire or partial lines, or columns of text, or even a single word or
character.  A block can be copied, moved, deleted, printed, or written to
disk.  You can also limit certain operations to text within a block.

In addition, you can copy or move ("cut") a block of text to a temporary area,
called a ClipBoard.  Text placed in a ClipBoard can later be retrieved and
pasted back into the original file or a different file.

This chapter describes methods available for:

    • Marking and manipulating a block of text:

      • Opening and closing a blockExtending a blockBlock-marking commands

            (MarkColumn, MarkLine, MarkStream, MarkChar, MarkWord, MarkToEOL,
            MarkParagraph)

      • Unmarking a block

            (UnMarkBlock)

      • Manipulating text in a block

            (CopyBlock, OverlayColumnBlock, DelBlock, FillBlock, MoveBlock,
            SaveBlock, Shift, ShiftLeft, ShiftRight)

      • Changing the case of characters in a block

            (Upper, Lower, Flip, Capitalize)

      • Moving to the beginning or end of a block

            (GotoBlockBegin, GotoBlockEnd)

    • Manipulating blocks via ClipBoards

            (Copy, CopyAppend, Cut, CutAppend, Paste, PasteOver, Empty,
            CopyToWinClip, CutToWinClip, PasteFromWinClip)


Other chapters describe how to use the mouse for block operations, and how to
use blocks to expand or restrict the scope of certain commands.

The chapter on "Mousing Around the Editor" explains how to use the mouse to
mark blocks, and how to access the Mouse menu to execute many block-related
and ClipBoard-related commands.

The chapter on "Manipulating Text" discusses how to limit or extend the scope
of the WrapPara, CenterLine, and QuoteLine commands by marking a block.

The chapter on "Search Features:  Finding and Replacing Text" presents the
"Local" option for Find and Replace operations, which allows you to restrict a
Find or Replace to the text in a block.

The chapter on "Checking Your Spelling" describes how to limit SpellCheck to
the words in a block.

The chapter on "Printing from the Editor" explains how to print a portion of a
file limited to the contents of a block marked in that file.

The chapter on "Special Commands and Features" describes how to Sort lines in
a file based on a sort key defined by a block marked in the text.





BlockBegCol

The first column of a marked block.

Values:     INTEGER

Default:    Undefined

Limits:     Can only be queried.  Cannot be used within a config/endconfig
            construct.

Notes:      For line blocks, 1 is returned.

            For column blocks, the starting column of the block is returned.

            For character blocks, the starting position of the block is
            returned.  The position is the same as the column unless hard tab
            characters occur before the position.

See Also:   BlockEndCol

            Commands:  CurrCol(), CurrPos()





BlockBegLine

The first line of a marked block.

Values:     INTEGER

Default:    Undefined

Limits:     Can only be queried.  Cannot be used within a config/endconfig
            construct.

See Also:   BlockEndLine





BlockEndCol

The ending column of a marked block.

Values:     INTEGER

Default:    Undefined

Limits:     Can only be queried.  Cannot be used within a config/endconfig
            construct.

Notes:      For line blocks, the maximum line length of the editor
            (MAXLINELEN) is returned.

            For column blocks, the ending column of the block is returned.

            For character blocks, the ending position of the block is
            returned.  The position is the same as the column unless hard tab
            characters occur before the position.

See Also:   BlockBegCol

            Commands:  CurrCol(), CurrPos()





BlockEndLine

The ending line of a marked block.

Values:     INTEGER

Default:    Undefined

Limits:     Can only be queried.  Cannot be used within a config/endconfig
            construct.

See Also:   BlockBegLine





BlockId

The id of the file which contains the marked block.

Values:     INTEGER

Default:    Undefined

Limits:     Can only be queried.  Cannot be used within a config/endconfig
            construct.

Notes:      If no blocks exist, BlockId is zero.

See Also:   Commands:  GetBufferId(), GotoBufferId()





Bookmark Commands

The editor provides a command to place (or "set") a Bookmark, and a command to
return to a specific Bookmark location.

▪ PlaceMark  (<Ctrl 2>, or "Place Bookmark" under Search Menu)

  This command allows you to place a Bookmark at a location in a file.  To
  place a Bookmark, you position the cursor at the desired location in the
  file, then execute this command.  The prompt, "Set Bookmark [A..Z]:", is
  displayed on the StatusLine.  Press a letter from A through Z.  (The case of
  the letter does not matter.)

▪ GotoMark  (<Ctrl 6>, or "Go to Bookmark" under Search Menu)

  This command allows you to return to a particular Bookmark.  When you
  execute this command, the prompt, "Go to Bookmark [A..Z]:", is displayed on
  the StatusLine.  Press the appropriate letter from A through Z that
  identifies that Bookmark.  (The case of the letter does not matter.)  The
  file containing that Bookmark becomes the current file, and you are
  positioned at the location where that Bookmark was placed.





Bookmark Shortcut

For added convenience, a shortcut method for placing or returning to Bookmarks
is provided.  The editor allows a Bookmark command (PlaceMark or GotoMark),
along with an identifying letter, to be assigned to a specific key (or key
combination).  Then you can simply press the appropriate key assignment to
place or return to a particular Bookmark, without being prompted to enter the
identifying Bookmark letter.

The editor is configured with predefined key assignments for placing and
returning to ten different Bookmarks.  For these predefined Bookmarks, the
editor uses the last ten alphabetic characters, Q through Z, and numbers them
from 0 through 9, respectively.  (Keep this in mind if you choose to use the
two different Bookmark methods in the same editing session.  To eliminate
conflicts between the letters used in the two methods, do not use letters Q
through Z when placing Bookmarks directly with the PlaceMark command.)

To place one of the predefined Bookmarks, press <Ctrl K><#>, where "#" is a
number from 0 through 9 (located above the alphabetic keys, NOT on the numeric
keypad).

To return to one of these Bookmarks, press <Ctrl Q><#>, where "#" is the same
number as the one selected to place the Bookmark.

Of course, you can create your own predefined Bookmark key assignments.  (For
more information on configuring commands and their key assignments, see
"Customization Using SAL Compiled Macros" in the chapter on
"Fully Customizing the Editor.")





Bookmarks

While reading this User's Guide, occasionally you may have referred from one
chapter to another, and then returned to that previous chapter.  In doing so,
you may simply have remembered the page number to which to return, or you may
have placed a bookmark at that page.

Similarly, during an editing session, you may wish to move from your current
position in one file, to another position in that file or to a different file,
and then return to your first file position.  You can do so by remembering the
file and the line number to which you wish to return.  Or, as with a book, you
can place a bookmark to mark that position.

This chapter provides the following information about the editor's Bookmark
feature:

    • Using BookmarksBookmark commands

            (PlaceMark, GotoMark)

    • Bookmark shortcut


The Book macro, an additional Bookmark feature available on the Potpourri
menu, provides a convenient way to set, go to, or list the currently-set
Bookmarks.  Information about this macro is provided under
"Executing Supplemental Macros from the Potpourri" in the chapter on
"Special Commands and Features."





Break

Allows pressing <Ctrl Break> to terminate the execution of a running macro.

Values:     BOOLEAN

Default:    OFF

Limits:     Cannot be used within a config/endconfig construct.

Notes:      USE WITH CAUTION:  Use this only when you are writing/debugging
            your macros.  "Breaking" from a running macro can leave the editor
            in an unstable state since the normal "housecleaning" is bypassed.
            Once a macro runs to completion, break is automatically set OFF.
            Break only has effect within a running macro.  It has no effect in
            normal editing mode.





BreakHookChain()

Ends the hook chain for the current event handler.

Syntax:     BreakHookChain()

Returns:    Nothing.

Notes:      BreakHookChain() only has an effect when called from within a
            hooked event.  Use it when you do not want any following hooks to
            be processed.  The actual editor event is not affected, and
            proceeds normally, except for the calling of additional hooks.

Examples:

            /********************************************************
              Prevent any _ON_CHANGING_FILES_ hooks from being run
              while we are busy.
             ********************************************************/
            proc StopOnChangingFilesHook()
                BreakHookChain()
            end

            proc foo()
                Hook(_ON_CHANGING_FILES_, StopOnChangingFilesHook)
                // Code goes here...
                UnHook(StopOnChangingFilesHook)
            end

See Also:   Hook(), UnHook(), ExecHook(), SetHookState(), TerminateEvent()





Breaking Out of Run-Away Macros

As you begin testing macros that you are developing, you may find errors in
your logic that result in unexpected or undesirable results.  In some cases,
the macro may even run "out of control."  To give you tighter control over a
macro during the testing and debugging phases, the editor provides the Break
variable.  Its intended use is to allow you to regain control of an errant
macro during development.

To enable the Break option within a macro, place the following statement at
the beginning of your macro:

    Set(Break, ON)

This allows you to interrupt the macro, at any time while it is executing, by
pressing the <Ctrl Break> key.  When you press <Ctrl Break> on a macro with
Break enabled, the following selection menu pops up:

    ┌ Macro interrupted... ┐
    │▒Terminate▒Macro▒▒▒▒▒▒│
    │ Continue             │
    └──────────────────────┘

Select "Terminate Macro" to immediately terminate the macro; select "Continue"
if you want the macro to resume processing.

When a macro is terminated this way, normal "clean-up" routines are bypassed.
As a result, editor variables and editing modes may not have been properly
restored, and you may notice erratic or unexpected behavior by the editor.  To
restore normal operation, you should exit and reload the editor.

Because of the unpredictable effects of interrupting a macro while it is
running, the Break feature should only be enabled while you are developing
macros.  Once you have completed testing and debugging your macro, you should
remove the Break statement from the macro.





BrowseMode()

Sets or queries the browse status of the current buffer.

Syntax:     INTEGER BrowseMode([INTEGER status])

            • status is the optional browse status (TRUE or FALSE) to which
              to set the buffer.

Returns:    The current setting of the browse status of the current buffer
            (before being set by status, if specified).

Notes:      Buffers that are marked as browse cannot be saved.

Examples:

            // determine the browse status of the current buffer
            integer browse_only

            browse_only = BrowseMode()

            // Set the current buffer to browse-only
            BrowseMode(TRUE)

            // Set browse-only OFF for the current buffer
            BrowseMode(FALSE)

            // Toggle the current buffer's browse-only status
            BrowseMode(not BrowseMode())





BufferFlags

Contains information about the current buffer, as a bit-mapped flag.

Values:     INTEGER_READONLY_LOCKING_ indicates the file is Read-Only locked.

            • _HANDLE_LOCKING_ indicates the file is handle locked.

            • _CANT_LOCK_ indicates the file could not be locked.

            • _NEWFILE_ indicates the file is new (that is, it does not
              exist on disk).

            • _LOADED_ indicates the file is loaded into the editor.

            • _PARTIAL_FILE_ indicates the entire file could not be loaded
              into the editor.

Default:    Undefined

Limits:     Can only be queried.  Cannot be used within a config/endconfig
            construct.

See Also:   Commands:  AddFileToRing(), CreateBuffer(), EditBuffer(),
                       EditFile(), EditThisFile(), LoadBuffer()





Buffers

Buffers are the memory areas in which the editor does its work.  Buffers are
where files are stored for user editing.  When a file is in memory, it is also
called a buffer.  Not surprisingly, the editor provides a rich assortment of
commands for manipulating buffers through the macro language.


Manipulating Text in Buffers
────────────────────────────

Many commands can be used in macros to manipulate text.  These include the
block and ClipBoard commands, such as CopyBlock(), MoveBlock(), DelBlock(),
Cut(), Copy(), and Paste(); the deletion commands, such as DelChar(),
DelLine(), and DelToEol(); and other text-changing commands, such as
DupLine(), InsertFile(), JoinLine(), SplitLine(), Upper(), Lower(), Flip(),
and WrapPara().


Retrieving Text from Buffers

Many times, it is useful to get text from the current buffer into a SAL string
in order to further manipulate it.  The editor provides several commands for
doing this, as described below.

In the examples that follow, assume the existence of the following SAL
variables:

    string c[1], s[80]

▪ CurrChar()

  Because CurrChar() retrieves the character at the cursor position, it is
  very common to use CurrChar() in a macro to examine the character the cursor
  is on.  For example, to see if the cursor character is "!", use the
  following:

    if CurrChar() == Asc('!')

  Note the use of Asc() with CurrChar().  This is necessary because CurrChar()
  returns an integer (as illustrated in the next example).

  Another common usage of CurrChar() is to see if the cursor is past the text
  on the current line.  For example:

    if CurrChar() < 0  // if CurrChar < 0, past text on current line

  As mentioned previously, CurrChar() returns the current character
  represented as an integer.  If, at the time of the call to CurrChar(), the
  current position is beyond the last character on the current line,
  CurrChar() returns a negative number to indicate this condition.  To
  distinguish between the position that is one column beyond the last
  character on the line (which is considered the "end-of-line" position), and
  a position more than one column beyond the last character on the line, the
  following constants are provided:  _AT_EOL_, _BEYOND_EOL_

  For example, to determine if the cursor is one column past the last
  character of the line (that is, at the end-of-line position), use the
  following:

    if CurrChar() == _AT_EOL_

  Another use of CurrChar() is to copy the current character into a string,
  such as the following:

    c = Chr(CurrChar())

▪ GetText()

  The GetText() command can be used to copy one or more characters from the
  current line into a SAL string.  For example:

    s = GetText(1, sizeof(s))

  This example copies text, starting at position 1 on the current line, into
  the string s.  The text is copied until either the end of line is reached,
  or the string s has no more room to accept new characters.

  A note about the first parameter of GetText():  This is the value of the
  character position in the current line where text retrieval begins.  This
  value represents the number of actual characters from the beginning of the
  line to the current character.  The value of this "position" is not always
  the same as the number of the cursor column at which the character is
  displayed on the screen; specifically, the two are different when hard tab
  characters exist in the current line, tab expansion is ON, and the TabWidth
  is greater than 1.  To get the current "position" within the line (that is,
  the number of the character position from the beginning of the line), use
  the CurrPos() command.  This is in contrast to CurrCol(), which returns the
  current cursor column.

  To start copying text at the current position, you can use the following:

    s = GetText(CurrPos(), SizeOf(s))

▪ GetMarkedText()

  The GetMarkedText() command is handy for copying a marked block into a SAL
  string.  GetMarkedText() is commonly used in a sequence as follows:

    // Position to the text you want to work with
    PushBlock()             // do not disturb pre-existing blocks
    MarkWord()              // mark the word at the cursor
    s = GetMarkedText()     // retrieve it into a string
    PopBlock()              // restore block state

  If the length of s is smaller than the length of the marked text, the
  stored text will be truncated to the length of s.


Storing Text in Buffers

Just as the editor provides commands to get text from buffers, there are also
commands to put text back in buffers, as described below.

▪ AddLine() and InsertLine()

  The basic formats of these commands are (respectively):

    AddLine([STRING st [, INTEGER buffer_id]])

    InsertLine([STRING st [, INTEGER buffer_id]])

  These commands place a new line in the file, containing the text passed in
  st.  AddLine() places the new line after the current line, while
  InsertLine() places the new line before the current line.  In either case,
  the newly-created line becomes the new current line.  The string st is
  optional.  If st is omitted, an empty line is placed in the file.  If the
  optional buffer_id is passed, the text is placed in the file with that
  buffer id.

▪ InsertText()

  The basic format of this command is:

    InsertText(STRING st [,flag])

  InsertText() is used to place text into the buffer, at the current position.
  If flag is not specified, the current value of the Insert variable is used
  to determine whether the text is inserted, or whether it overwrites text at
  the current cursor position.  To control how text is input, the constants
  _INSERT_ and _OVERWRITE_ can be used.  For example, to insert the string
  "Beam me up, Scotty!" at the current position:

    InsertText("Beam me up, Scotty!", _INSERT_)

  The text is inserted at the current position regardless of the setting of
  Insert.

▪ InsertData()

  The basic format of this command is:

    InsertData(data_name)

  This command inserts a set of data (defined by the datadef statement) into
  the current buffer.  (For more information, see "Datadef" later in this
  chapter.)


The following commands are available especially for use in macros.

▪ EmptyBuffer()

  The basic format of this command is:

    EmptyBuffer([INTEGER buffer_id])

  This command removes all the text associated with the current or specified
  buffer.  It is especially useful when re-using a work buffer, and the work
  buffer needs to be empty.

▪ ShiftText()

  The basic format of this command is:

    ShiftText(INTEGER shift_amount)

  This command shifts the text on the current line by the number of positions
  indicated as shift_amount.  The text shifts either right or left, depending
  on the sign of shift_amount:  if positive, text is shifted right; if
  negative, text is shifted left.


At times it may be useful to place a SAL string into the editor's ClipBoard.
The way to do so may not be obvious at first; but once understood, it can be
applied in many ways.  The following illustrates this method.

    /**********************************************************
      Macro to place a string in the ClipBoard.  The current
      contents of the ClipBoard are lost.

      Returns TRUE if successful, FALSE if not.
     *********************************************************/

    integer proc String2ClipBoard(string s)
        if CreateTempBuffer()
            MarkChar()
            InsertText(s)   //Insert the string, it will be marked
            Copy()          //Copy it to the ClipBoard
            AbandonFile()   //Remove the temp buffer
            return(TRUE)
        endif
        return(FALSE)
    end

This procedure could be called as follows:

    String2ClipBoard("Make it so...")

Now, the next time Paste() is executed, "Make it so..." will be pasted into
the text at the current cursor position.

Some general notes regarding the above procedure:

    • When putting text in ClipBoards or Named ClipBoards, always use the
      Cut() or Copy() commands.  These commands set internal information,
      making it possible for the Paste() command to work properly.

    • In String2ClipBoard(), a character block is used.  Other block types
      (line or column blocks) can also be used, if desired.

    • String2ClipBoard() takes advantage of the ring-like structure in which
      buffers are kept.  Since new buffers are added immediately after the
      current buffer, and abandoning the current buffer makes the previous
      buffer the new current buffer, there is no need to save the current
      buffer Id and return back to it, as it is handled automatically in this
      case.


Creating Buffers
────────────────

There are several types of buffers, which can be created in several ways.  The
buffer types include:

    • _NORMAL_, which is used for an interactively-edited file.  For example,
      buffers (files) created with the EditFile() command are _NORMAL_
      buffers.

    • _HIDDEN_, which is very similar to _NORMAL_, except this type of buffer
      will not show up in buffer lists, and is skipped over by the NextFile()
      and PrevFile() commands.  This type of buffer is used as a work buffer.
      For example, the PickList of loaded macros (optionally displayed by the
      ExecMacro() command) is stored in a _HIDDEN_ buffer.

    • _SYSTEM_, which is very different from a _NORMAL_ or _HIDDEN_ buffer.
      This should only be used if a system buffer is truly needed, and should
      never be edited interactively.  A _SYSTEM_ buffer, like a _HIDDEN_
      buffer, is not easily accessible and is used as a work buffer.  However,
      _SYSTEM_ buffers handle text in a raw fashion, so that tabs are not
      expanded and trailing spaces are not removed.  The buffers that hold
      ClipBoards and histories are created as _SYSTEM_ buffers.

There are a number of ways to create buffers, as follows:

    • The easiest, and probably most familiar way to create a buffer, is with
      the EditFile() command.  EditFile() creates a _NORMAL_ buffer.  The
      buffer is associated with a file on disk, and can be readily saved and
      loaded.

    • CreateBuffer() can be used to create a buffer of any type.  Buffers
      created by CreateBuffer() are not associated with a file on disk.

    • CreateTempBuffer() can be used to create a temporary _SYSTEM_ buffer.
      As with CreateBuffer(), these buffers are not associated with a file on
      disk.  In fact, these buffers are not given a name when they are
      created.  Since these are _SYSTEM_ buffers, these buffers should never
      be used for interactive editing.

The current buffer type can be queried and changed, by using the
BufferType() command.  For example, to query the buffer type, use:

    if BufferType() == _SYSTEM_     // This is a system buffer
        ...
    endif

and to set the buffer type, use:

    BufferType(_HIDDEN_)    // Make this buffer hidden


Referencing and Switching to Buffers
────────────────────────────────────

_NORMAL_ buffers can be switched to via the NextFile(), PrevFile(), and
EditFile() commands.

The method for switching to _HIDDEN_ or _SYSTEM_ buffers is quite different.
Each buffer has associated with it a buffer Id.  These Ids are used to switch
to _HIDDEN_ or _SYSTEM_ buffers.  CreateBuffer() and CreateTempBuffer() return
a buffer Id, and GetBufferId() can be used to get the Id of the current or a
specified buffer.  These Ids can be used in conjunction with the
GotoBufferId() command to change to the specified buffer.  Note that unlike
the NextFile(), PrevFile() and EditFile() commands, GotoBufferId() does not
invoke any event macros.  (For more information on event macros, see
"Event Macros" later in this chapter.)





BufferType()

Determines the current editing buffer "type."

Syntax:     INTEGER BufferType([INTEGER type])

            • type is an optional integer that represents the new buffer
              type that is set.  Supported values for type are:

              • _NORMAL_ causes the buffer to have no special attributes
                associated with it.  Buffers created with EditFile() have this
                buffer type.

              • _HIDDEN_ simply causes the buffer to not show up in the list
                of files, and makes the buffer inaccessible via the NextFile()
                and PrevFile() commands.  The PickList of loaded macros
                (optionally displayed by the ExecMacro() command) is stored in
                a _HIDDEN_ buffer.

              • _SYSTEM_ causes the buffer to be hidden, and places the
                buffer in a raw mode, so that trailing spaces are never
                removed, and tabs are treated as a normal character.  Buffers
                created with CreateTempBuffer() have this buffer type.  It is
                strongly recommended that system buffers not be used for
                interactive editing.

                Undo/Redo information is NOT recorded for _SYSTEM_ buffers.

Returns:    The buffer type of the current buffer.

Notes:      The return value of BufferType() will be the current editing
            buffer "type" which will be _NORMAL_, _SYSTEM_, or _HIDDEN_.
            (For more information on buffer types, see the description of
            CreateBuffer().)

Examples:

            // Determine the current buffer type
            integer type

            type = BufferType()

            // Set the current buffer type to _HIDDEN_
            BufferType(_HIDDEN_)

            // Save the current buffer type, and set it to _HIDDEN_
            integer save_type

            save_type = BufferType(_HIDDEN_)

See Also:   CreateBuffer(), CreateTempBuffer(), GotoBufferId(),
            GetBufferId(), EditFile(), EditThisFile(), NextFile(),
            PrevFile()





BufferVideo()

Routes all video output to the editor's virtual screen.

This command is intended for ADVANCED USAGE.

Syntax:     BufferVideo()

Returns:    Nothing.

Notes:      This is a video output command.  It has no effect on the actual
            text in the editing buffer.  It is used to temporarily "buffer"
            informational text that is to be displayed on the screen (in
            order to improve screen update performance).

            When the BufferVideo() command is executed, all subsequent video
            output commands operate on the editor's virtual screen (rather
            than the visible screen).  This continues until the
            UnBufferVideo() command is executed.

            To determine when video output is to be buffered (rather than
            displayed), an internal "buffer mode" counter is maintained.
            Normally, this counter is set to zero, causing video output to be
            visibly displayed on the screen.  Each time the BufferVideo()
            command executes, the buffer mode counter is incremented by 1.
            Each time the UnBufferVideo() command executes, the buffer mode
            counter is decremented by 1.  While the buffer mode counter is
            greater than zero, video output is buffered.  To restore normal
            "displayed" video output, the buffer mode counter must be
            returned to zero.  Thus, each call to BufferVideo() should be
            followed, at the appropriate time, by a corresponding call to
            UnBufferVideo().

            If BufferVideo() is called multiple times without intervening
            corresponding calls to UnBufferVideo(), pending screen output
            will not be displayed until the same number of calls are made to
            UnBufferVideo().  This behavior makes it possible for macros to
            call other macros without disturbing the current overriding state
            of video output buffering.  For example:

            • Macro A makes a call to BufferVideo() to buffer video output.

            • Macro A then calls Macro B to perform some standard routine.

            • Macro B makes a call to BufferVideo() to buffer video output.
              Before terminating (and returning to the calling macro, Macro
              A), Macro B makes a call to UnBufferVideo().

            • Macro A resumes execution, with video output still buffered,
              even though Macro B called UnBufferVideo().

            • When ready to update the display screen, Macro A calls
              UnBufferVideo().  All text in the editor's virtual screen (as
              modified by both Macro A and Macro B) is written to the visible
              screen, and normal display is restored.

            For more information on video output commands, see
            "Video Output Commands" in the chapter on
            "Using Macro Language Features."

Examples:

            integer i

            BufferVideo()       // turn off screen updating
            for i = 1 to 10
                VGotoxy(1, i)
                PutStr("This is a test")
            endfor
            UnBufferVideo()     // turn on screen updating, causing
                                // buffered text to appear

See Also:   UnBufferVideo()





BuildPickBufferEx()

Generates a "PickBuffer" list of the files in a specified directory, using
selected attributes.  The PickBuffer list is created by adding file entries
to the current buffer, at the current position.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER BuildPickBufferEx(STRING filename, INTEGER attributes
                                      [, INTEGER flags])

            • filename is the filename specification used to build the list
              of files.  filename should contain wildcards.  For example:

                    "*.*"

                    "d:\work\*.*"

                    "*.c"

                    "b*.doc"

            • attributes are the attributes to use when searching.  Supported
              values for attributes are:

              • _NORMAL_ specifies files that can be read from or written to.

              • _READONLY_ specifies files that can be read from but not
                written to.

              • _HIDDEN_ specifies files that are hidden and do not appear in
                file directory listings.

              • _SYSTEM_ specifies files that are system files.

              • _VOLUME_ specifies the volume label entry.

              • _DIRECTORY_ specifies directory entries.

              • _ARCHIVE_ specifies files that are marked for archiving.

            • flags is optional.  Supported values for flags are:

              • _INSERT_PATH_ causes BuildPickBufferEx() to insert the entire
                path, rather than just the name of the file.

              • _SEARCH_SUBDIRS_ causes BuildPickBufferEx() to also search
                any subdirectories that are under the current search path.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      When this command is executed, the current buffer itself must be
            a _SYSTEM_ buffer (as created or changed by the CreateBuffer(),
            CreateTempBuffer(), or BufferType() commands).

            If you specify any combination of _SYSTEM_, _HIDDEN_, or
            _DIRECTORY_, this command returns normal files in addition to
            files with the specified attribute(s).  If you want to work only
            with files with the specified attribute(s), you must examine the
            specific attribute for each file, via the FFAttribute() command.

            The PickFileFlags variable can affect the output of this command:

            • If _ADD_SLASH_ is specified, slashes are inserted at the
              beginning of each directory name.

            • If _ADD_DIRS_ is specified, and the _DIRECTORY_ attribute is
              specified for BuildPickBufferEx(), all directories in the
              specified path will be included.

            The first position of each entry in the generated PickBuffer list
            of files is reserved for user use, and can be set as desired.
            Typically, it is used as a tag indicator, as in the standard
            PickList used by the built-in file-editing commands (such as
            EditFile() and InsertFile()).

            The PB-type commands, such as PBName() and PBDate(), can be used
            to extract information from the file entries in a PickBuffer
            created via this command (for manipulation in a macro).

            To display a PickBuffer on the screen, use the DisplayMode()
            command.

Examples:

            // build a list of all the files in the current directory
            integer rc

            rc = BuildPickBufferEx("*.*",
                    _READONLY_|_HIDDEN_|_SYSTEM_|_DIRECTORY_)

            // build list of all INI files in C:\WINDOWS subdirectory:

            rc = BuildPickBufferEx("C:\WINDOWS\*.INI", _NORMAL_)

            // build a list of all BAT files on the C: drive:

            rc = BuildPickBufferEx("c:\*.bat", _NORMAL_,
                    _SEARCH_SUBDIRS_ | _INSERT_PATH_)

See Also:   DisplayMode(), PickFile(), PBAttribute(), PBName(), PBSize(),
            PBDate(), PBDateStr(), PBTime(), PBTimeStr(), AddFFInfoToBuffer()

            Variables:  PickFileFlags





Capture()

Runs an external command in the background, adds any captured output to the
buffer identified by CaptureId, and always switches to the CaptureId buffer.
At start-up the editor creates an empty default buffer for CaptureId.

Syntax:     INTEGER Capture(STRING command [, INTEGER flags])

            • command is the command and parameters to execute.

            • flags is an optional integer value.  Supported values for
              flags are:

              • _STDOUT_ prevents the editing screen from being cleared.

              • _STDERR_ prevents the editing screen from being cleared.

              Multiple flags values can be combined with the bitwise logical
              OR (|) operator.

              For instance: _STDOUT_, _STDERR_, _STDOUT_|_STDERR_

              The default value is _STDOUT_|_STDERR_, causing the
              capturing of both standard output and error output.

Returns:    Non-zero CaptureId if successful; zero (FALSE) on failure,
            indicating a system error.

Notes:      Output is appended to previous output in the capture buffer.

            You can clear the current capture buffer with:
              EmptyBuffer(Query(CaptureId))

            When a command fails without error output, you can try running it
            through a command shell. For example:
              Capture("LS -la /tmp") // Fails with no output, but why?
              Capture("/bin/bash -c LS -la /tmp") // Aha: "command not found"!

            If you explicitly run a command through a command shell, then
            always use the shell's "-c" (Linux) or "/c" (Windows) parameter.
            Not doing so can cause errors (Linux) or hang the editor (Windows).

            For example:

              Windows:
                // This hangs the editor:
                Capture("cmd.exe dir C:\Windows")
                // This succeeds:
                Capture("cmd.exe /c dir C:\Windows")
              Linux:
                // This reports an error:
                Capture("/bin/bash ls -la /tmp")
                // This succeeds:
                Capture("/bin/bash -c ls -la /tmp")

            Linux rule: To pass wildcards with your command, the command must
            be invoked through a Linux shell. For example:

              // This succeeds:
              ls -la /tmp")
              // This fails:
              ls -la /tmp/*")
              // This succeeds:
              Capture("/bin/bash -c ls -la /tmp/*")

Exception:  This exception is rare!

            If the command you want to execute is a built-in command of a
            command shell, and it is not a command for which the editor does
            so automatically, then you need to execute the command through its
            command shell.

            Windows the editor automatically inserts the command shell (as
            found in the COMSPEC environment variable) for these commands:

              assoc, break, call, cd, chdir, cls, color, copy, date, del, dir,
              dpath, echo, endlocal, erase, exit, for, ftype, goto, if, keys,
              md, mkdir, mklink, move, path, pause, popd, prompt, pushd, rd,
              rem, ren, rename, rmdir set, setlocal, shift, start, time,
              title, type, ver, verify, vol.

            Linux the editor automatically inserts the command shell (as found
            in the SHELL environment variable) for these commands:

              alias bg bind break builtin case cd command compgen complete
              continue declare dirs disown echo enable eval exec exit export
              fc fg getopts hash help history if jobs kill let local logout
              popd printf pushd pwd read readonly return set shift shopt
              source suspend test times trap type typeset ulimit umask unalias
              unset until wait while

            Beware false friends: In Linux' bash "help" is a built-in command;
            in Windows' cmd.exe "help" is an external command that lists both
            built-in and external commands.

WARNING:    Depending on what a command does, Capture() can hang the editor.

            One known example for Windows:
              To pass any command to an explicitly invoked shell, the shell's
              "-c" parameter must used or the editor will hang.

              Examples:
                // This hangs the editor:
                Capture("cmd.exe dir")
                // This succeeds:
                Capture("cmd.exe /c dir")

Examples:

            Windows:
              Capture("help")
              Capture("hellp", _STDERR_)
              Capture("date /t")
              Capture("dir C:\Windows")
              Capture("dir C:\Windows\*.*") // OK in Windows.
              Capture("cmd.exe /c dir C:\Windows")
              Capture('"C:\Program Files\7-Zip\7z i"')
              Capture('cmd /c "C:\Program Files\7-Zip\7z i"')

            Linux:
              Capture("ls -la")
              Capture("help")
              Capture("/bin/bash -c help")
              Capture("pwd")
              Capture(GetEnvStr("SHELL") + " -c ls *.*")

See also:   Dos(), lDos(), StartPgm(), Shell(), CaptureId





CaptureId

Determines the buffer id used by the Capture() command. At start-up the
editor creates an empty default buffer for CaptureId.

Values:     INTEGER

Default:    Undefined

Limits:     Cannot be used within a config/endconfig construct.

Notes:      CaptureId can be used to set up and control a user-defined capture
            buffer without affecting the current capture buffer.

            You can use CaptureId in a macro to (typically temporarily) set up
            your own capture buffer, so that your macro does not change the
            contents of the current capture buffer.

Examples:

            // To retrieve the current CaptureId:
            id = Query(CaptureId)

            // To set the current CaptureId to foo_id:
            Set(CaptureId, foo_id)

            // To retrieve the current CaptureId, and set it to foo_id:
            id = Set(CaptureId, foo_id)

            // The following procedure will save the id of the current
            // capture buffer, change the capture buffer to another buffer,
            // then restore the capture buffer at the end of the procedure.

            integer proc DoWork()
              integer ok                 = TRUE
              integer edit_buffer        = GetBufferId()
              integer new_capture_buffer = CreateTempBuffer()
              integer old_capture_buffer = Set(CaptureId, new_capture_buffer)

              if Query(CaptureId) == new_capture_buffer
                Capture( ... ) // Capture something.
                ...            // Do something with the captured data.
              else
                ok = FALSE
              endif

              Set(CaptureId, old_capture_buffer)
              GotoBufferId(edit_buffer)
              AbandonFile(new_capture_buffer)
              return(ok)
            end DoWork

See Also:   Capture()





CenterFinds

Centers the "found" text (vertically) within the current editing window.

Values:     BOOLEAN

Default:    OFF

Notes:      When CenterFinds is ON, the current cursor line that contains any
            "found" text due to the use of Find(), Replace(), or RepeatFind(),
            will be made the center row of the current window.  If set OFF,
            the current cursor line position within the display does not
            change due to text being "found".

Affects:    Find(), Replace(), RepeatFind()

See Also:   Commands:  HiLiteFoundText(), MarkFoundText()





ChainCmd()

Invokes the command (if any) previously assigned to the keystroke currently
being processed.

Syntax:     ChainCmd()

Returns:    Nothing.

Notes:      ChainCmd() is used when you want to pass control to a command
            that may have been previously assigned to the overridden key
            assignment.

Examples:

            The following macro illustrates a common use for this command.  It
            is assumed that mWordCompletion() is part of a larger external
            macro that is loaded by the user.  (The macros mLookupWord and
            mInsertReplacement are not specified here, but are used for
            example purposes.)  If mWordCompletion decides that it should not
            do anything (for whatever reason), it passes control to a possible
            previous assignment of the <Tab> key by using ChainCmd().

            proc mWordCompletion()
                if mLookupWord()
                    mInsertReplacement()
                else
                    ChainCmd()
                endif
            end

            <Tab>   mWordCompletion()

See Also:   GetKey(), PressKey()

            Variables:  Key





ChangeCurrFilename()

Changes the name of the current file to a new name.

Syntax:     INTEGER ChangeCurrFilename([STRING new_name [, INTEGER flags]])

            • new_name is an optional string expression that becomes the
              current file's new name.

            • flags is an optional integer that affects the operation of
              this command.  Supported values for flags are:

              • _DONT_PROMPT_ instructs the editor to suppress warning or
                informational messages that may be issued for any problems
                that occur when this command is executed.

              • _DONT_EXPAND_ prevents the editor from performing
                ExpandPath() on new_name; but rather accepts the name as is.

              • _OVERWRITE_ instructs the editor to change the name of the
                file even if a file by that name exists on disk.

              Multiple flags can be specified using the bitwise logical OR
              (|) operator.  For example:

              _DONT_PROMPT_ | _OVERWRITE_

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If new_name is not passed, ChangeCurrFilename() prompts for the
            name to use with "New filename:".

            If the drive and/or path are not specified, the current drive
            and/or path are used.

            If ChangeCurrFilename() successfully changes the file's name, the
            file is marked as modified.

            If the filename supplied by the user already exists in the
            editor's Ring of files, the following error message will be
            displayed: "Filename in use Press <Escape>".  The user will then
            be allowed to specify a new name.

            If the filename supplied already exists on disk (and
            _OVERWRITE_ is not specified), the user will receive the
            prompt:

                ┌ Overlay existing file? ┐
                │▒Yes▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
                │ No                     │
                │ Cancel                 │
                └────────────────────────┘

            If "Yes" is selected, the file will be overlaid the next time a
            save command is issued on the current file.

            If "No" or "Cancel" is selected, the user will be allowed to
            specify a new filename.

            If <Escape> is pressed in response to the "New filename:" prompt,
            no action occurs and zero is returned.

            If flags was specified as _DONT_PROMPT_, no prompt is displayed
            for the aforementioned situations, and the command immediately
            returns FALSE.

            This command includes a history list of previous entries passed to
            it.  See AddHistoryStr() for additional information.

See Also:   SaveAs(), RenameDiskFile(), ReplaceFile(), NewFile(),
            AddHistoryStr()

            Variables:  UseCommonDialogs





ChangedFilesExist()

Determines if there are any changed buffers in the editor's Ring of files.

Syntax:     INTEGER ChangedFilesExist()

Returns:    Non-zero if there are any changed buffers loaded; otherwise, zero
            (FALSE).

Notes:      Only buffers with a buffer type of _NORMAL_ (typically, buffers
            used to hold files) are checked.  Buffers with a buffer type of
            _HIDDEN_ or _SYSTEM_ are excluded from this command.  (For more
            information on buffer types, see the BufferType() command.)

See Also:   FileChanged(), BufferType()





ChangeShellPrompt

Causes the editor to add "TSE-Shell" to your command-line prompt whenever you
shell out of the editor, serving as a reminder that you are in an editor
shell.

Values:     BOOLEAN

Default:    ON

Limits:     Has effect at startup only.

Notes:      If you shell out of the editor, you should set ChangeShellPrompt
            ON.  This will serve as a reminder that you are shelled out of the
            editor.  When set ON, the editor will add "TSE-Shell" to your
            prompt.





Changing Position in a File

Moving through a file can be accomplished as simply as one character or line
at a time, or as broadly as going from one end of the file to another - with
many other choices in between.  The commands in this section move the cursor
to a new position in the text.  The text is scrolled only if the text at the
new position is not already displayed in the current window.


Changing Position by One Character or Line
──────────────────────────────────────────

These commands allow you to move the cursor by one character or line at a
time.

▪ CReturn  (<Enter>)

  This command moves the cursor down one line, and places the cursor on the
  next line at the effective left margin.  If Insert mode is ON, the current
  line is split at the cursor position.  (For more information on the effects
  of Insert mode on this command and for a discussion of the effective left
  margin, see "Insert Mode" and "AutoIndent Mode," respectively, in the
  chapter on "Editing Modes.")  When the cursor reaches the bottom edge of
  the window, the text scrolls up.

  If you execute CReturn on the last line of the file, a new line is added at
  the end of the file, and the cursor moves to that line.


  ┌──────────────────────────────── Tip ─────────────────────────────────┐
  │  When the configuration option, "CReturn Equals Next Line" is ON,    │
  │  Insert mode has no effect on the CReturn command.  That is, CReturn │
  │  always behaves as if Insert mode is OFF, and causes the cursor to   │
  │  go to the next line without splitting the current line.  (For more  │
  │  information on this option, see "Text Entry/Block Options" in the   │
  │  chapter on "Configuring the Editor Interactively.")                 │
  └──────────────────────────────────────────────────────────────────────┘


▪ Down  (<CursorDown>)

  This command moves the cursor down in the file by one line.  The column
  position remains unchanged.  When the cursor reaches the bottom edge of the
  window, the text scrolls up.  The cursor stops once it reaches the last line
  in the file.

▪ Up  (<CursorUp>)

  This command moves the cursor up in the file by one line.  The column
  position remains unchanged.  When the cursor reaches the top edge of the
  window, the text scrolls down.  The cursor stops once it reaches the first
  line in the file.


▪ Left  (<CursorLeft>)

  This command moves the cursor one column to the left on the current line. If
  the text was scrolled to the left, the Left command causes the text to
  scroll right when the cursor reaches the left edge of the window.  The
  cursor stops when it reaches column 1.  (For a similar command, see PrevChar
  below.)

▪ Right  (<CursorRight>)

  This command moves the cursor one column to the right on the current line.
  When the cursor reaches the right edge of the window, the text scrolls left.
  If Right is executed beyond the last character on the line, the cursor
  continues moving right on the same line.  The cursor stops once it reaches
  the maximum line length.  (For a similar command, see NextChar below.)


▪ NextChar

  Like the Right command, this command moves the cursor one column to the
  right on the current line.  If the text on the line extends beyond the right
  edge of the window, NextChar causes the text to scroll left.  However, if
  NextChar is executed after the last character on the current line, the
  cursor advances (or wraps) to the beginning of the line below.

▪ PrevChar

  Like the Left command, this command moves the cursor one column to the left
  on the current line.  If the text was scrolled left, PrevChar causes the
  text to scroll right when the cursor reaches the left edge of the window.
  However, if PrevChar is executed at column 1, the cursor moves (or wraps) up
  to the end of the text on the preceding line.


  ┌──────────────────────────────── Tip ─────────────────────────────────┐
  │  The Left and Right commands do not wrap the cursor at the beginning │
  │  and end of the line.  If you would like the <CursorLeft> and        │
  │  <CursorRight> keys to wrap at the beginning and end of a line,      │
  │  reassign those keys to the PrevChar and NextChar commands,          │
  │  respectively.  (For more information on reconfiguring keys, see     │
  │  "Adding or Changing Key Assignments" in the chapter on              │
  │  "Fully Customizing the Editor.")                                    │
  └──────────────────────────────────────────────────────────────────────┘


Changing Position by Multiple Characters or Lines
─────────────────────────────────────────────────

These commands allow you to move the cursor by multiple characters or lines.

▪ BegLine  (<Home>)

  This command moves the cursor to the beginning of the current line,
  scrolling the text as needed.  The cursor is positioned at column 1.

▪ EndLine  (<End>)

  This command moves the cursor to the end of the current line, scrolling the
  text as needed.  The cursor is positioned one column past the last character
  on the line.


  ┌──────────────────────────────── Tip ─────────────────────────────────┐
  │  The last character on a line may or may not be the last white       │
  │  character, depending on the setting of the variable                 │
  │  RemoveTrailingWhite.  If set ON (which is the standard setting),    │
  │  the last character is the last non-white character on a line.  If   │
  │  set OFF, the last character is the last non-white or white (space   │
  │  or tab) character at the end of a line.  (For more information, see │
  │  "Remove Trailing Whitespace" under "Text Entry/Block Options"     │
  │  in the chapter on "Configuring the Editor Interactively.")          │
  └──────────────────────────────────────────────────────────────────────┘


▪ BegFile  (<Ctrl PgUp>)

  This command moves the cursor to the beginning of the current file.  The
  cursor is positioned on the first line, at column 1; or at the same column
  position if a column block has been opened and not yet closed.

▪ EndFile  (<Ctrl PgDn>)

  This command moves the cursor to the end of the current file.  The cursor is
  positioned on the last line, one column past the last character; or at the
  same column position if a column block has been opened and not yet closed.


▪ BegWindow  (<Ctrl Home>)

  This command moves the cursor to the first line of text in the current
  window.  The column position remains unchanged.

▪ EndWindow  (<Ctrl End>)

  This command moves the cursor to the last line of text in the current
  window.  The column position remains unchanged.

▪ GotoColumn  (<Ctrl C>, or "Go to Column" under Search Menu)

  This command moves the cursor to the specified column on the current line.

  When you execute GotoColumn, the editor displays the prompt, "Go to
  column:".  Type the appropriate column number and press <Enter>.  The cursor
  then moves to the column number specified.

  You can designate a column position relative to the current column by
  preceding the column number with "+" to move to the right of the current
  column, or with "-" to move to the left of the current column.  For example,
  enter "+20" at the "Go to column:" prompt to move the cursor 20 columns to
  the right of its current position.

▪ GotoLine  (<Ctrl J>, or "Go to Line" under Search Menu)

  This command scrolls the text of the current file so that the specified line
  becomes the current line.  The cursor does not change its position relative
  to the screen.

  When you execute GotoLine, the editor displays the prompt, "Go to line:".
  Type the appropriate line number and press <Enter>.  The text is scrolled to
  make the specified line the current line.

  You can designate a line relative to the current line by preceding the line
  number with "+" to specify a line after the current line, or with "-" to
  specify a line before the current line.  For example, enter "-50" at the "Go
  to Line:" prompt to scroll to the line that is 50 lines before the current
  line.


▪ PrevPosition  (<Ctrl Q P>)

  This command moves the cursor to the line and column at which it was
  previously positioned, immediately prior to moving to the current line.

  For example, suppose you are in the middle of a file and you issue the
  BegFile command to go to the beginning of the file.  After viewing the text
  at the beginning, you then wish to return to your previous position in the
  middle.  Provided you have not moved the cursor off the beginning line of
  the file (where it was initially placed by BegFile), you can then execute
  PrevPosition and the cursor will immediately move to the previous line.
  (Changing the column position on the new line does not affect the behavior
  of PrevPosition.)


▪ WordLeft  (<Ctrl CursorLeft>)

  This command moves the cursor to the first character of the word that begins
  to the left of the cursor on the current line.  If you execute this command
  from the first character of the first word on the current line, the cursor
  moves to the end of the previous line.  (For more information on how the
  editor defines a word, see "WordSet Characters" under
  "Command/Format Options" in the chapter on
  "Configuring the Editor Interactively.")

▪ WordRight  (<Ctrl CursorRight>)

  This command moves the cursor to the first character of the word that begins
  to the right of the cursor on the current line.  If you execute this command
  on the last word of the current line, the cursor moves to the end of the
  line. If you execute WordRight beyond the last word, the cursor moves to the
  first character of the first word on the line below.  (For more information
  on how the editor defines a word, see "WordSet Characters" under
  "Command/Format Options" in the chapter on
  "Configuring the Editor Interactively.")


▪ BegPara

  This command moves the cursor to the first line of the current paragraph (or
  current function/procedure), scrolling the text as needed.  The column
  position remains unchanged.  If the beginning of the paragraph cannot be
  determined, the cursor does not move.

  A "paragraph," as defined by this command, is based on the file type
  (extension) of the current file:

    • For certain programming-language file types, a paragraph is a function
      or procedure.  Supported file types include SAL (.s, .ui), C (.c, .h),
      C++ (.cpp, .hpp), Pascal (.pas), and xBase (.prg, .spr, .mpr, .qpr,
      .fmt, .frg, .lbg, .ch).

    • For non-programming-language file types (or other non-supported
      programming-language file types), a paragraph is any contiguous group of
      non-blank lines.

▪ EndPara

  This command moves the cursor to the last line of the current paragraph (or
  current function/procedure), scrolling the text as needed.  The column
  position remains unchanged.  If the end of the paragraph cannot be
  determined, the cursor does not move.

  A "paragraph", as defined by this command, is based on the file type
  (extension) of the current file:

    • For certain programming-language file types, a paragraph is a function
      or procedure.  Supported file types include SAL (.s, .ui), C (.c, .h),
      C++ (.cpp, .hpp), Pascal (.pas), and xBase (.prg, .spr, .mpr, .qpr,
      .fmt, .frg, .lbg, .ch).

    • For non-programming-language file types (or other non-supported
      programming-language file types), a paragraph is any contiguous group of
      non-blank lines.


▪ NextPara  (<Shift PgDn>)

  This command moves the cursor to the first line of the next paragraph (or
  next function/procedure), scrolling the text as needed.  The column position
  remains unchanged.  If the next paragraph cannot be determined, the cursor
  does not move.

  A "paragraph", as defined by this command, is based on the file type
  (extension) of the current file:

    • For certain programming-language file types, a paragraph is a function
      or procedure.  Supported file types include SAL (.s, .ui), C (.c, .h),
      C++ (.cpp, .hpp), Pascal (.pas), and xBase (.prg, .spr, .mpr, .qpr,
      .fmt, .frg, .lbg, .ch).

    • For non-programming-language file types (or other non-supported
      programming-language file types), a paragraph is any contiguous group of
      non-blank lines.

▪ PrevPara  (<Shift PgUp>)

  This command moves the cursor to the first line of the current paragraph (or
  the current function/procedure); or to the first line of the previous
  paragraph (or previous function/procedure), if the cursor is already on the
  first line of the paragraph.  The text is scrolled as needed.  The column
  position remains unchanged.  If the previous paragraph cannot be determined,
  the cursor does not move.

  A "paragraph", as defined by this command, is based on the file type
  (extension) of the current file:

    • For certain programming-language file types, a paragraph is a function
      or procedure.  Supported file types include SAL (.s, .ui), C (.c, .h),
      C++ (.cpp, .hpp), Pascal (.pas), and xBase (.prg, .spr, .mpr, .qpr,
      .fmt, .frg, .lbg, .ch).

    • For non-programming-language file types (or other non-supported
      programming-language file types), a paragraph is any contiguous group of
      non-blank lines.





Changing Window Size and Orientation

When two or more windows are opened, you can adjust the size of any of the
windows.  The minimum size for a window is four lines by fifteen columns.
When you change the size of one window, compensating changes are made to the
window(s) adjacent to the side you adjust.

The following commands allow you to change the size of the current window.

▪ ResizeWindow  (<Ctrl O R>, or "Resize" under Window Menu)

  This command allows you to change the size of the current window by moving
  an interior window edge.  When you execute this command, the editor displays
  the following StatusLine prompt to request the window edge you want to move:

      Select window edge to resize (press cursor key):

  Press the cursor key (left, right, up, or down) that points toward the
  appropriate edge.  The edge you select must be an interior edge; that is, it
  must be an edge that is adjacent to another window.  Once you select the
  edge to resize, a resizing bar appears and the editor displays the following
  StatusLine prompt:

      Press cursor keys to resize, <Escape> to cancel, <Enter> when done:

  Press the cursor keys to move the resizing bar either up and down (if you
  selected the top or bottom window edge), or left and right (if you selected
  the left or right window edge).  Note that the minimum window size indicated
  earlier may affect the edge you wish to adjust.  Press <Enter> to complete
  the resizing operation, or press <Escape> to cancel the operation and keep
  the window size as it was before you executed this command.

  Note that you can resize a particular window edge only if its length is
  either the same as the length of the adjacent window edge, or is the same as
  the total length of all edges adjacent to the window edge being resized.
  For example, in the screen illustrations presented earlier in this chapter,
  you can resize the lower edge of window 1; however, you cannot resize the
  upper edge of window 2 or the upper edge of window 3.  You can also resize
  the shared inside vertical edge of windows 2 and 3.  (There are no other
  edges in those illustrations that can be resized.)

▪ ZoomWindow  (<Ctrl O Z>, or "Zoom" under Window Menu)

  This command expands the current window so that it covers the entire screen
  and temporarily hides all other windows.  A full border is placed around the
  editing window.  ZoomWindow leaves the other windows intact, though hidden
  from view.  To restore all previous windows to the screen, execute the
  ZoomWindow command again.

  While a window is zoomed on the screen, the window number that is displayed
  on the title line is temporarily replaced with a "Z".  Once the previous
  windows are restored to the screen, the appropriate window number is also
  restored.  (If you are using a mouse, the "Z" is not displayed.)


When exactly two windows are opened, you can use the ToggleHorizVertical
command to change the window orientation from horizontal to vertical, or
from vertical to horizontal.

▪ ToggleHorizVertical  ("Toggle Horiz/Vertical" under Window Menu)

  This command toggles the screen between horizontal and vertical
  windows, if exactly two windows are open.  If the screen is split into
  two vertical windows, the windows will be changed to horizontal
  windows; if the screen is split into two horizontal windows, the
  windows will be changed to vertical windows.

  This command does not do anything if there is only one window on the
  screen, nor if there are more than two windows.





ChDir()

Changes to the indicated directory.

Syntax:     INTEGER ChDir(STRING dir)

            • dir is the name of the directory to change to.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If the directory specification contains a drive, and it is
            different than the current drive, the current drive and directory
            are not changed.  To change the current drive (and directory), use
            the LogDrive() command.

            The trailing slash is accepted but not required (unless you are
            changing to the root directory).

Examples:

            // Make \foo the current directory, on the current drive
            ChDir("\foo")

            // Make \plans the current directory on the c: drive.
            // The current drive does not change.
            ChDir("c:\plans")

            // Make c:\plans the current drive and directory
            LogDrive("c")
            ChDir("\plans")

See Also:   GetDir(), CurrDir(), LogDrive()





CheckDefaultExt()

Checks an extension against the default file extension list (as specified by
the DefaultExt variable).

Syntax:     INTEGER CheckDefaultExt(STRING ext)

            • ext is the file extension to check.  The leading period is
              optional.

Returns:    Non-zero if the passed extension is in the default file extension
            list; otherwise, zero (FALSE).

Examples:

            if CheckDefaultExt("bat")
                Message("bat is a default extension")
            else
                Message("bat is not a default extension")
            endif

See Also:   Variables:  DefaultExt





Checking Your Spelling

To assist in verifying and correcting the spelling in your files, the editor
includes a built-in spelling checker, SpellCheck.  When invoked, SpellCheck
examines the words in the current file (or in the indicated portion of the
file) and attempts to match each word against the entries in the available
SpellCheck word list(s).  If no match for a particular word is found,
SpellCheck gives you several options for dealing with that word, including
options to modify the word, ignore the word, or add the word to your own
supplementary user-defined word list.

This chapter provides the following information on SpellCheck:

    • Running SpellCheckThe user-defined word listFiles needed by SpellCheck





ChooseFont()

Returns information about a font selected from the standard ChooseFont dialog
box.

This command has no effect in the Console version of the editor.

Syntax:     INTEGER ChooseFont(VAR STRING fontname, VAR INTEGER pointsize,
                VAR INTEGER flags)

            • fontname is the name of the selected font.  Examples are
              "Terminal" and "Courier".

            • pointsize identifies the font size.

            • flags can be any combination of _FONT_BOLD_ and/or _FONT_OEM_ or
              just 0.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command displays a dialog box, allowing the user to select
            a particular font.  Once selected, the information about the
            font is returned in the appropriate variables.

            The selected font is not used by the editor.  Information about
            the font is simply returned.  In order for the editor to use this
            font, the SetFont() command would need to be called, passing the
            appropriate information.

            Contrast this command with the GetFont() command, which returns
            information about the font that is being used for the editing
            display.

Examples:

            string fontname[255]
            integer pointsize, flags

            if ChooseFont(fontname, pointsize, flags)
                ...

            // at this point fontname, pointsize, and flags are set to
            // describe the selected font.

See Also:   GetFont(), SetFont(), GetCharWidthHeight(), ResizeFont()





Chr()

Returns the single-character string equivalent of the passed integer.

Syntax:     STRING Chr(INTEGER i)

            • i is the integer for which the string equivalent is to be
              returned.  Valid values for i are 0..255 inclusive.  Since
              Chr() is evaluated at compile time, if i is a constant value,
              and outside of the valid range, a compiler syntax error will be
              issued when this statement is compiled.

Returns:    The single character string value of the passed integer.

Examples:

            Assume the existence of a string variable, s:

            s = Chr(97)        // s is "a"

            In the next example, if the current character in the file (the
            character at the cursor position) is B, then s is "B":

            s = Chr(CurrChar())

See Also:   Asc(), Val(), Str()





ChrSet()

Used to create the string to be assigned to the WordSet variable.


Syntax:     STRING ChrSet(STRING s)

            • s is a string that contains the characters to be considered as
              part of the set.  The user may specify a range of characters by
              placing a dash ("-") between the first and last characters of
              the range.



Returns:    A bit-encoded 32-character string of the set of characters
            supplied in s.

Notes:      This command is used solely in conjunction with the WordSet
            variable.


            The slash ("\") character is used as an escape character.  In
            order to include a slash in the set, use two slashes ("\\").

            The \dnnn notation or \xnn notation, where nnn is a decimal
            number, and nn is a hexadecimal number, is allowed in
            specifications.

            To include the dash in the set, place it as either the first or
            last character.

            The "~" character is used as "not in this set," if it occurs as
            the first character.

            To set the WordSet variable within a config/endconfig construct,
            you must use the following format:

            WordSet = ChrSet("A-Za-z")

Examples:

            In the following example procedure, the WordSet is saved to a
            local variable at the beginning, then restored to the original
            value at the end:

            proc foo()
                string saved_wordset[32]      // must be 32 chars

                // save current WordSet and set the new one
                saved_wordset = Set(WordSet, ChrSet("a-z"))

                // user code to do something goes here

                // then restore the original WordSet
                Set(WordSet, saved_wordset)
            end

            // make WordSet everything but a-z
            Set(WordSet, ChrSet("~a-z"))

            // make WordSet all characters
            Set(WordSet, ChrSet("\d000-\d255")

See Also:   WordRight(), WordLeft(), MarkWord(), DelLeftWord(),
            DelRightWord()

            Variables:  WordSet





ClearBit()

Sets the specified bit to 0.

This command is intended for ADVANCED USAGE.

Syntax:     ClearBit(STRING bitset, INTEGER bit)

            • bitset is the bit-mapped string in which to clear a
              particular bit.

            • bit is the specific bit number to be cleared.

Returns:    Nothing.

Notes:      The editor uses bit-mapped strings for the WordSet variable
            and the TabSet() command.  SetBit(), ClearBit(), and GetBit()
            can be used to modify these values.

            Bit numbering starts at 0.

            Warning:  No checks are done to verify that bit is valid.  For
            example, given a string that is 10 characters long means that
            there are 80 bits available (8 bits per character/byte * 10 =
            80, bits 0 - 79).  Specifying a value greater than 79 would be
            out of bounds for this string, but this boundary condition is not
            checked!

Examples:

            Suppose you want to remove the "_" character from the WordSet
            without changing the other WordSet characters.  Since the WordSet
            variable is stored as a bit string (256 bits, stored in 32
            bytes), the ClearBit() command is just right for the job:

            string word_set[32]

            word_set = Query(WordSet)       // get the WordSet
            ClearBit(word_set, ASC('_'))    // clear appropriate bit
            Set(WordSet, word_set)          // and reset it

            See the WordSet variable for additional information.

See Also:   SetBit(), GetBit(), TabSet()

            Variables:   WordSet





ClearBufferDaTmAttr()

Clears the date, time, size and attribute fields for the current buffer.

Syntax:     ClearBufferDaTmAttr()

Returns:    Nothing.

Notes:      For each file loaded, the editor maintains a record of the file's
            date, time, size, and file attributes, as of the time the file
            was loaded into the editor, or the last time it was saved.
            ClearBufferDaTmAttr() will set these fields to zero.

            When a file is edited that does not have an associated file on
            disk, this command is invoked.

            When the SaveFile() command is executed, the editor uses this file
            information to determine if the file on disk has been changed by
            another process.

See Also:   UpdateBufferDaTmAttr(), GetBufferDaTmAttr()





ClearUndoRedoList()

Clears all Undo/Redo information associated with the current file.

Syntax:     ClearUndoRedoList()

Returns:    Nothing.

See Also:   Undo(), Redo(), SetUndoOn(), SetUndoOff(), UndoCount(),
            RedoCount(), UndoMode()

            Variables:  KeepUndoBeyondSave





ClipBoardId

Determines the id of the ClipBoard used by Cut(), Copy() and Paste() commands.

Values:     INTEGER

Default:    Undefined

Limits:     Cannot be used within a config/endconfig construct.

Notes:      ClipBoardId can be used to set up and control a user-defined
            ClipBoard, without affecting the system ClipBoard.

            To use ClipBoardId in a macro to set up the user's own ClipBoard
            (so that macros do not change the contents of the default
            ClipBoard), first retrieve and store the default ClipBoard id so
            that it can later be restored at the end of the macro.

Examples:

            // To retrieve the current ClipBoardId:
            id = Query(ClipBoardId)

            // To set the current ClipBoardId to foo_id:
            Set(ClipBoardId, foo_id)

            // To retrieve the current ClipBoardId, and set it to foo_id:
            id = Set(ClipBoardId, foo_id)

            The following procedure will save the id of the current
            ClipBoard, change the ClipBoard to another buffer, then restore
            the ClipBoard at the end of the procedure.

            integer proc DoWork()
                integer original = Set(ClipBoardId, CreateTempBuffer())

                if original == Query(ClipBoardId)
                    return (FALSE)
                endif

                DoSomething()               //Do something

                Set(ClipBoardId, original)  //restore ClipBoard
                return(TRUE)
            end

Affects:    Cut(), Copy(), Paste()

See Also:   Commands:  CreateBuffer(), CreateTempBuffer()





ClosePrint()

Closes the print device, if opened as a file.

Syntax:     ClosePrint()

Returns:    Nothing.

Notes:      The PrintDevice can be set to a filename, allowing print
            operations to be routed to a file.  The file will not be opened
            until the first PrintChar() command is invoked, but will remain
            open so that subsequent PrintChar() commands will print to the
            same file.  In order to edit, view, or otherwise manipulate the
            file, it must first be closed.  Use the ClosePrint() command to
            close the file.  Once the file has been closed, a subsequent call
            to the PrintChar() command (assuming that the PrintDevice has not
            been changed) will reopen the file and all data previously in the
            file will be lost.

            The commands PrintFile() and PrintBlock() call ClosePrint() upon
            completion.

See Also:   PrintChar()

            Variables:  PrintDevice





CloseWindow()

Closes the current editing window.

Syntax:     INTEGER CloseWindow()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If only one window is open or the current window is zoomed,
            CloseWindow() returns zero.

            Adjacent editing windows grow to fill the space of the closed
            window.  The cursor is placed in the window that occupies the
            space the closed window was in.

See Also:   HWindow(), VWindow(), OneWindow(), DelWindow()





Closing Editing Windows

Any windows that you no longer need can be closed, and thereby removed from
the screen.

The following commands allow you to close windows.  With the first group of
commands, the file that was displayed in the window remains open after the
window is removed.

▪ CloseWindow  (<Ctrl O C>, or "Close" under Window Menu)

  This command closes the current window.  The current window disappears, and
  an adjacent window(s) expands to fill the vacated space.  The cursor is
  placed in an adjacent window, making it the new current window.

▪ DelWindow  (<Ctrl O D>)

  This command closes (or deletes) a window adjacent to the current window.

  When you execute this command with more than two windows on the screen, the
  editor displays the following StatusLine prompt to request the window to
  close:

      Delete window (press cursor key):

  Press the cursor key (left, right, up, or down) that points toward the
  appropriate window.  A window(s) adjacent to the deleted window expands to
  fill the vacated space.

  When you execute this command with only two windows on the screen, the
  editor automatically closes the non-current window, and the current window
  expands to fill the entire screen.  In this case, DelWindow behaves the same
  as OneWindow, which is described below.

▪ OneWindow  (<Ctrl O O>, or "One" under Window Menu)

  This command closes all windows except the current window.  The current
  window then fills the entire screen.

  Do not confuse the OneWindow command with ZoomWindow.  While both commands
  cause the current window to fill the screen, OneWindow CLOSES all other
  windows.  ZoomWindow only temporarily HIDES all other windows.

The following command can be used to close the current window, and also close
the file in that window.

▪ CloseFileAndWindow  ("Close File & Window" under Window Menu)

  This command prompts you to save the file in the current window (if
  modified), and then closes (or "quits") the file.  (For more information on
  closing a file, see the QuitFile command in the chapter on
  "Loading, Processing, and Saving Files.")

  The current window is then closed (if there are multiple windows on the
  screen).  That window disappears, and an adjacent window(s) expands to fill
  the vacated space.  The cursor is placed in an adjacent window, making it
  the new current window.





ClrEol()

Blanks the display from the current video output position to the end of the
current line of the video output window.

Syntax:     ClrEol()

Returns:    Nothing.

Notes:      This is a video output command.  It has no effect on the actual
            text in the buffer.  It only affects what is displayed on the
            screen.

            Make sure the video output position has been positioned on the
            screen (via GotoXY() or VGotoXY()) before calling this command.

            For more information on video output commands, see
            "Video Output Commands" in the chapter on
            "Using Macro Language Features."

See Also:   ClrScr(), GotoXY(), VGotoXY(), VGotoXYAbs(), VHomeCursor()





ClrScr()

Blanks the current video output display window.

Syntax:     ClrScr()

Returns:    Nothing.

Notes:      This is a video output command.  It has no effect on the actual
            text in the buffer.  It only affects what is displayed on the
            screen.

            For more information on video output commands, see
            "Video Output Commands" in the chapter on
            "Using Macro Language Features."

See Also:   ClrEol(), VGotoXY(), VGotoXYAbs(), GotoXY(), VHomeCursor()





CmpiStr()

Compares two strings in a case-insensitive manner.

Syntax:     INTEGER CmpiStr(STRING s1, STRING s2)

            • s1 is the first string to be compared.

            • s2 is the second string to be compared

Returns:    0 if s1 is equal s2, otherwise, -1 if s1 is lexically
            less than s2, or +1 if s1 is lexically greater than s2.

Notes:      This command is provided as an adjunct to the normal string
            comparison operator, "==".  The "==" compares strings in a
            case sensitive manner.  CmpiStr() makes it easy to compare two
            strings for equality, regardless of their case.

            When to use CmpiStr() vs. EquiStr()

            If you want to know if two strings are equal, ignoring
            differences in case, use EquiStr().

            If you want to know the lexical ordering of two strings (if one
            is less than or greater than the other), use CmpiStr().

Examples:

            if CmpiStr(s1, s2) == 0
                Message("s2 and s2 are the same")
            elseif CmpiStr(s1, s2) <> 0
                Message("s1 is different than s2")

                if CmpiStr(s1, s2) > 0
                    Message("s1 is > s2")
                elseif CmpiStr(s1, s2) < 0
                    Message("s1 is < s2")
                endif
            endif

See Also:   EquiStr()





Color()

Returns the integer value of the requested color combination.

Syntax:     INTEGER Color([INTENSE] [BRIGHT] foreground [ON background])

            • Valid foreground and background colors are Black, Blue,
              Green, Cyan, Red, Magenta, Yellow, White.

            • The optional keywords, INTENSE and BRIGHT, allow you to select
              an intense color (INTENSE) or a bright color (BRIGHT).

Returns:    The integer value of the requested color combination.

Notes:      Because of PC hardware design, pre-defined colors may not always
            be what the user expects.  White is actually grey.  To get white,
            use "BRIGHT White".

Examples:

            The following will set the current video attribute to a white
            foreground on a blue background.

            Set(Attr, Color(BRIGHT White ON Blue))

See Also:   PutAttr()

            Variables:  Attr





COLOR Set

The standard set of color variables.

Values:     INTEGER - [0..255]

Limits:     None.

See Also:   Commands:  Color()

Following are the color variables, including a description and the default
value of each.

Text Color Variables
────────────────────────────

CursorAttr

            Text on the cursor line.

            Default: 176  or  Color(Intense Black on Cyan)

TextAttr

            Text that is not on the cursor line nor in a marked block.

            Default: 240  or  Color(Intense Black on White)

HiLiteAttr

            Highlighted text located by a search command.

            Default: 116  or  Color(Red on White)

BlockAttr

            Text within a marked block.

            Default:  15  or  Color(Bright White on Black)

CursorInBlockAttr

            Text on the cursor line within a block.

            Default: 112  or  Color(Black on White)


Window Border Variables
───────────────────────────────

CurrWinBorderAttr

            Border for the current window.

            Default: 240  or  Color(Intense Black on White)

OtherWinBorderAttr

            Border for non-current windows.

            Default: 241  or  Color(Intense Blue on White)


Menu/HelpLine Color Variables
─────────────────────────────────────

MenuTextAttr

            Enabled selection items in a menu, and command/option names in a
            HelpLine.

            Default: 112  or  Color(Black on White)

MenuTextLtrAttr

            Quick-key letters in a menu, and HelpLine key assignments.

            Default: 116  or  Color(Red on White)

MenuBorderAttr

            Menu borders.

            Default: 112  or  Color(Black on White)

MenuSelectAttr

            Menu selection cursor bar for enabled menu items.

            Default:  31  or  Color(Bright White on Blue)

MenuSelectLtrAttr

            Menu selection quick-key letter.

            Default:  28  or  Color(Bright Red on Blue)

MenuGrayAttr

            Disabled "grayed" selection items in a menu.

            Default: 120  or  Color(Bright Black on White)

MenuSelectGrayAttr

            Menu selection cursor bar for disabled "grayed" menu items.

            Default:  23  or  Color(White on Blue)


HelpSystem Color Variables
──────────────────────────────────

HelpTextAttr

            Normal text in the HelpSystem.

            Default:  23  or  Color(White on Blue)

HelpLinkAttr

            Links to the next topic in the HelpSystem.

            Default:  30  or  Color(Bright Yellow on Blue)

HelpInfoAttr

            InfoBox items in the HelpSystem.

            Default:  26  or  Color(Bright Green on Blue)

HelpBoldAttr

            Highlighted (bold) text in the HelpSystem.

            Default:  31  or  Color(Bright White on Blue)

HelpItalicsAttr

            "Italicized" text in the HelpSystem.

            Default:  29  or  Color(Bright Magenta on Blue)

HelpSelectAttr

            Selected field in the HelpSystem.

            Default:  113 or  Color(Blue on White)


SyntaxHilite Color Variables
────────────────────────────────────

Directive1Attr

            SyntaxHilite directive text, entry 1.

            Default: 244  or  Color(Intense Red on White)

Directive2Attr

            SyntaxHilite directive text, entry 2.

            Default: 244  or  Color(Intense Red on White)

Directive3Attr

            SyntaxHilite directive text, entry 3.

            Default: 244  or  Color(Intense Red on White)

KeyWords1Attr

            SyntaxHilite keyword text, group 1.

            Default: 249  or  Color(Intense Bright Blue on White)

KeyWords2Attr

            SyntaxHilite keyword text, group 2.

            Default: 246  or  Color(Intense Yellow on White)

KeyWords3Attr

            SyntaxHilite keyword text, group 3.

            Default: 253  or  Color(Intense Bright Magenta on White)

KeyWords4Attr

            SyntaxHilite keyword text, group 4.

            Default: 252  or  Color(Intense Bright Red on White)

KeyWords5Attr

            SyntaxHilite keyword text, group 5.

            Default: 243  or  Color(Intense Cyan on White)

KeyWords6Attr

            SyntaxHilite keyword text, group 6.

            Default: 243  or  Color(Intense Cyan on White)

KeyWords7Attr

            SyntaxHilite keyword text, group 7.

            Default: 249  or  Color(Intense Bright Blue on White)

KeyWords8Attr

            SyntaxHilite keyword text, group 8.

            Default: 249  or  Color(Intense Bright Blue on White)

KeyWords9Attr

            SyntaxHilite keyword text, group 9.

            Default: 249  or  Color(Intense Bright Blue on White)

NumberAttr

            SyntaxHilite number text.

            Default: 245  or  Color(Intense Magenta on White)

MultiLnDlmt1Attr

            SyntaxHilite multi-line delimited text, entry 1.

            Default: 242  or  Color(Intense Green on White)

MultiLnDlmt2Attr

            SyntaxHilite multi-line delimited text, entry 2.

            Default: 242  or  Color(Intense Green on White)

MultiLnDlmt3Attr

            SyntaxHilite multi-line delimited text, entry 3.

            Default: 242  or  Color(Intense Green on White)

SingleLnDlmt1Attr

            SyntaxHilite single-line delimited text, entry 1.

            Default: 242  or  Color(Intense Green on White)

SingleLnDlmt2Attr

            SyntaxHilite single-line delimited text, entry 2.

            Default: 242  or  Color(Intense Green on White)

SingleLnDlmt3Attr

            SyntaxHilite single-line delimited text, entry 3.

            Default: 242  or  Color(Intense Green on White)

ToEOL1Attr

            SyntaxHilite to-EOL delimited text, entry 1.

            Default: 242  or  Color(Intense Green on White)

ToEOL2Attr

            SyntaxHilite to-EOL delimited text, entry 2.

            Default: 242  or  Color(Intense Green on White)

ToEOL3Attr

            SyntaxHilite to-EOL delimited text, entry 3.

            Default: 242  or  Color(Intense Green on White)

Quote1Attr

            SyntaxHilite quote delimited text, entry 1.

            Default: 245  or  Color(Intense Magenta on White)

Quote2Attr

            SyntaxHilite quote delimited text, entry 2.

            Default: 245  or  Color(Intense Magenta on White)

Quote3Attr

            SyntaxHilite quote delimited text, entry 3.

            Default: 245  or  Color(Intense Magenta on White)

IncompleteQuoteAttr

            SyntaxHilite incomplete quote text.

            Default: 192  or  Color(Intense Black on Red)


Other Color Variables
─────────────────────────────

EOFMarkerAttr

            End-of-file marker.

            Default: 112  or  Color(Black on White)

MsgAttr

            Messages and warnings.

            Default: 112  or  Color(Black on White)

StatusLineAttr

            StatusLine.

            Default:  31  or  Color(Bright White on Blue)

LineNumbersAttr

            LineNumbers.

            Default: 112  or  Color(Black on White)





COLOR VARIABLES

The editor allows you to set different colors for many items on the editor's
screen display, using the variables described in this section.


Colors are set by assigning to a color variable the number associated with the
desired foreground/background color.  You can use the Color() command to
return the number of the color attribute you want to assign to the color
variable, or you can enter a color directly if you know the decimal value of
the color combination.





Command Prompts

As listed above, three types of command prompts are issued by the editor:
prompt boxes, StatusLine prompts, and selection menus.  Prompt boxes request
additional user-defined string input; StatusLine prompts generally request a
single character or keystroke response; selection menus display a set of
pre-defined selections from which to choose.  The editor's Menu system uses
the following notations to indicate that a command issues a prompt when
executed:

    • A series of three dots ("...") follows a command entry that issues a
      prompt box or StatusLine prompt.  This notation is also used to identify
      a command that issues a PickList.

    • The symbol "►" follows a command entry that issues a selection menu.


Prompt Box
──────────

For those commands which require additional string input in order to continue,
a prompt box is displayed on the screen once the command is executed.  Within
the prompt box, a number of editing commands and special prompt features are
available to simplify entry of the desired string response.

The following table identifies commands that are operational in prompt boxes:

                   COMMANDS OPERATIONAL IN PROMPT BOXES


                Key/Mouse
   Command      Assignment*             Operation within Prompt Box
 ____________   __________________   ___________________________________

 CReturn        <Enter>*             Accepts user entry.
                or <LeftBtn>*

 Escape         <Escape>*            Cancels command or operation.
                or <RightBtn>*

 Exit           <Alt X>              Cancels command or operation.

 BackSpace      <Backspace>*         Deletes character to left of cursor
                or <Ctrl H>*         in prompt box; any text to right of
                                     cursor is shifted left.

 DelChar        <Del>*               Deletes character at cursor
                                     position in prompt box.

 DelLeftWord    <Ctrl Backspace>     Deletes all/part of word to left of
                                     cursor in prompt box.


 DelRightWord   <Ctrl Del>           Deletes all/part of word from and
                or <Ctrl T>          to right of cursor in prompt box.

 DelLine        <Alt D>              Deletes contents of prompt box.

 DelToEol       <F6>                 Deletes text from and to right of
                or <Alt Del>         cursor position in prompt box.

 BegLine        <Home>*              Moves cursor to beginning of prompt
                                     box.

 EndLine        <End>*               Moves cursor to end of prompt
                                     string.

 Left           <CursorLeft>*        Moves cursor left in prompt box.

 Right          <CursorRight>*       Moves cursor right in prompt box.

 Down           <CursorDown>*        Pops up History box.

 Up             <CursorUp>*          Pops up History box.

 WordLeft       <Ctrl CursorLeft>    Moves cursor to first character of
                                     word left of cursor in prompt box.

 WordRight      <Ctrl CursorRight>   Moves cursor to first character of
                                     word right of cursor in prompt box.

 TabRight       <Tab>*               Filename completion.

 AsciiChart     <Ctrl A>*            Pops up ASCII chart.


 Help           <F1>*                Relevant Help (if available).

 Dos            <Alt F9>             Displays "OS command:" prompt
                                     for execution of external command.

 Shell          <F9>                 Temporarily suspends editor and
                                     opens an OS prompt.

 Copy           <Grey+>              Copies text in prompt box to System
                                     ClipBoard.

 Cut            <Grey->              Cuts text in prompt box to System
                                     ClipBoard.


 CopyBlock      <Alt C>              Copies marked block into prompt
                                     box.  If no block marked, copies
                                     word at cursor position in text.

 CopyToWinClip  <CtrlShift Grey+>    Copies text in prompt box to
                or <Ctrl Ins>        Windows Clipboard.

 CutToWinClip   <CtrlShift Grey->    Cuts text in prompt box to
                or <Shift Del>       Windows Clipboard.

 ListRecentFiles  <Ctrl 0>           Displays Recent Files list; places
                                     selected filename into prompt box.


 Literal        <Ctrl P>             Places literal representation of
                                     a character into prompt box at
                                     cursor position.  ("Literal:"
                                     StatusLine prompt is not
                                     displayed; however, character
                                     entered following execution of
                                     Literal command is processed.)

 Paste          <Grey*>              Pastes contents of System ClipBoard
                                     into prompt box.

 PasteFromWinClip <CtrlShift Grey*>  Pastes contents of Windows
                or <Shift Ins>       Clipboard into prompt box.


 ToggleInsert   <Ins>*               Toggles Insert mode ON and OFF.



 Keyboard Macro                      You can run a keyboard macro
                                     by pressing it's assigned key
                                     while in a prompt box.
                                     Use with caution.  If the
                                     keyboard macro contains commands
                                     which are not valid with a prompt
                                     box, undesirable results may occur.

 * An "*" following a key/mouse assignment indicates the editor has
   forced that key or mouse button to invoke the indicated command in a
   prompt box, regardless of how that key or mouse button is configured
   by the user.  For all other key/mouse assignments listed, if the user
   has reconfigured the command, the command is invoked by pressing the
   user-defined key or mouse button.


When a prompt box is displayed, it is placed on the screen immediately above
the cursor line.  If there is not enough room to place the entire prompt box
above the cursor line, it is placed immediately below the cursor line.

Within a prompt box, string input is entered by typing characters and/or
executing any of the commands listed above.  The numeric keypad can also be
used to input the decimal value of a character that is not directly available
from the keyboard.  (For more information on using the numeric keypad to input
characters, see the Tip under "Commands to Add Text" in the chapter on
"Manipulating Text.")

After your response is completed, press <Enter> for the operation to continue.
To cancel an operation from a prompt box, press <Escape>.


History Buffer for Prompt Boxes

The editor maintains a History Buffer that contains response strings
previously entered within prompt boxes.  This allows you to view and select
entries from a pop-up History box containing previous responses for a
particular command or group of related commands.  Certain groups of commands
share the same set of History entries.  For example, the commands EditFile,
InsertFile, SaveAs, and SaveBlock share the same set of History entries; the
Search prompts for the Find and Replace commands also share the same set.

As each response to a prompt box is entered, it is added to the top of the
History Buffer.  If that entry already exists in the History Buffer for the
same command or command group, the prior entry is deleted.

For each subsequent execution of a particular command (or command group), the
prompt box initially displays the last response string that was processed.  To
enter a response, you have the following options:

    • To enter the same response as the one displayed, simply press <Enter>.

    • To enter a modified response from the one that is displayed, first
      execute one of the cursor-movement commands (BegLine, EndLine, Left,
      Right, Down, Up), one of the deletion commands (BackSpace, DelChar,
      DelLine, DelToEol), the AsciiChart command, or the ToggleInsert command.
      This makes the displayed response active, and allows it to be modified.
      Now you can make desired changes to the response string.  Press <Enter>
      when the string is complete.

    • To automatically discard the response that is displayed and enter a new
      response, immediately begin typing the new string, and/or use the
      CopyBlock, Literal, or Paste commands to input a new string within the
      prompt box.  Press <Enter> when the string is complete.

    • To select a previous response, press <CursorDown> or <CursorUp> to pop
      up a History box containing a PickList of History Buffer entries for the
      command.  Position the cursor bar on the desired response and press
      <Enter> to select that entry, or press <Escape> to remove the History
      entries without selecting a previous response.  (For more information on
      how to select entries from a PickList, see "Using PickLists" later in
      this chapter.)  The selected entry is then placed in the prompt box, and
      you can make any desired changes to the response string.  Press <Enter>
      when the string is complete.


The editor gives you the option to maintain History entries across editing
sessions, via the PersistentHistory variable.  If PersistentHistory is ON,
the entries in the History Buffer are saved at the end of each editing
session, and then reloaded into the History Buffer at the start of the next
editing session.  (For more information, see
"Saving/Restoring Entries in the History Buffer" in the chapter on
"Loading, Processing, and Saving Files.")

If PersistentHistory is OFF, the History Buffer is cleared for each new
editing session, and only those responses entered during the current editing
session will be included in the History Buffer.  Within each new session under
this condition, the first time one of the applicable commands is executed, the
prompt box displayed by the command will be empty.  An exception is the
Options prompt box for the Find and Replace commands; when first executed,
these commands will optionally display initial values.  (For more information
on setting these initial Options values, see "Initial Find Options" and
"Initial Replace Options" under "Command/Format Options" in the chapter on
"Configuring the Editor Interactively.")

The editor maintains up to 1000 total History entries (for ALL commands).

The number of total entries maintained can be decreased or eliminated, if
desired.  The editor also allows you to specify the maximum number of entries
(up to 100) that you want to maintain for each particular command or command
group (that is, for each History "list").  (For more information, see
"Max History Entries" and "Max History Per List" under
"Command/Format Options" in the chapter on
"Configuring the Editor Interactively.")

If desired, you can remove individual entries from the History Buffer.  This
is accomplished while the appropriate History box is displayed on the screen.
Simply position the cursor on the entry to be deleted, and press <Del>.


Obtaining a File PickList within a Prompt Box
─────────────────────────────────────────────

For commands that display a prompt box requesting the filename to process
(such as the EditFile and SaveAs commands), you can obtain a PickList of
files from which to choose the desired filename.  A number of options are
available which allow you to:  configure the behavior of certain features of
the file-related PickList, limit the entries in the PickList, and quickly
scroll through the displayed entries.

From a file-related prompt box, you can also sort the PickList entries,
select an alternate drive for which to display the matching list of files,
and delete listed files from disk.

Within a file-related prompt box, you can enter an abbreviated filename to
obtain a file PickList.  Such a PickList includes the names of files that
match the abbreviated filename specification, as well as associated directory
entries.  By default, the entries in a file PickList consist of:

    • All matching files, in ascending order by filename.

    • All directories in the indicated path.  The directory entries are
      grouped together at the top of the PickList, and are designated with the
      "\" symbol preceding the name, and the notation < DIR > following the
      name.

    • The parent directory (if applicable), indicated as "\..", as the first
      entry in the PickList.

PickList file entries also include the size of the file in bytes, and the date
and time each file was last updated or each directory was created.


You can configure certain features of file-related PickLists, using the
"File PickList Settings" configuration options.  These options control the
treatment of directories and the order of the entries in a file PickList, as
follows:

    • You can configure whether or not the editor will change the current
      directory when a new directory is selected from a file PickList.  (By
      default, the current directory is changed.)

    • You can configure the editor to include ALL directories that are in the
      path containing the files displayed in the current PickList (the default
      behavior); or you can limit directory entries to those that match the
      filename specification.  (This option has no effect on the Filename
      Completion option discussed later in this section.)

    • You can configure the editor to display any included directory entries
      at the top of the PickList (the default behavior); or you can have the
      directory entries located according to the sort order of the PickList.

    • You can configure whether or not the editor adds a slash to the
      beginning of any included directory entries.  (By default, the slash is
      included.)

    • You can select the default sort order (ascending or descending) of the
      entries in the file PickList, and you can select the default key on
      which the entries will be sorted.  You can choose to sort the entries
      according to:  full filename, including extension; filename extension
      only; file size; file date; or file attributes.  (The standard default
      sort order is ascending, by full filename.)

(For more information on configuring the file PickList options, see
"File PickList Settings" under "System/File Options" in the chapter on
"Configuring the Editor Interactively.")

Several methods are available to allow you to specify an abbreviated filename
within a file-related prompt box, as follows.  (For more information on
specifying abbreviated filenames, see
"Adding Files to the Ring:  Specifying and Opening Files" in the chapter on
"Loading, Processing, and Saving Files.")

    • Enter a blank (empty) response for a PickList of all files and
      directories in the current directory.

    • Enter an ambiguous filename specification (by including the wildcard
      characters, "*" or "?") for a PickList of all directories in the current
      directory, and all matching files.


      Or you can specify the "Search SubDirs" (-s) option to obtain a PickList
      of all files in the indicated directory and all associated
      subdirectories, that match the filename specification.  This option is
      available for the EditFile and InsertFile commands.  (For more
      information on the "Search SubDirs" option, see
      "Command-Line Options" in the chapter on "Starting the Editor.")

      For this method to display a PickList when you execute the EditFile
      command, the variable LoadWildFromInside must be OFF, or you must
      precede the filename specification with the "-a-" ("Pick from List")
      command-line option.  (For more information on the LoadWildFromInside
      variable, see "Load Wild from Inside" under "System/File Options" in the
      chapter on "Configuring the Editor Interactively."  For more information
      on the "Pick from List" option, see "Command-Line Options" in the
      chapter on "Starting the Editor.")

    • Invoke the Filename Completion option to generate an ambiguous
      filename specification.  To do this, begin typing the filename.  When
      you have entered enough of the characters in the filename to identify
      the file(s) from which to choose, press the <Tab> key.  The editor will
      then complete your entry by appending "*.*", ".*", or "*", as
      appropriate, to create an ambiguous specification, and present a
      PickList of matching files and only matching directories.

      Note that the Filename Completion option is not affected by the setting
      of the LoadWildFromInside variable, nor is it affected by any
      command-line switches that are entered within the prompt box.

Once the file PickList is displayed, the following options are available:

    • You can select a different drive for which to display a PickList of
      files that match the initially entered filename specification.  Press
      <Alt F10> to display a PickList of drives.  Move the cursor bar over
      the desired drive and press <Enter>.  A new PickList of matching
      files/directories on the indicated drive is displayed.

    • You can change the sort order of the files displayed in the PickList.
      Press <Alt S> to display a selection menu of sort options.  Select the
      sort order (ascending or descending).  Then select the key (name,
      extension, size, date, or attribute) on which to sort the entries. Once
      you select the key, the entries are immediately sorted based on your
      sort selections and the newly-sorted PickList is displayed.

    • You can select files from the entries in the PickList to delete from
      disk.

      • To delete a single file, move the cursor bar over the name of the
        file to be deleted, and press <Del>.  The indicated file is then
        deleted and its entry removed from the PickList.

      • To delete multiple files, move the cursor bar over the name of each
        file to be deleted, and press either <Shift Spacebar> or
        <Ctrl Spacebar> to tag each indicated filename.  Once your selections
        are complete, press <Enter>.  The indicated files are then deleted
        and their entries are removed from the PickList.

    • You can select a file or directory from the PickList for processing.
      In a PickList displayed by the EditFile command, you can select
      multiple files and/or directories.

      • To select a single file or directory, move the cursor bar over the
        desired entry and press <Enter>.

      • To select multiple files and/or directories in a PickList displayed
        by the EditFile command, move the cursor bar over each desired entry,
        and press either <Shift Spacebar> or <Ctrl Spacebar> to tag the
        indicated files.  Once your selections are complete, press <Enter>.

      The editor then begins processing your selection(s):

      • If your selection is a directory entry, a PickList of files and
        directories under the selected directory is displayed. (Additionally,
        in the standard configuration of the editor, the selected directory
        becomes the current directory.)

        You can configure the editor so that the current directory is not
        changed when you select a directory from a PickList.  (For more
        information, see "File PickList Settings" under "System/File Options"
        in the chapter on "Configuring the Editor Interactively.")

      • In an EditFile PickList, if your selection included multiple
        directories, a PickList of files and directories under the first
        directory is displayed.  Then, once your file selections from this
        newly-displayed PickList are complete, the remaining directories are
        successively processed.

      • The editor adds the selected file(s) to the Ring of files.

      • Finally, the first, or only, selected file is made the current file,
        and the command being executed resumes, using that file.

(For more information on how to select entries from a PickList, see
"Using PickLists" later in this chapter.)


StatusLine Prompt
─────────────────

Certain commands request additional information by displaying a prompt on the
StatusLine.  Generally, the prompt requests a single key or character
response, and the command immediately resumes once the appropriate key has
been pressed (without <Enter> being pressed).  PlaceMark, Literal, and
GotoWindow are examples of commands that issue such prompts.

To remove a StatusLine prompt from the screen and cancel the command that was
executed, press <Escape>.  The Literal command, however, is not canceled by
pressing <Escape>.

A few commands issue StatusLine prompts that behave in a slightly different
manner than the general behavior.  For example:

    • The ResizeWindow command first displays a StatusLine prompt requesting
      the window border to be resized, and then displays a second prompt to
      allow you to move the resizing bar.  At the second StatusLine prompt,
      you must press <Enter> to complete the command once the resizing bar has
      been positioned at the desired location.

    • The IncrementalSearch command displays a StatusLine prompt to request
      the successive character(s) of the string to be located.  The prompt
      remains active on the StatusLine until you terminate the command by
      pressing <Enter> or <Escape>.


Selection Menu
──────────────

For commands that accept a response from predefined choices, a selection menu
of available choices is displayed.  To choose a response, place the cursor bar
over the desired selection and press <Enter>.  The command resumes, using the
selected response.

You can also choose the desired option within a selection menu by simply
pressing the highlighted quick-key for the option.  The command immediately
resumes execution once the quick-key is pressed (without <Enter> being
pressed).  (For more information on using quick-keys in menus, see
"Accessing Sub-Menu Commands and Options" in the chapter on
"The Pull-Down Menu System.")

To cancel a command or operation from within a selection menu, press <Escape>.





Command Prompts and Keydefs

Many commands in the editor, such as EditFile() and Find(), issue a prompt box
when you execute the command.  The prompt box is displayed on the screen, and
the user is allowed to enter a response for the command to process.  Within a
prompt box, a limited set of native commands are available for entering a
response.  Following are the native commands that you can execute once a
prompt box is displayed on the screen:

    • Editing commands:

        BackSpace(), Copy(), CopyBlock(), CopyToWinClip(), Cut(),
        CutToWinClip(), DelChar(), DelLine(), DelLeftWord(), DelRightWord(),
        DelToEol(), Literal(), Paste(), PasteReplace(), PasteFromWinClip(),
        PasteReplaceFromWinClip(), SelfInsert()

    • Movement commands:

        BegLine(), Down(), EndLine(), Left(), NextChar(), PrevChar(), Right(),
        Up(), WordRight(), WordLeft()

    • Other commands:

        CReturn(), Escape(), Exit(), Help(), TabRight(), ToggleInsert()


The editor also forces certain of these pre-defined commands to be executed
when a particular key (or mouse button) is pressed within a prompt box, as
follows:

      Key/Mouse Assignment          Command Invoked in Prompt Box
    _________________________       _____________________________

    <Enter>  or  <LeftBtn>          CReturn()

    <Escape>  or  <RightBtn>        Escape()

    <Backspace>  or  <Ctrl H>       BackSpace()

    <Del>                           DelChar()

    <Home>                          BegLine()

    <End>                           EndLine()

    <CursorLeft>                    Left()

    <CursorRight>                   Right()

    <CursorDown>                    Down()

    <CursorUp>                      Up()

    <Ins>                           ToggleInsert()

    <TabRight>                      TabRight()

    <F1>                            Help()


For those keys (or mouse buttons) that the editor forces to invoke a
pre-defined command, it does so regardless of the command or macro that is
assigned to the key (or mouse button).  For example, in a prompt box, the
<Enter> key (or <LeftBtn>) invokes the CReturn command, even if you have
assigned a different command or macro to this key (or mouse button).

The editor does not force key assignments for the following prompt-box
commands:

  Copy(), CopyBlock(), CopyToWinClip(), Cut(), CutToWinClip(), DelLine(),
  DelLeftWord(), DelRightWord(), DelToEol(), Exit(), Literal(), NextChar(),
  Paste(), PasteFromWinClip(), PasteReplace(), PasteReplaceFromWinClip(),
  PrevChar(), SelfInsert(), WordLeft(), and WordRight().

Thus, any of these commands can be executed within a prompt box only if you
have assigned the command to a key.  If you have replaced one of these native
editor commands with a macro of your own, and you do not have a key
assignment for the replaced native command in your copy of the editor, you
will not be able to execute the command in a prompt box.

To resolve this potential problem, the editor lets you identify your own group
of additional keys that are forced to execute a particular command within a
prompt box.  A special "PromptKeys" keydef allows you to have your own macro
assigned to a key for use while editing, and also have one of the prompt-box
commands assigned to that same key for use only when the key is pressed in a
prompt box.

The syntax to declare the PromptKeys keydef is:

    keydef PromptKeys
        <key_list>      command
            ...
        <key_list>      command
    end [PromptKeys]

where:

    • keydef specifies this as a key definition.

    • PromptKeys identifies this as a PromptKeys definition.

    • key_list is a key (or two-key) name.

    • command is one of the commands that are functional within a prompt box.

    • end specifies the end of the key definition.

    • The PromptKeys identifier may optionally be repeated after the end
      statement on the same line.


It is not necessary to enable and disable PromptKeys keydefs with the Enable()
or Disable() commands.  Instead, key assignments made in a PromptKeys keydef
(and installed in the editor) are automatically enabled when a prompt box is
displayed.  This effectively overrides the existing assignments for the keys
for the duration of the prompt.  Once the prompt is complete, the PromptKeys
assignments are automatically disabled and the previous key assignments are
restored.

To illustrate use of this feature, suppose you want a customized version of
the Paste() command to be assigned to the <Grey*> key.  In your custom
version, "paste" acts differently depending on the state of Insert mode, and
is defined as follows:

    proc myPaste()
        Paste(iif(Query(Insert), _DEFAULT_, _OVERWRITE_))
    end

    <Grey*>    myPaste()

With this macro, you have a paste command that works the way you like.
However, you can no longer use the <Grey*> key to Paste inside of prompts,
because myPaste() is a macro, rather than the native Paste() command that is
operational in a prompt box.  To remedy this, locate the PromptKeys keydef in
the TSE.UI user-interface file in the UI\ editor subdirectory (assuming you
are using the standard user interface), and add the following key assignment:

    keydef PromptKeys
        <Grey*>     Paste()
    end

After you compile and install your new TSE.UI interface, the native Paste()
command will again be available in prompt boxes when you press <Grey*>.  But
when you press <Grey*> while editing (outside a prompt box), the myPaste()
macro is executed.





Command Prompts and Picklists

Many commands in the editor require that additional information be provided or
that selections be made before the command can continue or complete the
operation.  For this, the editor issues command prompts and/or PickLists.
Within PickLists (and certain other types of displayed text), the editor
offers SpeedSearch capabilities.

This chapter describes the following features in the editor:

    • Command Prompts:

      • Prompt box (including use of the History Buffer and file PickLists)

      • StatusLine promptSelection menuUsing PickListsSpeedSearch Feature





Command-Line Options

You can specify a number of editing options when you start the editor (or when
you later open additional files during an editing session using the EditFile
command).  These command-line options can be entered either by including them
on the command line itself; or (unless otherwise noted in this section) by
passing them to the editor at the "File(s) to edit:" prompt, if the editor is
started without specifying any filenames.

Command-line options are identified by either the "-" or "/" character,
immediately followed by the letter that designates the desired option.  You
can enter the designating letter in either upper or lower case.  You can also
select multiple options (except when selecting the "Restore State" option).
This section describes the command-line options recognized by the editor.

Note that if you include the "Load Macro" (-l) or "Execute Macro" (-e)
command-line option, but do not specify any filenames to edit, the editor
does not display the prompt, "File(s) to edit:" (as described in the previous
section, "Selecting Files to Edit").  Instead, the editor creates its own
"dummy" ("unnamed") file.  This allows the editor to load/execute the
indicated macro file without forcing you to specify a file to be loaded.
This feature can be useful for certain types of macros.


▪ Load Keyboard Macro

  Syntax:

      -kKeyMacroFilename
      -k KeyMacroFilename

  This option instructs the editor to invoke the LoadKeyMacro command using
  the indicated KeyMacroFilename.  This causes the editor to load the
  Keyboard Macros contained in KeyMacroFilename and make these macros
  available in the current editing session.

  KeyMacroFilename must immediately follow "-k", with no intervening space.
  Only one "Load Keyboard Macro" option is recognized.  If you enter more than
  one, only the final entry is processed.

  If KeyMacroFilename does not include an extension, ".KBD" (the editor
  convention for Keyboard Macro filename extensions) is assumed.

  If you do not specify the path for KeyMacroFilename, the editor searches
  for the file in several pre-determined directories.  For more information on
  where the editor searches for the indicated filename, see
  "Loading Keyboard Macros Saved in a Previous Session" in the chapter on
  "Creating and Using Macros."


  Examples:

      Console version: Replace g32 with e32

      g32  foo.doc  abc.txt  -k KeyMacro.kbd
      g32  foo.doc  abc.txt  -kKeyMacro.kbd
      g32  -k KeyMacro  foo.doc  abc.txt
      g32  -kKeyMacro  foo.doc  abc.txt

  These examples instruct the editor to select the files foo.doc and abc.txt,
  and then to load the Keyboard Macros in the Keyboard Macro file
  KeyMacro.kbd.

  (For more information on creating and loading Keyboard Macro files, see
  "Keyboard Macros" in the chapter on "Creating and Using Macros.")


▪ Load Macro

  Syntax:

      -lMacroFilename
      -l MacroFilename

  This option instructs the editor to invoke the LoadMacro command using the
  indicated MacroFilename.  This causes the editor to load the Compiled
  Macros contained in the external MacroFilename and make these macros
  available for execution.  If MacroFilename contains a WhenLoaded macro,
  it is executed.

  MacroFilename must immediately follow "-l", with no intervening space.
  The "Load Macro" option can be specified for multiple MacroFilename
  entries.

  If MacroFilename does not include an extension, ".MAC" (the editor
  convention for external Compiled Macro filename extensions) is assumed.

  If you do not specify the path for MacroFilename, the editor searches for
  the file in several pre-determined directories, according to the
  "macro file search order" described under
  "Creating and Using Compiled Macros" in the chapter on
  "Creating and Using Macros."


  Examples:

      Console version: Replace g32 with e32

      g32  foo.doc  abc.txt  -l MyMacro.mac
      g32  foo.doc  abc.txt  -lMyMacro.mac
      g32  -l MyMacro  foo.doc  abc.txt
      g32  -lMyMacro  foo.doc  abc.txt

  These examples instruct the editor to select the files foo.doc and abc.txt,
  and then to load the Compiled Macros in the Compiled Macro file MyMacro.mac.
  If MyMacro.mac contains a WhenLoaded macro, that WhenLoaded macro is then
  executed.

  (For more information on creating and loading Compiled Macro files, see
  "Introduction to External Compiled Macros" in the chapter on
  "Creating and Using Macros," and also see "LoadMacro()" in the chapter on
  "Editor Commands" in the Macro Reference Guide.  For more information on
  processing WhenLoaded macros, see "Event Macros" in the chapter on
  "Using Macro Language Features" in the Macro Reference Guide.)


▪ Execute Macro

  Syntax:

      -eMacroFilename
      -e MacroFilename

  This option instructs the editor to invoke the ExecMacro command using the
  indicated MacroFilename.  This causes the editor to load the Compiled
  Macros contained in the external MacroFilename and make these macros
  available for execution.  If MacroFilename contains a WhenLoaded macro, it
  is executed.  Additionally, if MacroFilename contains a Main macro, it is
  also executed.

  MacroFilename must immediately follow "-e", with no intervening space.
  The "Execute Macro" option can be specified for multiple MacroFilename
  entries.

  If MacroFilename does not include an extension, ".MAC" (the editor
  convention for external Compiled Macro filename extensions) is assumed.

  If you do not specify the path for MacroFilename, the editor searches for
  the file in several pre-determined directories, according to the
  "macro file search order" described under
  "Creating and Using Compiled Macros" in the chapter on
  "Creating and Using Macros."


  Examples:

      Console version: Replace g32 with e32

      g32  foo.doc  abc.txt  -e MyMacro.mac
      g32  foo.doc  abc.txt  -eMyMacro.mac
      g32  -e MyMacro  foo.doc  abc.txt
      g32  -eMyMacro  foo.doc  abc.txt

  These examples instruct the editor to select the files foo.doc and abc.txt,
  and then to load the Compiled Macros in the Compiled Macro file MyMacro.mac.
  If MyMacro.mac contains a WhenLoaded macro, that WhenLoaded macro is then
  executed.  Finally, if MyMacro.mac contains a Main macro, that Main macro is
  executed.

  (For more information on creating and executing Compiled Macro files, see
  "Introduction to External Compiled Macros" in the chapter on
  "Creating and Using Macros," and also see "LoadMacro()" and
  "ExecMacro()" in the chapter on "Editor Commands" in the
  Macro Reference Guide.  For more information on processing WhenLoaded and
  Main macros, see "Event Macros" in the chapter on
  "Using Macro Language Features" in the Macro Reference Guide.)


▪ Go To Line/Column Number

  Syntax:

     -nLineNumber[,ColumnNumber]
     -n LineNumber[,ColumnNumber]

  This option instructs the editor to position the cursor at the line number
  indicated as LineNumber, in the FIRST file that is loaded.  It also allows
  you to specify an optional column number, indicated as ColumnNumber,
  on which to position the cursor on the specified line.

  LineNumber must immediately follow "-n", with no intervening space.  To
  specify a column number, place a comma and the appropriate ColumnNumber
  immediately after LineNumber.  To specify ColumnNumber without
  specifying LineNumber, place a comma and the appropriate ColumnNumber
  immediately after "-n"; the editor assumes line number 1.

  Only one "Go To Line/Column Number" option is recognized.  If you enter more
  than one, only the final entry is processed.  This option is always
  processed on the FIRST file that is loaded, regardless of the placement of
  the option within the list of any filenames or other command-line options.


  Examples:

      Console version: Replace g32 with e32

      g32  foo.doc  abc.txt -n79
      g32  -n79,5  foo.doc  abc.txt

  Both examples instruct the editor to select the files foo.doc and abc.txt,
  and position the cursor at line 79 of foo.doc.  The cursor will be
  positioned in column 1 in the first example, and in column 5 in the second
  example.


▪ Binary Load

  Syntax:

      -bLineLength

  This option instructs the editor to load the first filename following
  "-bLineLength", in Binary mode.  The length of each line displayed is
  determined by the value specified as LineLength.  That is, the file contents
  are split at the requested length and wrapped to successive lines.

  LineLength must immediately follow "-b", with no intervening space.  Each
  filename preceded by a "Binary Load" indicator will be loaded in Binary
  mode, and the lines will be split at the line length specified for that
  file.

  If you follow this option with a file specification containing wildcard
  characters ("*" or "?"), all matching files that are loaded will be
  displayed in Binary mode.

  If you do not specify LineLength for this option, a line length of 64 is
  assumed.  If you specify a LineLength value of zero, the editor ignores that
  "Binary Load" option.  If you specify a value for LineLength that exceeds
  the editor's maximum line length, the editor's maximum line length is
  assumed.

  You can load a file in Binary mode in combination with Hex mode by preceding
  the filename with "-bLineLength -h" (or "-h -bLineLength").  (Hex mode is
  described below.)

  (For more information on editing files in Binary mode, see
  "Alternative Modes for Viewing Files" in the chapter on
  "Loading, Processing, and Saving Files.")


  Examples:

      Console version: Replace g32 with e32

      g32  foo.doc  -b40  abc.txt
      g32  -b  *.doc  abc.txt

  The first example instructs the editor to select the files foo.doc and
  abc.txt.  The file abc.txt will be loaded in Binary mode, with lines split
  at column 40.

  The second example instructs the editor to select all files (in the current
  directory) with an extension of ".doc", and to also select the file abc.txt.
  Any ".doc" files that are loaded will be displayed in Binary mode, and the
  lines split at column 64.


▪ Hex Load

  Syntax:

      -h

  This option instructs the editor to load the first filename following "-h",
  in Hex (hexadecimal) mode.  If you follow this option with a file
  specification containing wildcard characters ("*" or "?"), all matching
  files that are loaded will be displayed in Hex mode.

  You can load a file in Hex mode in combination with Binary mode by preceding
  the filename with "-h -bLineLength" (or "-bLineLength -h").  (Binary mode
  is described above.)

  (For more information on viewing files in Hex mode, see
  "Alternative Modes for Viewing Files" in the chapter on
  "Loading, Processing, and Saving Files.")


  Examples:

      Console version: Replace g32 with e32

      g32  foo.doc  -h  abc.txt
      g32  -h  *.doc  abc.txt
      g32  -h -b abc.txt

  The first example instructs the editor to select the files foo.doc and
  abc.txt.  The file abc.txt will be loaded in Hex mode.

  The second example instructs the editor to select all files (in the current
  directory) with an extension of ".doc", and to also select the file abc.txt.
  Any ".doc" files that are loaded will be displayed in Hex mode.

  The third example instructs the editor to load abc.txt in Hex and Binary
  modes.


▪ Browse Load

  This option instructs the editor to load the first filename following
  "-y", in Browse Mode.

  If you follow this option with a file specification containing wildcard
  characters ("*" or "?"), all matching files that are loaded will be
  displayed in Browse mode.

  (For more information on editing files in Browse mode, see
  "Alternative Modes for Viewing Files" in the chapter on
  "Loading, Processing, and Saving Files.")


  Examples:

      Console version: Replace g32 with e32

      g32  foo1.doc  -y foo2.txt
      g32  -y  *.doc  abc.txt

  The first example instructs the editor to select the files foo1.doc and
  foo2.txt.  The file foo1.txt will be loaded in normal mode, and foo2.txt
  will be loaded in Browse mode.

  The second example instructs the editor to select all files (in the current
  directory) with an extension of ".doc", and to also select the file abc.txt.
  Any ".doc" files that are loaded will be loaded in Browse mode, with abc.txt
  being loaded in normal mode.

▪ Load All

  Syntax:

      -a

  This option instructs the editor to select all matching files for the FIRST
  filename specification following "-a", and make those files available for
  editing.

  This option is in effect only for ambiguous filenames (those that contain
  wildcard characters, "*" or "?"), or if the "Search SubDirs" (-s) option is
  also in effect.

  Normally, files are selected from the command line according to the setting
  of the LoadWildFromDOS variable.  Similarly, files are selected within the
  editor from the "File(s) to edit:" prompt according to the setting of the
  LoadWildFromInside variable.  The "Load All" option allows you to override
  the setting of LoadWildFromDOS or LoadWildFromInside, as appropriate.  (For
  more information on the LoadWildFromDOS and LoadWildFromInside variables,
  see "Load Wild from Command Line" and "Load Wild from Inside,"
  respectively, under "System/File Options" in the chapter on
  "Configuring the Editor Interactively.")

  The "Load All" option has no effect on filename specifications that do not
  contain wildcard characters, unless the "Search SubDirs" (-s) option is also
  in effect.


  Example:

      Console version: Replace g32 with e32

      g32  *.doc  -a  *.txt

  This example instructs the editor to handle "*.doc" according to the setting
  of the LoadWildFromDOS variable.  However, the editor will automatically
  select all files matching the "*.txt" specification (regardless of the
  LoadWildFromDOS setting), and make them available for editing.


▪ Pick from List

  Syntax:

      -a-

  This option instructs the editor to provide a PickList of all matching
  files for the FIRST filename specification following "-a-", and allows you
  to select the file to edit.

  This option is in effect only for ambiguous filenames (those that contain
  wildcard characters, "*" or "?"), or if the "Search SubDirs" (-s) option is
  also in effect.

  Normally, files are selected from the command line according to the
  setting of the LoadWildFromDOS variable.  Similarly, files are selected
  within the editor from the "File(s) to edit:" prompt according to the
  setting of the LoadWildFromInside variable.  The "Pick from List" option
  allows you to override the setting of LoadWildFromDOS or LoadWildFromInside.
  (For more information on the LoadWildFromDOS and LoadWildFromInside
  variables, see "Load Wild from Command Line" and "Load Wild from Inside,"
  respectively, under "System/File Options" in the chapter on
  "Configuring the Editor Interactively.")

  The "Pick from List" option has no effect on filename specifications that
  do not contain wildcard characters, unless the "Search SubDirs" option is
  also in effect.


  Example:

      Console version: Replace g32 with e32

      g32  *.doc  -a-  *.txt

  This example instructs the editor to handle "*.doc" according to the setting
  of the LoadWildFromDOS variable.  However, the editor will provide a
  PickList of all files matching the "*.txt" specification (regardless of the
  LoadWildFromDOS setting).

  (For more information on PickLists, see "Using PickLists" in the chapter on
  "Command Prompts and PickLists.")


▪ Search SubDirs

  Syntax:

      -s

  This option instructs the editor to search not only the indicated directory
  for any filename specifications, but also all associated subdirectories.  It
  affects all filename specifications which follow "-s".

  If "-s" is specified, then any matching files that the editor locates will
  be handled according to the setting of the LoadWildFromDOS variable (if
  entered on the command line) or the LoadWildFromInside variable (if entered
  at the "File(s) to edit:" prompt), or according to the "Load All" (-a) or
  "Pick from List" (-a-) option, if specified.

  Note that the "Search SubDirs" option affects all filename specifications
  which follow, even those that do not contain wildcard characters.


  Examples:

      Console version: Replace g32 with e32

      g32  -s  abc.doc  xyz.txt
      g32  *.txt  -s  abc.doc
      g32  -s  -a  \files\abc.doc
      g32  -s  -a-  \files\*.txt
      g32  -a-  -s  c:\

  The first example instructs the editor to locate all occurrences of the
  filename abc.doc, and all occurrences of the filename xyz.txt, in the
  current directory and all subdirectories of the current directory.  The
  located files will be handled according to the setting of the
  LoadWildFromDOS variable.

  The second example instructs the editor to locate all files, in the current
  directory only, with an extension of ".txt"; and to handle such files
  according to the setting of the LoadWildFromDOS variable.  The editor will
  also locate all occurrences of the filename abc.doc, in the current
  directory and all subdirectories of the current directory; and will handle
  the located files according to the setting of the LoadWildFromDOS variable.

  The third example instructs the editor to locate all occurrences of the
  filename abc.doc, in the \files directory and all subdirectories of the
  \files directory.  All the located files will automatically be selected and
  made available for editing.

  The fourth example instructs the editor to locate all occurrences of all
  files with an extension of ".txt", that are in the \files directory and all
  subdirectories of the \files directory.  The editor will provide a PickList
  of all the files that are located.

  The fifth example instructs the editor to find all files on the c: drive,
  beginning at the root directory, and provide a PickList of the files.


▪ Restore State

  Syntax:

      -r

  This option instructs the editor to restore the editing environment from a
  previous session.  This includes the file(s) that were loaded and the
  window(s) and file(s) that were displayed on the screen; the position of the
  cursor at the time the session was ended; the block (if any) that was
  marked; the bookmarks that were placed; and the settings of selected editing
  options (such as those on the "Options" Menu).

  If this option is entered at the "File(s) to edit:" prompt, any files that
  are currently loaded remain loaded; any additional files included in the
  restored environment are added to the current Ring of files.

  If the "-r" option is specified, the editor ignores any filenames or other
  command-line options that may be specified.

  This option is only valid if the editing environment was saved when a
  previous editing session was terminated.  Environment information is stored
  in the "state file" (TSESTATE.DAT).  To locate the state file, the editor
  looks first in the current directory; then, if not located, it looks in the
  editor load directory.  (For more information on saving and restoring the
  editing environment, see "Saving/Restoring the Editing Environment" in the
  chapter on "Loading, Processing, and Saving Files.")


  Example:

      Console version: Replace g32 with e32

      g32  -r

  This example instructs the editor to restore the editing environment from
  the last session for which the environment was saved.


▪ Augment Load Dir

  Syntax:

      -iDirectoryPath

  This option instructs the editor to extend its view of the "load directory,"
  to a specified additional directory.  This extended directory (rather than
  the actual directory from which the editor is loaded) will then be used as
  the load directory in which the editor will write any necessary
  configuration files.  This will also extend the directories the editor
  searches when it is attempting to locate certain files in the load
  directory:  the editor will first search the extended load directory, and if
  the file is still not found, the editor will then search in the directory
  from which the editor was actually loaded on startup.

  This option is only valid when included on the command line at editor
  startup.  It is not recognized at the "File(s) to edit:" prompt.

  You can also extend the editor load directory by setting the TSELOADDIR
  environment variable.  Once this is done, the "-i" command-line option can
  then be used, as needed, to override the value of TSELOADDIR at startup.
  (For more information on using the TSELOADDIR environment variable, see
  "Augmenting the Editor Load Directory" in the chapter on
  "Installation of the SemWare Editor Professional.")


  Example:

      Console version: Replace g32 with e32

      g32  -ic:\TSEPro  abc.txt

  This example instructs the editor to extend its load directory to include
  c:\TSEPro, in addition to the actual directory from which the editor is
  loaded.  File abc.txt will be selected for editing.

▪ Single Instance of the Editor On

  Syntax:

      -1     (The option is "minus one")

  This option instructs the editor to start/use a single instance of the
  editor for editing purposes. See SingleInstance for more information.

▪ Single Instance of the Editor Off

  Syntax:

      -1-    (The option is "minus one minus")


  This option instructs the editor start as a separate, non-shared instance
  for editing purposes. See SingleInstance for more information.





Commands and Features That Allow Recovery of Text

The editor offers three features for restoring text:  Undo (with a
corresponding Redo), which allows you to step back through changes made to the
text; RestoreCursorLine, which allows you to restore the current line with one
keystroke; and the Deletion Buffer, which allows you to recover deleted text
and restore it to the same or different file(s).


Using Undo/Redo
───────────────

▪ Undo  (<Alt Backspace>, or "Undo" under Text Menu)

  This command cancels the last change made to the text in the current file.
  You can use this command to successively cancel each preceding change to the
  text.

  For characters that are typed in the text, Undo cancels those changes in
  groups of characters.  For example, words that are typed in succession may
  be deleted by word, rather than character by character.  Or, a series of
  successive backspace commands may be removed by a single execution of Undo.
  But if continuous typing is "broken," such as by cursor-movement commands,
  then a single execution of Undo only deletes all changes since the last
  "break".

  For example, if you type the following without "breaking" your typing:

    This is a test.

  Then the first execution of Undo will remove " test."   A second execution
  of Undo will remove " a".  A third execution of Undo will remove " is".  A
  fourth execution of Undo will remove "This".

  However, if you type the following:

    This is a tt

  Then immediately execute Backspace <Backspace> to remove the last "t", and
  then proceed to complete the line as:

    This is a test.

  Then the first execution of Undo will remove "est.".  A second execution of
  Undo will restore the duplicate "t" that was originally entered and deleted
  (so that the text reads "This is a tt").  A third execution of Undo will
  remove " tt".  A fourth execution of Undo will remove " a".  And so on.

  For broad changes made to the text, Undo cancels the entire scope of the
  changes made by the last previous keystroke.

  For example, if you delete a block of text, then a single execution of Undo
  will restore the entire block.

  Or, for example, if you issue the Replace command to replace all occurrences
  of "this" in the text with "that", and you choose the "No-prompt" option,
  then a single execution of Undo will restore all changed occurrences of
  "that" back to "this".  But if you do not specify the "No-prompt" option,
  and instead let the editor prompt you for each replacement, then you will
  have to continue to execute Undo to successively restore each changed
  occurrence of "that" back to "this" (from the last back to the first).

  Note that if you Undo more than you intended, you can use Redo (if you do so
  immediately) to restore the change (that is, to cancel that Undo action).

  Whenever you use the SaveFile command to save a file, the Undo/Redo
  information for that file is purged (unless the editor is configured
  otherwise).  Thus, you cannot Undo any changes made prior to the time the
  file was last saved.  (You can configure the editor to keep Undo/Redo
  information even after the file is saved.  For more information on
  configuring this option, see "Keep Undo Beyond Save" under
  "Command/Format Options" in the chapter on
  "Configuring the Editor Interactively.")

▪ Redo  (<AltShift Backspace>, or "Redo" under Text Menu)

  This command cancels the last Undo action.  Successive executions of Redo
  will cancel each previous Undo action, in reverse order.

  If you Redo more than you intended, you can use Undo (if you do so
  immediately) to cancel the change (that is, to cancel the Redo action).

  Once you make a change to the text using any command other than Redo or
  Undo, the Redo information is purged.

  For example, if you type the following:

    This is aa test.

  And then you execute Undo one time, the text will be left as:

    This is aa

  If you then execute Backspace to remove the final "a", you cannot execute
  Redo to restore "test" (which was removed by the previous Undo).


Restoring the Current Line
──────────────────────────

▪ RestoreCursorLine  (<Ctrl Q L>, or "Restore Cursor Line" under Text Menu)

  This command generally restores the current line to what it was when the
  cursor initially moved to the line, provided the cursor has not moved off
  the line.  This command is useful if part of a line is accidentally deleted
  or altered, or if you wish to undo changes made to the line.  Issue this
  command before the cursor moves from the current line, and before executing
  File and Window commands.


The Deletion Buffer:  A Safety Net
──────────────────────────────────

During an editing session, you can recover text deleted by certain deletion
commands from a temporary storage area of deleted text, called the Deletion
Buffer.  When you execute the following commands, deleted text is
automatically placed in the Deletion Buffer:

    DelLine         (<Alt D>, or "Delete Line" under Text Menu)

    DelRightWord    (<Ctrl Del>, or "Delete Right Word" under Text Menu)

    DelToEol        (<Alt Del>, or "Delete to End of Line" under Text Menu)

    DelBlock        (<Alt G>, or "Delete" under Block Menu)

You can remove deleted text from the Deletion Buffer and restore it to the
same or different file(s).  The Deletion Buffer operates as a "last in, first
out" stack of entries.  That is, the last deletion placed into the Deletion
Buffer is the first deletion removed.  Following is an illustration of the
Deletion Buffer:

    Entry   File      Command
     No.     ID       Entered              Buffer Contents
    _____   _____   ____________   _______________________________

      4     File2   DelToEol       portion of deleted line

      3     File2   DelRightWord   deleted word

      2     File1   DelLine        contents of entire deleted line

      1     File1   DelLine        contents of entire deleted line


Each time one of the above deletion commands is executed, a new entry is
stored in the Deletion Buffer.  In this example, four deletion commands were
executed in two different files.  The text deleted by each of these commands
was stored in the Buffer from top to bottom.  When the DelToEol command was
executed (Entry #4), the first three deletions were pushed toward the bottom
of the Buffer, placing the newly deleted text on top.  The number of deletion
entries that can be stored in the Deletion Buffer is limited only by available
virtual memory.

The following commands allow you to recover text from the Deletion Buffer.

▪ UnDelete  ("Local UnDelete" under Text Menu)

  This command recovers the last deletion placed into the Deletion Buffer from
  the current file.  The associated text is removed from the Buffer, and each
  remaining Buffer entry below that one moves up one entry, from the bottom
  toward the top.

  In the illustration above, executing UnDelete from File1 (the current file)
  retrieves Entry #2 and restores the entire deleted line to the current file.
  Entry #2 is removed from the Deletion Buffer, and Entry #1 moves up one
  entry in the Buffer.

▪ GlobalUnDelete  (<Ctrl U>, or "Global UnDelete" under Text Menu)

  This command recovers the last deletion placed into the Deletion Buffer
  regardless of the file from which it was deleted, and restores it to the
  current file.  The associated text is removed from the Buffer, and each
  remaining Buffer entry below that one moves up one entry, from the bottom
  toward the top.

  In the illustration above, executing GlobalUnDelete from File1 (the current
  file) retrieves Entry #4, and restores the deleted portion of the line to
  the current file.  Entry #4 is removed from the Deletion Buffer, and Entries
  #1, #2, and #3 each move up one entry in the Buffer.

▪ PasteUnDelete  ("Paste UnDelete" under Text Menu)

  Similar to the GlobalUnDelete command, this command recovers the last
  deletion placed into the Deletion Buffer regardless of the file from which
  it was deleted, and restores it to the current file.  However, unlike
  GlobalUnDelete, the associated text is NOT removed from the Buffer; thus,
  PasteUnDelete can be used to copy deleted text to multiple locations in one
  or more files.

  In the illustration above, executing PasteUnDelete from File1 (the current
  file) retrieves Entry #4, and restores the deleted portion of the line to
  the current file.  Entry #4 remains in the Deletion Buffer so that the
  Buffer is unchanged.

Text recovered from the Deletion Buffer is inserted in the current file based
on the cursor position.  Execution of an UnDelete command does not alter the
position of the cursor relative to the screen.  Text is restored just as it
was stored, according to the command you used to delete the text, as follows:

    • If DelLine was used, the deleted line is inserted above the current
      line.  The current line, and any lines below it, shift down.  The
      recovered line becomes the current line.

    • If DelRightWord was used, the deleted word is inserted on the current
      line immediately before the cursor position.  Any text from and to the
      right of the cursor shift right.  The cursor is positioned on the first
      character of the recovered word.

    • If DelToEol was used, the deleted portion of the line is inserted on the
      current line beginning at the cursor position.  Any text from and to the
      right of the cursor shift right.  The cursor is positioned on the first
      character of the recovered text.

    • If DelBlock was used, the entire deleted block of text is restored.
      (You cannot recover just a portion of the block of text.  For example,
      you could not recover just one line out of a deleted block of lines.)
      The recovered text is placed in the current file according to the type
      of block you deleted, as follows:

      • If a line block was deleted, the block of deleted lines is inserted
        above the current line.  The current line, and any lines below it,
        shift down.  The first line of the recovered lines becomes the current
        line.

      • If a character block was deleted, the block of deleted characters is
        inserted beginning at the cursor position.  Any text from and to the
        right of the cursor is moved to the end of the recovered text. If the
        deleted characters spanned multiple lines, line breaks occur at the
        same places in the recovered text as they were when the text was
        deleted.  The cursor is positioned on the first character of the
        recovered text.

      • If a column block was deleted, the deleted column of text is inserted
        beginning at the cursor position.  If the column of deleted text
        spanned lines, it is restored across lines.  Any text from and to the
        right of the cursor position shifts right on each line, as necessary
        to accommodate the recovered text.  Any text to the left of the cursor
        on the affected lines is unchanged.  The cursor is positioned on the
        first character of the recovered text.

(For more information on the Block operations discussed in this section, see
the chapter on "Block Operations.")


  ┌──────────────────────────────── Tip ─────────────────────────────────┐
  │  The Deletion Buffer provides a quick way to move a word or line of  │
  │  text.  Position the cursor on the word or line, and execute         │
  │  DelRightWord or DelLine, as appropriate.  Then move the cursor to   │
  │  the new location and execute one of the UnDelete commands.  Use     │
  │  PasteUnDelete to insert the text multiple places.                   │
  └──────────────────────────────────────────────────────────────────────┘





Commands to Add TextAddLine  (<F2>, or "Add Line (below)" under Text Menu)

  This command inserts a blank line immediately BELOW the current line.  The
  cursor moves to the new line without changing its column position.

▪ InsertLine  (<Alt F2>, or "Insert Line (above)" under Text Menu)

  This command inserts a blank line immediately ABOVE the current line.  The
  cursor moves to the new line without changing its column position.

▪ Literal  (<Ctrl P>)

  This command places the literal representation of a character into the text,
  at the cursor position.  When you execute this command, the editor displays
  the prompt "Literal:" on the StatusLine.  You then press the key(s) for the
  desired character.  Depending on the status of Insert mode, the editor
  either overwrites the current character, or inserts the new character and
  shifts existing text to the right.

  This command is useful for entering control characters (ASCII 1 through
  ASCII 31), such as formfeed.  At the "Literal:" prompt, enter <Ctrl> plus
  the appropriate keyboard character (as identified in a standard ASCII
  chart).  For example, to place a formfeed character (ASCII 12) into the
  text, press <Ctrl P> to display the "Literal:" prompt, and then press <Ctrl
  L>.  To enter a null character, press <Ctrl P> and then <Ctrl @>. (Note
  that <Ctrl @> is the same as <Ctrl 2>.)

  Unlike other commands, the Literal command cannot be canceled by
  pressing the <Escape> key.  Rather, the escape character (ASCII 27) is
  accepted as the response to the command, and an escape character is
  placed in the text.

  Note that if you enter a linefeed (ASCII 10) or carriage return (ASCII 13)
  character into the text, the line will be split at that position the NEXT
  time the file is loaded into the editor.


  ┌──────────────────────────────── Tip ─────────────────────────────────┐
  │  An alternate method for entering control characters or any ASCII    │
  │  character (1 - 255) into the text, is to hold down the <Alt> key    │
  │  while typing the decimal equivalent of the ASCII character using    │
  │  the numeric keypad.  For example, to include a formfeed character   │
  │  (ASCII 12) in the text, enter <Alt 12>, using the numeric keypad.   │
  │                                                                      │
  │  You can also use the AsciiChart feature of the editor to place any  │
  │  ASCII character into the text.  (For more information, see          │
  │  "Accessing the Pop-up ASCII Chart" in the chapter on                │
  │  "Special Commands and Features.")                                   │
  └──────────────────────────────────────────────────────────────────────┘





Commands to Copy TextDupLine  (<F4>, or "Dup Line" under Text Menu)

  This command makes a copy of the current line and inserts it below the
  current line.  The cursor moves to the new line without changing its column
  position.

▪ CopyCharAbove  (<Ctrl ->)*

  This command copies the character directly above the cursor onto the current
  line.  Depending on the status of Insert mode, the editor either overwrites
  the character at the cursor position, or inserts the character and shifts
  existing text to the right.  (For a similar command, see CopyCharAboveToEol
  below.)

  To use this command, place the cursor beneath a line of text and press
  <Ctrl ->.  The character above the cursor is copied onto the current line,
  and the cursor moves right one position.  To copy multiple characters, hold
  down <Ctrl -> until all characters are copied.

  * <Ctrl -> indicates the dash character above the alphabetic keys, NOT on
    the numeric keypad.

▪ CopyCharAboveToEol  (<Alt ->)*

  Like CopyCharAbove, this command copies characters from the line above the
  cursor onto the current line.  Copying begins with the character immediately
  above the cursor, and continues through the last character of the line
  above.  Depending on the status of Insert mode, the editor either overwrites
  the text on the current line beginning at the cursor position, or inserts
  the new text at the cursor position and shifts existing text to the right.

  * <Alt -> indicates the dash character above the alphabetic keys, NOT on
    the numeric keypad.





Commands to Delete TextBackSpace  (<Backspace>)

  This command deletes the character to the left of the cursor and moves the
  cursor to that position.  If Insert mode is ON, the text from and to the
  right of the cursor moves with the cursor.

  If you execute BackSpace at column 1, the cursor moves to the end of the
  line above and the current line is appended to the preceding line.

▪ DelChar  (<Del>)

  This command deletes the character at the cursor position.  The cursor does
  not move.  Any text to the right of the cursor is shifted to the left.

  If you execute this command beyond the last character on the current line,
  the line immediately below is appended to the current line.

▪ DelLine  (<Alt D>, or "Delete Line" under Text Menu)

  This command deletes the entire current line.  Text below the current line
  shifts up one line.  The cursor does not change its position relative to the
  screen.

▪ DelLeftWord  (<Ctrl Backspace>)

  This command deletes the word (or portion of the word) to the left of the
  cursor, and moves the cursor to the left.  White characters to the immediate
  left of the word are deleted, and any text from and to the right of the
  cursor is shifted to the left.  The character at the cursor position is not
  deleted; thus, for this command to work effectively, the cursor should be
  positioned immediately after the last character of the word.

  If you execute this command at column 1, the cursor, and any text on the
  current line, moves to the end of the line above.

  This command also deletes non-word characters, one character at a time.
  Deletion of a string of word characters stops when a non-word character is
  encountered.  But if you execute DelLeftWord from one position to the right
  of a non-word character, that non-word character is then deleted.

  (For more information on how the editor defines a word, see
  "WordSet Characters" under "Command/Format Options" in the chapter on
  "Configuring the Editor Interactively.")

▪ DelRightWord  (<Ctrl Del>, or "Delete Right Word" under Text Menu)

  This command deletes the word (or portion of the word) to the right of the
  cursor, including the character at the cursor position.  White characters to
  the immediate right of the word are deleted, and any remaining text to the
  right is shifted to the left.  The cursor does not move.

  If you execute this command beyond the last character on the current line,
  the line immediately below is appended to the current line.

  This command also deletes non-word characters, one character at a time.
  Deletion of a string of word characters stops when a non-word character is
  encountered.  But if you execute DelRightWord with the cursor positioned on
  a non-word character, that non-word character is then deleted.

  (For more information on how the editor defines a word, see
  "WordSet Characters" under "Command/Format Options" in the chapter on
  "Configuring the Editor Interactively.")

▪ DelToEol  (<Alt Del>, or "Delete to End of Line" under Text Menu)

  This command deletes the text on the current line from and to the right of
  the cursor.  The cursor position does not change.





Commands to Format TextCenterLine  (<Ctrl O T>, or "Center Line" under Text Menu)

  This command centers the text on the current line between left and right
  margins, as specified by the settings of LeftMargin and RightMargin.  If
  LeftMargin is zero, column 1 is used for the left margin.  If RightMargin is
  zero, no action occurs when you execute CenterLine.  (To set LeftMargin or
  RightMargin, select "Left Margin" or "Right Margin," respectively, under the
  Options Menu.)

  Note that if the left and right margins are not wide enough to accommodate
  the text being centered, the editor attempts to center the text around the
  mid-point between the left and right margins.  If this mid-point is too
  close to column 1 to accommodate the text being centered, the text is placed
  beginning at column 1.

  If you execute CenterLine with the cursor positioned in a marked block, text
  on each line in the block is centered.  The left and right margins used for
  centering depend on the type of block that is marked, as follows:

    • For a line or character block, the text on each line of the block is
      centered between the left and right margins, as described in the
      preceding paragraphs.  (For a character block, the entire text is
      centered on each line spanned by the block, even if the block does not
      include all text on the first or last lines of the block.)

    • For a column block, only text within the block is centered.  The text is
      centered on each line between the left- and right-most columns of the
      block.

▪ WrapPara  (<Alt B>, or "Wrap Paragraph" under Text Menu)

  This command formats text in paragraph style between left and right margins,
  by aligning text at the effective left margin and wrapping text at the right
  margin, as necessary.  The following paragraphs describe the behavior of
  WrapPara when you execute it outside a block.  (For a description of the
  behavior of WrapPara when it is executed within a block, see
  "Behavior of WrapPara within a Block," below.)

  When you execute WrapPara, text is formatted through the end of the
  paragraph following the cursor position.  If the current line is not blank,
  formatting begins with the current line; otherwise, formatting begins with
  the first non-blank line following the current line.  Formatting continues
  until the end of the paragraph is reached, as determined by the setting of
  the Paragraph-End Style option.  (For more information on designating the
  style used to separate paragraphs, see "Paragraph-End Style" under
  "Text Entry/Block Options" in the chapter on
  "Configuring the Editor Interactively.")

  In the portion of text being formatted, the beginning column position is not
  changed on the first non-blank line.  However, as text is wrapped on all
  subsequent lines in the paragraph, text is aligned at the effective left
  margin.  The effective left margin is determined as follows:

    • If AutoIndent is OFF, the effective left margin is the column specified
      for the LeftMargin setting (or column 1, if LeftMargin is zero).

    • If AutoIndent is ON or STICKY, the effective left margin is the column
      position of the first non-white character on the second line of the text
      being formatted.  (For more information on AutoIndent mode, see
      "AutoIndent Mode" in the chapter on "Editing Modes.")

  As the text is formatted, it is wrapped on each line at the right margin so
  that no words (continuous strings of non-white characters) extend beyond the
  right margin, except as noted in the next paragraph.  The right margin is
  based on the value of RightMargin.  If RightMargin is zero, or if the
  effective left margin is greater than the right margin, no action occurs
  when you execute WrapPara.  (To set RightMargin, select "Right Margin" under
  the Options Menu.)

  Note that the editor does not break a line in the middle of a word.  If
  the first word on a line extends beyond the right margin, that word is not
  wrapped.  In this case, the word will extend beyond the right margin.


Behavior of WrapPara within a Block
───────────────────────────────────

If you execute WrapPara with the cursor in a block, its behavior is affected.
Within a block, formatting begins with the first line of the block and
continues through each paragraph in the entire block.  However, the beginning
column position for the first line of each paragraph in the block is not
changed.  Formatting stops once the end of the block is reached.

The left and right margins used for formatting depend on the type of block
that is marked, as follows:

    • For a line or character block, the left and right margins are determined
      as described in the preceding paragraphs for this command.  For a
      character block, the full text is formatted on each line spanned by the
      block, even if the block does not include all text on the first or last
      lines of the block.  If AutoIndent is ON or STICKY, the effective left
      margin is determined separately for each paragraph, based on the second
      line of each paragraph.

    • For a column block, only text within the block is formatted.  The left
      and right margins are set to the left- and right-most columns of the
      block, respectively.

▪ QuoteLine  (<Ctrl 8>, or "Quote/Comment Line" under Text Menu)

  This command notates the text on the current line as a quote or comment.
  Depending on the file type (extension) of the current file, quote/comment
  notation(s) are inserted at the beginning, or at the beginning and end, of
  the line.  For example:

    • For SAL (.s, .ui) and C++ (.cpp, .hpp) file types, "//" is inserted at
      the beginning of the line.

    • For Assembly language (.asm) file types, ";" is inserted at the
      beginning of the line.

    • For C (.c, .h) file types, "/*" is inserted at the beginning of the
      line, and "*/" is inserted at the end of the line.

    • For Pascal (.pas) file types, "{" is inserted at the beginning of the
      line, and "}" is inserted at the end of the line.

    • For other file types (such as ".txt" files, or any non-supported file
      type), ">" is inserted at the beginning of the line.

  If you execute QuoteLine with the cursor positioned in a marked block, the
  text on each line in the block is notated as a quote/comment.

  You can also use this command to "unquote" or "uncomment" text.  If you
  execute QuoteLine on text that has already been notated as a quote or
  comment, the notations will be removed (in accordance with the file type, as
  indicated above).





Commands to Move TextCReturn  (<Enter>)

  This command moves the cursor down one line and positions it at the
  effective left margin of the line.  If Insert mode is ON, and the variable
  ReturnEqNextLine is OFF, the current line is split at the cursor position,
  and the text from and to the right of the cursor is placed on the new line
  beginning at the effective left margin.  (For more information on the
  effective left margin, see "AutoIndent Mode" in the chapter on
  "Editing Modes."  For more information on the ReturnEqNextLine variable,
  see "CReturn Equals Next Line" under "Text Entry/Block Options" in the
  chapter on "Configuring the Editor Interactively.")

▪ JoinLine  (<Alt J>, or "Join Line" under Text Menu)

  This command joins the current line with the line immediately below it.  The
  text on the line below is moved to the end of the current line.  The
  remaining text below the current line is shifted up one line.  If the cursor
  is positioned on or before the last character of the line when you execute
  this command, the line below is appended immediately following the last
  character.  Otherwise, if the cursor is positioned beyond the last character
  of the line, the line below is appended at the cursor position.

▪ SplitLine  (<Alt S>, or "Split Line" under Text Menu)

  This command splits the current line at the cursor position.  The text from
  and to the right of the cursor is moved to a new line immediately below the
  current line, beginning at column 1.  The cursor does not move.

▪ SwapLines  (<Ctrl F2>, or "Swap Lines" under Text Menu)

  This command swaps the current line with the line immediately following it.
  The cursor does not change its position relative to the screen.





Comments

SAL allows both single-line and multi-line comments.  This makes it possible
for you to be as descriptive as you like in commenting your macro code.

To place a single-line comment at the end of a line, precede the comment with
//.  All text on the line which follows // is ignored.  For example:

    // This entire line is ignored

    a = 10    // a is set to 10, but this comment is ignored

To place multiple lines of comments within the source, enclose the comments
within /* and */.  All text, and all lines, within these tokens are ignored.
Multi-line comments may not be nested.  For example:

    /* This is a multi-line comment.
       All text is ignored until the
       closing indicator which follows */

The multi-line comment tokens, /* and */, can also be used to nest single-line
comments.

It is recommended that single-line comments be used within procedures, and
multi-line comments be used outside procedures.  This makes it easy to comment
out entire procedures by simply enclosing the procedure within /* and */.





Compiling Macros

Compiling a macro source file into an object file is a necessary step in the
process of creating macros.  The editor will not directly interpret macro
source files, but can efficiently and quickly interpret macro object files.
Macro source files can be compiled from within the editor, or at the
command-line prompt.

Note that macros only have to be compiled when created or changed.  After
being compiled, the Compiled Macro files can be executed again and again,
without the need for re-compiling.

To compile a macro file within the editor, load the desired macro source file
into the editor, making it the current file.  Now execute the Compile()
command (select "Compile" under the Macro Menu, or press <Ctrl F9>).  The
Compile() command executes the SAL Compiler program (SC32.EXE).  (For more
information on the Compile() command, see
"Introduction to External Compiled Macros" in the chapter on
"Creating and Using Macros" in the User's Guide.)

If there are errors, the screen will be split horizontally and the lower
window will contain any warning or error messages produced by the compiler.
Correct the indicated problems, then execute the Compile() command again.

If there are no errors, the editor pops up a selection menu that allows you to
"Load" or "Execute" the newly-created Compiled Macro file (or "Cancel" the
operation at this point).  If you wish to load and execute the macro file,
select "Execute Macro" from the menu.  If you only wish to load the macro
file, select "Load Macro".  If you do not wish to load or execute the macro
file, select "Cancel" or press <Escape>.

Compiling a macro source file from within the editor is the recommended method
for compiling.  However, if necessary, you can also compile a macro source
file from the command-line prompt, using the SAL compiler program directly.
You can type just "SC32" at the prompt, and the program will prompt
you for the proper parameters.  If you would prefer to pass the necessary
parameters on the command line, the format is:

    sc32 [[options] source_filename [object_filename]]

where:

    • [options] are option flags that may be passed to the compiler.
      Available options include:

      • -m instructs the compiler to create a map file.  This file will show
        the sizes (code, data and stack) for each procedure, menu, keydef, and
        datadef included in the macro file.  The map file will have the same
        name as the macro source, but with an extension of ".MAP".  This is
        useful if you are trying to write the smallest possible macros, or if
        you are just interested in seeing additional information about the
        macros you have created.

      • -b instructs the compiler to install a new interface into the
        editor by attempting to burn in that interface.  This is used to burn
        a new or changed interface macro file (".ui" or ".cfg") into the
        editor.

        If this burn-in operation is successful, the editor executable
        program itself (e32.exe, if the Console version is present in the
        current directory, or g32.exe, if the GUI version is the only
        version present in the current directory) is updated with the new
        interface.  Thus, only a single file will be required to run the
        editor.

          If BOTH the console version AND GUI version are present in the
          current directory, the burn-in process will only update the console
          version (e32.exe).  In this case, for the burn-in process to update
          the GUI version (g32.exe), re-run the compiler with the same options
          as before, but modify the -b parameter portion to include the name
          of the editor executable immediately following -b (no spaces
          between -b and the editor executable name).
          For example, modify the -b portion to be -bg32.exe

          If you have renamed the editor executable, you will need to specify
          the name of the editor executable immediately following -b (no
          spaces between -b and the editor executable name).  For example,
          if you have renamed the editor to MyRenamedEditor.exe, you will
          need to specify -bMyRenamedEditor.exe


        Note, however, that if the editor is running when you execute sc32,
        the compiler may not be able to update the editor program.  If this
        is the case, the compiler will display the following:

        Unable to burn in interface - continuing...
        Create separate automatically-loaded interface file(s) instead? [Y/N]

        If you type "n", the compiler will terminate, and the interface file
        will not be installed.

        If you type "y", then the compiler will create separate interface
        file(s) in the current directory.  (For these files to be effectively
        installed, they must be created in the same directory in which the
        editor program resides.)  If you are compiling a ".ui" user-interface
        file, then a "tseui.dat" interface file will be created; and if the
        ".ui" file contains a configuration (Config/EndConfig) section, then
        a "tsecfg.dat" interface file will also be created containing the
        configuration settings from that section.  If you are compiling a
        ".cfg" settings file, then a "tsecfg.dat" interface file will be
        created.  These interface files are effectively installed in the
        editor, in that they will be automatically activated by the editor
        each time the editor is started; no further action is necessary.

        Note:  If, when the editor is started, the date/time stamp on the
        editor program (e32.exe or g32.exe, as appropriate) is later than the
        date/time stamp any interface files ("tseui.dat" or "tsecfg.dat")
        located in the editor load directory, the editor will ignore those
        older files. Otherwise, if the date/time stamp on any interface files
        is later than the date/time stamp on the editor program, the interface
        files will automatically be loaded.  Thus, the most recent
        configuration of the editor will be effective (regardless of whether
        it is burned in, or included in separate interface files.)

      • -s[path] instructs the compiler to install a new ".ui" or ".cfg"
        interface file in the editor, by forcing creation of separate
        automatically-loaded interface file(s).  The compiler does not even
        attempt to burn in the interface.  The separate interface file(s)
        are placed in path, if specified, or in the current directory if
        path is not specified.  (For these files to be effectively
        installed, they must be created in the same directory in which the
        editor program resides.)

        If you are compiling a ".ui" user-interface file, then a "tseui.dat"
        interface file will be created; and if the ".ui" file contains a
        configuration (Config/EndConfig) section, then a "tsecfg.dat"
        interface file will also be created containing the configuration
        settings from that section.  If you are compiling a ".cfg" settings
        file, then a "tsecfg.dat" interface file will be created.

        These interface files are effectively installed in the editor, in
        that they will be automatically activated by the editor each time the
        editor is started; no further action is necessary.

      • -? (or -h) instructs the compiler to display the compiler syntax.

      • -v instructs the compiler to generate debug information in the
        resulting object (".mac") file.  (For more information, see
        "Debugging Macros" later in this chapter.)

      • -dsymbolic_constant[=integer_constant] instructs the compiler
        to define symbolic_constant and optionally assign it the value
        integer_constant.  If integer_constant is not specified, a value
        of 1 is given to symbolic_constant.

        The -d switch is useful when you want to dynamically assign a value
        for a conditional compilation directive.  (For more information, see
        "Conditional Compilation Directives" in the chapter on
        "Macro Language Syntax.")

    • source_filename is the name of the macro source file to compile.

      If source_filename contains wildcards, all matching files are
      compiled.

      List files are supported using the "@" character.  For example, to
      compile the three macros, MOE.S, LARRY.S, and CURLY.S, you could create
      a file called STOOGES and place the following lines in it:

        MOE.S
        LARRY.S
        CURLY.S

      Then run sc32:

        sc32 @stooges

      All files listed in STOOGES are then compiled.

    • object_filename is an optional parameter that specifies the desired
      name of the resulting object file, if you are compiling an external ".s"
      macro file.  If not specified, the object (Compiled Macro) filename will
      be the same as the source filename, but with an extension of ".mac". The
      object file will be placed in the same directory as the source file,
      unless you specify a path for the object file.





Compiling Macros (Overview)

Once you have written the source code for a macro, it must be translated from
the original English-like format, to a binary format (called an "object file")
that is executable by the editor.  This process is called "compiling."  When
you execute a macro file, it is the compiled version that the editor actually
processes.  Thus, it is necessary to compile the source for a macro before it
can be executed.  If you later make changes to the macro source code, you must
compile it again before your changes will take effect.


Compiling Macros from Inside the Editor
───────────────────────────────────────

To compile a macro file from within the editor, use the Compile command.  To
execute Compile, press <Ctrl F9>, or select "Compile" from the Macro Menu.  If
the compile completes successfully, the editor will pop up a selection menu
prompting you to "Load" or "Execute" the macro file, or "Cancel" the command.
Select "Execute Macro".  You will then see the message "Hello, World!" appear
on the StatusLine.  Congratulations!  You have just written and compiled your
first macro file!


Compiling Macros from Outside the Editor
────────────────────────────────────────

If, for some reason, you need to compile a macro file from outside the editor,
you will need to run the SAL macro compiler program.  The format for the
previous example would be:

    sc32 hello

This will create a Compiled Macro file called "HELLO.MAC".





Compiling Programs from Within the Editor

The Compile command provides a convenient tool for compiling source for a
number of programming languages.  The error-handling features of the Compile
command assist you in locating source code errors for correction.

The section "Compiling Macro Source," in the chapter on
"Creating and Using Macros," describes the operation of the Compile
command, specifically when used to compile external macros written in the
editor's macro programming language (SAL).  When used with other programming
languages, Compile operates similarly.

To execute Compile, press <Ctrl F9>.  Or, you can press <Shift F9> to pop up
the Compile menu, and then select "Compile Current File".

When you execute Compile, the editor saves the current file (if modified) and
attempts to execute the appropriate compiler, based on the filename extension
of the current file.  (If a compiler has not been pre-defined for the
extension of the current file, the editor pops up a PickList of defined
compilers from which you can choose an appropriate compiler.)  For Compile to
operate successfully, the compiler program you wish to execute must exist in
the current directory or in a directory included in your PATH environment
variable setting.  Also, the compiler program must be one that has been
defined in the editor (as described later in this section).

The editor then invokes the indicated compiler program, using the current file
as the source input.  The output (executable) file is created according to the
operation of the compiler program.  If the compiler program encounters any
statements for which it issues warning messages, the following occurs:

    • A temporary Errors buffer is created containing the error and/or warning
      messages issued by the compiler program.

    • The editing screen is split horizontally, and the temporary Errors
      buffer is loaded into the new window.  The cursor is placed on the first
      Error message in the new window.  As you move through the Error
      messages, the source file scrolls so that the corresponding source line,
      as indicated by the Error message, is displayed in the source window.

    • Special key assignments are activated to allow you to move through the
      Error messages, and to readily switch windows to go to any line in the
      source file that is identified in an Error message.  In the Errors
      window, you can position the cursor on an Error message, then press
      <Enter> or <Escape> to switch to the source window and automatically
      position the cursor at the corresponding source line.  Or, you can press
      <Alt F7> or <Alt F8> to move the cursor to the next or previous error
      (respectively) in either the Errors buffer or the source file, depending
      on the window in which you are located.  To display a list of the
      special Errors key assignments and their associated functions, press
      <F1> from the Errors window, or press <Shift F9> and select "Help on
      Keys" from the Compile menu.

In the source file window, you can make necessary corrections to the source.
To switch back to the Errors window, use the window-changing commands.  Once
you have corrected your source, you can then re-execute the Compile command.
If the compilation is successful, the Errors buffer is cleared.

The pop-up Compile menu gives you a convenient way to perform the Compile
options and Errors functions.  To pop up this menu, press <Shift F9>.  From
this menu, you can execute the Compile command, select the next or previous
error, switch between the source and Errors windows (which re-opens the Errors
window if it is currently closed), close the Errors window, and display Help
on the special Errors key assignments.

Two additional entries on the Compile menu allow you to access and maintain
the compiler setup entries that are defined in the editor:  "Compile from
List" and "Debug Compiler Setup".  The compiler setup entries identify the
compiler programs that are available for execution by the Compile command, and
dictate how the editor is to handle error and warning messages issued by the
compiler programs.

The selection "Compile from List" allows you to display a PickList of the
compilers defined for the current filename extension.  If no compilers are
defined for the current extension, then all defined compiler setup entries are
listed.  You can select a compiler entry from this list for execution.

The "Compile from List" option also allows you to change or delete existing
compiler setup entries, or even add your own compiler entries.  The compiler
setup entries are maintained by filename extension.  For each indicated
filename extension, the compiler setup information specifies:

    • the command-line information (including command-line switches) necessary
      to execute the appropriate compiler;

    • a short description of the compiler setup entry;

    • the method for handling output messages from the compiler; and

    • the rules (or parameters) used by the editor to find and display the
      compiler output messages.

For Help on adding or changing compiler setup entries, press <F1> from the
list of setup entries.

Once you have added or changed a compiler setup entry, you can use the
debugging mode to work out any errors you may have in your compiler setup.
First load (or create) a source file with the appropriate filename extension
for the language compiler you are using.  Then select "Debug Compiler Setup"
on the Compile menu.  A PickList of available compiler setup entries is
displayed.  Select the compiler entry that you want to debug.  The editor
invokes the indicated compiler, but as it encounters a compiler-generated
output message, based on the parameters identified in your setup entry, the
editor pauses.  The error identification type (such as "error," "warning," or
"note") issued by the compiler is displayed, along with the line number,
column number, and filename of the erroneous source line.  The compiler's
error or warning message is also displayed.  At any time during the debugging
process, you can cancel the compiling operation or instruct the editor to
complete compilation without further pausing.

In addition to giving you access to your external language compiler from
within the editor, a number of other features are included to help you when
entering program source code.  The chapter on "Editing Modes"
describes SyntaxHilite mode, SmartIndent mode, C mode, and Template
mode, which are helpful for entering code for certain programming
languages.  The chapter on "Search Features:  Finding and Replacing Text"
describes the Match command (which allows you to search for the matching
bracketing character for a group of opening/closing character pairs),
and the FunctionList command (which lists all function or procedure
declaration lines in a file).  The chapter on "Moving Through Text in a File"
describes the BegPara, EndPara, NextPara, and PrevPara commands, which
move the cursor to the beginning or end of the current function or
procedure, or to the next or previous function or procedure.





Conditional Compilation Directives

A conditional compilation directive is an advanced-usage feature that allows
you to selectively compile portions of a macro based on condition(s) supplied
at compile time.

To use this feature, you define special constant directives that are used to
determine whether certain portions should be compiled.  The value for each of
the constant directives can be set statically (by setting the appropriate
values in the code itself before compilation), or dynamically (by passing
command-line switches to the SAL compiler program).

To statically set a conditional compilation directive in the code itself, use
the #define statement.  The syntax for declaring a #define statement is:

    #define  identifier  constant_numeric_expression

where:

    • #define declares the following identifier as a compilation
      directive.

    • identifier is any valid user-definable identifier.  (For more
      information, see "Identifiers" earlier in this chapter.)

    • constant_numeric_expression is any numeric constant expression.
      (For more information, see "Constants" earlier in this chapter.)

For example:

    #define D40_VERSION     1
    #define DEBUG           TRUE

To dynamically assign a value to a conditional compilation directive, use the
"-d" command-line switch for the SAL compiler program.  (For more information
on passing a command line to the SAL compiler, see "Compiling Macros" in
the chapter on "Using Macros.")

When the program is compiled, the value assigned to the directive (either by
a #define statement in the macro source code, or by a value passed on the SAL
compiler command line) is used to control conditional compilation of the
code.  The following statements are available for referencing the directives,
as appropriate, within the macro source:

    #ifdef identifier

    #ifndef identifier

    #ifexist filename

    #ifnexist filename

    #if numeric_expression

    #else

    #endif

The "#ifdef" and "#ifndef" statements are used to see if a conditional
compilation directive has been defined.  For example:

    #define JOHNS_VERSION   1

    #ifdef JOHNS_VERSION
        // normal SAL statements go here
    #endif

    #ifdef PAMS_VERSION
        // normal SAL statements go here
    #endif

In the above example, the statements under JOHNS_VERSION would be compiled,
while the statements under PAMS_VERSION would not be compiled, since
PAMS_VERSION is not defined.

The "#if" statement is used to see if a conditional compilation directive
evaluates to TRUE (non-zero) or FALSE (zero).  The directive referenced via
the "#if" statement must have been defined, or a compile-time error will be
generated.  For example:

    #define MIKES_VERSION   0

    #if MIKES_VERSION
        // normal SAL statements go here
    #endif

    #if RAYS_VERSION
        // normal SAL statements go here
    #endif

In the above examples, the statements under MIKES_VERSION would not be
compiled, since the value of MIKES_VERSION is 0.  The second "#if" test would
generate a compile-time error, since RAYS_VERSION has not been defined.

As with the normal "if" statement, "#else" and "#endif" statements are
available for use with the "#if" and "#ifdef" statements.





Configuration Options Available Interactively

The various configuration options are grouped into the following categories,
which correspond to the pop-up menu selections available in IConfig:

    • System/File Options

      This category includes system and file-related options.


    • Keyboard/Mouse Options

      This category includes keyboard and mouse options.


    • Command/Format Options

      This category includes options that affect the behavior of certain
      commands, and that indicate the format of the date and time stamps.


    • Text Entry/Block Options

      This category includes options that affect the behavior of certain
      text-entry and block operations.


    • Tab/Margin Options

      This category includes tab options, along with settings for the left and
      right editing margins.


    • Print Output Options

      This category includes printing options.


    • Display/Color Options

      This category includes options that affect the appearance of the screen
      display, and that indicate settings for the screen colors.


The following sections describe the options that are available under each of
the above categories.  The editor's internal option name (that is, the
variable name used by the editor's macro language) is indicated in parentheses
to the immediate right of each option.  The value of the standard setting for
each option is also indicated to the far right of each option, preceded by
"Std:" ("Standard").


NOTE:   Certain options take effect only when the editor is restarted.  These
        options are indicated by the character "*" preceding the option.
        Changes made to any of these options do not take effect until you save
        the settings, and then exit and restart the editor.


System/File Options
───────────────────




▪ Path(s) for Supplemental Files    (TSEPath)               Std: empty

  Indicates additional drive/directory paths in which the editor is to search
  for supplemental files that are needed for certain commands.  This includes:
  external Compiled Macro files (that you specify when you execute the
  LoadMacro or ExecMacro commands, or that are needed by other operations that
  invoke macros), along with data files required by certain Compiled Macro
  files; the Help files required by the HelpSystem; and the word list files
  used by SpellCheck.

  When this option is selected, a prompt box is displayed containing the
  message, "Supplemental file path(s):", along with the current designation
  (if any) for this option.  The existing path(s) can be modified or
  removed.

  Multiple paths can be specified; however, no individual path can exceed 80
  characters.  To specify multiple paths, include a semicolon at the end of
  each path (except the final path).  If multiple paths are specified, the
  editor searches in the order in which the paths are listed.


  The path(s) specified by TSEPath are used by the editor as part of its
  search procedure when attempting to locate supplemental files.  The editor
  successively searches the following directories to locate a needed
  supplemental file:

    1.  The current directory

    2.  The drive/directory path(s) indicated by the TSEPath variable, as
        well as the following subdirectories (if they exist) of each directory
        indicated by TSEPath:  MAC\ for external Compiled Macro files and any
        required data files, SPELL\ for SpellCheck word-list files, and HELP\
        for Help files

    3.  The editor load directory, as well as the subdirectories identified
        in 2. above (if they exist in the editor load directory)


▪ Path for Keyboard Macro Files     (KbdPath)               Std: empty

  Indicates the drive and directory path in which Keyboard Macro files are
  stored.  The indicated drive/directory is the directory to which Keyboard
  Macro files are written when no path is specified when you execute the
  SaveKeyMacro command.  It is also the directory that the editor searches
  when no path is specified when you execute the LoadKeyMacro command, and the
  Keyboard Macro file could not be located in the current directory.

  When this option is selected, a prompt box is displayed containing the
  message, "Keyboard Macro path:", along with the current designation (if any)
  for this option.  The existing path can be modified or removed.

  Only one drive/directory path can be specified.  If this option is empty
  (which is the standard setting), the editor uses only the current directory.

▪ *Empty Command-Line Action        (StartupFlags)          Std: MENU

  Indicates the file-selection behavior of the editor that will be in effect
  when the editor is started with no command-line parameters specified (that
  is, with no file specifications or editing options included on the command
  line).  The available options are:

        Selection                File-selection Behavior
        _____________   __________________________________________

        PROMPT          Instructs the editor to issue the "File(s)
                        to edit:" prompt so that a filename
                        specification can be entered

        FILE MANAGER    Instructs the editor to execute the
                        FileManager command, passing it a file
                        specification of "*.*"

        RECENT          Instructs the editor to display the Recent
                        Files list

                        This option valid only if "Persistent
                        Recent Files", described under
                        "Command/Format Options", is ON

        UNNAMED         Instructs the editor to open an "unnamed"
                        file, by executing the NewFile command

        PICKLIST        Instructs the editor to display a PickList
                        of files in the current directory

        RESTORE STATE   Instructs the editor to restore a previous
                        editing environment (provided environment
                        information was saved for a previous
                        session)

        MENU            Instructs the editor to display a
                        selection menu from which you can choose
                        one of the above options or execute the
                        Where command

                        Also instructs the editor to re-display
                        selection menu when you exit the editor

                        Causes "EditFile Prompt on Quit" to have
                        no effect



  (For more information on starting the editor without specifying any options
  or filenames, see "Starting the Editor with No Command-Line Parameters" in
  the chapter on "Starting the Editor.")

▪ Single Instance of the Editor   (SingleInstance)    Std: OFF

  If SingleInstance is Off, the editor will always start as a separate,
  non-shared instance for editing purposes.

  If SingleInstance is On, a single shared instance of the editor is started,
  if a shared instance of the editor is not running.  If a shared instance of
  the editor is running, then the existing instance of the editor is used for
  editing purposes.


▪ Default File Extensions   (DefaultExt)    Std: UI S SI C CPP H JAVA PAS INC
                                                 BAT PRG TXT DOC HTML ASM

  Identifies the extensions used by the EditFile command to locate a file when
  a filename is specified without an extension (and does not end with a ".").
  The editor searches for a matching filename in the order in which the
  extensions are specified.

  When this option is selected, the editor displays the prompt, "Default file
  extensions:", and lists the current set of extensions.  Make any changes or
  additions by typing extension value (without the preceding ".") separated
  by a space, and then press <Enter>.

▪ File Locking                      (FileLocking)           Std: NONE

  Indicates whether the editor will lock files that are loaded.

  Two types of file-locking are available:  Read-Only and Handle.  Valid
  selections for this option are:

    Selection                      Description
    _________   __________________________________________________

    NONE        Disables the editor's file-locking routine.

    READONLY    Instructs the editor to lock each file by setting
                its read-only attribute.

    HANDLE      Instructs the editor to lock each file by keeping
                its associated file handle open until the file is
                closed (that is, removed from the editor).


  (For more information on file-locking, see "Locking Files" in the chapter
  on "Loading, Processing, and Saving Files.")

▪ *Load Wild from Command Line      (LoadWildFromDOS)       Std: ON

  Toggles whether the editor selects all matching files when a filename
  containing wildcard characters ("*" or "?") is entered at the command line.
  Set this option ON to have the editor select all matching files; set this
  option OFF to have the editor display a PickList of matching files from
  which you can choose.

▪ Load Wild from Inside             (LoadWildFromInside)    Std: OFF

  Toggles whether the editor selects all matching files when a filename
  containing wildcard characters ("*" or "?") is entered at a "File(s) to
  edit:" prompt within the editor.  Set this option ON to have the editor
  select all matching files; set this option OFF to have the editor
  display a PickList of matching files from which you can choose.

▪ File PickList Settings

  Allows you to select a number of options for file-related PickLists.  These
  options control the treatment of directories and the order of the entries in
  a PickList.

  Following are the configurable PickList options that are available on the
  File PickList Settings pop-up menu:

▪ Changes Directory                 (PickFileChangesDir)    Std: ON

  Toggles whether the editor changes the current directory when a new
  directory is selected from a file PickList.  Set this option ON to have the
  editor change the current directory to the directory selected from a
  PickList; set this option OFF to prevent the editor from changing the
  current directory when a different directory is selected from a PickList.


▪ Force Showing Directories         (PickFileFlags)         Std: ON

  Toggles whether the editor includes all directories in the path that
  contains the files displayed in the current PickList.  Set this option ON to
  have all directories included, regardless of the filename specification; set
  this option OFF to omit directories from the PickList, except those that
  match the filename specification.  (This option has no effect on the
  operation of the Filename Completion option.  For more information, see
  "Obtaining a File PickList within a Prompt Box" in the chapter on
  "Command Prompts and PickLists.")

▪ Show Directories at Top           (PickFileFlags)         Std: ON

  Toggles whether the editor displays any directory entries in the current
  PickList at the top of the PickList.  Set this option ON to have all
  directories placed at the top of the PickList; set this option OFF to have
  any included directory entries located according to the sort order of the
  PickList.

▪ Precede Directory Entries with Slash  (PickFileFlags)     Std: ON

  Toggles whether the editor places a slash at the beginning of any directory
  entries in the current PickList. Set this option ON to have a slash placed
  at the beginning of each directory entry; set this option OFF to prevent the
  editor from placing a slash at the beginning of each directory entry.

▪ Sort Order                        (PickFileSortOrder)     Std: ASCENDING

  Indicates whether file-related PickList entries will be displayed in
  ascending or descending order, according to the Sort Key that is selected.
  (See "Sort Key" below.)  Toggle this option to ASCENDING or DESCENDING, as
  needed.

▪ Sort Key                          (PickFileSortOrder)     Std: NAME

  Indicates the sort key that will be used to display file-related PickList
  entries.  (The sort order is determined by the "Sort Order" option above.)

  Sort key choices are:

        Selection                  Description
        _________   __________________________________________

        NAME        Sort by full filename, including extension
        EXTENSION   Sort by filename extension only
        SIZE        Sort by file size
        DATE        Sort by file date
        ATTRIBUTE   Sort by file attributes


▪ Line-Termination String           (EOLType)               Std: AS LOADED

  Identifies the character string to be placed at the end of each line (except
  the last line) when the file is saved to disk.  (See
  "File-Termination String" below.)

  Line-termination choices are:

        Selection   Character(s) to Add to End of Each Line
        _________   _______________________________________

        AS LOADED   Use the same termination character as is
                    in the file when it is initially loaded
        CR ONLY     Add carriage return only
        LF ONLY     Add linefeed only
        BOTH CR/LF  Add carriage return/linefeed pair

  If you select AS LOADED, the line termination string is determined by what
  is in the file itself when it is loaded into the editor. If ALL lines in
  the file are terminated by a linefeed character (LF), then the editor will
  terminate each line with a LF when the file is saved.  If ALL lines in the
  file are terminated by a carriage return character (CR), then the editor
  will terminate each line with a CR when the file is saved.  For all other
  files, the editor will terminate each line with a CR/LF when the file is
  saved.

▪ File-Termination String           (EOFType)               Std: EOL STRING

  Identifies the optional character string to be placed at the end of the file
  when saved to disk.  (See "Line-Termination String" above.)

  File-termination choices are:

          Selection         Character(s) to Add to End of File
        _____________   _________________________________________

        NOTHING         Do not add any termination characters
        ^Z ONLY         Add Control-Z only
        EOL STRING      Add Line-Termination String only
        EOL STRING/^Z   Add Line-Termination String and Control-Z


▪ Create Backups                    (MakeBackups)           Std: ON

  Toggles whether the editor creates a backup before a file is saved.  The
  backup is an image of the file as it is on disk before the copy in memory is
  written to disk.  The name of the backup copy is the same as that of the
  file in memory, but with a file extension as specified by "Backup Extension
  String" (described later in this section).  The backup copy is created in
  the same directory from which the file in memory was loaded.  Set this
  option ON to create a backup copy of a file when the file is saved; set
  this option OFF if you do not want backup copies made.

  Note that this option takes precedence over the "Protected Saves" option
  (below).  If "Create Backups" is set ON, "Protected Saves" is ignored.

▪ Protected Saves                   (ProtectedSaves)        Std: ON

  Toggles whether the editor saves files using its normal protected, safe
  method.  Set this option ON for the editor to first write the file to disk
  under a temporary name, then rename the file to the original name once the
  temporary file is successfully created on disk (and optionally create a
  backup copy of the original file).  Set this option OFF for files to be
  saved by directly overwriting the original file on disk (with no backup copy
  created).

  Note that the "Create Backups" option (above) takes precedence over this
  option.  If "Create Backups" is set ON, "Protected Saves" is ignored.

▪ Backup Extension String           (BackupExt)             Std: BAK

  Indicates the extension to be used for backup files.  The usual extension is
  "BAK".  To specify a different backup extension, enter a 1- to 3-character
  extension value (without the preceding ".").

▪ Backup Files Path           (BackupPath)                  Std: empty

  Determines where backup files are written. BackupPath should be set to an
  existing path.  If the path assigned does not exist, a backup file will not
  be written.

▪ Save State on Exit                (SaveState)             Std: OFF

  Indicates whether the editor saves certain information about the current
  editing environment ("state") when you exit from the editor.  The editing
  environment that is saved includes the file(s) that are loaded and the
  window(s) and file(s) that are displayed on the screen; the position of the
  cursor at the time the session is ended; the block (if any) that is marked;
  the bookmarks that are placed; and the settings of selected editing options
  (such as those on the "Options" Menu).

  This option is valid only when you terminate the current editing session
  using either the Exit (<Alt X>) or the SaveAllAndExit command.  Set this
  option to ON or LOCAL for the editor to save environment information when
  you exit using one of these two commands.  Editing environment information
  will be saved in a file TSESTATE.DAT.  If set to ON, the TSESTATE.DAT file
  is saved in the editor load directory.  If set to LOCAL, the TSESTATE.DAT
  file is saved in the current directory.

  Set this option OFF if you do not want environment information to be saved
  when you exit the editor.

  If environment information is saved, it can be restored in a subsequent
  editing session.  (For more information on restoring the editing
  environment, see "Saving/Restoring the Editing Environment" in the chapter
  on "Loading, Processing, and Saving Files.")

▪ Use the Windows Common File Dialogs  (UseCommonDialogs)   Std: OFF

  By default, the editor uses its own style of prompts to request filenames.
  If this variable is set ON, the familiar Windows common file dialogs are
  used instead.


(For more information on related topics, see the chapters on
"Starting the Editor," "Loading, Processing, and Saving Files," and
"Creating and Using Macros.")



Keyboard/Mouse Options
──────────────────────


▪ Equate Enhanced Keyboard          (EquateEnhancedKbd)     Std: ON

  Toggles whether the editor is to equate the enhanced grey keys (grey Cursor
  Up/Down/Left/Right, Page Up/Down, Home, End, Insert, and Delete) to the
  equivalent "normal" keys (on the numeric keypad).  For this option to be
  effective, you must have an enhanced keyboard, such as a 101-key keyboard,
  (and the option "Use Enhanced Keyboard" must be ON in the DOS version). Set
  "Equate Enhanced Keyboard" ON if you have an enhanced keyboard and want the
  enhanced keys to operate identically to the normal keys; set this option
  OFF if you have an enhanced keyboard and want the editor to distinguish
  between the enhanced keys and the normal keys (to allow assignment of
  different commands to the two sets of keys).



▪ Mouse Hold Time                   (MouseHoldTime)         Std: 9

  Indicates the amount of time a mouse button must be held down to distinguish
  between the mouse button being clicked (pressed and immediately released)
  versus being pressed and held.  When a mouse button is clicked, a command
  executed from a mouse scrollbar is executed one time only.  When a mouse
  button is pressed and held, the command is executed repeatedly until the
  mouse button is released.  (See "Mouse Repeat Delay" below.)

  To select the amount of time that you must hold down the mouse button before
  the editor begins repeating a mouse-executed command, set "Mouse Hold Time"
  to the desired value, from 1 through 36.  The time is measured in terms of
  machine timer ticks, in 1/18-second increments.

  For example:  A value of 9 means that the mouse button is considered clicked
  if pressed and released within 1/2 second; otherwise, if the mouse button is
  pressed and held for longer than 1/2 second, the editor begins repeating the
  selected command.

▪ Mouse Repeat Delay                (MouseRepeatDelay)      Std: 0

  Indicates the relative amount of time the editor is to wait between
  repetitions of a command when a mouse button is pressed and held.  (See
  "Mouse Hold Time" above.)  When a mouse button is pressed and held, a
  command executed from a mouse scrollbar is repeatedly executed as long as
  the mouse button is held down.

  To control the amount of time that the editor delays between each repetition
  of a mouse-executed command, set Mouse Repeat Delay to an appropriate value,
  from 0 through 65535.  This option is hardware dependent, and is relative to
  the speed of your particular machine.  To slow down repetition, increase the
  value of Mouse Repeat Delay; to speed up repetition, decrease the value.



(For more information on using a mouse with the editor, see the chapter on
"Mousing Around the Editor.")


Command/Format Options
──────────────────────

▪ Max History Per List              (MaxHistoryPerList)     Std: 50

  Indicates the maximum number of History entries to be stored in the History
  Buffer for each History list, ranging from 1 to 1000.  This number is the
  maximum number of History items that are maintained for each particular
  command, or command group, prompt.

  Note that the total number of History entries, for all command/command
  groups, is limited to the maximum number of History entries as specified by
  "Max History Entries" (described below).

  If the "Persistent History" option is ON (described later in this section),
  the items stored in the History Buffer will be maintained across editing
  sessions.  The History Buffer then has the potential to grow quite large.
  "Max History Per List," along with "Max History Entries" (described below),
  can be used to limit the History Buffer to a manageable size.

▪ Max History Entries               (MaxHistorySize)        Std: 1000

  Indicates the maximum number of History entries to be stored in the History
  Buffer, ranging from 1 to 10,000.

  This number is the total number of History items for all command prompts.

  The number of History entries that are stored for each particular command
  prompt may also have an effect on the total number of History entries that
  are maintained.  See "Max History Per List" (described above).

  Note that setting "Max History Entries" to a smaller number during an
  editing session does not immediately remove entries already in the History
  Buffer.  Thus, the effect of decreasing "Max History Entries" may not be
  realized until the editor is restarted.

  If the "Persistent History" option is ON (described later in this section),
  the items stored in the History Buffer will be maintained across editing
  sessions.  The History Buffer then has the potential to grow quite large.
  "Max History Entries," along with "Max History Per List" (described above),
  can be used to limit the History Buffer to a manageable size.

▪ Persistent History                (PersistentHistory)     Std: ON

  Toggles whether the entries stored in the History Buffer are maintained
  across editing sessions.  Set this option ON for entries in the History
  Buffer to be saved at the end of each editing session, and then reloaded
  into the History Buffer at the start of the next editing session; set this
  option OFF for the History Buffer to be cleared at the end of each editing
  session.

  If "Persistent History" is ON, History Buffer items are maintained in the
  file TSEHIST.DAT in the editor load directory.  The maximum number of
  items that are kept in this file is governed by the settings of "Max History
  Entries" and "Max History Per List" (described earlier in this section).

▪ Max Recent Files                  (MaxRecentFiles)        Std: 200

  Indicates the maximum number of files to be stored in the Recent Files list,
  ranging from 1 to 5000.  This number is the total number of filenames that
  will be maintained and displayed by the editor when you execute the
  ListRecentFiles command.

  If the "Persistent Recent Files" option is ON (described later in this
  section), the items stored in the Recent Files list will be maintained
  across editing sessions.  "Max Recent Files" can be used to limit the size
  of the Recent Files list.

▪ Persistent Recent Files       (PersistentRecentFiles)     Std: ON

  Toggles whether the entries stored in the Recent Files list are maintained
  across editing sessions.  Set this option ON for entries in the Recent Files
  list to be saved at the end of each editing session, and then reloaded into
  the Recent Files list at the start of the next editing session; set this
  option OFF for the Recent Files list to be cleared at the end of each
  editing session.

  If "Persistent Recent Files" is ON, entries in the Recent Files list are
  maintained in the file TSEFILES.DAT in the editor load directory.  The
  maximum number of items that are kept in this file is governed by the
  setting of "Max Recent Files" (described earlier in this section).

▪ WordSet Characters                (WordSet)               Std: 0-9A-Z_a-z

  Identifies the characters by which the editor defines a word for
  word-sensitive commands, such as WordRight, WordLeft, DelLeftWord,
  DelRightWord, FindWordAtCursor, MarkWord, and the "Words" option of Find and
  Replace.  The WordSet specification is case sensitive.

  When this option is selected, a prompt box is displayed containing the
  message, "WordSet characters:", along with the current specification.  You
  can modify the existing set, or enter a whole new set, according to the
  following guidelines:

    • Any of the 256 ASCII characters can be designated as part of the
      WordSet.

    • Do not enter a space between characters, unless you want to include the
      space character as a WordSet character.

    • To indicate a range of sequential characters, enter the first character
      in the range, immediately followed by "-", and then enter the last
      character in the range.  (For example, to indicate the lower-case
      letters of the alphabet, enter: a-z)

    • To include the dash character ("-") as a WordSet character, it must be
      listed as the first or last character within the set.

    • The back-slash ("\") character is used as an escape character.  To
      include the back-slash character in the set, use two back slashes
      ("\\").

    • The regular-expression notations for decimal and hexadecimal numbers can
      be used in a WordSet specification, as "\dnnn" (where "nnn" is a decimal
      number) or "\xnn" (where "nn" is a hexadecimal number).

    • The tilde ("~") character, if listed as the first character in the
      WordSet specification, is used to indicate that the remainder of the
      specification contains all the characters that are NOT part of the
      WordSet.  That is, the WordSet consists of all characters that are NOT
      listed in the specification.


▪ *Initial Find Options             (FindOptions)           Std: I

  Identifies the initial option(s) for the Find command.  A maximum of six
  options can be specified.

  These options are placed in the Find options prompt box the first time the
  Find command is executed in each editing session, unless "Persistent
  History" (described earlier in this section) is ON.  These options are
  effective only when there are no History entries for the Find options
  prompt.

  The "Initial Find Options" are also used as the effective options for the
  FindWordAtCursor command.

  (For more information on the valid Find options, see the chapter on
  "Search Features:  Finding and Replacing Text.")


▪ *Initial Replace Options          (ReplaceOptions)        Std: empty

  Identifies the initial option(s) for the Replace command.  A maximum of six
  options can be specified.

  These options are placed in the Replace options prompt box the first time
  the Replace command is executed in an editing session, unless "Persistent
  History" (described earlier in this section) is ON.  These options are
  effective only when there are no History entries for the Replace options
  prompt.

  (For more information on the valid Replace options, see the chapter on
  "Search Features:  Finding and Replacing Text.")

▪ Center Found Text                 (CenterFinds)           Std: OFF

  Toggles whether the line containing the text located by the Find or Replace
  commands is centered vertically in the current window.  Set this option ON
  to center the line containing the "found" text.  Set this option OFF to
  scroll the line containing the "found" text to the current cursor line
  (leaving the cursor line position unchanged relative to the screen).

▪ Beep on Failed Find               (Beep)                  Std: ON

  Toggles whether the editor sounds a beep when the specified search string is
  not located by the Find or Replace commands.  Set this option ON for a beep
  to sound when a string is not located; set this option OFF to suppress the
  beep.

▪ *Change Prompt in Shell           (ChangeShellPrompt)     Std: ON

  Toggles whether the editor changes the command-line prompt string when the
  Shell command is executed.  Set this option ON to have the notation
  "TSE-Shell" added to the current prompt string when Shell is executed.  Set
  this option OFF to leave the prompt string unchanged.

▪ EditFile Prompt on Quit           (QuitToPrompt)          Std: OFF

  Toggles whether the editor issues the "File(s) to edit:" prompt after
  closing the last file following execution of the QuitFile or SaveAndQuitFile
  commands.  Set this option ON to have the "File(s) to edit:" prompt
  displayed after the last file is closed via the QuitFile or SaveAndQuitFile
  commands.  Set this option OFF to have the editor exit to the operating
  system (or the calling program) after the last file is closed.

  NOTE:  If "Empty Command-Line Action" is set to MENU, then this option
  has no effect.

▪ Keep Undo Beyond Save             (KeepUndoBeyondSave)    Std: OFF

  Toggles whether the editor purges Undo/Redo information for a file after the
  SaveFile command is executed for that file.  Set this option OFF to have the
  Undo/Redo information purged when a file is saved; thus, you cannot restore
  any changes made before that file was saved.  Set this option ON to have the
  Undo/Redo information maintained even after a file is saved; thus, you can
  restore changes made before that file was saved.

▪ Date Format                       (DateFormat)            Std: MM-DD-YYYY

  Indicates the format of the current date stamp.  Six formats are
  available:  MM-DD-YYYY, DD-MM-YYYY, YYYY-MM-DD, MM-DD-YY, DD-MM-YY, or
  YY-MM-DD (where "MM" represents the two-character current month, "DD"
  represents the two-digit current day of the month, "YYYY" represents the
  four-digit current year, and "YY" represents the last two digits of the
  current year).

  This option affects the format of the date from the DateTimeStamp command,
  as well as the format of the date in the PrintHeader and PrintFooter print
  options.

▪ Date Separator                    (DateSeparator)         Std: /

  Indicates the character to use as the separator between the three parts of
  the current date.  (For example, in the date specification "01/23/57", the
  separator is the "/" character.)  Any character can be selected as the date
  separator.

  This option affects the format of the date from the DateTimeStamp command,
  as well as the format of the date in the PrintHeader and PrintFooter print
  options.

▪ Time Format                       (TimeFormat)            Std: 12-HOUR

  Indicates the format of the current time stamp.  Two formats are available:
  12-HOUR or 24-HOUR.  12-HOUR time is in the format "HH:MM Xm" (where "HH"
  represents the hour from 01 through 12, "MM" represents the minutes from 00
  through 59, and "Xm" represents the morning or evening as "am" or "pm",
  respectively).  24-HOUR time is in the format "HH:MM:SS" (where "HH"
  represents the hour from 00 through 23, "MM" represents the minutes from 00
  through 59, and "SS" represents the seconds from 00 through 59).

  This option affects the format of the time from the DateTimeStamp command,
  as well as the format of the time in the PrintHeader and PrintFooter print
  options.

▪ Time Separator                    (TimeSeparator)         Std: :

  Indicates the character to use as the separator between the two parts of the
  current time.  (For example, in the time specification "02:15 pm", the
  separator is the ":" character.)  Any character can be selected as the time
  separator.

  This option affects the format of the time from the DateTimeStamp command,
  as well as the format of the time in the PrintHeader and PrintFooter print
  options.


(For more information on related topics, see the chapters on
"Command Prompts and PickLists," "Loading, Processing, and Saving Files,"
"Moving Through Text in a File," "Manipulating Text,"
"Block Operations," "Search Features:  Finding and Replacing Text,"
"Printing from the Editor," and "Special Commands and Features.")


Text Entry/Block Options
────────────────────────

▪ Insert Mode                       (Insert)                Std: ON

  Toggles Insert mode ON or OFF.  (For more information on Insert mode, see
  the chapter on "Editing Modes.")

▪ AutoIndent Mode                   (AutoIndent)            Std: ON

  Indicates the state of AutoIndent mode, which affects placement of the
  cursor when CReturn (<Enter>) is executed.  Three options are available:
  OFF, ON, or STICKY.  (For more information on AutoIndent mode, see the
  chapter on "Editing Modes.")

▪ WordWrap Mode                     (WordWrap)              Std: OFF

  Indicates the state of WordWrap mode, which affects wrapping of text as
  characters are inserted or deleted.  Three options are available:  OFF, ON,
  or AUTO.  (For more information on WordWrap mode, see the chapter on
  "Editing Modes.")

▪ Template Expansion                (TemplateExpansion)     Std: OFF

  Indicates the state of Template mode, which affects expansion of
  pre-defined templates.

  When set ON, the <Tab> and <Ctrl Tab> keys are configured to operate
  in Template mode.  <Tab> expands a template-defined keyword into its
  pre-assigned text.  (If the cursor is not positioned at the end of a
  Template-defined keyword when you press <Tab>, the <Tab> key behaves
  as it is normally configured.) Pressing <Ctrl Tab> pops up the
  Template menu.

  When set OFF, the <Tab> and <Ctrl Tab> keys behave as they are
  normally configured.

  (For more information on Template mode, see the chapter on
  "Editing Modes.")

▪ Paragraph-End Style               (ParaEndStyle)          Std: BLANK LINE

  Identifies the style used in the text to indicate the end of a paragraph.
  This determines when the WrapPara command stops formatting text.  The two
  recognized paragraph-end styles are:

       Selection                       Description
    ________________    __________________________________________

    BLANK LINE          Paragraphs are separated by blank line(s).
                        WrapPara stops formatting text when a
                        blank line (or the end of the file) is
                        encountered following the text being
                        formatted.

    EQUAL IN/OUTDENT    Paragraphs are separated by indenting or
                        outdenting the first line of each
                        paragraph at a particular column, and/or
                        by blank line(s).  WrapPara stops
                        formatting text when a subsequent line is
                        encountered on which text begins in the
                        same column as the first line of text
                        being formatted, or until a blank line is
                        encountered.

                        If the text on the first line is not
                        indented or outdented with respect to the
                        line immediately following it (that is, it
                        begins in the same column as the text on
                        the following line), then the end of the
                        paragraph is not assumed until a blank
                        line is encountered.  This behavior is the
                        same as that for the BLANK LINE selection.

▪ CReturn Equals Next Line          (ReturnEqNextLine)      Std: OFF

  Toggles whether the CReturn command moves the cursor to the next line
  without splitting the line when Insert mode is ON.  Set this option ON for
  CReturn to simply move the cursor to the next existing line of text even
  when Insert mode is ON.  Set this option OFF for CReturn to behave according
  to its native behavior when Insert mode is ON; that is, by splitting the
  line at the cursor position and moving the cursor, along with the text at
  and to the right of the cursor, to a new line immediately following the
  current line.

  This option has no effect on CReturn when Insert mode is OFF.  When Insert
  mode is OFF, CReturn always moves the cursor to the next line without
  splitting the line, regardless of the setting of this option.

▪ Remove Trailing Whitespace        (RemoveTrailingWhite)   Std: ON

  Toggles whether the editor removes all white (space and tab) characters
  located beyond the last non-white character on the cursor line.  Set this
  option ON to have the editor remove trailing white characters on any line to
  which the cursor moves; set this option OFF to retain any trailing white
  characters on the cursor line.


▪ Line Type                         (LineDrawType)          Std: SINGLE

  Identifies the line-drawing style to be used when LineDrawing mode is ON.
  The available styles are:

       Selection                 Line-Drawing Characters
    ________________        _________________________________

    SINGLE       ┌─┐        Single-line top and side

    DOUBLE TOP   ╒═╕        Double-line top, single-line side

    DOUBLE SIDE  ╓─╖        Double-line side, single-line top

    DOUBLE BOTH  ╔═╗        Double-line both top and side

    ASCII        +-|        ASCII top and side

    ERASER                  Blank

    USER-DEFINED [▪]        User-defined top and side


  If you select USER-DEFINED, you then input the character you wish to use,
  within [ ].  (The numeric keypad or the pop-up AsciiChart can be used to
  input a character that is not directly available from the keyboard.)

▪ Insert Line Blocks Above      (InsertLineBlocksAbove)     Std: OFF

  Toggles whether the editor inserts line blocks above the current line.  Set
  this option ON for line blocks to be inserted ABOVE the current line; set
  this option OFF for line blocks to be inserted BELOW the current line.
  (Note that this option affects only line blocks, and not character or column
  blocks.)

▪ Use Current Line If No Block      (UseCurrLineIfNoBlock)  Std: OFF

  Toggles whether the editor treats the current line as a line block when the
  ClipBoard Cut/Copy, the CopyToWinClip, or the CutToWinClip commands are
  executed AND no block is marked in any file.  Set this option ON for the
  current line to be treated as a block for the ClipBoard Cut/Copy,
  CopyToWinClip, and CutToWinClip commands if no block is marked; set this
  option OFF for ClipBoard Cut/Copy, CopyToWinClip, and CutToWinClip to
  operate only on a block marked in the current file.

  The ClipBoard Cut/Copy, CopyToWinClip, and CutToWinClip commands fail
  regardless of this option's setting if a block is marked in a file other
  than the current file.

▪ UnMark After Paste                (UnMarkAfterPaste)      Std: ON

  Toggles whether the editor unmarks text when placed into a file from a
  ClipBoard via the Paste command.  Set this option ON for the text to be
  unmarked once it is placed into a file with the Paste command; set this
  option OFF for the text to remain marked following Paste.


(For more information on related topics, see the chapters on
"Moving Through Text in a File," "Manipulating Text," "Editing Modes,"
"Block Operations," and "Special Commands and Features.")


Tab/Margin Options
──────────────────


▪ Tab Type                          (TabType)               Std: SOFT

  Indicates the type of tab to be used in the editor.  Four options are
  available:  HARD, SOFT, SMART, or VARIABLE.

▪ Tab Width                         (TabWidth)              Std: 8

  Identifies the fixed interval (TabWidth) for placement of tab stops with
  Soft and Hard Tabs.  Valid TabWidth values range from 1 through 16.

▪ Cursor Tab Width              (CursorTabWidth)            Std: 0

  If CursorTabWidth is non-zero, it is used by tabbing commands in
  lieu of TabWidth. On-screen display of spaces for tabs is still
  controlled by TabWidth. If CursorTabWidth is 0, TabWidth is used
  by the tabbing commands, and CursorTabWidth has no effect.

▪ Zero-Based Tab Stops              (ZeroBasedTab)          Std: OFF

  Toggles ZeroBasedTab ON or OFF.  This determines the offset used to compute
  Soft and Hard Tab stops.  Set this option ON to have the tab stops based on
  column 0; set this option OFF to have the tab stops based on column 1.

  (For more information, see "ZeroBasedTab" under "Soft and Hard Tabs" in
  the chapter on "Using Tabs.")

▪ Variable Tab Stops                (VarTabs)               Std: 4 8 16 24 40

  Identifies the tab stop locations used with Variable Tabs.  Tab stops are
  designated by specifying the actual columns at which to place tab stops, and
  may occur at variable intervals.  The maximum variable tab stop location is
  column 255.

  When this option is selected, a prompt box is displayed containing the
  message, "Variable Tab stops:", along with a listing of the current set of
  Variable Tab stops.  You can modify the existing set, or enter a whole new
  set, by typing the appropriate column number(s), separated by spaces.

▪ Expand Tabs (Display Only)        (ExpandTabs)            Std: ON

  Toggles ExpandTabs ON or OFF.  This dictates whether the editor displays
  tabs as the appropriate number of spaces, as determined by the value of
  TabWidth.  Set this option ON to have the editor interpret tab characters so
  that the text is positioned on the screen according to the current TabWidth.
  Set this option OFF to have the editor display each tab character on the
  screen as the physical tab character itself (ASCII 9).  Note, however, that
  ExpandTabs has no effect on any line longer than 255 characters.

  ExpandTabs affects only the screen display of tab characters; it does not
  affect how tab characters are stored in the file itself.  If ExpandTabs is
  ON and the file is subsequently saved, the actual tab characters are stored
  in the file, and NOT the spaces that displayed on the screen.

▪ Detab files when loading              (DetabOnLoad)       Std: OFF

  If ON, tabs are converted to the appropriate number of spaces when a file is
  loaded into the editor. Tabs are expanded based on the value of the TabWidth
  editor variable.

▪ Entab files when saving              (EntabOnSave)        Std: OFF

  If ON, spaces are converted to tabs (as appropriate) when a file is saved.
  Spaces are converted to tabs based on the TabWidth editor variable.

▪ Left Margin                       (LeftMargin)            Std: 0


  Indicates the LeftMargin setting for editing.  The value (if any) specified
  may affect the operation of the CReturn and WrapPara commands, as well as
  WordWrap mode.  Valid values for LeftMargin range from 0 through the maximum
  allowable line length.

  The setting of AutoIndent may affect whether the editor recognizes the
  LeftMargin setting.

▪ Right Margin                      (RightMargin)           Std: 72

  Indicates the RightMargin setting for editing.  The value (if any) specified
  affects the operation of the WrapPara command and of WordWrap mode.  Valid
  values for RightMargin range from 0 through the maximum allowable line
  length.

  A value of 0 for this option is treated the same as a value of 1.


(For more information on related topics, see the chapters on "Using Tabs,"
"Manipulating Text," and "Editing Modes.")


Display/Color Options
─────────────────────

▪ StatusLine At Top                 (StatusLineAtTop)       Std: ON

  Toggles whether the editor displays the StatusLine at the top of the screen.
  Set this option ON for the StatusLine to display at the top of the screen;
  set this option OFF for the StatusLine to display at the bottom of the
  screen.

  The HelpLine, if active, is placed on the screen on the side opposite the
  StatusLine.  (See "Display HelpLine" later in this section.)

▪ StatusLine Fill Character         (StatusLineFillChar)    Std: space

  Identifies the optional character used to fill the unused space on the
  StatusLine.

▪ Display Main Menu                 (ShowMainMenu)          Std: ON

  Toggles whether the editor continually displays the main pull-down Menu.

  Set this option ON to have the main Menu remain on the screen throughout the
  editing session.  The main Menu will be displayed at the top of the screen.

  Set this option OFF if you do not want the main Menu to remain on the screen
  throughout the editing session.

▪ Display HelpLine                  (ShowHelpLine)          Std: ON

  Toggles whether the editor displays the HelpLine bars.  The HelpLine is
  displayed at either the top or bottom of the screen, opposite the
  StatusLine.  (See "StatusLine At Top" earlier in this section.)

▪ HelpLine Delay                    (HelpLineDelay)         Std: 6

  Indicates the amount of time a "shift" (<Shift>, <Alt>, or <Ctrl>) key must
  be held down before the editor updates the HelpLine with the associated
  HelpLine bar.  This option is only valid if "Display HelpLine" (described
  above) is ON.

  To select the amount of time that you must hold down the "shift" key before
  the HelpLine is updated, set "HelpLine Delay" to the desired value, from 0
  through 18.  The time is measured in 1/18-second increments.

  For example:  A value of 0 means that the HelpLine will be updated
  immediately (with no delay) once a "shift" key is pressed; a value of 18
  means there will be approximately a 1-second delay.

▪ Current Window Divider            (CurrWinBorderType)     Std: DOUBLE TOP

  Identifies the type of divider line that is used to separate the current
  window from any other windows on the screen.  Divider choices for the
  current window are:

       Selection                     Window Dividers
    ________________        _________________________________

    SINGLE       ┌─┐        Single-line top and side

    DOUBLE TOP   ╒═╕        Double-line top, single-line side

    DOUBLE SIDE  ╓─╖        Double-line side, single-line top

    DOUBLE BOTH  ╔═╗        Double-line both top and side

    THIN SOLID   ▐▀▌        Thin solid-line top and side

    THICK SOLID  █▀█        Thick solid-line top and side

    ASCII        +-+        ASCII characters (+, -, |)

    3D                      3D characters are used


  If the screen is split into multiple windows, the "top" divider separates a
  horizontal current window, and the "side" divider separates a vertical
  current window.

  The selected top AND side dividers are used to display a FULL border around
  the current window, if either:

    • you have the editor configured to display a full border around each
      window on the screen, or

    • the current window is zoomed.

  (For information about displaying a full border around each window, see
  "Display Border Around Windows" later in this section.)


▪ Non-Current Window Divider        (OtherWinBorderType)    Std: DOUBLE TOP

  Identifies the type of divider line that is used to separate any non-current
  windows from other windows on the screen.  Divider choices for non-current
  windows are the same as those for "Current Window Divider" (above).

  If the screen is split into multiple windows, the "top" divider separates
  each horizontal non-current window, and the "side" divider separates each
  vertical non-current window.

  The selected top AND side dividers are used to display a FULL border around
  each non-current window, provided you have the editor configured to display
  a full border around each window on the screen.  (For information about
  displaying a full border around each window, see
  "Display Border Around Windows" below.)

▪ Display Border Around Windows     (DisplayBoxed)          Std: MOUSE

  Indicates whether the editor displays a full border around the entire
  screen, so that each window (including a single window) is fully "boxed."
  The setting of this option has no effect on the window display when a window
  is zoomed.

  If you change the setting for this option while the screen is split into
  multiple windows, the editor will close all but one window and make the new
  setting effective.

  If you are using a mouse, note that mouse scrollbars in the editor are
  displayed within the window border.  Therefore, to use the mouse scrollbars,
  it is necessary that a full border be displayed around each window, by
  setting this option to either MOUSE or ALWAYS (as described below).

  Valid selections for this option are:

    Selection                      Description
    _________   __________________________________________________

    NEVER       Instructs the editor to never display the outside
                screen border.

    MOUSE       Instructs the editor to display the outside screen
                border only if a mouse is present on your system.
                If a mouse is not present, the editor does not
                display the outside border.

    ALWAYS      Instructs the editor to always display the outside
                screen border.

▪ Cursor Size: Insert               (InsertCursorSize)      Std: 4

  Indicates the size of the cursor when the editor is in Insert mode.  The
  size is specified by selecting a value from 1 through 8, 1 being the
  smallest and 8 the largest.

▪ Cursor Size: Overwrite            (OverwriteCursorSize)   Std: 2

  Indicates the size of the cursor when the editor is in overwrite mode.  The
  size is specified by selecting a value from 1 through 8, 1 being the
  smallest and 8 the largest.

▪ Show End-of-File Marker           (ShowEOFMarker)         Std: ON

  Toggles whether the editor displays a marker indicating that the end of the
  file has been reached.  Set this option ON to have the following line appear
  after the last line of the file to signal the file's end:

      <*** End of File ***>

  Set this option OFF to prevent the marker from displaying at the end of the
  file.

▪ Show Line Numbers                 (ShowLineNumbers)       Std: OFF

  Toggles whether line numbers are displayed on the left side of the editing
  window.


▪ *Startup Video Mode               (StartupVideoMode)      Std: AUTODETECT

  Indicates the number of lines and columns to be displayed on the screen
  (that is, the video mode in effect) when the editor is invoked.  Depending
  on your screen resolution and current font, you can select from the
  following choices:


         Selection                               Video Mode
    ___________________             ____________________________________

    AutoDetect                      Instructs the editor to use the same
                                    mode in effect at editor startup

    25 Lines by 80 Cols             25 lines by 80 columns

    28 Lines by 80 Cols             28 lines by 80 columns

    30 Lines by 80 Cols             30 lines by 80 columns

    30 Lines by 90 Cols             30 lines by 90 columns

    30 Lines by 94 Cols             30 lines by 94 columns

    33 Lines by 80 Cols             33 lines by 80 columns

    34 Lines by 90 Cols             34 lines by 90 columns

    34 Lines by 94 Cols             34 lines by 94 columns

    36 Lines by 80 Cols             36 lines by 80 columns

    40 Lines by 80 Cols             40 lines by 80 columns

    40 Lines by 90 Cols             40 lines by 90 columns

    40 Lines by 94 Cols             40 lines by 94 columns

    43 Lines by 80 Cols             43 lines by 80 columns

    44 Lines by 80 Cols             44 lines by 80 columns

    50 Lines by 80 Cols             50 lines by 80 columns

    Max Lines/Cols                  Maximum lines/columns supported by
                                    current screen resolution and font

    Custom Lines/Cols               User-specified lines and columns

  To change the current video mode in effect during an editing session, change
  CurrVideoMode.  (For more information, see "Selecting the Video Mode" in
  the chapter on "Special Commands and Features.")



▪ Display SyntaxHilite Colors       (ShowSyntaxHilite)      Std: ON

  Toggles whether SyntaxHilite colors are displayed for any files for which
  SyntaxHilite mode is active.  Set this option ON to display SyntaxHilite
  colors for any files for which SyntaxHilite mode is active; set this option
  OFF to suppress the display of SyntaxHilite colors for all files in the
  editing session.

  (For more information on SyntaxHilite mode, see "SyntaxHilite Mode" in
  the chapter on "Editing Modes.")

▪ Configure SyntaxHilite Mapping Sets

  Allows you to configure the mapping sets to be used by SyntaxHilite mode.
  When you select this item, the following options are available:

    Selection                            Description
    ____________    _____________________________________________________

    CURRENT         Selects the SyntaxHilite mapping set for the current
                    file, and allows you configure that set.

    OTHER           Displays a PickList of SyntaxHilite mapping files,
                    from which you can select a mapping set to configure.

    CREATE NEW      Creates a new SyntaxHilite mapping file, so that you
                    can configure a new mapping set.

    CONFIGURE       Displays a modifiable list of available SyntaxHilite
    ASSOCIATIONS    mapping (.SYN) files, from which you can maintain the
                    file extension associations.


  (For more information on configuring SyntaxHilite mapping sets, see
  "Mapping SyntaxHilite Tokens to Colors & Setting Other Options" and
  "Associating a SyntaxHilite Mapping Set with a Group of Files" under
  "SyntaxHilite Mode" in the chapter on "Editing Modes.")

▪ Set Colors

  Allows you to change the configurable screen display colors.

  Three groups of colors can be customized:  editing colors, HelpSystem
  colors, and SyntaxHilite mode colors.

  A color-customization screen displays to allow you to select the desired
  colors.  Your color selections are shown on a sample portion of a screen as
  you move through the available color patterns.

  From "Set Colors," you select the color group to configure, and the
  appropriate color-customization Item Selection screen is displayed.  On the
  left side of this screen is a PickList of all the configurable items.  On
  the right side of the screen is a sample screen that illustrates your
  current color settings.



Following are the configurable items on the Item Selection screen for
"editing" colors, accessed via the "Select Editing Colors" option:

▪ Text - Normal
                   (TextAttr)               Std: Intense Black on White


  Indicates the color of normal text (that is, text that is not on the cursor
  line, and is not highlighted or in a marked block).

▪ Text - Blocked
                   (BlockAttr)              Std: Bright White on Black


  Indicates the color of the text within a marked block.

▪ Text - Cursor Line in Block
                   (CursorInBlockAttr)      Std: Black on White


  Indicates the color of the text on the cursor line when located within a
  marked block.

▪ Text - Cursor Line
                   (CursorAttr)             Std: Intense Black on Cyan


  Indicates the color of the text on the cursor line (when not located within
  a marked block).

▪ Text - Highlighted
                   (HiLiteAttr)             Std: Red on White


  Indicates the color of the text that is highlighted when located by a search
  command.

▪ Menu/Help - Item Names
                   (MenuTextAttr)           Std: Black on White


  Indicates the color of the selection item names listed on the pull-down
  Menu, including the item names under the sub-menu categories; also
  determines the color of the command/option names included on the HelpLine.

▪ Menu/Help - Quick Letter
                   (MenuTextLtrAttr)        Std: Red on White


  Indicates the color of the highlighted quick-key letters for the items
  listed on the pull-down Menu, including the quick-keys for the sub-menu
  items; also determines the color of the key assignment values included on
  the HelpLine.

▪ Menu - Grayed
                   (MenuGrayAttr)           Std: Bright Black on White


  Indicates the color of disabled "grayed" selection items on the pull-down
  Menu and on the sub-menu categories.

▪ Menu - Selected Gray
                   (MenuSelectGrayAttr)     Std: White on Blue


  Indicates the color of the Menu cursor bar when it is located on a disabled
  "grayed" item on the pull-down Menu or on a sub-menu category.

▪ Menu - Border
                   (MenuBorderAttr)         Std: Black on White


  Indicates the color of the border around the pull-down Menu categories.

▪ Menu - Selected Item
                   (MenuSelectAttr)         Std: Bright White on Blue


  Indicates the color of the Menu cursor bar that identifies the selected item
  on the pull-down Menu and on the sub-menu categories.

▪ Menu - Selected Quick Letter
                   (MenuSelectLtrAttr)      Std: Bright Red on Blue


  Indicates the color of the quick-key letter (within the Menu cursor bar) for
  the selected item on the pull-down Menu and on the sub-menu categories.

▪ Border - Current Window
                   (CurrWinBorderAttr)      Std: Intense Black on White


  Indicates the color of the border around the current window.

▪ Border - Non-Current Window
                   (OtherWinBorderAttr)     Std: Intense Blue on White


  Indicates the color of the border around the non-current window(s).

▪ End-of-File Marker
                   (EOFMarkerAttr)          Std: Black on White


  Indicates the color of the optional line that identifies the end of the
  file.

▪ Messages
                   (MsgAttr)                Std: Black on White


  Indicates the color of various messages and warnings displayed on the
  StatusLine.

▪ StatusLine
                   (StatusLineAttr)         Std: Bright White on Blue

▪ LineNumbers
                   (LineNumbersAttr)        Std: Black on White

  Indicates the color of displayed Line Numbers (see ShowLineNumbers).

Following are the configurable items on the Item Selection screen for
HelpSystem colors, accessed via the "Select Help Colors" option:

▪ Help Text - Normal
                   (HelpTextAttr)           Std: White on Blue


  Indicates the color of normal text within the HelpSystem.

▪ Help Text - Highlighted
                   (HelpBoldAttr)           Std: Bright White on Blue


  Indicates the color of highlighted text within the HelpSystem.

▪ Help Text - Italicized
                   (HelpItalicsAttr)        Std: Bright Magenta on Blue


  Indicates the color of "italicized" text within the HelpSystem.

▪ Help Field - InfoBox
                   (HelpInfoAttr)           Std: Bright Green on Blue


  Indicates the color of HelpSystem InfoBox fields.

▪ Help Field - Link
                   (HelpLinkAttr)           Std: Bright Yellow on Blue


  Indicates the color of the fields that serve as Links to other HelpSystem
  topics.

▪ Help Field - Selected
                   (HelpSelectAttr)         Std: Blue on White


  Indicates the color of the field that is selected in the HelpSystem.

Following are the configurable items on the Item Selection screen for
SyntaxHilite mode colors, accessed via the "Select SyntaxHilite Colors"
option.  (For more information on colors used by SyntaxHilite mode, see
"Selecting Colors for SyntaxHilite Classes" under "SyntaxHilite Mode" in
the chapter on "Editing Modes.")

▪ Directives - 1
                   (Directive1Attr)         Std: Intense Red on White

  Indicates the color of SyntaxHilite directive text, entry 1.

▪ Directives - 2
                   (Directive2Attr)         Std: Intense Red on White

  Indicates the color of SyntaxHilite directive text, entry 2.

▪ Directives - 3
                   (Directive3Attr)         Std: Intense Red on White

  Indicates the color of SyntaxHilite directive text, entry 3.

▪ Multi-Line - 1
                   (MultiLnDlmt1Attr)       Std: Intense Green on White

  Indicates the color of SyntaxHilite multi-line delimited text, entry 1.

▪ Multi-Line - 2
                   (MultiLnDlmt2Attr)       Std: Intense Green on White

  Indicates the color of SyntaxHilite multi-line delimited text, entry 2.

▪ Multi-Line - 3
                   (MultiLnDlmt3Attr)       Std: Intense Green on White

  Indicates the color of SyntaxHilite multi-line delimited text, entry 3.

▪ Single-Line - 1
                   (SingleLnDlmt1Attr)      Std: Intense Green on White

  Indicates the color of SyntaxHilite single-line delimited text, entry 1.

▪ Single-Line - 2
                   (SingleLnDlmt2Attr)      Std: Intense Green on White

  Indicates the color of SyntaxHilite single-line delimited text, entry 2.

▪ Single-Line - 3
                   (SingleLnDlmt3Attr)      Std: Intense Green on White

  Indicates the color of SyntaxHilite single-line delimited text, entry 3.

▪ To-EOL - 1
                   (ToEOL1Attr)             Std: Intense Green on White

  Indicates the color of SyntaxHilite to-EOL delimited text, entry 1.

▪ To-EOL - 2
                   (ToEOL2Attr)             Std: Intense Green on White

  Indicates the color of SyntaxHilite to-EOL delimited text, entry 2.

▪ To-EOL - 3
                   (ToEOL3Attr)             Std: Intense Green on White

  Indicates the color of SyntaxHilite to-EOL delimited text, entry 3.

▪ Quote - 1
                   (Quote1Attr)             Std: Intense Magenta on White

  Indicates the color of SyntaxHilite quote delimited text, entry 1.

▪ Quote - 2
                   (Quote2Attr)             Std: Intense Magenta on White

  Indicates the color of SyntaxHilite quote delimited text, entry 2.

▪ Quote - 3
                   (Quote3Attr)             Std: Intense Magenta on White

  Indicates the color of SyntaxHilite quote delimited text, entry 3.

▪ Numbers
                   (NumberAttr)             Std: Intense Magenta on White

  Indicates the color of SyntaxHilite number text.

▪ Incomplete Quote
                   (IncompleteQuoteAttr)    Std: Intense Black on Red

  Indicates the color of SyntaxHilite incomplete quote text.

▪ KeyWords - 1
                   (KeyWords1Attr)          Std: Intense Bright Blue on White

  Indicates the color of SyntaxHilite keyword text, group 1.

▪ KeyWords - 2
                   (KeyWords2Attr)          Std: Intense Yellow on White

  Indicates the color of SyntaxHilite keyword text, group 2.

▪ KeyWords - 3
                   (KeyWords3Attr)          Std: Intense Bright Magenta on White

  Indicates the color of SyntaxHilite keyword text, group 3.

▪ KeyWords - 4
                   (KeyWords4Attr)          Std: Intense Bright Red on White

  Indicates the color of SyntaxHilite keyword text, group 4.

▪ KeyWords - 5
                   (KeyWords5Attr)          Std: Intense Cyan on White

  Indicates the color of SyntaxHilite keyword text, group 5.

▪ KeyWords - 6
                   (KeyWords6Attr)          Std: Intense Cyan on White

  Indicates the color of SyntaxHilite keyword text, group 6.

▪ KeyWords - 7
                   (KeyWords7Attr)          Std: Intense Bright Blue on White

  Indicates the color of SyntaxHilite keyword text, group 7.

▪ KeyWords - 8
                   (KeyWords8Attr)          Std: Intense Bright Blue on White

  Indicates the color of SyntaxHilite keyword text, group 8.

▪ KeyWords - 9
                   (KeyWords9Attr)          Std: Intense Bright Blue on White

  Indicates the color of SyntaxHilite keyword text, group 9.

To select a screen item for which to configure the color, move the cursor bar
over the desired item and press <Enter>.  A color chart replaces the PickList
of configurable items on the left of the screen.  The name of the current
item selection is indicated above the sample screen.

As you move through the selections in the color chart, the color of the
affected item is changed on the sample screen to match.  The PC attribute
number that represents the foreground/background color combination is
displayed in the upper left corner of the color chart.

Select the desired settings from the color chart, as follows:

    • Use the cursor keys (up, down, left, right) to select the desired
      foreground/background color combination.

    • Press <Ins> to toggle bright colors ON or OFF for the selected item.

    • Press <Del> to restore the item to its initial setting.

    • Press <Escape> to cancel any changes made to the item and return to the
      Item Selection screen.

    • Press <Enter> to accept the color change and return to the Item
      Selection screen.

    • Mouse users:  You can use the mouse to select a color combination by
      positioning the mouse pointer on the desired color combination, and
      clicking the <LeftBtn>.  You can perform the functions assigned to
      <Ins>, <Del>, <Escape>, and <Enter> by positioning the mouse pointer on
      the desired key assignment or function, and clicking the <LeftBtn>.
      (These key assignments are displayed on a "helpline" below the color
      chart.)

To cancel the color changes that you have made, select "Cancel Color Changes"
from the Item Selection screen.


(For more information on related topics, see the chapters on
"The Screen Layout," "The Pull-Down Menu System,"
"Getting Help in the Editor," "Splitting the Screen into Windows,"
"Editing Modes," and "Special Commands and Features.")


Print Output Options
────────────────────

Following is a list of the Print Output Options, including the editor's
internal option name and the value of the standard setting for each option.
For a description of each option, see the chapter on
"Printing From the Editor."

▪ Left Margin                       (PrintLeftMargin)       Std: 0

▪ Right Margin                      (PrintRightMargin)      Std: 0

▪ Lines Per Page                    (PrintLinesPerPage)     Std: 0

▪ Top Margin                        (PrintTopMargin)        Std: 0

▪ Bottom Margin                     (PrintBotMargin)        Std: 0

▪ Line Spacing                      (PrintLineSpacing)      Std: 1

▪ Use Current Screen Font           (PrintUseScreenFont)    Std: On

▪ Set Printer Font                  (SetPrinterFont())      Std: empty

▪ Print Line Numbers                (PrintLineNumbers)      Std: OFF

▪ Header                            (PrintHeader)           Std: empty

▪ Footer                            (PrintFooter)           Std: empty

▪ First Page                        (PrintFirstPage)        Std: 0

▪ Last Page                         (PrintLastPage)         Std: 0

▪ Number of Copies                  (PrintCopies)           Std: 1

▪ Pause Between Pages               (PrintPause)            Std: OFF





Configuring the Editor Interactively

Customizing editing options to suit your particular editing style is
accomplished from within the editor using IConfig, the Interactive
Configuration facility.  A limited set of options can also be configured
directly from the pull-down Menu.  Configuration changes can be applied to
the current session only, or they can be installed in the editor so they
remain in effect for future sessions.

This chapter provides the following information on configuring editing options
from within the editor:

    • Methods for interactively configuring the editorConfiguration options available interactivelySaving configuration settingsWriting configuration settings to a Settings FileFiles needed by IConfig


This chapter does not attempt to fully explain the effects of or uses for the
various configuration options (variables) available within the editor.  To
make effective use of this chapter, you may wish to review the other chapters
in this manual to familiarize yourself with the operation of the editor.  (For
more information on specific editor variables, see the chapter on
"Editor Variables" in the Macro Reference Guide.)

This chapter also does not discuss how to customize the editor using the
editor's macro programming language, the SemWare Applications Language (SAL).
(For more information on how to do this, see the chapter on
"Fully Customizing the Editor.")





Constants

To give constant numbers more descriptive names, constant declarations may be
used.  Constants may be used anywhere constant numbers are required.

Constant identifiers must be initialized when they are declared.

The syntax for declaring a constant is:

    constant identifier = constant_expression [, identifier =
             constant_expression] ...

where:

    • constant declares the following identifier as constant.

    • identifier is any valid user-definable identifier.  (For more
      information, see "Identifiers" earlier in this chapter.)

    • constant_expression is any constant expression.  (For more
      information, see "Constant Expressions" later in this chapter.)

To declare multiple constants, separate the identifiers with commas as shown
above.


Examples:

    constant  YES = 1, NO = 0

    constant  TEN_IN_HEX = 0ah

    constant  TEN_IN_BINARY = 1010b


Constants may also be used to create other constants:

    constant
        ONE  = 1,
        TWO  = 2,
        FOUR = 4,
        NINE = (TWO * FOUR) + ONE





Copy()

Copies the marked block to the ClipBoard.  The current contents of the
ClipBoard are discarded before the operation starts, unless the _APPEND_
constant is passed to the command.

Syntax:     INTEGER Copy([INTEGER flag])

            • flag is an optional integer specifying whether Copy() should
              keep or discard the current ClipBoard contents.  If not
              specified, _DEFAULT_ is used.  Supported values for flag are:

              • _DEFAULT_ causes Copy() to replace the contents of the
                ClipBoard with the block.

              • _APPEND_ causes Copy() to append the block to the ClipBoard.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            Copy() will not copy a block that exists outside the current file.

            The block is unmarked after the copy is performed.

            If there is no marked block, but the UseCurrLineIfNoBlock variable
            is set ON, the current line is copied to the ClipBoard.

            To retrieve text from the ClipBoard, use the Paste() or
            PasteReplace() command, as appropriate.

Examples:

            // Causes <Grey+> to Copy a block to the ClipBoard,
            // deleting the current contents
            <Grey+>         Copy()

            // Causes <Ctrl Grey+> to Copy a block to the ClipBoard,
            // appending it to the current contents
            <Ctrl Grey+>    Copy(_APPEND_)

See Also:   CopyAppend(), Cut(), CutAppend(), Paste(), PasteReplace()

            CopyToWinClip(), CopyAppendToWinClip(), CutToWinClip(),
            CutAppendToWinClip(), PasteFromWinClip(),
            PasteReplaceFromWinClip()

            CopyBlock(), DelBlock(), MoveBlock()

            isBlockMarked(), isBlockInCurrFile()

            Variables:  BlockId, ClipBoardId, UseCurrLineIfNoBlock





CopyAppend()

Copies the marked block to the ClipBoard, appending it to the current
contents.

Syntax:     INTEGER CopyAppend()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            CopyAppend() will not copy a block that exists outside the
            current file.

            The block is unmarked after the copy is performed.

            If there is no marked block, but the UseCurrLineIfNoBlock variable
            is set ON, the current line is copied to the ClipBoard.

            To retrieve text from the ClipBoard, use the Paste() command.

Examples:

            // Causes <Ctrl Grey+> to Copy a block to the ClipBoard,
            // appending it to the current contents
            <Ctrl Grey+>    CopyAppend()

See Also:   Copy(), Cut(), CutAppend(), Paste(), PasteReplace()

            CopyAppendToWinClip(), CopyToWinClip(), CutToWinClip(),
            CutAppendToWinClip(), PasteFromWinClip(),
            PasteReplaceFromWinClip()

            CopyBlock(), DelBlock(), MoveBlock()

            isBlockMarked(), isBlockInCurrFile()

            Variables:  BlockId, ClipBoardId, UseCurrLineIfNoBlock





CopyAppendToWinClip()

Copies the marked block to the Windows Clipboard, appending it to the current
contents.

Syntax:     INTEGER CopyAppendToWinClip([STRING text])

            • Optional text that is appended to the Windows Clipboard in
              lieu of the marked block.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            CopyAppendToWinClip() will not copy a block that exists outside
            the current file.

            The block is unmarked after the copy is performed.

            If there is no marked block, but the UseCurrLineIfNoBlock variable
            is set ON, the current line is copied to the Clipboard.

            To retrieve text from the Windows Clipboard, use the
            PasteFromWinClip() command.

            If the optional string is passed, any marked block is ignored
            and only the passed string is appended to the Clipboard.


See Also:   CutToWinClip(), PasteFromWinClip(), Cut(), Paste(),
            isBlockMarked(), isBlockInCurrFile(), CutAppendToWinClip()

            Variables:  BlockId, UseCurrLineIfNoBlock





CopyBlock()

The marked block is copied to the current cursor position.

Syntax:     INTEGER CopyBlock([INTEGER overwrite])

            • overwrite is an optional integer that specifies whether
              CopyBlock() should overwrite or insert column blocks.  If not
              specified, _DEFAULT_ is used.  overwrite has no effect if the
              block being copied is not a column block.  Supported values for
              overwrite are:

              • _DEFAULT_ causes column blocks to be inserted.

              • _OVERWRITE_ causes column blocks to overwrite text at the
                current cursor position.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If no block is marked, no action occurs and zero is returned.
            This command fails if there is not enough memory to successfully
            complete the operation.

            Character blocks are always inserted at the current cursor
            position.

            Column blocks are inserted or overlaid based on the value of the
            overwrite parameter.

            Where line blocks are placed depends on the value of the
            InsertLineBlocksAbove variable.  If set ON, line blocks are
            inserted above the current cursor line.  If set OFF, line blocks
            are added below the current cursor line.

            This command can copy blocks between files.

            This command also works within dialog boxes, if it is assigned to
            a key (and no parameter is specified).

See Also:   DelBlock(), MoveBlock()

            Copy(), CopyAppend(), Cut(), CutAppend(), Paste(), PasteReplace()

            CopyToWinClip(), CopyAppendToWinClip(), CutToWinClip(),
            CutAppendToWinClip(), PasteFromWinClip(),
            PasteReplaceFromWinClip()

            isBlockMarked(), isBlockInCurrFile()

            Variables:  InsertLineBlocksAbove, BlockId





CopyFile()

Copies a disk file from one location to another.

Syntax:     INTEGER CopyFile(STRING src, STRING dst [, INTEGER overwrite])

            • src is the name of the file to copy.

            • dst is the name of the copied file.

            • overwrite defaults to FALSE.  In this case, CopyFile() fails if
              dst exists.  If overwrite is set to TRUE, dst will be
              overwritten if it exists.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Wildcards cannot be specified with this command.  Only single
            files may be copied.

            If path information is not specified, the current directory is
            assumed.

            The original file is left unchanged.

Examples:

            CopyFile("foo", "bar")

            CopyFile("c:\dir\foo", "d:\path\bar")

            // assume the existence of two strings, s1 and s2

            CopyFile(s1, s2)    // fails if s2 exists

            CopyFile(s1, s2, TRUE)  // s2 will be overwritten

See Also:   MoveFile(), EraseDiskFile(), RenameDiskFile()





CopyToWinClip()

Copies the marked block to the Windows Clipboard.  The current contents of
the Windows Clipboard are discarded before the operation starts.

Syntax:     INTEGER CopyToWinClip([STRING text])

            • Optional text that is copied to the Windows Clipboard in lieu
              of the marked block.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.


            CopyToWinClip() will not copy a block that exists outside the
            current file.

            The block is unmarked after the copy is performed.

            If there is no marked block, but the UseCurrLineIfNoBlock
            variable is set ON, the current line is copied to the Clipboard.

            To retrieve text from the Windows Clipboard, use the
            PasteFromWinClip() or PasteReplaceFromWinClip() command, as
            appropriate.

            If the optional string is passed, any marked block is ignored
            and only the passed string is copied to the Clipboard.

See Also:   CopyAppendToWinClip(), CutToWinClip(), CutAppendToWinClip(),
            PasteFromWinClip(), PasteReplaceFromWinClip()

            Copy(), CopyAppend(), Cut(), CutAppend(), Paste(), PasteReplace()

            CopyBlock(), DelBlock(), MoveBlock()

            isWinClipAvailable(), EmptyWinClip(), isBlockMarked(),
            isBlockInCurrFile()

            GetStrFromWinClip()

            Variables:  BlockId, UseCurrLineIfNoBlock





CreateBuffer()

Creates a new buffer in memory.

Syntax:     INTEGER CreateBuffer(STRING fn [, INTEGER type])

            • fn is the name of the buffer to be created.  fn must be a
              valid filename only if it is desired to save the file to disk.

            • type is an optional integer parameter which tells what type of
              buffer is to be created.  If not specified, _NORMAL_ is used.
              Supported values for type are:

              • _NORMAL_ causes the buffer to have no special attributes
                associated with it.  Buffers created with EditFile() have this
                buffer type.

              • _HIDDEN_ simply causes the buffer to not show up in the list
                of files, and makes the buffer inaccessible via the NextFile()
                and PrevFile() commands.  The PickList of loaded macros
                (optionally displayed by the ExecMacro() command) is stored in
                a _HIDDEN_ buffer.

              • _SYSTEM_ causes the buffer to be hidden, and places the
                buffer in a raw mode, so that trailing spaces are never
                removed, and tabs are treated as a normal character.  Buffers
                created with CreateTempBuffer() have this buffer type.  It is
                strongly recommended that system buffers not be used for
                interactive editing.

                Undo/Redo information is NOT recorded for _SYSTEM_ buffers.

Returns:    The non-zero id number of the newly-created buffer if successful;
            otherwise, zero (FALSE).

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            A buffer is created only if a buffer of the same name does not
            already exist in the editor's internal list of files/buffers.  If
            created, the new buffer becomes the current buffer.

            If buffer fn already exists, no action occurs and zero is
            returned.

            CreateBuffer() is primarily intended for creating workspace areas
            for macros.  It is not intended for interactive editing of
            buffers.

            Unlike EditFile(), CreateBuffer() does NOT check to see if fn
            exists on disk.  Since CreateBuffer() is intended for creating
            macro workspace areas, checking file existence would defeat its
            purpose, and cause it to execute much more slowly.

            Likewise, buffers created via this command are not intended for
            saving to disk.  Since the disk is not checked before the buffer
            is created, a file on disk could be accidentally overwritten if a
            buffer is saved.  The FileExists() command can be used to prevent
            this.

            This command does not invoke the _ON_CHANGING_FILES_ and
            _ON_FIRST_EDIT_ events.  (For more information on events, see the
            Hook() command description.)

            _NORMAL_ buffers show up in the editor's list of files, and can be
            accessed via the following commands:  EditFile(), NextFile(),
            PrevFile(), GotoBufferId().

            _SYSTEM_ and _HIDDEN_ buffers are hidden buffers and can only be
            accessed via the GotoBufferId() command.  _SYSTEM_ buffers are not
            intended for interactive editing by the user, as many editor
            functions are not in effect (such as RemoveTrailingWhite and
            ExpandTabs, among others).  _HIDDEN_ files are treated as _NORMAL_
            buffers with the exception that they can only be accessed via
            GotoBufferId().

Examples:

            rc = CreateBuffer("foo")    // Creates a buffer named foo


            /********************************************************
              Creates a file named "foo2".  "foo2" can only be viewed
              by switching to it directly.
             ********************************************************/
            rc = CreateBuffer("foo2", _HIDDEN_)


            /********************************************************
             Create a new buffer, and then switch back to the original
             buffer.
             ********************************************************/
            integer currid, newid

            currid = GetBufferId()      // retrieve the current file's
                                        // id
            newid = CreateBuffer("foo") // create the new buffer
            if newid = FALSE            // error, could not create
                    ...
            else
                    ...                 // do whatever with new buffer
                GotoBufferId(currid)    // switch back to original
                                        // buffer
            endif

See Also:   CreateTempBuffer(), GotoBufferId(), GetBufferId(), EditFile(),
            EditThisFile(), NextFile(), PrevFile(), Hook(), UnHook(),
            FileExists(), BufferType(), AddFileToRing()





CreateTempBuffer()

Creates a temporary buffer of type _SYSTEM_.

Syntax:     INTEGER CreateTempBuffer()

Returns:    The non-zero id number of the newly-created system buffer;
            otherwise, zero (FALSE).

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            The buffer is always created unless the editor runs out of memory.
            The newly-created buffer becomes the current buffer.

            The buffer created by CreateTempBuffer is a _SYSTEM_ buffer and
            can only be accessed via the GotoBufferId() command.  It will not
            show up in the file lists shown by PickFile(), and cannot be
            accessed via the NextFile() and PrevFile() commands.

            Since buffers created by this command are _SYSTEM_ buffers, they
            are NOT intended for interactive editing.

            Undo/Redo information is NOT recorded for _SYSTEM_ buffers.

            Buffers created by CreateTempBuffer() last until they are
            explicitly removed by the user.

            For more information on _SYSTEM_ buffers, see the description of
            CreateBuffer().

See Also:   CreateBuffer(), GotoBufferId(), GetBufferId(), BufferType()





Creating and Using Macros

You can create macros to simplify and automate editing tasks and to further
customize and extend the features and capabilities of the editor.  Two types
of macros are available:  Keyboard Macros and Compiled Macros.  Keyboard
Macros are designed to make it easy to repeatedly execute a series of commands
and keystrokes entered from the keyboard.  Compiled Macros give you access to
the editor's macro programming language, allowing you to write simple or
complex macros to customize or create your own commands.

This chapter describes the following macro features:

    • Keyboard Macros:

      • Recording Keyboard Macros

            (RecordKeyMacro)

      • Re-playing Keyboard Macros

            (macros assigned to keys, ExecScrapMacro)

      • Saving Keyboard Macros for use in a later session

            (SaveKeyMacro)

      • Loading Keyboard Macros saved in a previous session

            (LoadKeyMacro)

      • Purging Keyboard Macros from the current session

            (PurgeKeyMacro)

    • Introduction to external Compiled Macros:

      • Creating and using Compiled MacrosCompiling macro source

            (Compile)

      • Loading and executing Compiled Macros

            (LoadMacro, ExecMacro, AutoLoadList)

      • Purging Compiled Macros

            (PurgeMacro)

      • Debugging Compiled Macros

            (Debug)


There are two types of Compiled Macros in the editor:  external and
user-interface.  This chapter deals with external Compiled Macros (in the
section, "Introduction to External Compiled Macros").  The chapter on
"Fully Customizing the Editor" explains how to create both external and
user-interface macros, and provides additional information about both types of
Compiled Macros.





Creating Macros

The first step in creating macros, is to create a macro source file using the
editor.  Macro source files are standard ASCII text files that contain a
sequence of SAL macro statements that perform a specific task. In order for
the SAL compiler to recognize the source file, the extension must be ".S" for
an external macro file, or ".UI" if the macro is a user-interface macro file.
The editor has some knowledge of SAL, and recognizes SmartIndent when you
press <Enter> on a line containing certain SAL statements.  The Compile() and
FunctionList() commands also know about SAL, allowing them to act
appropriately.

Once you have created a SAL source file, you are ready to compile the source
file into an object file that can be directly interpreted by the editor.





Creating Macros (Overview)

The first step in creating a macro is to type a series of macro commands and
statements (called "source code") that are recognized by the SemWare
Applications Language (SAL).  For example, to write a very simple macro, edit
a new file called "HELLO.S", and place the following text in it:

    proc Main()
        Message("Hello, World!")
    end





CReturn()

Performs a carriage return at the current cursor location.

Syntax:     INTEGER CReturn()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            The action of the CReturn() command will depend on several editor
            variables and editing modes.

            The following assumes that Insert is currently ON:

            • If ReturnEqNextLine is OFF, the current line will be split at
              the current cursor location, and the cursor will be placed at
              the beginning of the next line.  The cursor position on the new
              line may be different, depending on the following conditions:

              • If AutoIndent is OFF, the cursor will be placed at the
                position specified by the LeftMargin variable.

              • If AutoIndent is ON, the cursor position on the new line will
                be equal to the position of the first non-white character of
                the previous line.

              • If AutoIndent is set to STICKY, the cursor position on the new
                line will be equal to the position of the first non-white
                character of the previous non-blank line.

            • If ReturnEqNextLine is ON, the cursor will be moved to the
              following line (without splitting the current line).  The cursor
              position on the new line is determined by the following
              conditions:

              • If AutoIndent is OFF, the cursor will be placed at the
                position specified by LeftMargin.

              • If AutoIndent is ON or STICKY, and the line is non-blank, the
                cursor will be placed at the first non-white character on the
                line.  If the line is blank, the cursor will be placed under
                the first non-white character of the previous line if
                AutoIndent is ON, or under the first non-white character of
                the most recent non-blank line if AutoIndent is STICKY.

            • If the cursor is on the last line, a new line will be created
              below the current line, and the cursor will be placed on the new
              line according to the previous conditions dealing with blank
              lines.

            If Insert is OFF, ReturnEqNextLine has no effect.  The action of
            the CReturn() command is the same as described above for Insert
            set ON and ReturnEqNextLine set ON.

            In prompts, menus, and list boxes, CReturn() is assigned to the
            <Enter> key (sometimes called the <Return> key) regardless of
            the current key assignment.

See Also:   SplitLine(), JoinLine(), AddLine(), InsertLine()

            Variables:  AutoIndent, ReturnEqNextLine, Insert





CurrChar()

Returns the integer value of the character at the current (or specified)
position.

Syntax:     INTEGER CurrChar([INTEGER pos])

            • pos is the optional position within the current line from
              which to retrieve the character.  If not passed, the current
              position (CurrPos()) is used.

Returns:    The ASCII integer value of the current character if within the
            text on the line, or:

            • _AT_EOL_ if at the end-of-line position (that is, at the
              position immediately after the last character on the
              line).

            • _BEYOND_EOL_ if past the end-of-line position.

Notes:      To pass the results from CurrChar() to commands requiring a
            character string, use the Chr() command.

            This command can be used in a macro to easily determine whether
            the cursor position is within the text of the current line or is
            at or beyond the end-of-line position.  If the value returned is
            equal to or greater than zero, then the current cursor position is
            within the text of the current line.  If the value returned is
            less than zero, then the current cursor position is at or beyond
            the end-of-line position, and the value can be referenced as
            _AT_EOL_ or _BEYOND_EOL_, respectively.

Idioms:

            /********************************************************
              TRUE if the current cursor position is at the
              end-of-line position.
             ********************************************************/
            if CurrChar() == _AT_EOL_

            /********************************************************
              TRUE if the current cursor position is beyond the
              end-of-line position.
             ********************************************************/
            if CurrChar() == _BEYOND_EOL_

            /********************************************************
              TRUE if the current cursor position is at or beyond the
              end-of-line position.
             ********************************************************/
            if CurrChar() < 0

            /********************************************************
              TRUE if the current cursor position is within the text
              of the current line.
             ********************************************************/
            if CurrChar() >= 0

            /********************************************************
              The Asc() command is used with CurrChar() to test for a
              literal ASCII character.  To test for an "s" at the
              current position,  use the following:
             ********************************************************/
            if CurrChar() == Asc("s")

Examples:

            /********************************************************
             Example 1

             Return TRUE if the current character is alphabetic;
             otherwise, FALSE.
             ********************************************************/
            integer proc isAlpha()
                case Chr(CurrChar())
                   when "A".."Z", "a".."z"
                      return (TRUE)
                endcase
                return (FALSE)
            end

            /********************************************************
              Example 2

              Return the first word on the current line.  Use the
              current WordSet definition to determine what comprises a
              word.
             ********************************************************/
            string proc GetFirstWord()
                string word[12] = ""

                PushPosition()           // Save current position

                GotoPos(PosFirstNonWhite()) // Start at first
                                            // character on line
                while not isWord()       // Scan for start of word
                    if CurrChar() < 0    // Bail out if past
                        return ("")      // end-of-line
                    endif
                endwhile

                // Accumulate the word

                while isWord() and Length(word) < SizeOf(word)
                    word = word + Chr(CurrChar())
                    if not Right()       // break on max line length
                        break
                    endif
                endwhile

                PopPosition()            // Restore original position
                return (word)            // and return the word
            end

See Also:   GetText(), InsertText(), GetWord(), GetFoundText()





CurrCol()

Returns the number of the current column position on the current line.

Syntax:     INTEGER CurrCol()

Returns:    The number of the current column position on the current line.

Notes:      CurrCol() does not equal CurrPos() if:  Hard (real) tab characters
            exist in the current line before the current position; AND
            ExpandTabs is ON; AND TabWidth is greater than one.  (CurrCol()
            counts expanded hard tab characters as equal to the number of
            spaces to which the hard tab is expanded.  CurrPos() always counts
            a hard tab as one character.)

Idioms:

            /********************************************************
              TRUE if the current cursor position is at the first
              character of the current line.
             ********************************************************/
            if CurrCol() == 1

See Also:   CurrPos(), CurrXOffset(), CurrLine()

            Variables:  ExpandTabs, TabType, TabWidth





CurrDir()

Returns the current drive and directory.

Syntax:     STRING CurrDir()

Returns:    The current drive and directory.

Notes:      The trailing slash is always included in the returned string.


Examples:

            Given:
                The current drive is c: and the current directory is
                \foo\bar.

                string s[80]

            Then:

                s = Currdir()   // s is "c:\foo\bar\"

See Also:   GetDir(), ChDir()





CurrExt()

Returns the extension portion of the filename for the current file.

Syntax:     STRING CurrExt()

Returns:    The extension of the current file.

Notes:      If the current file does not have an extension, an empty string
            is returned; otherwise, the extension, including the period, is
            returned.

            The returned extension is always lower-cased.

            To return the actual case of the extension, use the following
            code:

            SplitPath(CurrFilename(), _EXT_)

Examples:

            // assign the extension of the current file to s
            string s[_MAXPATH_]

            s = CurrExt()

See Also:   CurrFilename(), ChangeCurrFilename(), SplitPath()





CurrFilename()

Returns the full name of the current buffer, including drive and path for disk
files.

Syntax:     STRING CurrFilename()

Returns:    The name of the current buffer.

Notes:      SplitPath() can be used to separate out the different parts of the
            name.

            The case of the filename is returned as is.

Examples:

            // A simple proc to return the extension of the current
            // file as a string
            string proc CurrExt()
                return (SplitPath(CurrFilename(),  _EXT_ ))
            end

See Also:   ChangeCurrFilename(), CurrExt(), SplitPath()





CurrHistoryList

The id number of the most recently used history list.

Values:     INTEGER - [1..255]

Default:    Undefined

Limits:     Cannot be used within a config/endconfig construct.

Notes:      Can be used in the _PROMPT_STARTUP_ event to determine the last
            or current prompt/history used.  (See the Hook() command for more
            information on this event.)

See Also:   Commands:  AddHistoryStr()





CurrLine()

Returns the line number of the current line.

Syntax:     INTEGER CurrLine()

Returns:    The number of the current line.

Idioms:

            /********************************************************
              TRUE if the current cursor position is at the first line
              of the file.
             ********************************************************/
            if CurrLine() == 1

            /********************************************************
              TRUE if the current cursor position is at the last line
              of the file.  NumLines() can be 0 in an empty file, and
              can also be less than CurrLine() if the last line has
              just been deleted, and the cursor has not moved off
              that line.
             ********************************************************/
            if CurrLine() >= NumLines()

See Also:   NumLines(), CurrCol(), CurrPos(), CurrRow()





CurrLineLen()

Returns the length of the current line.

Syntax:     INTEGER CurrLineLen()

Returns:    The length of the current line.

Notes:      If tab characters are contained within the current line, they will
            be counted as single characters.

Idioms:

            /********************************************************
              TRUE if the cursor is on an empty line
             ********************************************************/
            if CurrLineLen() == 0

            /********************************************************
              TRUE if the current cursor position is within the text
              of the current line.
             ********************************************************/
            if CurrPos() <= CurrLineLen()

            /********************************************************
              TRUE if the current cursor position is beyond the text
              of the current line.
             ********************************************************/
            if CurrPos() > CurrLineLen()

See Also:   Variables:  ExpandTabs, TabType, TabWidth





CurrMacroFilename()

Returns the full path of the Compiled Macro file containing the currently
executing macro.

Syntax:     STRING CurrMacroFilename()

Returns:    The full path of the Compiled Macro file containing the currently
            executing macro.

Notes:      Use SplitPath() in order to isolate the macro filename from the
            complete path.

Examples:

            string fn[8]

            fn = SplitPath(CurrMacroFilename(), _NAME_)

See Also:   ExecMacro(), LoadMacro(), PurgeMacro(), SplitPath()





CurrPos()

Returns the current position on the current line.

Syntax:     INTEGER CurrPos()

Returns:    The position on the current line.

Notes:      Expanded tab characters do not affect the value returned, as they
            do with CurrCol().  CurrPos() will not equal CurrCol() if Hard
            (real) tabs exist in the current line before the current position,
            and ExpandTabs is ON, and TabWidth is greater than 1.

Idioms:

            /********************************************************
              CurrPos() is commonly used with GetText() to copy text
              from the current cursor position for some length "len",
              into a macro language string.
             ********************************************************/
            s = GetText(CurrPos(), len)

See Also:   CurrCol(), CurrXOffset(), CurrLineLen()

            Variables:  ExpandTabs, TabType, TabWidth





CurrRow()

Returns the current cursor row relative to the top line of the current window,
in the range 1 through Query(WindowRows).

Syntax:     INTEGER CurrRow()

Returns:    The current cursor row.

See Also:   CurrLine(), CurrXOffset(), CurrPos()

            Variables:  WindowRows





CurrVideoMode

The current editor video mode.

Values:     INTEGER_25_LINES__28_LINES__30_LINES__33_LINES__36_LINES__40_LINES__43_LINES__44_LINES__50_LINES__MAX_LINES__MAX_COLS__MAX_LINES_COLS_

Default:    Undefined

Limits:     Cannot be used within a config/endconfig construct.

Notes:      When Set(CurrVideoMode, nn) is issued, the video system will be
            re-initialized.  This means that if you have split the screen into
            horizontal or vertical windows, or are in a zoomed window, the
            windows will be closed and you will be placed in a full window in
            the current file.

            In a macro, Set(CurrVideoMode, nn) should not be used if menus or
            pop-up windows are open.  If this happens, unpredictable results
            may occur.  If Set(CurrVideoMode, nn) is assigned to a menu item,
            then _MF_CLOSE_ALL_BEFORE_ should be specified for that menu item.

            Values for CurrVideoMode > 255 are considered as cols x rows.

            For example:

            // to get the rows and cols, if the value is >= 256:
            cols = HiByte(CurrVideoMode value)
            rows = LoByte(CurrVideoMode value)

            // to set 100 columns by 36 rows:

            CurrVideoMode value = cols * 256 + rows

            The value for CurrVideoMode, for 100 x 36 (cols 100, rows 36),
            would be expressed as:

            CurrVideoMode value = (100 * 256) + 36 = 25636

            CurrVideoMode can be set and queried.

            • _25_LINES_  forces 25-line mode

            • _28_LINES_  forces 28-line mode

            • _30_LINES_  forces 30-line mode

            • _33_LINES_  forces 33-line mode

            • _36_LINES_  forces 36-line mode

            • _40_LINES_  forces 40-line mode

            • _43_LINES_  forces 43-line mode

            • _44_LINES_  forces 44-line mode

            • _50_LINES_  forces 50-line mode

            • _MAX_LINES_ forces maximum number of lines for current font

            • _MAX_COLS_  forces maximum number of columns for current font

            • _MAX_LINES_COLS_ forces maximum number of lines and columns
              for current font

See Also:   StartupVideoMode





CurrWinBorderType

Determines the type of "line" used for outlining the current editing window.

Values:     INTEGER

            • 1 - single-line characters

            • 2 - single-line side, double-line top characters

            • 3 - double-line side, single-line top characters

            • 4 - double-line characters

            • 5 - small block characters

            • 6 - large block characters

            • 7 - ASCII characters (+, -, |)

            • 8 - 3D characters are used

Default:    2

Notes:      CurrWinBorderType allows you to set the current editing window
            border style.  Setting it to a value that is different from the
            value assigned to OtherWinBorderType makes it easier to tell which
            window is the current editing window.

See Also:   CurrWinBorderAttr, OtherWinBorderType, OtherWinBorderAttr





CurrXoffset()

Returns the number of columns that the current window is scrolled
horizontally.

Syntax:     INTEGER CurrXoffset()

Returns:    The number of columns the current window is scrolled horizontally,
            or zero if the current window is not scrolled.

Notes:      The following relationship holds for CurrXoffset(), CurrCol(), and
            the logical x position (in 1 through Query(WindowCols)):

            x = CurrCol() - CurrXoffset()

Examples:

            The following macros provide commands that position the cursor at
            the left and right edges of the current window, without causing
            additional horizontal scrolling, even if the window is already
            horizontally scrolled.  The commands are activated by pressing the
            <Home> and <End> keys.

            integer proc mCurrX()
                return (CurrCol() - CurrXoffset())
            end

            proc mLeftEdge()
                GotoColumn(CurrCol() - mCurrX() + 1)
            end

            proc mRightEdge()
                GotoColumn(CurrCol() + Query(WindowCols) - mCurrX())
            end

            <Home>    mLeftEdge()
            <End>     mRightEdge()

See Also:   GotoXoffset(), CurrCol(), GotoColumn()

            Variables:  WindowCols





Cursor

Determines if the hardware cursor is displayed.

Values:     BOOLEAN

Default:    ON

Limits:     Cannot be used within a config/endconfig construct.

Notes:      Cursor is used to turn the hardware cursor ON and OFF.

See Also:   InsertCursorSize, OverwriteCursorSize





CursorTabWidth

If non-zero, is used by tabbing commands in lieu of TabWidth.

Values:     INTEGER

Default:    0

Limits:     1..16

Notes:      If CursorTabWidth is non-zero, it is used by tabbing commands in
            lieu of TabWidth. On-screen display of spaces for tabs is still
            controlled by TabWidth.

            If CursorTabWidth is 0, TabWidth is used by the tabbing
            commands, and CursorTabWidth has no effect.

            Why a CursorTabWidth when there is already a TabWidth variable?

            So that you can distinguish between the width to which so-called
            hard tabs are expanded on display, and the measure used when
            the TabRight() and TabLeft() commands are run.

            For instance, you might have a TabWidth of 8, preferring hard
            tabs to be displayed this way, but have a CursorTabWidth of 4,
            as you want the TabRight() command to compute tab stops based on
            4.

Affects:    TabWidth

            Commands:  TabRight(), TabLeft()

See Also:   TabWidth, TabType

            Commands: TabRight(), TabLeft()





Customization Using Sal Compiled Macros

The ability to write and compile macros can be a useful feature of the
editor.  Using SAL (the SemWare Applications Language), you can develop
macros to extend or modify the features in the editor.  Macros are created by
writing source code using SAL instructions.  The source code is compiled
using the SAL compiler.  Compiled Macros can be external to the editor, or
can be installed in the editor as part of the user interface.

External Compiled Macros are maintained in separate, independent ".MAC" files
outside the editor.  They must be explicitly loaded into the editor before
they can be executed, and they can be subsequently purged (if desired) from an
editing session when they are no longer needed.  For access to external
macros, the editor offers a variety of commands and features (including
special classes of macros).  The LoadMacro and ExecMacro commands allow you
to load external Compiled Macro files, as needed.  Macros can be classified
as WhenLoaded, Main, Public, or WhenPurged, which allows you to determine
when and how the external macros are executed.  You can assign external
macros to keys, allowing you to execute them by pressing the designated key;
or you can assign them to menus, allowing you to execute them by choosing the
appropriate menu selection.  The Potpourri facility allows you to include
external macros on the Potpourri PickList.  The macro autoload file allows
you to automatically load Compiled Macro files each time you start the
editor.  The TSEStart macro allows you to include Compiled Macros in your own
startup routine for the editor.

User-interface Compiled Macros are maintained in unique macro files that are
installed in the editor, so they are implicitly invoked when the editor is
started.  Such macros effectively become part of the editor, and thus, cannot
be purged.  A user-interface file is also used to assign commands or macros to
keys; define the HelpLines, Help screen, and pull-down Menu; and optionally
set editing options.

(For more information on writing macros, see the chapters on
"Overview of the Macro Programming Language," "Macro Language Syntax,"
"Using Macros," and "Using Macro Language Features" in the
Macro Reference Guide.)


Creating an External Compiled Macro
───────────────────────────────────

External Compiled Macros are created in separate macro source files with a
filename extension of ".S".  They are compiled as external macro files with a
filename extension of ".MAC", and should be maintained in directories that are
accessible by the editor.

External Compiled Macros that are supplied with the editor are placed in the
MAC\ editor subdirectory.  It is recommended that you maintain your own
external macro files in a separate subdirectory.  You may wish to create a
\TSE\USERMAC\ subdirectory in which to keep your .S and .MAC macro files.  You
should then include this subdirectory in the TSEPath variable so that the
editor can find your Compiled Macros whenever you execute them.  By keeping
your custom macro files in a separate directory from the MAC\ editor
subdirectory, it will be much easier for you to manage your macros and to
later upgrade to newer versions of the editor.

(For more information on where the editor searches for external Compiled Macro
files, see the "macro file search order" described under
"Creating and Using Compiled Macros" in the chapter on
"Creating and Using Macros."  For more information on the TSEPath variable,
see "Path(s) for Supplemental Files" under "System/File Options" in the
chapter on "Configuring the Editor Interactively.")

To be executed, the external Compiled Macro (.MAC) file must first be loaded
into the editor (via either the LoadMacro or ExecMacro command).  Loading
external macros into the editor is a simple process; in fact, many of the
features included in the standard version of the editor are actually
implemented as external macros.  These features include SpellCheck, Template
mode, the Potpourri facility, and the multi-language Compile command.

For a simple example of how to create an external macro, suppose you need a
command similar to the editor's Cut command.  In the editor's version of the
command, surrounding text shifts to "close up the hole" that results from the
deletion of the text.  But assume you want the surrounding text to remain in
place, and to fill the area, from which the text was deleted, with spaces.  To
accomplish this, you could create a simple macro, as follows:

    • Edit a new "macro source" file called (for example) CUTFILL.S, in your
      \TSE\USERMAC\ subdirectory.  (The name you choose for this file should
      have the extension ".S".)

    • Type the following text into the file:

         // Cut a block to the ClipBoard, back-filling with spaces
         proc Main()
             if isBlockinCurrFile()
                 PushBlock()
                 Copy()
                 PopBlock()
                 FillBlock(' ')
             endif
         end

         <Alt Grey-> Main()

    • Press <Ctrl F9> to compile the macro source file.  When the Compile
      operation is complete, a Compiled Macro file, named CUTFILL.MAC, is
      placed in the same directory as CUTFILL.S.

In this example, the macro is assigned to <Alt Grey->.  To execute this macro,
you can use the ExecMacro command to invoke the macro file by name, or you can
simply press the key assignment for the macro (once the macro file is loaded).
Alternatively, you could add the macro file to the Potpourri facility or to
the pull-down Menu (as described later in this chapter).

(For more information on compiling and executing external macros, see
"Introduction to External Compiled Macros" in the chapter on
"Creating and Using Macros."  Also see "Compiling Macros" in the chapter on
"Using Macros" in the Macro Reference Guide.)


Adding an External Macro to the Potpourri
─────────────────────────────────────────

Do you ever have difficulty remembering the key assignment for that useful,
but seldom-used macro?  Do you have some really useful macros that you do not
use often enough to put on the regular menus or assign to a key?  Do you have
macros you would like to be available via a menu, but you do not want to go
to the trouble to put them there?  If so, the editor's Potpourri may be
helpful for you.

The Potpourri facility allows you to maintain a pop-up PickList of external
Compiled Macro files, including a short description of each.  From this
PickList, you can select a particular macro file to execute.  You can also
add a new entry or delete an existing entry from the PickList.  To invoke
Potpourri, select "Potpourri" from the Util Menu (or press <Shift F10>).

Once the PickList of available macro files is displayed, you can use the
cursor keys and/or SpeedSearch to select and execute a macro file.  Simply
position the cursor on the desired entry, and press <Enter>.  To add a new
macro file to the Potpourri, press <Ins>.  To delete an entry that is no
longer needed, position the cursor on the entry in question, and press <Del>.

For more information on the Potpourri facility, see
"Executing Supplemental Macros from the Potpourri" in the chapter on
"Special Commands and Features."


Maintaining a Macro Autoload File
─────────────────────────────────

The editor provides for the use of an optional macro autoload file that allows
you to maintain a list of Compiled Macros to automatically load each time you
start the editor.  This autoload file, TSELOAD.DAT, is a convenient facility
for loading user-written external macro files that you want to have available
every time you start the editor.  This eliminates the need to manually load
the macros, and is an alternative to using the "Load Macro" (-l) command-line
option when starting the editor.  The AutoLoadList command ("AutoLoad List"
under the Macro Menu) allows you to view and modify the list of entries in
the autoload file.

(For more information on the macro autoload file, see
"Editor Startup Processing" in the chapter on "Starting the Editor," and
"The AutoLoadList Command" in the chapter on "Creating and Using Macros.")


Creating a TSEStart Macro File
──────────────────────────────

To further facilitate user customization, the editor provides the TSEStart
macro file.  This is a special user-defined external macro file that, if used,
is automatically invoked every time you start the editor.

The TSEStart macro file is an excellent facility for specifying startup
procedures, such as initially setting variables and editing modes, and loading
custom macros.  It can serve as an alternative to modifying the WhenLoaded
macro procedure included in the standard TSE.UI user-interface macro file.

The TSEStart macro feature also provides an alternate method for creating
versions of the editor that behave differently depending on the directory from
which the editor is started.  You can include a unique TSEStart macro file in
the desired directories.  The editor will execute the TSEStart macro file
located in the directory where you start the editor, and perform the functions
specified.

Following are steps to create a very simple TSEStart macro file.  In this
example, TSEStart merely loads the CutFill macro file, created earlier in
"Creating an External Compiled Macro," and makes it automatically available
during each editing session.

    • In your \TSE\USERMAC\ subdirectory (or other suitable directory included
      in your TSEPath variable, as discussed earlier in
      "Creating an External Compiled Macro"), edit a macro source file called
      TSESTART.S.  This is the required name for the file.

    • Type the following text into the file (assuming that the CUTFILL.MAC
      macro file is in the same directory as TSESTART.MAC will be):

          proc Main()
              LoadMacro("cutfill")
          end

    • Press <Ctrl F9> to Compile the macro source file.  When Compile is
      complete, the Compiled Macro file, TSESTART.MAC, is placed in the same
      directory as TSESTART.S.

Now each time you run the editor, the TSEStart macro file will automatically
be invoked.  And in turn, TSEStart will load your new CutFill macro.

(For more information on the TSEStart macro file, see
"Editor Startup Processing" in the chapter on "Starting the Editor.")


Understanding User-Interface (UI) Macro Files
─────────────────────────────────────────────

As mentioned previously, a useful feature of the editor is its
customizability.  Control over much of the behavior of the editor has been
taken out of the editor itself, and placed into the hands of the user.  This
is accomplished through a user-interface (UI) macro source file, which you
can modify according to your preferences.

A user-interface macro source file has a filename extension of ".UI", and
includes the user's preferred key assignments, menus, and help information, as
well as source for additional macros.  (Optionally, the user's preferred
configuration options (variables) can be included in this file, though this is
not the recommended method.  The recommended method is to use IConfig.)

For the modifications and macros in the user-interface source file to become
effective, the user-interface source file must be compiled and then installed
in the editor.  These installed features, including any macros that are part
of the user-interface macro, are automatically activated and available during
an editing session.

Several user-interface macro source files are included with the editor, and
are located in the UI\ editor subdirectory.  The standard user-interface
macro file for the editor is TSE.UI.  User-interface files that emulate
several other popular editors and word processors are also included. These
user-interface files include editor variable (configuration) settings,
various commands implemented as macros, as well as menus, help, and all the
key assignments for commands.  Any or all of these can be changed by the
user.

The overall layout of the user-interface macro file is:

    • The configuration section, which is optional.  The configuration
      section, contained within the "Config" and "EndConfig" keywords, is
      where the editor variables can be set to the user's preferences.

      In the standard version of the editor, this section is not used.  An
      alternate, easier method for setting editor variables is provided
      through IConfig, the editor's menu-driven Interactive Configuration
      facility (as described previously under
      "Changing Settings for Editing Options Using IConfig").  It is
      recommended that you use IConfig to set editor variables, and then
      install the settings into the editor by selecting "Save Current
      Settings" under the Options Menu.

      The two methods for setting editor variables are not compatible with
      each other, so you should not use both.  If you choose not to use
      IConfig, you will have to add a configuration (Config/EndConfig) section
      to the user-interface file.

    • The "Help screen" of key assignments that are displayed when "Key
      Assignments" is selected from the Help Menu.  In the standard version,
      the only key assignments that are listed here are those commands that
      are not available on the pull-down Menu, or not included on the
      HelpLines.

    • All the macros for commands that are implemented in the editor as
      enhancements or additions to the native editor commands.

    • The entire pull-down Menu system.

    • The actual key assignments for all commands and macros assigned to keys.
      Key assignments are generally placed at the end of the user-interface
      macro file.  For any keys that are assigned to a macro, rather than to a
      native command, the key assignment must follow the macro definition.  By
      placing the key assignments at the end of the file, they will be located
      after any associated macro procedures defined within the user-interface
      file.


Many of the editor's commands are built-in native commands, and are used by
simply assigning them to keys in the user-interface file.  Examples of these
native commands include:

    • Left(), Right(), Up(), Down()

Other native editor commands are augmented by macros included in the
user-interface file.  These macros enhance the behavior of the native
commands.  These enhanced commands are assigned, in turn, to keys in the
standard version of the editor (in TSE.UI), rather than the built-in native
commands.  Examples of these macros include:

    • mDelChar(), mBackSpace(), mCReturn(), mBegFile(), mEndFile()

Additional macros are included in the standard version of the editor, and
provide enhanced features not available with the native editor commands.
Examples of these include:

    • mSwapLines(), mAsciiChart(), mListRecentFiles(), mCompressView()

Note the "m" preceding these last two types of "macro enhanced" commands.
This is used to distinguish native commands from commands implemented as
macros.

(For more information on user-interface macro files, see the chapters on
"Using Macros" and "Using Macro Language Features" in the
Macro Reference Guide.  For more information on the native editor commands,
see the chapter on "Editor Commands" in the Macro Reference Guide.)


Installing a User-Interface (UI) Macro File
────────────────────────────────────────────────────────

Installing a new user-interface (UI) macro file causes the changes you have
made to take effect.  This is done by compiling the ".UI" macro source file.
Typically, these changes include new key assignments, changes to the menus,
changes to the HelpLines, or changes and additions to the macros comprising
the user-interface file.  Keep in mind that any changes you make to your
user-interface macro file will not automatically be maintained when you
upgrade to a newer version of the editor.  You may want to document the
changes you make so that you can review those changes and re-apply them, as
necessary, to future versions.

As a precaution, it is recommended that you make a backup copy of the supplied
user-interface files before making changes to them.  Then, if your changes do
not give the results you expected, you can restore the original user-interface
file(s).

There are two ways to compile and install a new user-interface (".UI") macro
file.  The following outlines the simplest (and the recommended) way to do
this.  It assumes you are installing the standard editor user interface, and
that the current directory is \TSEPro.

    • In the editor, load the standard editor user-interface file, TSE.UI,
      located in the UI\ editor subdirectory.

    • Execute Compile (press <Ctrl F9>) to compile and install the new user
      interface.  If the compile operation is successful, the new interface is
      automatically installed.  However, in order for the changes to take
      effect, you must first quit and then restart the editor.

NOTE:   When installing your new user interface, the compile operation will
        create a separate automatically-loaded interface file, "TSEUI.DAT", in
        the editor load directory.  Also, if the .UI file contains a
        configuration (Config/EndConfig) section, then a "TSECFG.DAT"
        interface file will also be created containing the configuration
        settings from that section.

        Even though these files are separate files, they are effectively
        installed in the editor, in that they will be automatically activated
        by the editor each time the editor is started; no further action is
        necessary.

As an alternative, you can compile and install the new user interface (".UI")
macro file from the command line using the SAL compiler program directly, as
follows (assuming you are installing TSE.UI, and that the current directory
is \TSEPro):

    • Type "sc32".

    • At the first prompt, type "b" (to "burn in" a user interface) and press
      <Enter>.

    • At the "Filename of interface file:" prompt, type "ui\tse" and
      press <Enter>

    • At the "Filename of The SemWare Editor:" prompt, press <Enter> to
      accept the default choice, or modify as necessary before pressing
      <Enter>.

    • The compiler will compile the user-interface file, and then attempt to
      burn that user interface directly into the editor executable program
      If, however, the editor is currently running, it will not be able to
      burn in the user interface, and it will display the following:

        Unable to burn in interface - continuing...
        Create separate automatically-loaded interface file(s) instead? [Y/N]

      Type "y".  A separate "TSEUI.DAT" interface file will be created in the
      editor load directory.  If the ".UI" file contains a configuration
      (Config/EndConfig) section, then a "TSECFG.DAT" interface file will also
      be created containing the configuration settings from that section.
      These files are effectively installed in the editor, in that they will
      be automatically activated by the editor each time the editor is
      started; no further action is necessary.

      If you type "n" at the above prompt, the user interface will not be
      installed.

      Note that if you want to burn the user interface into the editor program
      itself, so that only a single file is required to run the editor, then
      type "n".  Then terminate the editor in any sessions where it may be
      running, and re-run the SAL compiler program (SC32.EXE).

    • The TSE.UI file is compiled and installed.  The next time you load the
      editor, your changes will be in effect.

As noted in the previous section, using the optional configuration
(Config/EndConfig) section of a user-interface macro file is not compatible
with using IConfig to set variable options (or with setting any other options
available under the Options Menu).  Once you select "Save Current Settings"
under the Options Menu, the variable settings currently in effect are
installed in the editor.  If you later compile and install a user-interface
macro file that contains a Config/EndConfig section, the settings installed by
the "Save Current Settings" option are overwritten by those specified in the
Config/EndConfig section.  Likewise, if you install a user-interface macro
file with a Config/EndConfig section, and then change settings interactively
(using IConfig or other Options Menu options) and select "Save Current
Settings," you overwrite the Config/EndConfig settings.


Adding or Changing Key Assignments
──────────────────────────────────

As discussed earlier in this chapter, the key assignments for commands and
macros are maintained in a user-interface macro file.  Adding or changing key
assignments is quite simple, as described in the following steps.

The first step is to decide the key you would like to assign.  You can assign
commands or macros to single keystrokes, either unshifted (such as <K> or
<F1>), or shifted (such as <Ctrl K> or <Alt F1>).  You can also assign
commands or macros to "two-keys", such as <F4 A> (which is assigned as
<F4><A>), or <Ctrl K S> (which is assigned as <Ctrl K><S>).

Additionally, you can assign commands or macros to multi-shift keys using
<Ctrl>, <Alt>, and <Shift> (such as <CtrlShift K> or <CtrlAlt F1>).  Most
keys are available for assignment; and generally, any keys that are available
as single keys are also available as two-keys and multi-shift keys.

To verify whether a particular single key (including single-shift and
multi-shift keys) is a valid assignable key, you can use the ShowKey macro,
available on the Potpourri menu.  (Select "Potpourri" under the Util Menu, or
press <Shift F10>; then choose "ShowKey".)  In ShowKey, type the desired key.
If the key is assignable, a line is displayed providing information about that
key, including how to identify the key in a key assignment (indicated under
the column "Key Name").  If the key is not assignable, nothing is displayed
when you press the key.

The next step in adding or changing a key assignment, is to decide the command
or macro you would like to assign to the key you selected.  This can be any of
the 400+ commands that are native to the editor, or it can be a macro written
by you or someone else.  To assign a macro to a key, the macro itself must
also be included in the user-interface file.  Numerous macros included with
the editor can be found in the TSE.UI user-interface file.  (For more
information on the native editor commands, see the chapter on
"Editor Commands" in the Macro Reference Guide.)

Now you are ready to edit the TSE.UI file, assuming you are using the
standard editor user interface, located in the UI\ editor subdirectory.  The
key assignments for the TSE.UI user interface are maintained in this file
(following the comment, "Keyboard bindings..."), and grouped by functions.

The format for key assignments is:

    <key>  command

where key is the name of the key you wish to assign, enclosed within < >,
and command is the command or macro you wish to assign to <key>.

If a command or macro is already assigned to the key that you have chosen,
locate the line containing the existing <key> assignment.  On that line,
delete the existing command, and replace it with your new command or macro.

If the key assignment does not already exist in the file, you can place the
new assignment anywhere in the file (as long as it is located after the
associated macro, if you are assigning a macro to a key).  However, you may
wish to add new key assignments at the end of the current key assignments.  To
add a key assignment, add a line in the format indicated above, with the
<key> and command of your choice.

Once you have changed and/or added key assignments, save the file.  For the
new key assignments to take effect, you must install your changes in the
editor.  To do this, follow the steps outlined previously in this chapter
under "Installing a User-Interface (UI) Macro File."

When you install your new user interface, the pull-down Menu is automatically
updated to reflect the current key assignments for any commands included in
Menu.  If the same command is assigned to multiple keys in the user interface,
then the first key assignment indicated in the user interface for that command
is the one that is identified in the Menu, where applicable.

Note that any given key can be assigned to only one command or macro.  If you
inadvertently assign the same key to more than one command or macro in a
user-interface file, and then install that user interface, only the first
occurrence of that key assignment in the file will become effective.

(For more information on key assignments, see
"Assigning Macros and Commands to Keys" in the chapter on
"Using Macro Language Features" in the Macro Reference Guide.)


Changing the HelpLines
──────────────────────

HelpLines are used in the editor to display up to four different user-defined
lines of text associated with the following key states:

    • The normal "unshifted" key state (that is, no shift keys pressed)

    • The "control" shifted key state (that is, the <Ctrl> key pressed)

    • The "shift" shifted key state (that is, the <Shift> key pressed)

    • The "alternate" shifted key state (that is, the <Alt> key pressed)

HelpLines are optional, and if displayed, appear at the top or bottom of the
screen, opposite the StatusLine.

HelpLines are declared similarly to key assignments, as follows:

    <HelpLine>  constant_string

    <Alt HelpLine>  constant_string

    <Ctrl HelpLine>  constant_string

    <Shift HelpLine>  constant_string

where constant_string is the text you want to display on the HelpLine, in a
form such as:

    "{F1}-Help {F2}-AddLn {F4}-DupLn {F5}-ScrollToTop {F6}-DelToEol
     {F9}-Shell {F10}-Menu"

The constant_string HelpLine text must be enclosed in single or double
quotes.  Text enclosed within braces, { }, is highlighted on the screen.

You can display whatever single line of text you wish in the HelpLines, up to
the width of the screen.  The unshifted HelpLine (<HelpLine>) is normally
displayed.  To display the shifted HelpLines, press and hold down the
appropriate shift key.

It is a simple process to add or change a HelpLine.  Begin by editing the
file TSE.UI, assuming you are using the standard editor user interface,
located in the UI\ editor subdirectory.  The HelpLine assignments for the
TSE.UI user interface are maintained in this file (following the comment,
"Keyboard bindings..."), grouped under the comment, "HelpLine assignments".

If you want to change an existing HelpLine, locate the line containing the
HelpLine assignment.  On that line, delete the existing constant_string
text, and replace it with your new text (enclosed in quotes).

If the HelpLine assignment does not already exist in the file, you can place
the new assignment anywhere in the file.  However, you may wish to add the new
HelpLine assignment near the other HelpLine assignments.  To add a HelpLine
assignment, add a line in the format indicated above, with the HelpLine
selection and text of your choice.

Once you have changed and/or added HelpLine assignments, save the file.  For
the new HelpLines to take effect, you must install your changes in the editor.
To do this, follow the steps outlined previously in this chapter under
"Installing a User-Interface (UI) Macro File."

(For more information on HelpLines, see the chapter on
"Getting Help in the Editor."  Also see "HelpLines" in the chapter on
"Using Macro Language Features" in the Macro Reference Guide.)


Modifying the Key-Assignment Help Screen
────────────────────────────────────────

The standard configuration of the editor includes a multi-page Help screen
that lists the key assignments for commands which are not included on the
menus or standard HelpLines.  This standard key-assignment Help screen is
displayed when "Key Assignments" is selected from either the Help Menu or from
the HelpSystem "Table of Contents".

If you change key assignments in the editor, you may wish to update the Help
screen to reflect your new assignments.  Or, you may want to include
additional key assignments on the Help screen.

To change or create a new Help screen, begin by editing the file TSE.UI,
assuming you are using the standard editor user interface, located in the UI\
editor subdirectory.  The Help screen key assignments for the TSE.UI user
interface are maintained in this file (following the comment, "Key-assignment
Help screen").

You will notice that the Help screen key-assignment section consists of
special macro (SAL) keywords in the first few lines at the beginning of the
section, followed by the SAL "end" statement at the end of this section.  The
other lines in between contain text enclosed within quotes, and is the text
that is displayed on the Help screen.

To change the contents of the Help screen, modify the text within quotes, as
desired.  Each line of display text must be enclosed within a pair of single
(') or double (") quote characters.  You may add as many lines to the Help
text as you wish.  If the additional lines force the Help text to exceed the
number of lines on your monitor, scroll bars will appear when the Help screen
is displayed, and you will be able to use the cursor keys or the mouse to
scroll through the Help text.

Once you have changed the Help screen text, save the file.  For the new Help
screen to take effect, you must install your changes in the editor.  To do
this, follow the steps outlined previously in this chapter under
"Installing a User-Interface (UI) Macro File."

Though you can modify the text on this Help screen to display whatever you
like, it is recommended that you use it as key assignment Help.  This Help
screen is displayed when you select "Key Assignments" from the Help Menu or
the HelpSystem "Table of Contents."

The Help facility, used by the editor to create the key-assignment Help
screen, is also available for creating your own additional help screens.  The
special macro (SAL) "helpdef" construct is used for this.

(For more information on the HelpSystem that uses the key-assignment Help
screen, see the chapter on "Getting Help in the Editor."  For more information
on creating your own help screens, see "Helpdef" in the chapter on
"Using Macro Language Features" in the Macro Reference Guide.)


Making Changes to the Pull-Down Menu
────────────────────────────────────

The editor's pull-down Menu system is defined in the main user-interface macro
file (TSE.UI), immediately following the macro procedures, after the comment,
"TSE Pull-down Menus".  You can modify the pull-down Menu system by deleting
or changing an existing entry, or by adding a new entry to a Menu.

To make a change to one of the pull-down Menus, first edit the file TSE.UI,
assuming you are using the standard editor user interface, located in the UI\
editor subdirectory.

In TSE.UI, locate the pull-down Menu definition that you want to change.  Each
pull-down Menu definition has the same name as shown on the main pull-down
Menubar, with the word "Menu" appended to it.  Each Menu definition is also
preceded by the "menu" keyword.

To delete a Menu entry, locate that entry in the appropriate Menu definition,
and delete the line containing that entry.  For example, suppose that you
never use the "Local UnDelete" option on the Text Menu, and would like to
remove it from the Menu to shorten the Text Menu list.  To do so:

    • Locate the Text Menu definition by searching for "TextMenu".

    • Locate the "Local UnDelete" line within the Text Menu definition, and
      simply delete this line.  Note that the actual text in the Menu
      definition is "&Local UnDelete".  The "&" preceding "L" indicates to the
      editor that the quick-key for this Menu entry is the letter "l".

To change a Menu entry, locate that entry in the appropriate Menu definition,
and make the desired change.  For example, suppose you want the "Mark
Character" option on the Block Menu to invoke the MarkChar command rather than
the MarkStream command.  To make this change:

    • Locate the Block Menu definition by searching for "BlockMenu".

    • Locate the "Mark Character" line within the Block Menu definition.  Note
      that the actual text in the Menu definition is "Mark Ch&aracter". The
      "&" preceding the first "a" indicates to the editor that the quick-key
      for this Menu entry is the letter "a".

    • Change the command assignment, located on the right, from "MarkStream()"
      to "MarkChar()" (without the quotes).  The key assignment for the
      MarkChar command (<Alt I>) will automatically be displayed beside this
      option when you pull down the Block Menu.

To add a Menu entry, add an entry line in the appropriate Menu definition.
For example, suppose you frequently use the MarkWord command, but have
difficulty remembering the key assignment.  (MarkWord is not included on the
Menu in the standard configuration of the editor.)  You might want to add it
to the pull-down Menu, so it is readily available.  Because it is a
block-marking command, you may want to put it under the Block Menu, and place
it immediately after the "Mark Column" option on the Menu list.  To add this
entry:

    • Locate the Block Menu definition by searching for "BlockMenu".

    • Locate the "Mark Column" line within the Block Menu definition.  Note
      that the actual text in the Menu definition is "Mar&k Column".  The "&"
      preceding "k" indicates to the editor that the quick-key for this Menu
      entry is the letter "k".

    • Add a line immediately after the "Mar&k Column" line, similar to:

          "Mark W&ord", MarkWord()

      The text in quotes will display on the screen when you pull down the
      Block Menu.  You can use whatever text you prefer.

      The "&" in front of "o" indicates that the quick-key for this entry is
      the letter "o".  You can choose any letter in the text you prefer, but
      be sure that the letter is not already used by another entry in the
      Block Menu definition.

      MarkWord() is the proper name of the native editor command to be invoked
      when this Menu option is selected.  (For more information on the names
      of commands and macros by which editing commands are implemented, see
      "Appendix E:  Command Implementation.")

      Note that the key assignment for the MarkWord command (<Ctrl K><T>) will
      also be displayed to the right of this option (as <Ctrl K T>) when you
      pull down the Block Menu.

Once you have completed your pull-down Menu changes in TSE.UI, save the file.
For the new Menu definitions to take effect, you must install your changes in
the editor.  To do this, follow the steps outlined previously in this chapter
under "Installing a User-Interface (UI) Macro File."

(For more information on the pull-down Menu system, see the chapter on
"The Pull-Down Menu System."  For more information on the syntax for menu
definitions, see "Menus" in the chapter on "Using Macro Language Features" in
the Macro Reference Guide.)


Adding Macros to the User-Interface (UI) Macro File
────────────────────────────────────────────────────

Suppose that you would like to have the CutFill macro (created previously in
"Creating an External Compiled Macro") added to the standard user-interface
macro file, and also have it appear on the Clip Menu.  By adding it to the
user-interface file and installing it in the editor, it can be executed, as
needed, without first having to load the CutFill macro file.

To add a macro to your user-interface file, edit the file TSE.UI, assuming
you are using the standard editor user interface, located in the UI\ editor
subdirectory.

In TSE.UI, you need to find an appropriate place to add the CutFill macro.  It
must be placed in TSE.UI at a location that precedes any other lines in TSE.UI
that will reference it.  Since it is referenced by a key (<Alt Grey->), and
you will be adding it to the Menu, it must be placed before the pull-down Menu
definitions, and before the key assignments.  A suitable place to add it would
be just before the Menu definitions.

    • Locate the string "TSE Pull-down Menus".  This identifies the beginning
      of the Menu definitions for the pull-down Menu system in the standard
      version of the editor.

    • Add the CutFill macro procedure just before the comment lines containing
      the string you just located.

    • Certain changes must be made to the CutFill macro, as originally created
      earlier in this chapter.  Because this macro has now been included in a
      larger macro file, you need to change the macro name from "Main" to
      something more appropriate, such as mCutFill.  (The "m" preceding
      "CutFill" indicates this is a macro, rather than a native editor
      command.)  You may also want to move the key assignment to the
      key-assignment area of the user-interface file.

      The entire macro definition should now look like:

         // Cut a block to the ClipBoard, back-filling with spaces
         proc mCutFill()
             if isBlockinCurrFile()
                 PushBlock()
                 Copy()
                 PopBlock()
                 FillBlock(' ')
             endif
         end

Next, add the CutFill macro to the Clip pull-down Menu.  A good place to add
it is immediately after the "Cut Append" option on the Menu list.  (For more
information on modifying the pull-down Menu definitions, see
"Making Changes to the Pull-Down Menu" earlier in this chapter.)  To add this
entry:

    • Locate the Clip Menu definition by searching for "ClipMenu".  (Each
      pull-down Menu definition has the same name as shown on the main
      pull-down Menubar, with the word "Menu" appended to it.)

    • Locate the "Cut Append" line within the Clip Menu definition.  Note that
      the actual text in the Menu definition is "C&ut Append".  The "&"
      preceding "u" indicates to the editor that the quick-key for this Menu
      entry is the letter "u".

    • Add a line immediately after the "C&ut Append" line, similar to:

          "Cut &Fill", mCutFill()

      The text in quotes will display on the screen when you pull down the
      Clip Menu.  You can use whatever text you prefer.

      The "&" in front of "F" indicates that the quick-key for this entry is
      the letter "f".  You can choose any letter in the text you prefer,
      provided the letter is not already used by another entry in the Clip
      Menu definition.

      mCutFill() is the name of the command (which YOU just created as a macro
      in TSE.UI) to be invoked when this Menu option is selected.

      Note that the key assignment for mCutFill (<Alt Grey->), to be added in
      the following steps, will also be displayed to the right of this option
      when you pull down the Clip Menu.

Now, add the key assignment for mCutFill to the user-interface file.  (For
more information on adding a key assignment, see
"Adding or Changing Key Assignments" earlier in this chapter.)

    • Locate the line containing the key definition for <Ctrl Grey->.

    • After the <Ctrl Grey-> definition line, add a line with the following
      text:

          <Alt Grey->  mCutFill()

    • Save the TSE.UI file.

Finally, you are ready to install your changes in the editor.  To do this,
follow the steps outlined previously in this chapter under
"Installing a User-Interface (UI) Macro File."

Congratulations!  You have just added a new command to the editor, added that
command to the Menu, and created a new key assignment.  Your new mCutFill
command will behave as if it had been originally built in to the editor.


Creating a Custom User-Interface (UI) Macro File
────────────────────────────────────────────────

Instead of using or modifying the standard user-interface macro file (TSE.UI),
or one of the other user-interface files included with the editor, you may
wish to create your own.  This section walks you through development of a
user-interface macro file, beginning with a very simple user interface, and
then adding more functionality.  (You should be familiar with the topics
covered earlier in this chapter before proceeding.)


Starting Simple

To begin creating your user-interface macro file, edit a new macro source file
called (for example) MY.UI.  The name you choose for this file should have the
extension ".UI", which identifies this file as a user-interface macro file.
This extension instructs the Compile command to automatically install this
macro file, once compilation of the file is successfully completed.

At the beginning of your user-interface file, type the following key
assignment:

    <Alt X>         Exit()

Now you have a very simple user-interface file for the editor.  To install it,
execute the Compile command (by pressing <Ctrl F9>).  For the changes to
actually take effect, quit the editor and then restart it.

Of course, this is not a very useful user interface, and it is not recommended
that you install this interface in the editor!  In this simple user interface,
you have assigned only a single editor command to a key; that is, the Exit
command.  There are no other key assignments and no menus available.  Thus, in
the version of the editor that would result from installing this user
interface, you could not execute any commands other than the Exit command, and
it could be executed only by pressing <Alt X>.  All you could do with this
editor would be to edit a file, view the first page, and exit (by pressing
<Alt X>).

Note that in a macro file, the case and the spacing of the characters are not
significant.  You could enter your code in a style that suits you, as
illustrated by the following key assignments:

    <Alt x>                 Exit()

    <ALT X> EXIT()

    <alt x>     exit()

    <aLt X>         eXiT()


Adding More Functionality

To add more functionality to your custom editor, edit your user-interface
file MY.UI, and include key assignments for a few cursor movement and
editing commands, so that MY.UI looks like the following:

    <F2>                AddLine()
    <F4>                DupLine()
    <F6>                DelToEol()
    <F9>                Shell()

    <BackSpace>         BackSpace()
    <Enter>             CReturn()
    <Tab>               TabRight()
    <CursorDown>        Down()
    <CursorLeft>        Left()
    <CursorRight>       Right()
    <CursorUp>          Up()
    <Del>               DelChar()
    <End>               EndLine()
    <Home>              BegLine()
    <Ins>               ToggleInsert()
    <PgDn>              PageDown()
    <PgUp>              PageUp()

    <Alt E>             EditFile()
    <Alt N>             NextFile()
    <Alt X>             Exit()


You can organize the key assignments in any order you prefer.

To install this new user interface, execute the Compile command (by pressing
<Ctrl F9>).  For the changes to take effect, quit the editor and then restart
it.

This user interface is a little more useful than the first, though it is not
recommended that you actually install this particular interface in the editor.
With this version of the editor, you could move around in a file using the
cursor keys, perform simple editing tasks, select additional files for editing
(by pressing <Alt E>), switch between files (by pressing <Alt N>), and even
Shell out of the editor to the operating system (by pressing <F9>).  However,
it is still not complete enough to be truly useful.  It does not even give you
access to any commands that save files!

To complete your user interface, you will want to add more key assignments,
and probably menus and help, to allow you to access the many commands that you
need for editing.  If you are not using IConfig to set editor variables, you
will need to add a variable configuration (Config/EndConfig) section.  (For
more information on how to do this, see the chapters on "Using Macros" and
"Using Macro Language Features" in the Macro Reference Guide.)


Adding Your Own Commands

To make your user interface more useful for your particular needs, you may
want to add your own commands or modify the behavior of some of the editor's
built-in commands.  Perhaps you have a preferred way of performing an editing
task, that is different from the way the editor performs that task.  Or maybe
there is an editing feature that you really need, but that feature is not
included in the editor.  Or you may possibly want to combine several editor
commands into one command that you can execute with a single keystroke.

For this type of extended customizability, user-written macros are beneficial.

For example, suppose you want to change the behavior of the native (built-in)
DelChar() command, which deletes the current character.  But if the cursor is
beyond the end of the text on the current line when you execute DelChar(),
nothing happens.  Like many other users, you would like DelChar() to join the
next line to the current line, when it is executed beyond the end of the line.

You can write a macro to implement your own DelChar command to behave in the
manner you prefer.  Begin by once again editing your user-interface file,
MY.UI.  Near the beginning of the file, before your key assignments, and
before any menu or help definitions, add the following:

    proc mDelChar()
        if CurrChar() >= 0  // if not past the end-of-line
            DelChar()       // just delete the current char
        else                // otherwise,
            JoinLine()      // join the next line to this one
        endif
    end

Next, locate the key assignment line containing "<Del>  DelChar()", and change
it to:

    <Del>               mDelChar()

You have now replaced the key assignment for <Del> (currently assigned to the
native DelChar() command) with a user-written macro named mDelChar().  (The
"m" at the beginning of the macro name is used as a convention to identify
this "command" as a macro.)

Once you install your new user interface file (and restart the editor), the
<Del> key will behave like the native command when the cursor is within the
text on a line; however, when the cursor is past the end-of-line, it will join
the next line to the end of the current line.  Note that in the standard
editor user interface (TSE.UI), the <Del> key is assigned to a macro that is
very similar to the macro presented here.

When adding macros to a user-interface file, keep in mind that new identifiers
(such as macro names) must be declared BEFORE they are referenced.  Thus, in
the example given, the key assignment used for mDelChar() has to occur AFTER
the mDelChar() procedure definition.  To keep things properly organized in the
user-interface files supplied with the editor, macro procedures (for commands
implemented as macros) are placed at the beginning of the file.  These are
followed by menus.  Finally, key assignments are placed at the very end of the
user-interface file.

To make your user-interface file easier to manage, you can take advantage
of "include files."  This allows you to logically break the user-interface
components into several smaller files.  (For more information on the #include
statement, see "Include Files" in the chapter on
"Using Macro Language Features" in the Macro Reference Guide.)





Customizing the Editor

Because no two users are alike, the editor offers extensive customization
options.

From within the editor itself, you can configure the behavior of many commands
and features using the Interactive Configuration facility (IConfig).  Your
configuration selections are in effect for the current session only, unless
you update the editor program so that they are in effect each time the editor
is started.  To access IConfig, select "Full Configuration" under Options on
the pull-down Menu.  To update the editor program with your configuration
settings, select "Save Current Settings" under the Options Menu.

Further customizing is provided through the editor's macro programming
language, the SemWare Applications Language (SAL), which is complete with its
own debugger.  SAL allows you to modify the pull-down Menu, the HelpLine
bars, and the key-assignment Help screen.  It also allows you to assign
commands to different or additional keys.  You can use SAL to enhance or
extend the editor's commands by writing and compiling your own Compiled Macro
commands:  if you do not like the way the editor performs an operation, you
can change it; or if you need an additional feature, you can add it.


(For more information on configuring the editor using IConfig, see the chapter
on "Configuring the Editor Interactively."  For more information on
customizing the Menu, HelpLine, Help screen, key assignments, and commands in
the editor, see the chapter on "Fully Customizing the Editor."  For more
information on the details of SAL, see the Macro Reference Guide.)





Cut()

Copies the marked block to the ClipBoard.  The block is then removed from the
file.  The current contents of the ClipBoard are discarded before the
operation starts unless the _APPEND_ constant is passed to the command.

Syntax:     INTEGER Cut([INTEGER flag])

            • flag is an optional integer that specifies whether Cut()
              should keep or discard the current ClipBoard contents.  If not
              specified, _DEFAULT_ is used. Supported values for flag are:

              • _DEFAULT_ specifies that the current ClipBoard contents
                should be discarded.

              • _APPEND_ causes Cut() to append the block to the current
                ClipBoard contents.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            Cut() will not cut a block that exists outside the current file.

            If no block is marked and the UseCurrLineIfNoBlock variable is set
            ON, the current line is cut to the ClipBoard.

            If no block is marked and UseCurrLineIfNoBlock is set OFF, no
            action occurs and zero is returned.

See Also:   CutAppend(), Copy(), CopyAppend(), Paste(), PasteReplace()

            CutToWinClip(), CutAppendToWinClip(), CopyToWinClip(),
            CopyAppendToWinClip(), PasteFromWinClip(),
            PasteReplaceFromWinClip()

            DelBlock(), CopyBlock(), MoveBlock()

            isBlockMarked(), isBlockInCurrFile()

            Variables:  BlockId, ClipBoardId, UseCurrLineIfNoBlock





CutAppend()

Copies the marked block to the ClipBoard, appending it to the current
contents.  The block is then removed from the file.

Syntax:     INTEGER CutAppend()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            CutAppend() will not cut a block that exists outside the current
            file.

            If no block is marked and the UseCurrLineIfNoBlock variable is set
            ON, the current line is cut to the ClipBoard.

            If no block is marked and UseCurrLineIfNoBlock is set OFF, no
            action occurs and zero is returned.

            To retrieve text from the ClipBoard, use the Paste() command.

Examples:

            // Causes <Ctrl Grey-> to Cut a block to the ClipBoard,
            // appending it to the current contents
            <Ctrl Grey->    CutAppend()


See Also:   Cut(), Copy(), CopyAppend(), Paste(), PasteReplace()

            CutAppendToWinClip(), CutToWinClip(), CopyToWinClip(),
            CopyAppendToWinClip(), PasteFromWinClip(),
            PasteReplaceFromWinClip()

            DelBlock(), CopyBlock(), MoveBlock()

            isBlockMarked(), isBlockInCurrFile()

            Variables:  BlockId, ClipBoardId, UseCurrLineIfNoBlock





CutAppendToWinClip()

Copies the marked block to the Windows Clipboard, appending it to the current
contents.  The block is then removed from the file.

Syntax:     INTEGER CutAppendToWinClip()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            CutAppendToWinClip() will not cut a block that exists outside the
            current file.

            The block is removed after the copy is performed.

            If there is no marked block, but the UseCurrLineIfNoBlock variable
            is set ON, the current line is cut to the Clipboard.

            To retrieve text from the Windows Clipboard, use the
            PasteFromWinClip() command.

See Also:   CopyToWinClip(), PasteFromWinClip(), Cut(), Paste(),
            isBlockMarked(), isBlockInCurrFile(), CopyAppendToWinClip()

            Variables:  BlockId, UseCurrLineIfNoBlock





CutToWinClip()

Copies the marked block to the Windows Clipboard.  The block is then removed
from the file.  The current contents of the Windows Clipboard are discarded
before the operation starts.

Syntax:     INTEGER CutToWinClip()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.
            CutToWinClip() will not cut a block that exists outside the
            current file.

            The block is removed after the copy is performed.

            If there is no marked block, but the UseCurrLineIfNoBlock
            variable is set ON, the current line is cut to the Clipboard.

            To retrieve text from the Windows Clipboard, use the
            PasteFromWinClip() or PasteReplaceFromWinClip() command, as
            appropriate.

See Also:   CutAppendToWinClip(), CopyToWinClip(), CopyAppendToWinClip(),
            PasteFromWinClip(), PasteReplaceFromWinClip()

            Cut(), CutAppend(), Copy(), CopyAppend(), Paste(), PasteReplace()

            DelBlock(), CopyBlock(), MoveBlock()

            isWinClipAvailable(), EmptyWinClip(), isBlockMarked(),
            isBlockInCurrFile()

            GetStrFromWinClip()

            Variables:  BlockId, UseCurrLineIfNoBlock





Datadef

The datadef construct is used to embed data within a macro without having to
maintain an additional file.  This data is then inserted into the current
buffer using the InsertData() command.  The data in the buffer can be accessed
and manipulated by the macro itself, or can be viewed and edited by the user.
(For more information on manipulating data in buffers, see
"Manipulating Text in Buffers" under "Buffers" earlier in this chapter.)

The format for data definition is:

    datadef data_name
        data_string
            ...
        data_string
    end [data_name]

where:

    • datadef specifies this as a data definition.

    • data_name is a unique name associated with this datadef.

    • data_string is a line of data.  It must be specified as a constant
      string enclosed within single or double quotes.  Each separate
      data_string will be inserted as a separate line in the current buffer
      when InsertData() is executed using this datadef.

    • end signifies the end of the data definition.

    • The data_name may optionally be repeated after the end statement on
      the same line.

The InsertData() command references a datadef to insert the contents of the
indicated data definition into the current file, just as if a file had been
read using InsertFile().

The following example shows how a datadef can be used to define a Main macro
template that is inserted into the current file when you press <F12>.

    datadef MainTemplate
        'proc Main()'
        '   integer i'
        ''
        'end main'
    end MainTemplate

    <F12> InsertData(MainTemplate)





DateFormat

Determines the format of the string returned by GetDateStr().

Values:     INTEGER

            • 1  - mm/dd/yy

            • 2  - dd/mm/yy

            • 3  - yy/mm/dd

            • 4  - mm/dd/yyyy

            • 5  - dd/mm/yyyy

            • 6  - yyyy/mm/dd

            • 7  - MMM dd yy

            • 8  - dd MMM yy

            • 9  - yy MMM dd

            • 10 - MMM dd yyyy

            • 11 - dd MMM yyyy

            • 12 - yyyy MMM dd

Default:    4

Notes:      mm   = 2 digit month
            dd   = 2 digit day
            yy   = 2 digit year
            yyyy = 4 digit year
            MMM  = 3 character abbreviation for Month

            If necessary, digits are padded with zero.

            Allows you to set the format of the date string that is returned
            by the GetDateStr() command.

            GetDateStr() is used in the PrintFile() and PrintBlock() commands
            when printing header and footer lines.  Therefore, DateFormat will
            affect how the date is printed in a header or footer.

Affects:    GetDateStr()

See Also:   DateSeparator, TimeFormat, TimeSeparator, PrintHeader,
            PrintFooter





DateSeparator

Determines the date separator used by GetDateStr().

Values:     INTEGER - ASCII value of a character.

Default:    ASC("/")

Notes:      Allows you to change the character that separates the elements of
            the date string returned from GetDateStr().

            GetDateStr() is used in the PrintFile() and PrintBlock() commands
            when printing header and footer lines.  Therefore, DateSeparator
            will affect how the date is printed in a header or footer.

Affects:    GetDateStr()

See Also:   DateFormat, TimeFormat, TimeSeparator, PrintHeader, PrintFooter





Debugging Macros

At some point in the development or maintenance of a Compiled Macro, it may
be helpful to debug the macro using the SAL macro debugger.  The debugger
allows you to examine the execution of a macro to verify proper execution or
to help determine the cause of problems while executing.  When you invoke the
debugger and execute a macro, control of the macro is passed to you.  You can
then step through execution of the macro, display the contents of affected
files and variables, and even modify the contents of variables as the macro
executes.

To debug a macro file, execute the Debug() command (select "Debug" under the
Macro Menu).  If the file you are currently editing has an extension of ".S",
Debug() operates on that file; otherwise, Debug() issues a prompt to request
the name of the source file to debug.

Once Debug() determines the file on which to operate, the following occurs:

    • If the selected source file is already loaded, it is first saved, if
      necessary.  (This occurs if the source file had been modified since it
      was last saved.)

      Otherwise, if the source file is not already loaded, it is loaded into
      the editor at this time.

    • The source file is then compiled, if necessary, with "debug
      information" included.  (This occurs if Debug() determines that the
      current source file has not already been compiled with debug
      information.)

      If the compiler detects any errors or warnings in the macro source, you
      will be placed in the Compile window.  You can then correct any errors
      or unacceptable warning conditions, and re-execute the Compile()
      command.  Upon successful compilation, select "Debug" from the prompt
      that is displayed to continue the debugging process.  If the compiler
      detects only warning conditions (with no fatal errors), you can
      optionally continue the debugging process (without re-compiling) by
      pressing <Ctrl Enter>.

      (For more information on the Compile() command, see "Compiling Macros"
      earlier in this chapter.)

    • The Compiled Macro (.MAC) file, for the selected source file, is then
      loaded into the editor, if a current Compiled Macro file for the source
      file is not already loaded.

      If a current Compiled Macro file is already loaded, Debug() gives you
      the option to either re-load the Compiled Macro file and begin the
      Debug process once again, or to resume the Debug process without
      reloading the macro.

    • The Debug process is now ready to begin, or possibly resume.  The Debug
      window is displayed, and the source file for the macro you are
      debugging is placed in this window.  The Debug menubar is placed at
      the top of this window, and the Debug helpline is placed at the bottom.

      When you begin a Debug process, breakpoints are automatically set on
      the WhenLoaded() and Main() macros, if these are included in the macro
      file.  The cursor is placed in the source at the first breakpoint, if
      any are set; otherwise, the cursor is placed at the top of the source
      file.  No macros are executed until you select one of the available
      tracing options.  Once you select the first tracing option, initial
      execution of the macro file occurs.

      If you resume (rather than begin) a Debug process, you are returned to
      the previous execution state of the macro.  Initial execution of the
      macro file is bypassed.

At this point, you control the continuing execution of the macro by selecting
the appropriate Debug options.  Debug options can be accessed from the Debug
menu.  (To activate the Debug menu, press <Escape>, or press <Alt> plus the
quick-key of the desired menu category).  Alternatively, you can execute a
Debug option by pressing the key assignment for that option.  (All available
options are included in the Debug menu.  The menu also shows the key
assignments for the Debug options.)

Debug options are available that allow you to set additional breakpoints,
trace or step through code, display the contents of affected files and
variables, and even modify the contents of variables as the macro executes.
The following describes the operation of the most commonly used Debug
options.

    • Setting breakpoints:

      Breakpoints are used to temporarily halt the macro when a certain point
      in the code is reached.

      Options are available to set, toggle, and delete breakpoints.  Just
      position the cursor on the line on which you want to set or delete a
      breakpoint, and execute the desired option.  Select the "BreakPoint"
      menu category to display the available options.

      Breakpoints remain set until you specifically delete them, or until you
      unload the current macro from memory or debug another macro.

    • Tracing through code:

      The basic modes for tracing through code are "Run," "Step," and
      "Trace."  Select the "Run" menu category to display these options.

      "Run" returns control to the current macro and allows it to run until a
      breakpoint is encountered.  The debugger then halts the execution of
      the macro and re-displays the Debug window.

      "Step" causes the macro to execute a single line of code and then
      automatically suspend execution and re-display the Debug window.  Each
      time you select the step option, the next line of code is executed.
      This feature does not require breakpoints to be manually set.  And
      unlike trace, this option bypasses procedure calls within the macro.

      "Trace" is similar to step, except that it also executes user-written
      procedure calls.  (Native commands are bypassed.)

    • Animation:

      Animation automates the tracing mode of the debugger.  By using
      animation, you can run, step, or trace through lines of code at regular
      time intervals without having to continually select a run, step, or
      trace option.  This is especially useful when you want to watch or view
      variables as they change within a looping construct, without having to
      manually continue through each line in the loop.

      "Animate Step" and "Animate Trace" cause execution to suspend
      temporarily as each new line of the macro is executed.  "Animate Run"
      temporarily suspends execution only when breakpoints are encountered.

      When you invoke animation, you will be prompted to provide the
      "animation delay."  This is specified in 1/18 second intervals, and
      indicates the amount of time to display the Debug window (along with
      any associated "watch" windows) before continuing execution.

      To halt animation, press <LeftShift><RightShift> at a point when the
      Debug window is displayed.

    • Exiting from the Debug process:

      Once the Debug process begins (that is, once the Debug window is
      initially displayed), you should not terminate it until you completely
      trace through the code (via the run, step, or trace options).
      Terminating the Debug process before the macro finishes execution would
      leave the editor in an unstable state.

      However, if a situation occurs where you must terminate the Debug
      process prematurely, select "Halt" from the "Run" menu.  This action is
      not recommended, and should only be taken in extreme cases where you
      have no other choice.

    • Watching and modifying memory variables:

      To watch a variable (that is, to display its contents as the macro
      executes), select "Add Watch" from the "Data" menu.  You will be
      prompted for the name of the variable you wish to display.  As the
      macro executes, the value of this variable will be displayed in the
      lower "watch window."  (You can also select a variable to watch by
      placing the cursor on the desired variable name in the source file and
      pressing <Ctrl F7>.)

      If you specify a global variable name, the value of the variable will
      always be available.  If you specify a local variable, the contents of
      the variable will only be available when a function is traced in which
      a variable by that name exists.  For local variables which are not in
      the currently active procedure, the message "not in scope" will be
      displayed.

      To display or modify the contents of a variable, select
      "Modify/Evaluate" from the "Data" menu.  You will be prompted for the
      name of the desired variable.  Once you have specified a variable name,
      you can display the current value by pressing <Enter>, or change the
      value by pressing <Tab>.  (You can also specify a variable to display
      or modify by placing the cursor on the desired variable name in the
      source file and pressing <Ctrl F4>.)

      If you specify a string variable, you can display or modify either all
      or only part of the string.  For example, given string "s", the entire
      string can be displayed or modified by specifying

        s

      as the variable name.  To view or modify only a part of the string, you
      can use one of the following formats:

        s[n]

        s[n:len]

        s[n..p]

      where n is a constant number indicating a starting position, len is
      a constant number indicating a length, and p is a constant number
      indicating an ending position.

      Note:  Local variables are only initialized when done so by the macro
      itself.  Thus, if you select a local variable to watch, or to display
      or modify, the value of the variable may be "garbage" until the
      variable is initialized by the macro.





DefaultExt

List of default file extensions.

Values:     STRING (maximum of 128 characters)

            A quoted string containing one or more extensions separated by
            spaces.

Default:    "ui s si c cpp h java pas inc bat prg txt doc html asm"

Notes:      When a filename, without an extension, is specified on the command
            line or in EditFile(), the editor attempts to load the file from
            disk.  If it does not exist, the editor attempts to match the
            filename with each of the default extensions.  Once a match is
            found, the process stops and the matched file is loaded. If a
            match is not found, the editor treats the filename you originally
            entered as a new file.

            To keep the editor from checking the disk for files from the
            default extension list, enter the filename with a trailing "."
            (period).

Affects:    EditFile(), EditThisFile()





DelAllBookMarks()

Removes all bookmarks.

Syntax:     DelAllBookMarks()

Returns:    Nothing.

Notes:      Removes all bookmarks that have been placed with the PlaceMark()
            command.  This is a simple and efficient way to remove all
            bookmarks.

See Also:   PlaceMark(), GotoMark(), DelBookMark(), GetBookMarkInfo()





DelAnyChar()

Deletes the character at the cursor position.

Syntax:     INTEGER DelAnyChar()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Unlike DelChar(), DelAnyChar() will join the next line with the
            current line when executed at or beyond the end of the current
            line.

See Also:   DelChar(), DelCharOrBlock(), DelAnyCharOrBlock(), BackSpace(),
            JoinLine()





DelAnyCharOrBlock()

If the cursor is in a marked block, the block is deleted. Otherwise, deletes
the character at the cursor position.

Syntax:     INTEGER DelAnyCharOrBlock()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Unlike DelCharOrBlock(), DelAnyCharOrBlock() will join the next
            line with the current line when executed at or beyond the end of
            the current line.

See Also:   DelAnyChar(), DelBlock(), DelChar(), DelCharOrBlock(),
            BackSpace(), JoinLine()





DelAutoLoadMacro()

Removes a Compiled Macro file from the list of macro files to be automatically
loaded on editor startup.

Syntax:     INTEGER DelAutoLoadMacro(STRING macro_name)

            • macro_name is the name of the macro file to be removed.  The
              name must be an exact match (not including case) for it to be
              removed from the list.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      The list of macro files to be loaded is maintained in the autoload
            file TSELOAD.DAT.  This file provides a simple, optional mechanism
            for automatically loading macro files at the beginning of each
            editing session.

            If TSELOAD.DAT is used, it is maintained in the editor
            load directory.  On startup, the editor loads any macro files
            found in this autoload file, using the LoadMacro() command.

See Also:   AddAutoLoadMacro(), EditAutoLoadList(), isAutoLoaded()





Delay()

Causes the editor to pause for the amount of time specified.

Syntax:     Delay(INTEGER duration)

            • duration is the number of 0.055 parts of a second that the
              editor should be idle.  (0.055 is about 1/18 of a second.)

Returns:    Nothing.

Notes:      The delay duration is accurate to within about 0.055 second.

Examples:

            Delay(36) // delay for approximately two seconds

See Also:   Alarm(), Sound()





DelBlock()

Deletes the marked block if it exists in the current file.

Syntax:     INTEGER DelBlock()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      DelBlock() will not delete a block outside the current file.

            If no block is marked in the current file or there was not enough
            memory to complete the operation, no action occurs and zero is
            returned.

            Deleted blocks are stored in the Deletion Buffer and can be
            retrieved with the UnDelete(), GlobalUnDelete(), and
            PasteUnDelete() commands.

            To delete a block without it being stored in the Deletion Buffer,
            use the KillBlock() command.  Alternatively, the KillMax variable
            may be set to 0, which is essentially what the KillBlock() command
            does.

Idioms:

            /********************************************************
              To delete a block WITHOUT it being stored in the
              Deletion Buffer, temporarily set the KillMax variable
              to 0, delete the block, and then restore KillMax to its
              previous value.
             ********************************************************/
            integer km = Set(KillMax, 0)
            DelBlock()
            Set(KillMax, km)

See Also:   UnDelete(), GlobalUnDelete(), isBlockInCurrFile(),
            isBlockMarked(), PasteUnDelete(), KillBlock(),
            DelAnyCharOrBlock(), DelCharOrBlock(),

            Variables:  KillMax, BlockId





DelBookMark()

Removes a specific bookmark.

Syntax:     DelBookMark(STRING bookmark_name)

            • bookmark_name is the single-character name (A through Z,
              case-insensitive) of the bookmark to remove.

Returns:    Nothing.

Notes:      This command is used to remove a specific bookmark placed with
            the PlaceMark() command.

Examples:

            // remove bookmark a
            DelBookMark("a")

See Also:   PlaceMark(), GotoMark(), DelAllBookMarks(), GetBookMarkInfo()





DelBufferVar()

Deletes the specified buffer variable.

Syntax:     INTEGER DelBufferVar(STRING buffer_var_name [, INTEGER buffer_id])

            • buffer_var_name is the name of the buffer variable to delete.

            • buffer_id is an optional buffer id, as returned by
              GetBufferId().

Returns:    Non-zero if buffer_var_name can be deleted (it must exist);
            otherwise, zero (FALSE).

Notes:      If buffer_id is not specified, the current buffer is assumed.

See Also:   ExistBufferVar(), GetBufferInt(), GetBufferStr(), SetBufferInt(),
            SetBufferStr()





DelChar()

Deletes the character at the cursor position.  Will not delete newline
characters.

Syntax:     INTEGER DelChar()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      DelChar() does not join lines.  Thus, it will not join the next
            line with the current line when executed at or beyond the end of
            the current line, and returns zero under these conditions.

            For a <Del> key definition that joins the next line with the
            current line, replace the <Del> key definition in TSE.UI (in the
            UI\ editor subdirectory) with:

            /********************************************************
             CurrChar() returns < 0 if the cursor is at or beyond
             the end of the current line.  This is used to determine
             whether to join the next line, or issue the normal
             DelChar() command.
             ********************************************************/
            proc mDelChar()
                if CurrChar() >= 0
                    DelChar()
                else
                    JoinLine()
                endif
            end

            <Del>   mDelChar()

See Also:   BackSpace(), DelCharOrBlock(), DelAnyCharOrBlock(), DelAnyChar(),
            JoinLine()





DelCharOrBlock()

If the cursor is in a marked block, the block is deleted. Otherwise, deletes
the character at the cursor position.  Will not delete newline characters.

Syntax:     INTEGER DelCharOrBlock()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      DelCharOrBlock() does not join lines.  Thus, it will not join
            the next line with the current line when executed at or beyond
            the end of the current line, and returns zero under these
            conditions.

            For a <Del> key definition that joins the next line with the
            current line, see the DelAnyCharOrBlock() command.

See Also:   DelAnyCharOrBlock(), DelBlock(), DelChar(), DelAnyChar(),
            BackSpace(), JoinLine()





DelGlobalVar()

Deletes the specified session global variable.

Syntax:     INTEGER DelGlobalVar(STRING var_name)

            • var_name is the name of the session global variable to
              delete.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      FALSE is returned if var_name does not exist.

Examples:

            DelGlobalVar("myvar")

See Also:   GetGlobalInt(), GetGlobalStr(), SetGlobalInt(),
            SetGlobalStr(), ExistGlobalVar()





DelHistory()

Deletes all history entries associated with a history number, and places the
history number back on the available history list.

Syntax:     DelHistory(INTEGER history_num)

            • history_num specifies the history to be removed.

Returns:    Nothing.

Notes:      history_num should be in the range 1..127, which constitutes the
            user history numbers.

            The pre-defined constant values (see AddHistoryStr()) that
            represent the built-in histories cannot be deleted.

            The AddHistoryStr() command contains detailed information about
            the use of history in the macro language.

See Also:   AddHistoryStr(), GetFreeHistory(), DelHistoryStr(),
            FindHistoryStr(), GetHistoryStr(), NumHistoryItems()





DelHistoryStr()

Deletes an item (string) from the History Buffer.

Syntax:     INTEGER DelHistoryStr(INTEGER history, INTEGER n)

            • history is an integer specifying the history list from which
              the item will be deleted.  history can be:

              • A pre-defined constant value representing one of the built-in
                histories.  See the AddHistoryStr() command for a listing
                of these constants.

              • A number in the range 1..127.

              • A number returned by GetFreeHistory(), which will be in the
                range 1..127.

            • n is the number, within the specified history list, of the
              history item to delete.  n should be in the range 1 through
              the value returned by NumHistoryItems(history), where 1
              represents the item added most recently, and higher numbers
              represent older items.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If the specified history list does not exist, or n is greater
            than the number of items that exist for that particular history
            list, then this command has no effect, and FALSE is returned.

Examples:

            //To delete an item such as "foo.bar" from history:
            DelHistoryStr(histno, FindHistoryStr("foo.bar", histno))

            // Prune history to specific number of items
            proc PruneHist(integer histno, integer num2keep)
                repeat
                until NOT DelHistoryStr(histno, num2keep + 1)
            end

See Also:   GetHistoryStr(), NumHistoryItems(), GetFreeHistory(),
            AddHistoryStr(), FindHistoryStr()

            Variables:  MaxHistoryPerList, PersistentHistory





DelLeftWord()

Deletes the word to the left of the cursor.

Syntax:     INTEGER DelLeftWord()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      The current value of the WordSet variable determines what the
            editor considers a word.

            DelLeftWord() deletes characters beginning with the character to
            the left of the cursor, and continues until a character that is
            not part of the current WordSet is encountered.  If the character
            to the left of the cursor is not part of the WordSet, only that
            character is deleted.

            This command joins the current line with the previous line when
            issued at column 1.  When issued at column 1 of the first line of
            the file, no action occurs and zero is returned.

See Also:   DelRightWord()

            Variables:  WordSet





DelLine()

Deletes the current line.

Syntax:     INTEGER DelLine()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            Upon deletion of the current line, the cursor is placed on the
            following line with the cursor column remaining unchanged.

            The deleted line is stored in the Deletion Buffer and can be
            retrieved via the UnDelete() or GlobalUnDelete() commands.

            To delete a line without saving the deleted line in the Deletion
            Buffer, use the KillLine() command, or use the following idiom.

Idioms:

            /********************************************************
              To delete a line WITHOUT it being stored in the
              Deletion Buffer, temporarily set the KillMax variable
              to 0, delete the line, and then restore KillMax to its
              previous value.
             ********************************************************/
            integer km = Set(KillMax, 0)
            DelLine()
            Set(KillMax, km)

See Also:   KillLine(), AddLine(), InsertLine(), UnDelete(), GlobalUnDelete()

            Variables:  KillMax





DelRightWord()

Deletes the word to the right of the cursor.

Syntax:     INTEGER DelRightWord()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      The current value of the WordSet variable determines what the
            editor considers a word.

            DelRightWord() deletes characters beginning with the character at
            the cursor position, and continues until a character that is not
            part of the current WordSet is encountered.  If the character at
            the cursor position is not in the WordSet, only that character is
            deleted.

            This command joins lines when issued at or beyond the end of the
            current line.  When issued at the end of the last line of the
            file, no action occurs and zero is returned.

            The deleted text is stored in the Deletion Buffer, and can be
            retrieved via the UnDelete() or GlobalUnDelete() commands.

See Also:   DelLeftWord(), UnDelete(), GlobalUnDelete()

            Variables:  WordSet





DelStr()

Deletes specified portions of a string variable.

Syntax:     STRING DelStr(STRING s, INTEGER p, INTEGER len)

            • s is the string from which to delete.

            • p is the position from which to start deleting.

            • len is the number of characters to delete.

Returns:    The new string with the specified portion deleted.

Notes:      If p is out of range, or len is less than or equal to 0,
            nothing is deleted from s.

Examples:

            string s[80] = "A rose by any other name"
            s = DelStr(s, 15, 6)    // s is now "A rose by any name"
            s = DelStr(s, 7, 12)    // s is now "A rose"
            s = DelStr(s, 1, 2)     // s is now "rose"

See Also:   InsStr(), SubStr(), Pos(), LeftStr(), RightStr(),
            StrCount(), StrFind(), StrReplace()





DelToEol()

Deletes the text from the cursor position to the end of the current line.

Syntax:     INTEGER DelToEol()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            Zero is returned if this command is executed when the cursor is at
            or past the end of the current line.

            The character at the cursor position is included with the text
            that is deleted.

            This command does not cause lines to be joined.

            The deleted text is stored in the Deletion Buffer, and can be
            retrieved via the UnDelete() or GlobalUnDelete() commands.

            To delete text without placing the deleted text in the Deletion
            Buffer, use the KillToEol() command.

See Also:   KillToEol(), DelChar(), DelLine(), UnDelete(), GlobalUnDelete()

            Variables:  KillMax





DelWindow()

Deletes an adjacent editing window.

Syntax:     INTEGER DelWindow()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If more than two editing windows are open and non-zoomed, this
            command prompts for the window to delete, which must be adjacent
            to the current window.  The window to be deleted is indicated by
            pressing the cursor key that "points" to that window.  If exactly
            two windows are open and non-zoomed, this command does not prompt;
            it deletes the non-current window.

            When a window is deleted, windows adjacent to the deleted window
            grow to fill in the empty space.

            This command affects only windows created by HWindow() and
            VWindow(), and not those created by the video output commands.

            Zero is returned if <Escape> is pressed at the "Window to delete:"
            prompt, if there is no window in the direction indicated, there is
            only one window, or the window is zoomed.

See Also:   CloseWindow(), HWindow(), VWindow(), OneWindow(), ZoomWindow()





DetabOnLoad

If on, tabs are converted to the appropriate number of spaces when a file is
loaded into the editor.

Values:     BOOLEAN

Default:    OFF

Notes:      Tabs are expanded based on the value of the TabWidth editor
            variable.

See Also:   EntabOnSave, TabWidth





Disable()

Disables a previously enabled set of key definitions.

Syntax:     Disable(KEYDEF keydef_name)

            • keydef_name is the name of the keydef to disable.

Returns:    Nothing.

Notes:      Once a keydef has been enabled via Enable(keydef_name), the
            keydef will remain in effect until Disable(keydef_name) is
            called.

            For more information on the keydef identifier, see "Keydef"
            and "Process() and Keydefs" in the chapter on
            "Using Macro Language Features."

Examples:

            See the Process() command for an example.

See Also:   Enable(), Process()





DisplayBoxed

Determines whether the editor should display a full border around the entire
screen, so that each window on the screen (including a single window) is
fully "boxed."

Values:     INTEGER

            • 0 - do not "box" the entire display

            • 1 - only "box" the entire display if the mouse is enabled and
              present

            • 2 - always "box" the entire display

Default:    1

See Also:   MouseEnabled





DisplayMode()

Sets or queries the current display mode for the current buffer.

Syntax:     INTEGER DisplayMode([INTEGER mode])

            • mode is the optional display mode to set.  Supported values
              for mode are:

              • _DISPLAY_TEXT_ places the screen display in standard display
                mode.

              • _DISPLAY_HEX_ places the screen display in Hex display mode.

              • _DISPLAY_PICKFILE_ places the screen display in the PickFile
                display mode.

Returns:    The display mode in effect when this command is invoked.

Notes:      Displaymode() only affects the current buffer.

            When Hex mode is enabled, each line is displayed in both text and
            hexadecimal format.  In Hex mode, the hexadecimal values are
            displayed on the right, while the text is displayed on the left.
            (See the HexEdit() command for information on how to set ON
            hex-editing mode, to allow the user to enter or modify the
            hexadecimal format of the data on the right.)

            Activating Hex mode does not place the file in Binary mode, but
            rather simply changes the view from text to hexadecimal.  To place
            a file in Binary mode, it must be loaded in Binary mode using the
            -b switch, or by using the BinaryMode() command.

            PickFile display mode is only valid for files in which the data
            was generated with the BuildPickBufferEx() command.  The
            PickFile() command uses this display mode.

Examples:

            // Toggle between Hex and text display modes:
            DisplayMode(iif(DisplayMode() == _DISPLAY_TEXT_,
                    _DISPLAY_HEX_, _DISPLAY_TEXT_))

See Also:   BinaryMode(), EditFile(), EditThisFile(),BuildPickBufferEx(),
            PickFile(), HexEdit()





DistanceToTab()

Returns the distance between the current cursor position and the next or
previous tab stop.

Syntax:     INTEGER DistanceToTab([INTEGER right])

            • right is an optional integer that defaults to zero.  If
              right has a non-zero value, the distance to the next tab stop
              is computed.  If right has a value of zero, the distance to
              the previous tab stop is computed.

Returns:    The distance to the next or previous tab stop.

Notes:      The distance from the current cursor location to the next or
            previous tab stop is based on the current setting of the TabType
            and TabWidth variables.

Examples:

            One usage for this command is to create tabbing commands that are
            only cursor movement commands, even in insert mode.

            proc mGotoNextTabStop()
                GotoColumn(CurrCol() + DistanceToTab(1))
            end

            proc mGotoPreviousTabStop()
                GotoColumn(CurrCol() - DistanceToTab())
            end

            <Tab>       mGotoNextTabStop()
            <Shift Tab> mGotoPreviousTabStop()

See Also:   Variables:  TabType, TabWidth, VarTabs





Dos()

Passes a command to the operating system for execution.

Syntax:     INTEGER Dos([STRING cmdline [, INTEGER flag]])

            • cmdline is the optional command line passed to the operating
              system, in order to execute an external command from within the
              editor.  If omitted, the editor will prompt for the command to
              execute.

            • flag is an optional integer that determines how the Dos()
              command operates.  If not specified, _DEFAULT_ is used.
              Supported values for flag are:

              • _DEFAULT_ causes the screen to be cleared and the command
                issued.  After completion, the editor prompts with "Press a
                key to continue...".  Once a key is pressed, the editor's
                screen is restored.

              • _DONT_CLEAR_ causes the command to be issued without the
                screen being cleared.  After completion, control returns
                immediately to the editor.  The editor does not issue the
                "Press a key to continue..." prompt, and the editor's screen
                is not restored.  This setting is useful for piping the
                command's output, or when the command itself restores the
                application screen after completion.

              • _DONT_PROMPT_ causes the screen to be cleared and the
                command issued.  After completion, control returns immediately
                to the editor, and the editor's screen is restored.  This
                option differs from _DEFAULT_ (above) in that the editor
                does not issue the "Press a key to continue..." prompt.

              • _DONT_WAIT_ causes the editor not to wait on the child
                command, in other words, the child program runs simultaneously
                with the editor.

              • _RETURN_CODE_ causes the Dos() command to process in such a
                way as to make the return code from the command passed to the
                operating system available via the DosIOResult() command.

              • _RUN_DETACHED_ causes cmdline to be run as a detached
                process.

              • _TEE_OUTPUT_ is useful when the external command's output
                is being redirected to another file.  Using the _TEE_OUTPUT_
                flag will also place that redirected output on the screen.
                This is primarily useful for long-running commands, in order
                to give the user feedback as to the progression of the
                command.  Good examples would be a long MAKE, or compiling
                with a very slow compiler.  The return code of the command
                passed to the operating system is available via the
                DosIOResult() command.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.


            This command includes a history list of previous entries passed to
            it.  See AddHistoryStr() for additional information.

Examples:

            /********************************************************
              Example 1

              The user is prompted for a command.
             ********************************************************/

            Dos()

            /********************************************************
              Example 2

              Issue the DIR command.  The screen will be cleared, the
              command executed, and after completion, the editor will
              issue a "continue" prompt.
             ********************************************************/

            Dos("dir *.bat")

            /********************************************************
              Example 3

              Issue the dir command, and pipe the output to the file
              "save.dat".  The editor's screen will not be cleared,
              and control will return to the editor without a
              "continue" prompt being issued.
             ********************************************************/

            Dos("dir *.bak >save.dat", _DONT_CLEAR_)

            /********************************************************
              Example 4

              Invoke the CC program, passing it the name of the
              currently edited file (which is saved first, so that the
              disk copy and what is in memory are the same), and pipe
              the output to the file "results".
             ********************************************************/

            SaveFile()
            Dos("CC " + CurrFilename() + " >results", _DONT_CLEAR_)

            /********************************************************
              Example 5

              Invoke the CC program, passing it the name of the
              currently edited file (which is saved first, so that the
              disk copy and what is in memory are the same), and pipe
              the output to the file "results".  At the same time, any
              piped output is also displayed on the screen.
             ********************************************************/

            SaveFile()
            Dos("CC " + CurrFilename() + " >results",
                _DONT_PROMPT_ | _TEE_OUTPUT_)

See Also:   lDos(), Shell(), AddHistoryStr(), DosIOResult(), StartPgm()





DosCmdLine

The command line passed to the editor.  For use within macros.

Values:     STRING (maximum of 128 characters)

Default:    The command-line string.

Limits:     Setting this has an effect only in the installed user-interface
            WhenLoaded macro.

Notes:      This variable can be used to add custom command-line arguments to
            the editor, or to peek at the command line passed to the editor
            and take user-determined appropriate action.

            In the installed user-interface file, the WhenLoaded() macro can
            access the command line (before the editor processes it).  This
            allows the WhenLoaded() macro to change the command line that the
            editor actually processes.  For example, additional command-line
            options could be added, a default filename could be loaded, etc.

            Note, however, that if the "Augment LoadDir" (-i) command-line
            option is specified, the editor processes this parameter before
            calling the WhenLoaded macro.


See Also:   MacroCmdLine





DosIOResult()

Returns result information about the last-executed Dos() command.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER DosIOResult()

Returns:    The return code of the external command run by the last-executed
            Dos() command, along with the return code of the last-executed
            Dos() command itself.

Notes:      For this command to work, either _RETURN_CODE_ or _TEE_OUTPUT_
            must have been specified as a flag value in the last-executed
            Dos() command.

            When this command is executed, the two return codes are placed in
            the lower 16 bits of the returned (32-bit) integer.  The return
            code of the relevant external command is placed in the upper byte
            (of the lower 16 bits); the return code of the Dos() command is
            placed in the lower byte (of the lower 16 bits).

Examples:

            proc CheckDosIOResult()
                integer rc

                Dos("pkzip", _RETURN_CODE_)
                rc = DosIOResult()
                Warn("Return code of pkzip: ",
                        HiByte(rc),
                        " Return from Dos() command: ",
                        LoByte(rc))
            end

See Also:   Dos()





Down()

Moves the cursor down one line in the current file.  The cursor column does
not change.

Syntax:     INTEGER Down()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command returns zero if the cursor is on the last line of the
            file.

            If the cursor is on the last line of the current window, the text
            will scroll up one line.

Idioms:

            /********************************************************
              To perform a given operation on every line of the
              current file, code similar to the following can be used.
             ********************************************************/
            BegFile()
            repeat
                // some operation
            until not Down()

See Also:   Up(), RollDown(), ScrollDown()





DrawBox()

Draws a box around the current video output window.

Syntax:     DrawBox(INTEGER boxtype, INTEGER attribute)

            • boxtype is the box-drawing character that will be used.

            • attribute is the color to use for the box.

            Supported values for boxtype are:

            • 1 - single-line characters

            • 2 - double-line top, single-line side characters

            • 3 - double-line side, single-line top characters

            • 4 - double-line characters

            • 5 - small block characters

            • 6 - large block characters

Returns:    Nothing.

Notes:      This is a video output command.  It has no effect on the actual
            text in the buffer.  It only affects what is displayed on the
            screen.

            For more information on video output commands, see
            "Video Output Commands" in the chapter on
            "Using Macro Language Features."

See Also:   Color(), Window()





Drawing Lines in the Text

The editor offers a customizable means for drawing lines and boxes, which can
be useful for creating diagrams, charts, and tables.  For this, LineDrawing
mode is provided.  When LineDrawing mode is ON, the cursor movement keys
(<CursorUp>, <CursorDown>, <CursorLeft>, and <CursorRight>) draw lines on the
screen as the cursor moves.  You can select the style used to draw lines from
a predefined set, or you can choose your own line-drawing character.

To toggle LineDrawing mode ON and OFF, choose "Line Drawing" under the Util
Menu.  When this mode is ON, an "L" displays on the StatusLine.

To specify the LineDrawing style, select "Line Type" under the Util Menu, and
choose one of the following:

       Selection                 Line-Drawing Characters
    ________________        _________________________________

    Single       ┌─┐        Single-line top and side

    Double top   ╒═╕        Double-line top, single-line side

    Double side  ╓─╖        Double-line side, single-line top

    Double both  ╔═╗        Double-line both top and side

    ASCII        +-|        ASCII top and side

    Eraser                  Blank

    User-defined [▪]        User-defined top and side


To select a style, move the cursor bar to the desired style and press <Enter>,
or simply press the quick-key associated with the desired style.  If you
select the user-defined style, you then input the character you wish to use
and press <Enter> again.  (The numeric keypad can be used to input the decimal
value of a character that is not directly available from the keyboard.  For
more information on using the numeric keypad to input characters, see the
Tip under "Commands to Add Text" in the chapter on
"Manipulating Text.")


  ┌──────────────────────────────── Tip ─────────────────────────────────┐
  │  The first four line-drawing styles listed above, along with the     │
  │  standard user-defined character, use graphics characters.  To print │
  │  these characters, your printer must be set to a graphics mode.      │
  └──────────────────────────────────────────────────────────────────────┘





DupLine()

Makes a copy of the current line and adds it immediately following the current
line.

Syntax:     INTEGER DupLine()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command fails if there is not enough memory to successfully
            complete the operation.

            The newly-added line becomes the current line.  The cursor column
            does not change.

See Also:   AddLine(), InsertLine()





EditAutoLoadList()

Allows interactive editing (adding and deleting) of the list of macro files to
be automatically loaded on editor startup.

Syntax:     EditAutoLoadList()

Returns:    Nothing.

Notes:      The list of macro files to be loaded is maintained in the autoload
            file TSELOAD.DAT.  This file provides a simple, optional mechanism
            for automatically loading macro files at the beginning of each
            editing session.

            If TSELOAD.DAT is used, it is maintained in the editor
            load directory.  On startup, the editor loads any macro files
            found in this autoload file, using the LoadMacro() command.

See Also:   AddAutoLoadMacro(), DelAutoLoadMacro(), isAutoLoaded()





EditBuffer()

A replacement for the common sequence "CreateBuffer() ... InsertFile()",
typically to create a system buffer and load a file into it without
causing any hooks to be called.

Syntax:     INTEGER EditBuffer(STRING fn [, INTEGER type [, INTEGER reclen]])

            • fn is the name of the file to load into the newly-created
              temporary buffer.

            • type is an optional integer parameter that specifies the type
              of buffer to be created.  If not specified, _SYSTEM_ is used.
              Supported values for type are:

              • _NORMAL_ causes the buffer to have no special attributes
                associated with it.  Buffers created by the EditFile()
                command have this buffer type.

              • _HIDDEN_ simply causes the buffer to not show up in the list
                of files, and makes the buffer inaccessible via the
                NextFile() and PrevFile() commands.  The PickList of loaded
                macros (optionally displayed by the ExecMacro() command) is
                stored in a _HIDDEN_ buffer.

              • _SYSTEM_ causes the buffer to be hidden, and places the
                buffer in a raw mode, so that trailing spaces are never
                removed, and tabs are treated as a normal character.  Buffers
                created with CreateTempBuffer() have this buffer type.  It is
                strongly recommended that system buffers not be used for
                interactive editing.

            • reclen is an optional integer parameter.  If passed and
              non-zero, the binary record length of the buffer is set to
              reclen.

Returns:    The non-zero id number of the newly-created buffer, if successful;
            otherwise, zero (FALSE).

Notes:      This command creates a buffer of the specified type, with
            optional reclen, and loads fn into it.  No hooks are called.
            The buffer is unnamed.  The newly created buffer becomes the
            current buffer.

            This a common operation performed by macros, that save and
            restore configuration or other types of information.  It performs
            the following sequence of instructions:

            if CreateBuffer("", type)
                BinaryMode(reclen)
                PushBlock()
                InsertFile(fn, _DONT_PROMPT_)
                PopBlock()
            endif

See Also:   CreateBuffer(), CreateTempBuffer(), EditFile(), EditThisFile(),
            InsertFile(), LoadBuffer()





EditFile()

Loads a file into the editor and makes it the current file.

Syntax:     INTEGER EditFile([STRING fn [STRING fn]... [, INTEGER flag]])

            • fn is an optional string expression specifying the file(s) to
              be loaded (and may include command-line options).

              fn can include long filenames and UNC network paths.  If a
              filename includes leading or embedded spaces, that filename
              must be enclosed in quotes.

            • flag is an optional integer that affects the operation of
              EditFile().  Supported values for flag are:

              • _DONT_PROMPT_ specifies that EditFile() should not display
                any warning or informational messages if a problem occurs.

              • _DONT_LOAD_ specifies that EditFile() should not actually
                load any files, but simply place them in the editor's Ring of
                files.  The file can later be loaded by switching to it; or
                by calling EditFile() again, with the appropriate filename,
                and without the _DONT_LOAD_ flag.

              • _FROM_CMDLINE_ specifies that EditFile() should perform as if
                it were called from the command line.  The editor uses this
                to determine whether to load or to prompt for ambiguous
                filenames, as determined by the LoadWildFromDos and
                LoadWildFromInside variables.  (See the WhenLoaded() macro
                in the TSE.UI user-interface file (located in the UI\ editor
                subdirectory) for examples of using this value with the
                EditFile() command.)

Returns:    The non-zero id number of the file just edited if successful;
            otherwise, zero (FALSE).

Notes:      fn can also include command-line options, if desired.  (For more
            Information on available command-line options, see
            "Command-Line Options" in the chapter on "Starting the Editor"
            in the User's Guide.)

            If no filename is specified, the editor will prompt for a
            filename.

            If an ambiguous filename is specified, the editor either pops up a
            list of all matching files from which the user can select a file,
            or automatically selects all matching files, depending on the
            setting of the LoadWildFromInside variable.  An ambiguous filename
            is indicated by either the presence of the wildcard characters (?
            and *), by a blank or empty filename string, by a string ending in
            the "\" character, or by using the "Search SubDirs" (-s)
            command-line option.  (For more information on the "Search
            SubDirs" command-line option, see "Command-Line Options" in the
            chapter on "Starting the Editor" in the User's Guide.)

            This command also supports filename completion.  This feature is
            invoked by typing a partial filename at the "File(s) to edit:"
            prompt, and then pressing the <Tab> key.  The editor will add *.*,
            .*, or * as appropriate to complete the filename specification.  A
            list of all matching files will be presented from which the user
            can select the appropriate file.

            To build the filename or list of files to process, the editor
            first determines the complete path.  If a drive is not specified,
            the current drive is used; if a path is not specified, the current
            path is used.  For example:

            • If the current drive/path is C:\WORK\STUFF and the user issues
              EditFile("new.doc"), then the editor will expand this to
              c:\work\stuff\new.doc.

            Once a particular file to be edited has been selected, the editor
            attempts to match the complete filename with a file already in the
            Ring, as follows:

            • If a match is found, that file becomes the current file and the
              _ON_CHANGING_FILES_ event is called, if it exists.

            • If no match is found, the editor creates a new entry in the
              Ring.  If the file exists on disk, it is read into memory.
              That file becomes the current file.  If the _ON_FIRST_EDIT_
              event exists, it is called.  If the _ON_CHANGING_FILES_ event
              exists, it is also called.  (Note that if _DONT_LOAD_ is
              specified, the file is not read into memory and neither of the
              indicated events are called.)

            When multiple filenames are selected, the editor repeats the above
            process.  However, it only loads into memory the file derived from
            the first fn entry, and makes that file the current file.  Each
            of the other selected files is added to the Ring, but is not
            loaded into memory until the user switches to it and makes it the
            current file.

            If a filename without an extension is passed to EditFile(), and
            that file does not exist, the editor will try to find an existing
            file by appending any default extensions that the user has
            specified via IConfig.

            This command includes a history list of previous entries passed to
            it.  See AddHistoryStr() for additional information.

            The description of the Hook() command contains information
            concerning the _ON_CHANGING_FILES_ and _ON_FIRST_EDIT_ events.

            EditFile() and EditThisFile() work similarly when filenames are
            quoted.

Examples:

            // Edit a file named "my.fle"
            EditFile("my.fle")

            // Edit a file, whose name is stored in the string s
            EditFile(s)

            // Edit 3 files, named "file1", "file2", and "file3"
            EditFile("file1 file2 file3")

See Also:   EditThisFile(), CreateBuffer(), CreateTempBuffer(), PickFile(),
            AddHistoryStr(), Hook(), UnHook(), BufferType(), AddFileToRing(),
            ReplaceFile(), NewFile()

            Variables:  LoadWildFromDOS, LoadWildFromInside, UseCommonDialogs





Editing Modes

A number of flexible editing modes are provided to control the way certain
commands or keys operate, or to affect the manner in which text is displayed
on the screen.  These modes not only allow you to further tailor the editor
to your particular editing style, but also help you to increase your
productivity at the keyboard.

The editing modes discussed in this chapter are:

    • Insert modeWordWrap modeAutoIndent modeTemplate modeSyntaxHilite modeSmartIndent modeC mode


To use Insert, WordWrap, AutoIndent, and Template modes, you must set the mode
to an active state (by setting it ON, or setting it to another applicable
state).  If you set the mode to a non-active state (by setting it OFF), it
will not affect editing.  Options are provided for each of these modes to
interactively toggle them between active and non-active states.  Multiple
modes can be in effect at the same time.  Be sure to note the effects that
these modes have on certain editing commands.

SyntaxHilite mode is a special editing display mode that causes certain
portions of the text to be distinctly colorized, according to the filename
extension.

SmartIndent mode and C mode are special programming-language modes, and are
automatically activated for files with certain filename extensions, if
AutoIndent mode is set appropriately.


The following chapters present additional editing modes.

The chapter on "Loading, Processing, and Saving Files" discusses Hex and
Binary modes, which provide alternate modes for editing files.

The chapter on "Special Commands and Features" explains how to use LineDrawing
mode to draw lines and create boxes.

The chapter on "Creating and Using Macros" describes RecordKeyMacro mode,
which allows you to create Keyboard Macros.





Editor Commands

To effectively use this chapter of the Macro Reference Guide, you need a
working knowledge of the SemWare Applications Language (SAL).  Detailed
information about SAL is provided in the first five chapters of the
Macro Reference Guide.  Descriptions of the built-in editor variables
available in SAL are provided in the chapter on "Editor Variables."

This chapter provides information about the commands that comprise the native
command set for SAL.  These native commands can be used to write macros to
customize existing commands or create additional editing commands.

The commands presented in this chapter are distinct from the "editing
commands" described in the User's Guide.  The editing commands are
implemented using native commands; however, not every editing command is an
actual native command.  The editing commands available in the editor are
implemented using the native commands, in the following ways:

    Many editing commands are, indeed, implemented as actual native commands.
    For example, AddLine is implemented as the unmodified native command
    AddLine(), and EditFile is implemented as the unmodified native command
    EditFile().

    A few editing commands are implemented by simply passing a specific
    parameter to a native command.  An example of this is the GotoWindowNumber
    commands.  These are implemented as a series of commands using the native
    command GotoWindow(n), where "n" is each of the numbers 1 through 9.  The
    result is nine GotoWindowNumber commands to allow you to go to any one of
    nine windows, with a single keystroke.

    Several other editing commands are implemented as macros that merely
    enhance the behavior of a native command.  The BackSpace editing command
    is implemented as the macro mBackSpace(), which enhances the native
    BackSpace() command to accommodate various editing modes.  The CReturn
    editing command is implemented as the macro mCReturn(), which enhances the
    native CReturn() command to recognize "smart" indenting for several
    programming languages.

    A number of editing commands are implemented as simple or complex macros
    that provide additional features not included in the native commands
    themselves.  The CompressView command is provided through the
    mCompressView() macro, which takes advantage of a number of native
    commands to provide the ability to list all lines that match a
    user-defined string.  The CenterLine command is implemented via the
    mCenterLine() macro, which allows you to center a line or block of text.

To distinguish editing commands from the native or macro commands by which
editing commands are implemented, slightly different naming conventions are
used in the editor documentation.  The editing command names (used
predominantly in the User's Guide) are notated merely as a descriptive name,
such as "Find" or "CompressView".  The native and macro command names (used
predominantly in the Macro Reference Guide) are notated as a descriptive
name followed by "()", such as "Find()" or "mCompressView()".

Further, to distinguish a macro command implementation from a native command,
the macro command name generally includes a prefix of "m" (for example,
"mCompressView()").  And for those macro commands that are just enhanced
versions of a native command, "m" is prefixed to the actual native command
name that has been enhanced (such as, "mBackSpace()" or "mCReturn()").

In this chapter, descriptions are given for each of the native commands in
the editor.  A command description indicates the command name, a summary
definition, the command syntax, the return type, and the return value(s).
Additional information provided for many native commands includes usage notes,
examples, and related commands.

NOTE:   This chapter is NOT intended to provide descriptions of the editing
        commands as implemented in the editor, or of any enhanced or
        additional macro commands.

        An asterisk (*) following a command name in this chapter indicates
        that an editing command by the same name, has been implemented via an
        enhanced macro in the standard user-interface file, TSE.UI (located in
        the UI\ editor subdirectory).  Those editing commands do not behave
        exactly as the native commands documented in this chapter.

        For a cross-reference list of the editing commands, and the native or
        macro commands by which the editing commands are implemented, see
        "Appendix B:  Command Implementation."


Syntax
──────

The format for the syntax of each command in this chapter is:

    RETURN_TYPE CommandName(PARM_TYPE identifier [,PARM_TYPE identifier])

where:

    • RETURN_TYPE is the type of Return Value (INTEGER or STRING) associated
      with the command.  Some commands do not return a value; therefore, the
      syntax for those commands does not indicate a RETURN_TYPE.

    • CommandName is the name of the command.

    • PARM_TYPE is the parameter type of the identifier which follows.  Valid
      parameter types are:

      • INTEGER (including VAR INTEGER)

        INTEGER is a whole number (... -2, -1, 0, 1, 2, 3, ...), in the
        range -2,147,483,648 (the MININT value in the editor) through
        +2,147,483,647 (the MAXINT value in the editor).

        A parameter denoted specifically as INTEGER can be coded as an
        integer constant (that is, an actual numeric value, such as 123),
        as an integer expression (such as, i * 7 + b), or as an integer
        variable name (such as line_number).

        Integer constants may be specified as binary, decimal, or
        hexadecimal values.  (For more information, see "Numbers" in the
        chapter on "Macro Language Syntax".)

        A parameter denoted specifically as VAR INTEGER must be coded as an
        integer variable name.  Such parameters may possibly be altered by
        the command.

      • STRING (including CONSTANT STRING and VAR STRING)

        STRING is a sequence of up to 255 characters, enclosed within single
        ('') or double ("") quotes.  It can include any alphabetic, numeric,
        or other characters.

        A parameter denoted specifically as STRING can be coded as a
        constant string (that is, an actual string value, such as
        "ABC123"), as a string expression (such as, s + "abc" + s2,
        where s and s2 are string variables, and "abc" is a constant
        string), or as a string variable name (such as saved_wordset).

        A parameter denoted specifically as CONSTANT STRING must be coded as
        an actual literal string value.

        A parameter denoted specifically as VAR STRING must be coded as a
        string variable name.  Such parameters may possibly be altered by
        the command.

      • PROCEDURE

        PROCEDURE is the name of another macro that is to be called by the
        command.

      • MENU

        MENU is the name of a pull-down or pop-up menu, or a menubar, that
        is to be displayed by the command.

      • KEYDEF

        KEYDEF is the name of a key definition (or set of key definitions)
        that may be enabled or disabled by the command.

    • identifier is the descriptive name of the parameter.

    • Parameters within square brackets [] are optional.

For example:

    INTEGER InsertText(STRING s [, INTEGER flag])

        This command returns an integer, requires one parameter (a string),
        and accepts an optional parameter (an integer).

    INTEGER Ask(STRING prompt, VAR STRING reply [, INTEGER history_number])

        This command returns an integer and requires two parameters, the first
        being a string and the second being a string variable.  It also has an
        optional third parameter, an integer.


Return Values
─────────────

Generally, INTEGER commands return non-zero for success, and zero (FALSE) for
failure.  To test a command's return value for success or failure, use the
following style code:

            if command() <> 0   // if command is successful (non-zero)
                [statements]
            endif

To loop while a command is successful, use the following style code:

            while command() <> 0 // while command result is non-zero
                [statements]
            endwhile

Note that not all commands return non-zero for success and zero for failure.


String Length
─────────────

The editor's maximum string length is 255 characters.  This applies to strings
that are input to a command, as well as strings that are returned by a
command.  Note that the maximum string length and the editor's maximum line
length are not related.


Optional Parameters
───────────────────

All parameters are required unless they are indicated as optional by enclosing
them in brackets [].  Some commands with an optional parameter prompt for
input when that parameter is omitted.  Other commands with optional parameters
use a default value when the parameter is omitted.  These are identified in
the command description.


Examples
────────

In the examples provided in this chapter, unless declared otherwise, "i", "j",
and "len" are integer variables; "fn" is a string variable used for filenames;
and "s" is a string variable.





Editor Files and Directories

The files on The SemWare Editor Professional distribution diskette(s) are
in compressed format.  To install the editor, you must run the menu-driven
installation routine.  This routine decompresses and installs all or selected
files onto your system.

By default, the installation routine creates the editor "load directory" with
the name \TSEPro, off the root directory of the drive you are logged onto
during installation.  The following files are placed in the editor load
directory:

    g32.exe         The SemWare Editor Professional (TSE Pro) program.
                    (if installing the GUI version)
    or

    e32.exe         The SemWare Editor Professional/32 (TSE Pro/32) program.
                    (if installing the Console version)


                    Once configured, the above (as appropriate) is the only
                    file needed to run the basic editor.

    sc32.exe        SAL Compiler program, used to compile macros that you
                    write using the SemWare Applications Language (SAL).

    read.me         Supplemental information about the editor, including
                    changes or additions not covered in the printed
                    documentation.

    *.dat           Various files in which the editor stores configuration
                    information.

    *.exe, *.com    Various utility programs called by the editor.

    *.dll           Various utility subroutines called by the editor.


Additional files provide further functionality in the editor.  If installed,
the following subdirectories are created, and the indicated files are copied
into them:

    \TSEPro\mac\    Compiled Macro (.mac) files supplied with the editor
                    (including iconfig.mac, the Interactive Configuration
                    macro file) are placed in this subdirectory.

                    Also included are source (.s) files for many of the macro
                    files; DLL (.dll) files required to compile certain macro
                    files; and data (.dat) files required by certain macro
                    files.

    \TSEPro\ui\     Source files for the user-interface macro files supplied
                    with the editor are placed in this subdirectory.

                    Several user-interface emulations are provided, including
                    the standard editor emulation (tse.ui), a TSE Jr.
                    emulation (tsejr.ui), a Brief(R) emulation (brief.ui), a
                    WordStar(R) emulation (ws.ui), and a Windows compliant
                    User Interface (win.ui).

    \TSEPro\doc\    Supplemental documentation files are placed in this
                    subdirectory.  Review these files for information about
                    the editor.

    \TSEPro\spell\  SpellCheck word-list (.lex) files are placed in this
                    subdirectory.

    \TSEPro\help\   HelpSystem (.hlp) files are placed in this subdirectory.

    \TSEPro\synhi\  Syntax highlighting files (.syn) are placed in this
                    subdirectory.


If you wish to install the editor in a different directory than that
indicated above, you can specify an alternate drive and/or directory during
installation.  You can also omit certain of the additional files from the
installation process.

The installation routine lets you select which sets of user-interface
emulation files are copied onto your machine.  It also lets you select the
particular user interface with which you want to configure the editor when it
is initially installed.  You can select the standard SemWare Editor
Professional user interface, or you can choose one of the alternate
user-interface emulations.

Once the editor is installed, you can use it to view the READ.ME file, located
in the editor load directory.  This will help acquaint you with the editor
and provide you with useful information.

To run the editor from any drive and directory, modify the PATH statement in
your AUTOEXEC.BAT file to include the editor drive and directory.  After you
update AUTOEXEC.BAT, reboot your machine so the modified PATH will be
effective. (See your system manual for information on modifying the PATH
statement.)

NOTE:   The installation routine creates ONLY the editor load directory, and
        subdirectories under it.  No other directories, and no hidden files,
        are created or modified by the installation routine.





Editor Startup Processing

When the editor is started, the following events occur in the order shown:

    1.  The editor checks to see if a WhenLoaded macro is defined in the
        installed user-interface file.  If present, the WhenLoaded macro is
        executed, and events 2 - 5 (below) are performed by the WhenLoaded
        macro.

    2.  The editor searches for a Compiled Macro file named TSESTART.MAC.  It
        searches directories according to the "macro file search order"
        described under "Creating and Using Compiled Macros" in the chapter on
        "Creating and Using Macros."  If a TSEStart macro file is found, it is
        then processed.

        The TSEStart macro file is simply a user-defined external Compiled
        Macro file that the editor attempts to run each time the editor is
        started.  When the editor processes the TSEStart macro file, it loads
        the macro file, and executes the WhenLoaded and Main macros in the
        file (if present).  This feature can be useful for specifying such
        startup actions as loading custom macros, and initially setting
        variables and editing modes.

        The TSEStart macro feature also provides an alternate method for
        creating versions of the editor that behave differently depending on
        the directory from which the editor is started.  You can include a
        unique TSEStart macro file in the desired directories.  The editor
        will process the TSEStart macro file located in the directory where
        you start the editor, and perform the functions specified.

    3.  The editor searches for a macro autoload file by the name of
        TSELOAD.DAT.  It searches for this file only in the editor
        load directory.  If this file is found, the editor loads each macro
        file specified in the autoload file, and executes the WhenLoaded macro
        (if any) located in each macro file.

        The purpose of the autoload file is to provide you with a simple
        means for automatically loading your own set of external Compiled
        Macro files, each time the editor is started.  To add to or delete
        from the list of macro files in the autoload file, use the
        AutoLoadList command.

    4.  The editor sets the current video mode, using the startup video
        mode.

    5.  The editor processes the filenames and options included on the
        command line, and loads the initial file (if one is included).  If
        the command line does not contain any options or filenames, the
        editor checks the setting of the StartupFlags variable to determine
        the appropriate startup action to take (as described under
        "Starting the Editor with No Command-Line Parameters" earlier in
        this chapter.)

    6.  Once the WhenLoaded macro (if present) is complete, the editor then
        checks to see if a Main macro is defined in the installed
        user-interface file.  If present, that Main macro is executed.

    7.  The _ON_EDITOR_STARTUP_ event is called.

    8.  The editor loads and/or executes any external macro files specified
        by the "Load Macro" (-l) or "Execute Macro" (-e) command-line options.


(For more information on creating, loading, and executing external Compiled
Macro files, including use of the macro autoload file, see
"Introduction to External Compiled Macros" in the chapter on
"Creating and Using Macros."  Also see "LoadMacro()" and "ExecMacro()"
in the chapter on "Editor Commands" in the Macro Reference Guide.  For
more information on processing WhenLoaded and Main macros, see
"Event Macros" in the chapter on "Using Macro Language Features" in the
Macro Reference Guide.  For more information on creating a TSEStart macro
file, see "Creating a TSEStart Macro File" in the chapter on
"Fully Customizing the Editor."  For more information on setting the
video mode that the editor uses each time it starts, see "Startup Video Mode"
under "Display/Color Options" in the chapter on
"Configuring the Editor Interactively.")





Editor Variables

To effectively use this chapter of the Macro Reference Guide, you need a
working knowledge of the SemWare Applications Language (SAL).  Detailed
information about SAL is provided in the first five chapters of the
Macro Reference Guide.  Descriptions of the native editor commands available
in SAL are provided in the chapter on "Editor Commands."

This chapter provides information on setting and querying the editor variables
(options) available within SAL that allow you to customize the editing
environment.

The description for each variable in this chapter indicates the variable name,
a summary definition, variable type, valid values or range of values, and
default value (if any).  Additional information provided for many variables
includes limitations, usage notes, related variables, and a list of commands
affected by the value assigned to the variable.  (The commands indicated in
this chapter are native commands, as described in the "Editor Commands"
chapter.  Command names are distinguished from variable names by "()"
following each command name, such as "Find()".)


Values
──────

For each variable, the variable type is identified as either INTEGER, STRING,
or BOOLEAN.  The valid values or range of values for each variable are also
indicated.

Note that BOOLEAN is a subset of INTEGER, with only two allowable values, ON
and OFF (or their equivalent values, TRUE and FALSE, or 1 and 0,
respectively).


Default
───────

The initial value of each variable at editor startup is indicated, if
appropriate.  (If you have installed the editor using an emulation other than
the standard editor user interface, the initial values for the variables may
differ.)


Limits
──────

Any limitations relating to the use and operation of a variable are indicated.

Unless otherwise noted in the limits, all variables can be manipulated by the
Query() and Set() commands, and all BOOLEAN type variables can also be
manipulated by the Toggle() command.  Unless otherwise indicated, all
variables can be used within the config/endconfig construct of an editor
configuration file.


Affects
──────

Commands that may be affected by the setting of a variable are indicated for
that variable.





EditThisFile()

Loads a file into the editor and makes it the current file.

Syntax:     INTEGER EditThisFile([STRING fn [, INTEGER flag]])

            • fn is an optional string expression specifying the file to be
              loaded.

            • flag is an optional integer that affects the operation of
              EditThisFile().  See the EditFile() command for supported
              values of flag.

Returns:    The non-zero id of the file just edited if successful; otherwise,
            zero (FALSE).

Notes:      If no filename is specified, the editor will prompt for a
            filename.

            This command is very similar to the EditFile() command, except
            that EditThisFile() expects a single filename, whereas
            EditFile() can accept multiple filenames.  EditFile() and
            EditThisFile() work similarly when filenames are quoted.

            For instance:

            If at the EditThisFile() prompt, one types:

            some file name

            Either "some file name" is loaded from disk (if it exists), or a
            new editing buffer is created, and given the specified name.

            In contrast, if the above was typed at an EditFile() prompt,
            three separate files would be loaded/created, "some", "file",
            and "name".

            See the EditFile() command for additional notes.


Examples:

            // Edit a file named "my.fle"
            EditThisFile("my.fle")

            // Edit a file, whose name is stored in the string s
            EditThisFile(s)

See Also:   EditFile(), CreateBuffer(), CreateTempBuffer(), PickFile(),
            AddHistoryStr(), Hook(), UnHook(), BufferType(),
            AddFileToRing(), ReplaceFile(), NewFile()

            Variables:  LoadWildFromDOS, LoadWildFromInside, UseCommonDialogs





Effects of Expandtabs

This section explains how tabs are visibly handled on the screen, and
describes some of the effects that may be noticed, when a file containing
physical tab characters is edited and ExpandTabs is ON.  The ExpandTabs option
can cause differences in the physical versus the visible effects of tab
characters in a file.  When the ExpandTabs option is ON, tab characters in a
file affect the columns at which text is displayed.  The tab characters
themselves are not displayed.  Note, however, that ExpandTabs has no effect on
any line longer than 255 characters.  (For more information on how to set the
ExpandTabs option, see "Expand Tabs (Display Only)" under "Tab/Margin Options"
in the chapter on "Configuring the Editor Interactively.")

When text is displayed on the screen, the presence of a tab character causes
the text following the tab character to be shifted out to the next tab stop.
The tab stops are determined based on the current setting of TabWidth.  This
also applies to the text display when an existing file containing tab
characters is loaded.  If the TabWidth value is changed during an editing
session, the display of the text visibly changes to accommodate the new
TabWidth.

When text is shifted to a tab stop, it will appear that space characters have
been inserted into the text to fill the void area.  However, this is not the
case.  That area is empty and does not contain any actual characters.

The behavior of CursorRight and CursorLeft may be affected as the cursor moves
past the tab characters and over the void area.  The cursor jumps from a
non-displayed tab character to the next or previous tab stop.

If you execute CursorDown, and the current cursor position on the new line
is within a void area, the cursor shifts left to an actual text character
(which may be a space character), or to the beginning of the line if no text
characters precede the cursor.

Inserting text within a line containing tab characters may also cause unusual
visible effects.  Non-displayed tab characters may be overwritten or moved as
new characters are typed or shifted into the void area, causing text to the
right of the tab to possibly shift.  Deleting text may also cause text to
shift, if a non-displayed tab character is deleted.

Caution should be exercised when executing TabLeft with Insert ON.  Because
the tab characters are not visible, this action could result in inadvertent
deletion of tab characters.


  ┌──────────────────────────────── Tip ─────────────────────────────────┐
  │  To print a file containing tab characters, use one of the editor's  │
  │  Print commands (under the Print Menu).  The editor then interprets  │
  │  tab characters according to your current TabWidth.  This should     │
  │  help achieve the desired placement of the text on the printed page. │
  └──────────────────────────────────────────────────────────────────────┘





EmptyBuffer()

Deletes all the text in the current or specified buffer.

Syntax:     INTEGER EmptyBuffer([INTEGER buffer_id])

            • buffer_id is the optional id number of the file in which to
              delete all lines.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      The cursor is positioned at line 1, column 1, after the completion
            of this command.

            Since this command deletes all the text in the specified buffer
            without confirmation, it should be limited to use within a macro
            procedure, and not assigned to a key by itself.

            _ON_CHANGING_FILES_ hooks are NOT invoked by this command.

See Also:   AbandonFile()





EmptyWinClip()

Empties the contents of the Windows Clipboard.

Syntax:     INTEGER EmptyWinClip()

Returns:    Non-zero if successful; zero (FALSE) on failure.

See Also:   CopyToWinClip(), CutToWinClip(), CopyAppendToWinClip(),
            CutAppendToWinClip(), PasteFromWinClip(), isWinClipAvailable()





Enable()

Activates the specified set of key definitions.

Syntax:     INTEGER Enable(KEYDEF keydef_name [,INTEGER exclusive])

            • keydef_name is the name of the keydef to enable.

            • exclusive is an optional integer that determines whether the
              keys in keydef_name will be the only keys active, or merged in
              with the keys already active.  If not specified, _DEFAULT_ is
              used. Supported values for exclusive are:

              • _DEFAULT_ specifies that only the keys listed in the keydef
                will be changed to the new definition.  All other keys will
                continue to be active and work as before.

              • _EXCLUSIVE_ specifies that only the keys listed in this
                keydef will be active.  All other keys will have no effect.

              • _TYPEABLES_ enables all typeable keys (alpha, numeric, and
                punctuation keys) that do not have any macros already assigned
                to them.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Any keydefs that are enabled will remain in effect until they are
            specifically disabled with the Disable() command, or when the
            editor is exited.

            This command returns zero if there is not room in the active
            keydef table for another entry.

            For more information on the keydef identifier, see "Keydef" and
            "Process() and Keydefs" in the chapter on
            "Using Macro Language Features."

Examples:

            /********************************************************
              Make my_keydef active, make it exclusive (only keys in
              this keydef are active), and allow all typeable keys.
             ********************************************************/
            Enable(my_keydef, _EXCLUSIVE_ | _TYPEABLES_)

            /********************************************************
              Make my_keydef active.  Other defined keys are still
              active, but keys in my_keydef take precedence.
             ********************************************************/
            Enable(my_keydef, _DEFAULT_)

            See the Process() command for additional examples.

See Also:   Disable(), Process()





EndFile()

Moves the cursor to the end of the last line of the current file.

Syntax:     INTEGER EndFile()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Zero is returned if the cursor position does not change.  For
            example, if the cursor is already at the end of the last line of
            the file, zero is returned.

            This command is equivalent to the following:

            GotoLine(NumLines())
            EndLine()

Examples:

            In order to maintain the current cursor column when a column
            block is open in the current file, use the following macro
            instead of the EndFile() command:

            proc mEndFile()
                integer col = CurrCol()

                EndFile()
                if Query(Marking) and isBlockInCurrFile() == _COLUMN_
                    GotoColumn(col)
                endif
            end

            <Ctrl PgDn> mEndFile()

See Also:   BegFile()





EndLine()

Moves the cursor to the end of the current line (that is, one position past
the last character on the line).

Syntax:     INTEGER EndLine()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If the cursor is already at the end of the current line, zero is
            returned.

            If the RemoveTrailingWhite variable is set ON, this command will
            remove any trailing white space found on the current line before
            going to the end-of-line position.

See Also:   BegLine(), BegLineTog(), EndLineTog()

            Variables:  RemoveTrailingWhite





EndLineTog()

Toggles the cursor position between end end of line and the right edge of
the editing window.

Syntax:     EndLineTog()

Returns:    Nothing.

            If the cursor is already positioned at the end-of-line position
            on the current line, the cursor moves to the right edge of the
            window on the current line, otherwise the cursor moves to the
            end-of-line position on the current line.

See Also:   EndLine(), BegLine(), BegLineTog()





EndProcess()

Terminates the current process and returns control to the previous process.

Syntax:     EndProcess([INTEGER status])

            • status is an optional result that can be passed to the calling
              process, which could be Process() itself, or List() or lList()
              if the appropriate event is hooked.  status defaults to 0 if
              not passed.

Returns:    Nothing.

Notes:      EndProcess() will terminate the current process level and return
            control back to the previous process at the instruction following
            the Process() command that invoked the process level.  If the
            current process level is the only one, control will be returned to
            the editor.

            Use this command to terminate a process that was started with the
            Process() command.  Typical usage is to assign EndProcess() to a
            key via a keydef.

Examples:

            See the Process() command for an example.

See Also:   Process(), Enable(), Disable()





EndWindow()

Moves the cursor to the bottom line of the current window, without changing
the cursor column.

Syntax:     INTEGER EndWindow()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If the cursor is already at the bottom line of the current window,
            zero is returned.

            If there are not enough lines in the current file to extend to the
            bottom line of the window, the cursor is moved to the last line in
            the file.

See Also:   BegWindow()





EndWord()

Moves the cursor to the end of the current word.

Syntax:     INTEGER EndWord()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Zero is returned if the cursor character and the character to the
            left of the cursor are not in the currently defined WordSet.
            Otherwise, the cursor is moved to the end of the word, if the
            cursor was not already there.

See Also:   BegWord(), WordLeft(), WordRight()

            Variables:  WordSet





EntabCurrLine()

Converts consecutive space characters on the current line to the appropriate
number of tabs.

Syntax:     INTEGER EntabCurrLine([INTEGER respect_column_block [,INTEGER min_spaces]])

            • respect_column_block, if non-zero, optionally limits
              entabbing to the text on the line that is within a column
              block.  If no text on the line is within a column block, this
              parameter is ignored.

            • min_spaces, at least this many spaces plus one must be found
              in order to replace a run of spaces with a tab character.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      The editor uses the TabWidth variable to determine the number
            of consecutive space characters to replace with a tab character.
            If TabWidth is 0, EntabCurrLine() does nothing and returns FALSE.

            A single space character is not replaced with a tab unless
            TabWidth is set to 1.

Examples:

            EntabCurrLine() // entab the current line

See Also:   ExpandTabsToSpaces()

            Variables:  TabWidth





EntabOnSave

If on, spaces are converted to tabs (as appropriate) when a file is saved.

Values:     BOOLEAN

Default:    OFF

Notes:      Spaces are converted to tabs based on the TabWidth editor
            variable.

See Also:   DetabOnLoad, TabWidth





EOFType

Determines what character(s) the editor will place at the end of the last line
of the file when the file is saved to disk.

Values:     INTEGER

            • 0 - do not append any characters at last line in file

            • 1 - append a Control-Z (^Z) at last line in file

            • 2 - force EOLType at last line in file

            • 3 - force EOLType at last line in file and append a Control-Z

Default:    2

Notes:      This setting has no effect on how files are loaded.

See Also:   EOLType





EOLType

Determines whether the editor adds CR/LF, CR, or LF at the end of each line
when the file is saved to disk.

Values:     INTEGER

            • 0 - AS LOADED.  If the file, when read into the editor,
                  contains only lines terminated by a linefeed character
                  (LF), then the editor will terminate each line with a LF
                  when the file is saved.  If the file contains only lines
                  terminated by a carriage return character (CR), then the
                  editor will terminate each line with a CR when the file is
                  saved.  For all other files, the editor will terminate each
                  line with a CR/LF when the file is saved.

            • 1 - ^M (CR)

            • 2 - ^J (LF)

            • 3 - ^M^J (CR/LF)

Default:    0

Notes:      For most applications, the default setting will be sufficient.
            Values 1 and 2 are provided to support file formats from other
            platforms such as UNIX and Macintosh.

            This variable has no effect on how the editor interprets lines
            when loading files.

Affects:    SaveAllAndExit(), SaveAllFiles(), SaveAndQuitFile(), SaveFile(),
            SaveAs()

See Also:   EOFType





EquateEnhancedKbd

Causes the editor to equate enhanced keys to their standard counterpart.

Values:     BOOLEAN

Default:    ON

Notes:      If EquateEnhancedKbd is ON, then enhanced keyboard keys, such as
            <GreyCursorRight>, are translated to their corresponding
            non-enhanced keys, such as <CursorRight>.

            For example:

            If you assign a command to <GreyCursorRight> and have
            EquateEnhancedKbd turned ON, then whenever you press
            <GreyCursorRight>, you will get the command assigned to
            <CursorRight>, instead of the one assigned to <GreyCursorRight>.

See Also:   Commands: GetKey()





EquiStr()

Compares two strings in a case-insensitive manner.

Syntax:     INTEGER EquiStr(STRING s1 , STRING s2)

            • s1 is the first string to be compared.

            • s2 is the second string to be compared

Returns:    Non-zero (TRUE) if s1 is equal to s2; otherwise, zero (FALSE).

Notes:      This command is provided as an adjunct to the normal string
            comparison operator, "==".  The "==" operator compares strings in
            a case sensitive manner.  EquiStr() makes it easy to compare two
            strings for equality, regardless of their case.

            When to use CmpiStr() vs. EquiStr()

            If you want to know if two strings are equal, ignoring
            differences in case, use EquiStr().

            If you want to know the lexical ordering of two strings (if one
            is less than or greater than the other), use CmpiStr().

Examples:

            // compare two strings to see if they are equal, regardless of
            // case

            if EquiStr(s1, s2)
                Message("s1 and s2 are the same")
            else
                Message("si is different than s2")
            endif

See Also:   CmpiStr()





EraseDiskFile()

Erases the specified file from disk.

Syntax:     INTEGER EraseDiskFile(STRING file_to_erase)

            • file_to_erase is the name of the file to erase.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Zero is returned if the file cannot be erased.  Possible reasons
            why the file cannot be erased are that the file does not exist, or
            the file is read-only.

            Wildcard characters (* and ?) are not supported by this command.

See Also:   FileExists()





Escape()

Terminates editor prompts; closes pop-up and pull-down menus; ends List().

Syntax:     INTEGER Escape()

Returns:    Zero (FALSE).

Notes:      When the editor prompts for information, or a menu or selection
            box is displayed on the screen, this command is always assigned to
            the <Escape> key.  This command is made available so that other
            keys can be used as additional keys for an escape function.





Event Macros

An event macro is one that is automatically executed (or "triggered") any time
certain pre-defined editor events occur.  There are two types of event macros:

    • Macros with certain pre-defined macro names that are triggered by
      certain pre-defined events.

    • Macros specifically defined by the user to be triggered by certain
      pre-defined events.


Event Macros with Predefined Names
──────────────────────────────────

The event macros that are triggered in accordance with pre-defined names are
those that are named Main(), WhenLoaded(), or WhenPurged().  These event
macros behave as follows:

    • A Main macro can be used in external or user-interface macros.
      In user-interface macros, it is executed (triggered) on editor
      startup. In external macros, it is associated with the name of the
      external Compiled Macro file in which it resides.  The Main macro is
      the one that is executed (triggered) when a macro filename is passed
      to ExecMacro().

    • A WhenLoaded macro can be used in external or user-interface macros.
      In user-interface macros, it is executed (triggered) on editor startup.
      In external macros, it is executed (triggered) when the external
      Compiled Macro file containing it is loaded.

    • A WhenPurged macro can be used in external or user-interface macros.
      In external macros, it is executed (triggered) when the Compiled Macro
      file containing it is purged.  In user-interface macros, it is executed
      (triggered) when the editor is terminated.

To use these types of event macros, simply declare a macro to have the name of
Main(), WhenLoaded(), or WhenPurged(), as appropriate.  Note that only one
occurrence of each can occur in a macro file.  (For more information on these
types of event macros, see the chapter on "Using Macros.")


Event Macros Defined by the User
────────────────────────────────

The event macros that are triggered in accordance with specific definition by
the user, are those for which the user explicitly establishes an association
between the desired macro and the particular triggering event, by "hooking"
the macro to the event.  Once you hook a macro to an event, that triggering
event is called a "hooked" event.  When the hooked event occurs, the editor
automatically executes the associated macro.

Following are the editor events that can be hooked, along with a short
explanation of when each event occurs.

    • _ON_EDITOR_STARTUP_  is called just before the editor starts the main
      editing loop.  It is useful when you want to gain control after the
      command line has been processed, the file to edit has been loaded, but
      the editor has not yet drawn the window or gotten keystrokes from the
      user.

    • _ON_CHANGING_FILES_ is called each time a different file is switched to,
      with the following exceptions:

      • If the file was switched to via the GotoBufferId() command, this event
        is NOT called.

      • If the file was switched to using the _DONT_LOAD_ option of the
        NextFile() or PrevFile() commands, this event is NOT called.

        See the OnChangingFiles() macro in the TSE.UI user-interface macro
        file for examples using this event.

    • _ON_FIRST_EDIT_ is called the first time a file is loaded into the
      editor.  Therefore, it is only called once for each file edited.  This
      event is NOT called by the CreateBuffer() or CreateTempBuffer()
      commands.

    • _ON_FILE_LOAD_ is called immediately before a file is loaded into the
      editor.  It is called before _ON_FIRST_EDIT_.

    • _ON_FILE_SAVE_ is called just before the editor saves a file.  It is NOT
      called by the SaveAs() and SaveBlock() commands.

    • _AFTER_FILE_SAVE_ is called just after the editor saves a file.  It is
      NOT called by the SaveAs() and SaveBlock() commands.

    • _ON_FILE_QUIT_ is called just before the editor quits a file via the
      single-file quitting commands, namely QuitFile(), SaveAndQuitFile(), and
      AbandonFile().  If only a single file is loaded, this event is not
      called unless the editor variable QuitToPrompt is set ON.

    • _ON_EXIT_CALLED_ is called at the beginning of the Exit() and
      SaveAllAndExit() commands.

    • _ON_ABANDON_EDITOR_ is called just before the editor terminates (that
      is, just before the editor exits to the operating system or to the
      calling program).

    • _IDLE_ is called from the editor's keyboard processing routine, when no
      keys are available to be processed, AND the editor is in a
      "text-editing" state (that is, the focus is a text-editing window, as
      opposed to a prompt, menu, list, or other similar input focus).

    • _NONEDIT_IDLE_ is called from the editor's keyboard processing loop,
      when no keys are available to be processed, AND the editor is in a
      "non-text-editing" state (that is, the focus is a prompt, menu, list,
      or other similar non-text-editing input focus).

    • _BEFORE_UPDATE_DISPLAY_ is called before each window is updated.

    • _AFTER_UPDATE_DISPLAY_ is called after each window is updated.

    • _AFTER_UPDATE_STATUSLINE_ is called after the StatusLine is updated.

    • _BEFORE_COMMAND_ is called before each text-editing command is
      processed.  (This event is called only by those commands that are
      executed by pressing a key, rather than being selected from the
      pull-down Menu.)

    • _AFTER_COMMAND_ is called after each text-editing command has completed
      processing. (This event is called only by those commands that are
      executed by pressing a key, rather than being selected from the
      pull-down Menu.)

    • _BEFORE_NONEDIT_COMMAND_ is called before each non-text-editing command
      is processed.  (This event is called only by those commands that are
      executed when the editor is in a "non-text-editing" state; that is, the
      focus is a prompt, menu, list, or other similar non-text-editing input
      focus.)

    • _AFTER_NONEDIT_COMMAND_ is called after each non-text-editing command
      has completed processing.  (This event is called only by those commands
      that are executed when the editor is in a "non-text-editing" state;
      that is, the focus is a prompt, menu, list, or other similar
      non-text-editing input focus.)

    • _LIST_STARTUP_ is called when the List() and lList() commands start
      processing.

    • _LIST_CLEANUP_ is called when the List() and lList() commands terminate.

    • _PICKFILE_STARTUP_ is called when the directory PickList routine is
      invoked.  (The PickList routine is invoked by the PickFile() command.
      Any commands that display a PickList of files, such as the EditFile()
      command, also call the PickFile() command.)

    • _PICKFILE_CLEANUP_ is called when the PickFile() command terminates.

    • _PROMPT_STARTUP_ is called when the Ask() and Read() family of commands
      start processing.

    • _PROMPT_CLEANUP_ is called when the Ask() and Read() family of commands
      terminate.

    • _ON_SELFINSERT_ is called after a character is inserted into a
      text-editing window.

    • _ON_DELCHAR_ is called after any of the following commands are executed
      in a text-editing window:  DelChar(), DelRightWord(), DelLeftWord(),
      BackSpace()

    • _PRE_UPDATE_ALL_WINDOWS_ is called once at the beginning of the
      UpdateDisplay() command processing.

    • _POST_UPDATE_ALL_WINDOWS_ is called once at the end of the
      UpdateDisplay() command processing.

    • _ON_UNASSIGNED_KEY_ is called whenever an unassigned key is pressed,
      AND the editor is in a "text-editing" state (that is, the focus is a
      text-editing window, as opposed to a prompt, menu, list, or other
      similar input focus).

    • _ON_NONEDIT_UNASSIGNED_KEY_ is called whenever an unassigned key is
      pressed, AND the editor is in a "non-text-editing" state (that is, the
      focus is a prompt, menu, list, or other similar non-text-editing input
      focus).

    • _BEFORE_GETKEY_ is called just before the editor gets another key or
      mouse button, regardless of whether the editor is in a "text-editing" or
      "non-text-editing" state.  (To determine the current state of the
      editor, use the QueryEditState() command.)

    • _AFTER_GETKEY_ is called just after the editor has gotten another key
      or mouse button, regardless of whether the editor is in a "text-editing"
      or "non-text-editing" state.  (To determine the current state of the
      editor, use the QueryEditState() command.)

A macro is hooked to a triggering event by using the Hook() command.

▪ Hook()

  The basic format for this command is:

    Hook(INTEGER event_name, PROCEDURE macro_name)

  This command is used to associate, or hook, the macro indicated by
  macro_name, with the triggering event indicated by event_name.
  event_name must be one of the events listed previously.  After this
  command executes successfully, macro_name is then called each time the
  hooked event occurs.

  The same macro can be hooked to multiple events, and multiple macros can be
  hooked to the same event.  However, the same macro cannot be hooked more
  than once to the same event.

  If multiple macros are hooked to the same event, then when the triggering
  event occurs, the hooked macros are scheduled for execution in chronological
  hooking order; that is, the first event that is hooked is the first one that
  is executed.  For example, given:

    proc foo()
        ...
    end

    proc foobar()
        ...
    end

    proc main()
        Hook(_ON_FILE_SAVE_, foobar)
        Hook(_ON_FILE_SAVE_, foo)
    end

  then, when the _ON_FILE_SAVE_ event occurs, foobar() is executed, and then
  foo() is executed.

A macro can subsequently be unhooked from an event by using the UnHook()
command.

▪ UnHook()

  The basic format for this command is:

    UnHook(PROCEDURE macro_name)

  This command breaks the association between the macro indicated by
  macro_name, and any triggering events; that is, it unhooks macro_name
  from any events.  After this command executes successfully, macro_name is
  no longer called by any events.

  When you purge a Compiled Macro file, any macros in that file that are
  hooked to events, are automatically unhooked.


You can also temporarily unhook macros from an event by using the
SetHookState() command.  This command allows you to specify whether the hooks
for a particular editor event are currently enabled or disabled.  If the
hooks are enabled, the editor event will trigger any event macros that are
hooked to the event.  If disabled, the event will not trigger event macros
that are hooked to it.

▪ SetHookState()

  The basic format for this command is:

    SetHookState(INTEGER event_state, INTEGER event_name)

  This command sets the current hook state of the editor event indicated by
  event_name.  If event_state is zero (FALSE), the hook state is
  disabled; if non-zero (TRUE), the hook state of the specified event is
  re-enabled.

  This command can be used within macros to disable the hooks for an event,
  do some required processing, and then re-enable the previous hooks.


A command that complements the SetHookState() command is the GetHookState()
command.  The GetHookState() command allows you to check the current state of
an editor event to see if the macros that are hooked to it are currently
enabled.

▪ GetHookState()

  The basic format for this command is:

    GetHookState(INTEGER event_name)

  This command allows you to determine if the hooks for the editor event,
  indicated by event_name, are currently enabled or disabled.  If the hooks
  are enabled, the editor event will trigger any event macros that are hooked
  to the event.  If disabled, the event will not trigger event macros hooked
  to it.

  This command, used in conjunction with the SetHookState() command, is
  useful for saving, setting, and then restoring the hook state of an event.
  Typically, the event hooks are disabled, a task is performed, and then the
  event hooks are re-enabled.


When you have multiple macros hooked to an event, and that event has just
occurred, it is possible to break the chain of macros triggered by the event
(for this occurrence of the event only).  To do this, use the BreakHookChain()
command within an appropriate event macro in the chain.  The remaining event
macros, currently scheduled for execution by the event, are immediately
canceled.

▪ BreakHookChain()

  The basic format for this command is:

    BreakHookChain()

  This command terminates the remaining chain of event macros that are
  currently scheduled for execution by the occurrence of a multi-hooked event.
  If BreakHookChain() is called by the currently-executing macro in a chain of
  hooked macros, no additional macros hooked to that event are called.

  BreakHookChain() breaks the chain of event macros only for the current
  occurrence of the event.  The next time the hooked event occurs, the entire
  chain of event macros will be scheduled for execution.  For example:

    /********************************************************
      Prevent any _ON_CHANGING_FILES_ hooks from being run
      while we are busy.
     ********************************************************/
    proc StopOnChangingFilesHook()
        BreakHookChain()
    end

    proc foo()
        Hook(_ON_CHANGING_FILES_, StopOnChangingFilesHook)
        // Code goes here...
        UnHook(StopOnChangingFilesHook)
    end


It is possible to explicitly call all of the macros hooked to an event, using
the ExecHook() command.

▪ ExecHook()

  The basic format for this command is:

    ExecHook(INTEGER event_name)

  This command provides a means of calling all macros hooked to a specified
  event, indicated by event_name.  Its primary purpose is to simulate the
  actual event for testing purposes; however, it is also useful in certain
  other situations.  event_name must be one of the events listed above.





ExecHook()

Executes all hooks associated with the specified event.

Syntax:     INTEGER ExecHook(INTEGER event)

            • event is the name of the event to execute.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      All hooked procedures for event are executed in the same way as
            when the specified event actually occurs.

            See the Hook() command for a list of the supported events.

Examples:

            // Execute any hooks associated with _ON_FIRST_EDIT_
            ExecHook(_ON_FIRST_EDIT_)

See Also:   Hook(), UnHook(), BreakHookChain(), GetHookState(),
            SetHookState(), TerminateEvent()





ExecLoadedMacro()

Displays a PickList of the macros currently loaded, then executes the macro
selected from the PickList.

Syntax:     INTEGER ExecLoadedMacro()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If there are no macros in memory (that is, no macros are loaded),
            or the PickList is abandoned without executing a macro, zero
            (FALSE) is returned.

See Also:   ExecMacro(), LoadMacro(), isMacroLoaded()





ExecMacro()

Executes the requested Compiled Macro.

Syntax:     INTEGER ExecMacro([STRING macro_str [, STRING public_name]])

            • macro_str consists of macro_name and an optional
              cmd_line_str, in the format "macro_name cmd_line_str",
              where:

              • macro_name is the name of a Compiled Macro file or an
                already-loaded Public macro to execute.  macro_name may
                contain wildcards or other characters used in filenames
                ("\", ":", or ".").

              • cmd_line_str is an optional command-line string to pass to
                macro_name.  cmd_line_str must be separated from
                macro_name by one or more spaces.  Spaces may be included
                within the text for cmd_line_str.

            • public_name is an optional name of a specific public procedure
              within macro_name.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      When macro_name is specified, the editor attempts to execute the
            specified macro as follows:

            • If macro_name includes path information:

              • The editor checks to see if a macro with the specified name
                is already loaded, and was loaded from the indicated drive
                and/or directory.  If one is located, that macro is executed.

              • If one is not found, the editor calls the LoadMacro() command
                to attempt to locate the indicated Compiled Macro file from
                the specified drive and/or directory.  If located, the
                Compiled Macro file is loaded:  the Main() macro, if present,
                and any Public macros are added to the Public macro table;
                and the WhenLoaded() macro, if present, is executed.  The
                editor then executes the Main() macro (if one is present).

              • If the specified Compiled Macro file still cannot be located,
                the command fails.

            • If macro_name does not include path information:

              • The editor checks to see if a macro with the specified name
                is already loaded.  If one is located, that macro is
                executed.

              • If one is not found, the editor calls the LoadMacro() command
                to attempt to locate the indicated Compiled Macro file on
                disk. If located, the Compiled Macro file is loaded:  the
                Main() macro, if present, and any Public macros are added to
                the Public macro table; and the WhenLoaded() macro, if
                present, is executed. The editor then executes the Main()
                macro (if one is present).

              • If the specified macro still cannot be located, the command
                fails.

            If macro_name is not specified, the editor pops up a list of
            currently-loaded macros.  It executes the selected macro and
            returns non-zero, or returns zero if the user presses <Escape>.

            cmd_line_str is valid only if macro_name is also specified.
            If cmd_line_str is specified, the contents of this command-line
            string are placed in the MacroCmdLine variable.  The invoked
            macro(s) can then access the command-line string by querying the
            MacroCmdLine variable.  If the invoked macro was called by
            another macro, information can also be passed back to the calling
            macro by setting the value of the MacroCmdLine variable.

            If ExecMacro() is executed and cmd_line_str is not specified,
            the MacroCmdLine variable is set to the empty string.

            To run a specific public procedure in a macro, the public_name
            variable should be specified.  To run public procedures in a .ui
            file, specify a macro_str of ".ui".

            Any Compiled Macros intended for repeated execution from memory
            (that is, they are not always reloaded before execution) should be
            fully reentrant.  Simply put, this means that the user should be
            aware that any global variables will start with whatever values
            they ended with on the last invocation of the macro.  If the user
            needs a global variable to have a certain value each time the
            macro is run, assign it that value via an assignment statement in
            the macro rather than in a global variable definition.

            For a Compiled Macro that should be loaded from disk each time it
            is to be executed, you can do either of the following:

            1) Purging the macro from memory, by calling:

                PurgeMacro(SplitPath(CurrMacroFilename(), _NAME_))

            2) Explicitly reloading the macro by first calling LoadMacro()
                and then ExecMacro()

                LoadMacro(macro_name)
                ExecMacro(macro_name)

            This command includes a history list of previous entries passed to
            it.  See AddHistoryStr() for additional information.

Examples:

            /********************************************************
               A macro to ALWAYS load and execute macros from disk.
             ********************************************************/
            proc ExecMacroFromDisk()
                string fn[65] = ""

                if Ask("Macro to Exec:", fn) and Length(fn)
                    if LoadMacro(fn)
                        ExecMacro(fn)
                        PurgeMacro(fn)
                    endif
                endif
            end


            Following is an example of how to pass a command line to a macro.
            Everything following the space(s) after "state" is assigned to
            the MacroCmdLine editor variable.

            ExecMacro("state -s -l -ftemp.sta")


            To run a public macro procedure named DelBlankLines() found in a
            macro file named delete-blank:

            ExecMacro("delete-blank", "DelBlankLines")

            To run a public macro procedure named mMarkPara() found in the
            .ui file:

            ExecMacro(".ui", "mMarkPara")


See Also:   isMacroLoaded(), LoadMacro(), PurgeMacro(), AddHistoryStr(),
            ExecLoadedMacro()

            Variables:  MaxHistorySize, TSEPath, MacroCmdLine





ExecScrapMacro()

Executes the scrap Keyboard Macro.

Syntax:     INTEGER ExecScrapMacro()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Executes the last scrap Keyboard Macro defined in the current
            editing session.  Scrap macros are created by pressing <Enter> in
            response to the "Assign to key" prompt of RecordKeyMacro().

            If no scrap macro is defined, no action occurs and zero is
            returned.

See Also:   IsScrapMacro(), RecordKeyMacro()





Executing External Commands from Within the Editor

The Dos, CaptureDosOutput, and Shell commands allow you to execute external
commands from within the editor.


▪ Dos  (<Alt F9>)

  This command allows you to execute a single external command from the editor.
  When you execute this command, the editor displays the prompt "OS command:".
  Enter any valid external command and press <Enter>.  The specified command
  is executed.  Upon its completion, the prompt "Press a key to continue..."
  is displayed.  Press any key on the keyboard to return to the editor and
  re-display the screen as it was prior to execution of this command.

▪ CaptureDosOutput  (<AltShift F9>, or "Capture OS Output" under Util Menu)

  Like the Dos command, this command allows you to execute a single external
  command from the editor.  However, CaptureDosOutput captures the screen
  output from the command and loads it into a temporary file upon completion.

  When you execute CaptureDosOutput, the editor displays the prompt "OS
  command capture:".  Enter any valid external command and press <Enter>.  The
  specified command is executed.  Upon its completion, any screen output that
  can be redirected is placed in a temporary file.  (Screen output that cannot
  be redirected is not included in the temporary file.)  You are then placed
  in the temporary file.  To return to the file you were editing at the time
  you executed CaptureDosOutput, you must switch back to that file.

▪ Shell  (<F9>, or "Shell" under Util Menu)

  This command temporarily suspends the editor and places you at an operating
  system prompt, allowing you to execute any number of external commands.
  Type "exit" at a system prompt and press <Enter> to return to the editor and
  re-display the screen as it was prior to execution of the Shell command.

  To remind you that you are in the editor's Shell facility, the notation
  "TSE-Shell" is added to the operating system prompt string when Shell is
  executed.

  If you do not want the system prompt string to be changed when you execute
  Shell, you can configure the editor to leave the prompt string unchanged.
  (For more information, see "Change Prompt in Shell" under
  "Command/Format Options" in the chapter on
  "Configuring the Editor Interactively.")





Executing Macros (Overview)

To invoke (or "execute") your macro file at any time after you have compiled
it, press <Ctrl X> (or select "Execute" from the Macro Menu).  The editor
displays the prompt, "Execute macro:".  To execute the "hello" macro file
created previously, simply type "hello" at this prompt.

Note that macros can also be:

    • Assigned to a key, so that they execute when you press that key.

    • Assigned to a user-defined menu, so that they execute when you select
      that menu item.

    • Assigned to certain editor events (such as when you start or terminate
      the editor, or switch files).  This is discussed in more detail later.





Executing Supplemental Macros from the Potpourri

A miscellaneous collection, or "potpourri," of supplemental macros is
available by selecting "Potpourri" under the Util Menu (or by pressing
<Shift F10>).  This option pops up a PickList of supplemental macros that can
be executed.  An optional short description is included with each macro in
the Potpourri PickList.

When the Potpourri PickList pops up, the following options are available:

    • You can select a macro for execution.

    • You can display and edit Help information for macros in the list.

    • You can add your own macros (and Help information) to the list for
      ready access from the pull-down Menu.

    • You can remove existing entries from the list.

To execute a macro from the Potpourri PickList, move the cursor bar to the
desired macro and press <Enter>.  The editor's SpeedSearch feature and other
PickList scrolling options are available within this pop-up list.  (For more
information, see "Using PickLists" in the chapter on
"Command Prompts and PickLists.")


To display Help information about a macro, move the cursor bar to the macro in
the Potpourri list and press <F1>.  (For more information on obtaining Help on
a topic, see "Context-Sensitive Help" in the chapter on
"Getting Help in the Editor.")

To add a new macro to the Potpourri list, press <Ins>.  The editor prompts you
for the name of the macro file you want to add.  This must be a Compiled Macro
file.  However, do not include the ".MAC" extension; the editor forces a
".MAC" extension to whatever macro filename you enter.  The editor then
displays a one-page window in which you can enter your own description.  The
text on the top line of this "help description" window will be displayed
beside the macro name in the Potpourri PickList.  When complete, the editor
updates the editor program to include the indicated macro file and description
in the Potpourri list.

To edit Help information for an existing macro in the Potpourri list, move the
cursor bar to the desired macro and press <Alt E>.

To remove a macro from the Potpourri list, move the cursor bar to the desired
macro in the PickList and press <Del>.  The editor prompts you for
confirmation to delete the macro.  Upon confirmation, the editor removes the
macro from the Potpourri list.

In order to execute a macro from the Potpourri list, or to add a macro to the
list, the Compiled Macro file containing the macro must be available to the
editor in one of several pre-determined macro file directories.  If the macro
requires a data file, the data file should be placed in the same directory as
the Compiled Macro file.  (For more information on the directories in which
the editor searches for Compiled Macro files, see the
"macro file search order" described under "Creating and Using Compiled Macros"
in the chapter on "Creating and Using Macros.")

When you select a macro for execution from the Potpourri PickList, the editor
issues the ExecMacro command for the indicated Compiled Macro file.  (For more
information on executing Compiled Macros, see
"Loading and Executing Compiled Macros" in the chapter on
"Creating and Using Macros.")

Following are some of the macros included in the standard Potpourri macro
list.  (For a complete list, pop up the Potpourri PickList!)  Additional
information and prompts are provided by the macros themselves.

▪ Adjust  ("Adjust" on Potpourri PickList)

  This macro allows you to adjust text within a block by aligning it either on
  the left or right, or by centering it.  If a column block is marked, the
  macro operates on the text in the block using the leftmost and/or rightmost
  column boundary (as appropriate).  If a line or character block is marked,
  it operates on the text on the lines spanned by the block, using the left
  and/or right margin (as appropriate).  A selection menu issued by the macro
  allows you to choose whether you want to left adjust, right adjust, or
  center the text.

▪ Book  ("Book" on Potpourri PickList)

  This macro provides a convenient way to set Bookmarks, or to go to or list
  the Bookmarks that are currently set.  The macro maintains the current set
  of Bookmarks in a circular ring of 26 Bookmarks.  The following key
  assignments are activated to allow you to perform the indicated function:

    <Ctrl />        Set a Bookmark (uses the next available Bookmark in
                    the Bookmark ring)

    <Ctrl <>        Go to the previous Bookmark in the Bookmark ring

    <Ctrl >>        Go to the next Bookmark in the Bookmark ring

    <CtrlShift />   Displays a Bookmark list, consisting of the filename,
                    line number, and text in which each of the Bookmarks
                    are set. This option allows you to delete or go to a
                    selected Bookmark.

▪ CD  ("CD" on Potpourri PickList)

  This macro provides a facility for changing the current drive and/or
  directory.  You can indicate a specific drive/directory to which to change,
  or optionally select a new directory from a database containing the drives
  and directories on your system.

  When you execute the CD macro, the current directory is displayed on the
  StatusLine; and a prompt box is displayed that contains the directory of the
  current file, along with the message "Change to directory:".

  To change to the directory of the current file (as displayed in the prompt),
  just press <Enter>.  To change to another directory, you can type the entire
  path name of the desired directory and press <Enter>.  Unless a drive is
  included in the path you specify, the macro looks for the indicated
  directory on the current drive.

  You can also change to another directory using the optional "database
  directory" feature included in the macro.  This allows you to select a
  directory based on a partial or ambiguous directory name specification.  Use
  this macro to build and maintain a database of directories on your machine.
  Once this database has been created, you can specify a partial directory
  name to change to; or you can enter an ambiguous directory entry, and then
  select the desired directory from a PickList displayed by the macro.

  If the database directory exists, the CD macro processes the entries you
  make at the "Change to directory:" prompt as follows:

    • The macro first attempts to match the specified directory path exactly.
      If a matching directory exists, that directory becomes the current
      directory and the macro terminates.

    • If an ambiguous entry is made (that is, one which contains the wildcard
      character "*"), the macro searches the database for matching directory
      entries, and displays a PickList of those entries.  You can select the
      desired directory by moving the cursor bar to that directory entry and
      pressing <Enter>.  The selected directory becomes the current directory
      and the macro terminates.

    • Otherwise, the macro treats your entry as a partial entry, and searches
      the database for a directory path(s) that begins with the string
      entered at the prompt.

      • If only one directory is located that matches the partial entry, that
        directory becomes the current directory and the macro terminates.

      • If more than one matching directory is located, the macro displays a
        PickList of matching entries from which you can select the desired
        directory.  The selected directory becomes the current directory and
        the macro terminates.

    • If a match still has not been found, the macro then searches the
      database for any directory that contains the indicated string, anywhere
      in the directory name.  If only one match is found, that directory
      becomes the current directory and the macro terminates.  If multiple
      matching entries are found, a PickList of matching entries is displayed
      and the macro terminates once you select an entry.

    • Finally, if no match is found, the macro issues a message that it could
      not find any matches, and then terminates.

  To initially create or to update the directory database, press <Alt U> once
  the "Change to directory:" prompt is displayed.  The macro then builds, or
  rebuilds, a database of all the directory entries that are currently on the
  selected drives.  The directory entries are stored in the CD "database file"
  (TSECD.DAT), which is placed in the same directory from which the CD macro
  was loaded.

  To configure several options of the macro, press <Alt C> once the "Change to
  directory:" prompt is displayed.  You can then select the drives that are to
  be searched when the directory database is being built (or rebuilt); you can
  choose to add the CD macro to your AutoLoad List; or you can choose to
  remove the CD macro from your AutoLoad List.

▪ CmpFiles  ("CmpFiles" on Potpourri PickList)

  This macro allows you to compare the current file with another file, by
  simultaneously displaying and scrolling the two files, and highlighting the
  differences.

  When you execute this macro, it prompts you for the name of the file to
  compare with the current file.  You can even compare the current file with a
  file by the same name located in an archive file (that is, in a compressed
  ".ARC", ".ARJ", ".LZH", or ".ZIP" file).  To select a file in an archive,
  specify the name of the archive file at the prompt; the macro will attempt
  to locate a file within the archive that has the SAME NAME as the current
  file, and uncompress that particular file.

  Once you specify the comparison file, the macro then loads the comparison
  file into the editor, and splits the screen into two vertical windows, with
  the current file displayed in one, and the comparison file in the other.  To
  toggle the display between vertical and horizontal windows, press the
  <Spacebar>.

  To synchronize the text display of the two files and begin the comparison,
  press <Enter>.  Once the macro encounters differences in the files, it
  displays the relevant portion of each file (in the appropriate window).  The
  text that differs between the two files is highlighted in each window, for
  easy comparison.  You can continue this process throughout the files.

  While this macro is in operation, a number of features are in effect:

    • Cursor movement commands that you execute in either window will cause
      simultaneous scrolling in the other window.

    • To move to the beginning of the highlighted "difference" text, press
      <Grey ->; to move to the end of the difference text, press <Grey +>.

    • To continue the comparison process, press <Enter> again.

    • To display the HelpScreen for this macro, press <F1>; to access the
      macro's pull-down menu, press <F10>.

    • To minimize false comparisons, white (space or tab) characters, by
      default, are automatically converted to a single space character.  To
      toggle this option OFF/ON, press <W>.

    • You can change the video mode.

  To terminate the macro, press <Escape> (or select "Exit" from the "File"
  entry of the macro pull-down menu).  The macro gives you the option to
  "flush" the comparison file (that is, remove it from memory).

▪ CUAMark ("CUAMark" on Potpourri PickList)

  This macro enables CUA-style (Common User Access) key assignments in the
  editor for marking and manipulating character and column blocks.  When you
  execute this command, the shifted cursor-movement keys can be used for
  marking blocks, and additional block operations can be accomplished using
  select shifted keys.

  CUA-style blocks are also called non-persistent blocks.  This means that in
  general, if you press a non Block Mark/extend key, the block is unmarked.

  When using CUA-style blocks, typing and pasting (from the Windows Clipboard)
  will replace the block with the typed character or the contents of the
  Windows Clipboard.

  The following shifted keys are assigned to the indicated block operation or
  command:

       CUA-style Key            Block-marking Operation or Command
    ______________________  __________________________________________

    <Shift CursorLeft>      Mark/extend Block, move left one column
    <Shift CursorRight>     Mark/extend Block, move right one column
    <Shift CursorUp>        Mark/extend Block, move up one line
    <Shift CursorDown>      Mark/extend Block, move down one line
    <Shift Home>            Mark/extend Block, go to beginning of line
    <Shift End>             Mark/extend Block, go to end of line
    <Shift PgUp>            Mark/extend Block, move up one page
    <Shift PgDn>            Mark/extend Block, move down one page
    <CtrlShift CursorRight> Mark/extend Block, move right one word
    <CtrlShift CursorLeft>  Mark/extend Block, move left one word
    <CtrlShift Home>        Mark/extend Block, go to top of window
    <CtrlShift End>         Mark/extend Block, go to bottom of window
    <CtrlShift PgUp>        Mark/extend Block, go to beginning of file
    <CtrlShift PgDn>        Mark/extend Block, go to end of file

    Adding the <alt> key to any of the above combinations will instead
    Mark/extend a Column Block.

    <Shift Ins>             PasteReplace (from the Windows ClipBoard)
    <Shift Del>             Cut (to the Windows ClipBoard)
    <Ctrl Ins>              Copy (to the Windows ClipBoard)
    <Ctrl Del>              DelBlock (delete marked Block)

    <Del>                   delete marked Block or delete character
    <GreyDel>               delete marked Block or delete character
    <BackSpace>             delete marked Block or backspace

    Optionally, (by selecting CUAMark options) the following keys will also be
    assigned:

    <LeftBtn>               Mark/extend Block via the mouse by dragging
    <Shift LeftBtn>         Mark/extend Block via the mouse clicking

    <Ctrl v>                PasteReplace (from the Windows ClipBoard)
    <Ctrl c>                Copy (to the Windows ClipBoard)
    <Ctrl x>                Cut (to the Windows ClipBoard)

    <Ctrl F>                Find.  If text is found, it is marked as
                            a CUA-style block.

    <Ctrl L>                Repeat Find commands.  If text is found,
    <F3>                    it is marked as a CUA-style block.

    <CtrlShift L>           Repeat Find Reverse commands.  If text is
    <Shift F3>              found, it is marked as a CUA-style block.


  If you want to automatically enable this feature every time you start the
  editor, add the CUAMark macro to your autoload file.  (For more information
  on adding a macro to your autoload file, see "The AutoLoadList Command" in
  the chapter on "Creating and Using Macros.")

  The first time the CUAMark macro is loaded, it will self-configure by asking
  you several questions.  To reconfigure CUA Marking at another time, assuming
  that you viewing the CUAMark help from the Potpourri list, press <escape>,
  <enter> to reconfigure CUAMark.

  If you are not in Potpourri, and assuming that CUAMark is already loaded,
  select Macro, Execute, clear the prompt by pressing your delete line key,
  press <enter>, and select setup under CUAMark.

▪ DelBlank  ("DelBlank" on Potpourri PickList)

  This macro removes blank lines from a file or block.  It gives you the
  option to either remove all blank lines, or replace multiple consecutive
  blank lines with a single blank line.

  If the cursor is located within a marked block in the current file when you
  execute this macro, the editor prompts to confirm whether to limit
  operation to the block; otherwise, it will operate on the entire file.  If
  the cursor is not located at the beginning of the block or file, as
  appropriate, the editor prompts for you to select whether to begin
  operation from the beginning of the block or file, or to begin with the
  current line.

  Finally, the editor prompts for you to select whether you want to replace
  multiple consecutive blank lines with one blank line, or to remove all
  blank lines.

▪ Expand  ("Expand" on Potpourri PickList)

  This macro file provides a macro that operates like a limited, dynamic
  Template mode.  It expands, or completes, the "partial" word to the left of
  the cursor based on other words in the file.  When you execute Expand from
  the Potpourri PickList, the Expand macro is assigned to <Ctrl H>.

  With this macro activated, just press <Ctrl H> each time you want to
  complete the partial word immediately preceding the cursor.  The macro
  searches backward and forward in the file for words that begin with the
  string that you typed as the partial word.  If only one match is found, the
  partial word is replaced with the expanded word.  If multiple matches are
  found, the macro first displays a PickList of expanded entries from which
  you can choose.  To select an expanded word from the PickList, move the
  cursor bar over the desired entry and press <Enter>.  Your partial word is
  then replaced in the text with the expanded word you selected.

▪ Expr  ("Expr" on Potpourri PickList)

  This macro operates as a simple calculator, and handles decimal or
  hexadecimal numbers.  For decimal numbers, only whole numbers are accepted.

  The following operations are available:

    Operator                   Operation
    ________     ______________________________________

       >         SHR             (bitwise shift right)
       <         SHL             (bitwise shift left)
       ~         COMP            (2's complement)
       %         MOD             (modulo division)
       &         AND             (bitwise AND)
       |         OR              (bitwise OR)
       ^         XOR             (bitwise eXclusive-OR)
       +         Addition
       -         Subtraction
       *         Multiplication
       /         Division


  The order of precedence is the same as that in SAL, unless appropriately
  overridden using parentheses.

  Hexadecimal numbers can be notated in C-language format, or by placing an
  "h" or "$" at the end of the number.  However, the first character of the
  number MUST be numeric.

▪ FillNum  ("FillNum" under Potpourri PickList)

  This macro fills a column block with a series of numbers that can be
  incremented or decremented.  You specify the beginning and (optionally)
  ending number in the series, as well as the positive or negative amount by
  which to increment or decrement the series.

▪ FindEOL  ("FindEOL" on Potpourri PickList)

  This macro file provides a group of macros that allow you to find and
  replace text that includes the end of line, if you specify the end of line
  (as "$") in the search string.  These macros are useful for locating a text
  string that begins on one line and ends on another.  They are also useful
  for such tasks as:

    • Deleting extra blank lines in a file

      For example, to change all occurrences of 2 blank lines to a single
      blank line, use this macro to search for "$$$" and replace with "$$".

    • Removing trailing text from certain lines

      For example, to remove a trailing comma from any lines immediately
      followed by a blank line, use this macro to search for ",$$" and
      replace with "$$".

  When you execute this macro file, special find, replace, and repeat
  find/replace macros are assigned to keys.  A message is displayed to
  identify the key to which each macro is assigned.

▪ Grep  ("Grep" on Potpourri PickList)

  This macro searches for a specified string in multiple files on disk,
  and displays a PickList of all lines, within each relevant file, that
  contain the specified string (in a listing similar to the CompressView
  command).

  When you execute this macro, it prompts you for the search string; the
  file, directory, and/or drive specifications of the files in which to
  search; and the desired search options.  The macro supports all the
  search options of the Find command (including Regular Expressions), as
  well as the "Search SubDirs" (-s) option (to allow searching within
  subdirectories of any specified directories).

▪ InsMatch  ("InsMatch" on Potpourri PickList)

  This macro causes the editor to insert the matching character for a specific
  group of bracketing character pairs, including the following:  [], (), {},
  <>, '', "".  Execute this macro to toggle the "insert matching" mode ON or
  OFF.  When ON, the matching character of a pair is automatically inserted
  when you type the first character.  For example, if you enter the character
  {, this macro inserts the matching character, }.

▪ Justify  ("Justify" on Potpourri PickList)

  This macro is an extension of the WrapPara command.  Like WrapPara, this
  macro formats text in paragraph style between left and right margins:  the
  text is aligned on the left at the effective left margin, and wrapped on the
  right at the right margin.  In addition, though, this macro also justifies
  each line of text at the right margin.

▪ LongstLn  ("LongstLn" on Potpourri PickList)

  This macro locates the longest line in the current file.  When you execute
  this macro, you are positioned on the longest line, and its length is
  displayed on the StatusLine.

▪ Overlay  ("Overlay" on Potpourri PickList)

  This macro is a form of synchronized scrolling that allows you to check
  minor differences between two files.

  This macro will "overlay" the current file with the next file in the ring,
  by switching back and forth between the two files.  This will allow you to
  quickly spot minor differences between the files.  While the macro is
  switching between files, it will allow you to move the cursor around in the
  files, and keep the two files synchronized.

  Before executing the macro, set the screen display for the two files at the
  area of text that you want to compare.  Once you activate the macro, it
  repeatedly overlays the current file with the next file in the file Ring. It
  accomplishes this by continuously switching back and forth between the two
  files.  Differences in similar files become readily apparent, as the screen
  display rapidly alternates where the text is different.

  While the macro is switching between files, only the cursor keys are active
  (<CursorUp>, <CursorDown>, <CursorLeft>, <CursorRight>, <PgUp>, <PgDn>).
  Cursor movement commands are executed simultaneously in both files, allowing
  you to scroll through the files to see any differences.

  To terminate the macro, press <Escape>, or any non-cursor key.  You are then
  placed back in the file from which you initiated the macro.

▪ RePage  ("RePage" on Potpourri PickList)

  This macro places formfeed characters (ASCII 12) throughout a file, based on
  the page size.  (The page size is determined by the value of the
  PrintLinesPerPage variable, which can be set from the Print Menu, by
  selecting "Lines Per Page" under "Set Options").  When you execute this
  macro, it pauses on each line where a formfeed should go, according to the
  page size, and places a cursor bar on that line.  You can then select that
  line on which to place the formfeed, or move the cursor bar to a previous
  line in the file to select a different line on which to place the formfeed.
  After you select the line for the formfeed, the macro resumes, relative to
  the location of the selected line.

▪ ShellExe  ("ShellExe" on Potpourri PickList)

    If a command line is passed, it is simply passed along to the Windows
    ShellExecute function.

    If a block is marked, the first line of the block is passed to the
    Windows ShellExecute function.  You can use this to go to a URL in the
    default browser, or to send an email via the default mailer.

    If you are editing an html file and would like to preview it in a
    Browser window, simply run ShellExe, and as long as the file extension
    is .htm or .html, the file will open in the default browser.

    To go to a web page, mark the following URL and run ShellExe:

    www.semware.com

    To send an email, mark any of the following addresses and run ShellExe:

    james.t.kirk@starfleet.command.org
    James T. Kirk <james.t.kirk@starfleet.command.org>
    mailto:James T. Kirk <james.t.kirk@starfleet.command.org>

▪ ShowKey  ("ShowKey" on Potpourri PickList)

  This macro displays information about the assignable keys on the keyboard.
  When you execute this macro, an information chart is displayed on the
  screen.  You then press a key or key-combination (using the <Ctrl>, <Shift>,
  and <Alt> keys).  If the key is one that the editor recognizes as an
  assignable key, a line is displayed in the chart that identifies the
  following information for that key:

    • screen display character (if applicable)

    • ASCII code

    • scan code

    • hexadecimal representation

    • decimal representation

    • key name (that is, the "name" to use for that key in an editor key
      assignment)

  If the key is not assignable, nothing is displayed when you press that key.


▪ State  ("State" on Potpourri PickList)

  This macro allows you to interactively save the editing environment for the
  current session, or restore the previously-saved environment.

  The State macro can come in handy when you need to interrupt your current
  editing session to view another set of files.  Without exiting from the
  editor, you can save the environment for the current session; load
  additional files and/or change certain editing options; then automatically
  restore the previous environment so you can return to the set of files and
  options as they were previously.

  When you execute this macro, the editor displays a prompt box from which you
  can select "Save State" to save the current editing environment, or select
  "Restore State" to restore the previously-saved environment.

  (For more information on saving and restoring the editing environment, see
  "Saving/Restoring the Editing Environment" in the chapter on
  "Loading, Processing, and Saving Files.")

▪ Sum  ("Sum" on Potpourri PickList)

  This macro sums up a column of numbers that have been marked in the text as
  a column block.  The result is optionally inserted in the text.  Sum handles
  decimal and hexadecimal numbers.  For decimal numbers, it accepts positive
  and negative (identified with a preceding "-" sign) numbers, as well as
  decimal-point fractions.

▪ SynHiUtl  ("SynHiUtl" on Potpourri PickList)

  This macro allows you to dynamically load an arbitrary SyntaxHilite mapping
  (.SYN) file and associate it with the current file.  It also allows you
  to activate or terminate (as appropriate) SyntaxHilite mode for the current
  file.

  When you execute this macro, it displays the name of the mapping (.SYN)
  file associated with the current file (if applicable).  You can then select
  a new mapping file to load and associate with the current file, or you can
  turn SyntaxHilite mode ON or OFF for the current file.

▪ TabUtil  ("TabUtil" on Potpourri PickList)

  This macro converts tab characters in the current file to spaces, or
  converts spaces to tab characters.  When you execute this macro, select
  "DeTab" to convert each tab character to the number of spaces that is equal
  to the current TabWidth.   Alternatively, select "EnTab" to convert each
  occurrence of the number of spaces equal to the TabWidth, to a tab
  character.  To limit the scope of this utility to a block, execute the macro
  from within a marked block.


▪ Uniq  ("Uniq" on Potpourri PickList)

  This macro removes duplicate lines from a file or block.  Only the first
  occurrence of a given line of text is retained; all others are deleted.
  The duplicated lines do not have to be adjacent to each other, and the
  order of the remaining lines in the file is not changed.

  When you execute this command, if the cursor is located on a line that
  includes a column block that is less than 128 characters in width, the
  editor will allow you to limit the comparison for duplicates to text within
  the block.  For any duplicate text that is found, the entire line
  containing that text will be deleted.

  If the cursor is located within a marked block in the current file, the
  editor prompts to confirm whether to limit operation to the block;
  otherwise, it will operate on the entire file.

  If the cursor is not located at the beginning of the block or file, as
  appropriate, the editor prompts for you to select whether to begin
  operation from the beginning of the block or file, or to begin with the
  current line.



▪ vMatch  ("vMatch" on Potpourri PickList)

Show the matching opening/closing character when the cursor is placed on the
corresponding opening/closing character.

Additionally, when an opening/closing character is typed, the matching
opening/closing character is temporarily highlighted.

Characters matched are: )]}


▪ Where  ("Where" on Potpourri PickList or "Where Is" under Util Menu)

  This macro searches one or more drives for files that match an indicated
  filename specification.  A PickList of all matching filenames is displayed,
  allowing you to select file(s) to edit or to delete (or on which to perform
  other available operations).

  When you execute the macro, it prompts you for the filename for which to
  search, with "Search for file:".  Following is the accepted format of the
  filename specification:

    • A complete name or an ambiguous name (with wildcard characters) can be
      specified, and can optionally include drive and/or path information.

    • Multiple filename specifications can be entered.

    • One or more drives can be specified.  If particular drive(s) are
      specified, the macro will limit the search to the indicated drive(s);
      if no drive is specified, all drives (for which the macro is configured
      to search) will be searched.  The drive(s) can be specified only as the
      beginning character(s) of the file specification entry; the indicated
      drive(s) will apply to all filename specifications that are entered.

    • If a particular directory is included in a filename specification, the
      macro will limit the search for that filename to the indicated
      directory and all of its subdirectories; if no directory is specified,
      the macro will search all directories and subdirectories of each drive
      that is searched.

  Once you enter a filename specification, the macro then searches the
  applicable drives and directories.  All matching filenames are displayed in
  a PickList.  You can select a particular file to edit or delete by
  positioning the cursor bar on that filename in the PickList, and pressing
  <Enter>.  Or you can tag multiple files (by pressing the <Spacebar> with the
  cursor bar positioned on a file) on which to operate.  The PickList is
  automatically removed once the indicated operation is performed.  Otherwise,
  to remove the PickList (and terminate the command), press <Escape>.  Or, to
  terminate the macro and release any memory used to store the PickList (if
  one exists), press <Alt X>.

  While a search is in progress, you can immediately stop the search by
  pressing <Escape>.  A PickList will be presented of those filenames that
  were located before the search was terminated.

  While the "Search for file:" prompt is displayed, a number of options are
  available:

    • To display an initial HelpScreen for the macro, press <F1>.

    • To configure several options of the macro, press <Alt C>.  You can then
      select the drives that are to be searched (when no drives are included
      in the specification entry); you can choose to add the Where macro to
      your AutoLoad List; or you can choose to remove the Where macro from
      your AutoLoad List.

    • To re-display the PickList from a previous search, press <Alt L>.

  While a PickList is displayed, other options are available:

    • To display additional HelpScreen information about other file
      operations available from the PickList, press <F1>.

    • To sort the list of entries in the PickList, press <Ctrl S>.  A pop-up
      menu allows you to select the sorting sequence.

    • To tag the file on which the cursor bar is positioned, press the
      <Spacebar>.

    • To display the entire directory containing the file on which the cursor
      bar is positioned, press <Alt L>.

▪ Wipe  ("Wipe" on Potpourri PickList)

  This macro file provides two macros:  MoveWipe, which is a variation of the
  MoveBlock command; and CutWipe, which is a variation of the Cut (to the
  System ClipBoard) command.  When you execute Wipe from the Potpourri
  PickList, MoveWipe is assigned to <AltShift M>, and CutWipe is assigned to
  <Shift Grey*>.  These macros behave similarly to the commands on which they
  are based, except that the area of text from which the block is moved or
  cut, is filled with spaces.  Also, with MoveWipe, if a column block is
  moved, the editor overlays existing text with the contents of the block,
  rather than inserting the contents of the block into its new location.





ExistBufferVar()

Determines if the specified buffer variable exists.

Syntax:     INTEGER ExistBufferVar(STRING buffer_var_name [, INTEGER
                                   buffer_id])

            • buffer_var_name is the name of the buffer variable to find.

            • buffer_id is an optional buffer id, as returned by
              GetBufferId().

Returns:    Non-zero if buffer_var_name exists; otherwise, zero (FALSE).


Notes:      If buffer_id is not specified, the current buffer is assumed.

See Also:   DelBufferVar(), GetBufferInt(), GetBufferStr(), SetBufferInt(),
            SetBufferStr()





ExistGlobalVar()

Verifies that the specified session global variable exists.

Syntax:     INTEGER ExistGlobalVar(STRING var_name)

            • var_name is the name of the session global variable for which
              to check.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Examples:

            if ExistGlobalVar("myvar")
                Message("myvar exists!")
            else
                Message("myvar does not exist!")
            endif

See Also:   GetGlobalInt(), GetGlobalStr(), SetGlobalInt(),
            SetGlobalStr(), DelGlobalVar()





Exit()

Exits the editor, allowing the user to optionally save modified files, if
there are any.

Syntax:     INTEGER Exit()

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If no modified files exist, this command causes the editor to exit
            without further prompting.

            For every modified file loaded into the editor, this command
            issues the protected quit command, QuitFile().  If the user
            selects cancel as a response to the QuitFile() menu, the exit
            operation is halted.

            The _ON_EXIT_CALLED_ event is called at the beginning of this
            command.  (See the Hook() command for a description of this
            event.)

            If the SaveState variable is ON, the editor's state is saved
            when this command begins execution.

See Also:   SaveAllAndExit(), QuitFile(), AbandonEditor(), Hook()

            Variables:  SaveState





Exiting from the Menu System

If you select a sub-menu item that executes a command, the editor
automatically deactivates the Menu and returns you to the editing session,
once the command is completed or cancelled.  To otherwise exit from the
pull-down Menu system, press <Escape> until the main Menu is deactivated.  You
can then resume editing.

If the editor is configured to continually display the main Menu, the Menu
system is deactivated once there is no longer a main Menu option that is
highlighted.  If configured otherwise, the Menu system is deactivated once the
Main menu is removed from the screen.





ExpandPath()

Expands the specified ambiguous path to a complete path specification.

Syntax:     STRING ExpandPath(STRING partial_path [, INTEGER respect_case])

            • partial_path is the ambiguous or incomplete path to expand.

            • respect_case is an optional integer specifying whether
              ExpandPath() should respect the case of an existing filename.
              If respect_case is zero (or not specified) ExpandPath()
              performs the Lower() command on the returned string.

              If respect_case is non-zero, ExpandPath() will retain the case
              of the filename as it exists on disk.

Returns:    The expanded path, or the empty string if the path could not be
            expanded.

Notes:      If the name passed to ExpandPath() is a directory name, "\*.*" is
            appended to the returned string.

            The long filename value is returned, if applicable.

            The Lower() command is issued on the return string just before
            returning it to the user, if respect_case is not specified
            or FALSE (zero).

Examples:

            Given:

                string st[_MAXPATH_], and the current path is "c:\tse\doc\ref"
                A file on disk named "Bar" exists.

            then:

                st = ExpandPath("foo")   // st is "c:\tse\doc\ref\foo"

                st = ExpandPath("bar")   // st is "c:\tse\doc\ref\bar"

                st = ExpandPath("bar", TRUE), // st is "c:\tse\doc\ref\Bar"

See Also:   SearchPath(), SplitPath()





ExpandTabs

Expands TAB characters (ASCII 9) to spaces on the display (but not in the
file).

Values:     BOOLEAN

Default:    ON

Notes:      This expands the tab character to spaces only on the display.  The
            TAB character remains unchanged in the file.  The number of spaces
            shown will depend on the position of the tab within the line and
            the setting of the TabType and TabWidth variables.

Affects:    Many commands

See Also:   TabType, TabWidth





ExpandTabsToSpaces()

Expand hard tab characters on the current line to spaces.

Syntax:     ExpandTabsToSpaces()

Returns:    Nothing.

Notes:      The current TabWidth is used when expanding hard tabs to spaces.

Examples:

            //Expand all tabs to spaces in the current file:
            proc ExpandTabsCurrentFile()
                PushPosition()
                BegFile()
                repeat
                    ExpandTabsToSpaces()
                until not Down()
                PopPosition()
            end

See Also:   EntabCurrLine()

            Variables:  TabWidth





External Macros Vs. the User-Interface Macro

There are two fundamental types of Compiled Macro files:  external and
user-interface.  External macro source files have extensions of ".S", whereas
user-interface macro source files have extensions of ".UI".

An external macro file contains procedures, key assignments, help text, and
menus.  The source file is compiled as an object file with an extension of
".MAC", and the elements in the Compiled Macro file become active when the
macro (.MAC) file is loaded or executed.

A user-interface macro file can contain the same elements as an external
macro file.  It can also contain editor variable (configuration) settings,
though this is not generally recommended.  A user-interface file is installed
in the editor, and the elements in the user-interface automatically become
active when the editor is started.

(For more information on the elements included in macro files, see the
chapters on "Macro Language Syntax" and "Using Macro Language Features."
Also see the chapter on "Fully Customizing the Editor" in the
User's Guide.)

External Macro Files
────────────────────

External macro files are compiled from ".S" source files by the SAL compiler
to create executable files with an extension of ".MAC".  They must be
explicitly loaded into the editor before they can be executed.  The
LoadMacro() and ExecMacro() commands are used to load and execute external
macro files.  They can subsequently be purged during an editing session if
they are no longer needed.

External macro files may contain the following:

▪ Public/Private macros

  Public macros are global in scope and are declared with the "public"
  keyword.  Public macros are added to the Public macros list when the macro
  file containing them is loaded or executed.  You can execute Public macros
  by name with the ExecMacro() command.  Public macros also display in the
  Public macros PickList, allowing you to interactively select them, without
  having to type their name.

  Private macros are local in scope.  Generally, any macro without the
  "public" keyword is a private macro.  Certain exceptions to this rule are
  noted below.  Private macros can only be called by other macros within the
  same macro file.  Private macros can not be directly executed interactively.

▪ Main macro

  The Main macro is a special macro that is always public.  If present in a
  macro file, it is automatically executed when a macro filename is passed to
  ExecMacro(), either interactively or via a macro.  External macro files are
  not required to have a Main macro.

  If the specified macro file is not already loaded when ExecMacro() is
  called, and the macro file to execute contains a Main macro, that macro is
  invoked just after the macro file is loaded and the WhenLoaded macro
  executed (if one exists in the macro file).  If the macro file does not have
  a Main macro, the macro file is loaded and only the WhenLoaded macro is
  executed (if one exists).

  In contrast to ExecMacro(), the LoadMacro() command does not execute the
  Main macro even if one exists in the indicated macro file.

▪ WhenLoaded macro

  The WhenLoaded macro is another special macro type.  As with the Main macro,
  the WhenLoaded macro is not required.

  The WhenLoaded macro, if one exists in the macro file, is automatically
  executed when a Compiled Macro file is loaded into the editor from disk
  (that is, the first time the macro file is loaded during an editing
  session, or re-loaded after the macro file has been purged).

  When LoadMacro() is called and the macro file to load has a WhenLoaded
  macro, that macro is invoked just after the macro file is loaded.  (If the
  specified macro file is already loaded into the editor when LoadMacro() is
  called, the macro file is reloaded and the WhenLoaded macro is executed.)

  When ExecMacro() is called and the specified macro file is not already
  loaded, the WhenLoaded macro (if present in the macro file) is invoked
  first, followed by the Main macro (if present).  If the specified macro file
  is already loaded into the editor when ExecMacro() is called, the WhenLoaded
  macro is not executed, but the Main macro is.

▪ WhenPurged macro

  The WhenPurged macro is a special macro that is called whenever an external
  macro file is purged.  It is useful for removing buffers created by the
  macro file that contains it, or for handling any cleanup that might be
  necessary.

▪ Key assignments

  Key assignments can also be included in external macro files.  When the
  macro file is loaded, any key assignments in the included macros override
  the current assignments.  When the macro file is purged, the previous key
  assignments are restored.

▪ Help

  Help definitions (helpdefs) may be placed throughout an external macro file.
  Help definitions are private and can only be referenced by other macros in
  the same macro file.

▪ Menus

  Menu definitions may also be placed throughout an external macro file.
  Menus are private and can only be referenced by other macros in the same
  macro file.


The User-Interface Macro File (TSE.UI)
──────────────────────────────────────

User-interface macro files are created in the same manner as external macro
files; however, you place the source in a file with an extension of ".UI"
(rather than ".S").  A key difference between external macro files and
user-interface files is that a user-interface file is installed in the
editor, so there is no need to load or execute the macro file to gain access
to any commands, menus, or help that may be defined by the macro.  Until
replaced (by installing a new user interface file), these are essentially a
part of the editor.  This is the primary advantage of installing a
user-interface macro file into the editor.  However, because user-interface
macros are installed in the editor, they cannot be purged.

Another difference between the two types of Compiled Macro files is that the
user-interface macro file may contain an editor variable configuration
section (though this is not generally recommended).  This configuration
section is denoted by the keywords "Config" and "EndConfig".

User-interface macro files may contain the following:

▪ Macros

  The macros in a user-interface file may be assigned to keys, menus, or
  called by other macros (that also reside in the user-interface macro file).
  The major difference between these macros and macros in external macro
  files, is that these macros are available immediately upon editor startup.

▪ Main macro

  The Main macro in a user-interface file behaves somewhat differently than a
  corresponding Main macro in an external macro file.  If a Main macro exists
  in a user-interface macro file that is installed in the editor, the Main
  macro is invoked immediately after the first file has been loaded into the
  editor.

▪ WhenLoaded macro

  The WhenLoaded macro in a user-interface file behaves somewhat differently
  than a corresponding WhenLoaded macro in an external macro file.  If this
  macro exists in a user-interface macro that is installed in the editor, the
  WhenLoaded macro is invoked just after the editor has been loaded, but
  before the command-line specifications and any files are processed.  Thus,
  the WhenLoaded macro in a user-interface file can actually process the
  command line, and add to or remove files and/or options from the command
  line.  The WhenLoaded macro in a user-interface macro file is often used to
  perform certain setup tasks before you begin your editing session.


  An exception to the above is the -i (Augment Load Dir) command-line option.
  If present on the command line when the editor is started, the -i option
  will be processed before the WhenLoaded macro is invoked.

▪ WhenPurged macro

  In a user-interface file, the WhenPurged macro (if it exists) is called
  when the editor is terminating, just before the _ON_ABANDON_EDITOR_ event
  is called.

▪ Key assignments

  Key assignments can also be included in user-interface macro files.  Key
  assignments in the user-interface file may be placed anywhere throughout the
  file except in the editor variable configuration section.  These key
  assignments are installed in the editor and are always available unless
  overridden by another key assignment enabled by the loading of an external
  macro file.

▪ Help

  Help definitions (helpdefs) may be placed throughout the user-interface
  macro file.  Help definitions are private and can only be referenced by
  other macros in the user-interface macro file.

▪ Menus

  Menu definitions may also be placed throughout the user-interface macro
  file.  They are also private and can only be referenced by macros in the
  user-interface macro file.  Although it is not required, most user-interface
  macro files contain a menu definition called "MainMenu".

  In the standard editor user interface, the MainMenu is bound to both the
  <F10> and the <Escape> keys, and serves as the primary pull-down Menu system
  in the editor.  In most situations, you will only want to modify the
  contents of this MainMenu to include or exclude certain commands or macros
  that you wish to have available through the pull-down Menu.

▪ Editor Variable Configuration Section

  The editor variable configuration section is defined by the "Config" and
  "EndConfig" keywords.  This is an optional section that can be used to make
  editor variable assignments.  Most editor variables can be set in this
  section.  There are a few editor variables which can ONLY be set in this
  section (as they only take effect when the editor is initially started),
  and there are other editor variables which cannot be set in this section.
  (For more information, see the descriptions of the variables (which note
  restrictions for the variable) in the chapter on "Editor Variables.")

  Use of a configuration section in the user-interface file to set or modify
  editor variable assignments is not recommended.  In the standard version of
  the editor, this section is not used.  An alternate, easier method for
  setting editor variables is provided through IConfig, the editor's
  menu-driven Interactive Configuration facility.  It is recommended that you
  use IConfig to set editor variables, and then install the settings into the
  editor by selecting "Save Current Settings" under the Options Menu.  Note
  that these two methods for setting editor variables are not compatible with
  each other, so you should not use both.  (For more information on using
  IConfig, see the chapter on "Configuring the Editor Interactively" in the
  User's Guide.)


(For more information on customizing the user-interface macro file, see the
chapter on "Fully Customizing the Editor" in the User's Guide.)





fClose()

Low-level file-access command:  closes a specified file using its handle.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER fClose(INTEGER handle)

            • handle is the handle, as assigned by the operating
              system, of the file to be closed.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Use this command to close files opened by the low-level
            file-access commands fOpen() or fCreate().


Examples:

            // Write the current date and time to a file
            // Assume success if > 0 bytes written
            // Returns TRUE or FALSE
            integer proc SaveDateAndTime(string fn)
                integer h, bytes

                h = fCreate(fn)
                if h == -1
                    return (FALSE)
                endif
                bytes = fWrite(h, GetDateStr() + ' ' + GetTimeStr())
                fClose(h)
                return (bytes > 0)
            end

See Also:   fCreate(), fOpen(), fRead(), fReadFile(), fSeek(), fWrite(),
            fWriteFile()





fCreate()

Low-level file-access command:  creates a new file on disk and returns
the associated handle.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER fCreate(STRING filename [, INTEGER attributes])

            • filename is name of the file to create.

            • attributes are the optional desired attributes for the
              newly-created file.  attributes may be a combination of the
              following:

              • _NORMAL_ specifies the file can be read from or written
                to.

              • _READONLY_ specifies the file can be read from but not
                written to.

              • _HIDDEN_ specifies the file is hidden and does not appear
                in a file directory listing.

              • _SYSTEM_ specifies the file is a system file.

              • _ARCHIVE_ specifies the file is marked for archiving.

              If not specified, attributes defaults to _NORMAL_.

Returns:    The handle, as assigned by the operating system, of the
            newly-created file; or -1, if the file could not be created.

Notes:      If the file specified by filename already exists, it is first
            erased (truncated).

            Until it is closed, you have read/write access to a file created
            with this command.

            The specified attributes are assigned to the file when it is
            closed.


Examples:

            // Write the current date and time to a file
            // Assume success if > 0 bytes written
            // Returns TRUE or FALSE
            integer proc SaveDateAndTime(string fn)
                integer h, bytes

                h = fCreate(fn)
                if h == -1
                    return (FALSE)
                endif
                bytes = fWrite(h, GetDateStr() + ' ' + GetTimeStr())
                fClose(h)
                return (bytes > 0)
            end

See Also:   fClose(), fDup(), fDup2(), fOpen(), fRead(), fReadFile(),
            fSeek(), fWrite(), fWriteFile(), FileExists()





fDup()

Low-level file-access command:  creates a new file handle by duplicating an
existing handle for a currently-open file.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER fDup(INTEGER handle)

            • handle is a file handle previously created by fOpen(),
             fCreate(), fDup(), or fDup2().

Returns:    The new handle, as assigned by the operating system, for the
            specified file handle; or -1, if the handle could not be
            duplicated.

Notes:      The new file handle created by fDup() shares the same file
            read/write pointer with the original handle.  That is, if the
            file read/write pointer is changed using one handle (for example,
            by fSeek()), the change is reflected when using the alternate
            handle.

Examples:

            // redirect stdout and stderr to file fn
            integer proc Redirect(string fn, var integer _fd1,
                                  var integer _fd2)
                integer fd1, fd2, fd_out, fd_err

                fd_out = fCreate(fn)
                fd1 = fDup(_STDOUT_)
                fDup2(fd_out, _STDOUT_)

                fd_err = fd_out
                fd2 = fDup(_STDERR_)
                fDup2(fd_err, _STDERR_)

                fClose(fd_out)
                _fd1 = fd1
                _fd2 = fd2
                return (TRUE)
            end

            // restore normal stdout and stderr
            integer proc CloseRedirect(integer fd1, integer fd2)
                fDup2(fd1, _STDOUT_)
                fClose(fd1)

                fDup2(fd2, _STDERR_)
                fClose(fd2)

                return (TRUE)
            end

            proc main()
                integer h1, h2

                Redirect("foo.bar", h1, h2) //redirect stdout to foo.bar
                lDos("grep", "if *.*")     //output of this command goes
                                           //to foo.bar, same as if we
                                       //ran Dos("grep if *.* >foo.bar")
                CloseRedirect(h1, h2)      //restore stdout
            end

See Also:   fOpen(), fCreate(), fDup2()





fDup2()

Low-level file-access command:  forces a file handle to be a duplicate handle
for another currently-open file.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER fDup2(INTEGER first_handle, INTEGER second_handle)

            • first_handle is the file handle for which to create a
              duplicate.

            • second_handle is the file handle to force to be a duplicate
              of first_handle.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      second_handle shares the same file read/write pointer as
            first_handle.  That is, if the file read/write pointer is
            changed using one handle (for example, by fSeek()), the change is
            reflected when using the alternate handle.

            fDup2() creates a new handle with the value of second_handle.  If
            the file associated with second_handle is open when fDup2() is
            called, the file is closed.

Examples:

            See the fDup() command for an example.

See Also:   fOpen(), fCreate(), fDup()





FFAttribute()

Returns the attribute of the last file found by a find-file command (such as
by the FindFirstFile() command).

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER FFAttribute()

Returns:    The attribute of the last file found via any of the find-file
            commands.

Notes:      Supported attribute values returned by this command are:

            • _NORMAL_ indicates files that can be read from or written to.

            • _READONLY_ indicates files that can be read from but not
              written to.

            • _HIDDEN_ indicates files that are hidden and do not appear in
              file directory listings.

            • _SYSTEM_ indicates files that are system files.

            • _VOLUME_ indicates the volume label entry.

            • _DIRECTORY_ indicates directory entries.

            • _ARCHIVE_ indicates files that are marked for archiving.

Examples:

            integer attribute

            if FindThisFile("foo.bar", _HIDDEN_|_SYSTEM_|_READONLY_)
                attribute = FFAttribute()
            endif

See Also:   FindFirstFile(), FindNextFile(), FindFileClose(),
            FindThisFile(), FFName(), FFSize(), FFDate(), FFDateStr(),
            FFTime(), FFTimeStr()





FFDate()

Returns the date, in encoded format, of the last file found by a find-file
command (such as by the FindFirstFile() command).

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER FFDate()

Returns:    The date of the last file found via any of the find-file
            commands.

Notes:      The date is returned in an encoded format that is suitable for
            comparison of dates returned by this command and the PBDate()
            command.

Examples:

            integer date

            if FindThisFile("foo.bar", _HIDDEN_|_SYSTEM_|_READONLY_)
                date = FFDate()
            endif

See Also:   FindFirstFile(), FindNextFile(), FindFileClose(),
            FindThisFile(), FFName(), FFSize(), FFAttribute(),
            FFDateStr(), FFTime(), FFTimeStr()





FFDateStr()

Returns the date, in displayable format, of the last file found by a
find-file command (such as by the FindFirstFile() command).

This command is intended for ADVANCED USAGE.

Syntax:     STRING FFDateStr()

Returns:    The date of the last file found via any of the find-file commands.

Notes:      The date is returned in a string format that is suitable for
            displaying.

Examples:

            string date[8]

            if FindThisFile("foo.bar", _HIDDEN_|_SYSTEM_|_READONLY_)
                date = FFDateStr()
            endif

See Also:   FindFirstFile(), FindNextFile(), FindFileClose(),
            FindThisFile(), FFName(), FFSize(), FFAttribute(), FFDate(),
            FFTime(), FFTimeStr()





FFName()

Returns the filename of the last file found by a find-file command (such as by
the FindFirstFile() command).

This command is intended for ADVANCED USAGE.

Syntax:     STRING FFName()

Returns:    The filename of the last file found via any of the find-file
            commands.

Notes:      The filename that is returned includes the name and the extension,
            if any.  The drive and/or directory of the file is not included.

Examples:

            string fn[_MAXPATH_]

            if FindThisFile("*.*", _HIDDEN_|_SYSTEM_|_READONLY_)
                fn = FFName()
            endif


See Also:   FindFirstFile(), FindNextFile(), FindFileClose(),
            FindThisFile(), FFSize(), FFAttribute(), FFDate(),
            FFDateStr(), FFTime(), FFTimeStr()





FFSize()

Returns the size of the last file found by a find-file command (such as by the
FindFirstFile() command).

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER FFSize()

Returns:    The size of the last file found via any of the find-file commands.

Notes:      This command is valid only for files less than 2 gigabytes in
            size.

Examples:

            integer size

            if FindThisFile("foo.bar", _HIDDEN_|_SYSTEM_|_READONLY_)
                size = FFSize()
            endif

See Also:   FindFirstFile(), FindNextFile(), FindFileClose(),
            FindThisFile(), FFName(), FFAttribute(), FFDate(),
            FFDateStr(), FFTime(), FFTimeStr()





FFTime()

Returns the time, in encoded format, of the last file found by a
find-file command (such as by the FindFirstFile() command).

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER FFTime()

Returns:    The time of the last file found via any of the find-file commands.

Notes:      The time is returned in an encoded format that is suitable
            for comparison of dates returned by this command and the
            PBTime() command.

Examples:

            integer time

            if FindThisFile("foo.bar", _HIDDEN_|_SYSTEM_|_READONLY_)
                time = FFTime()
            endif

See Also:   FindFirstFile(), FindNextFile(), FindFileClose(),
            FindThisFile(), FFName(), FFSize(), FFAttribute(), FFDate(),
            FFDateStr(), FFTimeStr()





FFTimeStr()

Returns the time, in displayable format, of the last file found by a
find-file command (such as by the FindFirstFile() command).

This command is intended for ADVANCED USAGE.

Syntax:     STRING FFTimeStr()

Returns:    The time of the last file found via any of the find-file commands.

Notes:      The time is returned in a string format that is suitable for
            displaying.

Examples:

            string time[8]

            if FindThisFile("foo.bar", _HIDDEN_|_SYSTEM_|_READONLY_)
                time = FFTimeStr()
            endif

See Also:   FindFirstFile(), FindNextFile(), FindFileClose(),
            FindThisFile(), FFName(), FFSize(), FFAttribute(), FFDate(),
            FFDateStr(), FFTime()





FileChanged()

Determines the current file's or buffer's modified (changed) status.

Syntax:     INTEGER FileChanged([INTEGER change_flag])

            • change_flag, if specified, is either TRUE or FALSE.

Returns:    The file's current modified status, as of the time this command is
            invoked.  If the file is not modified, zero (FALSE) is returned.
            Otherwise, a non-zero number that represents the current change
            state.  On each change, this number is incremented.

Notes:      If TRUE is passed to FileChanged(), the file is marked as
            modified.  If FALSE is passed, the file is marked as unmodified.

            Use with caution.  The modified status of a file is the method the
            editor uses to detect that a file has been changed.  If a modified
            file is marked as unmodified with FileChanged(), normal file
            exiting routines will not detect changes to the file.

Examples:

            // A LoseChanges command.
            proc LoseChanges()
                if FileChanged()
                    if YesNo("Lose Changes?") == 1 // Yes selected
                        FileChanged(FALSE)
                    else
                        return ()
                    endif
                endif
                QuitFile()
            end
See Also:   QuitFile(), SaveFile(), ChangedFilesExist()





FileExists()

Verifies that the specified file exists on disk, and returns the file's
attributes.

Syntax:     INTEGER FileExists(STRING fn)

            • fn is the name of the file for which to check on disk.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Zero is returned if the specified fn does not exist on disk.

            The filename can contain wildcard (? and *) characters.  If this
            is the case, the attributes of the first matching file found will
            be returned.

            If the drive and/or path are omitted, the current drive and/or
            path are assumed.

            The following pre-defined editor constants can be used to
            determine what attributes are associated with a particular file:

                                              Associated
                          Bit               Editor Constant
                _______________________     _______________

                0 - Read-only Attribute     _READONLY_
                1 - Hidden Attribute        _HIDDEN_
                2 - System Attribute        _SYSTEM_
                3 - Volume Attribute        _VOLUME_
                4 - Directory Attribute     _DIRECTORY_
                5 - Archive Attribute       _ARCHIVE_

Examples:

            The following code shows how to determine if particular attributes
            exist for a specified file:

            integer attribute

            attribute = FileExists("some.fle")
            // if the file exists at all...
            if attribute <> 0
                // is it readonly?
                if attribute & _READONLY_
                    ...
                endif

                // is it readonly or hidden or system?
                if attribute & (_READONLY_ | _HIDDEN_ | _SYSTEM_)
                    ...
                endif
            endif

            // If the current file being edited exists on disk, erase
            // it, and force the file's modified (changed) status to
            // be TRUE.
            if FileExists(CurrFilename())
                EraseDiskFile(CurrFilename())
                FileChanged(TRUE)
            endif

See Also:   EraseDiskFile(), SetFileAttr()





FileLocking

Determines whether the editor locks files that are loaded.


Values:     INTEGER_NONE_ disables file-locking.

            • _READONLY_LOCKING_ enables Read-Only locking.

            • _HANDLE_LOCKING_ enables Handle locking.

Default:    _NONE_


Notes:      • When FileLocking is set to _READONLY_LOCKING_, the editor
              locks each file that is loaded by setting its read-only
              attribute.

              If the editor terminates abnormally (such as it would if you
              turn off or reboot your computer while in the middle of an
              editing session), the read-only attribute would not be removed
              from any files that were loaded in that session.  In such case,
              the read-only attribute would have to be removed manually. (The
              editor FileManager can be used to accomplish this.)

            • When FileLocking is set to _HANDLE_LOCKING_, the editor locks
              each file by keeping its associated handle open until the file
              is closed (that is, removed from the editor).  (Normally, the
              editor releases the handle associated with a file once the file
              is loaded into the editor.)

              Files locked in this manner can still be read by other
              programs, but write access will be denied to those programs.


            For more information on file-locking, see the chapter on
            "Loading, Processing, and Saving Files" in the User's Guide.

Affects:    EditFile(), EditThisFile(), and all commands that close files.

See Also:   Commands: LockCurrentFile(), UnLockCurrentFile()





Files Needed By Iconfig

IConfig is written in the editor's own macro programming language, SAL.  To
keep the size of the editor executable program itself as small as possible,
IConfig is provided as an external macro.  For IConfig to be accessible from
within the editor, the following file must be available:

    ICONFIG.MAC         The IConfig Compiled Macro file

When you invoke IConfig, the editor successively searches the following
directories to locate this file:

    1.  The current directory

    2.  The directories indicated by the TSEPath variable, as well as the
        subdirectory MAC\ (if one exists) of each directory indicated by
        TSEPath

        (For more information on the TSEPath variable, see
        "Path(s) for Supplemental Files" under "System/File Options" earlier
        in this chapter.)

    3.  The editor load directory, as well as the subdirectory MAC\ (if one
        exists) of the editor load directory


(For more information on where the IConfig macro (ICONFIG.MAC) is placed when
you install the editor, see the chapter on
"Installation of The SemWare Editor Professional.")





Files Needed By Spellcheck

To use SpellCheck, the following files must be available to the editor:

    SPELLCHK.MAC        The SpellCheck Compiled Macro file

    SEMWARE.LEX         The standard SpellCheck word list

and, optionally:

    USER.LEX            The user-defined word list


When you invoke SpellCheck, the editor successively searches the following
directories to locate these files:

    1.  The current directory

    2.  The directories indicated by the TSEPath variable; as well as the
        subdirectory MAC\ (if one exists) of each TSEPath directory to locate
        SPELLCHK.MAC, and the subdirectory SPELL\ (if one exists) of each
        TSEPath directory to locate the word-list (.LEX) files

        (For more information on the TSEPath variable, see
        "Path(s) for Supplemental Files" under "System/File Options" in the
        chapter on "Configuring the Editor Interactively.")

    3.  The editor load directory; as well as the subdirectory MAC\ (if one
        exists) of the editor load directory to locate SPELLCHK.MAC, and the
        subdirectory SPELL\ (if one exists) of the editor load directory to
        locate the word-list (.LEX) files


(For more information on where the SpellCheck files are placed when you
install the editor, see the chapter on
"Installation of The SemWare Editor Professional.")





FillBlock()

Fills a marked block with the specified string.

Syntax:     INTEGER FillBlock([STRING s])

            • s is the optional string with which to fill the block.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      If a marked block does not exist in the current file, no action
            occurs and zero is returned.

            If a fill string is not passed, FillBlock() will prompt for a
            fill string.  If <Escape> is pressed, or no string is given
            before pressing <Return>, zero is returned.

            FillBlock() is useful for filling an area of existing text with
            spaces; thus accomplishing a deletion of text without surrounding
            text collapsing to "fill the gap", as will normally happen with
            block deletions.

            This command includes a history list of previous entries passed to
            it.  See AddHistoryStr() for additional information.

Examples:

            Fill a block with the string "Live long and prosper"

            FillBlock("Live long and prosper")

See Also:   MarkColumn(), AddHistoryStr(), isBlockInCurrFile(),
            isBlockMarked()

            Variables:  Marking





Find()

Searches for the specified text in the current file.

Syntax:     INTEGER Find([STRING search, STRING options])

            • search is the optional string for which to search.

            • options is the optional string containing the Find options;
              multiple options may be specified in any combination.  Supported
              values for options are:

              • b - search backwards from the current position.  (The search
                begins one character before the current cursor position.)

              • l - limit the search to the marked block.

              • i - ignore differences between upper-case and lower-case
                characters.

              • w - limit the search to whole words.  (See the WordSet
                variable for what constitutes a word.)

              • x - recognize regular expression characters in the search
                string.

              • g - start the search at the beginning of the file.

              • c - limit the search to the current line.

              • a - search all files currently loaded in the editor's Ring of
                files.  The current file is searched from the current
                position, and all other loaded files are searched from the
                beginning of each file.

              • v - display a PickList of all lines containing the search
                string.

              • ^ - limit the search to the beginning of the line.

              • $ - limit the search to the end of the line.

              • + - start the search at the next character, rather than
                starting at the current position.  (This option is valid only
                with a forward search.)

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      Either both parameters must be passed, or no parameters can be
            passed.

            If no parameters are passed, Find() prompts for the search string
            and Find() options.  In the prompt for options, Find() initially
            uses the default options as specified by the FindOptions
            variable.  Subsequent finds use the previously entered (or passed
            via a macro) options as the default for the prompt.

            Certain combinations of options affect each other, as follows:

            • If both b and g are specified, the search starts at the end of
              the file.

            • If both l and g are specified, the search starts at the
              beginning of the marked block.

            • If b, l, and g are specified together, the search starts at the
              end of the marked block.

            • If both c and g are specified, the search starts at the
              beginning of the current line.

            • If b, c, and g are specified together, the search starts at the
              end of the current line.

            • If both a and g are specified, all files (including the current
              file) are searched from the beginning of each file.

            Zero is returned if <Escape> is pressed at either prompt, or if
            the search string is not found.

            Macros can use the lFind() command to search for text in a macro
            without the side effects of placing the search string and options
            string in the Find() histories, and setting the RepeatFind()
            command's execution strategy.

            This command includes a history list of previous entries passed to
            it.  See AddHistoryStr() for additional information.

            For more information on regular expressions, see the chapter on
            "Search Features:  Finding and Replacing Text" in the
            User's Guide.

Examples:

            A Find() that ALWAYS uses the current FindOptions variable
            setting:

            integer proc mFind()
               string needle[40]

               return (Ask("Search for:", needle, _FIND_HISTORY_)
                     and Find(needle, Query(FindOptions)))
            end

            The next example is a macro to find the next occurrence of the
            word at the current cursor position.  It uses the
            GetWordAtCursor() macro presented in the GetMarkedText() command
            example.

            Since Find() normally starts at the current position, use the
            "Next" option (+) to force Find() to begin its search starting at
            the next character position.  (Otherwise, the Find() would never
            move from its current position.)

            If there is not a word at the current position, the normal Find()
            command is called, and the user will be prompted for a search
            string.

            integer proc mFindWordAtCursor()
                string word[80]

                word = GetWordAtCursor()
                return (iif(Length(word),
                      Find(word, Query(FindOptions) + "+"),
                      Find()))
            end

See Also:   Replace(), RepeatFind(), lFind(), lReplace(), lRepeatFind(),
            AddHistoryStr(), GetFoundText()

            Variables:  Beep, FindOptions, MaxHistorySize, WordSet





FindFileClose()

Closes a specified search handle that was previously opened using the
FindFirstFile() command.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER FindFileClose(INTEGER search_handle)

            • search_handle is a search handle returned by the FindFirstFile()
              command.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      The FindFileClose() command should always be called when search
            processing is complete following the FindFirstFile() and
            FindNextFile() commands.  This will release that search handle to
            the operating system.

Examples:

            See the FindFirstFile() command for an example.

See Also:   FindFirstFile(), FindNextFile(), FindThisFile(), FFName(),
            FFSize(), FFDate(), FFDateStr(), FFTime(), FFTimeStr(),
            FFAttribute()





FindFirstFile()

Searches a directory for the first file or directory whose name and attributes
match the specified name pattern and attributes; and opens a search handle
(that can be used for subsequent searches).

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER FindFirstFile(STRING filename, INTEGER attributes)

            • filename is the filename pattern for which to search.

            • attributes are the optional attributes to use when searching.
              attributes may be a combination of the following:

              • _NORMAL_ specifies a file that can be read from or written to.

              • _READONLY_ specifies a file that can be read from but not
                written to.

              • _HIDDEN_ specifies a file that is hidden and does not appear
                in a file directory listing.

              • _SYSTEM_ specifies a file that is a system file.

              • _VOLUME_ specifies a volume label entry.

              • _DIRECTORY_ specifies a directory entry.

              • _ARCHIVE_ specifies a file that is marked for archiving.

Returns:    The search handle of the first file or directory that matches
            filename, if successful; -1 on failure.

Notes:      The search handle that is returned by the FindFirstFile() command
            is used by the commands FindNextFile() and FindFileClose().

            The FindFileClose() command should always be called when search
            processing is complete following the FindFirstFile() and
            FindNextFile() commands.

            To retrieve information about the found file, use the FF-type
            commands, such as FFName() and FFDate().

            This command is intended for use with an ambiguous file
            specification.  For a similar command intended for finding a
            unique file, and that does not require you to close the search
            handle, see the FindThisFile() command.

            If you specify any combination of _SYSTEM_, _HIDDEN_, or
            _DIRECTORY_, this command returns normal files in addition to
            files with the specified attribute(s).  If you want to work only
            with files with the specified attribute(s), you must examine the
            specific attribute for each file, via the FFAttribute() command.

            To search for all files, an attribute of -1 can be used.

Examples:

            // Display all files that have an extension of '.c'

            integer handle

            handle = FindFirstFile("*.c", -1)   //allocate search handle
                                                //search for ALL files
            if handle <> -1
                repeat
                    WriteLine(FFName())
                until not FindNextFile(handle, -1)  //get next file
                FindFileClose(handle)          //release search handle
            endif

See Also:   FindNextFile(), FindFileClose(), FindThisFile(), FFName(),
            FFSize(), FFDate(), FFDateStr(), FFTime(), FFTimeStr(),
            FFAttribute(), AddFFInfoToBuffer()





FindHistoryStr()

Locates the relative position of a specified item (string) in the History
Buffer.

Syntax:     INTEGER FindHistoryStr(STRING history_str, INTEGER history_no)

            • history_str is the string for which to search in the History
              Buffer.

            • history_no is an integer specifying the history list in which
              to search.

Returns:    The relative position of the located string; otherwise, zero
            (FALSE) if not located.

Notes:      The return value is the number, within the specified history
            list, of the located history item.  It will be in the range 1
            through the value returned by NumHistoryItems(history_no),
            where 1 represents the item added most recently, and higher
            numbers represent older items.

            The return value of this command can be used as input to the
            DelHistoryStr() and GetHistoryStr() commands.

            A case-sensitive search is performed.

            Contrast this command with the GetHistoryStr() command, which
            returns the history string itself.

Examples:

            // locate "myfile" history item in the EditFile history
            integer i

            i = FindHistoryStr("myfile", _EDIT_HISTORY_)

See Also:   GetHistoryStr(), NumHistoryItems(), GetFreeHistory(),
            AddHistoryStr(), DelHistoryStr()

            Variables:  MaxHistoryPerList, PersistentHistory





FindNextFile()

Continues the search for the next file or directory associated with the
specified search handle, and with the specified attributes.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER FindNextFile(INTEGER search_handle, INTEGER attributes)

            • search_handle is a search handle returned by the FindFirstFile()
              command.

            • attributes are the optional attributes to use when searching.
              attributes may be a combination of the following:

              • _NORMAL_ specifies a file that can be read from or written to.

              • _READONLY_ specifies a file that can be read from but not
                written to.

              • _HIDDEN_ specifies a file that is hidden and does not appear
                in a file directory listing.

              • _SYSTEM_ specifies a file that is a system file.

              • _VOLUME_ specifies a volume label entry.

              • _DIRECTORY_ specifies a directory entry.

              • _ARCHIVE_ specifies a file that is marked for archiving.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command is used following the FindFirstFile() command.

            To retrieve information about the found file, use the FF-type
            commands, such as FFName() and FFDate().

            When FindNextFile() processing is complete for a particular search
            handle, the FindFileClose() command should be called to close that
            search handle.

            If you specify any combination of _SYSTEM_, _HIDDEN_, or
            _DIRECTORY_, this command returns normal files in addition to
            files with the specified attribute(s).  If you want to work only
            with files with the specified attribute(s), you must examine the
            specific attribute for each file, via the FFAttribute() command.

            The same attribute used in the FindFirstFile() command should be
            used with this command.

            To search for all files, an attribute of -1 can be used.

Examples:

            See the FindFirstFile() command for an example.

See Also:   FindFirstFile(), FindFileClose(), FindThisFile(), FFName(),
            FFSize(), FFDate(), FFDateStr(), FFTime(), FFTimeStr(),
            FFAttribute()





FindOptions

Defines the options for the initial execution of Find().

Values:     STRING (maximum of 11 characters)

            • B - search backwards

            • G - global search

            • C - search current line

            • L - local search

            • I - ignore case

            • W - whole words only

            • X - regular expressions

            • ^ - tie string to beginning of line

            • $ - tie string to end of line

            • + - start search at the next character

Default:    "I"

Limits:     Has effect at startup only.

Notes:      FindOptions is only effective the first time the Find() command is
            executed.  On subsequent executions, the option string from the
            previous execution is used.

            See the Find() command for detailed explanations of each option.

Affects:    Find()

See Also:   ReplaceOptions





FindThisFile()

Searches a directory for the first file or directory whose name and attributes
match the specified name and attributes.

This command is intended for ADVANCED USAGE.

Syntax:     INTEGER FindThisFile(STRING filename [, INTEGER attributes])

            • filename is the file for which to search.

            • attributes are the optional attributes to use when searching.
              attributes may be a combination of the following:

              • _NORMAL_ specifies a file that can be read from or written to.

              • _READONLY_ specifies a file that can be read from but not
                written to.

              • _HIDDEN_ specifies a file that is hidden and does not appear
                in a file directory listing.

              • _SYSTEM_ specifies a file that is a system file.

              • _VOLUME_ specifies a volume label entry.

              • _DIRECTORY_ specifies a directory entry.

              • _ARCHIVE_ specifies a file that is marked for archiving.

Returns:    Non-zero if successful; zero (FALSE) on failure.

Notes:      This command is a specialized version of the FindFirstFile()
            command.  It is intended for use when you are searching for a
            single file.  It saves you the overhead of opening and then
            closing a search handle.

Examples:

            if FindThisFile("foo.bar")
                Message("file found")
            else
                Message("file not found")
            endif

See Also:   FindFirstFile(), FindFileClose(), FindNextFile(), FFName(),
            FFSize(), FFDate(), FFDateStr(), FFTime(), FFTimeStr(),
            FFAttribute(), AddFFInfoToBuffer()





Flip()

Toggles alphabetic characters between upper and lower case.

Syntax:     STRING Flip(STRING s)

            • s is an optional string to convert.

            or:

            Flip()

Returns:    If the first Syntax format is used, the resulting flipped string
            is returned; otherwise, nothing is returned.

Notes:      Flip() "flips" the target characters:  all alphabetic characters
            (a to z and A to Z) in the string are "flipped" (that is, all
            lower-case characters become upper-case, and vice versa).  Other
            characters are not changed.

            If the first Syntax format is used, s is flipped.

            If the second Syntax format is used:  if the cursor is in a marked
            block, the characters in the block are flipped; otherwise, the
            character at the cursor position is flipped.

Examples:

            Given:

                string s[3], = "aBc", s2[3]

            then:

                s2 = Flip(s)       // s2 is "AbC"
                s2 = Flip("Def")   // s2 is "dEF"
                s2 = Flip(s2)      // s2 is "Def"

See Also:   Upper(), Lower()





FlushProfile()

The OS may keep a cached version of an initialization file. This command
will signal the OS to flush the cache for that initialization file.

Syntax:     FlushProfile([STRING profile_name])

            • profile_name is an optional initialization file's name.
              If not specified, the tse.ini file, located in the editor's load
              directory, is assumed.  If profile_name is specified, and does
              not include a path, the profile_name that resides in the
              WINDOWS directory (specified by the windir environment variable)
              is assumed.

Returns:    Nothing.

Notes:      The OS does not return any information as to whether this
            operation succeeds or fails.

Examples:

            // The following displays all the items in a section of the
            // tse.ini file if that section exists, otherwise that section,
            // and two items for that section, are added to the tse.ini file.
            // These added items are displayed, then one item is removed.
            // The remaining item is displayed, then the section is removed.

            proc main()
                string item[255] = ""
                string value[255] = ""
                integer counter = 0

                FlushProfile()

                if LoadProfileSection("$$test$$")
                    while GetNextProfileItem(item, value)
                        counter = counter + 1
                        Warn("Item ", Str(counter), " is ", item,
                                " which is equal to ", value, " ...")
                    endwhile
                    Warn("There were ", counter,
                            " items. There are no more original items ...")
                else
                    WriteProfileInt("$$test$$", "First Item", 200)
                    WriteProfileStr("$$test$$", "Second Item", "Two Hundred")
                    if LoadProfileSection("$$test$$")
                        while GetNextProfileItem(item, value)
                            counter = counter + 1
                            Warn("Item ", Str(counter), " is ", item,
                                    " which is equal to ", value, " ...")
                        endwhile
                        Warn("There were ", counter,
                                " items. There are no more items ...")

                        RemoveProfileItem("$$test$$", "Second Item")

                        if LoadProfileSection("$$test$$")
                            counter = 0
                            while GetNextProfileItem(item, value)
                                counter = counter + 1
                                Warn("Item ", Str(counter), " is ", item,
                                        " which is equal to ", value, " ...")
                            endwhile
                            Warn("There were ", counter,
                                    " items. There are no more items ...")
                        endif

                        RemoveProfileSection("$$test$$")

                        if LoadProfileSection("$$test$$")
                            counter = 0
                            while GetNextProfileItem(item, value)
                                counter = counter + 1
                                Warn("Item ", Str(counter), " is ", item,
                                        " which is equal to ", value, " ...")
                            endwhile
                            Warn("There were ", counter,
                                    " items. There are no more items ...")
                        else
                            Warn("$$test$$ section not found")