Enable word wrap check box, or by clicking the Wrap

+/- button on the program window.

When autowrapping is turned off via the option menu,
you may elect to show program line numbers in your
program window by selecting Display line numbers.
You may then right-click anywhere in your program
and select Go To Line... to jump directly to a specific
line number.
If you desire greater control over the appearance of
your lines, you can manually break long lines using the
ENTER key, and then use the underscore continuation
character _ as the last character on the line to join the
multiple lines. For example, the three separate lines of
text
equation eq1.ls _
yxc_
ar(1) ar(2)
are equivalent to the single line
equation eq1.ls y x c ar(1) ar(2)
formed by joining the lines at the continuation
character. We emphasize that the _ must be the very
last character in the line.
The apostrophe ' is the comment character in
programs. You may place the comment character
anywhere in a line to treat all remaining characters in
the line as a comment which will be ignored when
executing the program command.
equation eq1.ls y x c ar(1) ar(2) this is a comment
A block of lines may be commented or uncommented
in the EViews program file editor by highlighting the
lines, right-mouse clicking, and selecting Comment
Selection or Uncomment Selection.
You can instruct EViews to automatically format your
program by selecting the lines to which you wish to
apply formatting, right-mouse clicking and selecting
Format Selection. Automatic formatting will clean up
the text in the selection, and will highlight the structure
of the program by indenting lines of code inside loops,
if conditions and subroutines, etc. You should find that
automatic formatting makes your programs easier to
read and edit.
You may elect to have EViews automatically indent
your program as you type by changing the Indent
option in the main EViews options menu
(Options/General Options/Programs).

Program Basics
What is a Program?
Creating a Program
Program Formatting
Saving a Program
Saving the Command Window
Encrypting a Program
Opening a Program
Executing a Program
The Run Program Dialog
The Run and Exec Commands
External Automation Tools
Stopping a Program
Running Part of a Program
What is a Program?
A program is simply a text file containing EViews
commands. It is not an EViews object in a workfile. It
exists as a file on your computer hard disk, generally
with a .PRG extension.
Creating a Program
To create a new program, click File/New/Program.
You will see a standard text editing window where you
can type in the lines of the program. You may also
open the program window by typing program in the
command window, followed by an optional program
name. For example
program firstprg
opens a program window named FIRSTPRG.
Program names should follow standard EViews rules
for file names.
Program Formatting
As noted earlier, an EViews program is a text file,
consisting of one or more lines of text. Generally, each
line of a program corresponds to a single EViews
command, so you may enter the text for each
command and terminate the line by pressing the
ENTER key.
If a program line is longer than the current program
window, EViews will, by default, autowrap the text of
the line. Autowrapping alters the appearance of the
program line by displaying it on multiple lines, but
does not change the contents of the line. While resizing
the window will change the autowrap position, the text
remains unchanged and is still contained in a single
line. You may turn off autowrapping in programs via
Options/General Options/Programs and deselecting the

Saving a Program
After you have created and edited your program, you
will probably want to save it. Press the Save or SaveAs
button on the program window toolbar. When saved,
the program will have the extension .PRG.
1

If saving your program will overwrite an existing

program file and you have instructed EViews to make
backup
copies
(Programs),
EViews
will
automatically create the backup. The backup copy will
have the same name as the file, but with the first
character in the extension changed to ~.

open mysp500.prg
open "c:\mywork is here\eviews\myhouse.prg"
open the file Mysp500.PRG in the default EViews
directory, and Myhouse.PRG located in the directory
c:\mywork is here\eviews.
Executing a Program
Executing a program is the process of running all of
the commands in a program file.
Note that EViews commands can be executed in two
distinct ways. When you enter and run, line by line, a
series of commands in the command window, we say
that you are working in interactive mode.
Alternatively, you can type all of the commands in a
program and execute or run them collectively as a
batch of commands. When you run the commands
from a program file, we say that you are in (noninteractive) program mode or batch mode.
There are several ways to execute an EViews program:
The easiest method is by pushing the Run button on
an open program window and entering settings in the
Run Program dialog.
Alternately, you may use the run or exec command to
execute a program.
You may use external automation tools to run
EViews and execute a program from outside of the
EViews application environment.
You may select a set of subset of lines to execute and
run the selected lines.

Saving the Command Window

One convenient method of creating a program is to
execute several commands using the EViews
command window and then save the history of those
commands to a program file. Click in the command
window then select File/Save As... from the main
EViews menu. EViews will prompt you to save the
command log as a text file. Simply save the file with
the .PRG extension.
You may then edit the program file and save the edited
version in the usual fashion.

Encrypting a Program
EViews offers you the option of encrypting a program
file so that you may distribute it to others in a form
where they may not view the original text. Encrypted
files may be opened and the program lines may be
executed, but the source lines may not be viewed. To
encrypt a program file simply click on the Encrypt
button on the program window.
EViews will create an untitled program containing the
contents of the original program, but with only the
visible text Encrypted program. You may save this
encrypted program in the usual fashion using Save or The Run Program Dialog
SaveAs.
Note that once a program is encrypted it may not be
unencrypted; encryption should not be viewed as a
method of password protecting a program. You should
always keep a separate copy of the original source
program. To use an encrypted program, simply open it
and run the program in the usual fashion.
Opening a Program
To load a program file previously saved on disk, click
on File/Open/Program..., navigate to the appropriate
directory, and click on the desired name. You may also
drag an EViews program file onto the EViews window
to open it. Alternatively, from the command line, you
may type the keyword open followed by the full
program name, including the file extension .PRG.
By default, EViews will look for the program in the
default directory, but you may include the full path to
the file and enclosed the entire name in quotations, if
desired. For example, the commands:

To run a program from a dialog, click on the Run

button on the program window. The Run dialog opens.
The default run options are taken from the global
settings (Programs), but may be overridden on a onetime basis using the dialog settings or command
options. For purposes of discussion, we will assume
that the global options are set to their out-of-the-box
values.
2

The Program name or path edit field will show the

name and in some cases, path, of the program you are
running. You may enter a file specification to instruct
EViews to look for a particular program.
The Program arguments edit field is used to define
special string variables that will be passed to your
program when it is running. See Program Arguments
for details.
The Runtime errors section allows you to modify the
behavior of the program when it encounters an error.
By default, when EViews encounters an error, it will
immediately terminate the program and display a
message. If you enter a number into the Maximum
errors before halting field, EViews will, if possible,
continue to execute the program until the maximum
number of errors is reached. If it encounters a serious
error that makes it impossible to continue, EViews will
halt the program even if the maximum number of
errors is not reached. See Execution Errors.
If the Compatibility section checkbox labeled Version
4 compatible variable substitution and program
boolean comparisons is selected, EViews will use the
variable substitution behavior found in EViews 4 and
earlier. To support the use of alpha series, EViews 5
and subsequent versions altered the way that %
substitution variables are evaluated in expressions. To
return to EViews 4 compatible rules for substitution,
you may either use this checkbox or include a MODE
VER4 statement in your program. See Version 4
Compatibility Notes and Program Modes for
additional discussion.
Lastly, you may select the Save options as default
checkbox to update your global options with the
specified settings. Alternately, you may change the
global
options
from
the
Options/General
Options.../Programs/General dialog.

The default run options will be taken from the global

settings (Programs ), but may be overridden using
the command options. For example, you may use the
v or verboseoptions to run the program in verbose
mode, and the q or quiet options to run the
program in quiet mode. If you include a number as an
option, EViews will use that number to indicate the
maximum number of errors encountered before
execution is halted:
run(v, 500) mysp500
or
run(q, ver4) progarg
Alternatively, you may modify your program to
include statements for quiet or verbose mode, and
statements to specify version compatibility. For
example, to return to EViews 4 compatible rules for
substitution, you may use the ver4 option or include
a MODE VER4 statement in your program. See
Version 4 Compatibility Notes and Program
Modes for additional discussion.
You may provide a list of program arguments after the
name of the program. These arguments will be passed
on to the program as %0, %1 etc. See Program
Arguments for more details.
Program options may be passed on to the program by
entering them, surrounded by parenthesis immediately
after the name of the program. See Program Options
for details.
For example:
run myprog(opt1, opt2, opt3=k) arg0 arg1 arg1
will run the program MYPROG passing on the options
OPT1, OPT2, OPT3=k as options, and ARG0, ARG1
and ARG1 as arguments (%0, %1 and %2
respectively).
You may have launch EViews and run a program
automatically on startup by choosing File/Run from the
menu bar of the Windows Program Manager or
Start/Run in Windows and then typing eviews,
followed by the name of the program and the values of
any arguments. If the program has as its last line the
command exit, EViews will close following the
execution of the program.
The exec command is similar to the run command. It
can also be used to execute a program file. The main
differences between run and exec commands are the
default directory they will run from, and the behavior
when returning from executing a program. For more
details see Multiple Program Files.

The Run and Exec Commands

You may use the run command to execute a program
from the EViews command window. Simply enter the
keyword run along with any options, followed by a
program file specification and any arguments (see run).
You may run a program by entering the run command,
followed by the name of the program file:
run mysp500
or, using an explicit path,
run c:\eviews\myprog arg1 arg2 arg3
Note that use of the .PRG extension is not required
since EViews will automatically append one to your
specification.
3

properly when the selected lines are run. Finally, any

subroutines declared outside of the selected lines of
code cannot be called, since they do not exist in the
selected code.
Alternately, you may use add the stop command to
your EViews program to halt execution at a particular
place in the program file.

External Automation Tools

Lastly, you may use external automation tools to run
EViews and execute a program from outside of the
EViews application environment. In particular,
EViews may be used as a COM Automation server so
that an external program or script may launch and
control EViews programmatically. See EViews COM
Automation Server and the EViews COM
Automation Server whitepaper, available from our
website www.eviews.com/download/download.html,
for additional discussion.

Last updated: Tue, 18 Oct 2016 23:23:46 PST

Simple Programs

The simplest program is just a list of EViews

