home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 5 Edit
/
05-Edit.zip
/
epm603a.zip
/
EPMBK.ZIP
/
EPMTECH.INF
(
.txt
)
next >
Wrap
OS/2 Help File
|
1995-11-13
|
383KB
|
13,757 lines
ΓòÉΓòÉΓòÉ 1. Introduction to the E Language ΓòÉΓòÉΓòÉ
In order to change existing features or add your own features to the E editor,
you must understand the code in the *.E files which implements the editor.
These files are written in a macro language (the E language) developed for the
editor. To make changes to the editor, simply edit these files, remove the
pertinent E code, and make the necessary changes, place in a My*.E file, and
recompile using the etpm epm command as discussed in The EPM User's Guide.
Special features of the E language include:
o The E language provides high level list and display capabilities.
o The E language combines file list primitives, display primitives, and
keyboard primitives into a language with procedure definitions. Few other
languages have attempted to provide useful display, file list and keyboard
primitives.
o The E language, like REXX, has untyped variables, making it easier to
manipulate strings and numbers. (In essence all variables are strings.)
o The E language allows definition of keys, commands and procedures in a
similar manner.
An E program consists solely of one or more definitions. Each definition can
define:
a procedure,
which consists of tasks to be performed when that
procedure is called by another definition;
a command,
which consists of tasks to be performed in order to
execute a command that a user types in the command
dialog box of the editor;
a key,
which consists of tasks to be performed when a user
presses that key while in the E editor;
initializations,
which consist of variable assignments that must be
performed immediately after the editor is invoked;
constants,
which consist of unchangeable values assigned to
identifiers;
configuration options,
which allow the user to change the basic configuration
(colors, cursor size, margins etc.) of the editor.
Each definition is composed of statements which implement the procedure or key
function being defined.
A sample E program is presented below. The comments label and explain the key
features, so that you can relate their form to the descriptions above.
def a_f2 = /* beginning a definition:
defining the A_F2 key */
'temp' /* --> pressing this key causes the user-
defined command temp to
be performed */
defc temp /* beginning a definition:
defining the temp command */
sayerror "Command TEMP in progress." /* a statement */
junk = machine() /* this statement includes a call to a
built-in procedure (i.e. one that comes
with the editor, and is not user-defined) */
call mydisplay(junk) /* a call to a user-defined procedure */
defproc mydisplay(machtype) /* beginning a procedure definition:
defining a procedure = user-defined proc */
new_line = 'Machine type is: '||machtype /* string concatenation */
insertline new_line, 5 /* this built-in statement adds the
contents of variable new_line to the
fifth line of the current file */
We will devote a section of this manual to discussing each of the major
components of the E language. These components (followed by an example) are:
o Scoping (universal)
o Variables and identifiers (newline (see above example))
o Arrays (do_array 1, arrayid, myarray)
o Expressions and operators (x+1)
o String expressions ('foo'||'bar')
o Comments (/* like this */)
o Line continuations (x=9+8; y=x-9)
o Fileid structure (.filename)
o Definition primitives (DEF, DEFC, DEFPROC)
o Constants (const BLACK=0)
o SET definitions (set cursors)
o Built-in statements and procedures (insert; x=machine())
o Conditional and loop statements (IF-THEN-ELSE)
o The PARSE statement (PARSE arg(1) WITH filename '.' filetype)
o Compiler Directives (tryinclude)
o Using EPM Command Statements ('E myfile.txt')
o Predefined constants and variables (rc)
o User exits (in DEFMAIN, NAME, SAVE and QUIT)
In future sections, the following symbolic conventions will be used to convey
points of the language more clearly:
Symbol: Meaning:
{ }
Zero or more repetitions of what is inside.
[ ]
Zero or one of what is inside.
A | B
Substitution of A or B.
var
The word var indicates that a variable is required and not
an expression.
...
More repetitions of the same syntactic pattern
Note: For an example of a var variable being required instead of an
expression, see the ACTIVATEFILE entry in section Built-in Statements and
Procedures. After reading the following sections, users who wish to make
extensive customizations to the E macros should rely heavily on the following:
o Field Variables Listed;
o Built-in Statements and Procedures;
o E Language Syntax;
o General Structure of E-Macro Files;
o Descriptions of Procedures in Standard EPM.
Note how these sections are divided.
ΓòÉΓòÉΓòÉ 1.1. Fileid Structures ΓòÉΓòÉΓòÉ
The Field Variables Listed section contains field variables that can take
assignments or be be referenced. For example:
if .textcolor <> 14 then
.textcolor = 14
endif
The first reference to textcolor checks the color of the text window (a
referenced field variable). If it is not equal to color 14 (yellow) then it
makes the text window color yellow (a field variable assignment).
ΓòÉΓòÉΓòÉ 1.2. Built-in Statements and Procedures ΓòÉΓòÉΓòÉ
There are built-in statements and procedures. These are internal in the E code,
and therefore cannot be located in any of the .E files. These are listed in the
Built-in Statements and Procedures section. For example:
asciivalue = ASC('A')
insert 'Written by the Yorktown E group', 5
The first example is of the ASC() procedure. It will return the value 65 in the
variable asciivalue. Only procedures can return values (but don't always have
to). Procedures always take parentheses even if no arguments are passed. There
cannot be any spaces between the procedure name (in my example ASC) and the
left parenthesis, or E will think it is a statement.
Statements, however, never take parentheses and don't return values. They can,
but don't have to, take arguments. The second example is of the insert
statement, shown here with arguments. It would insert on line five the text:
Written by the Yorktown E group.
ΓòÉΓòÉΓòÉ 1.3. Standard Procedures ΓòÉΓòÉΓòÉ
There are also defproc procedures that have been written in E-code and
therefore exist in one of the .E files. These are listed in Descriptions of
Procedures in Standard EPM.. They always take parentheses and can return
values, just like the built-in procedures. An example is:
mymaxnum = MAX(4,5,98,6)
This E code will set the variable mymaxnum to 98, the maximum number in the
argument list. Again, the left parenthesis is flush with the procedure name.
ΓòÉΓòÉΓòÉ 1.4. EPM Commands ΓòÉΓòÉΓòÉ
Commands, defined with the defc and written in E-code can be invoked from the
command line dialog box, and are listed in the The EPM User's Guide and the
section Commands Omitted From the User's Guide in this manual. These can also
be called from within the E language if surrounded by quotation marks. For
example:
'bottom'
will move the cursor position to the bottom of the file, as if the user had
typed bottom from the command line dialog box.
ΓòÉΓòÉΓòÉ 1.5. Summary ΓòÉΓòÉΓòÉ
Understanding the differences between these commands, statements, and
procedures is critical when programming in the E programming language. When
looking for a specific result, remember to look in all these sections to help
find a command, statement, or procedure that may accomplish your goal. The
procedures defined with defproc and the commands defined with defc are good
sources of reference when programming in E. Examining the E-code of procedures
or commands can be helpful when trying to accomplish a goal close to an
existing procedure or command.
Note: E ignores case for procedure, statements, variable, and command names.
Capitalizing ASC and MAX in the examples above was done purely by whim.
Although the discussion above may be slightly fuzzy to a novice, it should get
more clear as the manual progresses. It may help to refer back to these
distinctions as the various elements of E are described in detail.
ΓòÉΓòÉΓòÉ 2. Basic Tools of the E Language ΓòÉΓòÉΓòÉ
Basic tools of the E language.
ΓòÉΓòÉΓòÉ 2.1. Comparision with to the REXX Language: Scoping ΓòÉΓòÉΓòÉ
Anyone familiar with the REXX language will notice that the E language has the
same look and feel. The string handling looks the same, and the control
structures are similar. You may well ask "Why not use REXX for the editor macro
language?" The answer is that there are some important differences, which we
will discuss.
Unlike REXX, E makes all variables local by default. You can specify that a
variable is to be global everywhere, i.e. available to any other procedure, not
only to the current caller, by using the universal keyword in the declaration.
A simple program will illustrate the scoping differences between REXX and E.
REXX SAMPLE PROGRAM
/* REXX scoping example */
call starthere
starthere: procedure
me='the old me'
call p1
say me /* says 'the old me' */
exit 0
p1: procedure /* don't expose me here */
call p2
p2: procedure expose me
me='the new me' /* try to modify me down here */
return ''
E SAMPLE PROGRAM
/* E scoping example */
defmain
call starthere
defproc starthere
universal me
me='the old me'
call p1()
say me /* says 'the new me' */
exit 0
defproc p1
call p2()
defproc p2
universal me /* make it really global */
me='the new me'
return ''
For the REXX program to calculate the same results as the E program, procedure
p1 would have to expose the me variable. The REXX expose statement requires
that the symbol table be known at the time of the call. When a REXX procedure
is called, the current symbol table entries are removed except for those
entries that are exposed. This means that a symbol table must be maintained at
run time. When a variable is referenced, a lookup is performed to see if it is
already in the symbol table. If the variable is not in the symbol table a new
symbol table entry is created.
In the E language, like MODULA-2, C and PASCAL, no symbol table is required at
run-time. The absence of variable lookup is one reason why E runs considerably
faster than REXX. However, REXX programs are more easily debugged for the same
reason. But the order of magnitude of improvement in performance was judged
critical for the programming environment.
Note: Rexx *is* supported as a macro programming language, for the benefit of
those who don't want to recompile the macros (and for external users who
might have problems downloading the EPMBBS package to get the macros and
macro compiler), but E is what is recommended for any serious EPM
programming. See the online help for details on writing EPM macros in Rexx.
ΓòÉΓòÉΓòÉ 2.2. E Variables and Identifiers ΓòÉΓòÉΓòÉ
Variable declarations are not needed except for universal variables. All other
variables are assumed to be local except for a few predefined, universal
variables to be discussed in Predefined Constants and Variables.
Identifiers have the following syntax:
[a-z | A..Z]{a-z | A..Z | 0-9 | _}
Identifiers are not case sensitive, and can consist of no more than 28
characters.
ΓòÉΓòÉΓòÉ 2.2.1. The Contents of Uninitialized Variables ΓòÉΓòÉΓòÉ
When a variable is referenced for the first time in a REXX program the variable
holds the name of itself in upper case (e.g., abc='ABC'). In an E program the
value of an uninitialized variable is undefined. This decision was made for the
following reasons:
1. No symbol table information is required at run time. A complete symbol
table is needed to know when the variable is first defined at run time.
2. Speed. Local variables do not have to be assigned anything except what the
user assigns to the variable.
Some people prefer the REXX convention because it allows you to type in some
operating system commands without using quotes. For example,
type profile exec
But many operating system commands will still require quotation marks anyway.
Requiring quotation marks in all cases reduces confusion.
Since uninitialized variables are truly uninitialized (random) in E, strange
behavior can occur if a programmer accidentally creates an unintended variable,
for instance, by misspellling a statement ('sayeror'). The ET compiler will
catch most uninitialized variables at compile time, and report "Variable not
initialized". For example, the following will be caught:
defc foo=
insertline x /* x was never given a value */
This feature will also catch several other previously obscure errors. Omitting
the commas between universal variable names:
universal a b c /* wrong, should be universal a,b,c */
/* ET reports b as not initialized */
The omission of parentheses after a procedure call:
call myproc /* ET will report myproc as not initialized */
And most misspellings that otherwise wouldn't be caught until the line was
executed:
sayeror 0
Limitation: This will not catch some cases where a variable is referenced
twice, or where two variables are combined in an expression:
call p(a+b) /* Won't catch uninitialized a. Will catch b. */
for i=i /* These are not caught. */
x=x+1
It should be noted that this feature is a benefit of E's compilation approach.
The variable names are tokenized at compile time (unlike REXX), making it easy
to tell when a new variable is being created.
ΓòÉΓòÉΓòÉ 2.3. Arrays in EPM ΓòÉΓòÉΓòÉ
Arrays are handled like files in a ring. When creating an array, an array id is
returned as a "handle" for the array. This array id then can be used to get and
put items into the array. Indices do not have to be numeric but instead can be
any arbitrary string (like REXX stems).
The following shows the format of the DO_ARRAY statement used to create, write
to, and read from an array:
do_array 1, array_id, myarray
This creates an array called MYARRAY and
returns its array id in the ARRAY_ID
variable. If an array called MYARRAY
already exists, then its array id will be
returned.
do_array 2, array_id, index, value
This sets the entry INDEX in the array
identified by the ARRAY_ID number to the
value specified in VALUE. Both the index
and value can contain arbitrary strings.
do_array 3, array_id, index, result
This will look up the INDEX entry in the
array ARRAY_ID and assign the result to
the variable RESULT. An error is given if
the index is not found.
do_array 4, array_id, index
This will delete an entry specified, by
INDEX, from the array.
do_array 6, array_id, array_name
Returns the array_id associated with the
array name specified by array_name
do_array 7, array_id, index, result
(32-bit EPM only.) This will look up the
INDEX entry in the array ARRAY_ID and
assign the result to the variable RESULT.
If the index is not found, the value of
the array's .userstring is returned.
Due to the common interface, the second and fourth arguments in the DO_ARRAY
statement must be variables and not numeric or string constants or expressions.
Arrays are, in fact, a special class of file, and the arrayid is the fileid of
the array file. While you would not normally make an array the active file,
the way to delete an array is:
getfileid curr_file -- Save the current file
activatefile arrayid -- Activate the array pseudo-file
'xcom quit' -- Quit the array
activatefile curr_file -- Restore the previously-active file
Suboperand 7 was added in the 32-bit version of EPM to not only avoid an error
message when looking up an index that is not present, but to allow you to set a
default value other than the null string. For example, the following Rexx
file:
/* Example Rexx code */
array. = '[not set]'
array.foo = 'Foo'
say 'Value of array.foo is' array.foo 'and value of array.bar is' array.bar
is equivalent to the following E code:
do_array 1, array_id, 'Array' -- Create the array
array_id.userstring = '[not set]' -- Set default value
temp = 'Foo' -- (Fourth parameter must be a variable; can't just do:
-- do_array 2, array_id, 'foo', 'Foo' -- )
do_array 2, array_id, 'foo', temp -- Set the value for index 'foo'
do_array 7, array_id, 'foo', foo_val -- Get the value for index 'foo'
do_array 7, array_id, 'bar', bar_val -- Get the value for index 'bar'
sayerror 'Value of array.foo is' foo_val 'and value of array.bar is' bar_val
When an edit window is opened, the standard macros create a utility array,
array.EPM, whose index is saved in the universal variable EPM_utility_array_ID.
It is used by various sections of code, each section using a unique prefix for
its variables. For example, 'bmi.' is the prefix for bookmark indices, with
'bmi.0' containing the number of indices and 'bmi.'n containing the name of
bookmark number n. Sharing a single array in this manner results in much less
overhead than creating a new array for each distinct usage. User code can also
share in this savings if desired, by selecting a unique prefix. This should
only be done for code which needs to keep the values for the extent of an edit
session. Code that can delete the array after its usage should use a private
array, as individual array elements can not be deleted. (They can be set to
null, but the indices will still be taking up space and slowing down the lookup
for other array indices.)
ΓòÉΓòÉΓòÉ 2.4. Expressions and Operators ΓòÉΓòÉΓòÉ
Expressions and operators.
ΓòÉΓòÉΓòÉ 2.4.1. Operators ΓòÉΓòÉΓòÉ
+
Add expressions
-
subtract expressions
==, /==
exactly equal, not exactly equal forces exact string
comparison, taking all spaces and digits as a string.
=, <>, <=, >=, <, >
These operators ignore leading and trailing spaces on
expressions being compared. If both operands are numbers a
number comparison is performed; otherwise a string
comparison is performed.
examples
'hi'='hi ' is true
'hi'=='hi ' is false
not, -, +
Boolean not, unary minus, unary plus
and, &, or, |
Boolean and, Boolean and, Boolean or, Boolean or
||
concatenates two strings
*, /, %
integer multiply, divide, integer divide
//
modulus (remainder) operator. 22 // 5 = 2.
Note: The percent sign % is to be used for integer division, while the slash /
is to be used for floating-point division.
ΓòÉΓòÉΓòÉ 2.4.2. Operator Precedence ΓòÉΓòÉΓòÉ
From lower to higher precedence:
1. AND, OR, NOT, &, |
2. >, <, =, ==, /==, <>, <=, >=
3. ||
4. +, -
5. *, /, %, //
ΓòÉΓòÉΓòÉ 2.5. String Expressions ΓòÉΓòÉΓòÉ
The rules for delimiting strings are shown below:
o Double or single quotes may be used.
o Two single quotes inside single quotes represent the single quote character.
o Two double quotes inside double quotes represent the double quote character.
o Strings may not extend across line boundaries.
o A backslash can be used to represent awkward characters, in the same style as
the C language. \t (without quotes) represents the tab character. On a PC
the ASCII value of the tab character is 9, so \9 represents the same thing.
Other special characters are \r and \l, which denote carrage return and line
feed, repectively.
Examples:
'abc'== "abc"
''''=="'"
""""=='"'
'1'\50==12 /* 50 is ASCII value for the character '2' */
3+ '1'\50==15 /* everything is a string! */
3+ '1'||2==42 /* Concat'n has lower precedence than + */
asc(\t)==9
asc(\r)==13
\r\n==''\r\n''
/* Note that \r\n is a single string literal, */
/* generically the same as a single string of */
/* two characters "XY". No concatenation here. */
ΓòÉΓòÉΓòÉ 2.5.1. Catenation (Concatenation) ΓòÉΓòÉΓòÉ
Strings can be joined by catenation using the (con)catenation operator (||).
However, the operator can be omitted in most cases. When the operator is
omitted, E will place a single blank between the catenated results IF there is
at least one space between the operands. As the following examples illustrate,
one can completely avoid using the catenation operator. Suppose:
v1 = 'abc'
v2 = 'xyz'
r1 = v1 v2
r2 = v1 'def'
r3 = v1'ghi'
r4 = v1 'qrs'
r5 = v1/* comment */v2
then:
r1 == 'abc xyz'
r2 == 'abc def'
r3 == 'abcghi'
r4 == 'abc qrs'
r5 == 'abcxyz'
ΓòÉΓòÉΓòÉ 2.6. Comments ΓòÉΓòÉΓòÉ
E allows three ways to add comments:
1. placing a semicolon in column one;
; this is a comment
2. surrounding the comment with '/* */'; and
/* this is a /* nested */ comment */
/* this is a leading comment */ followed by executable code
/* this is a
two line comment */
3. a double-dash at the start of a line comment.
this is executable code -- followed by a rest-of-line comment
If a semicolon appears in the first column (that's column one, without
preceding spaces) the rest of the line is ignored. This style is often handy
for quick commenting-out of existing source code. A comment in a REXX-style /*
*/ enclosure does not cause the remainder of the line (if any) to be ignored.
These comments can be nested. A double-dash ("--") causes the remainder of the
line to be ignored. This is an easier way to type one-line comments, but does
not allow multi-line comments or nesting.
ΓòÉΓòÉΓòÉ 2.7. Line Continuations ΓòÉΓòÉΓòÉ
This section was added to explain when statements can be continued across
lines. In theory this information was already in the manual - the syntax
listing in E Language Syntax shows that a semicolon (which the compiler
considers to be the same as a new line) is often acceptable in mid-statement.
But this will provide better illustrations.
E does not require an explicit statement continuation character as REXX does.
It automatically continues to the next line when it "knows" it needs more
information, such as after an operator in the middle of an expression. This
differs from the REXX treatment. REXX allows line continuations in more cases,
but EPM does not require the explicit comma. In REXX you could do this:
x = a ,
b /* REXX result is x = a b */
which concatenates the two strings a and b (implied concatenation). You can
achieve a similar (but not identical) effect by supplying an explicit operator
to make E aware that there must be more:
x = a || /* explicit concatenation operator */
b /* gives x = a||b, no intervening space */
A new line is allowed in all the following cases:
1. After an operator in an expression:
x = 1 +
2
2. After a comma in an expression list passed to a procedure:
call myproc( 'foobar' ,
'axolotl' )
3. After a comma in declarations of procedure parameters, constants or
universal variables:
defproc myproc( a ,
b )
const
x = 1,
y = 2
universal a
,
b
4. After a comma in a DEF with a series of keynames:
def a_a, a_b, a_c,
a_d, a_e
5. Between if and then:
if a=1
then b=a
else c=a
endif
6. And after commas between parameters of several statements - getcommand,
setcommand, getfileid, getline, replaceline, insertline, deleteline, and
getmark:
replaceline 'this is a long new line' ,
linenumber ,
fileid
As mentioned above, the semicolon can be used to separate statements on the
same line. For example:
x= 5+3; y= 9-7
will work and place the value of 8 in x and 5 in y Without a semicolon E
expects only one statement per line. For example:
x= 5+3 y= 9-7
will cause a compilation error of "Variable not initialized" on the y (it
attempts to concatenate 3 and y).
ΓòÉΓòÉΓòÉ 2.8. Fileid Structure ΓòÉΓòÉΓòÉ
The E editor must store information on each file in its rings. Therefore each
file is assigned a unique fileid, which acts as a handle for the file. The
fileid is actually a structure composed of many fields, such as .FILENAME,
.LINE, .DRAGCOLOR. Each field stores a value which identifies an attribute of
the file. By manipulating the values of these fields, macros can get and set
information about the files loaded, for example the modify status or the
contents of the message line. Because macros need the fileid to set the fileid
fields, E provides a GETFILEID statement to obtain the fileid.
To access the structure of a file other than the active one, the GETFILEID
statement is provided to get an ID or "handle" on a file.
GETFILEID var fileid [,filename]
If filename is given, a search is performed for it in the
EPM rings. A match is considered to be found if the name
portion (without drive and path) of a filespec in the ring
matches filename. This could be ambiguous if two files of
the same name (from different directories) are in the ring;
if this is a concern, specify the full filespec, with path,
to force an exact match.
This feature can also be used to find a temporary file with
a unique name, such as '.ALL' or '.DIR'.
If a match is found, then the fileid will be a valid
integer handle for that file, where fileid >= 0. Otherwise
fileid='', a null string.
If the filename is not given, then fileid will be a valid
handle for the current file, where fileid>=0.
Examples:
GETFILEID fileid /* Set variable fileid to */
/* correspond to active file */
GETFILEID myid,'AUTOEXEC.BAT' /* Set variable myid to */
/* correspond to file AUTOEXEC.BAT. */
/* If AUTOEXEC.BAT is not already */
/* loaded then myid will be null. */
To assign values to the fileid fields:
fileid.field = expression
fileid must be an integer handle corresponding to a valid
file. field must be one of the field names listed below.
For example, to set the current line of the active file to
one:
getfileid fileid /* get the fileid of the active file */
fileid.line=1 /* set the current line to one */
The alternative syntax is:
.field = expression
Since no fileid is specified, the current file is assumed.
.line=1 /* Make line 1 the current line of the */
/* current file. Note that there is */
/* no need to get a fileid to set a */
/* field of the current (active) file. */
A list of all the fileid fields and their meaning is presented here. In the
following list, remember that x refers to the horizontal axis and y refers to
the vertical axis.
ΓòÉΓòÉΓòÉ 2.8.1. Field Variables Listed ΓòÉΓòÉΓòÉ
The following is a list of the field (dot) variables and what information they
contain:
Field Variable Description
AUTOSAVE number of changes (0 to 65535) between autosaves;
this counts the true number of changes, not just
number of lines entered.
AUTOSHELL A flag indicating if unrecognized commands
entered on the command line should be checked for
along the PATH or EPMPATH. The default is 1;
someone who frequently mistypes commands and for
whom it takes a while to search the path (e.g.,
has many LAN drives in the PATH) might want to
set this to 0.
COL current column position, 1 to 255.
CURSORX cursor's x position relative to window origin.
CURSORY cursor's y position relative to window origin.
DRAGCOLOR is the color of the highlighted area within a
drag area.
DRAGSTYLE determines the type of mark done when a mouse
drag is used to mark text. Valid values are:
0 = don't show drag
1 = show character mark
2 = show block mark
3 = show line mark
EAAREA pointer to extended attribute area, containing
the EAs for the current file. See EPM_EA.E for
routines manipulating extended attributes in the
.EAAREA.
FILENAME name of current file.
FONT the font id of the current file's font
FONTHEIGHT contains the current font height in pixels.
FONTWIDTH contains the current font height in pixels.
KEYSET the name of the keyset bound to the file, a
string like "EDIT_KEYS".
LAST the total number of lines in the current file.
LEVELOFATTRIBUTESUPPORT A bit field indicating the level of attribute
support desired. The bits are:
1 Display color attributes.
2 Don't skip over attributes when moving the cursor.
4 Display font attributes.
8 Save attributes in an Extended Attribute when saving the file.
16 Used by the macros to indicate that the Compiler menu was added (part of
the Workframe support).
Note: Displaying mixed fonts can slow down
screen refresh considerably.
LINE the line number of the cursor's position, ranging
from 0 to LAST.
LINEG returns the same value as .LINE. When set,
doesn't cause scrolling, so has less overhead
than setting .LINE when making temporary line
changes. .*
LOCKHANDLE can be used as a Boolean variable determining
whether the current file is locked against other
user's access in a LAN situation. (If non-zero,
the actual value is the file handle of the file,
which is kept open.)
MARGINS the margin settings for the file, a string like
"1 79 1".
MARKCOLOR contains the color for marked text.
MESSAGECOLOR contains the message display color.
MESSAGELINE in older versions of EPM, contained the contents
of the message line. Replaced by the
SetMessageLine command.
MODIFY The number of modifications to the file since it
was loaded or last saved. Normally ranges
between 1 and .AUTOSAVE.
MOUSEX the column of the mouse location. This variable
is only valid when processing a mouse message.
MOUSEY the row of the mouse location. This variable is
only valid when processing a mouse message.
STATUSCOLOR contains the color of the status line.
STATUSLINE in older versions of EPM, contained the template
for the status line. Replaced by the
SetStatusLine command.
TABS the tab settings for the file, a string like "1 4
7 10" of up to 32 values. The tabs settings is
not a single global setting, but is remembered
for each file.
TEXTCOLOR shows the current textcolor setting.
TITLETEXT contains text to be displayed in the title bar
when this file is the current file. By default,
this field is empty, in which case the .filename
field is used.
USERSTRING this is a temporary storage string for the E
programmer to use for file specific information.
If used in your macro work files, you can do
anything you like with it. If used in normal
text files being edited, it is suggested that you
add uniquely-delimited tags to the .userstring
rather than simply replacing it, in order to
allow other macros to share the string. For
example:
parse value .userstring with '[MyTag:' old_val ']'
if old_val = '' then
new_val = my_process_new_file()
.userstring = .userstring '[MyTag:'new_val']'
endif
VISIBLE contains a one if the file is displayable (ie.
not hidden) and a zero if the file is a hidden
file.
WINDOWHEIGHT contains the height of the current window.
WINDOWWIDTH contains the width of the current window.
WINDOWX gap between the right edge of the client windows
presentation space and the right edge of the
client window.
WINDOWY gap between the bottom end of the client windows
presentation space and the bottom end of the
client window.
Some fields with numeric values also follow certain constraints about their
maximum and minimum values. Some fields are dependent upon other fields. The
following chart shows these dependencies and some of the fields' ranges of
values.
Field name Max value Min value
---------- --------- ---------
.AUTOSAVE 65535 0
.COL 255 1
.CURSORX .windowwidth 1
.CURSORY .windowheight 1
.FILENAME a string like 'C:\TESTFILE.DOC'
.KEYSET a string like 'EDIT_KEYS'
.LINE .last 0
.MARGINS a string like '1 254 1'
.MARKCOLOR 255 0
.MESSAGECOLOR 255 0
.MODIFY 65535 0
.STATUSCOLOR 255 0
.TABS a string like '1 4 7 10' or '3'
ΓòÉΓòÉΓòÉ 2.9. Attribute Pairs ΓòÉΓòÉΓòÉ
EPM provides one with the ability to associate information with positions and
regions of a file without modifying the content of the file. This capability
is called attribute support and can be used to provide features like embedded
objects, hidden text, bookmarks, hypertext links, and structured text editing.
In most editors files/buffers are treated as streams of characters. EPM
differs from most editors in that a file/buffer is treated (for display) as a
stream of characters and attribute records. Attribute support simply provides
an interface for managing files/buffers that contain attribute records.
Attribute records themselves are essentially invisible, but because they can be
used to pass information to the rendering, live parsing, and formatting
components of the editor, a user of the editor can often ascertain the
existence and location of some attribute records based on the effect these
attribute records have on the rendering of the file/buffer.
In order to manage attribute records, it is useful to have a notation system
for referencing individual attribute records within a file/buffer. In EPM the
notation system is positional-- that is, one points to location of the
attribute record when one wants to reference it.
In an ordinary text editor one can refer to any position in a file/buffer by
specifying a line number and column number. This approach is not adequate for
an editor like EPM that has the dual goal of supporting attributes record
management and yet minimizing the impact of attribute support on
applications/macros that are not attribute-aware. In order to best achieve
both goals, EPM has replaced the common line/column coordinate system with a
line/column/atoffset based coordinate system. In this system each character of
a line occupies a unique column, but individual attribute records are denoted
by their attribute offset relative to the next character in the buffer/file.
The characters themselves always have an atoffset value of zero, so the
atoffset value is often omitted when referring to characters. An attribute
record located immediately to the left of a character is said to be located at
the same column as that character but at an atoffset of -1. An attribute
record immediately to the left of that is said to be at atoffset -2. The
following diagram illustrates the notation for various characters and
attributes on a line:
abcd[A]efg[B][C][D]h[E] [F]
Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé
Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöö col 11 atoffset -1
Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöö column 9 atoffset -1
Γöé Γöé Γöé Γöé Γöé Γöé Γöö column 8 (atoffset 0)
Γöé Γöé Γöé Γöé Γöé Γöö column 8 atoffset -1
Γöé Γöé Γöé Γöé Γöö column 8 atoffset -3
Γöé Γöé Γöé Γöö column 5 (atoffset 0)
Γöé Γöé Γöö column 5 atoffset -1
Γöé Γöö column 4 (atoffset 0)
Γöö column 1 (atoffset 0)
Note: The text in the example will simply appear as a sequence characters from
"a" to "h" because attribute records are invisible. An exception to
this might be if the attributes effect the formatting, parsing, or
rendering of the text.
As you can see in this first example, each of the characters resides at a
unique column number and has an implicit atoffset of zero. You can also see
all attribute records reside at negative atoffsets and that it is possible for
more than one attribute record to reside between any two adjacent characters.
In this example, three attribute records reside between the "g" in column 7 and
the "h" in column 8.
It should be noted that negative column numbers and positive at offset values
are invalid. In previous versions of EPM it was possible to have positive
atoffsets. This has been changed because it complicates the implementation
without providing a satisfactory solution to any problem. It also be noted
that overly negative atoffset values have undefined semantics that may vary
depending on the operation requested. Most operations will flag an error when
overly negative values are specified. ((Footnote: It is recognized by the
developers of EPM that people tend to deal with positive numbers better than
with negative. For this reason, we'd like to change the notation to be positive
and to represent the position of attributes relative to the character to the
left. Unfortunately, we are unlikely to find the time to make this change.))
When working with attributes records it is also important to have a notation
for the spaces between characters and attribute records. The convention is
that each interstitial is reference by the same coordinate as the character or
attribute to its right. In the first example, the position on the left side of
the "c" character is referred to column 3 atoffset 0. Similarly the
interstitial between the C and D attribute records is referred to as column 8
atoffset -1.
In addition to positional information, attribute records also contain class,
value, and range information.
Each attribute record has a class field that is used to categorize the
attribute record based on its purpose. For example, one might be a member of a
bookmark class or sgml tag class. Certain predetermined classes are supported
by the editor: AC_FONT, AC_COLOR, AC_HSPACE. Internal support for additional
classes will be added later, and applications can create and support additional
classes. This is done by registering a class. The editor provides C and E
macro API's for this.
In addition to a class field, each attribute record has a four byte "value"
field whose interpretation is based on the class field of the attribute record.
For example, the value field of an SGML class attribute record might be a
pointer to meta information about the SGML element enclosed by the attribute
record. The interpretation of the value fields of the internally supported
attribute classes are:
AC_FONT The value fields of AC_FONT attribute records is interpreted as a
font ID. (See pregister_font for further info about font ID's.)
AC_HSPACE This attribute records are always interpreted has having point range
and their value field is interpreted as the amount of horizontal
white space that should be added at this point in the file when
rendered.
AC_COLOR The value fields of AC_COLOR attribute records is interpreted in the
same fashion that the attribute byte of CGA monitors was interpreted.
That is, the high nibble is the background color and the low nibble
is the foreground color. In the future this class may be broken down
into a foreground color class and a background color class so that
support can be added for more than 16 colors.
In the current implementation the class field is only one byte long. In
addition, the classes below 64 are reserved for internal use. This leaves only
192 classes for application use. This is a relatively small domain, so it
suggested that applications try to use as few classes as reasonable. For
example, if one were to implement a SGML tag set where each tag type was a
class, one could easily consume most of the available classes. In a situation
like this it is suggested that the application just register a single SGML tag
class and make the value field a pointer to a record that describes among other
things, the type of SGML tag being represented by the attribute record.
Each attribute record has a range field. The range field indicates over what
domain the attribute record rules. That is, if the attribute record indicates
that text should be colored red, the range value indicates what text should be
colored red. There are currently four types of range values supported in EPM:
point, set, push, and pop.
The "point" range is simply used to remember a location. Attributes with this
range might be used as book marks for example. Attribute records with such a
range effect no text, they just mark a location. For example if one put a
color attribute record with a point range into the document, no text would
change color.
The "set" range simply indicates that it's attribute record rules over all the
text that follows until another set attribute record of the same class is
encountered. Attribute records of this class can easily be used to simulate
character oriented attribute support much like that seen in most word
processors.
The "push" range simply indicates that it's attribute record rules over the the
text that follows until suspended with another push attribute record of the
same class or until a matching "pop" attribute record is encountered.
The "pop" range indicates that the text that follows should be ruled by the
attribute record (of the same class) that was suspended by "push" attribute
record that currently rules the text to the left of this pop attribute record.
Together the push and the pop attribute records are ideally suited implement a
structured text system or to do GML and SGML like text tagging.
The above definitions of push, pop, and set attribute records are a bit
ambiguous on what is done if a file contains both push/pop and set attribute
records of the same class. In actuality the behavior is undefined. In the
current implementation, push and set are actually the same value so the editor
can not distinguish between them. In the future this may change in order to
enable some optimizations. Therefore one should stick to the AR_PUSH, AR_POP,
AR_SET, and AR_POINT constant definitions provided in ATTR.E and ATTRIB.H, and
one should not mix push/pop attributes with set attributes of the same class.
It is anticipated that when one uses several modules/utilties at the same time,
each utility might choose to use a different set a ranges for a given attribute
class. No solution to this problem has been adequately worked out at this
point, but we don't expect this to be a major problem.
Potential solutions might be to register each as being either push/pop or set
and point.
ΓòÉΓòÉΓòÉ 3. Definition Primitives ΓòÉΓòÉΓòÉ
The E language has a rich collection of primitives. These primitives are the
building blocks of E programs since all E statements must occur within a
definition construct. Definition primitives define procedures, commands, keys
and initializations. Some definition primitives may be considered procedures.
When distinguishing between these DEF procedures, one must consider three
factors: how many of each type of definition may coexist in one program, when
they are executed and what parameters they can be passed. The definition
primitives are :
o DEFINIT
These procedures may be multiply defined. All DEFINIT procedures are executed
first upon initialization of the EPM editor, one after another in the order
in which they were encountered during compilation. (That's what we mean by
"may be multiply defined" - you can have several DEFINIT procedures and they
will be executed in sequence as if they were concatenated.) They take no
arguments and are typically used to initialize universal variables.
o DEFEXIT
The converse of DEFINIT. E executes all DEFEXIT procedures last, just before
it returns to the operating system. DEFEXIT procedures are also called
during unlinking. Like DEFINITs, these procedures may be multiply defined and
take no arguments.
o DEFMAIN
This procedure may be defined only once. DEFMAIN is executed after the
DEFINIT procedures are executed. This procedure is typically used to take
control of the editor's command dialog box arguments and options before the
editor. This can be particularly handy when you want the edit command to take
your own arguments or funky file names like "h:profile exec a". The
parameters that followed the epm command at the OS/2 prompt can be retrieved
by ARG(1), ARG(2), ARG(3), etc. function calls for as many arguments as are
passed. The number of arguments can be determined with the ARG() function.
This type of retrieval will be discussed in the next section.
o DEFPROC
This kind of procedure is called by other procedures. It has a much more
sophisticated parameter passing capability to make the programming of other
procedures easier. Its capabilities include call by reference, call by value
and the ability to receive a variable number of arguments.
o DEFC
This procedure allows the user to define new commands or redefine internal
editor commands as well as external commands. The command dialog box
arguments may be retrieved by an ARG(1) function call.
o DEF
This defines the operation of a key. It takes no arguments.
o DEFKEYS
This is not a procedure and will be talked about in the key definitions
section of this document. This primitive allows KEY procedures to be grouped
into a keyset.
o SET
This is not a procedure and will be talked about in the SET definitions
section of this document. This primitive is used for setting some of the
default configurations of the E editor.
o CONST
This is not a procedure and will be talked about in the CONST section of this
document. This primitive is used for defining constants used by the E
translator. Constants do not change during execution of the E procs.
o DEFMODIFY
DEFMODIFY, DEFLOAD and DEFSELECT are three "events". They are described more
fully later in this section. DEFMODIFY is automatically triggered when the
file's number of modifications crosses certain threshold values.
o DEFLOAD
DEFLOAD is invoked whenever a new file is created in the ring.
o DEFSELECT
This event is automatically triggered whenever you switch files.
The procedure definition primitives DEFINIT, DEFMAIN, DEFPROC, DEF and DEFC
have no explicit termination keyword. Each definition is ended by the beginning
of another DEFxxx. The rest of this chapter will explain each definition
primitive in more detail.
ΓòÉΓòÉΓòÉ 3.1. Parameter Retrieval using ARG(1) ΓòÉΓòÉΓòÉ
A DEFC or DEFMAIN receives only one argument/parameter: the command string. The
command string consists of what was last typed at the command dialog box. The
string may contain several words separated by spaces. In the case of DEFC, its
sole argument will consist of all the characters typed at the E command dialog
box after the name of the command. This argument is not declared as a parameter
in the DEFC declaration. The DEFC construct does not allow for any parameter
declarations. Instead, the argument can be retrieved via a function call,
ARG(1). An example of this usage is:
defc test
sayerror "arg(1) is " arg(1)
The user activates this command by typing test on the E command dialog box.
This would result in the following being printed on the message area: arg(1) is
. If the user added a parameter when calling test, for example test stuff, then
the following string would be printed: arg(1) is stuff.
In DEFMAIN, as with a DEFC, the only way to access the argument is to use an
ARG(1) function call. DEFMAIN's argument/command string will consist of
everything the user typed after the epm command at the OS/2 prompt. For
example, assume that the following lines are added to the file MYMAIN.E:
defmain
sayerror "arg(1) is " arg(1)
If the user invokes the editor with the command epm `list *.e', DEFMAIN will
print arg(1) is 'list *.e' in the message area.
A DEFPROC can receive multiple arguments separated by commas from the primitive
that calls it. In a DEFPROC, ARG(1) is only the first parameter. An example of
this usage is:
defc test2
call test2('actual param 1', 'actual param 2')
defproc test2(param1_decl, param2_decl)
sayerror "arg(1) is " arg(1)
If the user types test2 at the command dialog box, the procedure will print
arg(1) is actual param 1.
For the exact syntax of the ARG() procedure, please refer to section Built-in
Statements and Procedures.
ΓòÉΓòÉΓòÉ 3.2. DEFINIT ΓòÉΓòÉΓòÉ
The DEFINIT keyword allows the initialization of variables for use by other E
procedures. There is no limit to the number of DEFINIT definitions in an E
source file. The order of execution of the DEFINIT definitions is the same as
their compilation order. All DEFINIT definitions are executed before the
DEFMAIN definition is executed. The general syntax is:
DEFINIT
{UNIVERSAL variable {,variable} }
{statement}
ΓòÉΓòÉΓòÉ 3.3. DEFEXIT ΓòÉΓòÉΓòÉ
The DEFEXIT keyword allows for statements to be executed only when leaving the
editor or unlinking a module. This is useful for any tasks the user wishes to
perform once per session after any and all changes are made to a file. For
example, this allows the user to keep files or communication channels open
throughout the editing session for speed, and only close then when the user
really exits from E.
The syntax is the same as that of DEFINIT:
DEFEXIT
{UNIVERSAL variable {,variable} }
{statement}
ΓòÉΓòÉΓòÉ 3.4. DEFMAIN ΓòÉΓòÉΓòÉ
The DEFMAIN construct allows the user to take control of the command line
arguments, i.e. those arguments and options that the user specifies when
invoking the editor at the OS/2 prompt. The command line arguments may be
retrieved by an ARG(1) function call. The following example comes from the E
editor's DEFMAIN in file MAIN.E:
defmain
os2cmdline = 'e 'arg(1)
The DEFMAIN definition is not required, and if present, it is executed after
all DEFINIT definitions. To avoid an undefined state of the editor, a blank
file is inserted in the top ring of the editor before DEFMAIN is executed. The
general syntax is:
DEFMAIN
{UNIVERSAL variable {,variable} }
statement {statement}
ΓòÉΓòÉΓòÉ 3.5. Procedure Definitions (DEFPROC) ΓòÉΓòÉΓòÉ
The DEFPROC primitive is used to define new procedures (functions). The general
syntax is: (See E language syntax for precise description).
DEFPROC name [( [ [VAR] p1] {, [VAR] p2})] [=]
{UNIVERSAL variable {,variable} }
statement {statement}
[RETURN [expression] ].
where name, p's and v's are valid E identifiers.
Procedures can return a string of 255 characters or less. If no string is
returned, or if a simple RETURN statement with no value is issued, a null
string is automatically returned when the procedure definition ends.
The maximum number of DEFPROC arguments is 8. If parameters are specified (like
p1 and p2 above) then the function is assumed to require a minimum of that many
arguments. For example, if you've defined defproc myproc(x,y,z) but call it
elsewhere with call myproc(a,b), you'll get an error when the call occurs (at
run-time) "Procedure needs more arguments". But you can pass MORE than the
minimum number of arguments. That is, call myproc(a,b,c,d) will work. The
number of arguments can be retrieved inside the procedure using arg(). You saw
earlier how arg(1) retrieved the first parameter. Similarly, arg(2) retrieves
the second parameter and arg(3) retrieves the third, etc. In the above example,
the parameters c and d can be retrieved using the calls arg(3) and arg(4),
respectively. For an illustration of this technique, see the file SORTE.E.
If the keyword VAR prefaces a parameter name in the called procedure's
parameter list, then the variable that the caller passes in the corresponding
position may be changed (call by reference). If the caller passes a parameter
in this position that is not a variable, the E interpreter will detect the
error at run time and halt.
In example 3, call by reference is demonstrated. If the user types test at the
command dialog box, the defc test will call the defproc myproc() which will
print: a and b are 1 2. After the procedure returns, defc test will print : a
and b are 3 2. Variable b was permanently changed by the assignment in
procedure myproc() because it had the var prefix. Variable a's value was
unchanged once procedure myproc() returned. If defc test had made the following
call: call myproc(a, 5*6), an invalid call by reference message would appear at
run time.
ΓòÉΓòÉΓòÉ 3.5.1. Example 1: ΓòÉΓòÉΓòÉ
defproc myproc /* Define a new procedure */
return arg() /* Return number of arguments */
/* passed to procedure.*/
def a_l /* Define the key Alt-L */
call myproc() /* Throw away 0 returned by myproc */
Nofargs=myproc('a','b') /* Sets Nofargs to 2 */
ΓòÉΓòÉΓòÉ 3.5.2. Example 2: ΓòÉΓòÉΓòÉ
defproc myproc /* Define a new procedure */
return arg(1) /* Return first argument */
/* passed to procedure.*/
def a_l /* Define the key Alt-L */
call myproc() /* Throw away '' returned by myproc */
Firstarg=myproc('a','b') /* Sets Firstarg to 'a' */
Firstarg=myproc() /* Sets Firstarg to '' */
ΓòÉΓòÉΓòÉ 3.5.3. Example 3: ΓòÉΓòÉΓòÉ
definit
universal always_around /* Define a global variable */
always_around=0 /* set global variable to 0*/
defc test
a = 3
b = 5
call myproc(a, b)
sayerror "a and b are " a b
defproc myproc(a,var b) /* Define a new procedure */
universal always_around
always_around=1 /* set global variable to 1*/
a=1 /* Change local parameter */
b=2 /* Change callers variable */
i=10 /* Set local variable */
sayerror "a and b are " a b
ΓòÉΓòÉΓòÉ 3.6. Command Definitions (DEFC) ΓòÉΓòÉΓòÉ
The DEFC construct is used to define new commands. When a command is issued, E
will search for the first word of the command as follows:
ΓòÉΓòÉΓòÉ 3.6.1. Command search order: ΓòÉΓòÉΓòÉ
1. Look for a DEFC command (i.e. one defined in a .E file)
2. Look for an internal editor command (e.g. MARGINS or EDIT)
3. Search the directories in the PATH environment variable for any executable
file, as follows:
a. a .EXE, .CMD, .EX file in current directory
b. a .EXE, .CMD, .EX file in the PATH or EPMPATH directories
c. a .EXE, .CMD, .EX file in the same directory as EPM.EXE.
Because of the search order, user-defined commands with the same name as
built-in commands can override internal editor commands. The XCOM command may
be used to force execution of an internal editor command in the case of
duplicates.
ΓòÉΓòÉΓòÉ 3.6.2. Example: ΓòÉΓòÉΓòÉ
defc edit= /* Redefine the edit command. */
'xcom edit 'arg(1) /* Pass command through to the editor */
The general syntax is (See E language syntax for precise description):
DEFC name {,name} [=]
{UNIVERSAL variable {,variable} }
statement {statement}
[RETURN [expression] ].
where name is a valid E identifier.
ΓòÉΓòÉΓòÉ 3.7. Key Definitions (DEF and DEFKEYS) ΓòÉΓòÉΓòÉ
A keyset is a named collection of keys. Typically, this collection defines a
particular mode of editing. For example, you might want the keyboard to behave
one way in a drawing mode and another way in an editing mode. Therefore, each
of these modes would warrant its own keyset. You can have many keysets defined,
but only one can be used at any time.
The DEFKEYS keyword names the keyset. The KEYS statement activates a keyset.
The DEF keyword defines a key or pseudo-key that belongs to the current keyset.
Note: Keys may be redefined. If you create a DEF and the same DEF already
exists in an earlier place in the compilation, the compiler will not issue an
error. It will forget the previous definition. The penalty is that the
previous code is not removed (difficult to do in a fast one-pass compiler), so
a little memory will be wasted in the E.EX file. For a list of definable keys,
see E-Definable Keys.
DEF key_name|ch [-ch] {, key_name|ch [-ch]}[=]
Define key. ch represents any printable character. A
line-break (newline) is allowed after the comma, which can
help readability if you're defining many keynames at once.
Example:
/* Define 27 different keys to do same function,
pagedown. */
def 'a'-'z', a_t = pagedown
def '#' = 'add' /* define single key for add command */
Note that keys can only be defined to execute code. If you
want to remap the keyboard, you have to use the keyin
statement for text characters, and for keys defined to
execute code, either call the same routine as that key is
defined to call or, for keys which don't have a simple
definition and which you don't need to remap, define the
new key to execute the old one using the executekey
statement.
-- Define all alphabetic keys to type their upper-case equivalents
def 'a' - 'z' = keyin upcase(lastkey())
-- Define Alt+A to type a lower-case 'a'
def a_A = keyin 'a'
-- Define 'G' to enter an ASCII 234 (omega symbol)
def 'G' = keyin \234
-- Define Alt+0 to execute the same command executed by another key
def a_0= /* same as Alt+Equal, for sake of German keyboards */
'dolines'
-- Define Ctrl+P to execute whatever code the Alt+P key does
def c_P = executekey a_p
DEFKEYS name [NEW | BASE | OVERLAY | CLEAR]
Define keyset. If the OVERLAY or no option is specified,
then the last set of key definitions is copied onto the
named set of keys. The named keyset thus starts out with
the same keys as the last one. The NEW (or equivalent
BASE) option starts a keyset with only the alphabetic,
numeric and control characters. The CLEAR option starts an
empty keyset. Please refer to section Keysets for more
information on the BASE, OVERLAY and CLEAR options.
A sample keyset named test_keys is defined below. This example shows the
redefinition of the Enter and Space keys:
defkeys test_keys
def ' '=
universal expand_on
if expand_on then
if e_first_expansion()=0 then
keyin ' '
endif
else
keyin ' '
endif
def enter=
universal expand_on
if insertstate() then
insert
else
call maybe_autosave()
if expand_on then
if e_second_expansion()=0 then
call einsert_line()
endif
else
call einsert_line()
endif
endif
ΓòÉΓòÉΓòÉ 3.8. SET Definitions ΓòÉΓòÉΓòÉ
The E editor has a set of configuration options which may be reconfigured by a
SET definition. SET definitions are executed before the DEFINIT procedure
definitions are executed. For examples of these configuration options, refer
to The EPM User's Guide.
It can be seen that there isn't much need for the SET definition primitive
since most editor options can be set in DEFINIT and DEFMAIN. (We hope to do
away with them in the future, in favor of straightforward commands like 'tabs'
and 'margins'.)
Most users will care to change only insert_state.
ΓòÉΓòÉΓòÉ 3.9. Constants ΓòÉΓòÉΓòÉ
The CONST keyword allows a user to define constants that the E translator
remembers during the translation of the E procs. ET substitutes the value
whenever it sees the constant name. Constants serve no purpose at run-time.
Constants may be redefined to the same value without causing an error or loss
of memory space. This is useful if you wish to develop a package for
distribution, since you can define the constants you need without worrying
about conflict with other files installed by the user. The syntax for defining
constants is:
CONST
c1 = exp1 [,]
c2 = exp2 [,]
...
example
CONST
a=3
b=a * 2
ΓòÉΓòÉΓòÉ 3.10. DEFMODIFY ΓòÉΓòÉΓòÉ
The DEFMODIFY event is executed when a file's number of modifications:
o goes from zero to nonzero (the first modification - we might want to change
the screen color);
o goes from nonzero to zero (after a save - we might want to change the screen
color back again);
o goes from less than .autosave to greater than or equal to .autosave (so we
can autosave).
See the file MODIFY.E for more details.
ΓòÉΓòÉΓòÉ 3.11. DEFLOAD ΓòÉΓòÉΓòÉ
DEFLOAD is invoked whenever a new file is created in the ring, whether loaded
from disk or created by 'edit /n' or 'edit /c'.
It is invoked at the end of all processing, the last thing before returning
control to the user, so as not to be fooled by the file moving around in the
ring or being renamed. If a file is loaded from disk and renamed, DEFLOAD gets
the right filename.
After all new files are defload-processed, the expected current file is
restored. Thus the command 'e one two' loads both files, invokes defload on
'one', then on 'two', and finally re-activates 'one'; the user is left looking
at the same file as in the old days. This is done internally so the defload
procs don't have to worry about restoring fileids. Understand this example:
defc rcedit
'edit 'arg(1)
if rc=sayerror('New file') then
sayerror "It's a new file"
endif
defload -- this defload procedure need not be close to the defc.
sayerror "DEFLOAD for ".filename
When you type 'rcedit nosuch', the file nosuch (which doesn't exist on disk) is
created in the ring. DEFLOAD is not triggered until after all other procs are
done, so RCEDIT runs to completion with the proper RC value. You'll see 'It's
a new file' and then 'DEFLOAD for nosuch'. For another example of a DEFLOAD
definition statement see sample menu addition.
It's not guaranteed that the files will be defload-processed in the same order
as they're loaded. They're processed in fileid order. So 'two' might have
been processed before 'one' if fileids are reused.
The DEFLOAD event is also triggered whenever the name of the file changes.
Typically a DEFLOAD will do things like set tabs and margins based on the
filetype, so a name change is treated the same as a new load.
ΓòÉΓòÉΓòÉ 3.12. DEFSELECT ΓòÉΓòÉΓòÉ
This event is automatically triggered whenever you switch files. To be exact,
it is invoked after all other command processing is done, if the then-current
file is different from the current file before the command. Thus if a command
switches to a temporary file but switches back to the original file before
ending, this event will not be triggered.
This replaces the clumsy previous method, a procedure select_edit_keys() which
had to be explicitly called at the end of any action that might have switched
files.
But there's not much work to be done in this event because most of the things
that used to be done in select_edit_keys() are now done only once at file-load
time, in the DEFLOAD event. The keyset, tabs and margins stick with the file
from then on. In the standard macros nothing is done in the DEFSELECT.
Starting with EPM 6, the DEFSELECT event is also triggered whenever the name of
the file changes, just like the DEFLOAD.
Note: The order of events at start-up is: definit, defmain, defload,
defmodify and defselect. The defmodify event would not normally occur at
start-up, unless your defmain modified the newly-loaded file.
These three events can be multiply defined. You can have multiple procedures
under the same name scattered throughout your macro set, and they'll be run in
succession. (As DEFINIT procedures have been scattered around the E files in
the past.) This helps keep the macros modular - if you're writing an editor
application that needs to get control whenever a new file is loaded (the old
BOOKMARK application comes to mind), you can write a DEFLOAD within your module
without having to alter the base E files.
ΓòÉΓòÉΓòÉ 4. Statements ΓòÉΓòÉΓòÉ
Procedures, commands and key definitions are composed of statements. Valid
statements in the E language are:
Construct: Example:
assignment statements
temp = 36
built-in statements
insertline "Written by the Yorktown E
group", 2
conditional statements
to be discussed in section Conditional and
Loop Statements
parse statements
to be discussed in section The Parse
Statement
compiler directive statements
to be discussed in section Compiler
Directive Statements
procedure calls
testproc(arg1, arg2)
commands
to be discussed in section Using EPM
Commands in E Statements
ΓòÉΓòÉΓòÉ 4.1. Built-in Statements and Procedures ΓòÉΓòÉΓòÉ
In the following syntactic description the same symbolic conventions are used
as in The EPM User's Guide section "E Commands". In addition, the word var
followed by an argument means that the argument must be a variable, i.e. a
number, string or expression is not acceptable.
Most of the following statements can be optionally spelled with underscores
between the words. Please refer to E Language Syntax for more information.
Those commands followed by parentheses are procedures; those not followed by
parentheses are statements. Each can be followed by arguments. Only procedures
can return values.
ΓòÉΓòÉΓòÉ 4.1.1. ABBREV(information, info [, length] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ABBREV(information, info [, length])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
ABBREV returns 1 if info is equal to the leading characters of information and
the length of info is not less than length. ABBREV returns 0 if neither of
these conditions is met.
If specified, length must be a nonnegative whole number. The default for length
is the number of characters in info.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
ABBREV('Print','Pri') -> 1
ABBREV('PRINT','Pri') -> 0
ABBREV('PRINT','PRI',4) -> 0
ABBREV('PRINT','PRY') -> 0
ABBREV('PRINT','') -> 1
ABBREV('PRINT','',1) -> 0
Note: A null string will always match if a length of 0 (or the default) is
used. This allows a default keyword to be selected automatically if
desired. For example:
option = entrybox('Enter option:')
/* keyword1 is to be the default */
if abbrev('keyword1',option) then ...
elseif abbrev('keyword2',option) then ...
...
endif
ΓòÉΓòÉΓòÉ 4.1.2. ACTIVATEACCELTABLE var fileid ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ACTIVATEACCELTABLE table_name
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Makes the named accelerator table the active one.
See also:
o Building Accelerator Tables from the Macro Language
o BUILDACCELTABLE
o DELETEACCEL
o QUERYACCELSTRING
ΓòÉΓòÉΓòÉ 4.1.3. ACTIVATEFILE var fileid ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ACTIVATEFILE fileid
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Makes the file identified by the variable fileid the current file.
Fileid must be a simple variable (as indicated by the word var) containing a
valid file id number. If you give an expression, the compiler will stop and
complain, "Expression not assignment compatible."
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Correct usage:
ACTIVATEFILE myfileid
The following expressions will not work:
ACTIVATEFILE fileid' '
ACTIVATEFILE ARG(1)
ΓòÉΓòÉΓòÉ 4.1.4. ADDRESS(variable) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ADDRESS( variable )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the address of a variable. Intended for use in dynalink calls, the
format of the address depends on the version of EPM being used.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
In 16-bit versions (EPM 5.xx),
ADDRESS(varname) == SELECTOR(varname) || OFFSET(varname)
In 32-bit versions (EPM 6.xx),
ADDRESS(varname) == OFFSET(varname) || SELECTOR(varname)
ΓòÉΓòÉΓòÉ 4.1.5. ADJUSTBLOCK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ADJUSTBLOCK | ADJUST_BLOCK
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Overlays marked block at cursor, like the standard key definition Alt-A. The
source block is filled with spaces.
ΓòÉΓòÉΓòÉ 4.1.6. ADJUSTMARK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ADJUSTMARK
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves marked text to the location of the cursor by overlaying. The old location
is filled with blanks.
ΓòÉΓòÉΓòÉ 4.1.7. ARG([numeric_expression]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ARG([numeric_expression])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
May be used only in a DEFMAIN, DEFC or DEFPROC. In the case of a DEFPROC, if
numeric_expression is not given, the number of arguments passed to the macro is
returned. Otherwise the expression is evaluated to a number and the
corresponding argument is returned. If there are fewer arguments than specified
by the expression, a null string is returned.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example:
numofargs = arg()
argfour = arg(4)
In the first example, the number of arguments that were passed is returned in
the variable numofargs. In the second example the four argument is returned in
the variable argfour.
ΓòÉΓòÉΓòÉ 4.1.8. ASC(character) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ASC('character')
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the ASCII decimal value of the character expression.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example:
ASC('A') = 65
ΓòÉΓòÉΓòÉ 4.1.9. ATOI(numeric_expression) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ATOI('numeric_expression')
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Converts the E language representation of a number (as a string) to the C
language representation of an integer (data type int). Since many functions
that are available through the function DYNALINK() require input to be in
binary numbers as opposed to ASCII strings, we provide functions to convert
ASCII strings into binary numbers. For an example of this usage see the
DYNALINK() entry in this section.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
The following shows the high-level strings and the equivalent machine
representation:
string machine representation (hexadecimal digits)
'40' 34 30 /* '4' is 0x34 & '0' is 0x30 */
atoi('40') 28 00 /* 28 00 is 40 decimal */
/* since byte swapping */
/* exists in the Intel */
/* architecture */
/* In reality the word */
/* would be 0x0028 */
ΓòÉΓòÉΓòÉ 4.1.10. ATOL(numeric_expression) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ATOL('numeric_expression')
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Converts the E language representation of a number (as a string) to the C
language representation of a long integer (data type long). For use with C
functions that require numeric parameters, for example function calls via
DYNALINK().
ΓòÉΓòÉΓòÉ 4.1.11. ATTRIBUTE_ACTION subop, var class, var offset, var column, var line [, var fileid] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ATTRIBUTE_ACTION subop, var class, var offset, var column, var line [, var
fileid]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
subop is one of the following:
const
FIND_NEXT_ATTR_SUBOP = 1
FIND_PREV_ATTR_SUBOP = 2
FIND_MATCH_ATTR_SUBOP = 3
DELETE_ATTR_SUBOP = 16
The use of the remaining parameters varies with the operation to be performed.
FIND_NEXT_ATTR_SUBOP This action finds the next occurance (not including the
specified location) of an attribute record of the specified class.
class On input, this specifies the attribute class of the attribute
records of interest. A value of ANY_CLASS (zero) indicates that the
position of the next attribute record of any class should be
returned. On output, the class of the found attribute. A class of
zero indicates that no attribute record was found.
offset On input, the location (non-inclusive) where the search is to begin.
On output, the location of the found attribute record. If none was
found, then the parameter will not be modified.
column On input, the location where the search is to begin. On output, the
location of the found attribute record. If none was found, then the
parameter will not be modified.
line On input, the location where the search is to begin. On output, the
location of the found attribute record. If none was found, then the
parameter will not be modified.
fileid The fileid of the file where the search is to occur. The default is
the current file.
FIND_PREV_ATTR_SUBOP This action is just like the FIND_NEXT_ATTR_SUBOP except
that it finds the previous occurance of an attribute record of the
specified class rather than the next occurance.
FIND_MATCH_ATTR_SUBOP This action finds the (push/pop model) attribute record
that matches the specified attribute record. For example, if a push
attribute record was specified, the location of the corresponding pop
attribute record is returned.
class Unused parameter
offset On input, the location (non-inclusive) where the search for the
match is to begin. An attribute record must exist at this location
or an error code will be flagged. On output, the location of the
found attribute record. If none was found, then the parameter will
not be modified.
column On input, the location where the search is to begin. On output, the
location of the found attribute record. If none was found, then the
parameter will not be modified.
line On input, the location where the search is to begin. On output, the
location of the found attribute record. If none was found, then the
parameter will not be modified.
fileid The fileid of the file where the search is to occur. The default is
the current file.
DELETE_ATTR_SUBOP Deletes the attribute record at the specified location. If
attribute records exists at the specified character position having
an offset of the same sign as the specified attribute record but of
larger magnitude, then those attribute records will be shifted in
(their offset will be incremented or decremented) to fill in the
vacated location.
class On input, this is unused On output, the class of the deleted
attribute record. Zero if no attribute record exists at the
specified location.
offset The location of the attribute record to be deleted.
column The location of the attribute record to be deleted.
line The location of the attribute record to be deleted.
fileid The fileid of the file where the specified attribute record is to be
found. The default is the current file.
See Attribute Pairs for additional information on attributes.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
class = 1 -- 1 = COLOR_CLASS
offst1 = -255
col = .col
line = .line
getfileid fileid
attribute_action 1, class, offst1, col, line, fileid -- 1=FIND NEXT ATTR
if class & col = .col & line = .line then -- Found one on this character.
offst2 = offst1
attribute_action 3, class, offst2, col, line, fileid -- 3=FIND MATCH ATTR
if class then -- Found a match; delete them both.
attribute_action 16, class, offst1, .col, .line, fileid -- 16=DELETE ATTR
attribute_action 16, class, offst2, col, line, fileid -- 16=DELETE ATTR
endif
endif
This code checks for a color attribute on the current character. If found, it
checks for the matching attribute. If both a Push and Pop exist, both are
deleted.
ΓòÉΓòÉΓòÉ 4.1.12. BACKTAB ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BACKTAB
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor to previous tab stop. Like the standard Shift-Tab.
ΓòÉΓòÉΓòÉ 4.1.13. BACKTABWORD ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BACKTABWORD | BACKTAB_WORD
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Positions cursor on first character of previous word, like the standard
Ctrl-Left. If there are no more previous words the cursor is positioned at
beginning of line.
ΓòÉΓòÉΓòÉ 4.1.14. BACKWARD ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BACKWARD
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Same as page_up.
ΓòÉΓòÉΓòÉ 4.1.15. BEEP([pitch [, duration] ]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BEEP( [ pitch [, duration] ] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Sounds a beep defined by pitch (in Hertz) and duration (in milliseconds). The
default pitch is 900 and the defualt duration is 500.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
BEEP(850,1000)
This example will produce a beep with a frequency of 850 Hertz for a duration
of 1 second.
ΓòÉΓòÉΓòÉ 4.1.16. BEGINLINE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BEGINLINE | BEGIN_LINE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor to beginning of current line, like the standard Home key.
ΓòÉΓòÉΓòÉ 4.1.17. BINSEARCH( string [, fileid [, flags [, startcol]]]) ΓòÉΓòÉΓòÉ
New in EPM 6.
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BINSEARCH( string [, fileid, [, flags [, start_col ]]] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Performs a binary search in the current or specified file for the specified
search_string. Returns the line number on which a match was found, or 0 for
failure. The comparison starts at column start_col in the file (the default
column is 1). The default value for flags is 0. Possible values are any
combination of:
1 Perform a case-insensitive comparison.
2 Compare only the first length(string) characters; don't require that the
entire line matches.
Note: The file to be searched must be sorted in the same way that the search
is being performed (case-sensitive or case-insensitive).
ΓòÉΓòÉΓòÉ 4.1.18. BOTTOM, BOT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BOTTOM | BOT
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor to last line of file, like the standard Ctrl-End.
ΓòÉΓòÉΓòÉ 4.1.19. BROWSE( 0 | 1 ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BROWSE([0 | 1])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Turns browse mode on for the current file. Browse mode is a read-only mode. 0
turns the browse mode off; 1 turns it on. If no argument is given BROWSE
returns the current mode.
ΓòÉΓòÉΓòÉ 4.1.20. BUFFER( subfunction_number, parameters... ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BUFFER()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is for developers of advanced applications who want to share text with external
processes. It allows an E application to create a shared memory buffer of a
specified name and copy text to it, so that other processes can open the buffer
and read the text from E. (For those interested in OS/2 internals, the buffer
creation calls DosAllocShrSeg().)
The buffer function provides several subfunctions: create a new buffer; open
an existing buffer; free a buffer; get and put text; query the allocated and
used size of a buffer. You specify the subfunction you want with the first
argument, one of: CREATEBUF, OPENBUF, FREEBUF, GETBUF, PUTBUF, MAXSIZEBUF, or
USEDSIZEBUF. (These are only numeric constants from 0 to 6, as defined in
STDCONST.E.) The meaning of the remaining arguments to buffer() depends on the
subfunction, as shown in the seven cases below.
The maximum buffer size is 65535 bytes. E uses the first 32 bytes of the
buffer for status information:
2 bytes: bufsize available for text,
without the header
2 bytes: amount of buffer filled, <= bufsize
2 bytes: format (explained below)
2 bytes: number of lines if known
(E fills this in on a PUT)
26 bytes: reserved for anything
the application might want.
Thus the maximum space available for text is 65535-32 = 65503 bytes.
bufhndl = buffer( CREATEBUF, name [,size [,private]])
CREATEBUF allocates a shared memory segment of name "\SHAREMEM\name". The
prefix "\SHAREMEM\" is automatic and shouldn't be supplied. The size
specification is optional. If it's zero or omitted, it defaults to the maximum
size of 65503.
A last optional argument, private, can be supplied with a nonzero value if you
do not want want the buffer to be shared by other processes. You might wish to
create a memory buffer for use by your application only, in which case you
should specify private to avoid using one of the limited number of OS/2 shared
buffers. (Technically, a private buffer is created with DosAllocSeg() rather
than DosAllocShrSeg().)
The return value from CREATEBUF is a handle or ID, to be used by the other
subfunctions. (Actually the handle is the buffer segment selector, in string
form like that returned by seg(), ready for use by peek and poke.) A return
value of 0 means an error; RC will contain the error code given by OS/2.
bufhndl = buffer( OPENBUF, name)
OPENBUF shares a buffer created by another process. Again, bufhndl is
returned; zero means a system error is returned in RC. It is expected that the
other process has put the format and size into the first 2 words of the buffer,
and starts the data at offset 32.
success = buffer( FREEBUF, bufhndl)
FREEBUF frees the buffer. It's not required if you're exiting from E, but
recommended. The return value is zero if an error occurred, for consistency;
zero means an error for all these subfunctions.
noflines= buffer( GETBUF, bufhndl)
GETBUF loads all of a buffer into the current file at the current location, in
the same manner as a GET command. You have no control over the number of
lines; normally you'll do the GETBUF into a new empty file. The return value
is the number of lines transferred. A zero value along with a zero RC means the
buffer was empty. (Note: RC is automatically zeroed at the start of any
buffer() function.)
noflines= buffer( PUTBUF, bufhndl, startline
[,endline [,format]])
PUTBUF copies the current file's text from startline through endline. If
endline is omitted, or specified as zero or a huge value, as many whole lines
are copied as will fit, stopping at the end of file of course. The return value
is the number of lines transferred.
size = buffer( MAXSIZEBUF, bufhndl)
MAXSIZEBUF returns the buffer capacity, in case some other process created it
and you don't know its size. (This subfunction gives the same value as
peek(bufhndl,0,2).)
size = buffer( USEDSIZEBUF, bufhndl)
USEDSIZEBUF returns the size of data in the buffer. (This gives the same value
as peek(bufhndl,2,2).)
The format word in the header determines how the lines are formatted. It's a
bit string so you can mix and match options:
APPENDCR 1 append ASCII 13 after each line
APPENDLF 2 append ASCII 10 after the CR if any
APPENDNULL 4 append ASCII 0 after the CR-LF if any
TABCOMPRESS 8 tab-compress the line
STRIPSPACES 16 remove trailing spaces as usual in a save
FINALNULL 32 append a null at end of the buffer
The default format if unspecified is 19, for CR-LF and remove trailing spaces.
Note: The format is ignored on a GET. E handles whatever characters it finds,
in the same manner as loading a disk file. CR-LF's are dropped, tabs are
expanded.
Note 2: if an external process fills a buffer, it should make sure that the
last line is properly terminated with the appropriate end-of-line. E will
double-check for this to protect against overrunning the end of the buffer. E
will deposit an end-of-line if needed and restore whatever character was there,
but this might not be what the other process expected.
For sample usages, see the file BUFF.E.
ΓòÉΓòÉΓòÉ 4.1.21. BUILDACCELTABLE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BUILDACCELTABLE table_name, command, accel_flags, key, index
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Adds an entry to an accelerator table. 'tablename' is the name of the
accelerator table being built (and is later passed as a parameter to the
activateacceltable statement), 'command' is the command to be executed when the
accelerator key is pressed, accel_flags is the sum of some AF_ constants from
STDCONST.E, 'key' is as ASCII value for AF_CHAR, a VK_ constant for
AF_VIRTUALKEY, etc., and 'index' is a unique index number for that table. You
can reuse an index value to replace an entry in the accelerator table.
Note: Index values must be unique in both the current accelerator table and
the current action bar.
Some of the VK_ constants are defined in STDCONST.E; the full set can be found
in PMWIN.H in the OS/2 toolkit.
See also:
o Building Accelerator Tables from the Macro Language
o ACTIVATEACCELTABLE
o DELETEACCEL
o QUERYACCELSTRING
ΓòÉΓòÉΓòÉ 4.1.22. BUILDMENUITEM ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BUILDMENUITEM
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is used to build entries on the action bar menu. See Building Menus from the
Macro Language for more information on the BUILDMENUITEM statement.
ΓòÉΓòÉΓòÉ 4.1.23. BUILDSUBMENU ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
BUILDSUBMENU
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is used to build sub menu entries on the action bar menu.
ΓòÉΓòÉΓòÉ 4.1.24. CALL procedurename() ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
CALL procedurename
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Throws away the result of the procedure call. You could substitute any
expression for procedurename, e.g. call 2*2, but typically it will be a
procedure call such as "call machine()".
Throwing away the result of a procedure call is often necessary because
otherwise the result is executed. If a procedure returns 0, the valid command
'0' is executed which takes the cursor to the "Top of File" header (line 0).
Generally is always advisable to use the call statement unless the returned
value is used in some manner.
ΓòÉΓòÉΓòÉ 4.1.25. CENTER(string, length [, pad] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
CENTER( string, length [, pad] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns a string of length length with string centered in it, with pad
characters added as necessary to make up length. The default pad character is a
space. If the string is longer than length, it will be truncated at both ends
to fit. If an odd number of characters are truncated or added, the right hand
end loses or gains one more character than the left hand end.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
CENTER(abc,7) -> ' ABC '
CENTER(abc,8,'-') -> '--ABC---'
CENTRE('The blue sky',8) -> 'e blue s'
CENTRE('The blue sky',7) -> 'e blue '
ΓòÉΓòÉΓòÉ 4.1.26. CENTRE(string, length [, pad] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
CENTRE( string, length [, pad] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
(same as CENTER)
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
(same as CENTER)
ΓòÉΓòÉΓòÉ 4.1.27. CHR(numeric_expression) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
CHR( value )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is the inverse of ASC(), CHR() returns the character corresponding to the ASCII
value.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example,
CHR( ASC('A') ) = 'A'
CHR(65)='A'
ΓòÉΓòÉΓòÉ 4.1.28. CIRCLEIT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
CIRCLEIT style, line, col1, col2, attribute1, attribute2
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Draws a circle on the screen for highlighting a section of text. The circle
goes away when the screen is refreshed. 'line' is the line number of the file
to be highlighted, and col1 and col2 are the first and last columns. There are
five styles of circle; only the first two are available to EPM 5.51.
1. a perfect circle or oval.
2. a rougher version with the ends crossing rather than meeting, and drawn
using 2 different colors.
3. a wider version of (1).
4. a wider version of (2).
5. a perfect, solid (filled-in) circle or oval.
In EPM 5.51, the highlighting is added by XORing onto the screen, so the color
displayed is a function of the screen background color and can not be directly
controlled. ('Attribute' is currently unused.) The two styles use different
XOR masks.
In EPM 6, the color of the highlighting is specified by attribute1 (and by
attribute2 for the styles which use 2 colors). The value for each can either
be a number 0 to 15, corresponding to one of the foreground colors defined in
COLORS.E, or it can be an XOR mask (indicated by adding 16,777,216 to the value
of the desired mask). An XOR mask is generally preferable, since the color
will automatically be adjusted according to the background - a specific color
might not show up if the background or mark color is the same color. The
values corresponding to the built-in defaults of EPM 5.51 are 16777220 for
attribute1 and 16777218 for attribute2.
ΓòÉΓòÉΓòÉ 4.1.29. COMPARE(string1, string2 [, pad] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
COMPARE( string1, string2 [, pad] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns 0 if the strings, string1 and string2, are identical. If they are not,
the returned number is non-zero and is the position of the first character that
does not match. The shorter string is padded on the right with pad if
necessary. The default pad character is a space.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
COMPARE('abc','abc') -> 0
COMPARE('abc','ak') -> 2
COMPARE('ab ','ab') -> 0
COMPARE('ab ','ab',' ') -> 0
COMPARE('ab ','ab','x') -> 3
COMPARE('ab-- ','ab','-') -> 5
ΓòÉΓòÉΓòÉ 4.1.30. COPIES(string, n) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
COPIES( string, n )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns n concatenated copies of string. n must be positive or 0.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Examples:
COPIES('abc',3) -> 'abcabcabc'
COPIES('abc',0) -> ''
ΓòÉΓòÉΓòÉ 4.1.31. COPYMARK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
COPYMARK | COPY_MARK
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Copies marked text to cursor position, like standard Alt-C.
ΓòÉΓòÉΓòÉ 4.1.32. COUNT(string1, string2) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
COUNT( string1, string2 )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the number of occurrances of string1 that appear in string2.
Note: This procedure is only available in EPM 5.60 or above.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
COUNT('abc','abcdef') == 1
COUNT('abc','abcabc') == 2
COUNT('abc','abxc') == 0
COUNT('xx ','xxx') == 2
ΓòÉΓòÉΓòÉ 4.1.33. CURSOR_DIMENSIONS ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
CURSOR_DIMENSIONS cursorw, cursorh
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Queries or sets the cursor dimensions. 'cursorw' and 'cursorh' must be
variables. If their values are question marks, they will be changed to reflect
the current dimensions. If their values are numbers, this will set the size of
the text cursor. A positive number represents that number of pixels; a negative
number represents a proportional value of the size of the current character.
The absolute value of that number is used as the number of 128ths of the height
or width of the current character that the cursor should be drawn.
ΓòÉΓòÉΓòÉ 4.1.34. C2X(string) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
C2X( string )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns a printable hexadecimal representation of the binary string string.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
C2X('abc123') == '616263313233'
C2X( \15' '\240 ) == '0f20f0'
C2X( atoi(255) ) == 'ff00'
ΓòÉΓòÉΓòÉ 4.1.35. DELETE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DELETE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes the line the cursor is located on. Note that the statement DELETELINE
allows parameters, but DELETE does not.
Note: Previously, DELETE_LINE was a synonym for DELETE. This was dropped
because it was felt that it was too confusing to have two statements,
DELETE_LINE and DELETELINE, with different behaviors.
ΓòÉΓòÉΓòÉ 4.1.36. DELETEACCEL ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DELETEACCEL tablename
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes the named accelerator table.
See also:
o Building Accelerator Tables from the Macro Language
o ACTIVATEACCELTABLE
o BUILDACCELTABLE
o QUERYACCELSTRING
ΓòÉΓòÉΓòÉ 4.1.37. DELETECHAR ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DELETECHAR | DELETE_CHAR
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes character under cursor, like standard Del.
ΓòÉΓòÉΓòÉ 4.1.38. DELETELINE [line_number [,var fileid] ] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DELETELINE line_number [, {;} fileid]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes a specified line from a specified file. Defaulted values for omitted
parameters are line_number = current line, and fileid = current file.
This is NOT the same as DELETE_LINE: see the clarification above, under DELETE.
ΓòÉΓòÉΓòÉ 4.1.39. DELETEMARK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DELETEMARK | DELETE_MARK
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes marked text, like standard Alt-D.
ΓòÉΓòÉΓòÉ 4.1.40. DELETEMENU ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DELETEMENU (stmt)
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes a menu option or submenu option from the action bar. For more
information on DELETEMENU see Building Menus from the Macro Language.
ΓòÉΓòÉΓòÉ 4.1.41. DELSTR(string, n [, length] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DELSTR( string, n [, length] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes the substring of string that begins at the nth character, and is of
length length, and returns the result. If length is not specified, the rest of
string is deleted. If n is greater than the length of string, the string is
returned unchanged. n must be positive.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
DELSTR('abcd',3) -> 'ab'
DELSTR('abcde',3,2) -> 'abe'
DELSTR('abcde',6) -> 'abcde'
ΓòÉΓòÉΓòÉ 4.1.42. DELWORD(string, n [, length] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DELWORD( string, n [, length] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes the substring of string that begins at the nth word, and is of length
length blank-delimited words, and returns the result. If length is not
specified, the rest of string is deleted. n must be positive. If n is greater
than the number of words in string, the string is returned unchanged. The
string deleted includes any blanks following the final word involved.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
DELWORD('Now is the time',2,2) -> 'Now time'
DELWORD('Now is the time ',3) -> 'Now is '
DELWORD('Now is the time',5) -> 'Now is the time'
ΓòÉΓòÉΓòÉ 4.1.43. DIRECTORY([path]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DIRECTORY( [string_expression] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns current directory. If path parameter is given, the current drive and
path are changed accordingly.
Note: The drive and path are changed before the current directory is returned.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
This provides a way of verifying that a user-supplied path is valid.
current_dir = directory() -- Save current
if upcase(directory(user_dir)) <> upcase(user_dir) then -- Try user's
sayerror 'Directory 'user_dir' is invalid.' -- Warn
endif
call directory(current_dir) -- Restore
ΓòÉΓòÉΓòÉ 4.1.44. DISPLAY '-4' | '-2' | '-1' | '1' | '2' | '4' ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DISPLAY -4|-2|-1|1|2|4
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Allows screen updates to be turned off (-1) or on (1); non-critical messages to
be turned off (-2) or on (2); and errors to be forced to the message box (-4)
or to the default messageline (4).
These numbers can be combined. (DISPLAY -3 would turn off the screen updates
and the error messages.)
DISPLAY -1 prevents the screen from begin updated until a DISPLAY 1 statement
is issued. This can eliminate files being flashed on the screen briefly while
an application loads and manipulates files.
When a DISPLAY 4 is in effect, all messages (unless explicitly sent to a dialog
box) will be sent to:
1. first to the message line, unless toggled off;
2. next to the status line, unless toggled off;
3. or else overwrites the first line of text temporarily.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
An sample usage of DISPLAY is:
display -3 -- turn off display updates
getfileid startfid -- and error messages
'xcom e profile.xxx' -- load the profile
getfileid profile_fid -- won't show on screen
.visible = 0 -- make a hidden file
'xcom 1 /define' -- if not found, no error message
activatefile startfid -- activate the file
display 3 -- turn updates & messages on
In this example the user would see no screen flashing or "Not found" error
message.
ΓòÉΓòÉΓòÉ 4.1.45. DO ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in the section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in the section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ 4.1.46. DO_ARRAY ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DO_ARRAY
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Handles arrays in E. The DO_ARRAY statement can create an array, add to the
array, and lookup information from the array. The syntax for these functions
is:
do_array 1, array_id, arrayname
Creates an array of arrayname and returns
the array_id in the variable array_id.
do_array 2, array_id, index, value
Adds the value to the array under the index
in the array denoted by array_id.
do_array 3, array_id, index, result
Looks up the contents of the index entry of
the array specified by array_id and places
the value into result. If the index is not
found, an error message is given (Invalid
third parameter), the return code is set to
-330, and the result variable is set to the
null string.
do_array 4, array_id, index
This will delete an entry specified, by
INDEX, from the array.
do_array 6, array_id, array_name
Returns the array_id associated with the
array name specified by array_name
do_array 7, array_id, index, result
(32-bit EPM only.) Looks up the contents of
the index entry of the array specified by
array_id and places the value into result.
If the index is not found, the value of the
array's .userstring is returned, and no
error message is given, nor is the return
code set.
See Arrays in EPM for more information on arrays and the DO_ARRAY statement.
ΓòÉΓòÉΓòÉ 4.1.47. DO_OVERLAYWINDOWS ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DO_OVERLAYWINDOWS
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Provides various functions for the manipulation of graphics within a document.
Further information on graphics within EPM and the E Toolkit will be made
available.
ΓòÉΓòÉΓòÉ 4.1.48. DOWN ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DOWN
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves the cursor down 1 line, like the standard Down key.
ΓòÉΓòÉΓòÉ 4.1.49. DYNAFREE(library_name) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DYNAFREE( number )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Releases a dynalink library that has been previously called using the dynalink
statment. Also see the DYNALINK and DYNALINKC statements for more information.
ΓòÉΓòÉΓòÉ 4.1.50. DYNALINK(library_name, function_name, parameter_stack, [number_of_return_words]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DYNALINK( library_name, function_name, parameter_stack [,
number_of_return_words ])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Provides an interface between an E language program and external functions
stored in a dynamic link library. The operating system functions are
implemented via dynamic linking, and therefore DYNALINK() provides you with the
full power of the operating system calls such as DosDelete, DosQFileMode,
DosDevIOCtl, and video input/output calls such as VioWrtTty, VioWrtCharStrAtt,
and much more. DYNALINK() allows you to call any dynamic link library that
exists (files with a .DLL extension). Since application writers can develop
general purpose dynamic link libraries, E programs can call functions written
in other languages. For example, let us say that the "C" library functions are
available via a dynamic link library, then we may call the library functions
from an E program; or suppose that a spell checking dynamic link library
exists, DYNALINK() allows you to use the spell checking.
This procedure is the protect-mode equivalent of the INT86X() function of E3.
For more information on the system functions or dynamic link libraries, please
refer to The OS/2 Technical Reference.
In order to make a system call, you must provide the following parameters to
dynalink():
library_name the name of the dynalink library (e.g. file
library_name.DLL) which contains the function you wish
to call.
function_name this is a string containing the function name in most
cases. However if you are making calls to some DOS
functions (DOS functions being those whose names begin
with 'Dos') that are contained within the DOSCALLS.DLL
library, the function name is actually the ordinal
value of the DOS function, preceded by a '#'. These
numbers can be found in Ordinal Values of Functions
Accessed via DOSCALLS.DLL.
parameter_stack a string consisting of all of the parameters expected
by the function, concatenated together into one
string. Those parameters that the function requires to
be pushed on the parameter stack first should appear
first when concatenating. Parameter information is
dependent upon the function to be called, and can be
found in The OS/2 Technical Reference.
number_of_return_words an optional parameter that allows one to set the size
of the return code variable that the system should
expect to receive from the dynamic link function. This
parameter is provided for those dynalink library
functions whose return code is a long int rather than
simply an int. If the user simply uses DYNALINK() for
system calls to DOS and OS/2 functions, this parameter
need never be specified. The default value is 1.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
The numeric parameters passed by the E program must be converted from string
form to the proper C data type via E functions like ATOI(), ATOL(), SELECTOR(),
and OFFSET(), as shown below:
defc hello =
string = 'hello'
result = dynalink( 'VIOCALLS', /* library name */
'VIOWRTTTY', /* function name */
selector(string) || /* address of */
offset(string) || /* string */
atoi(length(string)) ||/* length */
atoi(0) ) /* vio handle */
defc curdir2 =
/* create empty strings for DosQCurDir() to fill */
string = atoi(80) || substr('',1,80)
stringlen_b = substr('',1,2)
result = dynalink( 'DOSCALLS', /* library name */
'#71', /* ordinal of DosQCurDir */
atoi(0) || /* drive number */
selector(string) || /* address of */
offset(string) || /* DirPath buffer */
selector(stringlen_b) || /* address of */
offset(stringlen_b) ) /* buf length */
stringlen = itoa(stringlen_b,10);
sayerror 'The current directory is "' ||
substr(string,1,stringlen) || '".'
defc beep =
result = dynalink( 'DOSCALLS', /* library name */
'#50', /* ordinal of Dos Beep() */
atoi(3000) || /* frequency of beep */
atoi(1000) ) /* duration of beep */
defc clear_semaphore =
result = dynalink( 'DOSCALL1', /* library name */
'DOSSEMCLEAR', /* function name */
atol(handle) ) /* semaphore handle */
ΓòÉΓòÉΓòÉ 4.1.51. DYNALINKC(library_name, function_name, parameter_stack, [number_of_return_words]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DYNALINKC( library_name, function_name, parameter_stack [,
number_of_return_words ])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is used to load and pass information to a dynalink library. It is like the
DYNALINK() procedure except that it passes its parameters using the C language
parameter passing convention rather than the Pascal convention. See the file
DYNATEST.E for examples of the use of DYNALINKC(). Also see DYNAFREE() for
information about releasing a dynalink library and DYNALINK() for information
about calling a dynalink library procedure using standard Pascal parameter
passing conventions.
ΓòÉΓòÉΓòÉ 4.1.52. DYNALINK32(library_name, function_name, parameter_stack, [number_of_return_words]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
DYNALINK32( library_name, function_name, parameter_stack [,
number_of_return_words ])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is used to load and pass information to a dynalink library. It is like the
DYNALINKC() procedure except that it is used for calling 32-bit DLLs.
Note: This procedure is only available in EPM 5.60 or above.
ΓòÉΓòÉΓòÉ 4.1.53. ECHO( 'on'|'off' ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ECHO( [ON | OFF] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Displays the command about to be executed. This is useful for debugging E code.
ΓòÉΓòÉΓòÉ 4.1.54. ENDLINE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ENDLINE | END_LINE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Positions the cursor at end of current line, like standard End.
ΓòÉΓòÉΓòÉ 4.1.55. ERASEENDLINE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ERASEENDLINE | ERASE_END_LINE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Erases the rest of current line starting at cursor position, like standard
Ctrl-E.
ΓòÉΓòÉΓòÉ 4.1.56. EXECUTE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
EXECUTE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Executes the contents of the command dialog box.
ΓòÉΓòÉΓòÉ 4.1.57. EXECUTEKEY key ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
EXECUTEKEY keyname | identifier
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Interprets key as if typed by user; key may be any valid expression. This is
very similar to the KEY statement, except that KEY can take only a literal key
name as in KEY A_L. EXECUTEKEY can take a variable, as in k=page_down;
executekey k. In fact the KEY statement is superfluous, since EXECUTEKEY can
be given a literal key name.
ΓòÉΓòÉΓòÉ 4.1.58. EXIT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
EXIT [return_code]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Exits the current E macro and all calling macros. This is useful to halt a
macro execution if a fatal error is generated. See the RETURN statement to exit
only the current macro.
A return code can be given as an argument.
ΓòÉΓòÉΓòÉ 4.1.59. FILECOMPARE( fileid1, fileid2 [, flag] ) ΓòÉΓòÉΓòÉ
New in EPM 6.
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
FILECOMPARE( fileid1, fileid2, [, flags ] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Compares the 2 files, starting at the current line of each, and stopping on the
first mismatch or when the end of one file is reached. The return value is 0 if
there were no differences, 1 if a mismatch occurred, and 2 if the end of only
one file was reached. The default value for flags is 0. Possible values are
any combination of:
1 Ignore differences in the number of leading and trailing spaces on each
line.
2 Perform a case-insensitive comparison.
4 Compare only a single pair of lines.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
See EPMCOMP.E for an example of the use of this function.
ΓòÉΓòÉΓòÉ 4.1.60. FILESINRING( [number] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
FILESINRING( [ number ] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the number of files in the ring. If number is 0 or missing, the number
of normal files in the ring is returned. If number is 1 the total number of
files is returned, including hidden files and arrays. If number is 2 the
maximum number of files currently allocated is returned. This corresponds to
the size of an internal structure, and in the current release will always be a
power of 2. An attempt to load more than this number of files will result in a
new structure being allocated, with room for twice as many files.
ΓòÉΓòÉΓòÉ 4.1.61. FILESIZE() ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
FILESIZE()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns sum of the lengths of each line in the file.
ΓòÉΓòÉΓòÉ 4.1.62. FILLMARK [character] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
FILLMARK [ 'character' ] | FILL_MARK [ 'character' ]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
If a character is given, fills the marked area with character. If no character
is specified, the user is asked to type a character for the fill. Like the
standard Alt-F.
ΓòÉΓòÉΓòÉ 4.1.63. FINDFILE destfilename, filename [,environment_path_variable, ('P'|'D') ] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
FINDFILE filename , destfilename [, environment_path_variable, (P|D)]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Searches for filename in the current directory and returns its entire pathname
in destfilename.
Note: This statement depends upon the program FILEFIND.EXE, which is available
on the PCTOOLS disk. You must download this into a directory which is in your
PATH environment variable (or the same directory as the E files) before this
statement will work properly.
The 'P' option specifies program searching. It forces a search for a file with
the extension .EXE or .CMD in each directory named in the
environment_path_variable. If environment_path_variable is "PATH", the effect
is the same as a normal OS/2 program search. Some variable other than path can
be specified, for example "EPMPATH", and that string will be looked up in the
environment. (The area where OS/2 keeps strings SET by the user.)
The 'P' option also checks whether the filename is an internal OS/2 command.
If so, destfilename is set up for invocation of the command processor, with
"COMMAND.COM /C" at the start.
If the 'D' option is used, the third parameter (environment_path_variable) is
ignored (although at least a null string must be passed in anyway). The 'D'
option will cause filename to be searched for in the following directories:
1. the current directory, and then
2. the directories listed in the EPMPATH environment variable (if it is
defined), and then
3. the directories in the DPATH environment variable, and then
4. the same directory as the file EPM.EXE.
An example of usage is:
findfile complete_filespec, 'e3help.hlp', '', 'D'
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Examples:
findfile cmdline,'dir','','P'
If rc is zero (no error) then cmdline could
be 'C:\COMMAND.COM /C dir'
findfile cmdline,'subdir','PATH','P'
If rc is zero then cmdline could
be 'C:\UTIL\subdir.com'
ΓòÉΓòÉΓòÉ 4.1.64. FOR ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ 4.1.65. GETFILEID ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
GETFILEID identifier [ ',' {';'} string_expression]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in the section Fileid Structure.
ΓòÉΓòÉΓòÉ 4.1.66. GETKEYSTATE( virtual_key_code ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
GETKEYSTATE(number )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is used to test the shift state of the shift keys. This statement replaces E's
previous statements of: GETSHIFTSTATE and SETSHIFTSTATE. The syntax for EPM's
GETKEYSTATE is:
keystate = getshiftstate( virtual_key_code)
where the virtual_key_code is one of the VK codes from PMWIN.H. For
convenience, the returned test states of VK codes (like PositiveOdd and
NegativeEven) have been converted to single values as follows:
KS_DOWN 1 (NegativeEven; key is down)
KS_DOWNTOGGLE 2 (NEgativeOdd; key is down + toggled)
KS_UP 3 (PositiveEven; key is up)
KS_UPTOGGLE 4 (PostiveOdd; key is up + toggled)
ΓòÉΓòÉΓòÉ 4.1.67. GETLINE var line [, line_number [, var fileid] ] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
GETLINE line [, {;} line_number [ , {;} fileid] ]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Gets a specified line from a specified file into the variable line. Defaulted
values for omitted parameters are line_number = current line, and fileid =
current file.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example:
GETLINE line
/* line = current line of current file */
GETLINE line, 7
/* line = line 7 of current file */
GETLINE line, 3, ThatFile
/* line = line 3 of file whose fileid
is in variable ThatFile */
The statement:
GETLINE line, 0
results in the variable line being set to null.
ΓòÉΓòÉΓòÉ 4.1.68. GETMARK var first_line_num,var last_line_num [,var first_col [,var last_col [, var fileid] ] ] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
GETMARK first_line [, {;} last_line [, {;} first_col [, {;} last_col [ , {;}
mark_fileid ] ] ]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the current mark coordinates and fileid. If no mark exists, the values
returned are meaningless; use the function MARKTYPE() to precheck whether a
mark exists.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
IF MARKTYPE()<>'' THEN /* text marked? */
/* Get active mark coordinates and fileid */
GETMARK first_line, last_line,first_col,
last_col, mark_fileid
ENDIF
ΓòÉΓòÉΓòÉ 4.1.69. GETMARKG var first_line_num,var last_line_num [,var first_col [,var last_col [, var fileid] ] ] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
GETMARKG first_line [, {;} last_line [, {;} first_col [, {;} last_col [, {;}
mark_fileid ] ] ]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Like GETMARK in that it returns the current mark coordinates and fileid, but
unlike GETMARK, the last_col parameter of GETMARKG represents the right edge of
the mark as opposed to the last column in the mark.
ΓòÉΓòÉΓòÉ 4.1.70. GETPMINFO (function ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
GETPMINFO( parameter )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
The following are constants values that are to be used as parameters to the
getpminfo internal function:
HAB 0 EDITORMSGAREA 8
OWNERCLIENT 1 EDITORVSCROLL 9
OWNERFRAME 2 EDITORHSCROLL 10
PARENTCLIENT 3 EDITORINTERPRETER 11
PARENTFRAME 4 EDITVIOPS 12
EDITCLIENT 5 EDITTITLEBAR 13
EDITFRAME 6 EDITCURSOR 14
EDITSTATUSAREA 7
Depending on the parameter passed, certain PM information will be returned. See
the OS/2 Reference Manual for more information on the meanings of these
constants and the meaning of the information returned.
Also the the file STDCTRL.E for sample usage of the GETPMINFO command.
ΓòÉΓòÉΓòÉ 4.1.71. GETSEARCH var search_cmd ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
GETSEARCH identifier
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Saves last search command in string variable search_cmd. See the SETSEARCH
command for retrieving such a command, and examples of usage.
ΓòÉΓòÉΓòÉ 4.1.72. HEX( character ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
HEX( 'character' )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the hexadecimal value associated with the ASCII representation of
character.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
HEX('A') = 41
ΓòÉΓòÉΓòÉ 4.1.73. IF - THEN - ELSE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ 4.1.74. INCLUDE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in section Compiler Directive Statements and in The EPM User's
Guide.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Compiler Directive Statements and in The EPM User's
Guide.
ΓòÉΓòÉΓòÉ 4.1.75. INSERT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
INSERT
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Inserts a new line after the current line and position cursor in same column of
new line as the first non-empty column of the previous line.
Note: Previously, INSERT_LINE was a synonym for INSERT. This was dropped
because it was felt that it was too confusing to have two statements,
INSERT_LINE and INSERTLINE, with different behaviors.
ΓòÉΓòÉΓòÉ 4.1.76. INSERT_ATTRIBUTE class, value, isPush, offset [, col [, line [, fileid]]] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
INSERT_ATTRIBUTE class, value, isPush, offset [, col [, line [, fileid]]]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
This statement (non destructively) inserts an attribute record at the specified
location.
Class The class of the attribute record to be inserted.
Value The value field of the attribute record to be inserted.
IsPush The support field of the attribute to insert.
Offset The offset of the position being queried. Offsets must be negative,
and indicate a position before the specified character location.
...[ar-2][ar-1][char]...
If a negative offset is specified that is less (more negative) than the
smallest offset of an attribute record at the specified column, then
the new attribute record is placed at an offset that is one less than
the smallest offset.
If an attribute record already exists at the specified offset, then the
old attribute record (and any attribute records at an offset of larger
magnitude) is shifted to an offset of greater magnitude to vacate the
specified offset for the new attribute record.
Column The column number where the new attribute record should be placed. If
this parameter is omitted, the current column of the cursor is assumed.
Line The line number where the new attribute record should be placed. If
this parameter is omitted, the current line number of the cursor is
assumed.
Fileid The fileid of the file where the new attribute record should be placed.
If this parameter is omitted, the active file is assumed.
See Attribute Pairs for additional information on attributes.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
class = 1 -- COLOR_CLASS
val = Red + WhiteB -- Red on a white background
insert_attribute class, val, 1, -1, 1
insert_attribute class, val, 0, -1, length(textline(.line))+1
if not (.levelofattributesupport // 2) then -- Turn on mixed color support
.levelofattributesupport = .levelofattributesupport + 1
endif
This will color the current line red. Note that the pop attribute is put at
the end of the line + 1, since it attaches to the left side of a character, and
we want the last character to be colored as well.
ΓòÉΓòÉΓòÉ 4.1.77. INSERTLINE new_line [ ,line_number [,var fileid] ] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
INSERTLINE new_line [,{;} line_number [, {;} fileid] ]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Inserts contents of variable new_line just before the designated line of a
specified file. Defaulted values for omitted parameters are line_number =
current line, and fileid = current file. Without arguments INSERTLINE is
identical to the INSERT statement.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
INSERTLINE line
/* inserts line before current line of current file */
INSERTLINE line, 7
/* inserts line before line 7 of current file */
INSERTLINE line, 3, ThatFile
/* inserts line before line 3 of file whose fileid
is in variable ThatFile */
ΓòÉΓòÉΓòÉ 4.1.78. INSERTSTATE() ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
INSERTSTATE()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the insert state of EPM. A 1 means insert mode is active; 0 means
overwrite mode is active.
ΓòÉΓòÉΓòÉ 4.1.79. INSERTSTR(new, target [, n [, length [, pad ]]]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
INSERTSTR( new , target [, n [, length [, pad]]] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Inserts the string new, padded to length length, into the string target after
the nth character. length and n must be non-negative. If n is greater than the
length of the target string, padding is added there also. The default pad
character is a blank. The default value for n is 0, which means insert before
the beginning of the string.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
INSERTSTR(' ','abcdef',3) -> 'abc def'
INSERTSTR('123','abc',5,6) -> 'abc 123 '
INSERTSTR('123','abc',5,6,'+') -> 'abc++123+++'
INSERTSTR('123','abc') -> '123abc'
INSERTSTR('123','abc',,5,'-') -> '123--abc'
ΓòÉΓòÉΓòÉ 4.1.80. INSERTTOGGLE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
INSERTTOGGLE | INSERT_TOGGLE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Toggles cursor from insert mode to replace mode and vice versa. Like pressing
the standard Ins key.
ΓòÉΓòÉΓòÉ 4.1.81. ISADEFC ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ISADEFC ( expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Boolean function that tells whether or not a macro-defined command with the
given name exists.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
if isadefc('mysave') then
'mysave' arg(1)
endif
ΓòÉΓòÉΓòÉ 4.1.82. ISADEFPROC ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ISADEFPROC ( expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Boolean function that tells whether or not a macro-defined procedure with the
given name exists.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
if ISADEFPROC('myfunction') then
call myfunction('Exiting')
endif
ΓòÉΓòÉΓòÉ 4.1.83. ISADIRTYLINE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ISADIRTYLINE()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Boolean function that tells whether or not the current line has been modified
but not yet "checked in". This corresponds to whether or not the undo opcode
will change the line; the function was added in order to enable the Undo menu
item to be greyed if not applicable.
ΓòÉΓòÉΓòÉ 4.1.84. ITERATE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ 4.1.85. ITOA(variable, radix) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
ITOA( variable, radix )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Converts a two byte binary representation of an integer stored in variable to a
string representation of the integer, so that the E language can understand it.
radix specifies the base of the number (i.e. base 10 = decimal; base 16 =
hexadecimal) to be converted to a string representation. This function is often
used to convert integers returned by dynalink library functions from binary
representation to ASCII string representation. See DYNALINK() for an example of
the use of ITOA().
ΓòÉΓòÉΓòÉ 4.1.86. JOIN ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
JOIN
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Joins the next line with current line, with an intervening space. Like the
standard a_J key combination.
ΓòÉΓòÉΓòÉ 4.1.87. KEYIN expression ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
KEYIN expression
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Types expression at current cursor position as if typed from the keyboard
without translation or execution. expression is most often a quoted command,
although it can also be a numeric expression.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example, one could enter the current date:
parse value getdate(1) with today';' . /* Discard MonthNum. */
keyin 'Today is' today'.'
One could also type graphics characters in the text by placing the cursor at
the desired location and issuing the statement:
keyin \24
ΓòÉΓòÉΓòÉ 4.1.88. KEYS name ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
KEYS name
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Changes to the keyset name. The keyset is created by the DEFKEYS statement Key
Definitions (DEF and DEFKEYS). The KEYS statement can be used in conjunction
with DEFLOAD DEFLOAD.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
The following example changes to a keyset that enhances keys such that the C
programming language syntax could be recognized:
defload
ext=filetype(name) -- get file extention
if ext='C' then -- test file is a c file
keys c_keys -- change to new keyset
endif
ΓòÉΓòÉΓòÉ 4.1.89. LASTERROR() ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LASTERROR()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the last error code. The example illustrates its usage.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
'tabs 0'
'ma 75 1'
if lasterror() = -271 then
sayerror "margin setting error"
elseif lasterror() = -272 then
sayerror "tabs setting error"
else
sayerror "no error"
endif
In the above example, an error would occur while trying to set both tabs and
margins. LASTERROR() would return -271, and margin setting error would be
printed. Assume the following two lines were substituted for the first two
lines of the above example:
'tabs 0'
'margins 1 75'
The result of LASTERROR() would be -272, and tabs setting error would be
printed. In this way, you can retain the error code returned by a command even
after a second command completes successfully.
ΓòÉΓòÉΓòÉ 4.1.90. LASTKEY([key_number]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LASTKEY( [0 | 1 | 2 | 3] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the user's last keystroke, whether typed manually or executed by a
KEYIN or EXECUTEKEY statement. The only values that are valid for the
parameter key_number are 0 to3. The LASTKEY(0) call has the same effect as a
LASTKEY() call, which has the same behavior as it always has, namely, to return
the most recent keystroke. This procedure call is not useful for checking for
prefix keys. (See the example.) LASTKEY(1) returns the next-to-last keystroke.
LASTKEY(2) returns an 8-byte string representing the last WM_CHAR message
received (see the example), and LASTKEY(3) returns the next-to-last WM_CHAR.
Note: The WM_CHAR data can be used to check scan codes and differentiate
between the numeric keypad and other keys (for example). If a character
is being processed from a KEYIN or EXECUTEKEY statement, then the
WM_CHAR data will consist of 8 bytes of ASCII zeros.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
You might expect that the following example would check for the two-key
sequence Esc followed by F5:
def f6=
if lastkey()=esc then
/* do the new code for Esc-F6 */
else
/* do the normal F5 (in this case the draw command) */
'draw'
endif
However, this is not the case. This definition is executed only if F5 is
pressed, and once F5 has been pressed, it becomes the value of LASTKEY().
Therefore the if condition in the example never holds true.
The procedure could be useful in the following case:
def f5, a_f5, esc =
if lastkey() = f5 then
/* do something for F5 case */
elseif lastkey() = a_f5 then
/* do something for A_F5 case */
else
/* do something for Esc case */
endif
/* do something for all of the keys */
In this case, one DEF is defined for multiple keys. By using the LASTKEY()
procedure, you can determine which of these keys was pressed.
The procedure call LASTKEY(1) returns the key before last, and will handle the
problem discussed in the first example. By substituting LASTKEY(1) calls for
the LASTKEY() calls in the first example, this piece of code will work as
expected: trapping the Esc followed by F5 key sequence.
Example of WM_CHAR usage:
def left = -- Note: the following are all binary:
parse value lastkey(2) with flags 3 repeat 4 scancode 5 charcode 7 vk_code 9
left
if scancode = \75 then -- x'4b'; keyboard-specific
sayerror 'Pad left'
else
sayerror 'Cursor key left'
endif
ΓòÉΓòÉΓòÉ 4.1.91. LASTPOS (needle, haystack [,startpos [,flags]]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LASTPOS( needle, haystack [, start [, flags]] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
searches for needle in haystack from startpos to beginning of string. If
startpos is not present, the search begins from the end of string. If needle is
not found, zero is returned. needle and haystack must be strings.
See the description of the POS function for an explanation of flags.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
LASTPOS(' ','abc def ghi') ==8
LASTPOS(' ','abcdefghi') ==0
LASTPOS(' ','abc def ghi',7) ==4
ΓòÉΓòÉΓòÉ 4.1.92. LASTWORD(string) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LASTWORD( string )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
returns the last space-delimited word in string.
Note: This procedure is only available in EPM 5.60 or above.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
LASTWORD(string) == WORD(string, WORDS(string))
ΓòÉΓòÉΓòÉ 4.1.93. LEAVE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ 4.1.94. LEFT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LEFT
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor 1 character to the left, like the standard Left.
ΓòÉΓòÉΓòÉ 4.1.95. LEFTSTR(string, length [, pad] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LEFTSTR( string, length [, pad] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns a string of length length containing the left-most length characters of
string. That is, padded with pad characters (or truncated) on the right as
needed. The default pad character is a blank. length must be non-negative.
Exactly equivalent to SUBSTR(string,1,length[,pad]).
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
LEFTSTR('abc d',8) -> 'abc d '
LEFTSTR('abc d',8,'.') -> 'abc d...'
LEFTSTR('abc def',7) -> 'abc de'
ΓòÉΓòÉΓòÉ 4.1.96. LENGTH(expression) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LENGTH( expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns length of expression.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
LENGTH('abcdefgh') -> 8
LENGTH('abc defg') -> 8
LENGTH('') -> 0
ΓòÉΓòÉΓòÉ 4.1.97. LEXAM( functionname ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LEXAM( numeric_expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Provides spell checking and synonym support for the EPM.
The LEXAM opcode allows word verification and word/dictionary lookup. The LEXAM
opcode can take on the following syntax:
lexam('Initialize')
lexam('Terminate')
lexam('PIckup Dictionary',dictionary_name)
lexam('DRop Dictionary',dictionary_name)
lexam('SEt Addenda Language Type',addenda_type)
lexam('Add to Transient Addenda',addenda_name)
lexam('Read from Transient Addenda',addenda_name)
lexam('Verification',word)
lexam('SPelling Aid',word)
lexam('Hyphenation',word)
lexam('DEhyphenation',word)
lexam('SYnonym',word)
lexam('GRAMmar Aid',word)
lexam('GRADe level',word)
lexam('PArt-of-speech',word)
ΓòÉΓòÉΓòÉ 4.1.98. LINK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LINK string_expression
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Linkable External Modules.
ΓòÉΓòÉΓòÉ 4.1.99. LINKED ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LINKED( module )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Queries whether a module is linked. The return value is:
o module number (a small positive integer) if linked
o -1 if found on disk but not currently linked
o -307 if module can't be found on disk. This RC value -307 is the same as
sayerror("Link: file not found").
o -308 if the expression is a bad module name that cannot be expanded into a
proper filename. Same as sayerror("Link: invalid filename").
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Sample usage: result = linked("draw").
Note: If you wish to make sure a module is linked, you can always just repeat
the link command. E won't reload the file from disk if it's already linked,
but it will rerun the module's DEFINIT which might not be desirable.
ΓòÉΓòÉΓòÉ 4.1.100. LONGESTLINE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LONGESTLINE()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the length of the longest line in the current file.
ΓòÉΓòÉΓòÉ 4.1.101. LOOP ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ 4.1.102. LOWCASE(expression) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LOWCASE( expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the lower-case conversion of the expression. (In versions earlier than
4.12, the input string was converted in place. Now the input is left alone and
the converted string is returned as the result.)
ΓòÉΓòÉΓòÉ 4.1.103. LTOA(variable, radix) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
LTOA( variable, radix )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Converts the C representation of a long integer (data type long) stored in
variable to a string representation of the same number, so that the E language
can understand the number. radix specifies the base of the number (i.e. base 10
= decimal; base 16 = hexadecimal) to be converted to a string representation.
For use in converting numbers returned by C functions, for example function
calls via DYNALINK().
ΓòÉΓòÉΓòÉ 4.1.104. MACHINE() ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MACHINE()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns operating system and machine information string. Return values are
"PCDOS" or "OS2REAL" or "OS2PROTECT".
ΓòÉΓòÉΓòÉ 4.1.105. MAP_POINT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MAP_POINT subop, op2, op3 [, op4 [, comment ] ]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Everything other than subop must be a variable. This opcode is used to map
between a pixel-offset in the window, a pixel-offset in the document, and a
line, column and offset within the file.
subop op2_in op3_in op4_in op2_out op3_out op4_out
1 WindowToDoc x y - x y =
2 DocToLCO x y - Line Col Off
3 LCOToDoc Line Col Off x y =
4 Doc2Win x y - x y =
5 Win2LCO x y - Line Col Off
6 LCO2Win Line Col Off x y =
The comment field is an extra field that eventually will be used to indicate if
the special processing had to occur. For example, a requested point was beyond
the EOF and the returned values are based on extrapolation.
Note: When mapping to Line/Column/Offset, the mapping is to the nearest
interstitial space - i.e., the transition between two characters, two
attributes, or an attribute and a character. This means that if you map
a coordinate that's on the left side of a character, it will return the
column of that character, but if you map a coordinate on the right side
of a character, you'll get back the column of the following character.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
The following example maps the mouse position to the character under the mouse
pointer.
xxx = .mousex; mx = xxx
yyy = .mousey
map_point 5, xxx, yyy, off, comment; -- map screen to line
MouseLine = min(max(xxx, 0), .last) -- Want line to be between 0 & .last
lne = yyy
map_point 6, xxx, lne, off, comment; -- map line/col/offset to screen
if xxx>mx then -- The intersection selected is to right of mouse pointer;
yyy = yyy - 1 -- the character clicked on is the one to the left.
endif -- Note: could get col. 0 this way, but the following
-- takes care of that.
MouseCol = min(max(yyy, 1), MAXCOL)
ΓòÉΓòÉΓòÉ 4.1.106. MARKBLOCK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MARKBLOCK | MARK_BLOCK
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Starts or changes coordinates of a block mark, like the standard Alt-B.
ΓòÉΓòÉΓòÉ 4.1.107. MARKBLOCKG ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MARKBLOCKG
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Like MARKBLOCK, but right column must be specified one beyond the desired right
column.
ΓòÉΓòÉΓòÉ 4.1.108. MARKCHAR ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MARKCHAR | MARK_CHAR
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Starts or changes coordinates of a character mark, like the standard Alt-Z.
ΓòÉΓòÉΓòÉ 4.1.109. MARKCHARG ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MARKCHARG
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Like MARKCHAR, but column numbers represent edges rather than characters, so
that they can be between attributes (and right column will generally be one
higher that it would be for MARKCHAR).
ΓòÉΓòÉΓòÉ 4.1.110. MARKLINE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MARKLINE | MARK_LINE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Starts or changes coordinates of a line mark, like the standard Alt-L.
ΓòÉΓòÉΓòÉ 4.1.111. MARKLINEG ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MARKLINEG
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Same as MARKLINE.
ΓòÉΓòÉΓòÉ 4.1.112. MARKSIZE() ΓòÉΓòÉΓòÉ
New in EPM 6.
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MARKSIZE()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the number of marked characters. Useful when allocating a buffer into
which to copy the marked text.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
if marktype() then
getmark firstline, lastline
-- size of marked text + CR/LF for each line + 32 bytes buffer header
buff_size = marksize() + 2 * (lastline - firstline + 1) + 32
bufhndl = buffer(CREATEBUF, 'TempBuf', buff_size, 1 )
call buffer(PUTMARKBUF, bufhndl, firstline, lastline, APPENDCR+APPENDLF)
endif
ΓòÉΓòÉΓòÉ 4.1.113. MARKTYPE() ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MARKTYPE()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns 'BLOCK', 'LINE', or 'CHAR'. ' ' is returned if no text is highlighted.
ΓòÉΓòÉΓòÉ 4.1.114. MEMCPYX(destination, source, length) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MEMCPYX( hexadecimal_address , hexadecimal_address , length )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Copies length bytes from source to destination. Both source and destination are
binary far pointers; e.g.
call memcpyx(atoi(ptr1) || atoi(seg1), atoi(ptr2) || atoi(seg2), len)
ΓòÉΓòÉΓòÉ 4.1.115. MOUSE_SETPOINTER type ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MOUSE_SETPOINTER
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Sets the mouse pointer to the figure specified by type. Mouse figures are:
1 = arrow pointer (can also user the constant SYSTEM_POINTER)
2 = a vertical bar (like those used to request text in a dialog box)
3 = an hour glass
4 = invisible
5 = four way arrows
6 = two way arrow (upper left/lower right)
7 = two way arrow (upper right/lower left)
8 = horizontal arrow
9 = vertical arrow
10 = an outlined box
11 = a stop octagon with a hand in a box
12 = the browse question mark in a box
13 = an explanation point in box
14 = an asterisk in a box
15 = cropping lines (as defined by the constant MARK_POINTER)
For instance, when entering browse mode the mouse pointer can be changed to
indicate that no text can be entered.
ΓòÉΓòÉΓòÉ 4.1.116. MOVEMARK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
MOVEMARK | MOVE_MARK
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves marked text to cursor position, like the standard Alt-M.
ΓòÉΓòÉΓòÉ 4.1.117. NEXTFILE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
NEXTFILE | NEXT_FILE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Activates the next file in the active ring, like the standard F12 or Ctrl-N.
ΓòÉΓòÉΓòÉ 4.1.118. OFFSET(variable) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
OFFSET( variable )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the offset of the memory address of variable in the form of a binary
word. To be used with C functions like those made via DYNALINK().
ΓòÉΓòÉΓòÉ 4.1.119. OFS(variable) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
OFS( variable )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns a string representation of the offset of the actual memory address of
variable. See SEG() for an example of usage.
ΓòÉΓòÉΓòÉ 4.1.120. OVERLAY(new, target[, n [, k [,pad] ] ]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
OVERLAY(new, target [, n [, length [, pad] ] ])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
overlays the string new, padded to length k, onto the string target starting
at the nth character. k must be zero or positive. If n is greater than the
length of the target string, padding is added there also. The default pad
character is the blank, and the default value for n is 1. n must be greater
than 0.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Examples are:
OVERLAY(' ','abcdef',3) == 'ab def'
OVERLAY('.','abcdef',3,2) == 'ab. ef'
OVERLAY('qq','abcd') == 'qqcd'
OVERLAY('qq','abcd',4) == 'abcqq'
OVERLAY('123','abc',5,6,'+') == 'abc+123+++'
Although E's OVERLAY procedure is similar to REXX's, they are not identical. E
requires that each field be filled with a string, even if it is only a null
string. REXX allows a field to be skipped. For example:
OVERLAY('qq',,5,6,'+')
This would be legal syntax in REXX, but would cause errors in E. The E
equivalent would be:
OVERLAY('qq','',5,6,'+')
ΓòÉΓòÉΓòÉ 4.1.121. OVERLAYBLOCK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
OVERLAYBLOCK | OVERLAY_BLOCK
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Copies marked text to cursor position without inserting, like standard Alt-O.
ΓòÉΓòÉΓòÉ 4.1.122. PAGEDOWN ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
PAGEDOWN | PAGE_DOWN
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor to next page of current file, like standard PgDn.
ΓòÉΓòÉΓòÉ 4.1.123. PAGEUP ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
PAGEUP | PAGE_UP
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor to previous page of current file, like standard PgUp.
ΓòÉΓòÉΓòÉ 4.1.124. PARSE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
See The Parse Statement.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
See The Parse Statement.
ΓòÉΓòÉΓòÉ 4.1.125. PEEK(segment, offset, count) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
PEEK( segment , offset , count )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns string of length count starting at the address segment:offset. The
segment and offset values are used just as they are in assembler programs. See
also POKE in the section Built-in Statement and Procedure Summary.
A PEEK() call is often necessary to access the string pointed to by a pointer
returned by a DYNALINK() function call.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
The following example of this type of usage is based on the procedure get_env()
in DOSUTIL.E.
seg_ptr = 1234 /* 4-byte place to put a far ptr */
cmd_ptr = 1234
call dynalink('DOSCALLS', /* dynamic link library name */
'#91', /* ordinal val for DOSGETENV */
selector(seg_ptr) || /* ptr to env. seg */
offset(seg_ptr) ||
selector(cmd_ptr) || /* ptr to ofs after */
offset(cmd_ptr) )/* COMSPEC: unneeded */
env_seg = itoa(seg_ptr,10)
env_ofs = 0
start = env_ofs
do while peek(env_seg,env_ofs,1) /== \0
env_ofs = env_ofs + 1
end
setting = peek(env_seg,start,env_ofs-start)
PEEK() allows us to determine where the end of the string is (marked by a null
character: \0), and thereby determine the length of the string.
WARNING: Attempts to PEEK to an area not owned by your process will cause a
TRAP-D error.
ΓòÉΓòÉΓòÉ 4.1.126. PEEK32(address, offset, count) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
PEEK32( address , offset , count )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns string of length count starting at the address address + offset. Like
Peek, but takes a full 32-bit address instead of a selector as the first
argument. See also POKE32 in the section Built-in Statement and Procedure
Summary.
WARNING: Attempts to PEEK32 to an area not owned by your process will cause a
TRAP-D error.
ΓòÉΓòÉΓòÉ 4.1.127. PEEKZ(segment, offset) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
PEEKZ( hexadecimal_address ) | PEEKZ( numeric_expression , numeric_expression
)
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Like PEEK, but for an ASCIIZ string. Returns the contents of storage starting
with the address given and ending with the character before the next null
character.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
This lets us simplify the PEEK example to:
env_seg = itoa(seg_ptr,10)
setting = peekz(env_seg,0)
An alternate format supported is PEEKZ(address), where address is the 4-byte
hex address of the storage. This is useful when calling an external routine
that returns a far pointer to an ASCIIZ string.
ΓòÉΓòÉΓòÉ 4.1.128. PEEKZ32(address, offset) ΓòÉΓòÉΓòÉ
New in EPM 6.
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
PEEKZ32( numeric_expression , numeric_expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Like PEEKZ, but takes a 32-bit address instead of a selector.
ΓòÉΓòÉΓòÉ 4.1.129. POKE segment, offset, string ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
POKE( segment , offset , string )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Writes string to the address segment:offset. The segment and offset values are
used just as they are in assembler programs.
WARNING: Attempts to POKE to an area not owned by your process will cause a
TRAP-D error and crash.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
-- put greeting at beginning of segment.
SelOfSharedSeg = itoa(Selector1, 10);
poke SelOfSharedSeg , 0 , "Bonjour"\0;
ΓòÉΓòÉΓòÉ 4.1.130. POKE32 address, offset, string ΓòÉΓòÉΓòÉ
New in EPM 6.
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
POKE32( address , offset , string )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Writes string to the address address + offset. Like Poke, but takes a full
32-bit address instead of a selector as the first argument.
WARNING: Attempts to POKE32 to an area not owned by your process will cause a
TRAP-D error and crash.
ΓòÉΓòÉΓòÉ 4.1.131. POS(needle, haystack [,start [,flags]]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
POS( needle, haystack [, start [, flags]] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the position of one string, needle, in another, haystack. (See also the
LASTPOS function.) If the string needle is not found, 0 is returned. By
default the search starts at the first character of haystack (that is, start is
of the value 1). This may be overridden by specifying start (which must be a
positive whole number), the point at which to start the search.
flags is allowed only in EPM version 6 and above. It is used to indicate that
an extended GREP search is desired. (See The EPM User's Guide or the EPM 6
online help for a description of extended GREP searching.) It can contain any
combination of:
G Indicate that an extended GREP search is desired.
X Same as 'G'.
M Indicate that, if the GREP search is successful, the result should contain
all the match columns rather than just the start column. I.e., the result
will contain pairs of numbers, the first pair indicating the first and last
column of the entire matched string, and subsequent pairs indicating the
first and last columns which matched each parenthesized subexpression (in
the order in which the open parens were seen).
P Indicate that needle is a pointer to a pre-compiled EGREP program, rather
than an EGREP search string.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
POS('day', 'Saturday') -> 6
POS('x', 'abc def ghi') -> 0
POS(' ', 'abc def ghi') -> 4
POS(' ', 'abc def ghi', 5) -> 8
POS('a.*t', 'This is a test', 1, 'X') -> 9
prog = '(q:a*) (:c)' -- 11111112222222222333333333344444
; 12345678901234567890123456789012345678901234
searchstr = 'The quick brown fox jumps over the lazy dog.'
pos(prog, searchstr, 1, 'XM') -> 5 15 5 9 11 15
In the last example, the EGREP search was matched by columns 5 to 15; the first
parenthesized expression (matching a word starting with 'q') was matched in
columns 5 to 9, and the second parenthesized expression (the following word)
was matched in columns 11 to 15.
See also:
o LastPos function
o RegExpComp function, to pre-compile an EGREP program
o RegExpExec function, to execute a pre-compiled EGREP program
ΓòÉΓòÉΓòÉ 4.1.132. PREVFILE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
PREVFILE | PREV_FILE
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Activates the previous file in the active ring, like the standard Alt-F11 or
Ctrl-P key combinations.
ΓòÉΓòÉΓòÉ 4.1.133. QPRINT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
QPRINT printername
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Performs a WYSIWYG print of the current file to the print queue associated with
the named printer.
ΓòÉΓòÉΓòÉ 4.1.134. QUERYACCELSTRING ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
QUERYACCELSTRING (table_name, id)
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the string associated with identifier 'id' in the accelerator table
named 'table_name'.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
accelstr=queryaccelstring(activeaccel, menuid)
if accelstr <> '' then
sayerror 'menu id' menuid 'would execute command' accelstr
endif
See also:
o Building Accelerator Tables from the Macro Language
o QUERYACCELSTRING
o BUILDACCELTABLE
o DELETEACCEL
ΓòÉΓòÉΓòÉ 4.1.135. QUERY_ATTRIBUTE var class, var value, var ispush, offset, column, line [, fileid] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
QUERY_ATTRIBUTE class, value, ispush, offset, column, line [, fileid]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
This statement allows a macro program to deterine what attribute record can be
found at the specified location.
Class returns the class of the found attribute record. A value of zero is
returned if no attribute was found. A value between 1 and 63 is
returned if an internally supported attribute record was found. A
value from 64 to 255 is returned if an application supported attribute
record was found. The meaning of an application supported attribute
record is not predictable at compile time. Some administrative macros
will be provided for determining the meaning of a macro during runtime.
Value returns the value of the found attribute record. Its value is
unchanged if no attribute record was found at the specified location.
IsPush returns the value of the support field of the found attribute. This
parameter's value is unchanged if no attribute record was found at the
specified location.
Offset The offset of the position being queried. Must be a negative value,
indicating a position before the specified character location.
Column The column number of the position being queried.
Line The line number of the position being queried.
FileID The fileid of the position being queried. If unspecified, the current
file will be assumed.
See Attribute Pairs for additional information on attributes.
ΓòÉΓòÉΓòÉ 4.1.136. QUERYFONT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
QUERYFONT (font_id)
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the font description associated with font_id, in the form
fontname.fontsize.fontsel - e.g.
Courier.DD100WW9HH8BB.0
Times New Roman.DD240WW0HH0.0
In fontsize, the numbers following DD are the size of the font in decipoints
for a proportional font, and the numbers following WW and HH are the width and
height of the font in pixels for a monospaced font. The BB is present at the
end if the font is a bitmapped font. 'fontsel' is any combination of
1 = Italic
2 = Underscore
8 = Outline
16 = Strikeout
32 = Bold
ΓòÉΓòÉΓòÉ 4.1.137. QUERYMENUSTRING(menuname, id) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
QUERYMENUSTRING( menuname , id )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Determines the command to be executed by the menu specified by the menuname and
by id. See Building Menus from the Macro Language for more information on the
QUERYMENUSTRING statement.
ΓòÉΓòÉΓòÉ 4.1.138. QUERYPROFILE(application, key_name) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
QUERYPROFILE( file_handle, application , key_name )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the value for key key_name listed under the application application,
found in the .INI file given by the file_handle or the null string if not
found. file_handle. can be any of
HINI_USERPROFILE (a constant) Indicates the user profile (OS2.INI) should be
used.
HINI_SYSTEMPROFILE (a constant) Indicates the system profile (OS2SYS.INI)
should be used.
HINI_PROFILE (a constant) Indicates that both the user and system profiles
should be searched.
APP_HINI (a universal variable) Indicates that the application profile should
be used. For EPM, this is EPM.INI. Other users of the E Toolkit can
have other application profiles.
ΓòÉΓòÉΓòÉ 4.1.139. QUIETSHELL string_expression ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
QUIETSHELL | QUIET_SHELL string_expression
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Executes string_expression. string_expression is to be an OS/2 command. If
string_expression is an external program, the screen and cursor are not touched
before or after the program is executed.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Use this when you know the external program will not write to the screen, and
you prefer not to see the screen clear and to be asked to press a key. Normally
this is used to keep redirected utilities invisible, for example quietshell
"subdir *.* >etemp".
If the command DOES write to the screen, say after an unexpected error, its
message will appear on top of E's text screen. The text will appear messy until
the next time E refreshes the screen. You can manually force a screen refresh
by pressing ESC a couple of times.
Another example is quietshell "mc2", which runs Richard Redpath's MC2
calculator. This is an unusual example because MC2 does write to the screen,
but it takes responsibility for restoring the screen contents it found. The
effect is that of a pop-up calculator on top of the text screen.
ΓòÉΓòÉΓòÉ 4.1.140. REFLOW ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
REFLOW
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Reformats marked text using current margin settings, like the standard Alt-P.
ΓòÉΓòÉΓòÉ 4.1.141. REFRESH ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
REFRESH
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Activates the active file in the top level ring. Activates the top level ring
and updates portions of screen which need to be updated.
ΓòÉΓòÉΓòÉ 4.1.142. REGEXPCOMP(grep_string) ΓòÉΓòÉΓòÉ
New in EPM 6.02.
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
REGEXPCOMP( grep_string )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Compiles the extended GREP search string into an EGREP program, and returns a
pointer to that program.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
regprog = RegExpComp('Dos(Alloc|Free)~Seg')
See also:
o Pos function
o RegExpExec function, to execute a pre-compiled EGREP program
ΓòÉΓòÉΓòÉ 4.1.143. REGEXPEXEC(grep_prog, search_string) ΓòÉΓòÉΓòÉ
New in EPM 6.02.
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
REGEXPEXEC( grep_program search_string )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Searches the search string using the EGREP program, and returns the starting
position of a successful match, or 0 if no match could be found.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
regprog = RegExpComp('Dos(Alloc|Free)~Seg')
result = RegExpExec(regprog, textline(.line))
if result then
sayerror 'Found at' substr(textline(.line), result)
else
sayerror 'Not found.'
endif
call dynalink32(E_DLL, -- E_DLL is defined in STDCONST.E.
'myfree', -- We must free the
atol(regprog)) -- program, when done with it.
See also:
o Pos function
o RegExpComp function, to pre-compile an EGREP program
ΓòÉΓòÉΓòÉ 4.1.144. REGISTERFONT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
REGISTERFONT (fontname, fontsize,fontsel)
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Loads the font specified and returns an identifier that can be set in the .font
field or which can be used as the value of a font attribute.
'fontsel' is any combination of
1 = Italic
2 = Underscore
8 = Outline
16 = Strikeout
32 = Bold
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Examples:
.font = registerfont('Times New Roman', 24, 0) -- Set a 24-point font.
.font = registerfont('System Monospaced','WW8HH16',0) -- 8 x 16 font
ΓòÉΓòÉΓòÉ 4.1.145. RELINK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in section Linkable External Modules.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Linkable External Modules.
ΓòÉΓòÉΓòÉ 4.1.146. REPEATFIND ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
REPEATFIND | REPEAT_FIND
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Repeats find of last string searched, like the standard Ctrl-F. The previous
search options are preserved. (Note: If the cursor is currently at the
beginning of a target search string, it skips to the next occurrence.)
ΓòÉΓòÉΓòÉ 4.1.147. REPLACELINE new_line [ ,line_number [,var fileid] ] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
REPLACELINE new_line [, {;} line_number [, {;} fileid] ]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Replaces a specified line in the specified file with the contents of variable
new_line Defaulted values for omitted parameters are line_number = current
line, and fileid = current file. See example under GETLINE.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example:
REPLACELINE line
/* Replaces current line of current file with line */
REPLACELINE line, 7
/* Replaces line 7 of current file with line */
REPLACELINE line, 3, ThatFile
/* Replace line 3 of file whose fileid
is in variable ThatFile with line */
ΓòÉΓòÉΓòÉ 4.1.148. RETURN [expression] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
RETURN [expression]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns expression to caller. If no expression is supplied, a null value is
returned to the caller. From a procedure, the returned value is passed back to
the caller as a function value (as in x=myproc()). From a command the returned
value is assigned to RC.
When returning from a key (DEF), an expression is not allowed. A return from a
key DEF is unusual, since keys do not return values, but a return is sometimes
used as an easy early exit from a key's program. A return is better than a STOP
in case some other procedure was "calling" the key with an executekey; a STOP
prevents the caller from regaining control.
ΓòÉΓòÉΓòÉ 4.1.149. REVERSE(string) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
REVERSE( string_expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the reverse of the string string.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
REVERSE('BACKWORDS') --> 'SDROWKCAB'
REVERSE('seluR MPE') --> 'EPM Rules'
ΓòÉΓòÉΓòÉ 4.1.150. RIGHT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
RIGHT
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor one character to the right, like the standard key Right.
ΓòÉΓòÉΓòÉ 4.1.151. RIGHTSTR(string, length [, pad] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
RIGHTSTR( string, length [, pad] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns a string of length length containing the right-most length characters
of string. That is, padded with pad characters (or truncated) on the left as
needed. The default pad character is a blank. length must be non-negative.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
RIGHTSTR('abc d',8) --> ' abc d'
RIGHTSTR('abc def',5) --> 'c def'
RIGHTSTR('12',5,'0') --> '00012'
ΓòÉΓòÉΓòÉ 4.1.152. RUBOUT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
RUBOUT
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Deletes character to left of cursor, like the standard key Backspace.
ΓòÉΓòÉΓòÉ 4.1.153. SAYAT string, row, column, attribute [,length][,window] ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SAYAT string, row, column, attribute [, length]
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Writes string at the screen location specified by row (any number included in
1..screenheight()) and column (any number included in 1..screenwidth()). The
parameter attribute allows you to specify any screen attribute (0..255 or any
constant color value listed in COLORS.e) to highlight string. If length is
omitted, E assumes length = LENGTH(string). If length < LENGTH(string), E
writes the first length number of characters. If length > LENGTH(string), E
changes the screen attribute to attribute for the last length - LENGTH(string)
number of character positions without changing the text.
The window option defines which text window area should be written to by the
SAYAT statement. 0=Edit Window, 1=Extra window. The extra window is the window
that makes up the status line and message line. The edit window is everything
else.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Examples:
/* write red string in upper right corner */
sayat 'mymessage', 1, 70, RED
/* change screen positions (10,20) to (10,24)
to green color without changing text */
sayat '', 10, 20, GREEN, 5
To put a message to the message line, use the MESSAGE() defproc.
Note: that something printed with the SAYAT statement only stays on the screen
until a screen refresh is done. Since a SAYERROR call produces a screen
refresh, combining these two statements:
sayat 'My Procedure.', 12, 20, GREEN, 5
sayerror "File not found!"
will result in the SAYAT message never being seen. To prevent this, you can use
the DISPLAY statement to stop screen refreshing, for example:
display -1 -- turn off display updating
sayat 'My Procedure.', 12, 20 ,GREEN, 5
sayerror "File not found!"
display +1 -- turn on display updating
In this way, the screen will not be refreshed (and therefore the message will
stay on the screen) until the next screen update.
ΓòÉΓòÉΓòÉ 4.1.154. SAYERROR expression ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SAYERROR( expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Should not be confused with the built-in procedure SAYERROR() described in this
section.
If expression is the number 0 or 1, any pending error messages are discarded
and not displayed. 0 will refresh the screen; 1 will not.
If expression is any number other than 0 or 1, `the interpreter displays the
string corresponding to that numbered error message. Error messages and their
corresponding return codes are listed in the section Return Codes.
Each command in the E language returns a code which indicates any errors that
were encountered while trying to perform the command. Each of these return
codes has a corresponding string which explains the error.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example:
sayerror -275
This will display the text "Missing filename" on the message line.
If expression is a number which does not correspond to a return code, an
"ERROR: Message not available" message is printed on the message line.
If expression is anything other than a number, the text will be displayed on
the message line. For example:
err1 = "-275" -- remember everything is a string
sayerror err1 -- equivalent to: err1 = -275
err2 = "David"
sayerror err2
The first example will display the error message (not "-275") on the message
line. The second example will display the text David on the message line.
A combination of text and numbers will act as if it were all text. For example:
sayerror "The error message was " err1
The intention to display all text would not work in this case. Instead the user
would get:
The error message was -275
The error code did not get translated.
To help clarify this explanation, try entering and compiling the following
defc:
defc mytest
sayerror arg(1)
Then experiment by typing in the command line dialog box mytest followed by
valid error numbers, invalid error numbers, text, and text with numbers to
determine what will happen.
ΓòÉΓòÉΓòÉ 4.1.155. SAYERROR(error_string) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SAYERROR expression
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the return code specified by error_string. Note that this is only true
if the sayerror procedure acts as a function and returns a return code. If the
SAYERROR() procedure is not assigned and not used in a comparison, then the
procedure acts the same as the SAYERROR statement (also described in this
section).
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example:
x = sayerror("new file")
sayerror("new file")
The first example will put the return code for new file (ie. -282) into the
variable x. The second example will act in the same manner as a SAYERROR
statement and would display the words "new file" on the message line.
The case of error_string does not matter. The compiler will convert
error_string to uppercase and then perform the lookup for error_string. The
compiler reduces sayerror(error_string) to a constant for efficiency.
Therefore, if the words new file were changed to gobbildy gook (not a valid
error message), the compiler would not compile and return an "invalid
parameter" error message.
The most common usage of this is to test an return code to see if a certain
error occurred. For example:
'e myfile'
if rc=sayerror("new file") then
All error messages and their corresponding RC code numbers can be found in
Return Codes.
ΓòÉΓòÉΓòÉ 4.1.156. SAYERRORTEXT(rc) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SAYERRORTEXT'(' numeric_expression ')'
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the message that would be displayed for error code rc.
ΓòÉΓòÉΓòÉ 4.1.157. SCREENHEIGHT() ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SCREENHEIGHT()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns physical screenheight, usually 25.
ΓòÉΓòÉΓòÉ 4.1.158. SCREENWIDTH() ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SCREENWIDTH()
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns physical screenwidth, usually 80.
ΓòÉΓòÉΓòÉ 4.1.159. SEG(variable) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SEG( variable )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns a string representation of the segment of the actual memory address of
variable.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example:
v = 'testing'
sayerror peek( seg(v), ofs(v), 7 )
The above example prints testing. See also OFS().
ΓòÉΓòÉΓòÉ 4.1.160. SELECTOR(variable) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SELECTOR( variable )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the segment address of variable in the form of a binary word. To be
used with C functions, like those made via DYNALINK().
This function it is to be used only during the protected mode execution.
ΓòÉΓòÉΓòÉ 4.1.161. SETMARK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SETMARK firstline, lastline, firstcol, lastcol, marktype, fileid
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Sets a mark in file 'fileid' from firstline firstcol to lastline lastcol.
marktype must be one of:
0 = line mark
1 = char mark
2 = block mark
3 = charg mark
4 = blockg mark
ΓòÉΓòÉΓòÉ 4.1.162. SETPROFILE(handle, application, key_name, data) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SETPROFILE( numeric_expression, string_expression, string_expression,
string_expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Sets the value for key key_name listed under the application application to
data in the .INI file represented by handle. handle. can be any of
HINI_USERPROFILE (a constant) Indicates the user profile (OS2.INI) should be
used.
HINI_SYSTEMPROFILE (a constant) Indicates the system profile (OS2SYS.INI)
should be used.
HINI_PROFILE (a constant) Indicates that both the user and system profiles
should be searched.
APP_HINI (a universal variable) Indicates that the application profile should
be used. For EPM, this is EPM.INI. Other users of the E Toolkit can
have other application profiles.
ΓòÉΓòÉΓòÉ 4.1.163. SETSEARCH var search_cmd ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SETSEARCH identifier
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Retrieves the search command string saved in the variable search_cmd via a
GETSEARCH statement. These two statements allow the user to save a search
command, perform other searches and then retrieve the original command, so that
Ctrl-F's and REPEATFIND statements refer to the original search pattern.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
For example:
'xcom L /foobar/c'
GETSEARCH search_command
'L /word'
SETSEARCH search_command
The first statement in the above example issues a search command. The GETSEARCH
statement effectively sets the variable search_command to 'xcom L/foobar/c'.
Then another search command is issued, wiping out the first search command, but
the SETSEARCH statement restores the first command, so that if a Ctrl-F
(REPEAT_FIND) is now executed, the string foobar will be once again located.
ΓòÉΓòÉΓòÉ 4.1.164. SHIFTLEFT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SHIFTLEFT | SHIFT_LEFT
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Shifts marked text 1 position to left, like the standard Ctrl-F7.
ΓòÉΓòÉΓòÉ 4.1.165. SHIFTRIGHT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SHIFTRIGHT | SHIFT_RIGHT
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Shifts marked text 1 position to right, like the standard Ctrl-F8.
ΓòÉΓòÉΓòÉ 4.1.166. SHOWMENU ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SHOWMENU
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Displays a menu after it has been built. See the section Building Menus from
the Macro Language for more information on the SHOWMENU statement.
ΓòÉΓòÉΓòÉ 4.1.167. SPLIT ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SPLIT
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Splits current line at cursor position, like the standard Alt-S.
ΓòÉΓòÉΓòÉ 4.1.168. STOP ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
STOP
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Stops execution of interpreter. A RETURN statement returns control to any
calling procedures, however the STOP statement ends the execution immediately.
RETURN is the preferred means of exiting a procedure, however, STOP is useful
for terminating execution on a critical error.
ΓòÉΓòÉΓòÉ 4.1.169. STOPONRC ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
STOPONRC | STOP_ON_RC
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Stops execution of interpreter only if rc is non-zero.
ΓòÉΓòÉΓòÉ 4.1.170. STRIP(string [,option] [,char]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
STRIP( string [, (L|T|B)] [, 'char' ] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Removes char from string in any of the following positions depending upon the
option specified:
Option: Position:
'L'
Leading
'T'
Trailing
'B'
Both
If option is omitted, the default is B. If char is omitted, the default is the
space character. (Same as REXX.)
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
strip(' ab c ') = 'ab c'
strip(' ab c ','L') = 'ab c '
Note: Calling the STRIP() function does not actually change the value of the
parameter string. In order to modify a variable you must assign to it, for
example:
field = strip( field )
ΓòÉΓòÉΓòÉ 4.1.171. SUBSTR(string,n [,k [,pad] ]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SUBSTR( string, n [, length [, 'pad' ] ] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the substring of string which begins at the nth character, and is of
length, padded with blanks or the specified character (pad). If length is
omitted, it defaults to be the rest of the string. The default pad character
is a blank. n must be positive.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
SUBSTR('abc',2) == 'bc'
SUBSTR('abc',2,4) == 'bc '
SUBSTR('abc',2,6,'.') == 'bc....'
Note: in some situations the positional (numeric) patterns of parsing templates
are more convenient for selecting substring, especially if more than one
substring is to be extracted from a string.
ΓòÉΓòÉΓòÉ 4.1.172. SUBWORD(string, n [, length] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
SUBWORD( string , n [, length] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the substring of string that begins at the nth word, and is of length
length blank-delimited words. If length is not specified, the rest of the
string is returned. n must be positive. The returned string will never have
leading or trailing blanks, but will include all blanks between the selected
words.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
SUBWORD('Now is the time',2,2) -> 'is the'
SUBWORD('Now is the time',3) -> 'the time'
SUBWORD('Now is the time',5) -> ''
ΓòÉΓòÉΓòÉ 4.1.173. TAB ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
TAB
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor to next tab stop, like standard key Tab.
ΓòÉΓòÉΓòÉ 4.1.174. TABGLYPH(bool) ΓòÉΓòÉΓòÉ
New in EPM 6.
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
TABGLYPH( [bool] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
If an argument is given, sets the TabGlyph flag to that value. Returns the
value that the TabGlyph flag had before the call.
If the TabGlyph flag is 1, tab characters will be displayed using a
proportional-width tab glyph (the usual glyph for an ASCII 9 is a circle). If
the TabGlyph flag is 0, tab characters will just display as whitespace. The
initial value is 0.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
definit -- (In MYSTUFF.E)
compile if EPM32
call tabglyph(1) -- I prefer to see the difference between
compile endif -- tabs and spaces.
ΓòÉΓòÉΓòÉ 4.1.175. TABWORD ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
TABWORD | TAB_WORD
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Positions cursor on first character of next word, like the standard key
Ctrl-Right. If there are no more words, the cursor is positioned at the end of
the last word.
ΓòÉΓòÉΓòÉ 4.1.176. TEXTLINE(line_num) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
TEXTLINE( line_num )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the text of line number line_num. The following statements perform the
same function:
getline line, i
and
line = textline(i)
The TEXTLINE() procedure is simply a more economical way to do comparison loops
like:
while textline(i) == ''
deleteline i
ΓòÉΓòÉΓòÉ 4.1.177. TOP ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
TOP
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor to top of file.
ΓòÉΓòÉΓòÉ 4.1.178. TRANSLATE(string [, tableo [, tablei [ pad ]]] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
TRANSLATE( string [, tableo [, tablei [, pad ] ] ] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Translates characters in string to be other characters, or may be used to
reorder characters in a string. If neither translate table is given, string is
simply translated to uppercase. tableo is the output table and tablei is the
input translate table (the default is ASCII 0...255). The output table
defaults to the null string, and is padded with pad or truncated as necessary.
The default pad is a blank. The tables may be of any length: the first
occurrence of a character in the input table is the one that is used if there
are duplicates.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Examples:
TRANSLATE('abcdef') == 'ABCDEF'
TRANSLATE('abbc','?','b') == 'a??c'
TRANSLATE('abcdef','12','ec') == 'ab2d1f'
TRANSLATE('abcdef','12','abcd','.') == '12..ef'
TRANSLATE('4123','abcd','1234') == 'dabc'
Note: The last example shows how the TRANSLATE function may be used to reorder
the characters in a string. In the example, any 4-character string could be
specified as the second argument and its last character would be moved to the
beginning of the string.
ΓòÉΓòÉΓòÉ 4.1.179. TRYINCLUDE filename ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in section Compiler Directive Statements.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Compiler Directive Statements.
ΓòÉΓòÉΓòÉ 4.1.180. UNDO ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
UNDO
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Restores the current line after modification (but before leaving it), like the
standard F9 key. Pressing the key (or issuing the statement) twice causes the
UNDO to undo itself, i.e. the line is re-modified.
ΓòÉΓòÉΓòÉ 4.1.181. UNDOACTION ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
UNDOACTION action, statevar
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Statevar must be a variable; it is used for input or output depending on the
action. Actions are:
Action Value Result
1=GET_STATE Returns a handle for the current state of the current file. If the
file hasn't changed since the the last time the file was checked,
then the same value is returned. If the file has changed, the
current state is checkpointed and a new handle is returned.
2=GET_OLDEST_STATE The editor periodically forgets old states in order to save
memory. This call allows one to determine the oldest reachable
state.
3=GOTO_STATE If the current state is not yet named, it is checkpointed and then
the content of the file is changed to reflect the specified state.
4=DISABLE_RECORDING The parameter specifies at which times state checkin should
no longer automatically be done. A side effect of this command is to
checkin the current state if it is not already checked in.
Times
0 upon starting each keystroke
1 upon starting each command
2 when moving the cursor from a modified line.
5=ENABLE_RECORDING The parameter specifies at what additional times checkin
should be done. Unlike the disabling code, this operation does not
have checkin as a side effect. See DISABLE for time codes.
6=QUERY_NAMED_SEQ This returns a string consisting of two numbers seperated by
an elipsis. This string represents the oldest and most recent states
that can be reached. These are lowlevel handles, so they can only be
use to call GOTO_STATE2. The left most number returned represents
the oldest state the is currently remembered. It is possible that it
is not reachable going to a state causes a checkpointing of the
current state and check pointing may require a trimming of the undo
tree. If the current state is checked in, the second value
represents the current state. If the current state is not checked
in, the second value represents the state of file when the next
checkin is done. (Note a checkin will be done as a side effect of
the first GOTO.) BTW, one can go to any state between the first and
last. They do represent a temporal sequence.
7=GOTO_STATE2 This is like GOTO_STATE, except the parameter should be a low
level handle like those returned from QUERY_NAMED_SEQ.
ΓòÉΓòÉΓòÉ 4.1.182. UNLINK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
UNLINK string_expression
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Linkable External Modules.
ΓòÉΓòÉΓòÉ 4.1.183. UNMARK ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
UNMARK
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Removes text marks, like the standard key Alt-U.
ΓòÉΓòÉΓòÉ 4.1.184. UP ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
UP
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Moves cursor 1 character up, like standard Up key.
ΓòÉΓòÉΓòÉ 4.1.185. UPCASE(expression) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
UPCASE( expression )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the upper-case conversion of the expression.
ΓòÉΓòÉΓòÉ 4.1.186. VALIDATEFILEID(fileid) ΓòÉΓòÉΓòÉ
New in EPM 6.
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
VALIDATEFILEID(fileid)
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns:
0 if the argument is not a fileid or viewid;
1 if the argument is a valid fileid for a normal file;
2 if the argument is a valid viewid;
3 if the argument is a fileid for an array.
ΓòÉΓòÉΓòÉ 4.1.187. VER([option]) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
VER([option])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the version of the editor being used.
If option is 1 then VER returns the editors numeric version. If option is 2,
VER returns the minimum allowed version number of a E macro file to be used
within this version. If no option is specified, the version "string" is
returned.
ΓòÉΓòÉΓòÉ 4.1.188. VERIFY(string, reference [,options [,start] ] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
VERIFY( string , reference [ ,(M|N) [, start] ])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
verifies that string is composed only of characters from reference, by
returning the position of the first character in string that is not also in
reference. If all the characters are present in reference, 0 is returned. The
options are:
'Match' and 'Nomatch'
If 'Match' is specified, i.e. the value of the third argument expression is a
string beginning with 'M' or 'm', the position of the first character in string
that is in reference is returned. 0 is returned if none of the characters are
found. 'Nomatch' (or any string expression beginning with 'N' or 'n') can also
be specified, although you would not normally do so because 'Nomatch' is the
default.
The default for start is 1, making the search start at the first character of
string. This can be overridden by giving a different start value, which must
be positive.
If string is null, 0 is returned regardless of the value of the third argument.
Similarly if start is greater than length(string), 0 is returned.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Examples:
VERIFY('123','1234567890') == 0
VERIFY('1Z3','1234567890') == 2
VERIFY('AB3','1234567890','M') == 3
The REXX documentation includes this example:
VERIFY('1P3Q4','1234567890',,3) == 4
Notice that the third parameter is completely omitted between two adjacent
commas. This causes REXX to use the default option of 'nomatch'.
In general, the E compiler does not like parameters to be completely omitted in
this way. It expects the parameter to be present even if it's an empty string.
Thus the same intent can be achieved by either of these:
VERIFY('1P3Q4','1234567890','',3) == 4
VERIFY('1P3Q4','1234567890','N',3) == 4
ΓòÉΓòÉΓòÉ 4.1.189. WHEREDEFC(string) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
WHEREDEFC( string )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
returns the name of the .ex file in which the argument is defined as a DEFC, or
the null string if the argument is an unknown command.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
defc find_cmd =
ex_file = WhereDefc(arg(1))
if ex_file then
sayerror '"'arg(1)'" is defined in' ex_file
else
sayerror '"'arg(1)'" is not a DEFC in any linked file'
endif
ΓòÉΓòÉΓòÉ 4.1.190. WHILE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Is described in section Conditional and Loop Statements.
ΓòÉΓòÉΓòÉ 4.1.191. WINDOWMESSAGE ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
WINDOWMESSAGE(send_flag, target, message, mp1, mp2)
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Performs a WinPostMessage (if send_flag = 0) or WinSendMessage (if send_flag =
1) to the target window with the given message number and MP1 and MP2 values.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
/* Pop the command line and pre-fill it with 'Prompt'
call windowmessage(0, getpminfo(EPMINFO_OWNERCLIENT),
5124, -- EPM_POPCMDLINE
0,
put_in_buffer('Prompt') )
ΓòÉΓòÉΓòÉ 4.1.192. WINMESSAGEBOX ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
WINMESSAGEBOX(caption, text [, attributes])
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Puts up a PM message box containing caption as the title and text as the
contents. attributes is any combination of the MB_ constants from PMWIN.H in
the OS/2 Toolkit. These are duplicated in STDCONST.E.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
r = WinMessageBox('Reality check',
'Are you sure you want to delete your thesis?',
MB_YESNOCANCEL + MB_WARNING + MB_DEFBUTTON3 + MB_MOVEABLE)
if r = MBID_YES then
sayerror 'Maybe you should sleep on it...'
elseif r = MBID_NO then
sayerror 'Good idea!'
else
sayerror '(Forget the whole thing.)'
endif
ΓòÉΓòÉΓòÉ 4.1.193. WORD(string, n) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
WORD( string , n )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the nth blank-delimited word in string. n must be positive. If there
are less than n words in string, the null string is returned. Exactly
equivalent to SUBWORD(string,n,1).
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
WORD('Now is the time',3) --> 'the'
WORD('Now is the time',5) --> ''
ΓòÉΓòÉΓòÉ 4.1.194. WORDINDEX(string, n) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
WORDINDEX( string , n )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the character position of the nth blank-delimited word in string. n
must be positive. If there are less than n words in string, 0 is returned.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
WORDINDEX('Now is the time',3) --> 8
WORDINDEX('Now is the time',6) --> 0
ΓòÉΓòÉΓòÉ 4.1.195. WORDLENGTH(string, n) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
WORDLENGTH( string , n )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the length of the nth blank-delimited word in string. n must be
positive. If there are less than n words in string, 0 is returned.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
WORDLENGTH('Now is the time',2) --> 2
WORDLENGTH('Now comes the time',2) --> 5
WORDLENGTH('Now is the time',6) --> 0
ΓòÉΓòÉΓòÉ 4.1.196. WORDPOS(needle, haystack [, start] ) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
WORDPOS( needle , haystack [, start] )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Searches haystack for the first occurrence of the sequence of blank-delimited
words needle and returns the word number of the first word of needle in
haystack. Multiple blanks between words in either needle or haystack are
treated as a single blank for the comparison, but otherwise the words must
match exactly. Returns 0 if needle is not found.
By default the search starts at the first word in haystack. This may be
overridden by specifying start (which must be positive), the word at which to
start the search.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
WORDPOS('the','now is the time') -> 3
WORDPOS('The','now is the time') -> 0
WORDPOS('is the','now is the time') -> 2
WORDPOS('is the','now is the time') -> 2
WORDPOS('is time ','now is the time') -> 0
WORDPOS('be','To be or not to be') -> 2
WORDPOS('be','To be or not to be',3) -> 6
ΓòÉΓòÉΓòÉ 4.1.197. WORDS(string) ΓòÉΓòÉΓòÉ
Choose:
o Syntax
o Definition
o Example
o E Language Syntax
ΓòÉΓòÉΓòÉ <hidden> Syntax ΓòÉΓòÉΓòÉ
WORDS( string )
ΓòÉΓòÉΓòÉ <hidden> Definition ΓòÉΓòÉΓòÉ
Returns the number of blank-delimited words in string.
ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
Here are some examples:
WORDS('Now is the time') --> 4
WORDS(' ') --> 0
ΓòÉΓòÉΓòÉ 4.2. Conditional and Loop Statements ΓòÉΓòÉΓòÉ
The IF statement is used to change the flow of statements depending upon some
condition. As you can see, the syntax varies from that of REXX:
IF
Conditional execution
IF expression THEN
statements
{ELSEIF expression THEN
statements}
[ELSE
statements]
ENDIF
Note: Any nonzero, non-null value for expression is regarded
as TRUE. The value zero is FALSE, and (as of version 3.07) a
null value is FALSE. The null-value treatment is important
because that's the default value returned by a DEFPROC. If a
DEFPROC simply "runs off the end" and does not have an
explicit RETURN statement, ET automatically assigns a null
return value. For example:
defproc tinyproc=
x = 1
/* no return statement */
defc test=
myswitch = tinyproc()
if myswitch then
sayerror 'null is true'
else
sayerror 'null is false'
endif
Previous versions of E would have printed null is true because
the value of myswitch was not precisely zero ('0'). It makes
more sense for no-value to be false. But it's still better
practice to specify the return value explicitly in your procs.
Several ways are provided to structure a repetitive loop:
WHILE - DO
Conditional loop
WHILE expression DO
statements
ENDWHILE
DO - WHILE
Same effect as WHILE - DO
DO WHILE expression
statements
END or ENDDO
DO FOREVER
Continuous loop (See LEAVE, below)
DO FOREVER /* clearer meaning than WHILE 1 */
statements /* Exit with a RETURN or LEAVE */
END or ENDDO
LOOP
Same effect as DO FOREVER
LOOP /* equivalent to the previous one */
statements
ENDLOOP
FOR
Stepwise Iteration
FOR i=expression TO expression [BY expression]
statements
ENDFOR
DO (FOR)
Same effect as FOR
DO i=expression TO expression [BY expression]
statements
END or ENDDO
LEAVE
Exits LOOP, WHILE or DO.
Execution resumes after ENDLOOP, ENDWHILE or END.
ITERATE
Iterates LOOP, WHILE or DO.
Execution resumes at LOOP, WHILE or DO.
Note: It is possible to modify the loop index within the FOR loop. For
example, the following is correct:
for i= 1 to 10
if i=7 then
i= i - 1 -- i = 6
endif
endfor
ΓòÉΓòÉΓòÉ 4.3. The Parse Statement ΓòÉΓòÉΓòÉ
Use the PARSE statement to extract information from a string. The syntax is:
PARSE ARG template
PARSE VALUE expression WITH template
where expression is the input, i.e. the string to parse, and template is a list
of symbols separated by blanks, which dictates how to parse the input.
The syntax of template is
{ '.' | string | +number | -number |number | variable | '(' variable ')' }
The only difference between the two forms of the parse statement is that the
PARSE ARG statement is a special case of the PARSE - VALUE - WITH statement.
The PARSE ARG statement automatically assumes ARG(1) to be its input.
Therefore, the following two statements are logically equivalent:
PARSE ARG A B C D
PARSE VALUE arg(1) WITH A B C D
The template in the above example is A B C D. A template in general specifies
the names of variables that are to be given new values, together with optional
triggers (either strings or special characters) to control the parsing. In the
example, A, B, C and D are all variables to which new values will be assigned;
there are no triggers.
Normally each variable in the template is assigned one word from the input
string. The last variable, however, is assigned the remainder of the string
(if any). If there are fewer words in the string than variables in the
template, all excess variables are set to null. A null, therefore, indicates
the end of data.
For example, if the string 'The Red Baron' is parsed with the template A B C D,
then the first three variables would each be assigned one word from the string,
in sequence, and the variable D would be set to ' '.
If the template were changed to A B and the input string remained the same,
then the variable A would be set to 'The' and the variable B would be set to
'Red Baron'.
The parsing algorithm also allows some pattern matching, in which you may
trigger on strings. If the template contains a string (such as a '/' or 'TO' ),
then synchronization will occur at the next point where the trigger matches the
data. This is best explained with the aid of examples:
Input data: EDIT AUTOEXEC.BAT /D
Template: X Fn '/'Opt
Variables set: X = 'EDIT'
Fn = 'AUTOEXEC.BAT'
Opt = 'D'
The value of a variable may be used as a trigger, by enclosing the name of the
variable in parentheses. It then acts in exactly the same way as a literal
string trigger. For example:
delim=','
parse value 'abc, def' with x (delim) y /* splits the string */
This feature allows you to parse when you don't know what the trigger string
(delim in the example) is in advance. Without the parentheses, the variable
delim would receive the value 'def'.
You may also use numbers as triggers to pick out positional substrings, or to
extract a string of a certain length. These may be absolute column numbers, or
numbers relative to the last trigger (or column) specified.
Input string: This is the time for all good men
Template: 8 X +4 16 Y +5
Variables set: X = ' the' /* four starting at column 8 */
Y = 'e for' /* five starting at column 16 */
In this case, a +n following the variable indicates that the string to be
picked out should begin at the last column specified and should continue n
characters to the right. The '-' unary operator cannot be used in this manner.
However, both unary plus and minus can also be used in the template to advance
the current column position. For example,
Input string: This is the time for all good men
Template: 10 't' X +4 +5 Y -4 Z
Variables set: X = 'time'
Y = 'all good men'
Z = 'for all good men'
Notice that in this example, the current position is moved to the 10th column,
and then to the next instance of 't' (which is the 't' in 'time'). X is
assigned a string of length 4 beginning from this point. The current position
is then moved 5 positions to the right. The Y variable is assigned a string
beginning at this point and continuing to the end of the string. The cursor
position is then moved back (to the left) 4 positions and the Z variable gets a
string from that position to the end of the string.
Further examples:
Input string: MSG WINPA(FRED) Hello Fred
Template: X node'('userid')' msg
Variables set: X = 'MSG'
NODE = 'WINPA'
USERID = 'FRED'
MSG = ' Hello Fred'
Input string: /foo/bar zot/
Template: delim 2 word1 (delim) word2 (delim)
Variables set: delim = '/'
word1 = 'foo'
word2 = 'bar zot'
Note that each substring (between triggers) is parsed in the same manner as a
complete string would be if there were no triggers present.
You can also use a period (.) as a place holder to skip over a word that would
otherwise be placed in a variable. For example:
Input string: 'The Red Baron'
Template: word1 . word2
Variables set: word1 = 'The'
word2 = 'Baron'
ΓòÉΓòÉΓòÉ 4.4. Compiler Directive Statements ΓòÉΓòÉΓòÉ
The following statements are different from other E statements because they
serve no function when the program is being run, rather they provide
instructions to the ET compiler.
ΓòÉΓòÉΓòÉ 4.5. compiler directives ΓòÉΓòÉΓòÉ
The compiler directive statements are:
Includes
INCLUDE 'filespec'
TRYINCLUDE 'filespec'
Conditional compilation
COMPILE IF constant_expression
statements
{ COMPILE ELSEIF constant_expression
statements }
[ COMPILE ELSE
statements ]
COMPILE ENDIF
ΓòÉΓòÉΓòÉ 4.5.1. Include Statements ΓòÉΓòÉΓòÉ
The usage and usefulness of INCLUDE statements is shown in The EPM User's
Guide. In this section, we will discuss how these statements work. Let's say
that there is an INCLUDE statement (INCLUDE 'filespec') in a file test.e. The
statement directs the compiler (ET) to replace the INCLUDE statement with the E
code found in the file named in filespec. The contents of file filespec are
inserted into file test.e. If file filespec does not exist, compilation is
aborted.
The TRYINCLUDE statement has the same syntax as an INCLUDE file, i.e. filespec
must be enclosed with quotes. It also behaves the same way as an INCLUDE
statement: the specified file is included into the file where the INCLUDE
statement appears. However, when a TRYINCLUDE statement is used, the compiler
tries to include the file. If it is unsuccessful, compilation does not halt.
For example, consider the following excerpt from a file:
tryinclude 'test1.e'
tryinclude 'test2.e'
include 'test3.e'
If the file test1.e does not exist, the compiler will simply go on to the next
statement without notifying the user. Next it will try to include file test2.e.
However, if file test3.e does not exist, the compiler will issue an error
message and stop compilation.
ΓòÉΓòÉΓòÉ 4.5.2. Conditional Compilation ΓòÉΓòÉΓòÉ
In the past few releases of E we've tried to simplify configuration and
updates. We've rearranged the standard E files to bring together all the usual
configuration options (in STDCNF.E and COLORS.E) and all the INCLUDEs (into
E.E). Ideally the user should be able to customize E with simple one-line
changes.
The available configuration techniques have been:
o setting a universal variable, for example matchtab_on=0. This is fine for
simple options but can be expensive for large features. The macros must
contain the code for all possible values of the variable since the value can
change at run-time. Even though you might never use the matchtab feature,
memory space is used for the possibility.
o setting a constant, like TEMP_PATH='C:\'. Constants have been good only for
minor configuration options which don't change after installation, such as
drive letters and directories. They're also useful for mnemonic names like
GREEN=2 to make macros more readable.
o using INCLUDE and TRYINCLUDE statements, such as tryinclude 'math.e', to ease
the installation of large optional features if the features are cleanly
separable into independent files. After the compilation is done, the INCLUDE
statements have no effect and occupy no memory.
Another tool, conditional compilation includes features which aren't cleanly
separable into files. Programmers experienced with the C language will be
familiar with this concept (as #if). Other users might be uncomfortable with
the distinction between compile-time and run-time processing.
Let's take a small feature as an illustration - imagine that whenever you press
F4 (File) you don't want the file saved if it hasn't been modified. If you were
a power user who wanted this feature, you had to modify STDCMDS.E as follows:
defc f,file=
if .modify=0 then /* my mod: don't file if not modified */
'quit'
endif
/* rest of code as before */
The trouble with modifying the standard commands like this is that you had to
repeat the modification on every new release of E. To ease your updates you
might have tried to convince us developers to include the feature in the
standard distribution version. But we've been reluctant to do this because
every user would be forced to use the same feature, or at least to sacrifice
memory space to it (if we turn it on/off with a variable assignment).
But now it's possible to write:
const FILE_ONLY_IF_MODIFIED = 1
defc f,file=
compile if FILE_ONLY_IF_MODIFIED
if .modify=0 then
'quit'
endif
compile endif
/* rest of code as before */
When the compiler sees the compile if it will check the value of the constant
FILE_ONLY_IF_MODIFIED, and, seeing that it's true, will compile the new code
just as it did when you hand-modified it. But now the feature is easier to
distribute to all users. A user who doesn't like it can set
FILE_ONLY_IF_MODIFIED = 0, which will cause ET to ignore the code enclosed
between compile if and compile endif. This happens at compile time, in much
the same manner as a TRYINCLUDE, so the other user is not penalized memory
space for the choice.
We encourage developers of add-on packages to use this feature. In time we
hope to make the most popular add-ons installable without the user having to
touch the macro source code.
The new keywords all start with the word compile:
o COMPILE IF const_expression
o COMPILE ELSE
o COMPILE ELSEIF const_expression
o COMPILE ENDIF
const_expression must be a simple expression combining only constants known at
compile time. Understand that ET cannot know the values that will be assigned
to variables at run-time (like matchtab_on). If we assume that all uppercase
identifiers represent pre-defined constants, the following are valid
const_expressions:
COMPILE IF 0 /* Means 'never compile'. */
COMPILE IF FOO + BAR >= 2
COMPILE IF EVERSION = '3.07'
COMPILE IF STATUSCOLOR = NORMAL
COMPILE IF not (OS2 or DOS)
Note: simple arithmetic and logical expressions are possible, but not string
functions such as substr().
Any strings in the constant expression associated with a COMPILE IF statement
are converted to upper case. This means that many of the values for
configuration options in the STDCNF.E file may now be entered in any
combination of lower and upper case letters. For example, the following
statement is now valid:
HOST_SUPPORT = 'pdq'
even though STDCNF.E contains the following statement:
COMPILE IF HOST_SUPPORT = 'PDQ'
HAVE_DOS = 0
COMPILE ENDIF
Since the string constant `pdq' will be converted to `PDQ' at compile-time, the
compile-if condition will be found to be true.
There must be one COMPILE ENDIF to each COMPILE IF, zero or one COMPILE ELSE's,
and zero or more COMPILE ELSEIF's. The ELSE must come after all ELSEIF's, as
in normal E if-else-endif structures.
These conditional blocks can be nested (in the same manner as if-else-endif
structures) up to a maximum depth of 20 levels.
Here's an example of how we might include different methods of host-file
support:
compile if HOST_SUPPORT = 'STD'
include 'saveload.e' -- with host support
compile elseif HOST_SUPPORT = 'EMUL'
include 'e3emul.e' -- Brian Tucker's add-on package
compile else
include 'slnohost.e' -- without host support
compile endif
The COMPILE keyword can be inserted anywhere a newline is allowed, including
cases where a newline serves as a line continuation in the middle of a
statement.
delay = 2000 /
compile if OS2
10 /* delay = 200 here */
compile else
1 /* delay = 2000 here */
compile endif
See the section Line Continuations for other examples.
ΓòÉΓòÉΓòÉ 4.5.3. Compiler Directives as Definition Primitives ΓòÉΓòÉΓòÉ
The compiler directives discussed in this section are valid E statements, i.e.
they can be contained within a DEFPROC, DEFC, or other definition. However,
compiler directives can also be considered definition primitives depending upon
what they contain. Consider the following example: file junk.e contains:
sayerror "print junk"
x = x + 5
file main_junk.e contains:
DEFPROC junk()
universal x
x = 8
include 'junk.e'
temp = 250
After execution of the procedure junk(), the value of x is 13. In this case,
the included file (junk.e) contains only statements, and therefore the INCLUDE
statement acts as a statement. However, consider the next example: file junk.e
contains:
DEFPROC junk()
sayerror "printing junk"
file main_junk.e contains:
SET insert_state 0
DEFC com1 =
call junk()
CONST
a = 25
include 'junk.e'
If the included file (junk.e) contained only statements, as in the last
example, the ET compiler would issue the following error: "Expecting DEFinition
primitive". Because the INCLUDE statement is no longer contained within a
definition primitive, the included file must contain a definition primitive, as
it does in this example. In this case, the INCLUDE statement is not really
acting as a statement; it is acting as a definition primitive.
The same can be said of the conditional compile statement: it can occur within
a definition primitive and enclose only statements or it can occur outside a
primitive and enclose one or more definition primitives. The following examples
show various correct usages:
CONST
flag1 = 1
DEFPROC fred()
universal perm
perm = 8
compile if flag1 = 1
perm = perm + 5
compile endif
sayerror "perm is " perm
/************** Second example ****************/
CONST
USERS_CHOICE = 0
compile if USERS_CHOICE
DEFC optional_command =
sayerror "just printing junk for testing"
compile endif
DEFPROC test()
sayerror "stuff"
In the first example, if flag1 is set to 1, then the value of perm becomes 13.
If flag1 is set to 0, then the value of perm is 8. In either case, the value is
printed out with the sayerror statement. In the second example, if USERS_CHOICE
is set to 1, the optional_command is included in the code; otherwise it is not,
and at run-time (when you are running the editor), the command optional_command
does not exist, and will not be recognized.
ΓòÉΓòÉΓòÉ 4.6. Using EPM Commands in E Statements ΓòÉΓòÉΓòÉ
The E commands that were discussed in The EPM User's Guide can be used not only
on the command dialog box, but also in E programs. When the name of a command
and its options and parameters are enclosed in quotes (single or double), the
command can be used in place of a statement. The syntax of these commands is
the same as that which was presented in the User's Guide. An example of this
usage follows:
defproc zap_file()
k = entrybox("Confirm",'/Yes/No/','Really quit?',18,0)
if k then
sayerror("Data has been cruelly obliterated ...")
'quit' /* <-- Note the quit command in quotes */
else
sayerror("File has been mercifully spared ...")
endif
When the zap_file() procedure is activated, it will prompt the user. If the
user picks 'Yes', it will quit the file; if he picks 'No' the user can continue
editing.
Another common usage is when redefining key strokes. For example:
def c_2
'togglecontrol 9 '
'togglecontrol 10'
This will define the key ctrl-2 to toggle the scroll bars on or off. Other
examples can be seen in section Sample E Procs.
Any command can be used as a statement. The command need not be a built-in
command; it can be a command defined by a user using a DEFC. For example:
defc temp
call temp()
defproc temp()
'testA stuff'
defc testA
sayerror "argument is " arg(1)
Issuing the command temp will print argument is stuff.
ΓòÉΓòÉΓòÉ 4.6.1. Commands Omitted From the User's Guide ΓòÉΓòÉΓòÉ
Most of the standard commands (defc constructions) are listed in The EPM User's
Guide. However, a few were omitted because they produce no useful results by
themselves, but are only really useful in a programming context or because they
may not be understood by a novice. These advanced commands are:
Command Description
ACTIVATEFILEID fileid
activates the file specified by the file handle
fileid.
AMU_ADDENDA_ADDITION word
adds the word specified by word to the addenda
file specified the variable ADDENDA_FILENAME.
AMU_ADDENDA_PICKUP
adds the addenda dictionary specified by the
variable ADDENDA_FILENAME to the standard
dictionary.
CLEARSHARBUFF
clears the shared PM buffer.
COMMANDLINE [ text ]
brings up the command line dialog box. This is
the equivalent of the standard ESC key
definition. This command optionally takes an
argument of text or a string variable. If the
argument is included, it will be placed on the
command line.
COPY2DMBUFF
copies the marked area to the "Delete Mark"
buffer.
COPY2SHARBUFF
copies a marked area to the shared buffer.
CURSOROFF
turns the cursor off. This command is equivalent
to a:
`TOGGLECONTROL 14 0'
To turn the cursor back on again, issue a
TOGGLECONTROL command with a 1 instead of a zero
as the second argument.
DUPMARK typemark
takes an argument (typemark) of:
M = move marked text
C = copy marked text
O = overlay marked text
U = unmark marked text
D = delete marked text
and executes that action on the marked text.
EPM will look first in the local buffer and then in the shared buffer for
marked text.
GETDMBUFF
gets text from the Delete Mark buffer.
GETSHARBUFF
gets text from EPM shared buffer.
LOADDEFAULTMENU
loads the default menu setup.
MH_BEGIN_MARK
mouse handler's begin mark. This is executed when
the standard mouse setup begins a drag. See
MOUSE.E and Configuring the Mouse. for more
information.
MH_CANCEL_MARK
mouse handler's cancel mark. This is executed
when the standard mouse setup double clicks on
button one. See MOUSE.E and Configuring the Mouse
for more information.
MH_END_MARK
mouse handler's end mark. This is executed when
the standard mouse setup ends a drag. See MOUSE.E
and Configuring the Mouse for more information.
MH_GOTOPOSITION
moves the cursor to the current mouse pointer
location. This is like the standard mouse of a
single button one click. See MOUSE.E and
Configuring the Mouse for more information.
SETMESSAGELINE [string]
Updates the messageline. If the optional string
is present, that is set as the new messageline
text. If no argument is given, the messageline
color is updated with the value in the universal
variable vMESSAGECOLOR.
SETSTATUSLINE [string]
Updates the statusline. If the optional string
is present, that is set as the new statusline
text. If no argument is given, the statusline
color is updated with the value in the universal
variable vSTATUSCOLOR.
ΓòÉΓòÉΓòÉ 4.7. Predefined Constants and Variables ΓòÉΓòÉΓòÉ
There are several predefined UNIVERSAL variables which may be accessed in any
definition without an explicit UNIVERSAL declaration:
o RC,
o join_after_wrap,
o center_search,
o exit_after_last_file, and
o two_spaces.
RC holds the error code from the last-executed command. All commands, for
example 'edit', 'quit', and 'file', set the value of RC. If no error occurs,
RC will be reset to zero by a command. Upon entering a DEFC, the value of RC
depends upon the source of the command invocation. If another definition
(internal to the E program) activates the command, RC is set to zero. If a user
issues the command from the command dialog box, RC is set to the position of
the cursor in the command dialog box. However, statements and procedures, such
as 'nextfile', 'copymark', or 'top', do NOT normally set RC. If no error
occurs, whatever value RC had before the statement is still there. This
approach was followed for considerations of speed, space, and to allow an
earlier command's RC to "filter down" to the end of the proc. Commands are the
ones most likely to encounter meaningful errors.
Thus if you want a sure error-check on a statement, zero RC first:
rc = 0
copymark
if rc then /* complain */ endif
One special case: REPEATFIND is a statement but it sets RC to zero if the find
is successful.
An assignment to one of the function key text variables changes the value of
the function key text displayed at the bottom of the screen.
There is also one predefined constant called ARGSEP. Since the argument option
separator can change from machine to machine, this constant is used to keep the
E procs portable. On a PC, ARGSEP is the slash '/'. On a RT, it's the hyphen
'-'.
JOIN_AFTER_WRAP, CENTER_SEARCH and other configurable constants are discussed
in The EPM User's Guide.
ΓòÉΓòÉΓòÉ 4.8. User Exits ΓòÉΓòÉΓòÉ
If the configuration constant SUPPORT_USER_EXITS is set when the macros are
compiled, "hooks" for user exits will be included. If any particular user exit
is not present, no attempt to call it will be made, and no error message will
be given.
The user exits are:
defmain_exit This defproc will be called from the DEFMAIN in MAIN.E, just
before the command-line arguments are executed. The argument given
will be the one passed to EPM (preceded by 'e '); if declared as a
VAR parameter, the exit can modify the value.
postsave_exit This defproc will be called from the SAVE command, just after the
file is saved. Arg(1) will be the .filename of the file, arg(2) will
be the options to the SAVE command, and arg(3) will be 0 to indicate
a normal save, or 1 to indicate that the name was changed (because
the user attempted to save a .Untitled file).
presave_exit This defproc will be called from the SAVE command, just before the
file is saved. The first three arguments will be the same as for
postsave_exit, and arg(4) will be the return code from the SAVE.
quit_exit This defproc will be called from the QUIT command, just before the
file is quit. Arg(1) will be the .filename of the file.
rename_exit This defproc will be called from the NAME command and the
SAVEAS_DLG command. Arg(1) will be the old name, arg(2) will be the
new name, and arg(3) (if present) will be 1 to indicate that the name
was changed by the SAVEAS_DLG command.
Note: The SAVEAS_DLG command (executed when Save as is selected from the File
menu) changes the name directly; it doesn't call the NAME command. It
does call the rename_exit directly. The SAVE command can also present
the Save as dialog if the user attempts to save the .Untitled file; in
this case, the NAME command is called to process the name change.
Note: The universal variable isa_file_cmd is set to 1 just before the FILE
command issues a SAVE command. User exits that need to know whether or
not a file is being quit immediately after being saved can check this variable.
Packages that want to provide an exit while still coexisting with other user
exits can use the following code:
tryinclude 'MYCNF.E'
compile if not defined(SUPPORT_USER_EXITS)
const SUPPORT_USER_EXITS = 0
compile endif
compile if not SUPPORT_USER_EXITS
*** Error - SUPPORT_USER_EXITS must be 1 in MYCNF.E to add this!
compile endif
compile if not defined(USER_PROVIDES_OWN_EXITS)
const USER_PROVIDES_OWN_EXITS = 0
compile endif
compile if USER_PROVIDES_OWN_EXITS -- Call the following from your exit.
defproc packagename_rename_exit(oldname, newname) =
compile else
defproc rename_exit(oldname, newname) =
compile endif
-- Body of routines goes here...
and instruct the user to include the following in their MYCNF.E if no other
exits are being used:
const
SUPPORT_USER_EXITS = 1
or, if other user exits are being used, to include the following in their
MYCNF.E:
const
SUPPORT_USER_EXITS = 1
USER_PROVIDES_OWN_EXITS = 1
and the following in their MYSTUFF.E:
defproc rename_exit(oldname, newname) =
call packagename_rename_exit(oldname, newname)
call otherpackagename_rename_exit(oldname, newname)
/* etc... */
ΓòÉΓòÉΓòÉ 5. Sample E Procs ΓòÉΓòÉΓòÉ
Using the E language, the user can configure the editor and define complex
macros for increased editing power. The E language is translated by the 'etpm'
compiler to increase the speed of execution. The syntax of the ETPM compiler
is:
ETPM filespec[.E] [destfile[.EX]]
The default extension of the source code is .E. If no destination file is
specified, ETPM will use the same source file name and just attach an .EX
extention. Typically, only the filespec is given. These source modules are
referred to as E Procs. Two examples of an E Procs are shown below.
ΓòÉΓòÉΓòÉ 5.1. Example One ΓòÉΓòÉΓòÉ
The first E Proc is a simple procedure to define a command to display the
different mouse pointers available. Edit a file (say TESTFILE.E). Then type in
the following code:
defc firsttime -- Define a initialization procedure
universal pointertype -- Make available to both procedures
pointertype = 1 /* Initialize pointertype (same as
pointertype = '1') */
mouse_setpointer pointertype -- Set the mouse pointer type
sayerror "Completed first time." -- Message so you know it worked
defc more -- Define a subsequent procedure
universal pointertype -- Make E know pointertype is global
pointertype = pointertype + 1 -- Increment pointer type
mouse_setpointer pointertype -- Set the mouse pointer type
sayerror "Completed subsequent time. Cusor number: "||pointertype
-- Message so you know it worked
Then enter RELINK from the commandline dialog box. This will save, compile, and
link this code (provided, of course, that there were no typos and the code
compiled successfully). The commands FIRSTTIME and MORE are now defined. From
the command line dialog box, type FIRSTTIME. Mouse pointer 1 is an arrow so you
won't notice a change in the pointer but will see the message Completed first
time. Now enter the MORE command. This should change the mouse pointer type.
You can continue changing the mouse pointer (upto 15 times) by entering the
MORE command. Entering FIRSTTIME again will start you at mouse pointer one
again.
Note how the variable pointertype is declared universal so it can carry a value
between procedures. Since strings and numbers are interchangeable, we could
have initialized pointertype with a string instead of a numeric constant.
ΓòÉΓòÉΓòÉ 5.2. Example Two ΓòÉΓòÉΓòÉ
The second E Proc shows how key set definitions can be programmed. This E Proc
will configure a few keys of the editor to mimic the EMACS editor.
/**********************************************************************/
/* This E Proc will configure a few keys in the E editor to perform */
/* the same operations as the EMACS editor. */
/**********************************************************************/
defkeys mykeys
def F3 = 'quit' /* define a key for fast exit. */
def C_A = beginline
def C_B = left
def C_D = deletechar
def C_E = endline
def C_F = right
def C_N = down
def C_P = up
def C_X =
choice = listbox("Choose:", "/Quit/Save/")
if (choice='Quit') then
'quit'
endif
if (choice='Save') then
'save'
endif
If we have a file called EMACS.E which contains the above E Procs, this file
would then be translated by the E translator with the following command from
the command dialog:
etpm emacs
To load this file (assuming it compiled correctly) we could type from the
command line dialog box:
link emacs
This will load EMACS into the currently running version of EPM.
To have this file automatically included we could add the line:
include "emacs.e"
in the file MYKEYS.E. When we recompile EPM (see The EPM User's Guide for
information on recompiling your editor from the OS/2 prompt) the EMACS key
definition will always be available by issuing the following from the command
dialog:
keys mykeys
ΓòÉΓòÉΓòÉ 6. Advanced Configuration ΓòÉΓòÉΓòÉ
The fact that you are reading this means that you probably want to configure
EPM beyond that which can be done merely by setting constants. In this section
are listed a few advanced configuration options that involve some programming.
ΓòÉΓòÉΓòÉ 6.1. Building Accelerator Tables from the Macro Language ΓòÉΓòÉΓòÉ
A Named Accelerator Table is the way true PM accelerators are created from the
E macro language. This is achieved using the BuildAccelTable, and the
ActivateAccelTable statements.
First, the BuildAccelTable statement is used to create, and add keys to, a
named accelerator table. (The first time BuildAccelTable is called the table
is automatically created.) During this process a data base is created linking
accelerator keys to command ids, and command ids to user strings. When a
named accelerator table is activated, it becomes a true PM accelerator table.
This is done via the ActivateAccelTable statement. Now, when a pre-registered
key is pressed, the corresponding command id is issued as part of the message
parameter of a PM - WM_COMMAND message. In the E macro world, the defc
PROCESSMENU is executed whenever a WM_COMMAND message is received. ARG(1) of
PROCESSMENU contains the command-id corresponding to the event that just took
place. If an accelerator key was the cause of the PROCESSMENU command, ARG(1)
will be the command-id registered during the corresponding BuildAccelTable
statement.
During the PROCESSMENU command, it is sometimes useful to take the command-id
(passed as arg(1)) and look up the corresponding user string. This is done
using the QueryAccelString function.
Accelerator tables created with the BuildAccelTable statement can be deleted
with the DeleteAccel statement. BY DEFAULT, named accelerator tables are
deleted when the corresponding edit window is closed.
ΓòÉΓòÉΓòÉ 6.1.1. BUILDACCELTABLE ΓòÉΓòÉΓòÉ
The buildacceltable statement adds a key to a named accelerator table. If it is
the first key added, the named table is automatically created. Once a table is
built, the ActivateAccelTable statement can be issued to make the named
accelerator table into an true, active PM Accelerator table. The syntax for the
buildacceltable statement is:
buildacceltable table-name, user-string, key-style, key, command-id
table-name a text string containing the name of your particular accelerator
table. (MAX. = 80 characters)
user-string an information string that can be retrieved using the
QueryAccelString function.
key-style describes the style of the accelerator key. The value must be the
sum of the PM-defined AF_ constants defined in STDCONST.E (copied
from PMWIN.H in the OS/2 Toolkit).
key a key constant, (e.g. VK_F1)
command-id a unique number within this particular accelerator table (and
active menu) to define the key in question. (1-MAXINT)
ΓòÉΓòÉΓòÉ 6.1.2. ACTIVATEACCELTABLE ΓòÉΓòÉΓòÉ
The activateacceltable statement activates a named Accelerator table created
with BuildAccelTable. When a named accelerator table is activated, it becomes a
true PM accelerator table. The syntax for the activateacceltable statement is:
activateacceltable table-name
table-name where 'table-name' is a text string containing the name of your
particular accelerator table. (MAX. = 80 characters)
ΓòÉΓòÉΓòÉ 6.1.3. QUERYACCELSTRING ΓòÉΓòÉΓòÉ
The queryaccelstring statement allows the retrival of the user-string which was
registered with the BuildAccelTable statement. The syntax for the
queryaccelstring statement is:
queryaccelstring table-name, command-id
table-name where 'table-name' is a text string containing the name of your
particular accelerator table. (MAX. = 80 characters)
command-id where 'command-id' is a unique number within this particular
accelerator table to define the key in question. (1-MAXINT)
ΓòÉΓòÉΓòÉ 6.1.4. DELETEACCEL ΓòÉΓòÉΓòÉ
The deleteaccel statement deletes a named Accelerator table created with
BuildAccelTable. BY DEFAULT, named accelerator tables are deleted when the
corresponding edit window is closed. The syntax for the deleteaccel statement
is:
deleteaccel table-name
table-name where 'table-name' is a text string containing the name of your
particular accelerator table. (MAX. = 80 characters)
ΓòÉΓòÉΓòÉ 6.1.5. An example that uses the Named Accelerator statements ΓòÉΓòÉΓòÉ
-- constants needed for Accelerator example.
-- key constants
const VK_F2 = 33 -- Taken from PMWIN.H
VK_F3 = 34
VK_F4 = 35
VK_F5 = 36
-- key style constants
AF_CHAR = 1 -- Taken from PMWIN.H
AF_VIRTUALKEY = 2
AF_SCANCODE = 4
AF_SHIFT = 8
AF_CONTROL = 16
AF_ALT = 32
AF_LONEKEY = 64
AF_SYSCOMMAND = 256
AF_HELP = 512
-- Creates Two named accel tables, and activates the "default" table
defc loadaccel
universal activeaccel
activeaccel='default'
otheraccel ='other'
-- Register F2 and F3 as accelerator keys
buildacceltable activeaccel, 'john', AF_VIRTUALKEY, VK_F2, 1000
buildacceltable activeaccel, 'thomas',AF_VIRTUALKEY, VK_F3, 1001
-- Register F4 and F5 as accelerator keys
buildacceltable otheraccel, 'jason', AF_VIRTUALKEY, VK_F4, 1002
buildacceltable otheraccel, 'larry', AF_VIRTUALKEY, VK_F5, 1003
-- Make the "default" named accel table active. Now F2 and F3
-- are real accel keys, when they are selected they will cause
-- "processmenu" to be executed with id's of 1000 or 1001
activateacceltable activeaccel
-- In the E macro world, the defc PROCESSMENU is executed whenever
-- a WM_COMMAND message is received. ARG(1) of PROCESSMENU contains
-- the command-id corresponding to the event that just took place.
-- If an accelerator key was the cause of the PROCESSMENU command,
-- ARG(1) will be the command-id registered during the corresponding
-- BuildAccelTable statement.
-- If a pull-down menu was selected then ARG(1) will be the command-id
-- registered during the corresponding BUILDMENUITEM statement.
defc processmenu
universal activemenu, activeaccel
-- arg(1) contains the command id specified as registered with
-- either the BUILDMENUITEM, or BUILDACCELTABLE statements.
cmdid = arg(1)
-- First check if a usersting exists for this command-id in the
-- active accel table.
accelstr=queryaccelstring(activeaccel, cmdid)
sayerror "querystring=<"accelstr"> cmdid=<"cmdid">"
-- "flip-flop" active accel tables just for fun!
if accelstr="thomas" then
activeaccel="other"
activateacceltable activeaccel
endif
if accelstr="jason" then
activeaccel='default'
activateacceltable activeaccel
endif
-- if an accel string was not found, try the menu manager.
if accelstr="" then
strip(querymenustring(activemenu,cmdid),"T",\0)
-- execute user string after stripping off null terminating char
endif
ΓòÉΓòÉΓòÉ 6.2. Building Menus from the Macro Language ΓòÉΓòÉΓòÉ
EPM allows user configurable pull-down menus. The menus are created from the
macro language using a set of macro procedures:
BuildSubMenu Adds an entry to the action bar.
BuildMenuItem Adds an entry to an action bar submenu.
ShowMenu Activates an action bar .
DeleteMenu Deletes an action bar, submenu, or menu item.
QueryMenuString Returns the command associated with a menu item.
ΓòÉΓòÉΓòÉ 6.2.1. Buildsubmenu ΓòÉΓòÉΓòÉ
The buildsubmenu command creates an option on the action bar. If the option
name already exists, then the command is appended to the existing option menu
as a sub menu option. Although the menu is built internally, it is not seen
until a 'showmenu' is issued. The syntax for a buildsubmenu command is:
buildsubmenu menu_name, subid, text, cmd, mis_style, mia_attr
menuname where 'menuname' is a text string containing the name of your
particular menu. (MAX. = 80 characters)
subid where 'subid' is a unique number within this particular menu to
define that sub-menu in question. (1-MAXINT)
text where 'text' is a string of text which is to appear in as the title
of that particular sub-menu.
cmd where 'cmd' is the editor defc that is to be executed when the
submenu is selected. If the submenu has associated items then the
defc is not executed.
mis_style where 'mis_style' is a PM menu style.
mis_attr where 'mis_attr' is a PM menu attribute.
ΓòÉΓòÉΓòÉ 6.2.2. Buildmenuitem ΓòÉΓòÉΓòÉ
The buildmenuitem command appends a menu item under an existing option on the
action bar (which can be created with buildsubmenu). The syntax for
buildmenuitem is:
buildmenuitem menu_name, subid, item_id, text, cmd, mis_style, mia_attr
menu_name where 'menuname' is a string containing the name of your particular
menu. (MAX. = 80 characters)
subid where 'subid' is a unique number within this particular menu to
define that sub-menu in question. (1-MAXINT)
item_id where 'item id' is a unique number within this particular menu to
define that menu-item in question. (1-MAXINT)
text where 'text' is a string of text which is to appear in as the title
of that particular sub-menu.
cmd where 'cmd' is the editor defc that is to be executed when the
submenu is selected.
mis_style where 'mis_style' is a PM menu style.
mis_attr where 'mis_attr' is a PM menu attribute.
ΓòÉΓòÉΓòÉ 6.2.3. Showmenu ΓòÉΓòÉΓòÉ
Displays a prebuilt menu, built using 'buildsubmenu' and 'buildmenuitem'. The
syntax for the showmenu command is:
showmenu menuname
menuname where 'menuname' is a string containing the name of your particular
menu. (MAX. = 80 characters)
Note: When a menu item is selected, the PROCESSMENU command (defined in
STDCTRL.E) is called, with an argument of the itemid. PROCESSMENU retrieves the
command associated with this itemid in the menu whose name is stored in the
universal variable ACTIVEMENU, and then executes the retrieved command.
Therefore, whenever a SHOWMENU is done, ACTIVEMENU should be set to the name of
the menu that was shown.
ΓòÉΓòÉΓòÉ 6.2.4. Deletemenu ΓòÉΓòÉΓòÉ
Deletes a named menu or a particular part of a named menu from the internal
menu manager. The syntax of the deletemenu command is:
deletemenu menuname, subid, itemid, itemonly
menuname where 'menuname' is a string containing the name of your particular
menu. (MAX. = 80 characters)
subid where 'subid' is the sub-menu that is to be deleted. To delete all
submenus set this parameter to 0.
itemid where 'item id' is the item to start deleting off a particular sub
menu. To delete all menu items under a sub menu, set this
parameter to 0.
itemonly where 'itemonly' is true if it is desired to delete only the items
under a sub-menu but not the sub-menu itself.
ΓòÉΓòÉΓòÉ 6.2.5. querymenustring ΓòÉΓòÉΓòÉ
Returns the command associated with a menu option. The syntax of the
querymenustring command is:
cmd = querymenustring(menuname, subid)
cmd where 'cmd' will contain the command associated with the menu
option requested.
menuname where 'menuname' is a string containing the name of the menu to be
queried.
subid where 'subid' is the sub-menu id number of the menu to be queried.
ΓòÉΓòÉΓòÉ 6.2.6. sample menu addition ΓòÉΓòÉΓòÉ
This example shows a menu being added to the default action bar menu. It is
defined as a DEFINIT in my MYSTUFF.E file. This means that each time a new edit
window is initialized, the action bar option Compile will be added to the
default action bar choices. Remember to recompile your editor to have this
addition take effect.
definit
universal defaultmenu
buildsubmenu defaultmenu, 19, 'Compile', '', 0, 0
buildmenuitem defaultmenu, 19, 911, 'Save', 'save', 0, 0
buildmenuitem defaultmenu, 19, 912, 'Relink', 'relink test', 0, 0
showmenu defaultmenu
Note that the numbers 19, 911, and 912 where chosen to insure that they are
unique.
ΓòÉΓòÉΓòÉ 6.3. Configuring the Mouse ΓòÉΓòÉΓòÉ
Power users may want to configure the mouse to meet their needs. There are
three base mouse sets that can be configured. See The EPM User's Guide for
information on setting the constant my_Mousestyle to the desired value (1,2 or
3). This will change the basic mouse configuration styles. You can also
configure the mouse actions yourself. To execute these use the built-in
procedure REGISTER_MOUSEHANDLER.
The REGISTER_MOUSHANDLER(IsGlobal, event, mcommand) command allows the binding
of mouse actions to commands. Mouse actions can be global or local. Mouse
actions will be processed as follows:
1. local mouse action definition (if defined)
2. else global mouse action definition (if defined)
3. else mouse action ignored.
The variable IsGlobal determines whether the mouse action described is local or
gloabl. The variable event determines the mouse action to be bound with the
command listed in the variable mcommand. Event should be in the following
format:
'key action state'
The key refers to the mouse key (either 1 or 2). The action must be one of the
following:
BEGINDRAG activates at the beginning of the drag
CLICK activates if a button (specified by key) is single clicked
SECONDCLK activates if a button (specified by key) is double clicked
These actions must be capitalized and have exactly one space between the key
and the state numbers. The state should be the sum of the following:
0 = no states active
1 = shift key active
2 = control key active
4 = alternate key active
An Event should can also be of the following format:
'action'
where action must be one of the following:
ENDDRAG activates at the end of a drag
CANCELDRAG activates if a drag is cancelled
These actions must be capitalized and unpadded by spaces.
An example of a mouse action is:
call register_mousehandler(0,'2 SECONDCLK 3','quit')
This would set the second click of button two on the mouse with the shift and
control states activated to do a QUIT command. This key action would be bound
locally to a particular file. Similarly,
call register_mousehandler(1,'CANCELDRAG','SynthesizeVoice whoops')
would cause the 'SynthesizeVoice whoops' command to be invoked every time a
drag was canceled in any file that did not have a local CANCELDRAG event
handler defined.
By combining several of these register_mousehandler statements together in a
DEFLOAD statement, one can customize the mouse actions. Note that the
following defc commands are useful for helping define common mouse actions:
o MH_BEGIN_MARK
o MH_CANCEL_MARK
o MH_END_MARK
o HH_GOTOPOSITION
See the section Commands Omitted From the User's Guide. for descriptions on
these commands.
An example use of these commands is:
defc mymouse
register_mousehandler(0,'1 CLICK 2','MH_GOTOPOSITION')
sayerror "New mouse command is in effect."
Compiling and linking this command into EPM will allow the new mouse action to
be added when the command MYMOUSE is entered in the commandline dialog box.
Then, whenever you hit a ctrl+left mouse button one click, the cursor will move
to the mouse's position.
If you want a series of events to happen, define a new command using defc. The
following is an example:
defc mycmd
getline txtline -- get the current line
'mh_gotoposition' -- go to the mouse position
insertline txtline -- copy the line
up -- move up to the new line
defc mymouse
register_mousehandler(0,'1 CLICK 2','mycmd') -- set the mouse key
sayerror "New mouse command is in effect." -- show it worked
In this example, when compiled and linked, executing the command MYMOUSE will
setup the ctrl+single button one click combination to copy the line the cursor
is on, to the line the mouse is pointing to. See the file MOUSE.E for more
examples of defining mouse actions.
As you can see, the REGISTER_MOUSEHANDLER is a very powerful command that
should be exploited to make the most of EPM and the mouse.
ΓòÉΓòÉΓòÉ 6.4. Programming Hints ΓòÉΓòÉΓòÉ
Programming Hints
ΓòÉΓòÉΓòÉ 6.4.1. Using REFRESH ΓòÉΓòÉΓòÉ
Advanced users may find themselves writing applications that rely heavily on
the E programming language. In such applications the need may arise to have
messages and actions update the screen while the macro continues in progress.
Take the following example:
defproc delay(time)= -- procedure to slow things down
totaltime=time * 100 -- this procedure represents the time consumed
for i = 1 to totaltime -- ... by calculations and E commands or
j = i+5/3 -- ... external programs
endfor
defc mycmd=
'togglecontrol 8 1' -- make sure the message bar is showing
'setmessageline Stage one executing...' -- this should trace
call delay(4) -- ... the macro's execution
'setmessageline Stage two executing...'
call delay(4)
'setmessageline Stage three executing...'
In this example, all the message appear very quickly as the message buffer
empties at the end of the procedure and not throughout the procedure as was
intended. This occurs because the compiler doesn't refresh the screen during
the execution of the macro. Constantly refreshing the screen is very costly and
would slow down the execution of EPM too much. To accomplish the goal (ie. have
the messageline trace the execution) replace mycmd with:
defc mycmd=
'togglecontrol 8 1'
'setmessageline Stage one executing...'
refresh
call delay(4)
'setmessageline Stage two executing...'
refresh
call delay(4)
'setmessageline Stage three executing...'
refresh
The new MYCMD will show the lines as they execute. All that was added was the
internal statement REFRESHto cause a screen refresh. (By the way the command
'TOGGLECONTROL 8 0' will turn the messageline off).
ΓòÉΓòÉΓòÉ 6.4.2. Using ECHO ΓòÉΓòÉΓòÉ
Debugging programs can sometimes be a rather tricky task. E is no exception.
There is an internal procedure ECHO that can be inserted into programs to allow
a command trace. Whenever a command is executed, it will first appear in a
message dialog box. By keeping track of the commands the programmer can help
trace down errors.
There is also a defc front end for this internal command, allowing ECHO to be
issued from the command line dialog box.
Another useful debug tool is the messageNwait standard procedure. By placing
messageNwaits one can view variables and create check points to verify the
macro's execution.
ΓòÉΓòÉΓòÉ 7. Linkable External Modules ΓòÉΓòÉΓòÉ
Linkable external modules.
ΓòÉΓòÉΓòÉ 7.1. Introduction ΓòÉΓòÉΓòÉ
You can compile a group of .E files into an .EX file that is separate from the
E.EX file, and yet still incorporate both into the editor. In other words,
multiple .EX files can be loaded into the editor. Each .EX file can use up to
64K of p-code space. This means that there's effectively no limit on the total
size of a user's compiled macros, as long as they can be broken into logical
chunks ("modules") of less than 64K each.
I'll use the DRAW feature as an example of the new reorganization of E via
these linkable modules. We used to include the draw code into the base E.E so
that it was always available, and always occupied 3410 bytes of p-code space.
But in version 4.02, E.E omits the feature:
compile if EVERSION < '4.02'
include 'slimdraw.e'
compile endif
Instead, DRAW.E is compiled separately into its own .EX file. Now when you type
draw in the command dialog box, EPM searches for DRAW.EX on disk, loads it into
its own block of memory, and begins execution. The relocation of the draw code
is transparent to the user, except for the slight delay of the disk search.
Once the draw command is completed, the module is released again, to free up
memory.
ΓòÉΓòÉΓòÉ 7.2. Implicit Loading of External Modules ΓòÉΓòÉΓòÉ
External modules can be invoked implicitly, by simply issuing the name of the
module as a command. As in our previous example, the user (or a macro) can
simply issue the DRAW command (F6). When E sees that the command is not in its
base set, it will search the disk for an .EX file of the same name. The search
follows the same rules as for shelling an external .EXE program:
o It does not occur if AUTOSHELL is off.
o The search path is:
- the current directory,
- the directories in PATH,
- the directories in EPMPATH, and
- E's directory.
o An .EX file will be found before a .EXE or .CMD file, but after an internal
system command. (That is, you can't name a module EDIT.EX because EDIT will
always be recognized first as an internal system command.)
Upon activation of the module, its code contents will be executed in the
following order:
o DEFINIT will be executed first if it exists. This will consist of minor
initialization tasks like predefining variables.
o DEFMAIN will be executed. This is the body of the command. If you convert
an old macro to an external module, you'll usually rename its DEFC to
DEFMAIN. For instance, when SLIMDRAW.E was converted to the module DRAW.E,
defc draw was changed to defmain.
o DEFEXIT, if it exists, will be executed after DEFMAIN finishes.
When a module is invoked implicitly, it is executed once and discarded. All
three sections -- DEFINIT, DEFMAIN, DEFEXIT -- are run in sequence, so the
division makes little difference; you'd get the same results by lumping them
all into DEFMAIN.
ΓòÉΓòÉΓòÉ 7.3. Explicit Linking of External Modules ΓòÉΓòÉΓòÉ
For better control, you can explicitly load a module with the LINK and UNLINK
statements. The DRAW module can be linked by the statement:
link 'draw'
E will search the disk for the explicit filename DRAW.EX, without bothering to
check for internal system commands or .EXE files. This gives you some minor
advantages since an explicit search can be faster, and the module can have the
same name as a system command (DIR.EX) or a DEFC compiled into your base set.
But the primary advantage is a better control of the order of execution.
DEFMAIN is not executed at all. DEFINIT is executed at link time, and DEFEXIT
at unlink time. In the interim all the module's commands, procs, universal
variables and keysets are available globally. This will be important if
procedures or variables are shared by several modules.
Explicit linking to the draw module does NOT execute the DRAW command. In fact
the DEFMAIN of such a module is never executed if it is explicitly linked. In
order to execute the DRAW command under these conditions, you must define a
defc draw. The following example shows how the new external draw module allows
users to link to it implicitly and explicitly:
definit
/* initializations, global vars, etc. */
defmain
'draw' arg(1)
defc draw
/* code which implements DRAW command */
/* remains the same as when it was */
/* included in E.E */
If you repeat a link of an already-linked module, no harm is done. The disk is
not searched again, but the module's DEFINIT is re-executed as if the module
were reloaded from scratch.
Note: if your module has a DEFEXIT, don't use a STOP statement to end
execution of DEFMAIN. A STOP will permanently end the module's execution
before getting to the DEFEXIT.
Note: The RC, universal return code variable, is set to the module number of
the .ex file linked.
ΓòÉΓòÉΓòÉ 7.4. Useful Commands ΓòÉΓòÉΓòÉ
Since LINK and UNLINK are statements, we had to redefine them as commands in
order to give you access to explicit linking from the command dialog box. We
also added a RELINK command. All of these commands are defined in the file
LINKCMDS.E as follows:
defc link
link arg(1)
defc unlink
unlink arg(1)
A combination of the two gives us the nifty RELINK command:
defc relink
if arg() > 0 then
modulename=arg(1) -- if argument is given, then uses that
else
modulename=.filename -- if no argument, then assume current file
'save '||.filename -- ... and save current file
endif
'etpm' modulename -- Recompile it,
unlink modulename -- unlink the old version,
link modulename -- relink the new one.
This is very useful for fast development of macros, since you don't have to
exit from the editor to compile revised macros and re-run the newly compiled
version. You can relink a macro in a few seconds. (RELINK DRAW, for example,
takes 3 seconds on my AT. Understand that the slow step is the compilation;
LINK and UNLINK are almost instantaneous.)
When using LINK, UNLINK and RELINK as commands, you need not enclose the module
name in quotes. For example, the statement link 'draw' is acceptable, but the
command link 'draw' would be incorrect. The interpreter would assume that the
name of the module was six characters and included the quotes. The correct
syntax for the command (i.e. issued from the command line dialog box) is:
link draw
ΓòÉΓòÉΓòÉ 7.5. Keysets ΓòÉΓòÉΓòÉ
Individual keys cannot be linked; you cannot define a single key (like def f1)
in an external module. You can however link a keyset, which is almost as easy,
by following these steps:
1. Begin the key definitions with a DEFKEYS declaration:
In MYMODULE.E:
defkeys mymodule_keys
def f5=
sayerror 'F5 pressed'
2. Compile the module: et mymodule.
3. Link it: link mymodule.
4. Execute a KEYS statement: keys mymodule_keys. The best place to put the
KEYS statement is in the module's DEFINIT so that it automatically gets
executed immediately after linking:
definit -- Also in MYMODULE.E
keys mymodule_keys
It doesn't make much sense to define keys in a module that will be implicitly
loaded. An implicitly-loaded module will be run once and discarded; its keyset
will not be retained long enough to be used. Instead you should explicitly link
an external module with keyset definitions, so that its resources will stick
around until released.
Keysets are stored economically (as a linked list) so that a two-key keyset
occupies only 8 bytes. The expansion and overlaying onto a base keyset occur
at run time, within the KEYS statement.
Partial keysets can be defined usefully in external modules. edit_keys can be
defined in the base module E.E, and mymodule_keys can be defined elsewhere.
The overlaying occurs soon after the link (assuming you put a KEYS statement in
MYMODULE's DEFINIT as recommended). We refer to the partial external keyset as
an overlay keyset and edit_keys as the base. E will accept BASE as a synonym
for NEW, and OVERLAY means the same thing as the absence of NEW. The following
are equivalent:
defkeys edit_keys new = defkeys edit_keys base
defkeys c_keys = defkeys c_keys overlay
You can return to the base edit_keys either by executing keys edit_keys or by
unlink 'mymodule'. When a module is unlinked, its keyset is automatically
removed.
Note: That's true only for OVERLAY keysets. E will complain if you try to
unlink a module containing the current base keyset, since that would leave no
keys at all. You'd see the message Cannot unlink base keyset module.
Note: A base keyset (as defined by DEFKEYS BASE or NEW) is automatically given
a starting set of the standard 128 ASCII keys, including 'A'-'Z', '0'-'9', and
control keys. Even if you don't give the keyset any DEF's, it will include the
ASCII keys. But some applications might not want those keys included, so
another keyset attribute CLEAR has been added. For example:
defkeys zero_keys base clear
defines a REALLY empty keyset.
ΓòÉΓòÉΓòÉ 7.6. Multiple Definitions ΓòÉΓòÉΓòÉ
If a command (DEFC) of the same name is defined in more than one module, the
highest (latest-linked) module wins. The last-linked module can be regarded as
the "current application", whose commands take precedence in case of name
conflicts. If the highest module is unlinked, commands in lower modules become
available again. Keysets are similar. If multiple modules define the same
keyset name, the latest-linked module's keyset wins.
If a procedure (DEFPROC) is defined in multiple modules, the definition in the
caller's module (if any) wins, whether or not that module is the latest-linked.
This is consistent with the concept of a current application. If module 3 calls
myproc() and module 3 itself contains a defproc myproc(), that's certainly the
one that the application writer intended to be called.
If a procedure is multiply defined but none of the definitions are in the
caller's module, an error Call: duplicated proc is issued. If a procedure is
defined only once, that definition wins even if it isn't in the caller's
module.
To determine a module number, issue a QLINK command followed by the name of an
E module already linked. For example:
QLINK EPM
would return module number zero (the lowest level) because it is always linked,
and always the first module loaded.
Universal variables can be declared in many different modules, all of which
share the same data. A universal variable is not discarded as long as any
active module references it. Thus a module can initialize a variable and be
unlinked, without the value being lost, as long as any other module needs it.
ΓòÉΓòÉΓòÉ 7.7. E Applications ΓòÉΓòÉΓòÉ
Large applications are feasible in the E language. Dynamic linking, i.e. the
ability to link a compiled module at run-time, makes it possible to distribute
an application as a compiled .EX file. Distributing object-code-only
applications is possible. This is not recommended, as many programmers wish to
be able to examine and adjust the source code of applications according to
their own needs. However, this type of distribution would have its advantages.
For example, this would make such an application much easier for the end-user
to use. The user would simply have to:
1. copy it onto the hard disk, somewhere along the PATH, and
2. type its name as a command.
Note: that's strictly true only for implicit loading. Complex applications
will usually require explicit LINK and UNLINK commands, but even those can
be given single-word front ends if desired; see MATH.E for examples.
In addition, invoking it is fast: the time for a link equals a fraction of a
second plus the path-search time. (Path-search times can be minimized by
explicit LINK commands with explicit file specs for the modules, like "link
c:\epm\mymodule".)
Another recent change to support compiled applications is that: EPM.EXE can run
earlier-version .EX files. If a developer releases an application as an
object-code black box (compiled, say, with ET 4.03) it will still be runnable
if and when the user upgrades EPM.EXE. The versions of E and ETPM will not
have to match, as long as E is more recent than the .EX file. (Assuming we
don't make any more major structural revisions as we did in release 4.02.)
If your application really must know the exact versions of E and ET it's
working with, it can check two things:
o EVERSION is a constant supplied automatically by ET. It's a constant
attribute of the .EX file. The name EVERSION appears to be an unfortunate
choice in hindsight, since it's really ETVERSION.
o A new function VER() provides EPM.EXE's version. This will be the same
version number now shown by the VER command, but in function form so it's
queryable by a macro.
Your application could do something like:
if ver() <> EVERSION then
sayerror "Sorry, I can only run with EPM.EXE version "EVERSION"."
stop
endif
Note: Advice to writers of add-on applications: If you're writing a
stand-alone E application, one that you'd like to compile separately and link
in as an external module (which we recommend), feel free to include STDCONST.E
because unused constants do not waste space now. You should also try to
include MYCNF.E to allow the user to pre-override your constants. A catch-all
header is:
include 'colors.e'
include 'stdconst.e'
tryinclude 'mycnf.e'
Your applications can check whether the user overrode your constants with
compile if defined(). For example:
compile if not defined(AUTOSAVE_PATH)
const AUTOSAVE_PATH=''
compile endif
A similar technique allows your application to check whether it's being
compiled as part of the base (by an INCLUDE) or as an external module (by a
LINK). Query the existence of any constant that's defined in the base, like
SMALL.
compile if not defined(SMALL) -- are we separately compiled?
include 'colors.e' -- if so, must include color names
compile endif
The file USERAPP.SMP, which is included in EMACROS.FLS, is a good example of a
routine that tests to see if it's base or external; if external, sets
configuration constants the same way they would be set if it were included in
the base; and defines the routines it needs without duplicating anything that's
included in the base macros.
ΓòÉΓòÉΓòÉ 7.8. Dynamic Linking ΓòÉΓòÉΓòÉ
Dynamic linking is the delayed binding of application program external
references to subroutines. There are two forms of dynamic linking -- load time
and run time.
In load time dynamic linking, a program calls a dynamically linked routine just
as it would any external routine. When the program is assembled or compiled, a
standard external reference is generated. At link time, the programmer
specifies one or more libraries which contain routines to satisfy external
references. External routines to be dynamically linked contain special
definition records in the library. A definition record tells the linker that
the routine in question is to be dynamically linked and provides the linker
with a dynamic link module name and entry name. The module name is the name of
a special executable file with the filename extension of .DLL which contains
dynamic link entry points. The linker stores module name/entry name pairs
describing the dynamic link routines in the executable file created for the
program. When the calling program is run, OS/2 loads the dynamic link routines
from the modules specified and links the calling program to the called
routines.
For more information on Dynamic Linking see the OS/2 Technical Reference
Manual. For an example of dynamic linking in E using the DYNALINK command see
the DYNATEST.E file.
ΓòÉΓòÉΓòÉ 7.9. Run-Time Error Messages for Linking and Keysets ΓòÉΓòÉΓòÉ
Call: duplicated proc
A macro called a procedure that is not defined in
the caller's module, but which is defined in more
than one other module. The caller can't decide
which DEFPROC is the right one.
Call: unknown proc
A macro tried to call a procedure that is not
defined in any module. Note that ET will now
allow you to compile an .E file with unresolved
procedure calls; it assumes some other module
will supply the DEFPROC by the time the call
occurs. If that doesn't happen, this message is
given at run-time.
Cannot find keyset
A macro tried to execute a KEYS statement with an
unknown keyset name. Perhaps the module
containing the keyset (the DEFKEYS) has not been
linked.
Cannot unlink base keyset module
You tried to unlink the module that selected the
current base keyset. What keys would be left
after the unlink?
Cannot unlink module in use
A macro tried to unlink the same module it was
contained in. Or it tried to unlink a calling
module (one that must be kept around for
returning to). Only modules which are not
involved in the current chain of execution can be
unlinked. You can produce this message by the
command 'UNLINK E' which tries to unlink E.EX.
Invalid EX file or incorrect version
You tried to link to a file that does not have
the proper .EX format expected, or you tried to
link to an .EX file that was compiled with a past
version of the ET translator.
Link: file not found
You probably misspelled the module's filename in
a LINK statement. The filename.EX could not be
found in the current directory or along the PATH.
Link: invalid filename
The module name is poorly formed in a link
statement, for example with multiple periods or
colons. This is an unusual error; normally
you'll get "Link: file not found".
Unlink: bad module filename
You tried to unlink a module that does not exist
on disk.
Unlink: unknown module
You tried to unlink a module that is not
currently linked, although it does exist on the
disk.
ΓòÉΓòÉΓòÉ 8. E Language Syntax ΓòÉΓòÉΓòÉ
In this appendix the syntax of the E language is presented in a modified EBNF
notation. For those who are unfamiliar with this form, a brief summary of its
symbolic conventions are presented here:
Keywords of the E language are printed here entirely in capital letters. All
program components (non-terminals) whose definition is included in this section
are highlighted in a bold font. All other literals (i.e. those strings that
should be included in an E phrase exactly as they appear here in the syntax)
are enclosed with single or double quotes. Any other character in the syntax is
used as a symbol to convey the following meanings:
A B represents the concatenation of A AND B.
(A | B) represents either expression A OR expression B.
[ A ] represents an optional occurrence of expression A: zero or one
occurrence.
{ A } represents zero or more occurrences of expression A.
'a'..'z' represents: 'a' OR 'b' OR 'c' ... OR 'z'
ΓòÉΓòÉΓòÉ 8.1. Syntax Notes ΓòÉΓòÉΓòÉ
1. A semicolon is treated the same as a new line. Wherever you see ';' in the
following listing, a line-break (a 'newline', CR-LF) is acceptable. Several
examples of line breaks were given in the earlier section Line
Continuations.
2. Quoted strings in syntax descriptions below indicate that the enclosed
string is not a keyword in the language. Quoted strings (ex. 'filename')
below are not case specific.
3. For speed reasons the lexer does not return a space token for space and tab
characters. Syntax descriptions have been written without space tokens for
convenience.
4. Strings may not cross file or line boundaries.
5. Comments may not cross file boundaries. There are three styles of
comments. /* */ may be nested and may cross line boundaries. ;
in column 1 makes the rest of line a comment. -- in any column makes
the rest of line a comment.
6. Include files may be nested.
7. Implied concatenation expressions with comments between have undefined
values. 'a' /* comment */'b' Undefined value
8. Identifiers are not case sensitive.
9. Compiler directives (COMPILE IF and INCLUDEs) are included in the following
listing, but cannot be sufficiently explained with this limited syntactical
depiction. Be aware that they can occur anywhere a semicolon or newline
can. For a more in depth discussion, see section Compiler Directive
Statements.
ΓòÉΓòÉΓòÉ 8.2. The Syntax ΓòÉΓòÉΓòÉ
Syntax of the E language.
ΓòÉΓòÉΓòÉ 8.2.1. e_program ΓòÉΓòÉΓòÉ
e_program ::= definition_group
ΓòÉΓòÉΓòÉ 8.2.2. definition_group ΓòÉΓòÉΓòÉ
definition_group ::= definition {definition}
ΓòÉΓòÉΓòÉ 8.2.3. definition ΓòÉΓòÉΓòÉ
definition ::= DEF keyname {','{';'} keyname} ['='] global_decl_group
statement_group [RETURN]
| DEFC identifier {',' identifier} ['='] global_decl_group statement_group
[RETURN [expression] ]
| DEFEXIT {';'} global_decl_group statement_group
| DEFINIT {';'} global_decl_group statement_group
| DEFKEYS identifier [NEW | BASE | OVERLAY | CLEAR]
| DEFMAIN {';'} global_decl_group statement_group
| DEFPROC identifier ['('{';'} formal_decl_group')'] global_decl_group
statement_group [RETURN [expression] ]
| SET 'cursors' ['='] number
| SET 'insert_state' ['='] 0 | 1
| CONST {';'} const_decl_group
| compiler_directive
| ';'
ΓòÉΓòÉΓòÉ 8.2.4. compiler_directive ΓòÉΓòÉΓòÉ
compiler_directive INCLUDE string ';'
| TRYINCLUDE string ';'
| COMPILE IF constant_expression { ';' } ( statement_group |
definition_group ) {COMPILE ELSEIF constant_expression { ';' } (
statement_group | definition_group ) } [COMPILE ELSE { ';' } (
statement_group | definition_group ) ] COMPILE ENDIF
ΓòÉΓòÉΓòÉ 8.2.5. formal_decl_group ΓòÉΓòÉΓòÉ
formal_decl_group ::= formal_declaration { {';'} [','] {';'}
formal_declaration }
ΓòÉΓòÉΓòÉ 8.2.6. formal_declaration ΓòÉΓòÉΓòÉ
formal_declaration ::= [VAR] identifier
ΓòÉΓòÉΓòÉ 8.2.7. const_decl_group ΓòÉΓòÉΓòÉ
const_decl_group ::= { constant_declaration {';'} (';' | ',') {';'} }
ΓòÉΓòÉΓòÉ 8.2.8. constant_declaration ΓòÉΓòÉΓòÉ
constant_declaration ::= identifier '=' expression
ΓòÉΓòÉΓòÉ 8.2.9. global_decl_group ΓòÉΓòÉΓòÉ
global_decl_group ::= {global_declaration {';'} }
ΓòÉΓòÉΓòÉ 8.2.10. global_declaration ΓòÉΓòÉΓòÉ
global_declaration ::= UNIVERSAL {';'} identifier ['*'] {';'} {',' {';'}
identifier }
ΓòÉΓòÉΓòÉ 8.2.11. keyname ΓòÉΓòÉΓòÉ
keyname ::= " ' " printable_char " ' "
| " ' " printable_char " ' " '-' " ' "printable_char " ' "
Although ETPM will accept all key definitions, some may seem not to take effect
because PM intercepts these keys before EPM sees them. For a list of these keys
see PM Keys.
| 'backspace'
| 'keydown'
| 'keyend'
| 'keyenter'
| 'keyleft'
| 'keyright'
| 'keytab'
| 'keyup'
| 'space'
| 'del'
| 'end'
| 'tab'
| 'up'
| 'enter'
| 'entry'
| 'esc'
| 'f1'..'f12'
| 'down'
| 'home'
| 'ins'
| 'left'
| 'pgdn'
| 'pagedown'
| 'pgup'
| 'pageup'
| 'right'
| 'padenter'
| 'pad_enter'
| 's_f1'..'s_f12'
| 's_tab'
| 's_backspace'
| 's_enter'
| 's_esc'
| 's_pgup'
| 's_pageup'
| 's_pgdn'
| 's_pagedown'
| 's_end'
| 's_home'
| 's_left'
| 's_up'
| 's_right'
| 's_down'
| 's_ins'
| 's_del'
| 's_padenter'
| 's_space
| 'a_0'..'a_9'
| 'a_a'..'a_z'
| 'a_f1'..'a_f12'
| 'a_enter'
| 'a_padenter'
| 'a_backspace'
| 'a_space'
| 'a_minus'
| 'a_equal'
| 'a_leftbracket'
| 'a_rightbracket'
| 'a_tab'
| 'a_quote'
| 'a_comma'
| 'a_period'
| 'a_slash'
| 'a_semicolon'
| 'a_backslash'
| 'c_0'..'c_9'
| 'c_a'..'c_z'
| 'c_f1'..'c_f12'
| 'c_backslash'
| 'c_backspace'
| 'c_keyenter'
| 'c_pagdown'
| 'c_pgdn'
| 'c_pageup'
| 'c_pgup'
| 'c_space'
| 'c_quote'
| 'c_comma'
| 'c_period'
| 'c_slash'
| 'c_semicolon'
| 'c_equal'
| 'c_del'
| 'c_down'
| 'c_end'
| 'c_enter'
| 'c_home'
| 'c_ins'
| 'c_left'
| 'c_leftbracket'
| 'c_minus'
| 'c_prtsc'
| 'c_right'
| 'c_rightbracket'
| 'c_tab'
| 'c_up'
| 'c_padenter'
| 'c_pad_enter'
| 'otherkeys'
| 'other_keys'
ΓòÉΓòÉΓòÉ 8.2.12. statement_group ΓòÉΓòÉΓòÉ
statement_group ::= { {';'} statement ';' {';'} }
ΓòÉΓòÉΓòÉ 8.2.13. statement ΓòÉΓòÉΓòÉ
statement ::= assignment_statement
| built-in_statement
| conditional_statement
| parse_statement
| compiler_directive
| procedure_call
| " ' "command" ' " All commands used in an E program must be quoted, e.g.
if new=0 then 'edit'
ΓòÉΓòÉΓòÉ 8.2.14. assignment_statement ΓòÉΓòÉΓòÉ
assignment_statement ::= designator '=' expression
ΓòÉΓòÉΓòÉ 8.2.15. designator ΓòÉΓòÉΓòÉ
designator ::= identifier
| identifier '.' field
| '.' field
| built-in_universal_variable
ΓòÉΓòÉΓòÉ 8.2.16. field ΓòÉΓòÉΓòÉ
field ::= 'autosave'
| 'autoshell'
| 'col'
| 'cursorx'
| 'cursory'
| 'dragcolor'
| 'dragstyle'
| 'filename'
| 'font'
| 'fontheight'
| 'fontwidth'
| 'keyset'
| 'last'
| 'line'
| 'lineg'
| 'lockhandle'
| 'margins'
| 'markcolor'
| 'messagecolor'
| 'modify'
| 'mousex'
| 'mousey'
| 'statuscolor'
| 'tabs'
| 'textcolor'
| 'userstring'
| 'visible'
| 'windowheight'
| 'windowwidth'
| 'windowx'
| 'windowy'
ΓòÉΓòÉΓòÉ 8.2.17. built-in_universal_variable ΓòÉΓòÉΓòÉ
built-in_universal_variable ::= CENTER_SEARCH
| JOIN_AFTER_WRAP
| RC
| EXIT_AFTER_LAST_FILE
| TWO_SPACES
ΓòÉΓòÉΓòÉ 8.2.18. built-in_statement ΓòÉΓòÉΓòÉ
built-in_statement ::= See individual statement.
ΓòÉΓòÉΓòÉ 8.2.19. conditional_statement ΓòÉΓòÉΓòÉ
conditional_statement ::= DO i=expression TO expression [BY expression]
statement_group [LEAVE] [ITERATE] statement_group (END | ENDDO)
| DO FOREVER statement_group [LEAVE] [ITERATE] statement_group (END |
ENDDO)
| DO WHILE expression statement_group [LEAVE] [ITERATE] statement_group
(END | ENDDO)
| FOR i=expression TO expression [BY expression] statement_group [LEAVE]
[ITERATE] statement_group ENDFOR
| IF expression { ';' } THEN statement_group {ELSEIF expression { ';' } THEN
statement_group} [ELSE statement_group] { ';' } ENDIF
| LOOP statement_group [LEAVE] [ITERATE] statement_group ENDLOOP
| WHILE expression { ';' } DO statement_group [LEAVE] [ITERATE]
statement_group ENDWHILE
ΓòÉΓòÉΓòÉ 8.2.20. parse_statement ΓòÉΓòÉΓòÉ
parse_statement ::= PARSE ARG {string | +number | -number |number |
identifier }
| PARSE VALUE expression WITH {string | +number | -number |number |
identifier }
ΓòÉΓòÉΓòÉ 8.2.21. expression ΓòÉΓòÉΓòÉ
expression ::= simple_expression [relation simple_expression]
ΓòÉΓòÉΓòÉ 8.2.22. simple_expression ΓòÉΓòÉΓòÉ
simple_expression ::= term {operator term}
ΓòÉΓòÉΓòÉ 8.2.23. term ΓòÉΓòÉΓòÉ
term ::= numeric_term
| string
| unary_operator term
| '(' expression ')'
ΓòÉΓòÉΓòÉ 8.2.24. arithmetic_expression ΓòÉΓòÉΓòÉ
arithmetic_expression ::= arithmetic_term {arithmetic_operator
arithmetic_term}
ΓòÉΓòÉΓòÉ 8.2.25. arithmetic_term ΓòÉΓòÉΓòÉ
arithmetic_term ::= '('arithmetic_expression')'
| number
| hex_number
| octal_number
| [numeric_unary_operator] arithmetic_term
ΓòÉΓòÉΓòÉ 8.2.26. numeric_expression ΓòÉΓòÉΓòÉ
numeric_expression ::= numeric_term {numeric_operator numeric_term}
ΓòÉΓòÉΓòÉ 8.2.27. numeric_term ΓòÉΓòÉΓòÉ
numeric_term ::= number
| designator
| '('numeric_expression')'
| procedure_call
| numeric_unary_operator numeric_term
ΓòÉΓòÉΓòÉ 8.2.28. string_expression ΓòÉΓòÉΓòÉ
string_expression ::= string
| designator
| procedure_call
ΓòÉΓòÉΓòÉ 8.2.29. constant_expression ΓòÉΓòÉΓòÉ
constant_expression ::= simple_constant_expression [ relation
simple_constant_expression ]
ΓòÉΓòÉΓòÉ 8.2.30. simple_constant_expression ΓòÉΓòÉΓòÉ
simple_constant_expression ::= constant_term { operator constant_term }
ΓòÉΓòÉΓòÉ 8.2.31. constant_term ΓòÉΓòÉΓòÉ
constant_term ::= number
| designator
| '('simple_constant_expression')'
| unary_operator constant_term
| string
ΓòÉΓòÉΓòÉ 8.2.32. relation ΓòÉΓòÉΓòÉ
relation ::= '=='
| '/=='
| '='
| '<>'
| '<='
| '>='
| '<'
| '>'
ΓòÉΓòÉΓòÉ 8.2.33. operator ΓòÉΓòÉΓòÉ
operator ::= numeric_operator
| AND
| '&'
| OR
| '|'
| '||'
| spaces
ΓòÉΓòÉΓòÉ 8.2.34. spaces ΓòÉΓòÉΓòÉ
spaces ::= (' '|'\t') spaces
ΓòÉΓòÉΓòÉ 8.2.35. numeric_operator ΓòÉΓòÉΓòÉ
numeric_operator ::= arithmetic_operator
| '//'
| '%'
ΓòÉΓòÉΓòÉ 8.2.36. arithmetic_operator ΓòÉΓòÉΓòÉ
arithmetic_operator ::= '+'
| '-'
| '*'
| '/'
ΓòÉΓòÉΓòÉ 8.2.37. unary_operator ΓòÉΓòÉΓòÉ
unary_operator ::= NOT
| numeric_unary_operator
ΓòÉΓòÉΓòÉ 8.2.38. numeric_unary_operator ΓòÉΓòÉΓòÉ
numeric_unary_operator ::= '+'
| '-'
ΓòÉΓòÉΓòÉ 8.2.39. procedure_call ΓòÉΓòÉΓòÉ
procedure_call ::= user_defined_proc_call
| built-in_proc_call
ΓòÉΓòÉΓòÉ 8.2.40. user_defined_proc_call ΓòÉΓòÉΓòÉ
user_defined_proc_call ::= identifier '(' [expression_list] ')'
ΓòÉΓòÉΓòÉ 8.2.41. built-in_proc_call ΓòÉΓòÉΓòÉ
built-in_proc_call ::= See individual procedure.
ΓòÉΓòÉΓòÉ 8.2.42. command ΓòÉΓòÉΓòÉ
command ::= macro-defined_command
| internal_command
| dos_command
ΓòÉΓòÉΓòÉ 8.2.43. internal_command ΓòÉΓòÉΓòÉ
internal_command ::= NUMBER
| '+' [number]
| '-' [number]
| 'C/' unquoted_string '/' unquoted_string '/' ['-'] ['+'] ['*'] ['m'] ['a']
['c'] ['e'] ['r'] ['f'] ['g']
| ( 'E' | 'ED' | 'EDIT' ) {['/d'] ['/e'] ['/n'] ['='] unquoted_string}
[quoted_string]
| ( 'F' | 'FILE' ) ['/t'] [unquoted_string]
| ( 'L/' | '/' ) unquoted_string '/' unquoted_string'/' ['-'] ['+'] ['m'] ['a']
['c'] ['e'] ['r'] ['f'] ['g']
| ( 'MA' | 'MARGINS' ) [number_list3]
| ( 'N' | 'NAME' ) [unquoted_string]
| ( 'O' | 'OPEN' ) {[ options ] filespec }
| 'OS2' string_expression
| ( 'Q' | 'QUIT' )
| ( 'S' | 'SAVE' ) ['/t'] [unquoted_string]
| 'TABS' number_list3
| 'VER'
| 'XCOM' internal_command
ΓòÉΓòÉΓòÉ 8.2.44. macro-defined_command ΓòÉΓòÉΓòÉ
macro-defined_command ::= 'ADD'
| 'ALL' '/' searchstring ['/'][c]
| ( 'APPEND' | 'APP' ) [unquoted_string]
| 'ASC' ( character )
| 'AUTOSAVE' [ ( number | 'on' | 'off') ]
| 'AUTOSAVEDLG'
| 'AUTOSHELL' ( ['0' | '1' ] )
| ( 'BOTTOM' | 'BOT' )
| 'BOX' ('1' | '2' | '3' | '4' | '5' | '6' | 'C' | 'P' | 'A' | 'E' | 'R' |
'/'character)
| 'BROWSE' ( ['ON' | 'OFF' | '?'] )
| 'CD' [unquoted_string]
| ( 'CHANGE' | 'C' ) '/' find_text '/' replace_text ['/' [-] [+] [*] [M] [A]
[C] [E] [R] [F] [G] ]
| 'CHANGEDLG'
| 'CENTER'
| 'CHR' number
| 'CLOSE'
| 'COMMANDLINE [ string_expression ]
| 'CUT'
| 'DIR' [ path ]
| 'DOLINES'
| 'DPATH'
| 'DRAW' ('1' | '2' | '3' | '4' | '5' | '6' | 'B' | '/'character)
| 'ECHO' ('on' | 'off')
| ( 'ETPM' | 'ET' ) ['/e' unquoted_string] ['/u']
[unquoted_string [unquoted_string] ]
| 'EXPAND' ['on' | 'off']
| 'FILL' character
| 'FINDDLG'
| ( 'FINDFILE' | 'FILEFIND' ) unquoted_string
| 'GET' unquoted_string
| 'HELP'
| 'KEY' ( number ' ' character )
| 'LINK' ( filespec )
| 'LIST' [unquoted_string]
| 'LOCK' ( [ filespec ] )
| 'LOOPKEY' ( number | 'all' )
| 'LOWERCASE'
| 'MARGINSDLG'
| 'MARKWORD'
| 'MATCHTAB' ['on' | 'off']
| 'MATH' arithmetic_expression
| 'MATHO' arithmetic_expression
| 'MATHX' arithmetic_expression
| 'MESSAGEBOX'
| 'MULT'
| 'OPENDLG'
| 'PASTE'
| 'PATH'
| 'PRINT' [ printer_name ]
| 'PROCESSBREAK'
| 'PROOF'
| 'PROOFWORD'
| 'PUT' [unquoted_string]
| 'QCONTROL' idnum
| ( 'QDATE' | 'QD' )
| ( 'QL' | 'QLINK' | 'QLINKED' )
| ( 'QUIETSHELL' | 'QS' )
| ( 'QTIME' | 'QT' )
| 'RC' command
| 'RELINK' [ filename ]
| 'SET'
| 'SETSCROLLS'
| ( 'SORT' | 'SORTDLL' ) [ 'R' ] [ 'C' ]
| 'STAY' ( 'ON' | 'OFF' )
| 'STDFILE_READ'
| 'STDFILE_WRITE'
| 'TABS' { numeric_expression }
| 'TOGGLECONTROL' numeric_expression [, '0' | '1' ]
| 'TOGGLEFONT'
| 'TOP'
| 'UNLINK' [ filespec ]
| 'UNLOCK' filespec
| 'UPPERCASE'
| 'VOL'
ΓòÉΓòÉΓòÉ 8.2.45. dos_command ΓòÉΓòÉΓòÉ
dos_command ::= Any command recognized and interpreted by the current
operating system, whether that is DOS or OS/2.
ΓòÉΓòÉΓòÉ 8.2.46. expression_list ΓòÉΓòÉΓòÉ
expression_list ::= expression { {';'} [','] {';'} expression }
ΓòÉΓòÉΓòÉ 8.2.47. identifier ΓòÉΓòÉΓòÉ
identifier ::= letter {letter | digit | '_' }
ΓòÉΓòÉΓòÉ 8.2.48. identifier_list ΓòÉΓòÉΓòÉ
identifier_list ::= identifier [spaces identifier [spaces identifier [spaces
identifier . . . ] ] ]
ΓòÉΓòÉΓòÉ 8.2.49. unquoted_string ΓòÉΓòÉΓòÉ
unquoted_string ::= {character}
ΓòÉΓòÉΓòÉ 8.2.50. string ΓòÉΓòÉΓòÉ
string ::= " ' " {character} " ' "
| ' " ' {character} ' " '
| esc_code
ΓòÉΓòÉΓòÉ 8.2.51. letter ΓòÉΓòÉΓòÉ
letter ::= 'a' .. 'z' | 'A' .. 'Z'
ΓòÉΓòÉΓòÉ 8.2.52. character ΓòÉΓòÉΓòÉ
character ::= any character whose ASCII value is between 0 and 255
ΓòÉΓòÉΓòÉ 8.2.53. printable_char ΓòÉΓòÉΓòÉ
printable_char ::= any character whose ASCII value is between 0 and 255
ΓòÉΓòÉΓòÉ 8.2.54. esc_code ΓòÉΓòÉΓòÉ
esc_code ::= '\' ('n' | 't' | 'b' | 'r' | 'f')
| '\' digit [digit [digit] ]
| '\'x hex_digit [hex_digit]
ΓòÉΓòÉΓòÉ 8.2.55. hex_number ΓòÉΓòÉΓòÉ
hex_number ::= 'x'hex_digit {hex_digit}
ΓòÉΓòÉΓòÉ 8.2.56. octal_number ΓòÉΓòÉΓòÉ
octal_number ::= 'o'octal_digit {octal_digit}
ΓòÉΓòÉΓòÉ 8.2.57. octal_digit ΓòÉΓòÉΓòÉ
octal_digit ::= '0'..'7'
ΓòÉΓòÉΓòÉ 8.2.58. hex_digit ΓòÉΓòÉΓòÉ
hexdigit ::= (number | 'a' .. 'f' | 'A' .. 'F' )
ΓòÉΓòÉΓòÉ 8.2.59. number ΓòÉΓòÉΓòÉ
number ::= digit{digit}
ΓòÉΓòÉΓòÉ 8.2.60. digit ΓòÉΓòÉΓòÉ
digit ::= '0' .. '9'
ΓòÉΓòÉΓòÉ 8.2.61. number_list2 ΓòÉΓòÉΓòÉ
number_list2 ::= number [spaces number]
ΓòÉΓòÉΓòÉ 8.2.62. number_list3 ΓòÉΓòÉΓòÉ
number_list3 ::= number [spaces number [ spaces number] ]
ΓòÉΓòÉΓòÉ 8.2.63. number_list4 ΓòÉΓòÉΓòÉ
number_list4 ::= number [spaces number [ spaces number [spaces number] ]
]
ΓòÉΓòÉΓòÉ 9. Summary of Keywords, Procedures, Variables, and Keys ΓòÉΓòÉΓòÉ
Summary of keywords, procedures, variables and keys.
ΓòÉΓòÉΓòÉ 9.1. Built-in Statement and Procedure Summary ΓòÉΓòÉΓòÉ
In this section all of E's internal procedure and statements are listed
followed by a brief description. See Built-in Statements and Procedures for
more complete descriptions and parameters. Procedures are followed by
parentheses and can return values. Statements have no parentheses, return
nothing, and generally perform some operation on the screen. Both statements
and procedures can be followed by arguments. Procedure arguments must appear
within the parentheses.
ABBREV()
returns 1 if one string is an abbreviation of another
ACTIVATEFILE
makes a file the current file
ADDRESS()
returns the address of a variable
ADJUSTBLOCK
moves a marked area by overlaying
ADJUST_BLOCK
same as ADJUSTBLOCK
ADJUSTMARK
same as ADJUSTBLOCK for any marked type
ADJUST_MARK
same as ADJUSTMARK
ARG()
returns an argument
ASC()
determins an ASCII value
ATOI()
converts a string to integer
ATOL()
converts a string to a long integer
ATTRIBUTE_ACTION
does an attribute action
BACKTAB
moves cursor to previous tab
BACKTABWORD
moves cursor to beginning of last word
BACKTAB_WORD
same as BACKTABWORD
BEEP()
emits a noise
BEGINLINE
moves cursor to beginning of line
BEGIN_LINE
same as BEGINLINE
BOT
goes to the bottom of the file
BOTTOM
same as BOT
BEGINLINE
moves cursor to beginning of the line
BEGIN_LINE
same as BEGIN_LINE
BINSEARCH()
perform a binary search in a file
BROWSE()
turns browse mode on/off
BUFFER()
allows shared buffers
BUILDMENUITEM
builds an action bar menu item
BUILDSUBMENU
builds an action bar sub menu item
CALL
executes a procedure
CENTER
centers a string in a given length field
CENTRE
centers a string in a given length field
CHR()
finds the character from an ASCII value
COMPARE
compares two strings; returns the character position of the
first difference
COPIES
returns n copies of the given string
COPYMARK
copies marked to text to the cursor pos.
COPY_MARK
same as COPYMARK
COUNT()
returns the number of occurrances of one string in another
C2X()
returns the printable hex representation of a binary string
DELETE
deletes the line the cursor is on
DELETECHAR
deletes the character under the cursor
DELETE_CHAR
same as DELETECHAR
DELETELINE
deletes a line of text
DELETEMARK
removes marked text
DELETE_MARK
same as DELETEMARK
DELETEMENU
removes an action bar menu item or subitem
DELSTR
deletes a substring of a string
DELWORD
deletes a phrase from a string
DIRECTORY( [path])
returns current directory; if path is given, changes
current directory first
DISPLAY
allows screen updating etc. to be toggled
DO
start of an iteration routine
DO_ARRAY
handles arrays in E
DO_OVERLAYWINDOWS
is undisclosed
DOWN
moves the cursor down a line
DYNAFREE()
releases a dynalink library
DYNALINK()
allows PM calls thru C code
DYNALINKC()
same as DYNALINK but in C format
DYNALINK32()
same as DYNALINKC but for calling 32-bit code
ECHO()
performs a command execution trace
ENDLINE
moves the cursor to the end of line
END_LINE
same as ENDLINE
ERASEENDLINE
erases text to the end of line
ERASE_END_LINE
same as ERASEENDLINE
EXECUTE
executes the command dialog box
EXECUTEKEY
executes the key specified
EXIT
exits from the current macro
FILECOMPARE
compares two files in the ring
FILESINRING
returns the number of files in the ring
FILESIZE
returns the sum of the lengths of all lines in the file
FILLMARK
fills the marked area
FILL_MARK
same as FILLMARK
FINDFILE
finds a file path
FOR
begining of an iterative loop
GETFILEID
gets a file id number
GETKEYSTATE()
gets the shift state of keys
GET_KEY_STATE
same as GETKEYSTATE
GETLINE
returns the current text line
GETMARK
gets the type of mark
GETPMINFO()
returns PM information
GETSEARCH
saves the last search string
GET_SEARCH
same as SETSEARCH
HEX()
returns the hex value of a char.
IF - THEN - ELSE
the beginning of a conditional stmt.
INCLUDE
includes another E file
INSERT
inserts a blank line
INSERT_ATTRIBUTE
inserts an attribute
INSERTLINE
inserts a line at a specified location
INSERTSTATE()
returns insert/replace mode
INSERT_STATE()
same as INSERTSTATE()
INSERTSTR
inserts a string into another string
INSERTTOGGLE
toggles the insert/replace modes
INSERT_TOGGLE
same as INSERTTOGGLE
ISADEFC()
tells if a given command has been defined
ISADEFPROC()
tells if a given procedure has been defined
ISADIRTYLINE()
tells if the current line has been modified and not yet
"checked in"
ITERATE
part of a repeat loop
ITOA()
converts a integer to string
JOIN
joins two lines
KEY
executes the key specified
KEYIN
enters text into the file
KEYS
actives a keyset name
LASTERROR()
returns the last error code
LAST_ERROR()
same as LASTERROR
LASTKEY()
returns the last key hit
LASTPOS()
finds text in the file
LEAVE
leaves a repetitive loop
LEFT
moves the cursor one column left
LEFTSTR()
returns the leftmost n characters of a string
LENGTH()
retuns the length of a string
LEXAM()
access the dictionary functions
LINK
links an .EX module into EPM
LINKED()
returns if a module is linked
LONGESTLINE()
returns the length of the longest line in the file
LOOP
a iterative looping command
LOWCASE()
lowers the case on a string
LTOA()
converts a string to a long integer
MACHINE()
returns the type of Operating System
MARKBLOCK
issues a block-type mark
MARK_BLOCK
same as a MARKBLOCK
MARKCHAR
issues a character-type mark
MARK_CHAR
same as a MARKCHAR
MARKLINE
issues a line-type mark
MARK_LINE
same as a MARKLINE
MARKSIZE()
returns the number of marked characters
MARKTYPE()
returns the marktype set
MEMCPYX()
copies information from one memory location to another
MOUSE_SETPOINTER
sets the mouse pointer
MOVEMARK
moves marked text to the cursor pos.
MOVE_MARK
same as MOVEMARK
NEXTFILE
actives the next file in the ring
NEXT_FILE
same as NEXTFILE
OFFSET()
returns the offset in binary
OFS()
returns the offset in a string format
OVERLAY
allows the overlay of strings
OVERLAYBLOCK
copies marked text without inserting
OVERLAY_BLOCK
same as OVERLAY_BLOCK
PAGEDOWN
moves the cursor one page down
PAGE_DOWN
same as PAGEDOWN
PAGEUP
moves the cursor one page up
PAGE_UP
same as PAGEUP
PARSE
parses a string
PEEK()
looks up a memory location value
PEEK32()
looks up a memory location value
PEEKZ()
returns an ASCIIZ string from memory
PEEKZ32()
returns an ASCIIZ string from memory
POKE()
inserts a value into a memory location
POKE32()
inserts a value into a memory location
PREVFILE
moves to the previous file
QUERY_ATTRIBUTE
determines the attribute type set
QUERYMENUSTRING
get the command associated with an menu option
QUERYPROFILE()
gets a string from OS2.INI
QUIETSHELL
allows an OS/2 command to be executed
REFLOW
reformats text
REFRESH
updates the screen
REGEXPCOMP
pre-compiles an extended GREP search string into an EGREP
program.
REGEXPEXEC
does an EGREP search of a string, using a pre-compiled
program.
RELINK
compiles and links .E modules
REPEATFIND
finds the next occurrence of a search
REPEAT_FIND
same as REPEATFIND
REPLACELINE
replaces a line with new text
RETURN
returns an expression to the caller
REVERSE()
returns the reverse of a string
RIGHT
moves the cursor one column right
RIGHTSTR()
returns the rightmost n characters of a string
RUBOUT
deletes the character to the left
SAYAT
writes text at a location on the screen
SAY_AT
same as SAYAT
SAYERROR
displays an error code or a message
SAYERROR()
displays a message
SAYERRORTEXT()
returns the error message associated with a given error
code
SCREENHEIGHT()
returns the screen height
SCREENWIDTH()
returns the screen width
SEG()
returns the segment address as a string
SELECTOR()
returns the segment address in binary
SETPROFILE()
sets a string in OS2.INI
SETSEARCH
sets the search command string
SET_SEARCH
same as SETSEARCH
SHIFTLEFT
shifts marked text one position left
SHIFT_LEFT
same as SHIFTLEFT
SHIFTRIGHT
shifts marked text one position right
SHIFT_RIGHT
same as SHIFTRIGHT
SHOWMENU
displays a newly built action bar menu
SPLIT
splits a line of text into two lines
STOP
stops execution of a macro
STOPONRC
stops only if RC is non-zero
STOP_ON_RC
same as STOPONRC
STRIP()
strips away extra spaces
SUBSTR()
returns a sub-string from within a string
SUBWORD
returns a phrase from a string
TAB
moves to the next tab stop
TABGLYPH()
specifies whether the tab glyph should be displayed
TABWORD
moves to the beginning of the next word
TAB_WORD
same as TABWORD
TEXTLINE()
gets the contents of the indicated line
TOP
moves to the top of the file
TRANSLATE()
translates a string according to a given translate table
TRYINCLUDE
attempts to include a .E file
UNDO
undoes changes on a line
UNLINK
removes a .EX module from EPM
UNMARK
unmarks text
UP
moves the cursor up one key
UPCASE()
converts a string to upper case
VALIDATEFILEID()
verifies that a fileid is valid
VER()
returns the version number
VERIFY()
makes sure a string is valid in a set
WHEREDEFC()
tells in which .ex file a defc is defined
WINMESSAGEBOX()
does a Dynalink call to the PM WinMessageBox function
WORD()
returns the nthe word of a string
WORDINDEX()
returns the character position of a word in a string
WORDLENGTH()
returns the length of a word in a string
WORDPOS()
returns the position of a phrase in a string
WORDS()
returns the number of words in a string
WHILE
a conditional repetitive statement
ΓòÉΓòÉΓòÉ 9.2. Command Summary ΓòÉΓòÉΓòÉ
These commands can be issued from within the command line dialog box or from
within a program. When used within the E language they must be surrounded by
quotation marks. For example:
`CD'
or
`CD C:\EPM\FILES'
or
`CD` mypath
In the first example the macro command CD will be executed as if the user typed
it in on the command line dialog. In the second example CD was issued with an
argument. And in the third example, the argument was a variable name. For more
information on the commands and their syntax see The EPM User's Guide and
Commands Omitted From the User's Guide in this manual.
####
goes to line number ####
+ [####]
moves cursor forward #### lines.
- [####]
moves cursor backward #### lines.
/find_string/[options]
same as 'L' command
ACTIVATEFILEID
activates the file specified
ADD
adds a marked block of numbers
ALL
if included, it finds all occurrences of a given string in
the current file
APP
appends marked text to a file
APPEND
same as APP
ASC
determines the ASCII value of a char.
AUTOSAVE
sets the AUTOSAVE field value
AUTOSAVEDLG
brings up the AUTOSAVE dialog box
AUTOSHELL
turns AUTOSHELLing on or off
BOT
goes to the bottom of the file
BOTTOM
same as BOT
BOX
draws a box of specified style around block mark. (See
BOX.E)
BROWSE
make the file read-only or read-write
C
changes text strings
CD
changes the default drive/path
CENTER
centers marked text
CHANGE
same as C
CHANGEDLG
brings up the change dialog box
CHR
displays the character associated
CLEARSHARBUFF
clears the shared buffer
CLOSE
closes files in the ring
COMMANDLINE
brings up the command line dialog box
COPY2DMBUFF
copies marked area to "Delete Mark" buffer
COPY2SHARBUFF
copies marked area to shared buffer
CURSOROFF
turns the cursor off
CUT
moves marked text to the shared buffer
DIR
lists the directory in a temp. file
DOLINES
executes the current line or marked lines
DPATH
shows the DPATH setting
DRAW
enters draw mode
DUPMARK
executes a mark action specified
ECHO
turns command trace on
E
edit a file
ED
same as E
EDIT
same as E and ED
ET
invoke the compiler
ETPM
same as ET
EXPAND
turns syntax expansion on/off
F
saves and quit the current file
FILE
same as F
FILEFIND
attempts to find a file
FILL
fills the marked block with a character
FINDDLG
invokes the find dialog box
FINDFILE
same as FILEFIND
GET
gets the file into the current file
GETDMBUFF
gets text from the delete mark buffer
GETSHARBUFF
gets text from the shared buffer
HELP
brings up EPM help
KEY
allows the repeat of a key or macro
L
searches for text
LINK
links an .EX module into EPM
LIST
same as FILEFIND and FINDFILE
LOADDEFAULTMENU
loads the default action bar menu
LOCK
prevents other users from updating a file
LOOPKEY
repeats a key in a vertical direction
LOWERCASE
converts marked text into lowercase
MA
sets/displays the margin settings
MARGINS
same as MA
MARGINSDLG
brings up the margins dialog box
MARKWORD
marks the word under the mouse pointer
MATCHTAB
sets tab stops to the words in the line above
MATH
computes an expression in base 10
MATHO
computes an expression in base 8
MATHX
computes an expression in base 16
MESSAGEBOX
brings up the message review dialog box
MH_BEGIN_MARK
mouse handler begin mark
MH_CANCEL_MARK
mouse hander cancel mark
MH_END_MARK
mouse handler end mark
MH_GOTOPOSITION
mouse handler go to position
MULT
multiplies the numbers in a marked area
N
renames the current file
NAME
same as N
O
loads a file into a new window
OPEN
same as O
OPENDLG
brings up the OPEN dialog box
OS2
executes an OS/2 command
PASTE
copies text from the shared buffer
PATH
displays the path settings
PRINT
prints a marked area or whole file
PROCESSBREAK
stops a macro in progress
PROOF
initiates spell checking
PROOFWORD
spell checks the current word
PUT
writes the marked text to a file
QCONTROL
determines the status of windows
QD
returns the current date
QDATE
same as QD
QL
determines if a module is linked
QLINK
same as QL
QLINKED
same as QL and QLINK
QS
executes an OS/2 command w/ no results
QUIETSHELL
same as QS
QT
displays the time
QTIME
same as QT
Q
quits the current file
QUIT
same as Q
RC
returns the error code of a command
RELINK
compiles and links and E module
S
saves a file to disk
SAVE
same as S
SET
displays all SET parameters in a temp. file
SETSCROLLS
turns the scroll bars on/off
SORT
sorts marked text or the whole file
SORTDLL
same as SORT
STAY
sets whether to move on a find & replace
STDFILE_READ
reads in from standard input stream
STDFILE_WRITE
writes out the the standard output stream
TABS
sets the tabs stops
TOGGLECONTROL
toggles the window on/off
TOGGLEFONT
toggles between large/small fonts
TOP
goes to the top of the current file
UNLINK
removes an .EX module from EPM
UNLOCK
allows other users to update a file
UPPERCASE
makes text in a marked area uppercased
VER
displays the EPM version
VOL
displays the current drive's volume info
XCOM
executes a built in command
ΓòÉΓòÉΓòÉ 9.3. E Language Keywords ΓòÉΓòÉΓòÉ
AND
Boolean AND function. That is, a logical AND like REXX, not a
bit operator.
ARG
is used in parse constructs
BASE
is used in defkeys construct
BY
is used in loop constructs
CLEAR
is used in defkeys construct
COMPILE
conditional compilation instruction, followed by
IF/ELSE/ELSEIF/ENDIF
CONST
defines constants that the E translator uses during translation
of the E procs
DEF
defines a key or pseudo-key that belongs to the current keyset
DEFC
defines new commands
DEFINIT
allows initialization of variables for use by other E
procedures
DEFKEYS
names a keyset
DEFLOAD
is executed whenever a new file is loaded
DEFMAIN
allows the user to take control of the command dialog box
arguments of the editor
DEFMODIFY
is executed when .modify passes certain threshold values
DEFPROC
is used to define new procedures (functions)
DEFSELECT
is executed whenever you switch to a different file
DO
is used in loop constructs
ELSE
indicates action to take place when an IF statement proves
false
ELSEIF
executes a secondary IF when an IF statement proves false
END or ENDDO
is used in loop constructs, to terminate a DO block (DO WHILE,
DO (FOR), or DO FOREVER)
ENDFOR
is used in loop constructs
ENDIF
marks the end of an IF block
ENDLOOP
is used in loop constructs
ENDWHILE
is used in loop constructs
FOR
is used in loop constructs
FOREVER
is used in loop constructs
IF
changes the flow of statements depending upon a condition
INCLUDE
includes another file into the current file for compilation.
ITERATE
iterates a loop, while, or do
LEAVE
exits loop, while, or do
LOOP
is used in loop constructs
NEW
is used in defkeys construct
NOT
Boolean NOT function
OR
Boolean OR function
OVERLAY
is used in defkeys construct
PARSE
is used to extract information from a string
RETURN
returns from a defined procedure or command, with an
expression.
SAY
writes a line to terminal when shelled to OS/2
SAYS
writes a line to terminal when shelled to OS/2, no CR-LF
SET
defines configuration options. Only a few options are still
set in this way: cursors and insertstate.
THEN
indicates action to take place when an IF statement proves true
TO
is used in loop constructs
TRYINCLUDE
includes another file into the current file for compilation,
similar to INCLUDE, but does not stop compilation if the file
cannot be found.
UNIVERSAL
specifies that a variable is available to all procs, is not
local to the current one.
VALUE
is used in Parse constructs
VAR
is used in DEFPROC definitions. Specifies that the following
variable is passed by reference. If the procedure modifies the
variable its value is also changed in the caller. Otherwise
the caller's value for the variable is not modifiable by the
called procedure.
WHILE
is used in loop constructs
WITH
is used in Parse constructs
ΓòÉΓòÉΓòÉ 9.4. Field Attributes ΓòÉΓòÉΓòÉ
Field attributes are variables that are unique to each file. They can be
accessed by specifying the fileid and the attribute name separated by a period.
If the fileid is omitted, the current file is assumed. Some are able to be
assigned and all are able to be referenced. For example:
.line = 1
sayerror "The current line is: "||.line
tmpfileid.line = 1
The first is an assignment statement. The second is reference statement. In the
third a fileid (in the form of the variable tmpfileid) is used. For a more
complete description of field variables see Field Variables Listed. Valid field
variables are:
.AUTOSAVE
number of changes before autosaving
.AUTOSHELL
allow checking externally for commands not recognized
internally
.COL
the cursor column position
.CURSORX
the cursor x coordinate
.CURSORY
the cursor y coordinate
.DRAGCOLOR
the drag color
.DRAGSTYLE
the drag style
.FILENAME
the current file's filename
.FONT
the font id of the current file's font
.FONTHEIGHT
the font height
.FONTWIDTH
the font width
.KEYSET
the current active keyset
.LAST
the maximum file line number
.LINE
the cursor's line number
.LINEG
same as .LINE, but setting it doesn't cause scrolling
.LOCKHANDLE
determines if the file is LOCKed
.MARGINS
contains the margin settings
.MARKCOLOR
contains the mark color
.MESSAGECOLOR
contains the message color
.MODIFY
the number of modifications made
.MOUSEX
the mouse's x coordinate
.MOUSEY
the mouse's y coordinate
.STATUSCOLOR
the status bar color
.TABS
the tab settings
.TEXTCOLOR
the text color
.USERSTRING
a user definable variable
.VISIBLE
determines if the file is visible
.WINDOWHEIGHT
contains the window height
.WINDOWWIDTH
contains the window width
.WINDOWX
the window x coordinate
.WINDOWY
the window y coordinate
ΓòÉΓòÉΓòÉ 9.5. E-Definable Keys ΓòÉΓòÉΓòÉ
The following keys may be defined using E. In all cases, the prefix A_ means
that the Alt key must be depressed at the same time as the key to get the
desired function. Similarly, the prefix C_ means the Ctrl key must be used,
and S_ means the shift key must be used. For information on the format of
defining these keys, refer to section Key Definitions (DEF and DEFKEYS) or E
Language Syntax.
A - Z
A_A - A_Z
A_EQUAL
A_F1 - A_F12
A_LEFTBRACKET
A_MINUS
A_RIGHTBRACKET
A_TAB
A_0 - A_9
BACKSPACE
C_A - C_Z
C_BACKSLASH
C_BACKSPACE
C_DEL
C_DOWN
C_END
C_ENTER
C_F1 - C_F10
C_HOME
C_INS
C_LEFT
C_LEFTBRACKET
C_MINUS
C_PGDN
C_PGUP
C_PRTSC
C_RIGHT
C_RIGHTBRACKET
C_TAB
C_UP
C_2, C_6
DEL
DOWN
END
ENTER
ESC
F1 - F10
HOME
INS
LEFT
PGDN
PGUP
RIGHT
S_F1 - S_F10
S_PAD5
S_TAB
TAB
UP
any printable character whose ASCII value is 0 to 255.
The following name may be defined in the same manner as keys, but is used as a
pseudo-key:
ENTRY
The following keys are available only on enhanced keyboards, which come with
the PS/2 and AT models:
A_ENTER
A_F11, A_F12
A_PADENTER
C_F11, C_F12
C_PADENTER
F11, F12
PADENTER
S_F11, S_F12
ΓòÉΓòÉΓòÉ 9.5.1. PM Keys ΓòÉΓòÉΓòÉ
The keys listed below are used be Presentation Manager to accomplish certain
functions standard to all PM applications (set by CUA standards). To maintain
consistency between PM applications, these keys cannot be redefined.
Key PM Function
F1
Help
F10
Goto action bar.
A_F7
Move a PM window.
A_F8
Size a PM window.
A_F9
Minimize a PM window.
A_F10
Maximize a PM window.
A_Esc
Switch application.
C_Esc
Goto Task List.
ΓòÉΓòÉΓòÉ 10. General Structure of E-Macro Files ΓòÉΓòÉΓòÉ
ALL.E Procedure for including the ALL command and the ctrl-Q key
setup for paging between ALL occurrences. This file is
only included if the configuration constant WANT_ALL is
TRUE.
ASSIST.E Procedure for including the bracket-matching code. This
file is only included if the configuration constant
WANT_BRACKET_MATCHING is TRUE.
BOOKMARK.E Procedures for working with bookmarks, and for loading and
saving EPM attributes as an Extended Attribute associated
with the file. This file is only included if the
configuration constant WANT_BOOKMARKS is TRUE.
BOX.E Procedure for the BOX command. This is compiled separately
into a BOX.EX file. The file is loaded when the user issues
a BOX command. When the command finished, BOX is unlinked
from EPM, thereby saving memory space.
BUFF.E Test procedures for the buffer() opcode.
CALLREXX.E Procedures for calling Rexx macros. This file is only
included if the configuration constant WANT_REXX is TRUE.
CHAROPS.E Procedures for block fill, copy, delete and mark, for
character-marked text.
CKEYS.E Syntax aids for C files.
CKEYSEL.E A small file which selects the C keyset. This is a
separate file to allow easy omission of the
syntax-expansion feature by erasing CKEYS*.E. Only used
for E3, not for EPM - as of version 4.12, this file is no
longer needed. The selection of the keyset is done in
CKEYS.E where the keyset is defined. This is made possible
by the new DEFLOAD feature. Similarly, EKEYSEL.E and
PKEYSEL.E are unnecessary.
CLIPBRD.E Contains procedures and commands that:
o allow a user to pass lines of text between edit windows
o allow text to be placed in the PM clipboard.
COLORS.E Defines default colors.
DOSUTIL.E Procedures interfacing to the operating system.
Note: No longer used under OS/2.
DRAW.E Includes the procedures for the DRAW command. This is
compiled separately into a DRAW.EX file. The file is loaded
when the user issues a DRAW command. The code is then
unlinked when the DRAW command is finished.
DRAWKEY.E Includes the key definition for F6 to trigger the draw
command.
DYNATEST.E An example program showing how to program in E using the
DYNALINK command.
E.E The main file containing all the include statements that
create EPM. Do not compile this module, however. Compile
the EPM.E file.
E3EMUL.E Includes the procedures and commands to enable E3EMUL host
support. See The EPM User's Guide for more information on
the E3EMUL package support.
EKEYS.E Key definitions for E syntax support.
EKEYSEL.E See CKEYSEL.E.
ENGLISH.E The file containing all the text strings used by the
macros. This file is only included if the configuration
constant NLS_LANGUAGE = 'ENGLISH'. Other NLS translations
exist, but are owned by Boca.
EPM.E The main file for compilation. See The EPM User's Guide for
information on compiling this file.
EPMDBCS.E Procedures related to DBCS support. This file is only
included if the configuration constant WANT_DBCS is TRUE.
EPMGCNF.SMP This is a copy of the MYCNF.E used to compile the *.ex
files shipped externally.
EPMLEX.E Includes spell checking and synonym support for the EPM
editor. This file is only included if the configuration
constant SPELL_SUPPORT = 1. Can also be compiled
separately and linked in.
EPMSHELL.E Procedures related to EPM's Shell support. This file is
only included if the configuration constant WANT_EPM_SHELL
is TRUE.
EPM_EA.E Procedures dealing with extended attributes.
EXIT.E Asks the user if he really wants to leave EOS2. No longer
used in EPM.
EXTRA.E A file used to split some of the function out of EPM.EX
when it grew above 64k, before EPM 6.00 supported larger
.ex files. See EXTRA_EX in The EPM User's Guide.
FEVSHMNU.E An alternate to STDMENU.E that implements the "FEVSH" menu
style of OS/2 Warp. Used only if the configuration
constant STD_MENU_NAME = "FEVSHMNU.E", this should only be
used in EPM 6.00 or above, as it doesn't have an Options
menu. The newer settings notebook of EPM 6 allows the user
to select most of the settings which would otherwise be
lost.
GET.E Procedures for the GET command. This is an external package
created to save memory space. When the user issues a GET
command, EPM loads the GET.EX file. Once the GET command is
completed, GET will unlink itself from memory to free up
memory space.
HELP.E Procedure for the HELP command. This is an external package
created to save memory space. When the user issues a HELP
command, EPM loads the HELP.EX file. Once the user has
finished viewing the EPMHELP.HLP file, HELP automatically
unlinks itself from memory to free up memory space.
KWHELP.E Procedures related to EPM's keyword help feature. This
file is only included if the configuration constant
WANT_KEYWORD_HELP is TRUE.
LINKCMDS.E Contains procedures and commands related to the linking of
editor modules (ie. LINK, ETPM, RELINK and UNLINK).
LOAD.E This file contains the default DEFLOAD procedure.
MAIN.E Contains the DEFMAIN procedure, which is where E begins
execution after all DEFINITs. Processes the OS/2 command
line.
MAKETAGS.E Procedures for the MAKETAGS command. This is normally
compiled to an external MAKETAGS.EX file rather than
included in the base .ex files.
MARKFILT.E Defines procedures to extract and replace strings from
marked text.
MATH.E Definitions for ADD and MULT commands. Also refer to the
file MATHLIB.E for more math command definitions.
MATHLIB.E An extension of MATH.E created for EOS/2 to allow the
components to compile only if needed. See MATH.E for more
math command definitions.
MENUHELP.H Contains definitions of the help panel IDs. This file is
shared between the macros and the help file source.
MODIFY.E This file contains the procedures and commands executed
when a DEMODIFY event is triggered. The DEMODIFY event
occurs when a file's number of modifications (.modify):
o goes from zero to nonzero (first modification, so we can change the
textcolor or title to indicate that the file needs to be saved;
o goes from nonzero to zero (so we can return to the safe textcolor, usually
after a save);
o goes from less than .autosave to greater than or equal to .autosave.
The DEMODIFY.E file is new as of EPM.
MOUSE.E Contains the commands and procedures associated with the
MOUSE movements and actions. This file is new as of EPM.
OS2TOOLS.CFG This is a copy of the MYCNF.E used to compile the *.ex
files shipped internally to IBM.
OVSHMENU.E An alternate to STDMENU.E that implements the proposed
"OVSH" menu style. Used only if the configuration constant
STD_MENU_NAME = "OVSHMENU.E", this should only be used in
EPM 6.00 or above. (See comments under FEVSHMNU.E.)
PKEYS.E Syntax aids for Pascal files.
PKEYSEL.E See CKEYSEL.E.
PUT.E Contains the procedures and statements for the PUT command.
This was made an external module to save space.
RETREIVE.E Used to retrieve commands from a hidden file in E3. This
file is no longer used under EPM.
REXXKEYS.E Syntax aids for Rexx command files.
RKEYSEL.E See CKEYSEL.E.
SAVELOAD.E Things common to loading and saving files (host file
support).
SELECT.E Contains the procedure select_edit_keys() which selects
options (like keysets) whenever you switch to a new file.
SHELL.E Presents an E interface to the internal shell command.
SLNOHOST.E Substitute for SAVELOAD.E, without host file support.
SMALL.E A version of E.E with several features removed to save
memory.
SORTDLL.E Provides the link between the E's SORT command and the
QISRTMEM sort DLL.
SORTE.E Definitions for the sorting using the E language.
SORTEPM.E Definitions for the sorting using the EPM 5.60 or above
internal sort.
STDCMDS.E Definitions of standard E commands.
STDCNF.E Mode settings and default values for the standard E
configuration.
STDCONST.E Contains EPM's standard constants.
STDCTRL.E Adds LISTBOX and MENU support. Routines to interface with
EPM and PM controls are defined here.
STDKEYS.E Standard E command-key definitions.
STDMENU.E The default action bar is defined here.
STDPROCS.E Standard procedural support for other files.
TAGS.E Procedures related to EPM's tags file support. This file
is only included if the configuration constant WANT_TAGS =
1. It can also be linked dynamically.
WINDOW.E Definitions for tiled window support. No longer used in
EPM.
ΓòÉΓòÉΓòÉ 11. Descriptions of Procedures in Standard EPM ΓòÉΓòÉΓòÉ
This section lists in alphabetical order all of the procedures in the *.E files
and gives a brief description of how they function and what they are used for.
For more detailed information, please study the comments in the .E code itself.
ΓòÉΓòÉΓòÉ 11.1. ALREADY_IN_RING(filename, var tryid) ΓòÉΓòÉΓòÉ
Attempts to find the filename in the current ring. If successful tryid returns
the file id for the filename. This function returns a one if the filename is in
the ring and a zero if not.
ΓòÉΓòÉΓòÉ 11.2. APPEND_PATH(filename) ΓòÉΓòÉΓòÉ
For use with DOS 3.30 or higher: searches the path listed in the APPEND path
string for filename and returns the path (ended by a trailing backslash) where
it was found; otherwise it returns null. Only included if requested with the
USE_APPEND configuration constant.
ΓòÉΓòÉΓòÉ 11.3. ASKYESNO() ΓòÉΓòÉΓòÉ
Displays the message: 'Are you sure (Y/N)' and returns an uppercase keystroke
to the caller. If called with a string parameter, the string is displayed
before the message: 'Are you sure (Y/N)'. An optional second argument is a flag
to prevent the 'Are you sure (Y/N)' message from appearing. For example:
usersays = askyesno("About to erase")
The user's response would be placed in the variable usersays.
ΓòÉΓòÉΓòÉ 11.4. BEEP(pitch,duration) ΓòÉΓòÉΓòÉ
Emits a tone of pitch (range 25Hz - 7FFFHz) and a duration of duration in
milliseconds.
ΓòÉΓòÉΓòÉ 11.5. BREAKOUT_MVS(filename,lastqual) ΓòÉΓòÉΓòÉ
Breaks out a filetype from a MVS filename. PASCAL will return PAS and C will
return C. Only included if requested with HOST_SUPPORT.
ΓòÉΓòÉΓòÉ 11.6. CHECK_FOR_HOST_FILE() ΓòÉΓòÉΓòÉ
Parses arg(1) in the host filename form: fname ftype fmode; gives an error
message and returns zero if not in correct format; returns one if in correct
format. Included only if HOST_SUPPORT is requested.
ΓòÉΓòÉΓòÉ 11.7. CHECK_FOR_PRINTER(name) ΓòÉΓòÉΓòÉ
Tests whether name is actually a printer device. Returns zero if not a valid
printer device and the printer number if valid.
ΓòÉΓòÉΓòÉ 11.8. CHECK_MARK_ON_SCREEN() ΓòÉΓòÉΓòÉ
Tells if a mark is visible on the screen. Returns a one if the mark is on the
visible screen and a zero if not. Use checkmark() to see if a mark exists
anywhere in the file.
ΓòÉΓòÉΓòÉ 11.9. checkmark() ΓòÉΓòÉΓòÉ
Checks if a marked area exists in the current file. Returns a one if a mark is
set; zero if no mark exists.
ΓòÉΓòÉΓòÉ 11.10. CURSOROFF() ΓòÉΓòÉΓòÉ
Turns the cursor off.
ΓòÉΓòÉΓòÉ 11.11. DEC2HEX() ΓòÉΓòÉΓòÉ
Converts a decimal number, arg(1), to a number of base arg(2) (default is
hexadecimal). Example usage is:
HexStringOut=Dec2Hex(DecimalIn)
ΓòÉΓòÉΓòÉ 11.12. DOS_COMMAND() ΓòÉΓòÉΓòÉ
Executes the DOS (OS/2) command specified in the arg(1) and redirects the
output to the file specified in vTEMP_FILENAME. Used by commands like the DIR
command.
ΓòÉΓòÉΓòÉ 11.13. DOS_VERSION() ΓòÉΓòÉΓòÉ
Returns DOS version number, multiplied by 100 so it can be treated as an
integer string. For example DOS 3.2 is reported as "320".
ΓòÉΓòÉΓòÉ 11.14. EINSERT_LINE() ΓòÉΓòÉΓòÉ
Inserts a line after current line and positions the cursor on the same column
number of the first nonblank character of preceding line.
ΓòÉΓòÉΓòÉ 11.15. ENTRY_BOX(title) ΓòÉΓòÉΓòÉ
Creates a System-Modal Dialog Box with an entry field and two push buttons. The
format for entry_box is:
userstext = entrybox(title,buttons,entrytext,cols,
maxchars)
with the following field definitions:
userstext is the variable that will contain the user's text entered.
title the text to be displayed in the title bar.
buttons the labels on the buttons separated by delimiting characters. If this
entry is null, the EPM defaults to Enter and Cancel.
entrytext contains the text to be entered into the user's text entry area. This
is useful for displaying defaults for change.
cols is the width of the dialog box.
maxchars is the maximum number of characters allowed for entry.
An example of a procedure (called testit) that uses the entrybox command
follows:
defc testit
k=entrybox('This is a test box.', '/one/two/',
'Hi!',30, 10)
message("The character returned was = "||k)
In the procedure, a dialog box with the title This is a test box will appear.
The two buttons will be labeled one and two. Initially the word Hi! will be
entered in the text input area. This is useful for displaying current values
and allowing the user to change them. The dialog box will be thirty characters
wide and allow the user to input up to ten characters. The input will be stored
in the variable k and the command message will display the input.
Also see the LISTBOX procedure in this section for an alternative means of
getting user input.
ΓòÉΓòÉΓòÉ 11.16. ERASETEMP(filename) ΓòÉΓòÉΓòÉ
Erases a file quietly (no "File not found" message) on both DOS and OS/2;
returns 0 if successful erase, and the error code (if on DOS) which is usually
2 for 'file not found'.
ΓòÉΓòÉΓòÉ 11.17. EXIST(filename) ΓòÉΓòÉΓòÉ
Determines whether filename exists. Returns a one if it does exist; a zero if
it doesn't.
ΓòÉΓòÉΓòÉ 11.18. FILETYPE() -- in SLNOHOST.E ΓòÉΓòÉΓòÉ
Returns the extension (everything after '.') of the current filename or fileid
specified in arg(1).
ΓòÉΓòÉΓòÉ 11.19. FILETYPE() -- in SAVELOAD.E ΓòÉΓòÉΓòÉ
Returns the 'ftype' portion of the host filename.
ΓòÉΓòÉΓòÉ 11.20. FIND_ROUTINE(utility) ΓòÉΓòÉΓòÉ
Used to both verify that the external utility program exists, and to get its
path.
ΓòÉΓòÉΓòÉ 11.21. GET_CHAR() ΓòÉΓòÉΓòÉ
Returns the character at the current cursor position.
ΓòÉΓòÉΓòÉ 11.22. GET_ENV(varname) ΓòÉΓòÉΓòÉ
Returns whether the variable name (varname) is found in the environment.
Returns the setting if found; zero if not found. For example:
res=get_env('DPATH')
In this case the contents of the DPATH environment variable would be returned
into the variable res.
ΓòÉΓòÉΓòÉ 11.23. GETDATE() ΓòÉΓòÉΓòÉ
Returns the date in the form: Weekday Month Day, Year; MonthNum.
ΓòÉΓòÉΓòÉ 11.24. GETTIME() ΓòÉΓòÉΓòÉ
Returns the time in the form: hh:mm:ss xm;hour24:hund.
ΓòÉΓòÉΓòÉ 11.25. HEX2DEC() ΓòÉΓòÉΓòÉ
Converts the number in arg(1) to a decimal number; arg(1) is assumed to be a
number of base arg(2) (hexadecimal by default). See the dec2hex() procedure for
an example.
ΓòÉΓòÉΓòÉ 11.26. ISA_MVS_FILENAME(candidate, var hostfile, var tempfile, var thisLT, var bin, var error_msg) ΓòÉΓòÉΓòÉ
Returns a zero and the error message (in error_msg) if it is not a valid MVS
filename; and returns a one and the rest of the information if the candidate is
a valid MVS filename.
ΓòÉΓòÉΓòÉ 11.27. ISA_PC_FILENAME(candidate, var tempfile, var error_msg) ΓòÉΓòÉΓòÉ
Returns a zero and the error message (in error_msg) if it is not a valid PC
filename; and returns a one and the rest of the information if the candidate
ΓòÉΓòÉΓòÉ 11.28. ISA_VM_FILENAME(candidate, var hostfile, var tempfile, var thisLT, var bin, var error_msg) ΓòÉΓòÉΓòÉ
Returns a zero and the error message (in error_msg) if it is not a valid VM
filename; and returns a one and the rest of the information if the candidate
ΓòÉΓòÉΓòÉ 11.29. ISHOST(candidate, verb, var hostfile, var tempfile, var thisLT, var bin) ΓòÉΓòÉΓòÉ
Determines a filename's type and returns:
0 = PC filename
1 = VM filename
2 = MVS filenme
ΓòÉΓòÉΓòÉ 11.30. ISNUM() ΓòÉΓòÉΓòÉ
Returns true if parameter given is a number, ignores leading and trailing
spaces.
ΓòÉΓòÉΓòÉ 11.31. ISOPTION(var cmdline, optionletter) ΓòÉΓòÉΓòÉ
Eliminates optionletter from cmdline; if optionletter occurred in the
commandline, returns 1; returns 0 otherwise.
ΓòÉΓòÉΓòÉ 11.32. JOINLINES() ΓòÉΓòÉΓòÉ
Joins the line below the cursor line with the cursor line.
ΓòÉΓòÉΓòÉ 11.33. LISTBOX(params) ΓòÉΓòÉΓòÉ
Enables the dynamic creation of modal PM list boxes. A macro can pop up a list
of items and have the user's selection returned to the macro. The entry chosen
(with a mouse double click or enter from the keyboard) is returned. If ESC was
hit then a null string is returned. Parameters are:
param1 the title for the listbox
param2 the list of items, separated by a common separator. The common
separator is the first character in the string.
example: /cat/dog/fish
separator='/'
list=cat, dog, fish
example: $cat/ground$fish/water
separator='$'
list=cat/ground, fish/water
These lists will be displayed like the past commands are displayed in
the command line dialog box. If one of elements in the box is
double-clicked on, it will be returned. For instance, if the second
element of the first example list was chosen by the user, the string
DOG would be returned.
An alternate method, useful for long lists which might not fit into an
EPM string, is passing the data in a buffer. This is indicated by
passing in a string starting with a hex '00', followed by the buffer
size, the buffer address, and an optional set of flags. The full
param2 in this case would be, for 6.00 and above:
\0 || atol(usedsize) || atoi(buffer_offset) || atoi(buffer_selector) [ || flag ]
and for earlier versions:
\0 || atoi(usedsize) || atoi(buffer_selector) || atoi(buffer_offset) [ || flag ]
The function listbox_buffer_from_file, defined in STDCTRL.E, can be
used for putting the contents of a file into a buffer in a suitable
format for listbox().
The default flag is 3. The bits are:
1 Position the listbox below the points specified.
2 Map the points to the desktop.
4 Each listbox item starts with an ASCII help panel ID. The IDs are removed
before filling the listbox. The first button is assumed to be a Details
button. Pressing it invokes help for the panel ID associated with the
current listbox item. (This feature is used by the Workframe/2.)
param3 (optional) button names. A maximum of four button names can be
specified to allow multiple buttons. If button one is clicked on, the
highlighted value from the list is returned and so should probably be
entitled ENTER. If the second button is chosen, a null string will be
returned as so should have a title something equivalent to Cancel. If
included the third and fourth boxes return the numbers 3 and 4
respectively. The meanings of these buttons can be defined by the
programmer. If no button names are given, buttons one and two will
default to ENTER and CANCEL respectively.
param4 (optional) row of text in which list box will go under. If this
parameter is not specified or if a parameter of zero (0) is specified,
the box will be placed under the cursor.
param5 (optional) column of text in which list box will go under. If this
parameter is not specified or if a parameter of zero (0) is specified,
the box will be placed under the cursor.
Note: If the row parameter is selected the column parameter must be
selected as well.
param6 (optional) height of the listbox in characters
Note: Since the default PM font is proportional the character height
and width are approximate values.
param7 (optional) width of listbox in characters.
param8 (optional) a buffer string - see below.
An example of listbox usage is:
retvalue = listbox("Pick a number",
"/one/two/three",
"/Enter/Cancel/None")
In this example there would be three entries in the list: one, two, and three.
There would also be three buttons entitled: Enter, Cancel, and None. Since the
last three parameters were omitted, the box would be located at the cursor
position and would be wide enough to accommodate the longest element of the
list and three buttons.
The above only lets the caller get back a string containing an entry from the
list if button 1 is selected. The buffer string allows you to get both the
button number and the selected text. If present, it is a string consisting of
(5.51 and below):
item# || button# || help_ID || handle || prompt
or, in 5.60 and above, of:
handle || item# || button# || help_ID || prompt
where item# is the listbox entry to be initially selected, button# is the
button that will be the default, help_ID is a help panel ID (all shorts),
handle is the window handle of the OWNERCLIENT (needed to call help; ignored if
help_ID is 0), and prompt is an ASCIIZ string to be displayed below the title
bar. If help_ID is non-zero, the rightmost button is assumed to be the help
button. The new parameters are passed to the toolkit in the return buffer,
which is padded with nulls, so only the minimum needed string need be sent.
The old way only supported returning a string if button 1 was pressed; button 2
was assumed to be Cancel, and returned null; anything else returned the button
number. The new way returns one byte representing the button number (in hex)
followed by the selected item. A button number of 0 means Esc was pressed or
the dialog was closed. If param8 was passed, the listbox() routine returns
this entire string; if not, it parses it and returns what the old callers
expected.
Examples of using all the features of listbox() can be found in BOOKMARK.E.
Also see the ENTRYBOX procedure in this section for an alternative method of
getting user input.
ΓòÉΓòÉΓòÉ 11.34. LOADFILE(files, options) -- in SLNOHOST.e ΓòÉΓòÉΓòÉ
Issues edit command on the specified files with the specified options.
ΓòÉΓòÉΓòÉ 11.35. LOADFILE(files,options) -- in SAVELOAD.e ΓòÉΓòÉΓòÉ
Issues edit command on the specified files with the specified options, after
checking for host file specification ('H:').
ΓòÉΓòÉΓòÉ 11.36. LOCK() ΓòÉΓòÉΓòÉ
Locks a file from other users in a LAN situation. Returns a zero if successful;
one if unsuccessful. This procedure is only available if requested with the
WANT_LAN_SUPPORT configuration constant.
ΓòÉΓòÉΓòÉ 11.37. MakeTempName() ΓòÉΓòÉΓòÉ
Creates a temporary filename using the optional arguments filename and fileid.
If no arguments are specified, the current filename and current fileid are
used. For example, if filename = `origname' and its fileid is 2, then the
temporary filename returned will be origname.$$2.
ΓòÉΓòÉΓòÉ 11.38. MATHCOMMON(input, suffix) ΓòÉΓòÉΓòÉ
Is responsible for math computations (dec, hex, or oct) done at commandline in
E, where input is the expression to be calculated and suffix is either 'x', 'o'
or '' depending upon the base of the number to be returned.
ΓòÉΓòÉΓòÉ 11.39. MAX(a,b) ΓòÉΓòÉΓòÉ
Returns the number which has the maximum value of those numbers in the
arguments list. As many arguments as needed can be listed.
ΓòÉΓòÉΓòÉ 11.40. MESSAGE(mymsg) ΓòÉΓòÉΓòÉ
Prints the message specified by the string mymsg on the messageline. This
procedure is a carry-over from earlier versions of E and effectively does the
same thing as a SAYERROR statement, except this MESSAGE() procedure takes up
more code.
ΓòÉΓòÉΓòÉ 11.41. MESSAGENWAIT() ΓòÉΓòÉΓòÉ
Prints the message passed to it in the editor messages dialog box and waits for
Cancel or ESC.
ΓòÉΓòÉΓòÉ 11.42. MIN(a,b) ΓòÉΓòÉΓòÉ
Returns the number which has the minimum value of those numbers in the list of
parameters. As many parameters as needed can be included for comparison.
ΓòÉΓòÉΓòÉ 11.43. MY_C_ENTER() ΓòÉΓòÉΓòÉ
Applies to c_enter key the appropriate action defined in C_ENTER_ACTION
constant.
ΓòÉΓòÉΓòÉ 11.44. MY_ENTER() ΓòÉΓòÉΓòÉ
Applies to enter key the appropriate action defined in ENTER_ACTION constant.
ΓòÉΓòÉΓòÉ 11.45. NAMEFILE() -- in SLNOLOAD.e ΓòÉΓòÉΓòÉ
Issues name command using arg(1) as the new filename.
ΓòÉΓòÉΓòÉ 11.46. NAMEFILE() -- in SAVELOAD.e ΓòÉΓòÉΓòÉ
Issues name command using arg(1) as the new filename, after checking whether
file is a host file.
ΓòÉΓòÉΓòÉ 11.47. NO_CHAR_MARK() ΓòÉΓòÉΓòÉ
Checks if WANT_CHAR_OPS option was set in STDCNF.e.
ΓòÉΓòÉΓòÉ 11.48. OPENSHELLWINDOW() ΓòÉΓòÉΓòÉ
Opens a edit window under a temporary filename for output. (i.e. like the DIR
command does)
ΓòÉΓòÉΓòÉ 11.49. PARSE_FILE_N_OPTS(argstr) ΓòÉΓòÉΓòÉ
Parses argstr which contains a mix of options and DOS file specs. The DOS file
specs can contain an '=' for the path or fileid, which will be replaced by the
corresponding part of the previous file.
ΓòÉΓòÉΓòÉ 11.50. PARSE_FILENAME(var filename) ΓòÉΓòÉΓòÉ
Parses a DOS filename. Optional second argument gives source for '=' when used
for path of fileid. Rc is 0 if successful, or rc is the position of '=' in
first argument if no second argument given but was needed.
ΓòÉΓòÉΓòÉ 11.51. PARSE_LEADING_OPTIONS(var rest, var options) ΓòÉΓòÉΓòÉ
Parses options portion of the edit command. It does not assume that all options
are specified before filenames. It is called by DEFC EDIT.
ΓòÉΓòÉΓòÉ 11.52. PBEGIN_MARK() ΓòÉΓòÉΓòÉ
Moves the cursor to the first character of the mark area. If the mark area is
not in the active file, the marked file is activated.
ΓòÉΓòÉΓòÉ 11.53. PBEGIN_WORD() ΓòÉΓòÉΓòÉ
Moves the cursor to the beginning of the word if the cursor is on this word.
If its not on a word, its moved to the beginning of the first word on the left.
If there is no word on the left its moved to the beginning of the word on the
right. If the line is empty the cursor doesn't move.
ΓòÉΓòÉΓòÉ 11.54. PBLOCK_REFLOW(option, var space, var tempofid) ΓòÉΓòÉΓòÉ
Reflows the text in the marked area; then the destination block area must be
selected and a second call to this procedure to reflow the source block in the
destination block. The source block is filled with spaces. Option=0 saves the
marked block in temp file; option=1 reflows temp file text and copies it to
marked area
ΓòÉΓòÉΓòÉ 11.55. PCENTER_MARK() ΓòÉΓòÉΓòÉ
Centers the strings inside a block mark. If a line mark exists, the text in the
marked lines is centered within the current margins. If no mark exists, the
text on the current line is centered within the current margins.
ΓòÉΓòÉΓòÉ 11.56. PCOMMON_ADJUST_OVERLAY(letter) ΓòÉΓòÉΓòÉ
Implements adjust and overlay commands for character and line marks (previously
only block marks enjoyed these privileges); parameter letter specifies 'A' for
adjust and 'O' for overlay. This procedure is only included if requested with
the WANT_CHAR_OPS configuration constant.
ΓòÉΓòÉΓòÉ 11.57. PCOPY_MARK(var destfirstline, var destlastline, var destfirstcol, var destlastcol) ΓòÉΓòÉΓòÉ
Implements the copymark statement for character marks; parameters specify the
marked area.
ΓòÉΓòÉΓòÉ 11.58. PDELETE_MARK(var destfirstline, var destlastline, var destfirstcol, var destlastcol) ΓòÉΓòÉΓòÉ
Implements the deletemark statement for character marks; parameters specify the
marked area.
ΓòÉΓòÉΓòÉ 11.59. PDISPLAY_MARGINS() ΓòÉΓòÉΓòÉ
Puts the margin settings on the current line.
ΓòÉΓòÉΓòÉ 11.60. PDISPLAY_TABS() ΓòÉΓòÉΓòÉ
Puts the tab stops on the current line.
ΓòÉΓòÉΓòÉ 11.61. PEND_MARK() ΓòÉΓòÉΓòÉ
Moves the cursor to the end of the marked area.
ΓòÉΓòÉΓòÉ 11.62. PEND_WORD() ΓòÉΓòÉΓòÉ
Moves the cursor to the end of the word if the cursor is on this word. If it's
not on a word, it's moved to the end of the first word on the right. If there
is no word on the right it's moved to the end of the word on the left. If the
line is empty the cursor doesn't move.
ΓòÉΓòÉΓòÉ 11.63. PFILE_EXISTS() ΓòÉΓòÉΓòÉ
Checks if file already exists in ring.
ΓòÉΓòÉΓòÉ 11.64. PFILL_MARK() ΓòÉΓòÉΓòÉ
Implements the fillmark statement for character marks; checks arg() to see if a
character for fill was specified, otherwise prompts for a character. This
procedure is available only if requested with the WANT_CHAR_OPS configuration
constant.
ΓòÉΓòÉΓòÉ 11.65. PFIND_BLANK_LINE() ΓòÉΓòÉΓòÉ
Finds first blank line starting from current line.
ΓòÉΓòÉΓòÉ 11.66. PFIRST_NONBLANK() ΓòÉΓòÉΓòÉ
Finds first nonblank character in the current line.
ΓòÉΓòÉΓòÉ 11.67. PLOWERCASE() ΓòÉΓòÉΓòÉ
Changes all alphabetic characters in the marked area to lowercase.
ΓòÉΓòÉΓòÉ 11.68. PMARGINS() ΓòÉΓòÉΓòÉ
Returns the current margins setting. Uses pcommon_tab_margin().
ΓòÉΓòÉΓòÉ 11.69. PMARK(mt) ΓòÉΓòÉΓòÉ
Marks at the cursor position; receives the mark type as an argument.
ΓòÉΓòÉΓòÉ 11.70. PMARK_WORD() ΓòÉΓòÉΓòÉ
Marks the word pointed at by the cursor. If the cursor is on a space the word
at the right is marked. If there is no word on the right, the word on the left
is marked.
ΓòÉΓòÉΓòÉ 11.71. PMOVE_MARK() ΓòÉΓòÉΓòÉ
Implements the movemark statement for character marks by calling pcopy_mark()
and pcopy_delete().
ΓòÉΓòÉΓòÉ 11.72. PPUT_STRING_BACK(string) ΓòÉΓòÉΓòÉ
Puts string back into marked area on current line.
ΓòÉΓòÉΓòÉ 11.73. PRESTORE_MARK(savemark) ΓòÉΓòÉΓòÉ
Marks the area specified in savemark, where savemark is a concatenated string
composed of the components: first_line, last_line, first_col, last_col, fileid,
marktype.
ΓòÉΓòÉΓòÉ 11.74. PRESTORE_POS(save_pos) ΓòÉΓòÉΓòÉ
Resets the cursor position according to save_pos, a string composed of the
concatenation of the fields: .col, .line, .cursorx, and .cursory.
ΓòÉΓòÉΓòÉ 11.75. PRINTER_READY() ΓòÉΓòÉΓòÉ
In EPM this procedure will always return ready. It remains for compatibility
with previous E macros.
ΓòÉΓòÉΓòÉ 11.76. PROOF1(word) ΓòÉΓòÉΓòÉ
Calls Lexam to spell check for the word specified by word.
ΓòÉΓòÉΓòÉ 11.77. PROOF2() ΓòÉΓòÉΓòÉ
Calls Lexam to begin spell-checking at the current word.
ΓòÉΓòÉΓòÉ 11.78. PSAVE_MARK(var savemark) ΓòÉΓòÉΓòÉ
Saves the specifications of the currently marked area in savemark, a string
composed of the concatenation of: first_line, last_line, first_col, last_col,
fileid, and marktype.
ΓòÉΓòÉΓòÉ 11.79. PSAVE_POS(var save_pos) ΓòÉΓòÉΓòÉ
Saves the cursor position according to save_pos, a string composed of the
concatenation of the fields: .line, .col, .cursorx, and .cursory.
ΓòÉΓòÉΓòÉ 11.80. PSET_MARK(firstline, lastline, firstcol, lastcol, mt, fileid) ΓòÉΓòÉΓòÉ
Marks the area designated by the parameters. The firstline, lastline, firstcol
and lastcol refer to position of the text in the file. The mt is the mark type
(block, line, or character). The fileid is the id number of the file to be
marked.
ΓòÉΓòÉΓòÉ 11.81. PTABS() ΓòÉΓòÉΓòÉ
Calls pcommon_tab_margin() to return tab settings.
ΓòÉΓòÉΓòÉ 11.82. PUPPERCASE() ΓòÉΓòÉΓòÉ
Converts all alphabetic characters in the marked area to uppercase letters.
ΓòÉΓòÉΓòÉ 11.83. QUITFILE() -- in SLNOHOST.e ΓòÉΓòÉΓòÉ
Issues quit command after checking windowing and modify status.
ΓòÉΓòÉΓòÉ 11.84. QUITFILE() -- in SAVELOAD.e ΓòÉΓòÉΓòÉ
Issues quit command after checking windowing and modify status.
ΓòÉΓòÉΓòÉ 11.85. REGISTER_MOUSEHANDLER(IsGlobal, event, mcommand) ΓòÉΓòÉΓòÉ
Allows the binding of mouse actions to commands. Mouse actions can be global or
local. Mouse actions will be processed as follows:
1. local mouse action definition
2. global mouse action definition
3. mouse action ignored
The variable IsGlobal determines whether the mouse action described is local or
global. The variable event determines the mouse action to be bound with the
command listed in the variable mcommand. Event should be in the following
format:
'key action state'
The key refers to the mouse key (either 1 or 2). The action must be one of the
following:
BEGINDRAG activates at the beginning of the drag
ENDDRAG activates at the end of a drag
CANCELDRAG activates if a drag is cancelled
CLICK activates if a button (specified by key) is single clicked
SECONDCLK activates if a button (specified by key) is double clicked
These actions must be capitalized and have exactly one space between the key
and the state numbers. The state should be the sum of the following:
0 = no states active
1 = shift key active
2 = control key active
4 = alternate key active
An example of a mouse action definition is:
register_mousehandler(0,'2 SECONDCLK 3','quit')
This would set the second click of button two on the mouse with the shift and
control states activated to do a QUIT command. This key action would be bound
locally to a particular file.
ΓòÉΓòÉΓòÉ 11.86. REMOVE_TRAILING_SPACES() ΓòÉΓòÉΓòÉ
Calls strip() to remove all trailing blanks; no longer used by standard EPM,
but left in for compatibility --> use strip() directly.
ΓòÉΓòÉΓòÉ 11.87. SAVEFILE(name) -- in SLNOHOST.e ΓòÉΓòÉΓòÉ
Issues save command with file specified in name parameter.
ΓòÉΓòÉΓòÉ 11.88. SAVEFILE(name) -- in SAVELOAD.e ΓòÉΓòÉΓòÉ
Issues save command with file specified, after checking whether the file is a
host file.
ΓòÉΓòÉΓòÉ 11.89. SAYATBOX() ΓòÉΓòÉΓòÉ
Use the messageNwait command instead.
ΓòÉΓòÉΓòÉ 11.90. SCROLL_LOCK() ΓòÉΓòÉΓòÉ
Determines whether or not the Scroll Lock key has been set on; if so, returns
1; otherwise returns 0.
ΓòÉΓòÉΓòÉ 11.91. SEARCH_PATH(AppendPath, FileName) ΓòÉΓòÉΓòÉ
Searches a path specifed in AppendPath for the file specified in FileName.
Returns the pathname, if successful; a null string if unsuccessful.
ΓòÉΓòÉΓòÉ 11.92. SELECT_EDIT_KEYS() ΓòÉΓòÉΓòÉ
Calls filetype() which returns the extension of the file whose fileid is
specified in arg(1), then activates the default keyset edit_keys. In EPM this
function is defunct.
ΓòÉΓòÉΓòÉ 11.93. SETLT(var LT_to_use) ΓòÉΓòÉΓòÉ
Sets the logical terminal to use. This procedure is only active if host editing
is included.
ΓòÉΓòÉΓòÉ 11.94. SET_FTO(hostfile, bin var fto) ΓòÉΓòÉΓòÉ
Sets the file transfer options. This procedure is only active if host editing
is included.
ΓòÉΓòÉΓòÉ 11.95. SetMouseSet (IsGlobal, NewMSName) ΓòÉΓòÉΓòÉ
Sets the current mouse action definition keys to the NewMSName. If IsGlobal is
true then the effects will be global, if IsGlobal if false then the new
settings will only affect the local file and not the rest of the files in the
ring.
ΓòÉΓòÉΓòÉ 11.96. SetTitleText() ΓòÉΓòÉΓòÉ
Sets the text in the editor's active title bar.
ΓòÉΓòÉΓòÉ 11.97. SHOWWINDOW() ΓòÉΓòÉΓòÉ
Allows the edit window to be invisible or visible.
ΓòÉΓòÉΓòÉ 11.98. SKIP_SPACES() ΓòÉΓòÉΓòÉ
Performs upon universal variables input (a string) and i (a position in the
string) set by next_sym(); increments i beyond any blank spaces.
ΓòÉΓòÉΓòÉ 11.99. SORT(firstline, lastline, firstcol, lastcol, fileid) ΓòÉΓòÉΓòÉ
Sorts the text in the area specified by the parameters. The first four
arguements outlines the area of the text to be sorted and the fifth is the id
number of the file to be sorted.
ΓòÉΓòÉΓòÉ 11.100. SPELLWORD() ΓòÉΓòÉΓòÉ
Checks the word at the cursor position, removing punctuation characters. It is
assumed that the cursor is positioned at the beginning of the word. (Used by
proof2 and proofword.) If it's a valid word then check the spelling of the
word using the lexam opcode. If a valid result is returned place it in a PM
list box using the 'listbox' procedure. Returns the length of the word found.
The optional argument is a string containing a button name. E.g., '/Next'
ΓòÉΓòÉΓòÉ 11.101. SPLITLINES() ΓòÉΓòÉΓòÉ
Inserts a line; moves the text from the cursor position to the end of line onto
the new line; and indents the new line to the column of the first non-blank
character of the line preceding it.
ΓòÉΓòÉΓòÉ 11.102. SUBDIR() ΓòÉΓòÉΓòÉ
Uses SUBDIR if in DOS; uses FILEFIND if in OS/2 protect mode; then calls
find_routine() to verify that the external utility program exists, and to get
its path.
ΓòÉΓòÉΓòÉ 11.103. SYNONYM() ΓòÉΓòÉΓòÉ
Checks the next word on the line for its possible synonyms. If synonyms are
found a PM list box is displayed showing the possible new words.
ΓòÉΓòÉΓòÉ 11.104. TRUNC(num) ΓòÉΓòÉΓòÉ
Truncates that part (if any) of num after a decimal point.
ΓòÉΓòÉΓòÉ 11.105. UNLOCK(fileid) ΓòÉΓòÉΓòÉ
Attempts to unlock a previously locked file in a LAN situation. Returns a zero
if successful; a one if unsuccessful. This procedure is only available if
requested with the WANT_LAN_SUPPORT configuration constant.
ΓòÉΓòÉΓòÉ 11.106. VMFILE(var name, var cmdline) ΓòÉΓòÉΓòÉ
Checks to make sure that a host filename (name) is of the correct form.
ΓòÉΓòÉΓòÉ 11.107. WINDOWSIZE1(row,col,x,y) ΓòÉΓòÉΓòÉ
Sizes a window row high and col wide based at the lower left hand corner
coordinates of x and y. An optional fifth argument sets:
1 = size window
2 = move window
3 = both (default)
ΓòÉΓòÉΓòÉ 12. Return Codes ΓòÉΓòÉΓòÉ
RC Error strings
---- -----------------
-1 Unable to Initialize interpreter object
-2 File not found
-3 Path not found
-4 Too many open files
-5 Access denied
-6 DOS ERROR: Message not available
-7 Memory control blocks destroyed. Save files and reboot.
-8 Insufficient memory
-9 Error Building SubMenu
-10 Error Building Menu Item
-11 Error Showing Menu
-12 Error Deleting Menu
-13 Too Many AVIO window
-14 DOS ERROR: Message not available
-15 Invalid drive
-16 DOS ERROR: Message not available
-17 DIS ERROR: Message not available
-18 No more files
-19 Disk is write-protected
-20 Unknown unit
-21 Drive not ready
-22 Unknown command
-23 Data error (CRC)
-24 Bad request structure length
-25 Seek error
-26 Unknown media type
-27 Sector not found
-28 Printer out of paper
-29 Write fault
-30 Read fault
-31 General failure
-32 ERROR: Message not available
... ERROR: Message not available
-253 ERROR: Message not available
-254 Numeric overflow or underflow
-255 Invalid number of arguments
-256 Recursion too deep
-257 Invalid number of parameters
-258 Out of string space
-259 Expression stack overflow
-260 Invalid fileid
-261 Illegal opcode
-262
-263 Invalid argument
-264 For loops nested too deep
-265 Divide by zero
-266 Unable to shrink
-267 Invalid call by reference
-268 Procedure needs more arguments
-269 User Break. Command halted
-270 Not enough memory
-271 Error in margin settings
-272 Error in tab settings
-273 String not found
-274 Unknown command
-275 Missing filename
-276 Line too long to join
-277 Too many files
-278 Line(s) truncated
-279 Text already marked
-280 Text not marked
-281 Source destination conflict
-282 New file
-283 Line mark required
-284 Error opening file
-285 Error writing file
-286 Error reading file
-287 Insufficient disk space
-288 Block mark required
-289 Too many rings
-290 Invalid EX file or incorrect version.
-291 No main entry point
-292 Error closing file
-293 has been modified
-294 Quit without saving?
-295
-296
-297
-298
-299
-300 Command dialog box too long to shell
-301 Cannot unlink module in use
-302 Cannot unlink base keyset module
-303 Internal error: unlink invalid mod
-304 Linking module error
-305 DEFMAIN not found
-306 DEFINIT not found
-307 Link: file not found
-308 Link: invalid filename
-309 File already linked
-310 Unlink: unknown module
-311 Unlink: bad module filename
-312 Call: duplicated proc
-313 Call: unknown proc
-314 Grep: memory error
-315 Grep: missing ]
-316 Grep: bad range in [a-z]
-317 Grep: empty []
-318 Grep: regular expression too long
-319 Dynalink: incorrect number of parameters
-320
-321 Cannot find keyset
-322 Dynalink: unrecognized library name
-323 Line number invalid or too large for file
-324 Keyboard status failed
-325 Buffer creation size too large
-326 Dynalink: unrecognized procedure name
-327 Too many keysets
-328
-328 Invalid first parameter
-329 Invalid second parameter
-330 Invalid third parameter
-331 Invalid fourth parameter
-332 Invalid fifth parameter
-333 Invalid sixth parameter
-334 Invalid seventh parameter
-335 Invalid Subcommand
-336 Invalid column number
-337 Invalid array identifier
-338 Array already exists:
-339 ERROR: Message not available
... ERROR: Message not available
etc.
ΓòÉΓòÉΓòÉ 13. ET Compilation Error Message Explanations ΓòÉΓòÉΓòÉ
If you have made changes to the configuration or have programmed your own
macros in the E language, this section is important to you. Any syntactic or
semantic errors in your programming, will be noted by the ET compiler. The
following section describes each compilation error in simple terms. When you
receive an error from ET, note the error message and look it up in the
following list. The messages appear in alphabetic order.
ΓòÉΓòÉΓòÉ 13.1. Column specification out of range. ΓòÉΓòÉΓòÉ
The value specified for a column position exceeds the compiler's maximum line
length of 255.
ΓòÉΓòÉΓòÉ 13.2. Comment not terminated. ΓòÉΓòÉΓòÉ
You have begun a comment with the '/*' string but never ended it with a
matching '*/'. This means that all code after the comment has been ignored by
the compiler. Reaching an end of file has alerted the compiler to the fact
that the comment was not terminated.
ΓòÉΓòÉΓòÉ 13.3. DEFMAIN already defined. ΓòÉΓòÉΓòÉ
You have defined more than one main procedure using the DEFMAIN statement. Only
one can be defined at a time. See User's Manual section Definition Primitives
for more information.
ΓòÉΓòÉΓòÉ 13.4. EX code too big. ΓòÉΓòÉΓòÉ
The code that ET is producing after compiling your input file is taking up more
space than allowable. The maximum amount of memory available for a .EX file is
65,500 bytes.
ΓòÉΓòÉΓòÉ 13.5. Expecting '('. ΓòÉΓòÉΓòÉ
The compiler was expecting a left parenthesis. Possible reasons for this are
that you have called a procedure and omitted the parentheses after the
procedure name. The syntax for procedure calls is either:
proc_name([parameters])
OR call proc_name([parameters])
ΓòÉΓòÉΓòÉ 13.6. Expecting ')'. ΓòÉΓòÉΓòÉ
The compiler was expecting a right parenthesis to match a left parenthesis
which was read in earlier. Perhaps you have not matched each parenthesis in a
procedure call or complex expression. For example, if the following expression
was typed in YOUR_FILE.E: call proc_test( k=( (a*b)+ 8 ), you would
have received such an error message because there are three left parentheses
and only two right parentheses.
ΓòÉΓòÉΓòÉ 13.7. Expecting ';'. ΓòÉΓòÉΓòÉ
The compiler's newline symbol is the semi-colon (';'). Therefore, they are
often interchangeable. A statement was encountered whose syntax requires either
a semi-colon or a new line in a specific place, but no such semi-colon or new
line was found. For example, each INCLUDE statement is required to end with
either a semi-colon or a new line. All of the following examples are
syntactically correct:
include 'mystuff.e' ; include 'mykeys.e'
AND
include 'mystuff.e'
include 'mykeys.e'
AND
include 'mystuff.e' ; x = 1
However, you could not have multiple INCLUDE statements on one line without a
semi-colon as separator.
ΓòÉΓòÉΓòÉ 13.8. Expecting ','. ΓòÉΓòÉΓòÉ
A statement has been found whose syntax dictates that there should be a comma
in a specific position, yet no comma was found there. The most likely cause of
this error message is that you have called some built-in procedure, but have
not given the correct number of parameters. The compiler is looking for a
comma which would indicate that there are more parameters still to come.
ΓòÉΓòÉΓòÉ 13.9. Expecting '='. ΓòÉΓòÉΓòÉ
A statement was found whose syntax dictates that an assignment operator must
occur at some specific place in the statement, but no such assignment symbol
was found. One example of such a statement is the FOR statement. As shown in
section Conditional and Loop Statements, there must be a '=' symbol immediately
after the loop variable name. The other likely causes of this error are syntax
errors in a CONST declaration (see Constants).
ΓòÉΓòÉΓòÉ 13.10. Expecting an identifier. ΓòÉΓòÉΓòÉ
A statement has been found whose syntax dictates that there should be an
identifier in a specific position, yet no such identifier was found. One
possible cause of this error message is that you have defined a keyset with the
DEFKEYS keyword, but forgot to name the keyset. See section Key Definitions
(DEF and DEFKEYS) for the syntax of the DEFKEYS statement.
Another less obvious reason for this error is that you have used a keyword or
procedure name in place of an identifier. For example, if you try to declare:
UNIVERSAL function_key_text
Since function_key_text is a predefined universal variable, it is a reserved
word, and therefore is not considered an identifier.
ΓòÉΓòÉΓòÉ 13.11. Expecting constant expression. ΓòÉΓòÉΓòÉ
You have begun a constant definition statement by using the CONST keyword, but
you have not assigned a constant expression (an expression involving only
arithmetic operators, numbers and previously defined constants) to an
identifier. Please use the following syntax:
CONST
max_id=7
max_len=max_id * 10
ΓòÉΓòÉΓòÉ 13.12. Expecting DEFinition primitive. ΓòÉΓòÉΓòÉ
The compiler is expecting a definition primitive, i.e. one of the DEFxxxx
statements, a SET statement, an INCLUDE statement or a CONST statement.
Unfortunately, this error message can be triggered at inappropriate times when
the compiler is confused by the syntax it has read. This error message often
complains about a statement in the middle of a DEF construct. Do not
necessarily assume that you need to add a DEF. Each of these cases must be
evaluated individually.
However, this error message does have value when it reports on a statement that
has been issued outside a DEF construct. Remember that you cannot have
statements outside a DEFxxxx block. All statements must be contained within a
DEFxxxx primitive. Often a statement issued outside a DEF is not reported
because since there is no keyword or statement to terminate the DEF, the
compiler assumes that the statement belongs to the last DEF. However, there are
cases when it will correctly report this error. For example, assume the
following statements occur in some file TEST.E:
CONST
stuff = 1
sayerror "stuff is " stuff
defproc test1()
temp = 45 * 36
During compilation of TEST.E, the user would receive an "Expecting DEF" error
message with an arrow pointing to the sayerror statement. Since a CONST
statement is a DEF primitive, it ends all previous DEFS, and since sayerror is
not accepted as part of a CONST construct, an error is reported.
ΓòÉΓòÉΓòÉ 13.13. Expecting DO ΓòÉΓòÉΓòÉ
A WHILE construct has been started, i.e. a WHILE keyword has been found, but
the keyword DO is missing from the statement. Please check the section on
Conditional and Loop Statements for the syntax of the WHILE DO statement.
ΓòÉΓòÉΓòÉ 13.14. Expecting DO WHILE or DO FOREVER ΓòÉΓòÉΓòÉ
One of the DO constructs has been started, i.e. a DO keyword was found, but
the rest of the statement's syntax does not fit any of the DO constructs ( DO
WHILE, DO FOREVER, and/or DO (FOR) ). See section Conditional and Loop
Statements for the syntax of the DO construct.
ΓòÉΓòÉΓòÉ 13.15. Expecting END to DO loop. ΓòÉΓòÉΓòÉ
One of the DO constructs ( DO-WHILE, DO FOREVER or DO (FOR) ) has been started,
but no 'END' or 'ENDDO' statement has been found to end the loop. Please refer
to section Conditional and Loop Statements for the syntax of the DO constructs.
ΓòÉΓòÉΓòÉ 13.16. Expecting ENDFOR. ΓòÉΓòÉΓòÉ
A FOR construct has been started, i.e. a FOR keyword has been found, but no
ENDFOR keyword has been found to end the loop. Please check the section on
Conditional and Loop Statements for the syntax of the FOR statement.
ΓòÉΓòÉΓòÉ 13.17. Expecting ENDIF to terminate IF statement. ΓòÉΓòÉΓòÉ
An IF keyword has been read, but no ENDIF statement has been found to end the
block of statements encased by the IF condition. See the section on
Conditional and Loop Statements for the syntax of the IF statement.
ΓòÉΓòÉΓòÉ 13.18. Expecting ENDLOOP to terminate LOOP. ΓòÉΓòÉΓòÉ
A LOOP construct has been started, but no ENDLOOP statement has been found to
end the loop. See section Conditional and Loop Statements for the syntax of
the LOOP construct.
ΓòÉΓòÉΓòÉ 13.19. Expecting ENDWHILE to terminate WHILE. ΓòÉΓòÉΓòÉ
A WHILE construct has been started, but no ENDWHILE statement has been found to
end the loop. Please refer to section Conditional and Loop Statements for the
syntax of the WHILE construct.
ΓòÉΓòÉΓòÉ 13.20. Expecting procedure name. ΓòÉΓòÉΓòÉ
A procedure definition has been started, i.e. a DEFPROC keyword has been found,
but no procedure name appeared after it to identify the procedure. Please see
the section on Definition Primitives for the syntax of a DEFPROC statement.
ΓòÉΓòÉΓòÉ 13.21. Expecting quoted string. ΓòÉΓòÉΓòÉ
A statement was found whose syntax dictates that a quoted string must occur at
some specific place in the statement, but no such quoted string was found. An
example of such a statement is the SAY statement. As shown in section Built-in
Statements and Procedures, there must be a quoted string immediately after the
SAY keyword.
ΓòÉΓòÉΓòÉ 13.22. Expecting THEN. ΓòÉΓòÉΓòÉ
An IF construct has been started, i.e. an IF keyword was found, but no THEN
keyword can been found. See section Conditional and Loop Statements for the
syntax of the IF-THEN-ELSE statement.
ΓòÉΓòÉΓòÉ 13.23. Expecting TO. ΓòÉΓòÉΓòÉ
A FOR construct has been started, i.e. a FOR keyword has been found, but the
keyword TO is missing from the statement. Please check the section Conditional
and Loop Statements for the syntax of the FOR statement.
ΓòÉΓòÉΓòÉ 13.24. Expecting VALUE. ΓòÉΓòÉΓòÉ
A PARSE statement has been started, i.e. the keyword PARSE was found, but
neither a VALUE nor an ARG keyword can been found. See the User's Manual
section The Parse Statement for the syntax of the PARSE statement.
ΓòÉΓòÉΓòÉ 13.25. Expecting variable name. ΓòÉΓòÉΓòÉ
A statement was found whose syntax dictates that a variable name must occur at
some specific place in the statement, but no such variable name was found. An
example of such a statement is the FOR statement. As shown in the section on
Conditional and Loop Statements, there must be a variable name (the loop
variable to be incremented) immediately after the FOR keyword.
ΓòÉΓòÉΓòÉ 13.26. Expecting WITH. ΓòÉΓòÉΓòÉ
A PARSE-VALUE statement has been started, i.e. the keywords PARSE and VALUE
were found, but a WITH keyword cannot be found. See the section on The Parse
Statement for the syntax of the PARSE statement.
ΓòÉΓòÉΓòÉ 13.27. Expression not assignment compatible. ΓòÉΓòÉΓòÉ
The compiler has detected an assignment in which the expression on the right
side of the assignment operator can not be assigned to the expression or
identifier on the left side. The most common cause of this is that you have
tried to assign a value to something other than a variable, i.e. a constant or
procedure.
ΓòÉΓòÉΓòÉ 13.28. Expression too complex. ΓòÉΓòÉΓòÉ
An expression is any combination of identifiers (variables, constants, and/or
procedures), numbers and operators that fit the syntax of a language. A complex
expression is one that contains expressions within itself. For example, the
following is an expression:
test_var + 6.
An example of a complex expression would be:
( (test_var + 6) * 8).
Each of the innermost expressions must be evaluated before the entire
expression can be assigned a value. The specified expression in your input
file is too complicated, i.e. has too many expressions within itself, for the
compiler to evaluate it. Please break the expression into several less complex
expressions. For example, let us assume that the following expression was too
complex:
call proc_test( k=( (a*b)+ 8 ) ),
You could simplify the call to proc_test by assigning some of the inner
expressions to temporary variables. One solution would be:
temp1 = a*b
k = temp1 + 8
call proc_test(k)
Note: The above expression is a simple example. It is not too complex for the
compiler. ET allows for 40 expressions within an expression.
ΓòÉΓòÉΓòÉ 13.29. Extraneous parameters. ΓòÉΓòÉΓòÉ
You have specified too many parameters in the command dialog box. The syntax
is: ET [options] inputfile[.e] [outputfile[.ex]] Remember that any
options MUST PRECEDE the input and output filenames!
ΓòÉΓòÉΓòÉ 13.30. Identifier already defined as same or different type. ΓòÉΓòÉΓòÉ
You are trying to use an identifier to name a variable, constant or procedure
uniquely, yet the identifier has already been used in the same scope for
another purpose. Check over your program and rename the appropriate
identifiers.
ΓòÉΓòÉΓòÉ 13.31. Identifier too long. ΓòÉΓòÉΓòÉ
The number of characters in the name of the specified variable, constant,
procedure, etc. exceeds the maximum allowance of 255 characters. Please rename
it with fewer letters and/or numbers.
ΓòÉΓòÉΓòÉ 13.32. Illegal character. ΓòÉΓòÉΓòÉ
This character does not make sense or is not allowed in the E language. One
example of E code which would yield this error message is if a unary minus or
plus operator is used preceding an alphabetic character rather than a digit.
For example,
temp = +c
These unary operators make sense only with numeric operands.
ΓòÉΓòÉΓòÉ 13.33. Illegal operator. ΓòÉΓòÉΓòÉ
An operator is some function to be performed on its operands. Operands are
identifiers or constant values that are acted upon by operators. Examples of
operators are: '+' (addition), '=' (assignment), 'NOT' (logical negation), and
'<=' (less than or equal). The operator you have specified does not exist in
the E language. Please check the Operators section for a complete list of
operators.
ΓòÉΓòÉΓòÉ 13.34. INCLUDES nested too deep. ΓòÉΓòÉΓòÉ
A nested INCLUDE statement means that a file, for example FILE1.E, contains a
statement: include 'file2.e' and that file2.e also contains an
INCLUDE statement, which includes a third file. ET only allows for 5 levels of
nested include files. You have exceeded this limit. Please reorganize your
files.
ΓòÉΓòÉΓòÉ 13.35. Internal error in POPS. ΓòÉΓòÉΓòÉ
This error is internal to the workings of the ET compiler. It has nothing to do
with user input. Please send a note to the userid EOS2 at YORKTOWN with
information regarding the error.
ΓòÉΓòÉΓòÉ 13.36. Invalid argument. ΓòÉΓòÉΓòÉ
The argument specified in the procedure call is incorrect. Specifically, the
string argument in the SAYERROR() procedure call does not match any of the
strings associated with error messages known to the compiler. Read the
description of the usage of the SAYERROR() procedure in section Built-in
Statements and Procedures for more information.
ΓòÉΓòÉΓòÉ 13.37. Invalid color. ΓòÉΓòÉΓòÉ
You are trying to redefine the colors of the E editor; however the syntax of
your statement is incorrect. Possible explanations of this are that: (1) you
have not used an identifier to name the constant, (2) you have not used a valid
color value name, or (3) you have not separated each assignment with either a
semi-colon or a new line. An example of the syntax is: /* color example */
TEXTCOLOR = BLUE For more information on usage, see section Changing the
Default Configuration in The EPM User's Guide. For a list of valid color value
names, see the top of the COLORS.E file which contains the values of the
defaults.
ΓòÉΓòÉΓòÉ 13.38. Invalid cursor setting. ΓòÉΓòÉΓòÉ
You are trying to set the default cursor sizes, but the values you have given
in the set cursors statement are not valid. Valid values are 1 through 15.
ΓòÉΓòÉΓòÉ 13.39. Invalid expression. ΓòÉΓòÉΓòÉ
This expression is not a valid expression in the E language. Please refer to E
Language Syntax for a list of all valid expressions.
ΓòÉΓòÉΓòÉ 13.40. Invalid field name. ΓòÉΓòÉΓòÉ
You have attempted to manipulate a field in the fileid structure; however the
field you have named does not exist. Check section Fileid Structure for a list
of all field names.
ΓòÉΓòÉΓòÉ 13.41. Invalid key name. ΓòÉΓòÉΓòÉ
A KEY keyword has been found, but no valid keyname followed the keyword. There
are a limited number of keys on the keyboard that can be redefined. For a
complete list of those keys, see E Language Syntax.
ΓòÉΓòÉΓòÉ 13.42. Invalid margin setting. ΓòÉΓòÉΓòÉ
You are trying to reset the margins for the E editor, but the column values of
your desired margin settings are invalid. Possible causes of this error are
that you have tried: (1) to set a margin past E's maximum margin column (254),
(2) to set a margin in a zero or negative column, or (3) to set the left margin
in a column greater than the right margin. Please refer to The EPM User's Guide
for examples of the correct syntax.
ΓòÉΓòÉΓòÉ 13.43. Invalid number of parameters. ΓòÉΓòÉΓòÉ
You have called a procedure with fewer parameters than it is defined to have.
For example, in the section Built-in Statements and Procedures, look at the
description of the procedure SUBSTR(). SUBSTR() is defined to have two, three
or four parameters, but it requires AT LEAST two parameters to perform its
function. If the user invokes the function with only one argument, for example
SUBSTR('abc'), an error will occur.
ΓòÉΓòÉΓòÉ 13.44. Invalid numeric. ΓòÉΓòÉΓòÉ
You have attempted to perform some arithmetic function on variables that are
not numeric; or you have mixed other characters in with some digits. For
example, 35.x or 3temp_var are not valid expressions. The compiler expects
identifiers to BEGIN WITH AN ALPHABETIC CHARACTER, and expects numbers to
consist solely of digits and certain special characters (for example, the
decimal point ".").
ΓòÉΓòÉΓòÉ 13.45. Invalid option. ΓòÉΓòÉΓòÉ
You have specified an option in the command dialog box which does not exist.
Check The EPM User's Guide or section Command Summary for all possible command
dialog box options.
ΓòÉΓòÉΓòÉ 13.46. Invalid set name. ΓòÉΓòÉΓòÉ
You are trying to set a configurable option for the E editor, but the option
you have named in the SET statement does not exist. Please check The EPM User's
Guide for a complete list of options.
ΓòÉΓòÉΓòÉ 13.47. Invalid tab setting. ΓòÉΓòÉΓòÉ
You are trying to reset the tabs for the E editor, but the column values of
your desired tab settings are invalid. Possible causes of this error are that:
(1) you have tried to set a tab past E's maximum column (255), (2) you have
tried to set a tab in a negative column, or (3) you have not typed the tab
settings in ascending order. Tab settings CANNOT be listed in a mixed order,
for example: tabs 5 10 20 15 30 25 ... They must be written in
ascending order. In the above example, the statement must be rewritten as
follows: tabs 5 10 15 20 25 30 ...
ΓòÉΓòÉΓòÉ 13.48. ITERATE may only be executed inside a loop. ΓòÉΓòÉΓòÉ
An ITERATE statement has been issued outside one of the loop constructs (WHILE,
LOOP, or DO). Since the ITERATE statement only makes sense in combination with
a loop, this is an error. See section Conditional and Loop Statements for the
rules governing and syntax of the ITERATE statement.
ΓòÉΓòÉΓòÉ 13.49. Keyset not defined. ΓòÉΓòÉΓòÉ
You have issued a KEYS statement to change the keyset to a predefined keyset;
however the named keyset has not been defined in the current scope. In order to
use a KEYS keyset_name statement, you must have issued a DEFKEYS keyset_name
statement to define the named keyset and then issued a series of DEF statements
to define the new function of the desired keys. A sample keyset definition can
be found in section Key Definitions (DEF and DEFKEYS).
ΓòÉΓòÉΓòÉ 13.50. LEAVE may only be executed inside a loop. ΓòÉΓòÉΓòÉ
A LEAVE statement has been issued outside one of the loop constructs (WHILE,
LOOP, or DO). Since the LEAVE statement only makes sense in combination with a
loop, this is an error. See section on Conditional and Loop Statements for the
rules governing and syntax of the LEAVE statement.
ΓòÉΓòÉΓòÉ 13.51. Line too long. ΓòÉΓòÉΓòÉ
The number of characters in this line exceeds the maximum. The maximum line
length is 255 characters. Please break-up the line using the technique
discussed in section Line Continuations.
ΓòÉΓòÉΓòÉ 13.52. More than max number of global variables. ΓòÉΓòÉΓòÉ
You have defined more global variables than the compiler allows. The maximum
number of global variables is 8200. Note Any variable preceded by the
UNIVERSAL keyword is considered global, i.e. any procedure can access it.
ΓòÉΓòÉΓòÉ 13.53. More than max number of local variables. ΓòÉΓòÉΓòÉ
Your procedure has been defined with more than the compiler's maximum number of
allowable local variables, i.e. variables defined within the procedure. The
maximum number of locals is 1038.
ΓòÉΓòÉΓòÉ 13.54. Not enough core. ΓòÉΓòÉΓòÉ
Your computer does not have enough core memory (primary memory not disk space)
to compile the specified input file and write compiled code to an output file.
Typically, 320K of memory is required; however if you have added a great amount
of code to the e.e file, more memory may be necessary.
ΓòÉΓòÉΓòÉ 13.55. Number out of range or expecting number. ΓòÉΓòÉΓòÉ
This error could occur for a few different reasons. The first possible cause of
the error is incorrect syntax or semantics in a parse statement. If a '+' or
'-' was encountered in the template portion of a PARSE statement, a number is
expected to follow it. Either a number did not follow one of these operators or
the number that did follow exceeded 255. Remember that the numbers in the
template represent column specifications and therefore cannot exceed the
maximum column. Please see section The Parse Statement for the exact syntax of
the parse statement.
Another possible cause of this error is that an arithmetic operator symbol was
found in an expression, and yet all of the operands were either not numeric or
exceeded the compiler's maximum number of 32,767.
ΓòÉΓòÉΓòÉ 13.56. Number too large. ΓòÉΓòÉΓòÉ
This error occurs only when the compiler is translating ASCII codes preceded by
the '\' operator. Values following such a '\' cannot exceed 255. See section
String Expressions for a more detailed explanation of this use of the backslash
character.
ΓòÉΓòÉΓòÉ 13.57. Numeric overflow. ΓòÉΓòÉΓòÉ
You have attempted to perform some arithmetic function where the result has an
exponent greater than 999999999.
ΓòÉΓòÉΓòÉ 13.58. Out of symbol table space. ΓòÉΓòÉΓòÉ
The compiler allocates a certain amount of memory space for each variable. The
space is needed to store necessary information relevant to that variable.
There is not enough primary memory (not disk space) on your computer to allow
any more variables to be used.
ΓòÉΓòÉΓòÉ 13.59. Procedure not defined. ΓòÉΓòÉΓòÉ
You have called or made reference to a procedure which was never defined.
Please define the procedure or delete the call to it. Note: the compiler will
not tell you where the call to the undefined procedure occurred or whether
there are many such occurrences.
ΓòÉΓòÉΓòÉ 13.60. String not terminated. ΓòÉΓòÉΓòÉ
The specified string was not enclosed with quote marks. The final quote was
omitted.
ΓòÉΓòÉΓòÉ 13.61. Too many arguments. ΓòÉΓòÉΓòÉ
You have defined a procedure or function with more than the compiler's maximum
number of allowable arguments. The maximum number of arguments is 8.
ΓòÉΓòÉΓòÉ 13.62. Unable to open input file. ΓòÉΓòÉΓòÉ
The compiler could not open the file which you listed in the command dialog box
as the input file. This is probably due to the fact that no such file exists.
Check your spelling of the filename and make sure the file is in the current
directory.
ΓòÉΓòÉΓòÉ 13.63. Unable to open output file. ΓòÉΓòÉΓòÉ
The compiler cannot create the file you named in the command dialog box as the
output file. This probably occurred because you gave a nonexistent path to the
file. Check the spelling and accuracy of the pathname. (The default pathname is
the current directory.)
ΓòÉΓòÉΓòÉ 13.64. Unable to read input file. ΓòÉΓòÉΓòÉ
The compiler was unable to read from the input file you specified in the
command dialog box. This maybe due to the fact that the file is locked or
damaged. Please check the file.
ΓòÉΓòÉΓòÉ 13.65. Unable to write output file. ΓòÉΓòÉΓòÉ
The compiler cannot write to the file you named in the command line as the
output file. This error could occur because the file is read-only or because
no space is left on the disk.
ΓòÉΓòÉΓòÉ 13.66. Variable not initialized. ΓòÉΓòÉΓòÉ
You have used a variable which was never initialized. The variable has no
value; therefore the expression containing it cannot be evaluated.
Another common cause for this error is when a command has been issued within an
E statement, but the command has not been quoted. Please read the section Using
EPM Commands in E Statements for information on how to use commands in an E
program.
ΓòÉΓòÉΓòÉ 14. Ordinal Values of Functions Accessed via DOSCALLS.DLL ΓòÉΓòÉΓòÉ
This list shows the mapping between the DOS system function names and their
ordinal values. In order to access one of these system functions in OS/2, you
must make a call to the function DYNALINK(), and include the function's ordinal
value in the parameter list. For more information, see the DYNALINK() entry in
section Built-in Statements and Procedures.
Function Name Ordinal Value
------------- -------------
DBGETKVAR 109
DBGETOWNER 117
DBMEMFREE 116
DBMEMLOCK 112
DBMEMREALLOC 115
DBMEMUNLOCK 113
DBPHYSINFO 118
DBSEGALLOC 114
DOSALLOCHUGE 40
DOSALLOCSEG 34
DOSALLOCSHRSEG 35
DOSBEEP 50
DOSBUFRESET 56
DOSCALLBACK 157
DOSCHDIR 57
DOSCHGFILEPTR 58
DOSCLIACCESS 51
DOSCLOSE 59
DOSCLOSESEM 23
DOSCREATECSALIAS 43
DOSCREATESEM 24
DOSCWAIT 2
DOSDELETE 60
DOSDEVCONFIG 52
DOSDEVIOCTL 53
DOSDEVIOCTL2 99
DOSDUPHANDLE 61
DOSENTERCRITSEC 3
DOSENUMATTRIBUTE 204
DOSERROR 120
DOSEXIT 5
DOSEXITCRITSEC 6
DOSEXITLIST 7
DOSFILELOCKS 62
DOSFINDCLOSE 63
DOSFINDFIRST 64
DOSFINDNEXT 65
DOSFLAGPROCESS 15
DOSFREEMODULE 46
DOSFREESEG 39
DOSGETCP 130
DOSGETDATETIME 33
DOSGETENV 91
DOSGETHUGESHIFT 41
DOSGETINFOSEG 8
DOSGETMACHINEMODE 49
DOSGETMODHANDLE 47
DOSGETMODNAME 48
DOSGETPID 94
DOSGETPROCADDR 45
DOSGETPRTY 9
DOSGETSEG 121
DOSGETSHRSEG 36
DOSGETSTDA 119
DOSGETVERSION 92
DOSGIVESEG 37
DOSGLOBALSEG 132
DOSHOLDSIGNAL 13
DOSHUGEINCR 136
DOSHUGESHIFT 135
DOSICANONICALIZE 100
DOSICREATETHREAD 1
DOSIEXECPGM 4
DOSIRAMSEMWAKE 125
DOSIREAD 79
DOSISEMREQUEST 18
DOSISEMWAIT 21
DOSISETCP 131
DOSISYSSEMCLEAR 17
DOSISYSSEMSET 19
DOSIWRITE 87
DOSKILLPROCESS 10
DOSLIBINIT 96
DOSLOADMODULE 44
DOSLOCKSEG 122
DOSMAKEPIPE 16
DOSMEMAVAIL 127
DOSMKDIR 66
DOSMOVE 67
DOSMUXSEMWAIT 22
DOSNEWSIZE 68
DOSOPEN 70
DOSOPEN2 95
DOSOPENSEM 25
DOSPHYSICALDISK 129
DOSQPATHINFO 98
DOSSETPATHINFO 104
DOSPOKETESTDAEMON 104
DOSPORTACCESS 69
DOSPROFILE 133
DOSPTRACE 12
DOSQCURDIR 71
DOSQCURDISK 72
DOSQFHANDSTATE 73
DOSQFILEINFO 74
DOSQFILEMODE 75
DOSQFSINFO 76
DOSQHANDTYPE 77
DOSQPROCSTATUS 154
DOSQTRACEINFO 93
DOSQVERIFY 78
DOSREADPHYS 103
DOSREALLOCHUGE 42
DOSREALLOCSEG 38
DOSRESUMETHREAD 26
DOSRMDIR 80
DOSSELECTDISK 81
DOSSEMSETWAIT 20
DOSSENDSIGNAL 134
DOSSETCP 153
DOSSETDATETIME 28
DOSSETFGND 101
DOSSETFHANDSTATE 82
DOSSETFILEINFO 83
DOSSETFILEMODE 84
DOSSETFSINFO 97
DOSSETINFOSEG 128
DOSSETMAXFH 85
DOSSETPRTY 11
DOSSETSIGHANDLER 14
DOSSETVEC 89
DOSSETVERIFY 86
DOSSGSWITCH 54
DOSSGSWITCHME 55
DOSSGSWITCHPROC 124
DOSSICG 95
DOSSIZESEG 126
DOSSLEEP 32
DOSSUSPENDTHREAD 27
DOSSWAPTASKINIT 102
DOSSYSTEMSERVICE 88
DOSSYSTRACE 90
DOSTIMERASYNC 29
DOSTIMERSTART 30
DOSTIMERSTOP 31
DOSUNLOCKSEG 123
GETADDR 111
GETHEADERS 108
GETSELADDR 110
PANICWRITE 105
STRUCHECK 106
STRURESUPDATE 107
UNUSEDA 98
UNUSEDB 99
The following Operating System entry points are defined in the library
DOSCALL1. In this case, the procedures must be called by name rather than
ordinal value. For an example of this usage, see the explanation of the
DYNALINK() function.
DOSREAD
DOSWRITE
DOSERRCLASS
DOSSEMREQUEST
DOSSEMCLEAR
DOSSEMWAIT
DOSSEMSET
DOSEXECPGM
DOSCREATETHREAD
DOSSUBSET
DOSSUBALLOC
DOSSUBFREE
DOSREADASYNC
DOSWRITEASYNC
DOSSEARCHPATH
DOSSCANENV
ΓòÉΓòÉΓòÉ 15. Advanced Compiler Features ΓòÉΓòÉΓòÉ
Advanced compiler features.
ΓòÉΓòÉΓòÉ 15.1. Compile time variables ΓòÉΓòÉΓòÉ
Compile time variables.
ΓòÉΓòÉΓòÉ 15.1.1. Definition ΓòÉΓòÉΓòÉ
E provides certain language extensions and configuration options by means of a
single pass symbol table access facility. This means that the macro programmer
can assign a compile time variable and later test the value of that variable.
ΓòÉΓòÉΓòÉ 15.1.2. Advantages ΓòÉΓòÉΓòÉ
The usage of compile time variables can aid in the portability of the macro
language. This means that one set of macros can be used in DOS, OS/2, and the
Presentation Manager environments. For examples of this see the current
E-macros. By testing the version, the compiler can know which code to include.
This means later versions can make use of the newest features while still
maintain compatibility with older versions of the E family of editors.
The usage of compile time variables saves disk space. The reason for this is
that universal variables must be actually saved on the disk in the resultant
.EX file. Compile-time variables are saved in far memory while the translation
process executes and are freed when the translation process ends.
ΓòÉΓòÉΓòÉ 15.1.3. Compile-time variable assignment ΓòÉΓòÉΓòÉ
We allow a compile-time variable assignment by means of the define statement in
the macro language. An example of such as assignment is the following:
define compile_variable = 'this is a compile-time variable'
In addition, the C preprocessor #define is supported, in order to allow sharing
*.H files between C code and E macro code.
#define MB_OK 0000
#define MB_OKCANCEL 0001
Note: Starting with EPM 6.03 in May, 1995, the letter L may immediately follow
a numeric constant on a #define statement, and will be ignored. This is
to allow sharing *.H files containing definitions such as:
#define WS_VISIBLE 0x80000000L
#define WS_DISABLED 0x40000000L
ΓòÉΓòÉΓòÉ 15.1.4. Compile-time variable and conditional compilation ΓòÉΓòÉΓòÉ
Compile-time variables can be used in concert with the translator's compile if
statements to provide a powerful conditional compilation facility. An example
of the usage of compile if is the following:
compile if compile_variable = 'this is a compile-time variable'
sayerror 'compile_variable exists'
compile else
sayerror 'compile_variable does not exists'
compile endif
ΓòÉΓòÉΓòÉ 15.1.5. Compile `defined' test ΓòÉΓòÉΓòÉ
In addition to the straightforward test of a compile-time variable value, we
can also test whether a variable is defined or not. This is useful in cases
where the macro programmer does not wish to expressly assign a value to a
compile-time variable, but simply would like to know if the variable has any
value. For example:
compile if defined(compile_variable)
sayerror 'compile_variable is defined'
compile else
sayerror 'compile_variable is not defined'
compile endif
ΓòÉΓòÉΓòÉ 15.1.6. Text replacement ΓòÉΓòÉΓòÉ
A powerful text replacement function is part of the translator language. This
text replacement option allows one to literally change the text upon which the
translator is operating during the translation process. The text replacement
option is initiated when the translator encounters a '$' (dollar sign). When
the text replacement character is encountered the translator places the value
of the compile-time variable that follows the '$' into a text buffer and begins
to use the that buffer as the input buffer to the translator. When the buffer
is empty, we switch back to the previous translation buffer. For example:
define sayinformation = 'sayerror'
$sayinformation 'this is information'
In the preceding example, we have defined our own language extension. The
example is equivalent to the standard E code of:
sayerror 'this is information'
ΓòÉΓòÉΓòÉ 16. Toolbar ΓòÉΓòÉΓòÉ
EPM version 6 introduces a user-configurable Toolbar, using the UCMENUS package
(which EPM uses as ETKUCMS.DLL). The built-in toolbar is defined in the macros.
The user can configure the toolbar to execute any of the available toolbar
actions, which are defined in the *.ex files listed in the ACTIONS.LST file, or
any other EPM or OS/2 command by selecting either * or ExecuteProgram as the
action to be executed. * executes its parameter as though it were entered on
the EPM command line, while for ExecuteProgram, the parameters are executed
directly by the UCMENUS code as an external program.
See the following sections for additional information.
o Building a toolbar from the macros
o The ACTIONS.LST file
o Creating a toolbar actions file
ΓòÉΓòÉΓòÉ 16.1. Building a toolbar from the macros ΓòÉΓòÉΓòÉ
The default toolbar is built in STDCTRL.E, in the loaddefaulttoolbar command. A
toolbar is another type of menu, and as such is built using the buildsubmenu
opcode. The first paramater to buildsubmenu consists of a delimiter character,
the button text, the delimiter, the button bitmap (the name of a *.BMP file, or
a number corresponding to a built-in resource ID), the delimiter, the command
to be executed, the delimiter, the command's parameters (if any), the
delimiter, and the name of the *.ex file in which the command is defined.
ΓòÉΓòÉΓòÉ 16.2. The ACTIONS.LST file ΓòÉΓòÉΓòÉ
The ACTIONS.LST file contains a list of actions files. When the user selects
Edit item from the toolbar's pop-up menu, the LOAD_ACTIONS command (defined in
STDCTRL.E) is executed. The first time it is executed, the ACTIONS.LST file is
searched for (using findfile with the 'D' option) and loaded. Each line in the
file contains the name of an actions file. For each line, the corresponding
action_name.ex file is linked, the action_name_actionlist command is executed
to obtain a list of actions defined in that file, and the .ex file is unlinked.
The resulting list of available actions is passed to the UCMENUS code, which
uses it to fill the Function listbox on the Action page of the configuration
dialog.
ΓòÉΓòÉΓòÉ 16.3. Creating a toolbar actions file ΓòÉΓòÉΓòÉ
A toolbar actions file is simply a filename.ex file which contains a
filename_actionlist command. When a list of actions is generated, the
filename_actionlist command is executed, and it adds one line for each action
it defines to the file whose fileid is contained in the universal variable
ActionsList_FileID. Each line added consists of a delimiter character, the
name of the action, the delimiter, a string to go in the Function description
section of the Action page of the Toolbar's configuration dialog, the
delimiter, and finally the name of the .ex file in which the action command is
defined.
An action command is a normal DEFC, but it must expect to be invoked by way of
the toolbar. This is because the action command is passed a parameter
consisting of a letter, possibly followed by a space and then the parameters
entered in the Parameters field of the Action page of the Toolbar's
configuration dialog. The possible values for the letter are:
I Initialized - the toolbar button has been depressed. A prompt may be
given, indicating what action will be performed if this toolbar item is
selected, but no other action should be performed.
S Selected - the toolbar button has been selected. The action associated
with this button should be performed.
E Ended - either the initialization or selection has ended. Nothing is
normally done when this parameter is passed.
H The user has asked for help, by pressing F1 while the button associated
with this action was initialized. Some of the supplied toolbar actions
invoke the OS/2 Help manager and bring up a panel in the standard EPM.HLP
(e.g., most of the ones in SAMPACTN.E); some provide their own help file,
which they dynamically add (e.g., TREE.E), and some just pop up a message
box containing their prompt string (e.g., JOT.E).
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
An alternative approach might involve having a handle to an attribute record.
In such an approach one can still refer to an attribute record by the same
handle even if the attribute record changes location. On the other hand,
implementation of this approach is often inefficient because it often includes
generation of new handles when text containing attributes is copied so that a
handle only refers to a single attribute record.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Note in this diagram, the attribute records are delimited by brackets.
Throughout this document I will only use brackets to delimit attribute records.
To avoid confusion, I will refrain from using brackets as a textual character
in my examples. The use of capital letters here between brackets is only used
in this example as a means of referring to individual attribute records. In
other examples in this document, I might actually put words or numbers between
the brackets if I want to denote some characteristic of an attribute record.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
The last character of line in the example is the "h". There is an attribute
record located immediately to the right of that character. Because it is at
the end of the line there is no character to the right of it. This is
acceptable because there is a virtual character to the right of it. (In the
case of line mode, there is a virtual space, and in the case of stream mode
there is a virtual CR/LF or questionably a soft linebreak.) The F attribute
record in the example is a slightly different situation. It is similar in that
its positional notation is derived from the assumed existence of virtual spaces
beyond the end of line. It differs from the previous attribute record in that
its location is invalid in stream mode and may not be effectively supported by
some operations.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
The exception to this is the '/' (search) command. When this command is
invoked, E searches for the 'L' command definition.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
DEFC's and DEFPROC's cannot be redefined. CONSTants can be redefined (to the
same value) without penalty.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
The ET compiler does a simple substitution for every occurrence of a constant.
If you define a long string constant and reference it ten times, its value is
included ten times and takes up ten times its length in the resulting EX file.
You might prefer to make a long string value a universal variable rather than a
constant.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
By "event" we mean a procedure that is automatically invoked when a certain
condition becomes true. Previous examples are DEFINIT (executed when you start
the editor or a new module) and DEFEXIT (executed when you quit the editor or a
module). In a sense keystrokes are also events, and in the past we sometimes
called events "pseudo-keys".
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Understand that the word var is only a notational convenience. Do not include
the word literally in your program.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
AF_ constants:
AF_CHAR = 1 -- 'key' represents an ASCII value
AF_VIRTUALKEY = 2 -- 'key' is a VK_ constant
AF_SCANCODE = 4 -- 'key' represents a keyboard scan code
AF_SHIFT = 8 -- The Shift key must be pressed along with 'key'
AF_CONTROL = 16 -- The Control key must be pressed along with 'key'
AF_ALT = 32 -- The Alt key must be pressed along with 'key'
AF_LONEKEY = 64 -- 'key' is a shift key, but is used by itself
AF_SYSCOMMAND = 256 -- 'index' should be sent in a WM_SYSCOMMAND message
AF_HELP = 512 -- 'index' should be sent in a WM_HELP message
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
See the OS/2 2.x Presentation Manager Reference from the OS/2 2.x Toolkit for a
description of the various menu styles. Assuming that you have the toolkit
installed on your system, you can enter the command
view PMREF Menu Item Styles
to see the menu styles, and can edit \toolkt2x\c\os2h\pmwin.h to determine what
value to specify for each style.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
See the OS/2 2.x Presentation Manager Reference from the OS/2 2.x Toolkit for a
description of the various menu attributes. Assuming that you have the toolkit
installed on your system, you can enter the command
view PMREF Menu Item Attributes
to see the menu attributes, and can edit \toolkt2x\c\os2h\pmwin.h to determine
what value to specify for each attribute.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
As described in the OS/2 Technical Reference Manual section 2.3.8.1 entitled
Dynamic Linking.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
In the 'printable_char' cases, the keyname must be quoted in an E program. For
example, the following example redefines the '~' key on the keyboard to toggle
the cursor between the text and the command dialog box, and redefines some of
the alphabetic keys to produce help information: def '~' = command_toggle
def 'a' - 'z' = 'help' However, the rest of the keynames need not be quoted,
e.g. KEY c_end
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
In all constructs which require a numeric_term, a numeric value is expected.
The following can be substituted for a number:
o the name of a variable representing a numeric value, or
o a procedure call which returns a numeric value
Starting with EPM 6.03 in May, 1995, a numeric term may also be given as a
hexadecimal number, in the format 0Xhhhh, where hhhh represents 1 to 8
hexadecimal digits.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
In all constructs which require a string_expression, a string value is
expected. The following can be substituted for a string:
o the name of a variable representing a string, or
o a procedure call which returns a string
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
In a constant_expression, any identifiers or designators must be the names of
constants; no variables are permitted.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
There may not be spaces between the identifier and the '('.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
A macro-defined command is any command defined using a DEFC construct in the E
macro code, whether it is part of the distributed macros written by the E
developers or added later by a user. For an example of such a DEFC construct,
see section Using EPM Commands in E Statements.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Note: Two double quotes inside a double-quoted string will output one double
quote character. For example, the string: "She said, ""Oh, that's
fascinating."" " will yield the following output: She said, "Oh, that's
fascinating." There can be no spaces between the two double quotes.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Note: Two single quotes inside a single-quoted string will output one single
quote character. For example, the string: 'I went to Jim Kennedy''s house'
will yield the following output: I went to Jim Kennedy's house. There can be no
spaces between the two single quotes.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
Any number to be interpreted or manipulated by the editor cannot exceed 32,767.