Stopping a Program
commands. Execution of the program is equivalent to
Pressing the ESC or F1 keys halts execution of a typing the commands one-by-one into the command
program. It may take a few seconds for EViews to window.
respond to the halt command.
Programs will also stop when they encounter a stop While you may execute the commands by typing them
command, when they reach the maximum number of in the command window, you could just as easily open
errors, when they encounter a non-recoverable error in
a program window, type in the commands and click on
a program statement, or when they finish processing a
the Run button. Entering commands in this way has the
file that has been executed via a run statement.
If you include the exit keyword in your program, the advantage that you can save the set of commands for
later use, and execute the program repeatedly, making
EViews application will close.
minor modifications each time. (Note that you may
Running Part of a Program
combine the two methods by entering the commands in
You may choose to only run part of your program by the command window and then save them to a file as
highlight the lines you wish to run, then right-clicking
described in Saving the Command Window.)
and selecting Run Selected. EViews will then execute
only the selected line of code as a new program.
Since an EViews program is a collection of commands,
familiarity with the EViews command language is an
essential part of programming. The command language
may be split into four different groups in EViews.
General commands create, structure and manipulate
workfiles (including importing and exporting data) and
create workfile objects. These commands are listed in
Command Reference.
Object commands execute views and procedures on
objects in the workfile (such as series, groups and
equations).
For example, unit root tests are done via a series
command (series.uroot), co-integration tests are a
group command (group.coint), and regression and
forecasting are performed via equation commands
(equation.ls and equation.forecast). The full set of
object commands can be found in Object View and

You should note that there are potential pitfalls when

using Run Selected. The first is that no arguments or
options can be passed into the selected lines of code. If
the selected lines rely on program arguments or
options, they will fail to execute properly. Similarly,
any program variables (Program Variables) declared
outside of the selected lines may not be initialized
4

Procedure Reference, where they are listed by object in the command window. In the program window that
type.
opens for MYPROG, we are going to enter the
commands to create a workfile, fetch a series from an
Functions may be used to create new data, either in EViews database named PROGDEMO, run a
the form of workfile objects or as program variables.
regression, compute residuals and a forecast, make a
Creating a new series that is equal to the moving plot of the forecast, and save the results.
average of an existing series is done with the @movav
function. The @rbinom function is used to generate a
random scalar or series from the binomial distribution.
@pagefreq may be used to generate a string object or
program variable containing the frequency of the
current workfile page. In general, functions all start
with the @ symbol.

' housing analysis

wfcreate(wf=myhouse) m 1968m3 1997m6
fetch progdemo::hsf
smpl 1968m5 1992m12
equation reg1.ls hsf c hsf(-1)

Listings of the available @-functions available can be

found in (here)19 (Operator and Function
Reference, Operator and Function Listing,
Workfile
Functions,
Special
Expression
Reference, String and Date Function Reference,
Matrix Language Reference, and Programming
Language Reference).

reg1.makeresid hsfres
smpl 1993m1 1997m6
reg1.forecast hsffit
freeze(hsfplot) hsffit.line
save

Object data members allow you to retrieve a

fundamental piece of data from an object. Unlike
object commands that execute a view or procedure on
an object, data members merely provide access to
existing results. Data members almost all start with an
@ symbol and can be accessed by typing the name of
the object followed by a . and the name of the data
member.

The first line of the program is a comment, as denoted

by the apostrophe '. In executing a program, EViews
will ignore all text following the apostrophe until the
end of the line.
The line containing the wfcreate command creates a
new workfile, called MYHOUSE, with a monthly
frequency spanning the dates March 1968 to June
1997. A series called HSF (total housing units started)
is fetched from the database PROGDEMO. The rest of
the program results in a saved workfile named
MYHOUSE containing the HSF series, an equation
object REG1, residual and forecast series HSFRES and
HSFFIT, and a graph HSFPLOT of the forecasts.

For example, eq1.@coefs returns a vector containing

the estimated coefficients from the equation object
EQ1. ser01.@last returns a string containing the date
(or observation number) of the last non-NA value in
the series SER01. The list of data members available
for each object is listed in the objects section of
Object View and Procedure Reference.

You can run this program by clicking on Run and

Lets examine a simple example (the data series are
filling in the dialog box.
provided in the database PROGDEMO in your EViews
directory so that you can try out the program). Create a Now, suppose you wish to perform the same analysis,
new program by typing
but for the S&P 500 stock price index (FSPCOM). Edit
the program, changing MYHOUSE to MYSP500, and
program myprog
change all of the references of HSF to FSPCOM:
5

' s&p analysis

In the remainder of this section we describe the use of

these two types of program variables.

wfcreate(wf=mysp500) m 1968m3 1997m6

Control Variables

fetch progdemo::fspcom

Control variables are program variables that you can

use in place of numeric values in your EViews
programs. Once a control variable is assigned a value,
you can use it anywhere in a program that you would
normally use a number.

smpl 1968m5 1992m12

equation reg1.ls fspcom c fspcom(-1)
reg1.makeresid fspcomres
smpl 1993m1 1997m6

It is important to note that control variables do not

exist outside of your program and are automatically
reg1.forecast fspcomfit
deleted after a program finishes. In this regard, control
variables should not be confused with scalar objects as
freeze(fscomplot) fspcomfit.line
the former are not saved when you save the workfile.
save
You can save the values of control variables by
creating new EViews objects which contain the values
Click on Run to execute the new analysis. Click on the
of the control variable.
Save button to save your program file as
MYPROG.PRG in the EViews directory.
The name of a control variable starts with an !
character. After the !, the name should be a legal
EViews name of 23 characters or fewer (leading
numbers are allowed). Examples of control variable
names are:

Since these two programs are almost identical, it seems

inefficient to have two separate programs for
performing the analysis. In Program Arguments we
describe a method for performing these two forecasting
problems using a single program. First however, we
must define the notion of program variables that exist
solely when running programs.

!x
!1
!counter

Last updated: Tue, 18 Oct 2016 23:23:46 PST

Program Variables
Control Variables

You need not declare control variables, but you must

assign them values before use. Control variable values
are assigned in the usual way, with the control variable
name on the left of an = sign and a numerical value
or expression on the right. For example:

String Variables
Replacement Variables

While you can use programs just to run, and re-run

!x = 7
collections of EViews commands, the real power of the
EViews programming language comes from the use of !12345 = 0
program variables and program control statements.
!counter = 12
Program variables are variables that you may use in
place of numeric or string values in your EViews !pi = 3.14159
programs. Accordingly, there are two basic types of Once assigned a value, a control variable may appear
program variables: control (numeric) variables and in an expression. For example:
string variables.
6

!counter = !counter + 1

String Variables

genr dnorm = 1/sqr(2*!pi)*exp(-1/2*epsilon^2)

A string expression or string is text enclosed in double

quotes:

scalar stdx = x/sqr(!varx)

"gross domestic product"

smpl 1950q1+!i 1960q4+!i

"3.14159"

For example, the following commands:

"ar(1) ar(2) ma(1) ma(2)"

scalar stdx = sqr(!varx)

A string program variable is a program variable whose

value is a string of text. String variables, which exist
only during the time that your program is executing,
sample years 1960+!z 1990
have names that begin with a % symbol. String
use the numeric values assigned to the control variables should not be confused with String Objects
variables !VARX, !LENGTH, and !Z.
which are objects that exist in a workfile.
c(100) = !length

It is important to note that control variables are used in

programs via text substitution. Whenever EViews
encounters a control variable in a program it
substitutes the text value of that variable into the
program. One of the implications of the text
substitution is that you may lose some numeric
accuracy when using a program variable due to the
conversion in to and out of a text representation of the
number.

String variables are assigned by putting the string

variable name on the left of an = sign and a string
expression on the right. For example, the following
lines assign values to string variables:
%value = "value in millions of u.s. dollars"
%armas = "ar(1) ar(2) ma(1) ma(2)"
%mysample = " 83m1 96m12"

A second unintended consequence of text substitution %dep = " hs"

can arise when raising a negative control variable to a
%pi = " 3.14159"
power:
You may use strings variables to help you build up
command text, variable names, or other string values.
!b = !a^2
EViews provides a number of operators and functions
for manipulating strings; a complete list is provided in
When evaluating these lines, EViews will substitute Strings.
the value of !A in the second line, leaving the line:
Once assigned a value, a string variable may appear in
!b = -3^2
any expression in place of the underlying string. When
Which it then evaluates as 9 (since the square substituted for, the string variable will be replaced by
operator takes precedence over the negation operator), the contents of the string variable, enclosed in double
quotes.
rather than the expected 9.
!a = -3

You should also take care to avoid inadvertent Here is a simple example where we use string
replacement of program variables, as outlined in operations to concatenate the contents of three string
variables.
Replacement Variables.
7

!repeat = 500

creates a control variable !LEVEL=0.05. If the string

cannot be evaluated to a number, @val returns the
value NA.

%st1 = " draws from the normal"

%st2 = "Cauchy "

String variables are closely related to the concept of a

%st3 = @str(!repeat) + @left(%st1,16) + %st2 + string object (String Objects). A string object is an
EViews workfile object that holds a string:
"distribution"
string a = "Hello World"

In this example %st3 is set to the value 500 draws

from the Cauchy distribution. Note the spaces before
draws and after Cauchy in the string variable
assignments. After string variable substitution, the
latter assignment is equivalent to entering

string b = """First Name"" Middle ""Last Name"""

Unlike string variables, string objects are named
objects in the workfile that may exist apart from a
running program.

%st3 = "500" + " draws from the " + "Cauchy " +

"distribution"
In programming applications, string variables and
string objects are sometimes defined using string literal
Similarly, the table assignment statement
expressions as illustrated above. However, in most
settings, string variables and objects are defined using
table1(1,1) = %st3
results from string functions, or by manipulation of
is equivalent to entering the command
string lists and string vectors. For example, you could
use the @wlookup and @wsplit functions to obtain a
table(1,1) = "500 draws from the Cauchy distribution"
set of strings corresponding to the names of all of the
One important use for string variables is assigning series in a workfile. See Strings for a full discussion.
string values to string objects, string vectors, or Alpha
Replacement Variables
series. For example, we may have the assignment
statement
When working with EViews commands, you may wish
to use a string variable, not simply to refer to a string
%z = "Ralph"
value, but as an indirect way of referring to something
else, perhaps a command, or an object name, or portion
alpha full_name = %z + last_name
of names for one or more items.
which is equivalent to the expression
Suppose, for example, that we assign the string
alpha full_name = "Ralph" + last_name
variable %X the value GDP:
We again emphasize that string variable substitution %x = "gdp"
involves replacing the string variable by its string
We may be interested, however, not in the actual string
value contents, enclosed in double quotes.
variable value gdp, but rather in an EViews object
As with any string value, you may convert a string named GDP. Accordingly, we require a method of
variable containing the text representation of a number distinguishing between a string value and the item
into a number by using the @val function. For corresponding to the string value.
example,
If you enclose a string variable in curly braces ({
%str = ".05"
and }) EViews will replace the expression with the
name, names, or name fragment given by the string
!level = @val(%str)
8

value. In this context we refer to the expression If you wish to use a string variable %VAR to refer to
{%x} as a replacement variable since the string the INCOME series, you must use the replacement
variable %X is replaced in the command line by the variable in the @obs function, as in
name or names of objects to which the string refers.
%var = "income"
Suppose we want to create the series Y and set it equal
to the values in the series GDP. Given the string @obs({%var})
variable %X defined above, the series declaration,
since you wish to refer indirectly to the object named
in %VAR. Note that the expression

series y = %x

creates a numeric series Y and sets it equal to the string @obs(%var)

value gdp,
will return an error since @obs requires a series or
matrix object name as an argument.
series y = "gdp"
Any string variable may be used as the basis of a
replacement variable. Simply form your string using
one or more string operations

which generates an error since the series declaration

expects the name of a series or a numeric value, not a
string value. In this circumstance, we would like to
replace the string value with the name of an object.
With the replacement variable {%X}, the command

%object = "group"
%space = " "

series y = {%x}
%reg1 = "gender"
is properly interpreted as
%reg2 = "income"
series y = gdp
%reg3 = "age"
Similarly,
variables,

the

program

line

using

replacement
%regs = %reg1 + %space + %reg2 + %space + %reg3
then enclose the string variable in braces. In the
expression,

equation eq1.ls {%x} c {%x}(-1)

would be interpreted by EViews as

{%object} g1 {%regs}
equation eq1.ls gdp c gdp(-1)
EViews will substitute the names found in %OBJECT
Changing the contents of %x to M1 changes the and %REGS so that the resulting command is
interpretation of the original program line to
group g1 gender income age
equation eq1.ls m1 c m1(-1)
It is worth noting that replacement variables may be
since the replacement variable uses the name obtained used as building blocks to form object names. For
from the new value of %X.
example, the commands
To take another example, when trying to find the %b = "2"
number of valid (non-missing) observations in a series
named INCOME, you may use the @obs function %c = "temp"
along with the name of the series:
series z{%b}
@obs(income)
9

matrix(2, 2) x{%b}

!x = 10

vector(3) x_{%c}_y

series y = !x1

matrix named X2, where the first line has !X rather than !X1, EViews
will not generate an error due to the missing !X1
variable, but will instead evaluate the second line by
Up to this point, we have focused on replacement substituting !X into the expression, and evaluating the
variables formed from string variables. However, result as 101.
control variables may also be used to form replacement
Replacement variables may be constructed using
variables. For example, the commands
nested evaluation of replacement variables. Suppose
!i = 1
we have the strings:
declare a series named Z2, a
and a vector named X_TEMP_Y.

series y{!i} = nrnd

%str1 = "x"

!j = 0

%name = "%str1"

series y{!j}{!i} = nrnd

Then we can declare the series X and fill it with

random normals using the command

are equivalent to

series {{%name}} = nrnd

series y1 = nrnd

After evaluation of the innermost replacement variable,

the expression reduces to

series y01 = nrnd

and will create two series Y1 and Y01 that contain a
set of (pseudo-)random draws from a standard normal
distribution. Conveniently, in cases where there is no
possibility of ambiguity, EViews will treat a control
variable as a replacement variable, even if the braces
are not provided. For example:
!x = 3
series y!x = 4
will generate the series Y3 containing the value 4.

series {%str1} = nrnd

and then to
series x = nrnd
when we evaluate the remaining brace. The double
braces allow us perform a double replacement in which
the string variable used to form a replacement variable
is itself obtained as a replacement variable.
The double nested braces need not be adjacent. For
example:

While convenient, this loose interpretation of control

variables can, however, lead to unexpected results if %x1 = "x"
one is not careful. Take the following program:
%x2 = "y"
!x1 = 10
scalar x = 10
series y = !x1
scalar y = 20
This program will create a series equal to the value of
!X1 (i.e. 10). However if you were to mis-type the !y = 1
program slightly:
scalar r1 = {%x{!y}}
10

!y = 2

string LAGGDP = "GDP(-1) GDP(-2) GDP(-4)"

scalar r2 = {%x{!y}}

equation eq1.ls GDP C {LAGGDP}

First we create two string variables, %X1 and %X2,

and three scalar objects, X, Y, and R. First, the control
variable is !Y is set to 1 and the replacement variable
{!Y} is used to construct the name %X1 of a string
variable. The resulting replacement variable {%X1}
refers to the scalar object X. We assign the scalar X
value of 10 to the scalar R1. Next, we set !Y to 2, the
replacement variable {%X{!Y}} evaluates to Y, and
we assign the Y value of 20 to the scalar R2.

executes the command

equation eq1.ls GDP C GDP(-1) GDP(-2) GDP(-4)

In most respects, there is no difference between using a

string object or a string variable in a program. String
objects have the advantage that they may be used
interactively, outside of programs, while string
variables may not. This can be useful when debugging
a program; string variables disappear once the program
Multiple sets of braces may be used to create various has finished, making it difficult to identify problems in
their construction. Note that string objects do,
string names:
however, go out-of-scope when the active workfile
string uslabel = "USA"
page changes, while string variables are always in
scope.
string nzlabel = "New Zealand"
Lastly, while replacement variables provide you with
%a1 = "US"
great flexibility in referencing objects in your
programs, used carelessly, they can lead to confusion.
%a2 = "NZ"
We suggest, for example, that you avoid using similar
%b = "LABEL"
base names to refer to different objects. Consider the
following program:
!y = 1
' possibly confusing commands (avoid)
string label1 = {%a{!y}}{%b}
!a = 1
!y = 2
series x{!a}
string label2 = {%a{!y}}{%b}
!a = 2
First we create two string objects, USLABEL and
NZLABEL, which hold the label we wish to assign to matrix x{!a}
each country. Then we create the string variables %A1
and %A2 to hold the country abbreviations. When the In this code snippet, it is easy to see that X1 is the
control variable !Y=1, {%A{!Y}}{%B} evaluates to series and X2 is the matrix. But in a more complicated
the
object
USLABEL
and
when
!Y=2, program, where the control variable assignment !A=1
{%A{!Y}}{%B} evaluates to the object NZLABEL. may be separated from the declaration by many
Then the string LABEL1 contains USA and program lines, it may be difficult to tell at a glance
what kind of object X1 represents. A better approach
LABEL2 contains New Zealand.
might be to use different names for different kinds of
Replacement variables may also be formed using string variables:
objects in place of string variables. To use a string
object as a replacement variable, simply surround it !a = 1
with curly braces ({ and }). For example,
series ser{!a}
11

!a = 2
matrix mat{!a}

and multiple mode statements may be specified in a

program to change the mode as the program runs:

mode quiet
so that the meaning of replacement variable names are
more apparent from casual examination of the [some program lines]
program.
mode verbose
Last updated: Tue, 18 Oct 2016 23:23:47 PST
[additional program lines]
Program Modes
Note that setting the execution mode explicitly in a
Program Message Logging
program overrides any settings specified at the time the
program is executed.
Program modes describe different settings associated
with the execution of your program. You may, for Program Message Logging
example, choose to provide verbose messaging where
your program will echo each command to the status When executing a program in EViews, it may be
line, or you may choose quiet mode. Alternately, you useful to keep track of what is happening during
may wish to run a legacy program file in Version 4 execution. Log windows allow you to determine more
accurately the state of various objects in your workfile
compatibility mode.
or follow program progression.
EViews provides you with the opportunity to set
program execution modes at the time that the program Log windows may be switched on using the logmode
is first run. In addition, you may use the MODE command. One log window is created for each
statement to change the execution mode of a program program. If a program is executed more than once and
from within the program itself. One important benefit a log window has already been created, the log
to using MODE statements is that the program can window will be cleared and all subsequent messages
begin executing in one mode, and switch to a second will be sent to the existing log window. If you wish to
preserve a log, you may either save the log to a text file
mode as the program executes.
or freeze it, creating a text file object.
To change the mode for quiet or verbose mode, simply
add a line to your program reading MODE followed There are several types of messages which can be
by either the QUIET or the VERBOSE keyword, logged: program lines, status line messages, user log
messages, and program errors. When displayed in a log
as in
message, each type will appear in a different color,
mode quiet
making it easier to differentiate one type from another.
Program lines are echoes of the line of code in the
For version 4 compatibility, you should use the program currently being executed, and are displayed in
keyword VER4:
black. Status line messages are the messages displayed
in the status line (see The Status Line ) and appear in
mode ver4
blue. User log messages are custom messages created
as a line in the body of the program.
by the program via the logmsg command and appear in
green. Program errors are messages generated when a
Multiple settings may be set in a single MODE line:
logical or syntax error has occurred and appear in red.
mode quiet ver4

12

Last updated: Tue, 18 Oct 2016 23:23:47 PST

Program Arguments
Program arguments are special string variables that are
passed to your program when you run the program.
Arguments allow you to change the value of string
variables every time you run the program. You may
use them in any context where a string variable is
appropriate. Any number of arguments may be
included in a program. The individual arguments will
be available in the string variables %0, %1, %2,
and so on; the %ARGS variable will contain a space
delimited list of all the arguments passed into the
program.
When you run a program that takes arguments, you
may supply the values for the arguments. If you use the
Run button or File/Run, you will see a dialog box
where you can type in the values of the arguments. If
you use the run or exec command, you may list the
arguments consecutively after the name of the
program.
For example, suppose we have a program named
REGPROG:
equation eq1
smpl 1980q3 1994q1
eq1.ls {%0} c {%1} {%1}(-1) time
To run REGPROG from the command line with
%0=lgdp and %1=m1, we enter
run regprog lgdp m1
This program performs a regression of the variable
LGDP, on C, M1, M1(-1), and TIME, by executing the
command:
eq1.ls lgdp c m1 m1(-1) time
Alternatively, you can run this program by clicking on
the Run button on the program window, or selecting
File/Run.... In the Run Program dialog box that
appears, type the name of the program in the Program
name or path field and enter the values of the
arguments in the Program arguments field. For this
example, type regprog for the name of the program,
and lgdp and m1 for the arguments.
Any arguments in your program that are not initialized
in the Run Program dialog or run command are treated
as empty string variables. For example, suppose you
have a one-line program named REGRESS:
equation eq1.ls y c time {%0} {%1} {%2} {%3}
{%4} {%5} {%6} {%7} {%8}
The command,
run regress x x(-1) x(-2)
executes
equation eq1.ls y c time x x(-1) x(-2)
while the command,

run regress
executes
ls y c time
In both cases, EViews ignores arguments that are not
included in your run command.
As a last example, we repeat our simple forecasting
program from above, but use arguments to simplify our
work. Suppose you have the program MYPROG:
wfcreate(wf={%0}) m 1968m3 1997m6
fetch progdemo::{%1}
smpl 1968m5 1992m12
equation reg1.ls {%1} c {%1}(-1)
reg1.makeresid {%1}res
smpl 1993m1 1997m6
reg1.forecast {%1}fit
freeze({%1}plot) {%1}fit.line
save
The results of running the two example programs at the
start of this chapter can be duplicated by running
MYPROG with arguments:
run myprog myhouse hsf
and
run myprog mysp500 fspcom
Last updated: Tue, 18 Oct 2016 23:23:47 PST
Program Options
Much like program arguments, program options are
special string variables that may be passed to your
program when you run the program. You may specify
options by providing a comma separated list of options
in parentheses in the run or exec command statement,
immediately after the name of the program as in:
run myprogram(myoption1, myoption2)
Note that options are only supported via the command
line method using run or exec. You cannot pass an
option to a program when running a program via the
menus. Options are included via the command line by
entering them in parenthesis immediately following the
name of the program to be run.
In contrast with arguments, options may not be
accessed directly from within your program. Rather
you can only test for the existence of an option, or
retrieve part of an option. The @hasoption command
lets you test for the existence of an option. For
example, @hasoption("k") will return a value of 1 if

13

the k option was passed into the program at run time, example, if we were to name our above program as
or 0 if it was not.
MY PROG, then the correct method to issue options is:
@equaloption may be used to return the value to the
right of an equality sign in an option. For example if
cov=hac
is
entered
as
an
option,
@equaloption("cov") would return hac. If the option
was not entered at all, @equaloption will return an
empty string.

run "my prog"(file=myhouse, ls) hsf

Last updated: Tue, 18 Oct 2016 23:23:47 PST

Control of Execution
IF Statements
The FOR Loop
FOR Loops with Numerical Control Variables or
Scalars
For example, suppose you have the following program: FOR Loops with String Variables and String Objects
The WHILE Loop
%filename = @equaloption("file")
Execution Errors
Handling Errors
wfcreate(wf={%filename}) m 1968m3 1997m6
Stopping Programs
Exiting Loops
fetch progdemo::{%0}
if (@hasoption("LS")=1) then

EViews provides you with several ways to control the

execution of commands in your programs. Controlling
execution in your program means that you can execute
commands selectively or repeatedly under changing
conditions. The tools for controlling execution will be
familiar from other computer languages.

smpl 1968m5 1992m12

equation reg1.ls {%0} c {%0}(-1)
endif
If you were to run this program with:

IF Statements

run myprog(file=myhouse, ls) hsf

There are situations where you may want to execute

commands only if some condition is satisfied. EViews
uses IF and ENDIF, or IF, ELSE, and ENDIF
statements to indicate the condition to be met and the
commands to be executed.

the program would create a workfile called

MYHOUSE, would fetch a series called HSF, and
would then create an equation called REG1 by
performing least squares using the series HSF (for
discussion of the if condition used in this example,
An IF statement starts with the if keyword, followed
see IF Statements).
by an expression for the condition, and then the word
If we had run the program with just:
then. You may use AND/OR statements in the
condition, using parentheses to group parts of the
run myprog hsf
statement as necessary.
the workfile would not have been named (and would
All comparisons in the IF statement follow the rules
be given the default name of UNTITLED), and the
outlined in String Relational Operators and in
regression would not have been run.
Numeric Relational Operators. Note in particular
Note that if your program name has spaces or illegal that string comparisons are case-sensitive. You may
characters, it must be enclosed within quotes in run or perform caseless comparison using the @upper or
exec commands. In this case, program options should @lower string functions as in
be included after the closing quote without a space. For

if (@lower(%x) = "abc") then

14

or

series newage = age/!scale

if (@upper(%x) = "ABC") then

else

If the expression is true, all of the commands until the series newage = age
matching endif are executed. If the expression is false,
endif
all of these commands are skipped. For example,

endif

(It is worth noting that this example performs a

conditional recode in which the series NEWAGE is
assigned using one expression if a condition is true,
and a different expression otherwise. EViews provides
a built-in @recode function for performing this type of
evaluation; see @recode(s,x,y).)

if !a>5 and !a<10 then

IF statements may also be applied to string variables:

smpl 1950q1 1970q1+!a

if %0="CA" or %0="IN" then

endif

series stateid = 1

only generates the series GNPSTD and CONSTD and

sets the sample if the corresponding IF statements are
true. Note that we have indented the lines between the
if and the endif statements. The indentation is added
for program clarity and has no effect on the execution
of the program lines.

else

if !stand=1 or (!rescale=1 and !redo=1) then

series gnpstd = gnp/sqr(gvar)
series constd = cons/sqr(cvar)

if %0="MA" then
series stateid=2
else

The expression to be tested may also take a numerical if %0="IN" then

value. In this case, 0 and NA are equivalent to false series stateid=3
and any other non-zero value evaluates to true. For
endif
example,
if !scale then

endif

series newage = age/!scale

endif

endif

Note that the nesting of our comparisons does not

cause any difficulties.

executes the series statement if !SCALE is a nonYou should note when using the IF statement with
missing, non-zero value.
series or matrix objects that the comparison is defined
An IF statement may include a matching ELSE clause on the entire object and will evaluate to false unless
containing commands to be executed if the condition is every element of the element-wise comparison is true.
FALSE. If the condition is true, all of the commands Thus, if X and Y are series, the IF statement
up to the keyword else will be executed. If the
condition is FALSE, all of the commands between else if x<>y then
and endif will be executed. For example:
[some program lines]
if !scale>0 then
15

endif

for !j=1 to 10

evaluates to false if any element of X does not equal

the corresponding value of Y in the default sample. If
X and Y are identically sized vectors or matrices, the
comparison is over each of the elements X and Y. This
element-wise comparison is described in greater detail
in Relational Operators (=, >, >=, <, <=, <>).

series decile{!j} = (income<level{!j})

The FOR Loop

The commands inside the FOR loop are first executed

for the initial control value (unless that value is already
beyond the terminal value). After the initial execution,
the control variable is incremented by step and EViews
compares the new control variable value to the limit. If
the limit is exceeded, execution stops.

next

In this example, step=1 and the variable !j is twice

used as a replacement variable, first for the ten series
declarations DECILE1 through DECILE10 and for the
If you wish to operate on individual elements of a ten variables LEVEL1 through LEVEL10.
series on the basis of element-wise conditions, you We may add the step keyword and value to the FOR
should use the @recode function or use smpl loop to modify the step:
statements to set the observations you wish to change.
Element-wise operations on a vector or matrix should for !j=10 to 1 step -1
use comparisons of individual element comparisons
series rescale{!j}=original/!j
if x(3)=7 then
next
x(3) = 2
In this example, the step is -1, and !J is used as a
replacement variable in naming the ten constructed
endif
series RESCALE10 through RESCALE1 and as a
or the element-wise matrix functions (Matrix Element control variable scalar divisor in the series
Functions).
ORIGINAL.

The FOR loop allows you to repeat a set of commands

for different values of numerical or string variables.
The FOR loop begins with a for statement and ends
with a next statement. Any number of commands may
appear between these two statements.

The syntax of the FOR statement differs depending One important use of FOR loops with control variables
upon whether it uses numerical variables or string is to change the workfile sample using a smpl
command. If you add a control variable to a date in a
variables.
smpl command statement, you will get a new date as
FOR Loops with Numerical Control Variables or many observations forward as the current value of the
Scalars
control variable. Here is a FOR loop that gradually
increases the size of the sample and estimates a
To repeat statements for different values of a control recursive regression:
variable, you should follow the for keyword by a
control variable initialization, the word to, and then an for !horizon=10 to 72
ending value. After the ending value you may include
the word step followed by a number indicating an smpl 1970m1 1970m1+!horizon
amount to change the control variable each time the equation eq{!horizon}.ls sales c orders
loop is executed. If you dont include step, the step is
next
assumed to be 1. Consider, for example the loop:
16

One other important case uses loops and control for !i=1 to 25
variables to access elements of a matrix object. For
vector a!i
example,
!rows = @rows(vec1)

!i=!i+10

vector cumsum1 = vec1

next

Here, both the FOR assignment and the assignment

statement within the loop change the value of the
cumsum1(!i) = cumsum1(!i-1) + vec1(!i)
control variable !i. Loops of this type are difficult to
follow and may produce unintended results. If you find
next
a specific need to change a control variable inside the
computes the cumulative sum of the elements in the loop, you should consider using a WHILE loop (The
WHILE Loop) as an alternative to the FOR loop.
vector VEC1 and saves it in the vector CUMSUM1.
for !i=2 to !rows

To access an individual element of a series, you will You may execute FOR loops with scalars instead of
need to use the @elem function and @otod to get the control variables. However, you must first declare the
scalar, and you may not use the scalar as a replacement
desired element
variable. For example,
for !i=2 to !rows
scalar i
cumsum1(!i) = @elem(ser1, @otod(!i))
scalar sum = 0
next
vector (10) x
The @otod function returns the date associated with
the observation index (counting from the beginning of for i=1 to 10
the workfile), and the @elem function extracts the x(i) = i
series element associated with a given date.
sum = sum + i
You may nest FOR loops to contain loops within
loops. The entire inner FOR loop is executed for each next
successive value of the outer FOR loop. For example:
In this example, the scalar objects I and SUM remain
matrix(25,10) xx
in the workfile after the program has finished running,
unless they are explicitly deleted. When using scalar
for !i=1 to 25
objects as the looping variable you should be careful
that the scalar is always available white the FOR loop
for !j=1 to 10
is active. You should not, for example, delete the
xx(!i,!j)=(!i-1)*10+!j
scalar or change the workfile page within the FOR
loop.
next
FOR Loops with String Variables and String Objects
next
To repeat statements for different values of a string
You should avoid changing the control variable within
variable, you may use the FOR loop to let a string
a FOR loop. Consider, for example, the commands:
variable range over a list of string values. You should
list the FOR keyword, followed by the name of the
' potentially confusing loop (avoid doing this)
17

string program variable, followed by the list of values. the object name or replacement variable with curly
For example,
braces ({ }). For example,
for %y gdp gnp ndp nnp

string dates = "1960m1 1960m12"

equation {%y}trend.ls {%y} c {%y}(-1) time

%label = "year1"

next

for %1 %2 %3 {dates} {%label}

executes the commands

smpl {%1} {%2}

equation gdptrend.ls gdp c gdp(-1) time

equation {%3}eq.ls sales c orders

equation gnptrend.ls gnp c gnp(-1) time

next

equation ndptrend.ls ndp c ndp(-1) time

finds the three strings for the loop by taking two

elements of the string list and one element of the string
variable:

equation nnptrend.ls nnp c nnp(-1) time

You may include multiple string variables in the same smpl 1960m1 1960m12
FOR statementEViews will process the string values
in sets. For example, we may define a loop with list equation year1eq.ls sales c orders
three string variables:
Note the difference between using a FOR loop with
for %1 %2 %3 1955q1 1960q4 early 1970q2 1980q3 multiple string variables and using nested FOR loops.
mid 1975q4 1995q1 late
In the multiple string variable case, all string variables
are advanced at the same time, while with nested
smpl %1 %2
loops, the inner variable is advanced over all choices,
for each value of the outer variable. For example:
equation {%3}eq.ls sales c orders
next

!eqno = 1

In this case, the elements of the list are taken in groups for %1 1955q1 1960q4
of three. The loop is executed three times for the for %2 1970q2 1980q3 1975q4
different sample pairs and equation names:
smpl %1 %2
smpl 1955q1 1960q4
'form equation name as eq1 through eq6
equation earlyeq.ls sales c orders
equation eq{!eqno}.ls sales c orders
smpl 1970q2 1980q3
!eqno=!eqno+1
equation mideq.ls sales c orders
next
smpl 1975q4 1995q1
next
equation lateeq.ls sales c orders
Here, the equations are estimated over the samples
Both string objects and replacement variables may be 1955Q11970Q2 for EQ1, 1955Q11980Q3 for EQ2,
used to specify a list for use in loops, by surrounding 1955Q11975Q4 for EQ3, 1960Q41970Q2 for EQ4,
18

1960Q41980Q3 for EQ5, and 1960Q41975Q4 for There are four parts to this WHILE loop. The first part
EQ6.
is the initialization of the control variables used in the
test condition. The second part is the WHILE
Note that you may use the exitloop command to exit a statement which includes the test. The third part is the
FOR loop early. See Exiting Loops.
statements updating the control variables. Finally the
end of the loop is marked by the word wend.
The WHILE Loop
In some cases, we wish to repeat a series of commands
several times, but only while one or more conditions
are satisfied. Like the FOR loop, the WHILE loop
allows you to repeat commands, but the WHILE loop
provides greater flexibility in specifying the required
conditions.

Unlike a FOR statement, the WHILE statement does

not update the control variable used in the test
condition. You need to include an explicit statement
inside the loop to change the control variable, or your
loop will never terminate. Use the F1 key to break out
of a program which is in an infinite loop.

The WHILE loop begins with a while statement and

ends with a wend statement. Any number of
commands may appear between the two statements.
WHILE loops can be nested.

Earlier, we cautioned against this behavior creating

FOR loops that explicitly change the control variable
inside the loop and offered an example to show the
resulting lack of clarity (here). Note that the equivalent
WHILE loop provides a much clearer program:

The WHILE statement consists of the while keyword

followed by an expression involving a control variable !i = 1
or scalar object. The expression should have a logical while !i<=25
(true/false) value or a numerical value. In the latter
case, zero is considered false and any non-zero value is vector a{!i}
considered true.
!i = !i + 11
If the expression is true, the subsequent statements, up
to the matching wend, will be executed, and then the wend
procedure is repeated. If the condition is false, EViews Note that you may use the exitloop command to exit a
will skip the following commands and continue on WHILE loop early. See Exiting Loops.
with the rest of the program following the wend
Execution Errors
statement. For example:

smpl 1950q1 1970q1+!a

By default, EViews will stop executing after

encountering any errors. You can instruct the program
to continue running even if errors are encountered by
changing the maximum error count from the Run
dialog (see Executing a Program), or by using the
setmaxerrs command inside a program.

series inc{!val} = income/!val

Handling Errors

!val = !val*10

You may wish to perform different tasks when errors

are encountered. For example, you may wish to skip a
set of lines which accumulate estimation results when
the estimation procedure generated errors, or you may

!val = 1
!a = 1
while !val<10000 and !a<10

!a = !a+1
wend

19

wish to overwrite the default EViews error with one of endif

your own, using the seterr command.
Note that if SER1 contains missing values, the
EViews offers a number of different ways to test for corresponding elements of TEST will also be missing.
and handle execution errors. For example, the But since the @sum function ignores missing values,
@lasterrstr command will return a string containing the program does not halt for SER1 that has missing
the previous line's error. If the previous line of your values, as long as there is no negative value.
program did not error, this string will be empty.
Alternatively you could use the @errorcount function Exiting Loops
to check the number of errors currently encountered Sometimes, you do not wish to stop the entire program
before and after a program line has been executed.
when a condition is satisfied; you just wish to exit the
For example, to test whether the estimation of an current loop. The exitloop command will exit the
equation generated an error, you can compare the current for or while statement and continue running the
program.
number of errors before and after the command:

if !new_count > !old_count then

As a simple example, suppose you computed a

sequence of LR test statistics LR11, LR10, LR9, ...,
LR1, say to test the lag length of a VAR. The
following program sequentially carries out the LR test
starting from LR11 and tells you the statistic that is
first rejected at the 5% level:

[various commands]

!df = 9

endif

for !lag = 11 to 1 step -1

!old_count = @errorcount
equation eq1.ls y x c
!new_count = @errorcount

Here, we perform a set of commands only if the !pval = 1 - @cchisq(lr{!lag},!df)

estimation of equation EQ1 incremented the error if !pval<=.05 then
count.
exitloop
For additional error handling functions, see Support
Commands and Support Functions.
endif
Stopping Programs

next

Occasionally, you may want to stop a program based

on some conditions. To stop a program executing in
EViews, use the stop command. For example, suppose
you write a program that requires the series SER1 to
have nonnegative values. The following commands
check whether the series is nonnegative and halt the
program if SER1 contains any negative value:

scalar lag=!lag

series test = (ser1<0)

Last updated: Tue, 18 Oct 2016 23:23:47 PST

Multiple Program Files
When working with long programs, you may wish to
organize your code using multiple files. For example,

if @sum(test) <> 0 then

stop

Note that the scalar LAG has the value 0 if none of the
test statistics are rejected.
If the exitloop is issued inside nested loops it will stop
execution of the innermost loop. Execution of the
remaining loops is unaffected.

20

suppose you have a program file named

Powers.PRG which contains a set of program lines
that you wish to use.
While you may be tempted to string files together
using the run command, we caution you that EViews
will stop after executing the commands in a runreferenced file. Thus, a program containing the lines
run powers.prg
series x = nrnd
will only execute the commands in the file
Powers.PRG, and will stop before generating the
series X. This behavior is probably not what you
intended.
The exec command may be used execute commands in
a file in place of the run command. Though exec is
quite similar to the run command, there are important
differences between the two commands:
First, exec allows you to write general programs that
execute other programs, something that is difficult to
do using run, since the run command ends all program
execution when processing of the named file is
completed. In contrast, once exec processing
completes, the calling program will continue to run.
Second, the default directory for exec is the Add-ins
directory (in contrast with both run and include which
defaults to using the EViews default directory). Thus,
the command
exec myprog1.prg
will run the program file Myprog1.prg located in the
default Add-ins directory. You may specify files using
relative paths in the standard fashion. The command:
exec MyAddIn\myprog2.prg
runs the program Myprog2.prg located in the
MyAddIn subdirectory of the Add-ins directory.
If you wish to run a program that is located in the same
directory as the calling program, simply issue a .\ at
the start of the program name:
exec .\myprog2.prg
Alternatively you may use the include keyword to
include the contents of a program file in another
program file. For example, you can place the line
include powers
at the top of any other program that needs to use the
commands in POWERS. include also accepts a full
path to the program file, and you may have more than
one include statement in a program. For example, the
lines,
include c:\programs\powers.prg
include durbin_h
[more lines]

will first execute all of the commands in

C:\Programs\Powers.PRG,
will
execute
the
commands in Durbin_h.PRG, and then will execute
the remaining lines in the program file.
If you do not provide an absolute path for your include
file, EViews will use the location of the executing
program file as the base location. In the example
above, EViews will search for the Durbin_h.PRG
file in the directory containing the executing program.
Note that in contrast to using exec to execute another
program, include simply inserts the child program into
the parent. This insertion is done prior to executing any
lines in either program. One important consequence of
this behavior is that any program variables that are
declared in the parent program will not be available in
the child/included program, even if they are declared
prior to the include statement.
Last updated: Tue, 18 Oct 2016 23:23:47 PST
Subroutines
Defining Subroutines
Subroutine with Arguments
Calling Subroutines
Subroutine Placement
Global and Local Variables
Global Subroutines
Local Subroutines
Local Samples
A subroutine is a collection of commands that allows
you to perform a given task repeatedly, with minor
variations, without actually duplicating the commands.
You may also use subroutines from one program to
perform the same task in other programs.
Defining Subroutines
A subroutine begins with the keyword subroutine
followed by the name of the routine and any
arguments, and ends with the keyword endsub. Any
number of commands can appear in between. The
simplest type of subroutine has the following form:
subroutine z_square
series x = z^2
endsub
where the keyword subroutine is followed only by the
name of the routine. This subroutine has no arguments
so that it will behave identically every time it is used.

21

It forms the square of the existing series Z and stores it where depends upon the argument . The argument
in the new series X.
is merely a place holderits there to define the
You may use the return command to force EViews to function and it does not really stand for anything.
exit from the subroutine at any time. A common use of Then, if you want to evaluate the function at a
return is to exit from the subroutine if an unanticipated particular numerical value, say 0.7839, you can write
error is detected. The following program exits the
. If you want to evaluate the function at a
subroutine if Durbins statistic (Greene, 2008, p. different value, say 0.50123, you merely write
646, or Davidson and MacKinnon, 1993, p. 360) for
. By defining the function, you save
testing serial correlation with a lagged dependent yourself from writing the full function expression
variable cannot be computed:
every time you wish to evaluate it for a different value.
subroutine durbin_h

To define a subroutine with arguments, you start with

the subroutine keyword, followed by the subroutine
name and (with no space) the arguments separated by
commas, enclosed in parentheses. Each argument is
specified by listing a type of EViews object, followed
by the name of the argument. For example:

equation eqn.ls cs c cs(-1) inc

scalar test=1-eqn.@regobs*eqn.@cov(2,2)
' an error is indicated by test being nonpositive
' exit on error

subroutine power(series v, series y, scalar p)

if test<=0 then

v = y^p

return

endsub

endif

This subroutine generalizes the example subroutine

Z_SQUARE. Calling the subroutine POWER will fill
the series given by the argument V with the power P of
the series specified by the argument Y. So if you set V
equal to X, Y equal to Z, and P equal to 2, you will get
the equivalent of the subroutine Z_SQUARE above.
See the discussion below on how to call subroutines.

' compute h statistic if test positive

scalar h=(1-eqn.@dw/2)*sqr(eqn.@regobs/test)
endsub
Subroutine with Arguments
The subroutines we have seen thus far have been
written to work with a specific set of variables. More
generally, subroutines can take arguments. Arguments
allow you to change the behavior of the group of
commands each time the subroutine is used. You may
be familiar with the concept from other programming
languages, but if now, you are probably familiar with
similar concepts in mathematics. You can define a
function, say
(6.1)

When creating subroutines with scalar or string

arguments, you will define your arguments using the
scalar or the string types. Beyond that, you have a
choice of whether you can to make the corresponding
argument a (temporary) program variable or a
(permanent) workfile object:
To make the argument a program variable, you
should use a program variable name (beginning with a
! for a control variable and a % for a string
variable). If you choose to use program variables, they
should be referred to using the ! or % name inside
the subroutine.

22

 To make the argument a workfile object, you should Calling Subroutines

use a standard EViews object name. The object should
be referred to by the argument name inside the Once a subroutine is defined, you may execute the
commands in the subroutine by using the call keyword.
subroutine.
call should be followed by the name of the subroutine,
Obviously, you can mix the two approaches in the and a list of any argument values you wish to use,
definition of any subroutine.
enclosed in parentheses and separated by commas
(with no space after the subroutine name). If the
For example, the declaration
subroutine takes arguments, the arguments must be
provided in the same order as in the declaration
subroutine mysub(scalar !a, string %b)
statement. Here is an example program file that calls
uses program variable names, while
subroutines:
subroutine mysub(scalar a, string b)

include powers

uses object names. In the first case you should refer to load mywork
!A and %B inside the subroutine; in the latter case,
fetch z gdp
you should refer to the objects named A and B.
If you define your subroutine using program variables, series x
the subroutine will operate on them as though they series gdp2
were any other program variable. The variables, which
cannot go out-of-scope, should be referred to using the series gdp3
! or % argument name inside the subroutine.
call z_square
If you define your subroutine using object names, the
subroutine will operate on those variables as though call power(gdp2,gdp,2)
they were scalar or string objects. The variables, which call power(gdp3,gdp,3)
may be deleted and may go out-of-scope (if, for
example, you change the workfile page), should be The call of the Z_SQUARE subroutine fills the series
referred to using the argument names as though they X with the value of Z squared. Next, the call to the
POWER subroutine creates the series GDP2 which is
were scalar or string objects.
GDP squared. The last call to POWER creates the
(We discuss in detail related issues in Calling series GDP3 as the cube of GDP.
Subroutines.)
When calling your subroutine, bear in mind that:
You should note that EViews makes no distinction
between input or output arguments in a subroutine. When the subroutine argument is a scalar, the
Each argument may be an input to the subroutine, an subroutine may be called with a scalar object, a control
output from the subroutine, or both (or neither!). There variable, a simple number (such as 10 or 15.3), a
is no way to declare that some arguments are inputs matrix element (such as mat1(1,2)) or a scalar
and some are outputs. There is no need to order the expression (such as !y+25).
arguments in any particular order. However we find it
Subroutines with a string argument may be called
much easier to read subroutine code when we stick to a
with a string object, a string program variable, simple
convention, such as listing all output arguments prior
text (such as hello) or an element of an svector
to all input arguments (or vice versa).
object.
23

 Subroutines that take matrix and vector arguments However the subroutine is called, bear in mind that
can be called with a matrix name, and if not modified behavior inside the subroutine is dependent on whether
by the subroutine, may also take a matrix expression.
the subroutine declaration is in terms of program
variables or objects, not on the variable type that is
All other arguments must be passed to the subroutine passed into the subroutine.
with an object name referring to a single object of the
correct type.
Subroutine Placement
In Subroutine with Arguments we described how
you can define subroutines that use either program
variables or objects for scalar or string arguments.
However you define your subroutine, you may call the
subroutine using either program variables or objects
you are not required to match the calling arguments
with the subroutine definition. Suppose, for example,
that you define your subroutine as
subroutine mysub(scalar a, string b)

Subroutine definitions may be placed anywhere

throughout your program. However, for clarity, we
recommend grouping subroutine definitions together
either at the start or at the end of your program. The
subroutines will not be executed until they are
executed by the program using a call statement. For
example:
subroutine z_square
series x=z^2

Then for scalar and string objects F and G, and

endsub
program variables !X and %Y,
scalar f = 3

' start of program execution

string g = "hello"

load mywork

!x = 2

fetch z

%y = "goodbye"

call z_square

you may call the subroutine using any of the following Execution of this program begins with the load
statement; the subroutine definition is skipped and is
commands:
executed only at the last line when it is called.
call mysub(!x, %y)
Subroutine definitions must not overlapafter the
call mysub(!x, g)
subroutine keyword, there should be an endsub before
the next subroutine declaration. Subroutines may call
call mysub(f, %y)
each other, or even call themselves.
call mysub(f, g)

Alternatively, you may place frequently used

Note that changes to the scalars A and B inside the subroutines in a separate program file and use an
subroutine will change the corresponding program include statement to insert them at the beginning of
your program. If, for example, you put the subroutine
variable or object that you pass into the routine.
lines in the file Powers.PRG, then you may put the
Similarly, you may define
line:
subroutine mysub(scalar !a, string !b)

include powers

and use the same four call statements to execute the

subroutine commands.
24

at the top of any other program that needs to call Here is a simple program that calls a global subroutine:
Z_SQUARE or POWER. You can use the subroutines
in these programs as though they were built-in parts of subroutine z_square
the EViews programming language.
series x = z^2
Global and Local Variables

endsub

Subroutines work with variables and objects that are load mywork
either global or local.
fetch z
Global variables refer either to objects which exist in
the workfile when the subroutine is called, and to call z_square
objects that are created in the workfile by a subroutine.
Z_SQUARE is a global subroutine which has access to
Global variables remain in the workfile when the
the global series Z. The new global series X contains
subroutine finishes.
the square of the series Z. Both X and Z remain in the
A local variable is one that is defined within the workfile when Z_SQUARE is finished.
subroutine. Local variables are deleted from the
If one of the arguments of the subroutine has the same
workfile once a subroutine finishes. The program that
name as a global variable, the argument name takes
calls the subroutine will not be able to use a local
precedence so that any reference to the name in the
variable since the local variable disappears once the
subroutine will refer to the argument, not to the global
subroutine finishes and the original program continues.
variable. For example:
Global Subroutines
subroutine sqseries(series z, string sername)
By default, subroutines in EViews are global. Global
series {sername} = z^2
subroutine may refer to any global object that exists in
the workfile at the time the subroutine is called. Thus, endsub
if Z is a series in the workfile, the subroutine may refer
to and, if desired, alter the series Z. Similarly, if Y is a load mywork
global matrix that has been created by another
fetch z
subroutine, the current subroutine may use the matrix
Y.
fetch y
The rules for variables in global subroutines are:

call sqseries(y, "y2")

All objects created by a global subroutine are global In this example, there is a series Z in the original
and will remain in the workfile when the subroutine workfile and Z is also an argument of the subroutine.
finishes.
Calling SQSERIES with the argument set to Y tells
EViews to use the series passed-in via the argument Z
Global objects may be used and updated directly
instead of the global Z series. On completion of the
from within the subroutine. If, however, a global object
routine, the new series Y2 will contain the square of
has the same name as an argument in a subroutine, the
the series Y, not the square of the series Z. Since
variable name will refer to the argument and not to the
keeping track of variables can become confusing when
global variable.
subroutine arguments take the same name as existing
The global objects corresponding to arguments may workfile objects, we encourage you to name subroutine
arguments as clearly and distinctly as possible.
be used and updated by referring to the arguments.
25

Global subroutines may call global subroutines. You matrix(2,2) x = 0

should make certain to pass along required arguments
when you call a subroutine from within a subroutine. matrix(2,2) y = 0
For example,
endsub
subroutine wgtols(series y, series wt)

load mywork

equation eq1

series x

call ols(eq1, y)

call newxy

equation eq2

If you call this subroutine, EViews will return an error

indicating that the global series X already exists and is
of a different type than a matrix.

series temp = y/sqr(wt)

call ols(eq2, temp)

Local Subroutines

delete temp

eq.ls y c y(-1) y(-1)^2 y(-1)^3

If you include the word local in the definition of the

subroutine, you create a local subroutine. Local
subroutines are most useful when you wish to write a
subroutine which creates many temporary objects that
you do not want to keep.

endsub

The rules for variables in local subroutines are:

endsub
subroutine ols(equation eq, series y)

All objects created by a local subroutine will be local

and will be removed from the workfile upon exit from
the subroutine.

can be run by the program:

load mywork

The global objects corresponding to subroutine

arguments may be used and updated in the subroutine
by referring to the arguments.

fetch cpi
fetch cs
call wgtols(cs,cpi)

You may not use or update global objects that do not

In this example, the subroutine WGTOLS must correspond to subroutine arguments.
explicitly pass along arguments to the subroutine OLS
There is one exception to the general inaccessibility of
so that it uses the correct series and equation objects.
non-argument global variables in local subroutines.
You cannot use a subroutine to change the object type When a global group is passed as an argument to a
of a global variable. Suppose that we wish to declare local subroutine, all of the series in the group are
new matrices X and Y by using a subroutine NEWXY. accessible to the local routine.
In this example, the declaration of matrix X generates
an error since X exists and is a series, but the
declaration of the matrix Y works (assuming there is
no Y in the workfile MYWORK, or that Y exists and
is already a matrix):
subroutine newxy

The last two rules deserve a bit of elaboration. In

general, local subroutines do not have access to any
global variables unless those variables are associated
with arguments passed into the subroutine. Thus, if
there is a series X in the workfile, a local subroutine
will not be allowed to use or modify X unless it is

26

passed into the subroutine using a series argument. Note that we first declare the series URES and scalar
Conversely, if X is passed into the subroutine, it may USSR before calling the local subroutine. These
be modified.
objects are global since they are declared outside the
local subroutine. Since we call the local subroutine by
Since locally created objects will vanish upon passing these global objects as arguments, the
completion of the subroutine, to save results from a subroutine can use and update these global variables.
local subroutine, you have to include them as
arguments. For example, consider the subroutine:
Object commands that require access to global
variables should be used with care in local subroutines
subroutine local ols_local(series y, series res, scalar since that the lack of access to global variables can
ssr)
create problems for views or procs of objects passed
into the routine. For example, a subroutine of the form:
equation temp_eq.ls y c y(-1) y(-1)^2 y(-1)^3
temp_eq.makeresid res

subroutine local bg(equation eq)

ssr = temp_eq.@ssr

eq.hettest z c

scalar se = ssr/temp_eq.@df

endsub

will fail because the hettest equation proc requires

access to the original variables in the equation and the
This local subroutine takes the series Y as input and global variable Z, and these series are not available
modifies the argument series RES and argument scalar since they are not passed in as arguments to the
SSR as output. Note that since Y, RES, and SSR are subroutine.
the only arguments of this local subroutine, the only
global variables that may be used or modified are those Care should also be taken when using samples and
associated with these arguments.The equation object local subroutines. If the workfile sample is based upon
TEMP_EQ and the scalar SE are local to the a series in the workfile (for example smpl @all if
subroutine and will vanish when the subroutine x>0), most procedures inside the local subroutine will
fail unless all of the series used in the sample are
finishes.
passed into the subroutine.
Here is an example program that calls this local
Local Samples
subroutine:
endsub

load mywork
fetch hsf
equation eq1.ls hsf c hsf(-1)
eq1.makeresid rres
scalar rssr = eq1.@ssr
series ures
scalar ussr
call ols_local(hsf, ures, ussr)

Local samples in subroutines allow you to indicate that

changes to the workfile sample are temporary, with the
original sample restored when you exit the routine.
This feature is useful when designing subroutines
which require working on a subset of observations in
the original sample.
You may, in a subroutine, use the local smpl statement
to indicate that subsequent changes to the sample are
temporary, and should be undone when exiting the
subroutine. The command
local smpl
27

makes a copy of the existing sample specification. You smpl 10 100

may then change the sample as many times as desired
using the smpl statement, and the original sample global smpl
specification will be reapplied when existing from the smpl 5 100
subroutine.
local smpl
You may use the global smpl statement to indicate that
subsequent smpl statements will result in permanent smpl 50 100
changes to the workfile sample. Thus, the commands:
endsub
global smpl
As before, first smpl statement changes the workfile
sample to 2 100 and the local smpl statement and
smpl 5 100
following smpl statement set the local sample to 10
in a subroutine permanently change the sample.
100. The global smpl indicates that subsequent
For example, consider the following program snippet sample statements will once again be global so the next
which illustrates the behavior of local and global line permanently changes the workfile sample to 5
100. Note that the last local smpl and subsequent
samples:
smpl statement change the local sample only. When we
workfile temp u 100
exit the subroutine the sample will be set to the last
global sample of 5 100.
call foo
Last updated: Tue, 18 Oct 2016 23:23:48 PST
subroutine foo
User-Defined Dialogs
@uiprompt
smpl 2 100
@uiedit
@uilist
local smpl
@uimlist
@uiradio
smpl 10 100
@uidialog
@uifiledlg
endsub
Example Program
Here, we create a workfile with 100 observations and EViews offers the ability to construct several types of
an initial workfile sample of 1 100, then call the user-interface controls, or dialogs, within your
subroutine FOO. Inside FOO, the first smpl statement program. These dialogs permit users to input variables
changes the workfile sample to 2 100. We then issue or set options during the running of the program, and
the local smpl statement which backs up the existing allow you to pass information back to users.
sample and identifies subsequent sample changes as
There are five different functions that create dialogs in
local. The subsequent change to the 10 100 sample is
EViews:
local so that when the subroutine exits, the sample is
reset to 2 100.
@uiprompt creates a prompt control, which
If instead we define FOO to be
subroutine foo
smpl 2 100
local smpl

displays a message to the user.

@uiedit creates an edit control, which lets users
input text.
@uilist creates a list control, which lets users select
from a list of choices.
28

 @uiradio creates a set of radio controls, which lets the user and let them continue or cancel from the
users select from a set of choices.
procedure.
@uidialog creates a dialog which contains a if type is equal to YN, then the dialog will contain
mixture of other controls.
a Yes button and a No button which can be used to
ask the user a question requiring an affirmative or
@uifiledlg creates a open/save-style dialog to negative response.
obtain the name of a file.
if type is equal to YNC the dialog will have a
Each dialog function returns an integer indicating how Yes button, a No button and a Cancel button.
the user exited the dialog:
For example, the command:
User Selection Return Value
Cancel
-1
@uiprompt("Welcome to EViews")
OK
0
Yes
1
No
2
Note that the only dialog types that can return exit
conditions other than Cancel or OK are
@uiprompt and @uidialog. If Cancel is pressed, the
variables passed into the dialog will not be updated will display a simple dialog box with a simple
with whatever settings the user has chosen. If OK is welcome message and an OK button, while the
command
pressed, then the dialog changes are accepted.
Each of the dialog functions accept arguments that are
used to define what will be displayed by the dialog,
and that will be used to store the user's inputs to the
dialog. You may use string or a scalar arguments,
where both the string and scalar can be a literal, a
program variable, or a workfile object.
@uiprompt
The @uiprompt(string prompt, string type) function
creates a simple message/prompt box that displays a
single piece of text, specified using the prompt
argument, and lets the user click a button to indicate an
action. The choices of action offered the user will
depend upon the string specified in type.

@uiprompt("Would you like to continue", "YN")

displays a dialog asking the user if they would like to
continue the program, with a Yes or No answer.
Note that the arguments to the function may be a
program variable or string object rather than string
literals. The following sets of commands give identical
results to that above:
%type = "YN"
%msg = "Would you like to continue"
scalar ret = @uiprompt(%msg, %type)

The return value of the control is determined by the

if type is equal to O, or is omitted completely, then user response: Cancel (-1), OK (0), Yes (1), No (2).
the dialog will only have an OK button. This type of See @uiprompt for additional detail.
prompt dialog would typically be used to provide a
@uiedit
message to the user.
if type is equal to OC, then the dialog will have an The @uiedit(string IOString, string prompt, scalar
OK button and a Cancel button. This type of maxEditLen) function provides an edit control that lets
prompt dialog would be used to pass a message onto the user enter text which is then stored in the string
29

IOString. If IOString contains text before the @uiedit and one that stores it as an integer IOScalar
function is called, the edit box will be initialized with representing the position of the selection in the list,
that text.
@uilist(scalar IOScalar, string prompt, string list)
The string prompt is used to specify text to be
displayed above the edit box, which may be used to The string prompt is used to specify text to be
displayed above the list box, providing a message or
provide a message or instructions to the user.
instructions to the user.
maxEditLen is an option integer scalar that specifies
the maximum length that IOString can take. If the user The string list is a space delimited list of items that will
tries to enter text longer than maxEditLen characters, be displayed in the list box. To specify entries with
the extra characters will be truncated. By default spaces, you should enclose the entry in double-quotes
using double-quote escape characters.
maxEditLen is set to 32.
Both prompt and maxEditLen may be written in-line Both prompt and list may be provided using in-line
using string literals, but IOString must be either a text, but IOString or IOScalar must be either a program
variable or an object in your workfile.
program variable or a string object in your workfile.
If the IO variable (IOString or IOScalar) is defined
before the function is called, then the list box control
%eqname = "eq_unemp"
will have the item defined by the variable pre-selected.
If the IO variable does not match an item in the list
scalar ret = @uiedit(%eqname, "Enter a name for your box, or if it is not pre-defined, the first item in the list
equation")
will be selected.
As an example,

equation {%eqname} unemp c gdp gdp(-1)

The following program lines provide the user with a

will display the following dialog box and then create choice of robust standard errors, and then displays that
an equation object with a name equal to whatever was choice on the statusline:
entered for %EQNAME.
%choice = "White"
%list = "Default White HAC"
scalar ret = @uilist(%choice, "Standard Errors
Choice", %list)
The return value of the control is determined by the statusline %list
user response: Cancel (-1) or OK (0).
See @uiedit for additional detail.
@uilist
This function creates a list box dialog, which lets the
user select one item from a list. There are two forms of Note that the above program could also be run with the
the @uilist function, one that returns the user's following lines:
selection as a string IOString,
!choice = 2
@uilist(string IOString, string prompt, string list)
30

%list = "Default White HAC"

scalar ret = @uimlist(choice, "Standard Errors

Choice", %list)

scalar ret = @uilist(!choice, "Standard Errors Choice",

%list)
statusline %list
%choice = @word(%list,!choice)
statusline %choice
The return value of the control is determined by the
user response: Cancel (-1) or OK (0).
@uiradio

See @uilist for details.

@uiradio(scalar IOScalar, string prompt, string list) is

similar to @uilist in that it provides a dialog that lets
This function is similar to @uilist in that it creates a the user select from a list of choices. However rather
list box dialog, with a difference being that here than selecting an item from a list box, the user must
multiple selections from the list may be made. The select the desired item using radio buttons. The
form of the @uimlist function is:
@uiradio function will return the user's choice in
IOScalar.
@uimlist(vector IOVector, string prompt, string list)
@uimlist

The string prompt is used to specify text to be The string prompt should be used to specify a message
or instructions to the user to be displayed above the set
displayed above the list box, providing a message or
of radio buttons.
instructions to the user.
The string list is a space delimited list of items that will
be displayed in the list box. To specify entries with
spaces, you should enclose the entry in double-quotes
using double-quote escape characters.

The string list is a space delimited list of items that

contains the items for the radio buttons. To specify
entries with spaces, you should enclose the entry in
double-quotes using double-quote escape characters.

Both prompt and list may be specified using in-line

Both prompt and list may be provided using in-line
text, but IOString or IOScalar must be either a program text, but IOScalar must be either a program variable or
an object in your workfile.
variable or an object in your workfile.
If the IO variable (IOVector) is defined before the
function is called, then the list box control will have
the items defined by the vector pre-selected. If the IO
variable does not match an item in the list box, or if it
is not pre-defined, the first item in the list will be
selected.

If IOScalar is defined and set equal to a valid integer

before the function is called, the radio button
associated with that integer will be the default
selection when the dialog is shown. If IOScalar is not a
valid choice, the first radio will be selected.

As an example, we replicate the standard error choice

The following program lines provide the user with a example from the @uilist function, but this time use
radio buttons:
choice of robust standard errors, and then displays
those choices on the statusline:
!choice = 2
vector(1) choice = 2

%list = "Default White HAC"

%list = "Default White HAC"

31

scalar ret = @uiradio(!choice, "Standard Errors specification for an edit box would be (edit, string
Choice", %list)
IOString, string prompt, scalar maxEditLen).
%choice = @word(%list,!choice)
statusline %choice

The caption control changes the title of the dialog,

shown in the title bar. The caption keyword should be
followed by a string containing the text to be used as
the caption, yielding a specification of (caption,
string caption).
The text control adds basic text to the dialog. Like
the caption control, the text control keyword, text,
should be followed by a string containing the text to be
used, yielding a specification of (text, string text).

The return value of the control is determined by the

The check box control adds a check box to the
user response: Cancel (-1) or OK (0).
dialog. The check keyword should be followed by a
See @uiradio for additional detail.
scalar, IOScalar, which stores the selection of the
check box - 1 for checked, and 0 for unchecked, and
@uidialog
then by a string prompt which contains the text to be
The @uidialog(control_spec1[, control_spec2, .]) used as a prompt/instructions for the check box. The
function displays a dialog which may be composed of specification for the check box control is then:
different controls, including simple text, edit boxes, list (check, scalar IOScalar, string prompt).
boxes, radio buttons and check boxes. The dialog is
The button and buttonc controls add a custom
specified using a list of control specifications passed
button to the dialog. The dialog will close after a
into the function as arguments. Each control
button has been pressed. The behavior of the button
specification is a type keyword specifying the type of
will depend on the type of button buttons of type
control, followed by a list of parameters for that
button will behave in the same way as the OK
control.
button (i.e., all variables passed into the dialog will be
The type keywords should be from the following list: updated to reflect changes made to their corresponding
controls). Buttons of type buttonc will behave in the
Keyword
Control
same way as the Cancel button (i.e., all variables
caption
Dialog title
will be reset to the values that were passed into the
text
Plain text
dialog).
edit
Edit box
list
List box
The return value of the dialog will correspond to the
radio
Radio buttons
order in which buttons are placed in the dialog. If only
check
Check box
one button (apart from the standard OK and
button
OK-type button
Cancel) is included in the dialog, the return value for
buttonc
Cancel-type
that button will be 1. If there is more than one
button
button, then the first button will return a value of 1,
colbreak
Column break
setoc
Set
OK/Cancel
the second will return a value of 2 and so on. Note
text
that the return value is independent of whether the
The edit, list and radio controls are similar to button was of type button or buttonc. The
their individual dialog functions, and the specifications specification for the button controls is (button[c],
for those controls follow the same pattern. Thus the
32

text) where text specifies the text that will be on the IO_Filespec will also contain the file specified on
button.
return.
The column break control inserts a column break. By
default, EViews will automatically choose the number
of columns in the constructed dialog. There is still a
maximum of only two columns allowed, but by adding
a colbreak control, you can force the position of a
break in the dialog.

The string filter is used to specify the types of files to

show in the dialog using the filter argument, with, for
example, used to denote all files, and prg used to
limit the display to files ending in .prg.
The type argument is used to determine whether the
shown dialog has an open or a save prompt.

setoc allows you to change the text of the OK and

Cancel buttons on the dialog. You should supply two (Note that the clicking OK on the dialog does not
words, separated by a space as the text for OK and actually open or save the selected file, it merely returns
the name of the selected file. Thus, specifying the type
Cancel.
argument is for cosmetic reasons only.)
As an example, a dialog that offers a choice of
covariance matrix options, plus a check box for degree Both filter and style may be specified using in-line
text, but IO_Filespec must be either a program variable
of freedom adjustment, could be made with:
or an object in your workfile.
!choice = 2
The displayed dialog will display both an OK and a
!doDF = 1
Cancel button, and will return an integer representing
the button clicked: Cancel (-1), OK (0).
%list = "Default White HAC"
string myfile = "c:\temp\"
scalar ret = @uidialog("caption", "Covariance
Options", "list", !choice, "Covariance method", %list, @uifiledlg(myfile, "prg, "open")
"check", !doDF, "DF-adjust")
These commands display a file open dialog style
containing a list of all files with a .prg extension in
the folder c:\temp\. The user can navigate through
the file system and select another file, whose path and
name will be returned in the string MYFILE.
Note that the slightly different set of commands
See @uidialog for details.
@uifiledlg

string myfile = "c:\temp"

@uifiledlg(myfile, "prg", "save")

The @uifiledlg(string IO_Filespec, string filter, string

will instead display a save dialog that opens in the
style) displays a standard Windows file open or save
c:\ folder with the filename initialized to temp.prg
dialog so that you may obtain the path and name of a
(MYFILE does not have the trailing \).
file.
See also @uifiledlg.
@uifiledlg function will return the user's specification
in file_spec.
Example Program
The string IO_Filespec should be used to specify an This program creates a workfile and some series, then
initial location and possibly the name for the file. puts up dialogs asking the user to specify the
33

dependent variable and the regressors to be used in a

least-squares equation. Note that the part of the
example program that generates the data could be
replaced with a command to open up an existing
workfile.
'Create a workfile and some series
wfcreate temp u 100
series y=nrnd
series x=nrnd
series w=nrnd

equation eq1.ls {%dep} {%regs} 'estimate equation.

Three program variables are used in this program:
%DEP, %REGS and !RESULT. %DEP is the string
variable that will contain the users entry for the
dependent variable. To begin, we set this equal to an
empty string. %REGS is used to store the users entry
for the list of regressors. We set this equal to C to
begin with. This means that the default setting for the
regressor list will be a constant. !RESULT will be used
to track the completion of the dialogs. Every dialog
returns an integer value depending on whether the user
clicked OK or Cancel (or in some cases Yes or No).
We initialize this value to 0.

'------------------------------------'variable to store name of dependent variable

%dep = ""
'variable to store list of regressors. Default is "c" for a
Following the declaration of the variables, the first
constant.
dialog is brought up using the @uiedit command. This
%regs = "c "
will create an Edit dialog asking the user to Enter the
'variable that will track the result of dialogs. -1 dependent variable. The users response will be stored
in %DEP. Following the dialog command, we check
indicates user hit Cancel. 0 Indicates user hit OK.
whether the value of !RESULT is equal to -1. A -1
!result = 0
indicates that the user pressed Cancel in the dialog. If
this is the case, the program quits, using the stop
'put up an Edit dialog asking for dependent variable.
command.
!result =
variable")

@uiedit(%dep,"Enter

the

dependent The second dialog command is similar to the first, but

rather than asking for the dependent variable, it asks
if !result=-1 then 'if user cancelled, then stop program the user to Enter the list of regressors, and stores that
list in %REGS. Note that since %REGS was set equal
stop
to C prior to the dialog being put up, the dialog will
be pre-filled with the constant term. Users can still
endif
delete the constant or add extra regressors.
'put up an Edit dialog asking for regressors list.
!result = @uiedit(%regs,"Enter the list of regressors")

Finally, having obtained entries for both %DEP and

%REGS, equation EQ1 is estimated via least squares
with the specified variables.

if !result=-1 then 'if user cancelled, then stop program

Last updated: Tue, 18 Oct 2016 23:23:48 PST
stop
endif
34