EViews 14 Command and

Programming Reference
EViews 14 Command and Programming Reference
Copyright © 1994–2024 S&P Global Inc.
All Rights Reserved

This software product, including program code and manual, is copyrighted, and all rights are
reserved by S&P Global Inc. The distribution and sale of this product are intended for the use of
the original purchaser only. Except as permitted under the United States Copyright Act of 1976,
no part of this product may be reproduced or distributed in any form or by any means, or stored
in a database or retrieval system, without the prior written permission of IHS Global Inc.

Disclaimer
The authors and S&P Global Inc. assume no responsibility for any errors that may appear in this
manual or the EViews program. The user assumes all responsibility for the selection of the pro-
gram to achieve intended results, and for the installation, use, and results obtained from the pro-
gram.

Trademarks
EViews® is a registered trademark of S&P Global Inc. Windows, Excel, PowerPoint, and Access
are registered trademarks of Microsoft Corporation. PostScript is a trademark of Adobe Corpora-
tion. Bloomberg is a trademark of Bloomberg Finance L.P. All other product names mentioned in
this manual may be trademarks or registered trademarks of their respective companies.

Third Party Licenses

This section contains third party notices or additional terms and conditions applicable to certain
software technologies which may be used in one or more EViews products and/or services.
Please be sure to consult the individual product files, about box, and/or install or manual docu-
mentation for specific copyright notices and author attributions. Notices on this page are current
for EViews products released on or after October 1, 2017.
• diff template Library - Copyright © 2015 Tatsuhiko Kubo [email protected]. All
rights reserved.
• FFmpeg Library - FFmpeg is a trademark of Fabrice Bellard, originator of the FFmpeg
project.
• GZipHelper - Copyright © 1995-2002 Gao Dasheng [email protected].
• Java SE Runtime Environment v1.8.0_401 licensed under Oracle Binary Code License
Agreement.
• JDemetra+ v3 licensed under European Union Public License v1.2.
• jsonCPP Library - Copyright © 2007-2010 Baptiste Lepilleur and The JsonCPP Authors.
• openssl Library - Copyright © 1998-2016 The OpenSSL Project. All rights reserved.
 • libcurl Library - Copyright © 1996-2013, Daniel Stenberg [email protected].
• libharu Library - Copyright © 2000-2006 Takeshi Kanno, Copyright © 2007-2009 Antony
Dovgal et all.
• libssh2 Library - Copyright © 2004-2007 Sara Golemon [email protected], Copyright ©
2005, 2006 Mikhail Gusarov [email protected], Copyright © 2006-2007 The
Written Word, Inc., Copyright © 2007 Eli Fant [email protected], Copyright © 2009 Daniel
Stenberg, Copyright © 2008, 2009 Simon Josefsson. All rights reserved.
• Meta Prophet 1.1.5 licensed under MIT license. Copyright (c) Facebook, Inc. and its affil-
iates.
• OpenXLSX Library Copyright © 2020, Kenneth Troldal Balslev All rights reserved.
• Python 3 licensed under Python Software Foundation License.
• rapidjson Library - Copyright © 2015 THL A29 Limited, a Tencent company, and Milo Yip.
• shapelib Library - Copyright © 1998 Frank Warmerdam.
• ssleay License - Copyright © 1995-1998 Eric Young ([email protected]) All rights
reserved.
• Tableau Data Extract API - Copyright © 2003-2017 Tableau and its licensors. All rights
reserved.
• Tramo/Seats - Copyright (c) 1996 Agustin Maravall and Victor Gomez. Windows version
developed by G. Caporello and A. Maravall (Bank of Spain)
• X11.2 and X12-ARIMA version 0.2.7 and X-13ARIMA-SEATS - Copyright (c) U.S. Census
Bureau.

zlib Data Compression Library - Copyright © 1995-2017 Jean-loup Gailly and Mark
Adler.Notices, terms and conditions pertaining to third party software are located at http://
www.eviews.com/thirdparty and incorporated by reference herein.

S&P Global Inc.

Telephone: (949) 856-3368
e-mail: [email protected]
web: www.eviews.com
June 24, 2024
Table of Contents

PREFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
CHAPTER 1. OBJECT AND COMMAND BASICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Command Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Using Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Object Declaration and Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Object Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Object Data Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Interactive Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Auxiliary Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

CHAPTER 2. WORKING WITH GRAPHS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Creating a Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Changing Graph Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Customizing a Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Labeling Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Printing Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Exporting Graphs to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Graph Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

CHAPTER 3. WORKING WITH TABLES AND SPREADSHEETS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Creating a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Assigning Table Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Customizing Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Labeling Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Printing Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Exporting Tables to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Customizing Spreadsheet Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Table Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

CHAPTER 4. WORKING WITH SPOOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Creating a Spool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Working with a Spool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Printing the Spool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Spool Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
ii—Table of Contents

CHAPTER 5. STRINGS AND DATES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

CHAPTER 6. EVIEWS PROGRAMMING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129

Program Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Simple Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Program Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Program Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Program Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Program Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Control of Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Multiple Program Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
User-Defined Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Version 4 Compatibility Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

CHAPTER 7. EXTERNAL CONNECTIVITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193

Reading EViews Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
EViews COM Automation Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
EViews COM Automation Client Support (MATLAB, R, Python) . . . . . . . . . . . . . . . . . . . . . . .195
EViews Database Extension Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Jupyter Notebook Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205

CHAPTER 8. ADD-INS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207

What is an Add-in? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Getting Started with Add-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
Using Add-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
Add-ins Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Managing Add-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Creating an Add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
Add-ins Design Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230

CHAPTER 9. USER OBJECTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233

What is a User Object? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Unregistered User Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Registered User Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
 Table of Contents—iii

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Managing User Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Defining a Registered User Object Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
User Object Programming Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

CHAPTER 10. USER-DEFINED OPTIMIZATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Defining the Objective and Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
The Optimize Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

CHAPTER 11. MATRIX LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Declaring Matrix Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Assigning Matrix Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Copying Data Between Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Matrix Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Matrix Commands and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Matrix Views and Procs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Matrix Operations versus Loop Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

CHAPTER 12. WORKFILE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Basic Workfile Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Workfile Sample Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Dated Workfile Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Panel Workfile Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

CHAPTER 13. SPECIAL EXPRESSION REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

CHAPTER 14. STRING AND DATE SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
String Function Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Date Function Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

CHAPTER 15. MATRIX LANGUAGE SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Matrix Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Matrix Function Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

CHAPTER 16. PROGRAMMING LANGUAGE SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Program Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Support Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
iv—Table of Contents

Support Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Workfile Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Dialog Display Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

CHAPTER 17. COMMAND REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .357

CHAPTER 18. FUNCTION REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .679
Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
Function Summaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .681
Function Reference: A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
Function Reference: B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
Function Reference: C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
Function Reference: D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
Function Reference: E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
Function Reference: F . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
Function Reference: G . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
Function Reference: H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
Function Reference: I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .913
Function Reference: J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .933
Function Reference: K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935
Function Reference: L . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
Function Reference: M . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
Function Reference: N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Function Reference: O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
Function Reference: P . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
Function Reference: Q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
Function Reference: R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061
Function Reference: S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
Function Reference: T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
Function Reference: U . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
Function Reference: V . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175
Function Reference: W . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1187
Function Reference: X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
Function Reference: Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223
Function Reference: Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225

APPENDIX A. WILDCARDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1227

Wildcard Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
 Table of Contents—v

Using Wildcard Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1227

Source and Destination Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1228
Resolving Ambiguities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1229
Wildcard versus Pool Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1230

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1233
vi—Table of Contents
Preface

The EViews User’s Guide focuses primarily on interactive use of EViews using dialogs and
other parts of the graphical user interface.

Alternatively, you may use EViews’ powerful command and batch processing language to
perform almost every operation that can be accomplished using the menus. You can enter
and edit commands in the command window, or you can create and store the commands in
programs that document your research project for later execution.

This text, the EViews Command and Programming Reference, documents the use of com-
mands in EViews, along with examples of commands for commonly performed operations,
and provides general information about the command, programming, and matrix languages:

The first chapter provides an overview of using commands in EViews:

• Chapter 1. “Object and Command Basics,” on page 3 explains the basics of using
commands to work with EViews objects, and provides examples of some commonly
performed operations.

The next set of chapters discusses commands for working with specific EViews objects:
• Chapter 2. “Working with Graphs,” on page 33 describes the use of commands to cus-
tomize graph objects.
• Chapter 3. “Working with Tables and Spreadsheets,” on page 57 documents the table
object and describes the basics of working with tables in EViews.
• Chapter 4. “Working with Spools,” on page 77 discusses commands for working with
spools.

The EViews programming and matrix language are described in:

• Chapter 5. “Strings and Dates,” on page 85 describes the syntax and functions avail-
able for manipulating text strings and dates.
• Chapter 6. “EViews Programming,” on page 129 describes the basics of using pro-
grams for batch processing and documents the programming language.
• Chapter 11. “Matrix Language,” on page 279 describes the EViews matrix language.
• Chapter 7. “External Connectivity,” on page 193 documents EViews features for inter-
facing with external applications through the OLEDB driver and various COM automa-
tion interfaces.

The remaining chapters contain reference material:

2—Preface

• Chapter 17. “Command Reference,” on page 357 is the primary reference for com-
mands to work with EViews objects, workfiles, databases, external interfaces, pro-
grams, as well as other auxiliary commands.
• Chapter 18. “Function Reference,” on page 679 offers an alphabetical list of element
operators, numerical functions and descriptive statistics functions.

There is additional material in the appendix:

• Appendix A. “Wildcards,” on page 1227 describes the use of wildcards in different
contexts in EViews.
Chapter 1. Object and Command Basics

This chapter provides an brief overview of the command method of working with EViews
and EViews objects. The command line interface of EViews is comprised of a set of single
line commands, each of which may be classified as one of the following:
• object declarations and assignment statements.
• object view and procedure commands.
• interactive commands for creating objects and displaying views and procedures.
• auxiliary commands.

The following sections provide an overview of each of the command types. But before dis-
cussing the various types, we offer a brief discussion of the interactive and batch methods of
using commands in EViews.

Command Capture
Before beginning our in-depth discussion of commands in EViews, we note that a great way
to familiarize yourself with the EViews command language is to use command capture. With
command capture, when you perform an operation using the user-interface, EViews will
save the equivalent text command for display and export.

EViews offers command capture for most object views and procedures, and a large number
of interactive operations.

To enable command capture you must display the command capture window. To display the
window or set focus on the window, click on Window/Display Command Capture Win-
dow from the main EViews menu.
4—Chapter 1.Command Capture

Once opened, you may move and resize the capture window as desired. The window may
even be pinned or moved outside of the frame of the EViews application (see “Command
and Capture Window Docking” on page 10).

Additionally, you may choose to echo any captured commands to the command window. To
enable this feature, select Options/General Options from the manu menu, and click on the
Command Capture node, and click on the Capture to Command Window checkbox.

You can copy-and-paste the contents of the capture window, or you can save the contents to
a file. Right-clicking in the window brings up a menu for copying or clearing the window,
saving the contents to a file on disk, or opening a new, untitled program containing the con-
tents of the window.

Note that not all interactive operations in EViews are capture enabled. Among the notable
exceptions are some types of graph creation and customization, and individual cell editing
for tables and spreadsheets. In addition, capture of object view graph customization is not
supported. Thus, if you wish to capture the commands for customizing the impulse
response view of a VAR object, you should freeze the view, and then customize the frozen
graph object.
 Using Commands—5

Using Commands
Commands may be used interactively or executed in batch mode.

Interactive Use
The command window is located (by default) just below the main menu bar at the top of the
EViews window. A blinking insertion cursor in the command window indicates that key-
board focus is in the command window and that keystrokes will be entered in the window at
the insertion point. If no insertion cursor is present, simply click in the command window to
change the focus.

To work interactively, you will type a command into the command window, then press
ENTER to execute the command. If you enter an incomplete command, EViews will open a
dialog box prompting you for additional information.

A command that you

enter in the window will
be executed as soon as
you press ENTER. The
insertion point need not
be at the end of the com-
mand line when you
press ENTER. EViews
will execute the entire line that contains the insertion point.

The contents of the command area may also be saved directly into a text file for later use.
First make certain that the command window is active by clicking anywhere in the window,
and then select File/Save As… from the main menu. EViews will prompt you to save an
ASCII file in the default working directory (default name “commandlog.txt”) containing the
entire contents of the command window.

Command Window Editing

When you enter a command, EViews will add it to the list of previously executed commands
contained in the window. You can scroll up to an earlier command, edit it, and hit ENTER.
The modified command will be executed. You may also use standard Windows copy-and-
paste between the command window and any other window.

EViews offers a couple of specialized tools for displaying previous commands. First, to bring
up previous commands in the order they were entered, press the Control key and the UP
arrow (CTRL+UP). The last command will be entered into the command window. Holding
down the CTRL key and pressing UP repeatedly will display the next prior commands.
Repeat until the desired command is displayed.
6—Chapter 1.Using Commands

To look at a history of commands, press the Control Key and the J key (CTRL+J). This key
combination displays a history window containing the last 30 commands executed. Use the
UP and DOWN arrows until the desired command is selected and then press the ENTER key
to add it to the command window, or simply double click on the desired command. To close
the history window without selecting a command, click elsewhere in the command window
or press the Escape (ESC) key.

To execute the retrieved command, simply press ENTER again. You may first edit the com-
mand if you wish to do so.

You may resize the command window so that a larger number of previously executed com-
mands are visible. Use the mouse to move the cursor to the bottom of the window, hold
down the mouse button, and drag the bottom of the window downwards.

Command Explorer
The Command Explorer provides a quick way to display context specific documentation
while working in EViews. In particular, you may use the explorer to list all of the applicable
commands and data members for a specific object type, and to display documentation for
those commands.

By default, EViews ships with the explorer window in a docked window on the right-hand
side of your EViews window. To activate the explorer, simply click on the tab labeled Com-
mand Explorer.

EViews will open a window showing a list of the EViews object types.
 Using Commands—7

• Clicking on the name of an object type will open a documentation page for that object
in a browser window.
• Clicking on the arrow to the left of the object name will toggle the display of alphabet-
ical tree-listing of all of the commands, procs, and data members for that object. To
open a browser window to the documentation of a given element, click on the name.

Alternately, from the open explorer window, you may use the search box to locate a specific
command or proc.

if you already know the command name or a portion of the command name, you may
search for the command by simply typing portion of that command followed by a wildcard
(“*”) into the search window and pressing return. A list of matching commands will be dis-
played. Clicking on one of the results will display the corresponding help page.
8—Chapter 1.Using Commands

Use the left and right arrows to the left of the search window to switch between the search
results and the full list of commands.

By default, the Command Explorer window will automatically close when it loses focus. You
may click on the push-pin in the upper right portion of the window to dock the open win-
dow. Click on the push-pin again to restore the docked window to auto-close.

Auto-Complete Names and Commands

You may instruct EViews to auto-complete the name of the object or object command you
are in the middle of typing. This feature is particularly useful in workfiles with long series
names or when issuing a series of commands. (Note that auto-complete is only enabled
when there is a workfile open).

Object Name Auto-Complete

Assuming you have an open workfile, simply begin typing the first characters of the name of
an object or command. Press CONTROL+SPACE to display a list of the objects in the current
workfile.
Ne

If there are no ambiguities, the name of the object will be added to the command window. If
there are ambiguities, a list of all the objects in the workfile will appear with the first match
selected:
 Using Commands—9

From here you can either press ENTER and the name of the object will be completed, or you
may use the up and down arrows to select a name and press ENTER to complete your selec-
tion:

Alternately, you may press CONTROL+SPACE at any time when nothing has been typed, to
see the full list of objects.

Object Command Auto-Complete

Similarly, you may use auto-completion for commands. If you have typed an object name
along with a trailing period, press CONTROL+SPACE again to display the list of commands
for that object. Assuming that object exists in your current workfile, EViews will list all the
commands and procs for that object,

As with object name auto-complete, typing a portion of a command will add the full string if
there are no ambiguities, or will display a list of applicable commands with the nearest
match partially selected:

Using the arrow keys, select the desired command:

10—Chapter 1.Using Commands

and press ENTER to add the command to the window:

Command and Capture Window Docking

The EViews 14 command and capture windows are dockable, hideable, and floatable.

Dockable and hideable windows allow you to move frequently used windows out of the way
while keeping them close at hand. They offer space saving convenience which is particu-
larly valued when working with smaller screen devices like laptops.

Floatable windows allow you to move them out of the way of your work. You may even go
so far as to float a window outside of the EViews frame.

To re-arrange the layout of the Command or Capture window, first make sure the window
pane is not in sliding mode (the Pin icon should be IN so that it is vertical).

Then drag the window to the desired location or dock.

Note that it is possible to drag a window into an unwanted position where it covers a por-
tion of a window with which you wish to work. In most cases, you may simply move the
window out of the way. If it is difficult to drag the window because you cannot see the title-
bar, you should be able use the scroll bars to gain easier access to the titlebar of the window.

Floating
You can drag the window to a new location just like any other window in EViews. However,
unlike other EViews windows, You can drag the command window outside of the EViews
frame:
 Using Commands—11

Docking
Both the command and capture window panes can now be docked on any side inside the
main EViews window. Begin dragging the pane by left-clicking title bar and holding it down
as you drag it off the edge. At that point, you will see small docking guides appear inside the
main EViews window:
12—Chapter 1.Using Commands

To dock the window, you will drag it to one of the docking guides. The docking behavior
will depend on which guide you select.

The docking guides allow you to dock the window pane to one of eight pre-defined areas.
The four guides on the outer edge of the main window allow you to dock the window as the
primary pane while the inner guides allow you to dock the window as a secondary pane. Pri-
mary panes take over the entire length of the selected edge and force other docked panes
that could intersect to become smaller to compensate. Secondary panes only take over the
portion of the selected edge that is not already occupied.

For example, if the capture pane is dragged to the right-most docking guide like this:

and then released, the final layout looks like this

 Using Commands—13

Because it is primary, it pushes the docked Command window pane at the top of the win-
dow to become smaller.

Alternatively, if the inner right guide was selected instead like this:
14—Chapter 1.Using Commands

the final layout would look like this

Docking two panes onto the same primary edge can result in stacking, with the recently
moved pane being adjacent to the edge (as the primary), and any secondary panes being
stacked next to the primary pane (in the order they were docked).
 Using Commands—15

You can also dock a pane inside another pane in order to use the share the same space. If
you drag a pane over another pane, you are presented with additional docking guides inside
the other pane:

For example, selecting the inner-right guide area allows the Capture pane to appear to the
right of the Command pane with an adjustable split bar to let you resize the split:
16—Chapter 1.Using Commands

The docking guide also offers an additional guide area directly in the center that allows you
to convert both panes into a tabbed view:
 Using Commands—17

Pinning
If your window is docked, you can “pin” it by clicking on the pin icon (so that it is horizon-
tal). When pinned, the window will be minimized and a small tab will be displayed in the
docked location.

To expand the pinned window, simply click on the tab. The window will automatically con-
tracts when it loses focus. Clicking on the Pin icon again will “un-pin” and expand the win-
dow permanently.

See also “Pane and Tab User Interface” on page 97 of User’s Guide I for an alternative user
interface that extends the use of docking and pinning.

Keyboard Focus
We note that as you open and close object windows in EViews, the keyboard focus may
change from the command window to the active window. If you then wish to enter a com-
mand, you will first need to click in the command window to set the focus. You can influ-
ence EViews’ method of choosing keyboard focus by changing the global defaults—simply
select Options/General Options.../Window Behavior in the main menu, and change the
Keyboard Focus setting as desired.

Batch Program Use

You may assemble a number of commands into a program, and then execute the commands
in batch mode. Each command in the program will be executed in the order that it appears
in the program. Using batch programs allows you to make use of advanced capabilities such
18—Chapter 1.Object Declaration and Initialization

as looping and condition branching, and subroutine and macro processing. Programs also
are an excellent way to document a research project since you will have a record of each
step of the project. Batch program use of EViews is discussed in greater detail in Chapter 6.
“EViews Programming,” on page 129.

One way to create a program file in EViews is to select File/New/Program. EViews will
open an untitled program window into which you may enter your commands. You can save
the program by clicking on the Save or SaveAs button, navigating to the desired directory,
and entering a file name. EViews will append the extension “.PRG” to the name you provide.

Alternatively, you can use your favorite text (ASCII) editor to create a program file contain-
ing your commands. It will prove convenient to name your file using the extension “.PRG”.
The commands in this program may then be executed from within EViews.

You may also enter commands in the command window and then use File/Save As... to
save the log for editing.

Object Declaration and Initialization

The simplest types of commands create an EViews object, or assign data to or initialize an
existing object.

Object Declaration
A simple object declaration has the form
object_type(options) object_name
where object_name is the name you would like to give to the newly created object and
object_type is one of the following object types:

Alpha (p. 6) Pool (p. 650) Sym (p. 991)

Coef (p. 22) Rowvector (p. 703) System (p. 1031)

Equation (p. 51) Sample (p. 738) Table (p. 1072)

Factor (p. 273) Scalar (p. 747) Text (p. 1112)

Graph (p. 368) Series (p. 755) User (p. 1122)

Group (p. 436) Spool (p. 904) Valmap (p. 1133)

 Object Declaration and Initialization—19

Logl (p. 537) Sspace (p. 931) Var (p. 1141)

Matrix (p. 554) String (p. 961) Vector (p. 1221)

Model (p. 606) Svector (p. 968)

Details on each of the commands associated with each of these objects are provided in the
section beginning on the specified page in the Object Reference.

For example, the declaration,

series lgdp

creates a new series called LGDP, while the command:

equation eq1

creates a new equation object called EQ1.

Matrix objects are typically declared with their dimension as an option provided in paren-
theses after the object type. For example:
matrix(5,5) x

creates a 5  5 matrix named X, while

coef(10) results

creates a 10 element coefficient vector named RESULTS.

Simple declarations initialize the object with default values; in some cases, the defaults have
a meaningful interpretation, while in other cases, the object will simply be left in an incom-
plete state. In our examples, the newly created LGDP will contain all NA values and X and
RESULTS will be initialized to 0, while EQ1 will be simply be an uninitialized equation con-
taining no estimates.

Note that in order to declare an object you must have a workfile currently open in EViews.
You may open or create a workfile interactively from the File Menu or drag-and-dropping a
file onto EViews (see Chapter 2. “Workfile Basics,” on page 29 of User’s Guide I for details),
or you can may use the wfopen (p. 640) command to perform the same operations inside a
program.

Object Assignment
Object assignment statements are commands which assign data to an EViews object using
the “=” sign. Object assignment statements have the syntax:
object_name = expression
20—Chapter 1.Object Declaration and Initialization

where object_name identifies the object whose data is to be modified and expression is an
expression which evaluates to an object of an appropriate type. Note that not all objects per-
mit object assignment; for example, you may not perform assignment to an equation object.
(You may, however, initialize the equation using a command method.)

The nature of the assignment varies depending on what type of object is on the left hand
side of the equal sign. To take a simple example, consider the assignment statement:
x = 5 * log(y) + z

where X, Y and Z are series. This assignment statement will take the log of each element of
Y, multiply each value by 5, add the corresponding element of Z, and, finally, assign the
result into the appropriate element of X.

Similarly, if M1, M2, and M3 are matrices, we may use the assignment statement:
m1 = @inverse(m2) * m3

to postmultiply the matrix inverse of M2 by M3 and assign the result to M1. This statement
presumes that M2 and M3 are suitably conformable.

Object Modification
In cases where direct assignment using the “=” operator is not allowed, one may initialize
the object using one or more object commands. We will discuss object commands in greater
detail in a moment (see “Object Commands,” on page 21) but for now simply note that
object commands may be used to modify the contents of an existing object.

For example:
eq1.ls log(cons) c x1 x2

uses an object command to estimate the linear regression of the LOG(CONS) on a constant,
X1, and X2, and places the results in the equation object EQ1.
sys1.append y=c(1)+c(2)*x
sys1.append z=c(3)+c(4)*x
sys1.ls

adds two lines to the system specification, then estimates the specification using system
least squares.

Similarly:
group01.add gdp cons inv g x

adds the series GDP, CONS, INV, G, and X to the group object GROUP01.
 Object Commands—21

More on Object Declaration

Object declaration may often be combined with assignment or command initialization. For
example:
series lgdp = log(gdp)

creates a new series called LGDP and initializes its elements with the log of the series GDP.
Similarly:
equation eq1.ls y c x1 x2

creates a new equation object called EQ1 and initializes it with the results from regressing
the series Y against a constant term, the series X1 and the series X2.

Lastly:
group group01 gdp cons inv g x

create the group GROUP01 containing the series GDP, CONS, INV, G, and X.

An object may be declared multiple times so long as it is always declared to be of the same
type. The first declaration will create the object, subsequent declarations will have no effect
unless the subsequent declaration also specifies how the object is to be initialized. For
example:
smpl @first 1979
series dummy = 1
smpl 1980 @last
series dummy=0

creates a series named DUMMY that has the value 1 prior to 1980 and the value 0 thereafter.

Redeclaration of an object to a different type is not allowed and will generate an error.

Object Commands
Most of the commands that you will employ are object commands. An object command is a
command which displays a view of or performs a procedure using a specific object. Object
commands have two main parts: an action followed by a view or procedure specification.
The (optional) display action determines what is to be done with the output from the view
or procedure. The view or procedure specification may provide for options and arguments to
modify the default behavior.

The complete syntax for an object command has the form:

action(action_opt) object_name.view_or_proc(options_list) arg_list
where:
action....................is one of the four verb commands (do, freeze, print, show).
22—Chapter 1.Object Commands

action_opt ............ an option that modifies the default behavior of the action.
object_name.......... the name of the object to be acted upon.
view_or_proc ........ the object view or procedure to be performed.
options_list .......... an option that modifies the default behavior of the view or proce-
dure.
arg_list ................ a list of view or procedure arguments.

Action Commands
There are four possible action commands:
• show displays the object view in a window.
• do executes procedures without opening a window. If the object’s window is not cur-
rently displayed, no output is generated. If the objects window is already open, do is
equivalent to show.
• freeze creates a table or graph from the object view window.
• print prints the object view window.

As noted above, in most cases, you need not specify an action explicitly. If no action is spec-
ified, the show action is assumed for views and the do action is assumed for most proce-
dures (though some procedures will display newly created output in new windows unless
the command was executed via a batch program).

For example, when using an object command to display the line graph series view, EViews
implicitly adds a show command. Thus, the following two lines are equivalent:
gdp.line
show gdp.line

In this example, the view_or_proc argument is line, indicating that we wish to view a line
graph of the GDP data. There are no additional options or arguments specified in the com-
mand.

Alternatively, for the equation method (procedure) ls, there is an implicit do action:
eq1.ls cons c gdp
do eq1.ls cons c gdp

so that the two command lines describe equivalent behavior. In this case, the object com-
mand will not open the window for EQ1 to display the result. You may display the window
by issuing an explicit show command after issuing the initial command:
show eq1

or by combining the two commands:

show eq1.ls cons c gdp
 Object Commands—23

Similarly:
print eq1.ls cons c gdp

both performs the implicit do action and then sends the output to the printer.

The following lines show a variety of object commands with modifiers:

show gdp.line
print(l) group1.stats
freeze(output1) eq1.ls cons c gdp
do eq1.forecast eq1f

The first example opens a window displaying a line graph of the series GDP. The second
example prints (in landscape mode) descriptive statistics for the series in GROUP1. The third
example creates a table named OUTPUT1 from the estimation results of EQ1 for a least
squares regression of CONS on GDP. The final example executes the forecast procedure of
EQ1, putting the forecasted values into the series EQ1F and suppressing any procedure out-
put.

Of these four examples, only the first opens a window and displays output on the screen.

Output Control
As noted above, the display action determines the destination for view and procedure out-
put. Here we note in passing a few extensions to these general rules.

You may request that a view be simultaneously printed and displayed on your screen by
including the letter “p” as an option to the object command. For example, the expression,
gdp.correl(24, p)

is equivalent to the two commands:

show gdp.correl(24)
print gdp.correl(24)

since correl is a series view. The “p” option can be combined with other options, sepa-
rated by commas. So as not to interfere with other option processing, we recommend that
the “p” option always be specified after any required options.

Note that the print command accepts the “l” or “p” option to indicate landscape or portrait
orientation. For example:
print(l) gdp.correl(24)

Printer output can be redirected to a text file, frozen output, or a spool object. (See output
(p. 533), and the discussion in “Print Setup” on page 2562 of User’s Guide I for details.)

The freeze command used without options creates an untitled graph or table from a view
specification:
24—Chapter 1.Object Commands

freeze gdp.line

You also may provide a name for the frozen object in parentheses after the word freeze.
For example:
freeze(figure1) gdp.bar

names the frozen bar graph of GDP as “figure1”.

View and Procedure Commands

Not surprisingly, the view or procedure commands correspond to elements of the views and
procedures menus for the various objects.

For example, the top level of the view menu for the series
object allows you to: display a spreadsheet view of the data,
graph the data, perform a one-way tabulation, compute and
display a correlogram or long-run variance, perform unit root
or variance ratio tests, conduct a BDS independence test, or
display or modify the label view.

Object commands exist for each of these views. Suppose for

example, that you have the series object SER01. Then:
ser01.sheet
ser01.stats

display the spreadsheet and descriptive statistics views of the data in the series. There are a
number of graph commands corresponding to the menu entry, so that you may enter:
ser01.line
ser01.bar
ser01.hist

which display a line graph, bar graph, and histogram, respectively, of the data in SER01.
Similarly,
ser01.freq

performs a one-way tabulation of the data, and:

ser01.correl
ser01.lrvar
ser01.uroot
ser01.vratio 2 4 8
ser01.bdstest

display the correlogram and long-run variances, and conduct unit root, variance ratio, and
independence testing for the data in the series. Lastly:
 Object Data Members—25

ser01.label(r) "this is the added series label"

appends the text “this is the added series label” to the end of the remarks field.

There are commands for all of the views and procedures of each EViews object. Details on
the syntax of each of the object commands may be found in Chapter 1. “Object View and
Procedure Reference,” beginning on page 3 in the Object Reference.

Object Data Members

Every object type in EViews has a selection of global data members. Custom data members
object may also be added to an object. These members contain information about the object
and can be retrieved from an object to be used as part of another command, or stored into
the workfile as a new object.

Custom attributes must be added interactively via the label view of an object. Retrieving
custom and default data members however can be accessed by using the “@attr” data mem-
ber.

The following data members belong to every object type in EViews:

Data Member Name Description

Returns the name of the
@name
object
Returns the display name of
the object. If the object has
@displayname
no display name, the name is
returned
@type Returns the object type
Returns the description of the
@description
object (if available)
Returns the remarks of the
@remarks
object (if available)
Returns the string representa-
@updatetime tion of the time the object
was last updated

Along with these global data members, each object type has a set of data members specific
to that type. For example, equation objects have a data member, @r2, that returns a scalar
containing the R-squared from that equation. Groups have an member, @count, that returns
a scalar containing the number of series contained within that group. A full list of each
object’s data members can be found under the object’s section in Chapter 1. “Object View
and Procedure Reference,” on page 3 of the Object Reference.
26—Chapter 1.Interactive Commands

As an example of using data members, the commands:

equation eq1.ls y c x1 x2
table tab1
tab1(1,1) = eq1.@f

create an equation named EQ1 and a table named TAB1, and then set the first cell of the
table equal to the F-statistic from the estimated equation.

Interactive Commands
There is also a set of auxiliary commands which are designed to facilitate interactive use.
These commands perform the same operations as equivalent object commands, but do so
on newly created, unnamed objects. For example, the command:
ls y c x1 x2

will regress the series Y against a constant term, the series X1 and the series X2, and create
a new untitled equation object to hold the results.

Similarly, the command:

scat x y

creates an untitled group object containing the series X and Y and then displays a scatterplot
of the data in the two series.

Since these commands are designed primarily for interactive use, they are designed for car-
rying out simple tasks. Overuse of these interactive tools, or their use in programs, will
make it difficult to manage your work since unnamed objects cannot be referenced by name
from within a program, cannot be saved to disk, and cannot be deleted except through the
graphical Windows interface. In general, we recommend that you use named objects rather
than untitled objects for your work. For example, we may replace the first auxiliary com-
mand above with the statement:
equation eq1.ls y c x1 x2

to create the named equation object EQ1. This example uses declaration of the object EQ1
and the equation method ls to perform the same task as the auxiliary command above.

Similarly,
group mygroup x y
mygroup.scat

displays the scatterplot of the series in the named group MYGROUP.

 Auxiliary Commands—27

Auxiliary Commands
Auxiliary commands are commands which are unrelated to a particular object (i.e., are not
object views or procs), or act on an object in a way that is generally independent of the type
or contents of the object. Many of the important auxiliary commands are used for managing
objects, and object containers. A few of the more important commands are described below.

Auxiliary commands typically follow the syntax:

command(option_list) argument_list
where command is the name of the command, option_list is a list of options separated by
commas, and argument_list is a list of arguments generally separated by spaces.

An example of an auxiliary command is:

store(d=c:\newdata\db1) gdp m x

which will store the three objects GDP, M and X in the database named DB1 in the directory
C:\NEWDATA.

Managing Workfiles and Databases

There are two types of object containers: workfiles and databases. All EViews objects must
be held in an object container, so before you begin working with objects you must create a
workfile or database. Workfiles and databases are described in depth in Chapter 2. “Workfile
Basics,” beginning on page 29 and Chapter 10. “EViews Databases,” beginning on page 333
of User’s Guide I.

Managing Workfiles
To declare and create a new workfile, you may use the wfcreate (p. 634) command. You
may enter the keyword wfcreate followed by a name for the workfile, an option for the fre-
quency of the workfile, and the start and end dates. The most commonly used workfile fre-
quency type options are:

a annual.
s semi-annual.
q quarterly.
m monthly.
w weekly.
d daily (5 day week).
7 daily (7 day week).
u undated/unstructured.
28—Chapter 1.Auxiliary Commands

but there are additional options for multi-year, bimonthly, fortnight, ten-day, daily with cus-
tom week, intraday, integer date, and undated frequency workfiles.

For example:
wfcreate macro1 q 1965Q1 1995Q4

creates a new quarterly workfile named MACRO1 from the first quarter of 1965 to the fourth
quarter of 1995.
wfcreate cps88 u 1 1000

creates a new undated workfile named CPS88 with 1000 observations.

Alternately, you may use wfopen (p. 640) to read a foreign data source into a new workfile.

If you have multiple open workfiles, the wfselect (p. 663) command may be used to
change the active workfile.

To save the active workfile, use the wfsave (p. 656) command by typing the keyword
wfsave followed by a workfile name. If any part of the path or workfile name has spaces,
you should enclose the entire expression in quotation marks. The active workfile will be
saved in the default path under the given name. You may optionally provide a path to save
the workfile in a different directory:
wfsave a:\mywork

If necessary, enclose the path name in quotations.

To close the workfile, use the close (p. 393) command. For example:
close mywork

closes the workfile window of MYWORK.

To open a previously saved workfile, use the wfopen (p. 640) command. You should follow
the keyword with the name of the workfile. You can optionally include a path designation to
open workfiles that are not saved in the default path. For example:
wfopen "c:\mywork\proj1"

Managing Databases
To create a new database, follow the dbcreate (p. 426) command keyword with a name for
the new database. Alternatively, you could use the db (p. 424) command keyword followed
by a name for the new database. The two commands differ only when the named database
already exists.

If you use dbcreate and the named database already exists on disk, EViews will error indi-
cating that the database already exits. If you use db and the named database already exists
 Auxiliary Commands—29

on disk, EViews will simply open the existing database. Note that the newly opened data-
base will become the default database.

For example:
dbcreate mydata1

creates a new database named MYDATA1 in the default path, opens a new database win-
dow, and makes MYDATA1 the default database.
db c:\evdata\usdb

opens the USDB database in the specified directory if it already exists. If it does not, EViews
creates a new database named USDB, opens its window, and makes it the default database.

You may use dbopen (p. 428) to open an existing database and to make it the default data-
base. For example:
dbopen findat

opens the database named FINDAT in the default directory. If the database does not exist,
EViews will error indicating that the specified database cannot be found.

You may use dbrename to rename an existing database. Follow the dbrename keyword by
the current (old) name and a new name:
dbrename temp1 newmacro

To delete an existing database, use the dbdelete (p. 428) command. Follow the dbdelete
keyword by the name of the database to delete:
dbdelete c:\data\usmacro

dbcopy (p. 424) makes a copy of the existing database. Follow the dbcopy keyword with
the name of the source file and the name of the destination file:
dbcopy c:\evdata\macro1 a:\macro1

dbpack (p. 431) and dbrebuild (p. 431) are database maintenance commands. See also
Chapter 10. “EViews Databases,” beginning on page 333 of User’s Guide I for a detailed
description.

Managing Objects
In the course of a program you will often need to manage the objects in a workfile by copy-
ing, renaming, deleting and storing them to disk. EViews provides a number of auxiliary
commands which perform these operations. The following discussion introduces you to the
most commonly used commands; a full description of these, and other commands is pro-
vided in Chapter 17. “Command Reference,” on page 357.
30—Chapter 1.Auxiliary Commands

Copying Objects
You may create a duplicate copy of one or more objects using the copy (p. 411) command.
The copy command is an auxiliary command with the format:
copy source_name dest_name

where source_name is the name of the object you wish to duplicate, and dest_name is the
name you want attached to the new copy of the object.

The copy command may also be used to copy objects in databases and to move objects
between workfiles and databases.

Copy with Wildcard Characters

EViews supports the use of wildcard characters (“?” for a single character match and “*” for
a pattern match) in destination specifications when using the copy and rename commands.
Using this feature, you can copy or rename a set of objects whose names share a common
pattern in a single operation. This features is useful for managing series produced by model
simulations, series corresponding to pool cross-sections, and any other situation where you
have a set of objects which share a common naming convention.

A destination wildcard pattern can be used only when a wildcard pattern has been provided
for the source, and the destination pattern must always conform to the source pattern in that
the number and order of wildcard characters must be exactly the same between the two. For
example, the patterns:

Source Pattern Destination Pattern

x* y*
*c b*
x*12? yz*f?abc

conform to each other. These patterns do not:

Source Pattern Destination Pattern

a* b
*x ?y
x*y* *x*y*

When using wildcards, the destination name is formed by replacing each wildcard in the
destination pattern by the characters from the source name that matched the corresponding
wildcard in the source pattern. Some examples should make this principle clear:
 Auxiliary Commands—31

Source Pattern Destination Pattern Source Name Destination Name

*_base *_jan x_base x_jan
us_* * us_gdp gdp
x? x?f x1 x1f
*_* **f us_gdp usgdpf
??*f ??_* usgdpf us_gdp

Note, as shown in the second example, that a simple asterisk for the destination pattern
does not mean to use the unaltered source name as the destination name. To copy objects
between containers preserving the existing name, either repeat the source pattern as the des-
tination pattern,
copy x* db1::x*

or omit the destination pattern entirely:

copy x* db1::

If you use wildcard characters in the source name and give a destination name without a
wildcard character, EViews will keep overwriting all objects which match the source pattern
to the name given as destination.

For additional discussion of wildcards, see Appendix A. “Wildcards,” on page 1227.

Renaming Objects
You can give an object a different name using the rename (p. 573) command. The rename
command has the format:
rename source_name dest_name

where source_name is the original name of the object and dest_name is the new name you
would like to give to the object.

rename can also be used to rename objects in databases.

You may use wildcards when renaming series. The name substitution rules are identical to
those described above for copy.

Deleting Objects
Objects may be removed from the workfile or a database using the delete command. The
delete command has the format:
delete name_pattern

where name_pattern can either be a simple name such as “XYZ”, or a pattern containing
the wildcard characters “?” and “*”, where “?” means to match any one character, and “*”
32—Chapter 1.Auxiliary Commands

means to match zero or more characters. When a pattern is provided, all objects in the
workfile with names matching the pattern will be deleted. Appendix A. “Wildcards,” on
page 1227 describes further the use of wildcards.

Saving Objects
All named objects will be saved automatically in the workfile when the workfile is saved to
disk. You can store and retrieve the current workfile to and from disk using the wfsave
(p. 656) and wfopen (p. 640) commands. Unnamed objects will not be saved as part of the
workfile.

You can also save objects for later use by storing them in a database. The store (p. 600)
command has the format:
store(option_list) object1 object2 …

where object1, object2, ..., are the names of the objects you would like to store in the data-
base. If no options are provided, the series will be stored in the current default database (see
Chapter 10. “EViews Databases,” on page 333 of User’s Guide I for a discussion of the
default database). You can store objects into a particular database by using the option
“d=db_name” or by prepending the object name with a database name followed by a dou-
ble colon “::”, such as:
store db1::x db2::x

Fetch Objects
You can retrieve objects from a database using the fetch (p. 449) command. The fetch
command has the same format as the store command:
fetch(option_list) object1 object2 …

To specify a particular database use the “d=” option or the “::” extension as for store.
Chapter 2. Working with Graphs

EViews provides an extensive set of commands to generate and customize graphs from the
command line or using programs. A summary of the graph commands described below may
be found under “Graph” on page 368 of the Object Reference.

In addition, Chapter 15. “Graph Objects,” on page 867 of User’s Guide I describes graph cus-
tomization in detail, focusing on the interactive method of working with graphs.

Creating a Graph
There are three types of graphs in EViews: graphs that are views of other objects, and named
or unnamed graph objects. The commands provided for customizing the appearance of your
graphs are available for use with named graph objects. You may use the dialogs interactively
to modify the appearance of all types of graphs.

Displaying graphs using commands

The simplest way to display a graph view is to use one of the basic graph commands.
(“Graph Creation Commands” on page 361 provides a convenient listing.)

Where possible EViews will simply open the object and display the appropriate graph view.
For example, to display a line or bar graph of the series INCOME and CONS, you may simply
issue the commands:
line income
bar cons

In other cases, EViews must first create an unnamed object and then will display the desired
view of that object. For example:
scat x y z

first creates an unnamed group object containing the three series and then, using the scat
view of a group, displays scatterplots of Y on X and Z on X in a single frame.

As with other EViews commands, graph creation commands allow you to specify a variety
of options and arguments to modify the default graph settings. You may, for example, rotate
the bar graph using the “rotate” option,
bar(rotate) cons

or you may display boxplots along the borders of your scatter plot using:
scat(ab=boxplot) x y z
34—Chapter 2.Creating a Graph

Note that while using graph commands interactively may be quite convenient, these com-
mands are not recommended for program use since you will not be able to use the resulting
unnamed objects in your program.

The next section describes a more flexible approach to displaying graphs.

Displaying graphs as object views

You may display a graph of an existing object using a graph view command. For example,
you may use the following two commands to display graph views of a series and a group:
ser2.area(n)
grp6.xypair

The first command plots the series SER2 as an area graph with normalized scaling. The sec-
ond command provides an XY line graph view of the group GRP6, with the series plotted in
pairs.

To display graphs for multiple series, we may first create a group containing the series and
then display the appropriate view:
group g1 x y z
g1.scat

shows the scatterplot of the series in the newly created group G1.

There are a wide range of sophisticated graph views that you may display using commands.
See Chapter . “,” beginning on page 1266 of the Object Reference for a detailed listing along
with numerous examples.

Before proceeding, it is important to note that graph views of objects differ from graph
objects in important ways:
• First, graph views of objects may not be customized using commands after they are
first created. The graph commands for customizing an existing graph are designed for
use with graph objects.
• Second, while you may use interactive dialogs to customize an existing object’s graph
view, we caution you that there is no guarantee that the customization will be perma-
nent. In many cases, the customized settings will not be saved with the object and
will be discarded when the view changes or if the object is closed and then reopened.
In contrast, graph objects may be customized extensively after they are created. Any
customization of a graph object is permanent, and will be saved with the object.

Since construction of a graph view is described in detail elsewhere (Chapter . “,” beginning
on page 1266 of the Object Reference), we focus the remainder of our attention on the cre-
ation and customization of graph objects.
 Creating a Graph—35

Creating graph objects from object views

If you wish to create a graph object from another object, you should combine the object
view command with the freeze command. Simply follow the freeze keyword with an
optional name for the graph object, and the object view to be frozen. For example,
freeze grp6.xypair(m)

creates and displays an unnamed graph object of the GRP6 view showing an XY line graph
with the series plotted in pairs in multiple graph frames. Be sure to specify any desired
graph options (e.g., “m”). Note that freezing an object view will not necessarily copy the
existing custom appearance settings such as line color, axis assignment, etc. For this reason
that we recommend that you create a graph object before performing extensive customiza-
tion of a view.

You should avoid creating unnamed graphs when using commands in programs since you
will be unable to refer to, or work with the resulting object in a program. Instead, you
should tell EViews to create a named object, as in:
freeze(graph1) grp6.line

which creates a graph object GRAPH1 containing a line graph of the data in GRP6. By
default, the frozen graph will have updating turned off, but in most cases you may use the
Graph::setupdate graph proc to turn updating on.

Note that using the freeze command with a name for the graph will create the graph object
and store it in the workfile without showing it. Furthermore, since we have frozen a graph
type (line) that is different from our current XY line view, existing custom appearance set-
tings will not be copied to the new graph.

Once you have created a named graph object, you may use the various graph object procs to
further customize the appearance of your graph. See “Customizing a Graph,” beginning on
page 38.

Creating named graph objects

There are three direct methods for creating a named graph object. First, you may use the
freeze command as described above. Alternatively, you may declare a graph object using
the graph command. The graph command may be used to create graph objects with a spe-
cific graph type or to merge existing graph objects.

Specifying a graph by type

To specify a graph by type you should use the graph keyword, followed by a name for the
graph, the type of graph you wish to create, and a list of series (see “Graph Type Com-
mands” on page 368 of the Object Reference for a list of types). If a type is not specified, a
line graph will be created.
36—Chapter 2.Creating a Graph

For example, both:

graph gr1 ser1 ser2
graph gr2.line ser1 ser2

create graph objects containing the line graph view of SER1 and SER2, respectively.

Similarly:
graph gr3.xyline group3

creates a graph object GR3 containing the XY line graph view of the series in GROUP3.

Each graph type provides additional options, which may be included when declaring the
graph. Among the most important options are those for controlling scaling or graph type.

The scaling options include:

• Automatic scaling (“a”), in which series are graphed using the default single scale.
The default is left scale for most graphs, or left and bottom for XY graphs.
• Dual scaling without crossing (“d”) scales the first series on the left and all other
series on the right. The left and right scales will not overlap.
• Dual scaling with possible crossing (“x”) is the same as the “d” option, but will allow
the left and right scales to overlap.
• Normalized scaling (“n”), scales using zero mean and unit standard deviation.

For example, the commands:

graph g1.xyline(d) unemp gdp inv
show g1

create and display an XY line graph of the specified series with dual scales and no crossing.

The graph type options include:

• Mixed graph (“l”) creates a single graph in which the first series is the selected graph
type (bar, area, or spike) and all remaining series are line graphs.
• Multiple graph (“m”) plots each graph in a separate frame.
• Stacked graph (“s”) plots the cumulative addition of the series, so the value of a series
is represented as the difference between the lines, bars, or areas.

For example, the commands:

group grp1 sales1 sales2
graph grsales.bar(s) grp1
show grsales
 Changing Graph Types—37

create a group GRP1 containing the series SALES1 and SALES2, then create and display a
stacked bar graph GRSALES of the series in the group.

You should consult the command reference entry for each graph type for additional informa-
tion, including a list of the available options (i.e., see bar for complete details on bar
graphs, and line for details on line graphs).

Merging graph objects

The graph command may also be used to merge existing named graph objects into a named
multiple graph object. For example:
graph gr2.merge gr1 grsales

creates a multiple graph object GR2, combining two graph objects previously created.

Creating unnamed graph objects

There are two ways of creating an unnamed graph object. First, you may use the freeze
command as described in “Creating graph objects from object views” on page 35.

As we have seen earlier you may also use any of the graph type keywords as a command
(“Displaying graphs using commands” on page 33). Follow the keyword with any available
options for that type, and a list of the objects to graph. EViews will create an unnamed
graph of the specified type that is not stored in the workfile. For instance:
line(x) ser1 ser2 ser3

creates a line graph with series SER1 scaled on the left axis and series SER2 and SER3 scaled
on the right axis.

If you later decide to name this graph, you may do so interactively by clicking on the Name
button in the graph button bar. Alternatively, EViews will prompt you to name or delete any
unnamed objects before closing the workfile.

Note that there is no way to name an unnamed graph object in a program. We recommend
that you avoid creating unnamed graphs in programs since you will be unable to use the
resulting object.

Changing Graph Types

You may change the graph type of a named graph object by following the object name with
the desired graph type keyword and any options for that type. For example:
grsales.bar(l)

converts the bar graph GRSALES, created above, into a mixed bar-line graph, where SALES1
is plotted as a bar graph and SALES2 is plotted as a line graph within a single graph.
38—Chapter 2.Customizing a Graph

Note that specialized graphs, such as boxplots, place limitations on your ability to change
the graph type. In general, your ability to customize the graph settings is more limited when
changing graph types than when generating the graph from the original data.

Graph options are generally preserved when changing graph types. This includes attributes
such as line color and axis assignment, as well as objects added to the graph, such as text
labels, lines and shading. Commands to modify the appearance of named graph objects are
described in “Customizing a Graph” on page 38.

Note, however, that the line and fill graph settings are set independently. Line attributes
apply to line and spike graphs, while fill attributes apply to bar, area, and pie graphs. For
example, if you have modified the color of a line in a spike graph, this color will not be used
for the fill area if the graph is changed to an area graph.

Customizing a Graph
EViews provides a wide range of tools for customizing the appearance of a named graph
object. Nearly every display characteristic of the graph may be modified, including the
appearance of lines and filled areas, legend characteristics and placement, frame size and
attributes, and axis settings. In addition, you may add text labels, lines, and shading to the
graph.

You may modify the appearance of a graph using dialogs or via the set of commands
described below. Note that the commands are only available for graph objects since they
take the form of graph procedures.

An overview of the relationship between the tabs of the graph dialog and the associated
graph commands is illustrated below:
 Customizing a Graph—39

Line characteristics
For each data line in a graph, you may modify color, width, pattern and symbol using the
Graph::setelem command. Follow the command keyword with an integer representing
the data element in the graph you would like to modify, and one or more keywords for the
characteristic you wish to change. List of symbol and pattern keywords, color keywords, and
RGB settings are provided in Graph::setelem.

To modify line color and width you should use the lcolor and lwidth keywords:
graph gr1.line ser1 ser2 ser3
gr1.setelem(3) lcolor(orange) lwidth(2)
gr1.setelem(3) lcolor(255, 128, 0) lwidth(2)

The first command creates a line graph GR1 with colors and widths taken from the global
defaults, while the latter two commands equivalently change the graph element for the third
series to an orange line 2 points wide.

Each data line in a graph may be drawn with a line, symbols, or both line and symbols. The
drawing default is given by the global options, but you may elect to add lines or symbols
using the lpattern or symbol keywords.

To add circular symbols to the line for element 3, you may enter:
gr1.setelem(3) symbol(circle)

Note that this operation modifies the existing options for the symbols, but that the line type,
color and width settings from the original graph will remain. To return to line only or sym-
bol only in a graph in which both lines and symbols are displayed, you may turn off either
symbols or patterns, respectively, by using the “none” type:
gr1.setelem(3) lpat(none)

or
gr1.setelem(3) symbol(none)

The first example removes the line from the drawing for the third series, so only the circular
symbol is used. The second example removes the symbol, so only the line is used.

If you attempt to remove the lines or symbols from a graph element that contains only lines
or symbols, respectively, the graph will change to show the opposite type. For example:
gr1.setelem(3) lpat(dash2) symbol(circle)
gr1.setelem(3) symbol(none)
gr1.setelem(3) lpat(none)

initially represents element 3 with both lines and symbols, then turns off symbols for ele-
ment 3 so that it is displayed as lines only, and finally shows element 3 as symbols only,
since the final command turns off lines in a line-only graph.
40—Chapter 2.Customizing a Graph

The examples above describe customization of the basic elements common to most graph
types. “Modifying Boxplots” on page 52 provides additional discussion of Graph::setelem
options for customizing boxplot data elements.

Use of color with lines and filled areas

By default, EViews automatically formats graphs to accommodate output in either color or
black and white. When a graph is sent to a printer or saved to a file in black and white,
EViews translates the colored lines and fills seen on the screen into an appropriate black and
white representation. The black and white lines are drawn with line patterns, and fills are
drawn with gray shading. Thus, the appearance of lines and fills on the screen may differ
from what is printed in black and white (this color translation does not apply to boxplots).

You may override this auto choice display method by changing the global defaults for
graphs. You may choose, for example, to display all lines and fills as patterns and gray
shades, respectively, whether the graph uses color or not. All subsequently created graphs
will use the new settings.

Alternatively, if you would like to override the color, line pattern, and fill settings for a given
graph object, you may use the Graph::options graph proc.

Color
To change the color setting for an existing graph object, you should use options with the
color keyword. If you wish to turn off color altogether for all lines and filled areas, you
should precede the keyword with a negative sign, as in:
gr1.options -color

To turn on color, you may use the same command with the “-” omitted.

Lines and patterns

To always display solid lines in your graph, irrespective of the color setting, you should use
options with the linesolid keyword. For example:
gr1.options linesolid

sets graph GR1 to use solid lines when rendering on the screen in color and when printing,
even if the graph is printed in black and white. Note that this setting may make identifica-
tion of individual lines difficult in a printed black and white graph, unless you change the
widths or symbols associated with individual lines (see “Line characteristics” on page 39).

Conversely, you may use the linepat option to use patterned lines regardless of the color
setting:
gr1.options linepat
 Customizing a Graph—41

One advantage of using the linepat option is that it allows you to see the pattern types that
will be used in black and white printing without turning off color in your graph. For exam-
ple, using the Graph::setelem command again, change the line pattern of the second
series in GR1 to a dashed line:
gr1.setelem(2) lpat(dash1)

This command will not change the appearance of the colored lines on the screen if color is
turned on and auto choice of line and fill type is set. Thus, the line will remain solid, and
the pattern will not be visible until the graph is printed in black and white. To view the cor-
responding patterns, either turn off color so all lines are drawn as black patterned lines, or
use the linepat setting to force patterns.

To reset the graph or to override modified global settings so that the graph uses auto choice,
you may use the lineauto keyword:
gr1.options lineauto

This setting instructs the graph to use solid lines when drawing in color, and use line pat-
terns and gray shades when drawing in black and white.

Note that regardless of the color or line pattern settings, you may always view the selected
line patterns in the Lines & Symbols section of the graph options dialog. The dialog can be
brought up interactively by double clicking anywhere in the graph.

Filled area characteristics

You can modify the color, gray shade, and hatch pattern of each filled area in a bar, area, or
pie graph.

To modify these settings, use Graph::setelem, followed by an integer representing the

data element in the graph you would like to modify, and a keyword for the characteristic you
wish to change. For example, consider the commands:
graph mygraph.area(s) series1 series2 series3
mygraph.setelem(1) fcolor(blue) hatch(fdiagonal) gray(6)
mygraph.setelem(1) fcolor(0, 0, 255) hatch(fdiagonal) gray(6)

The first command creates MYGRAPH, a stacked area graph of SERIES1, SERIES2, and
SERIES3. The latter two commands are equivalent, modifying the first series by setting its
fill color to blue with a forward diagonal hatch. If MYGRAPH is viewed without color, the
area will appear with a hatched gray shade of index 6.

See Graph::setelem for a list of available color keywords, and for gray shade indexes and
available hatch keywords. Note that changes to gray shades will not be visible in the graph
unless color is turned off.
42—Chapter 2.Customizing a Graph

Using preset lines and fills

For your convenience, EViews provides you with a collection of preset line and fill character-
istics. Each line preset defines a color, width, pattern, and symbol for a line, and each fill
preset defines a color, gray shade, and hatch pattern for a fill. There are thirty line and thirty
fill presets.

The global graph options are initially set to use the EViews preset settings. These global
options are used when you first create a graph, providing a different appearance for each
line or fill. The first line preset is applied to the first data line, the second preset is applied to
the second data line, and so on. If your graph contains more than thirty lines or fills, the pre-
sets are simply reused in order.

You may customize the graph defaults in the global Graph Options dialog. Your settings will
replace the existing EViews defaults, and will be applied to all graphs created in the future.

EViews allows you to use either the original EViews presets, or those you have specified in
the global Graph Options dialog when setting the characteristics of an existing graph. The
keyword preset is used to indicate that you should use the set of options from the corre-
sponding EViews preset; the keyword default is used to indicate that you should use the
set of options from the corresponding global graph element defaults.

For example:
mygraph.setelem(2) preset(3)

allows the second fill area in MYGRAPH to use the original EViews presets for a third fill
area. In current versions of EViews, these settings include a green fill, a medium gray shade
of 8, and no hatch.

Alternatively:
mygraph.setelem(2) default(3)

also changes the second area of MYGRAPH, but uses the third set of user-defined presets. If
you have not yet modified your global graph defaults, the two commands will yield identical
results.

When using the preset or default keywords with boxplots, the line color of the specified
preset will be applied to all boxes, whiskers, and staples in the graph. See “Modifying Box-
plots” on page 52 for additional information.

Scaling and axes

There are four commands that may be used to modify the axis and scaling characteristics of
your graphs:
• First, the Graph::setelem command with the axis keyword may be used to assign
data elements to different axes.
 Customizing a Graph—43

• Second, the Graph::axis command can be used to customize the appearance of any
axes in the graph object. You may employ the axis command to modify the scaling of
the data itself, for example, as when you use a logarithmic scale, or to alter the scaling
of the axis, as when you enable dual scaling. The axis command may also be used to
change the appearance of axes, such as to modify tick marks, change the font size of
axis labels, turn on grid or zero lines, or duplicate axes.
• Third, the Graph::datelabel command modifies the labeling of the bottom date/
time axis in time plots. Use this command to change the way date labels are formatted
or to specify label frequency.
• Finally, the Graph::setobslabel command may be used to create custom axis
labels for the observation scale of a graph.

Assigning data to an axis

In most cases, when a graph is created, all data elements are initially assigned to the left
axis. XY graphs differ slightly in that data elements are initially assigned to either the left or
bottom axis.

Once a graph is created, individual elements may generally be assigned to either the left or
right axis. In XY graphs, you may reassign individual elements to either the left, right, top,
or bottom axis, while in boxplots or stacked time/observation graphs all data elements must
be assigned to the same vertical axis.

To assign a data element to a different axis, use the setelem command with the axis key-
word. For example, the commands:
graph graph02.line ser1 ser2
graph02.setelem(2) axis(right)

first create GRAPH02, a line graph of SER1 and SER2, and then turn GRAPH02 into a dual
scaled graph by assigning the second data element, SER2, to the right axis.

In this example, GRAPH02 uses the default setting for dual scale graphs by disallowing
crossing, so that the left and right scales do not overlap. To allow the scales to overlap, use
the axis command with the overlap keyword, as in:
graph02.axis overlap

The left and right scales now span the entire axes, allowing the data lines to cross. To
reverse this action and disallow crossing, use -overlap, (the overlap keyword preceded
by a minus sign, “–”).

For XY graphs without pairing, the first series is generally plotted along the bottom axis, and
the remaining series are plotted on the left axis. XY graphs allow more manipulation than
time/observation plots, because the top and bottom axes may also be assigned to an ele-
ment. For example:
44—Chapter 2.Customizing a Graph

graph graph03.xyline s1 s2 s3 s4
graph03.setelem(1) axis(top)
graph03.setelem(2) axis(right)

first creates an XY line graph GRAPH03 of the series S1, S2, S3, and S4. The first series is
then assigned to the top axis, and the second series is moved to the right axis. Note that the
graph now uses three axes: top, left, and right.

Note that the element index in the setelem command is not necessary for boxplots and
stacked time/observation graphs, since all data elements must be assigned to the same ver-
tical axis.

While EViews allows dual scaling for the vertical axes in most graph types, the horizontal
axes must use a single scale on either the top or bottom axis. When a new element is moved
to or from one of the horizontal axes, EViews will, if necessary, reassign elements as
required so that there is a single horizontal scale.

For example, using the graph created above, the command:

graph03.setelem(3) axis(bottom)

moves the third series to the bottom axis, forcing the first series to be reassigned from the
top to the left axis. If you then issue the command:
graph03.setelem(3) axis(right)

EViews will assign the third series to the right axis as directed, with the first (next available
element, starting with the first) series taking its place on the horizontal bottom axis. If the
first element is subsequently moved to a vertical axis, the second element will take its place
on the horizontal axis, and so forth. Note that series will never be reassigned to the right or
top axis, so that series that placed on the top or right axis and subsequently reassigned will
not be replaced automatically.

For XY graphs with pairing, the same principles apply. However, since the elements are
graphed in pairs, there is a set of elements that should be assigned to the same horizontal
axis. You can switch which set is assigned to the horizontal using the axis keyword. For
example:
graph graph04.xypair s1 s2 s3 s4
graph03.setelem(1) axis(left)

creates an XY graph that plots the series S1 against S2, and S3 against S4. Usually, the
default settings assign the first and third series to the bottom axis, and the second and
fourth series to the left axis. The second command line moves the first series (S1) from the
bottom to the left axis. Since S1 and S3 are tied to the same axis, the S3 series will also be
assigned to the left axis. The second and fourth series (S2 and S4) will take their place on
the bottom axis.
 Customizing a Graph—45

Modifying the data axis

The Graph::axis command may be used to change the way data is scaled on an axis. To
rescale the data, specify the axis you wish to change and use one of the following keywords:
linear, linearzero (linear with zero included in axis), log (logarithmic), norm (stan-
dardized). For example:
graph graph05.line ser1 ser2
graph05.axis(left) log

creates a line graph GRAPH05 of the series SER1 and SER2, and changes the left axis scaling
method to logarithmic.

The interaction of the data scales (these are the left and right axes for non-XY graphs) can
be controlled using axis with the overlap keyword. The overlap keyword controls the
overlap of vertical scales, where each scale has at least one series assigned to it. For
instance:
graph graph06.line s1 s2
graph06.setelem(2) axis(right)
graph06.axis overlap

first creates GRAPH06, a line graph of series S1 and S2, and assigns the second series to the
right axis. The last command allows the vertical scales to overlap.

The axis command may also be used to change or invert the endpoints of the data scale,
using the range or invert keywords:
graph05.axis(left) -invert range(minmax)

inverts the left scale of GRAPH05 (“–” indicates an inverted scale) and sets its endpoints to
the minimum and maximum values of the data.

Modifying the date/time axis

EViews automatically determines an optimal set of labels for the bottom axis of time plots. If
you wish to modify the frequency or date format of the labels, you should use the
Graph::datelabel command. Alternately, to create editable labels on the observation
scale, use the Graph::setobslabel command.

To control the number of observations between labels, use datelabel with the interval
keyword to specify a desired step size. The stand-alone step size keywords include: auto
(use EViews' default method for determining step size), ends (label first and last observa-
tions), and all (label every observation). For example,
mygraph.datelabel interval(ends)

labels only the endpoints of MYGRAPH. You may also use a step size keyword in conjunc-
tion with a step number to further control the labeling. These step size keywords include:
46—Chapter 2.Customizing a Graph

obs (one observation), year (one year), m (one month), and q (one quarter), where each
keyword determines the units of the number specified in the step keyword. For example, to
label every ten years, you may specify:
mygraph.datelabel interval(year, 10)

In addition to specifying the space between labels, you may indicate a specific observation
to receive a label. The step increment will then center around this observation. For example:
mygraph.datelabel interval(obs, 10, 25)

labels every tenth observation, centered around the twenty-fifth observation.

You may also use datelabel to modify the format of the dates or change their placement
on the axis. Using the format or span keywords,
mygraph02.datelabel format(yy) -span

formats the labels so that they display as two digit years, and disables interval spanning. If
interval spanning is enabled, labels will be centered between the applicable tick marks. If
spanning is disabled, labels are placed directly on the tick marks. For instance, in a plot of
monthly data with annual labeling, the labels may be centered over the twelve monthly
ticks (spanning enabled) or placed on the annual tick marks (spanning disabled).

If your axis labels require further customization, you may use the setobslabel command
to create a set of custom labels.
mygraph.setobslabel(current) "CA" "OR" "WA"

creates a set of axis labels, initializing each with the date or observation number and assigns
the labels “CA”, “OR”, and “WA” to the first three observations.

To return to EViews automatic labeling, you may use the clear option:
mygraph.setobslabel(clear)

Customizing axis appearance

You may customize the appearance of tick marks, modify label font size, add grid lines, or
duplicate axes labeling in your graph using Graph::axis.

Follow the axis keyword with a descriptor of the axis you wish to modify and one or more
arguments. For instance, using the ticksin, minor, and font keywords:
mygraph.axis(left) ticksin -minor font(10)

The left axis of MYGRAPH is now drawn with the tick marks inside the graph, no minor
ticks, and a label font size of 10 point.

To add lines to a graph, use the grid or zeroline keywords:

mygraph01.axis(left) -label grid zeroline
 Customizing a Graph—47

MYGRAPH01 hides the labels on its left axis, draws horizontal grid lines at the major ticks,
and draws a line through zero on the left scale.

In single scale graphs, it is sometimes desirable to display the axis labels on both the left and
right hand sides of the graph. The mirror keyword may be used to turn on or off the dis-
play of duplicate axes. For example:
graph graph06.line s1 s2
graph06.axis mirror

creates a line graph with both series assigned to the left axis (the default assignment), then
turns on mirroring of the left axis to the right axis of the graph. Note that in the latter com-
mand, you need not specify an axis to modify, since mirroring sets both the left and right
axes to be the same.

If dual scaling is enabled, mirroring will be overridden. In our example, assigning a data ele-
ment to the right axis:
graph06.setelem(1) axis(right)

will override axis mirroring. Note that if element 1 is subsequently reassigned to the left
scale, mirroring will again be enabled. To turn off mirroring entirely, simply precede the mir-
ror keyword with a minus sign. The command:
graph06.axis -mirror

turns off axis mirroring.

Customizing the graph frame

The graph frame is used to set the basic graph proportions and display characteristics that
are not part of the main portion of the graph.

Graph size
The graph frame size and proportions may be modified using the Graph::options com-
mand. Simply specify a width and height using the size keyword. For example:
testgraph.options size(5,4)

resizes the frame of TESTGRAPH to 5  4 virtual inches.

Other frame characteristics

The Graph::options command may also be used to modify the appearance of the graph
area and the graph frame. A variety of modifications are possible.

First, you may change the background colors in your graph, by using the “fillcolor” and
“backcolor” keywords to change the frame fill color and the graph background color, respec-
tively. The graph proc command:
48—Chapter 2.Customizing a Graph

testgraph.options fillcolor(gray) backcolor(white)

fills the graph frame with gray, and sets the graph area background color to white. Here we
use the predefined color settings (“blue,” “red,” “ltred”, “green,” “black,” “white,” “pur-
ple,” “orange,” “yellow,” “gray,” “ltgray”); alternately, you may specify “color” with three
arguments corresponding to the respective RGB settings.

You may control display of axes frames. To select which axes should have a frame, you
should use the “frameaxes” keyword:
testgraph.options frameaxes(labeled)

which turns off the frame on any axis which is not associated with data. Similarly:
testgraph.options frameaxes(lb)

draws a frame on the left and bottom axes only.

By default, EViews uses the entire width of the graph for plotting data. If you wish to indent
the data display from the edges of the graph frame, you should use the “indenth” (indent
horizontal) or “indentv” (indent vertical) keywords:
testgraph.options indenth(.05) indentv(0.1)

indents the data by 0.05 inches horizontally, and 0.10 inches vertically from the edge of the
graph frame.

The options command also allows you to add and modify grid lines in your graph. For exam-
ple:
testgraph.options gridb -gridl gridpat(dash2) gridcolor(red)

turns on dashed, red, vertical gridlines from the bottom axis, while turning off left scale gri-
dlines.

Labeling data values

Bar and pie graphs allow you to label the value of your data within the graph. Use the
Graph::options command with one of the following keywords: barlabelabove, barla-
belinside, or pielabel. For example:
mybargraph.options barlabelabove

places a label above each bar in the graph indicating its data value. Note that the label will
be visible only when there is sufficient space in the graph.

Outlining and spacing filled areas

EViews draws a black outline around each bar or area in a bar or area graph, respectively. To
disable the outline, use options with the outlinebars or outlineareas keyword:
mybargraph.options -outlinebars
 Customizing a Graph—49

Disabling the outline is useful for graphs whose bars are spaced closely together, enabling
you to see the fill color instead of an abundance of black outlines.

EViews attempts to place a space between each bar in a bar graph. This space disappears as
the number of bars increases. You may remove the space between bars by using the bar-
space keyword:
mybargraph.options -barspace

Modifying the Legend

A legend's location, text, and appearance may be customized. Note that single series graphs
and special graph types such as boxplots and histograms use text objects for labeling instead
of a legend. These text objects may only be modified interactively by double-clicking on the
object to bring up the text edit dialog.

To change the text string of a data element for use in the legend, use the Graph::name com-
mand:
graph graph06.line ser1 ser2
graph06.name(1) Unemployment
graph06.name(2) DMR

The first line creates a line graph GRAPH06 of the series SER1 and SER2. Initially, the legend
shows “SER1” and “SER2”. The second and third command lines change the text in the leg-
end to “Unemployment” and “DMR”.

Note that the name command is equivalent to using the Graph::setelem command with
the legend keyword. For instance,
graph06.setelem(1) legend(Unemployment)
graph06.setelem(2) legend(DMR)

produces the same results.

To remove a label from the legend, you may use name without providing a text string:
graph06.name(2)

removes the second label “DMR” from the legend.

For an XY graph, the name command modifies any data elements that appear as axis labels,
in addition to legend text. For example:
graph xygraph.xy ser1 ser2 ser3 ser4
xygraph.name(1) Age
xygraph.name(2) Height

creates an XY graph named XYGRAPH of the four series SER1, SER2, SER3, and SER4.
“SER1” appears as a horizontal axis label, while “SER2,” “SER3,” and “SER4” appear in the
50—Chapter 2.Customizing a Graph

legend. The second command line changes the horizontal label of the first series to “Age”.
The third line changes the second series label in the legend to “Height”.

To modify characteristics of the legend itself, use Graph::legend. Some of the primary
options may be set using the inbox, position and columns keywords. Consider, for exam-
ple, the commands:
graph graph07.line s1 s2 s3 s4
graph07.legend -inbox position(botleft) columns(4)

The first line creates a line graph of the four series S1, S2, S3, and S4. The second line
removes the box around the legend, positions the legend in the bottom left corner of the
graph window, and specifies that four columns should be used for the text strings of the leg-
end.

When a graph is created, EViews automatically determines a suitable number of columns for
the legend. A graph with four series, such as the one created above, would likely display two
columns of two labels each. The columns command above, with an argument of four, cre-
ates a long and slender legend, with each of the four series in its own column.

You may also use the legend command to change the font size or to disable the legend
completely:
graph07.legend font(10)
graph07.legend -display

Note that if the legend is hidden, any changes to the text or position of the legend remain,
and will reappear if the legend is displayed again.

Adding text to the graph

Text strings can be placed anywhere within the graph window. Using the Graph::addtext
command:
graph07.addtext(t) Fig 1: Monthly GDP

adds the text “Fig 1: Monthly GDP” to the top of the GRAPH07 window. You can also use
specific coordinates to specify the position of the upper left corner of the text. For example:
graph08.addtext(.2, .1, x) Figure 1

adds the text string “Figure 1” to GRAPH08. The text is placed 0.2 virtual inches in, and 0.1
virtual inches down from the top left corner of the graph frame. The “x” option instructs
EViews to place the text inside a box.

An existing text object can be edited interactively by double-clicking on the object to bring
up a text edit dialog. The object may be repositioned by specifying new coordinates in the
dialog, or by simply dragging the object to its desired location.
 Customizing a Graph—51

Adding lines and shading

You may wish to highlight or separate specific areas of your graph by adding a line or
shaded area to the interior of the graph using the Graph::draw command. Specify the type
of line or shade option (line or shade), which axis it should be attached to (left, right,
bottom, top) and its position. For example:
graph09.draw(line, left) 5.2

draws a horizontal line at the value 5.2 on the left axis. Alternately:
graph09.draw(shade, left) 4.8 5.6

draws a shaded horizontal area bounded by the values 4.8 and 5.6 on the left axis. You can
also specify color, line width, and line pattern:
graph09.draw(line, bottom, color(blue), width(2), pattern(3))
1985:1

draws a vertical blue dashed line of width two points at the date “1985:1” on the bottom
axis. Color may be specified using one or more of the following options: color(n1, n2, n3),
where the arguments correspond to RGB settings, or color(keyword), where keyword is
one of the predefined color keywords (“blue”, “red”, “ltred”, “green”, “black”, “white”,
“purple”, “orange”, “yellow”, “gray”, “ltgray”).

Using graphs as templates

After customizing a graph as described above, you may wish to use your custom settings in
another graph. Using a graph template allows you to copy the graph type, line and fill set-
tings, axis scaling, legend attributes, and frame settings of one graph into another. This
enables a graph to adopt all characteristics of another graph—everything but the data itself.
To copy custom line or fill settings from the global graph options, use the preset or
default keywords of the Graph::setelem command (as described in “Using preset lines
and fills” on page 42).

Modifying an existing graph

To modify a named graph object, use the template command:
graph10.template customgraph

This command copies all the appearance attributes of CUSTOMGRAPH into GRAPH10.

To copy text labels, lines and shading in the template graph in addition to all other option
settings, use the “t” option:
graph10.template(t) customgraph

This command copies any text or shading objects that were added to the template graph
using the Graph::addtext or Graph::draw commands or the equivalent steps using dia-
52—Chapter 2.Customizing a Graph

logs. Note that using the “t” option overwrites any existing text and shading objects in the
target graph.

Using a template during graph creation

All graph type commands also provide a template option for use when creating a new graph.
For instance:
graph mygraph.line(o = customgraph) ser1 ser2

creates the graph MYGRAPH of the series SER1 and SER2, using CUSTOMGRAPH as a tem-
plate. The “o” option instructs EViews to copy all but the text, lines, and shading of the tem-
plate graph. To include these elements in the copy, use the “t” option in place of the “o”
option.

When used as a graph procedure, this method is equivalent to the one described above for
an existing graph, so that:
graph10.template(t) customgraph
graph10.bar(t = customgraph)

produce the same results.

Arranging multiple graphs

When you create a multiple graph, EViews automatically arranges the graphs within the
graph window. (See “Creating a Graph” on page 33 for information on how to create a mul-
tiple graph.) You may use either the “m” option during graph creation or the merge com-
mand.

To change the placement of the graphs, use the Graph::align command. Specify the num-
ber of columns in which to place the graphs and the horizontal and vertical space between
graphs, measured in virtual inches. For example:
graph graph11.merge graph01 graph02 graph03
graph11.align(2, 1, 1.5)

creates a multiple graph GRAPH11 of the graphs GRAPH01, GRAPH02, and GRAPH03. By
default, the graphs are stacked in one column. The second command realigns the graphs in
two columns, with 1 virtual inch between the graphs horizontally and 1.5 virtual inches
between the graphs vertically.

Modifying Boxplots
The appearance of boxplots can be customized using many of the commands described
above. A few special cases and additional commands are described below.
 Customizing a Graph—53

Customizing lines and symbols

As with other graph types, the setelem command can be used with boxplots to modify line
and symbol attributes, assign the boxes to an axis, and use preset and default settings. To
use the Graph::setelem command with boxplots, use a box element keyword after the
command. For example:
boxgraph01.setelem(mean) symbol(circle)

changes the means in the boxplot BOXGRAPH01 to circles. Note that all boxes within a sin-
gle graph have the same attributes, and changes to appearance are applied to all boxes. For
instance:
boxgraph01.setelem(box) lcolor(orange) lpat(dash1) lwidth(2)

plots all boxes in BOXGRAPH01 with an orange dashed line of width 2 points. Also note that
when shaded confidence intervals are used, a lightened version of the box color will be used
for the shading. In this way, the above command also changes the confidence interval shad-
ing to a light orange.

Each element in a boxplot is represented by either a line or symbol. EViews will warn you if
you attempt to modify an inappropriate option (e.g., modifying the symbol of the box).

Assigning boxes to an axis

The setelem command may also be used to assign the boxes to another axis:
boxgraph01.setelem axis(right)

Note that since all boxes are assigned to the same axis, the index argument specifying a
graph element is not necessary.

Using preset line colors

During general graph creation, lines and fills take on the characteristics of the user-defined
presets. When a boxplot is created, the first user-defined line color is applied to the boxes,
whiskers, and staples. Similarly, when you use the preset or default keywords of the
setelem command with a boxplot, the line color of the preset is applied to the boxes, whis-
kers, and staples. (See “Using preset lines and fills” on page 42 for a description of presets.)

The preset and default methods work just as they do for other graph types, although
only the line color is applied to the graph. For example:
boxgraph01.setelem default(3)

applies the line color of the third user-defined line preset to the boxes, whiskers, and staples
of BOXGRAPH01. Note again that setelem does not require an argument specifying an
index, since the selected preset will apply to all boxes.
54—Chapter 2.Labeling Graphs

There are a number of setelem arguments that do not apply to boxplots. The fillcolor,
fillgray, and fillhatch option keywords are not available, as there are no custom areas
to be filled. The legend keyword is also not applicable, as boxplots use axis text labels in
place of a legend.

Hiding boxplot elements

In addition to the setelem command, boxplots provide a Graph::setbpelem command
for use in enabling or disabling specific box elements. Any element of the boxplot can be
hidden, except the box itself. Use the command with a list of box elements to show or hide.
For example:
boxgraph01.setbpelem -mean far

hides the means and confirms that the far outliers are shown in BOXGRAPH01.

Modifying box width and confidence intervals

The width of the individual boxes in a boxplot can be drawn in three ways: fixed width over
all boxes, proportional to the sample size, or proportional to the square root of the sample
size. To specify one of these methods, use the setbpelem command with the width key-
word, and one of the supported types (fixed, rootn, n). For example:
boxgraph01.setbpelem width(rootn)

draws the boxes in BOXGRAPH01 with widths proportional to the square root of their sam-
ple size.

There are three methods for displaying the confidence intervals in boxplots. They may be
notched, shaded, or not drawn at all, which you may specify using one of the supported
keywords (notch, shade, none). For example:
boxgraph01.setbpelem ci(notch)

draws the confidence intervals in BOXGRAPH01 as notches.

Labeling Graphs
As with all EViews objects, graphs have a label view to display and edit information such as
the graph name, last modified date, and remarks. To modify or view the label information,
use the Graph::label command:
graph12.label(r) Data from CPS 1988 March File

This command shows the label view, and the “r” option appends the text “Data from CPS
1988 March File” to the remarks field of GRAPH12.

To return to the graph view, use the graph keyword:

graph12.graph
 Exporting Graphs to Files—55

All changes made in label view will be saved when the graph is saved.

Printing Graphs
A graph may be printed using the print (p. 566) command. For example:
print graph11 graph12

prints GRAPH11 and GRAPH12 on a single page.

In addition, many graph commands and graph views of objects include a print option. For
example, you can create and simultaneously print a line graph GRA1 of SER1 using the “p”
option:
graph gra1.line(p) ser1

You should check the individual commands for availability of this option.

Exporting Graphs to Files

You may use the Graph::save proc of a graph object to save the graph as a Windows meta-
file (.wmf), Enhanced Windows metafile (.emf), PostScript file (.eps), bitmap (.bmp),
Graphics Interchange Format (.gif), Joint Photographics Exchange Group (.jpg), Portable
Network Graphics (.png), LaTeX (.tex), Markdown (.md), or Moving Picture Experts Group-
4 (.mp4) file.

You must specify a file name and file type, and may also provide the file height, width, units
of measurement, and color use. PostScript files also allow you to save the graph with or
without a bounding box and to specify portrait or landscape orientation. For instance:
graph11.save(t=postscript, u=cm, w=12, -box) MyGraph1

saves GRAPH11 in the default directory as a PostScript file “MyGraph1.EPS”, with a width of
12 cm and no bounding box. The height is determined by holding the aspect ratio of the
graph constant. Similarly:
graph11.save(t=emf, u=pts, w=300, h=300, -c) c:\data\MyGraph2

saves GRAPH11 as an Enhanced Windows metafile “Mygraph2.EMF”. The graph is saved in

black and white, and scaled to 300  300 points.
graph11.save(t=png, u=in, w=5, d=300) MyGraph3

saves GRAPH11 in the default directory as a PNG file “Mygra3.PNG”. The image will be 5
inches wide at 300 dpi.
graph11.save(t=gif, u=pixels, w=500) MyGraph4

saves GRAPH11 in a 500 pixel wide GIF file, “Mygraph4.GIF”.

56—Chapter 2.Graph Summary

Graph Summary
See “Graph” on page 368 of the Object Reference for a full listing of procs that may be used
to customize graph objects, and for a list of the graph type commands.

Graph commands are documented in “Graph Creation Command Summary” on page 1266
of the Object Reference.
Chapter 3. Working with Tables and Spreadsheets

There are three types of tables in EViews: tabular views, which are tables used in the display
of views of other objects, named table objects, and unnamed table objects. The main portion
of this discussion focuses on the use of commands to customize the appearance of named
table objects. The latter portion of the chapter describes the set of tools that may be used to
customize the display characteristics of spreadsheet views of objects (see “Customizing
Spreadsheet Views,” beginning on page 74).

You may use EViews commands to generate custom tables of formatted output from your
programs. A table object is an object made up of rows and columns of cells, each of which
can contain either a number or a string, as well as information used to control formatting for
display or printing.

Chapter 17. “Table and Text Objects,” on page 937 of the Object Reference describes various
interactive tools for customizing table views and objects.

Creating a Table
There are two basic ways to create a table object: by freezing an object view, or by issuing a
table declaration.

Creating Tables from an Object View

You may create a table object from another object, by combining an object view command
with the freeze (p. 457) command. Simply follow the freeze keyword with an optional
name for the table object, and the tabular view to be frozen. For example, since the com-
mand
grp6.stats

displays the statistics view of the group GRP6, the command

freeze(mytab) grp6.stats

creates and displays a table object MYTAB containing the contents of the previous view.

You should avoid creating unnamed tables when using commands in programs since you
will be unable to refer to, or work with the resulting object using commands. If the MYTAB
option were omitted in the previous example, EViews would create and display an untitled
table object. This table object may be customized interactively, but may not be referred to in
programs. You may, of course, assign a name to the table interactively.

Once you have created a named table object, you may use the various table object procs to
further customize the appearance of your table. See “Customizing Tables,” beginning on
page 60.
58—Chapter 3.Assigning Table Values

Declaring Tables
To declare a table, indicate the number of rows and columns and provide a valid name. For
example:
table(10,20) bestres

creates a table with 10 rows and 20 columns named BESTRES. You can change the size of a
table by declaring it again. Re-declaring the table to a larger size does not destroy the con-
tents of the table; any cells in the new table that existed in the original table will contain
their previous values.

Tables are automatically resized when you attempt to fill a table cell outside the table’s cur-
rent dimensions. This behavior is different from matrix objects which issue an error when
an out-of-range element is accessed.

Assigning Table Values

You may modify the contents of cells in a table using assignment statements. Each cell of the
table can be assigned either a string or a numeric value.

Assigning Strings
To place a string value into a table cell, follow the table name by a cell location (row and
column pair in parentheses), then an equal sign and a string expression.

For example:
table bestres
bestres(1,6) = "convergence criterion"
%strvar = "lm test"
bestres(2,6) = %strvar
bestres(2,6) = bestres(2,6) + " with 5 df"

creates the table BESTRES and places various string values into cells of the table.

Assigning Numbers
Numbers can be entered directly into cells, or they can be converted to strings before being
placed in the table.

Unless there is a good reason to do otherwise, we recommend that numbers be entered

directly into table cells. If entered directly, the number will be displayed according to the
numerical format set for that cell; if the format is changed, the number will be redisplayed
according to the new format. If the number is first converted to a string, the number will be
frozen in that form and cannot be reformatted to a different precision.

For example:
 Assigning Table Values—59

table tab1
tab1(3,4) = 15.345
tab1(4,2) = 1e-5
!ev = 10
tab1(5,1) = !ev
scalar f = 12345.67
tab1(6,2) = f

creates the table TAB1 and assigns numbers to various cells.

Assignment with Formatting

The setcell (p. 585) command is like direct cell assignment in that it allows you to set the
contents of a cell, but setcell also allows you to provide a set of simple formatting options
for the cell. If you desire even greater control over formatting, or if you wish to alter the for-
mat of a cell without altering its contents, you should use the tools outlined in “Customizing
Tables,” beginning on page 60.

The setcell command takes the following arguments:

• the name of the table
• the row and the column of the cell
• the number or string to be placed in the cell
• (optionally) a justification code or a numerical format code, or both

The justification codes are:

• “c” for centered (default)
• “r” for right-justified
• “l” for left-justified

The numerical format code determines the format with which a number in a cell is dis-
played; cells containing strings will be unaffected. The format code can either be a positive
integer, in which case it specifies the number of digits to be displayed after the decimal
point, or a negative integer, in which case it specifies the total number of characters to be
used to display the number. These two cases correspond to the fixed decimal and fixed
character fields in the number format dialog.

Note that when using a negative format code, one character is always reserved at the start of
a number to indicate its sign, and if the number contains a decimal point, that will also be
counted as a character. The remaining characters will be used to display digits. If the num-
ber is too large or too small to display in the available space, EViews will attempt to use sci-
60—Chapter 3.Customizing Tables

entific notation. If there is insufficient space for scientific notation (six characters or less),
the cell will contain asterisks to indicate an error.

Some examples of using setcell:

setcell(tabres,9,11,%label)

puts the contents of %LABEL into row 9, column 11 of the table TABRES.
setcell(big_tabl,1,1,%info,"c")

inserts the contents of %INFO in BIG_TAB1(1,1), and displays the cell with centered justifi-
cation.
setcell(tab1,5,5,!data)

puts the number !DATA into cell (5,5) of table TAB1, with default numerical formatting.
setcell(tab1,5,6,!data,4)

puts the number !DATA into TAB1, with 4 digits to the right of the decimal point.
setcell(tab1,3,11,!data,"r",3)

puts the number !DATA into TAB1, right-justified, with 3 digits to the right of the decimal
point.
setcell(tab1,4,2,!data,-7)

puts the number in !DATA into TAB1, with 7 characters used for display.

Customizing Tables
EViews provides considerable control over the appearance of table objects, providing a vari-
ety of table procedures allowing you specify row heights and column widths, content for-
matting, justification, font face, size, and color, cell background color and borders. Cell
merging and annotation are also supported.

Column Width and Row Height

We begin by noting that if the contents of a cell are wider or taller than the display width or
height of the cell, part of the cell contents may not be visible. You may use the
Table::setwidth and Table::setheight table procedures to change the dimensions of
a column or row of table cells.

To change the column widths for a set of columns in a table, use the setwidth keyword fol-
lowed by a column range specification in parentheses, and a desired width.

The column range should be either a single column number or letter (e.g., “5”, “E”), a colon
delimited range of columns (from low to high, e.g., “3:5”, “C:E”), or the keyword “@ALL”.
The width unit is computed from representative characters in the default font for the current
table (the EViews table default font at the time the table was created), and corresponds
 Customizing Tables—61

roughly to a single character. Width values may be non-integer values with resolution up to
1/10 of a unit. The default width value for columns in an unmodified table is 10.

For example, both commands

tab1.setwidth(2) 12
tab1.setwidth(B) 12

set the width of column 2 to 12 width units, while the command

tab1.setwidth(2:10) 20

sets the widths for columns 2 through 10 to 20 width units. To set all of the column widths,
use the “@ALL” keyword.
tab1.setwidth(@all) 20

Similarly, you may specify row heights using the setheight keyword, followed by a row
specification in parentheses, and a desired row height.

Rows are specified either as a single row number (e.g., “5”), as a colon delimited range of
rows (from low to high, e.g., “3:5”), or using the keyword “@ALL”. Row heights are given in
height unit values, where height units are in character heights. The character height is given
by the font-specific sum of the units above and below the baseline and the leading in the
default font for the current table. Height values may be non-integer values with resolution
up to 1/10 of a height unit. The default row height value is 1.

For example,
tab1.setheight(2) 1

sets the height of row 2 to match the table default font character height, while
tab1.setheight(2) 3.5

increases the row height to 3-1/2 character heights.

Similarly, the command:

tab1.setheight(2:7) 1.5

sets the heights for rows 2 through 7 to 1-1/2 character heights.

We may set the row height conditionally. The command

tab1.setheight(2:7 if [a2:a7]>0.5) 1.5

will set the heights of row 2 through 7 to 1-1/2 character heights if the additional condition
is true. In this case, if the value of cell A2 is greater than 0.5, the height of row will be set to
1.5 character. If the value of cell A3 is greater than 0.5, the height of row 3 will be set to 1.5
character and so forth through row 7. For more information on using table ranges and
expressions see “Conditional Table Cells” on page 68.
62—Chapter 3.Customizing Tables

Lastly the command,

tab1.setheight(@all) 2

sets all row heights to twice the default height.

Earlier versions of EViews supported the setting of column widths using the setcolwidth
command. This command, which is provided for backward compatibility, offers only a sub-
set of the capabilities of Table::setwidth.

Cell Formatting
A host of cell characteristics may be set using table procedures. Each procedure is designed
to work on individual cells, ranges of cells, or the entire table.

Content Formatting
Cell content formatting allows you to alter the appearance of the data in a table cell without
changing the contents of the cell. Using the table proc Table::setformat, you may, for
example, instruct EViews to change the format of a number to scientific or fixed decimal, or
to display a date number in a different date format. These changes in display format do not
alter the cell values.

To format the contents of table cells, simply follow the table name with a period and the
setformat proc keyword, followed by a cell range specification in parentheses, and then a
valid numeric or date format string. The cell range may be specified in a number of ways,
including individual cells, cell rectangles, row or column ranges or the entire table. See
Table::setformat for a description of cell range specification and numeric and date for-
mat string syntax.

For example, to set the format for the fifth column of a matrix to fixed 5-digit precision, you
may provide the format specification:
tab1.setformat(e) f.5

To set a format for the cell in the third row of the fifth column to scientific notation with 5
digits of precision, specify the individual cell, as in:
tab1.setformat(3,e) e.5
tab1.setformat(e3) e.5

To specify the format for a rectangle of cells, specify the upper left and lower right cells in
the rectangle. The following commands set cells in the same region to show 3-significant
digits, with negative numbers in parentheses:
tab1.setformat(2,B,10,D) g(.3)
tab1.setformat(r2c2:r10c4) g(.3)
tab1.setformat(b2:d10) g(.3)

The rectangle of cells is delimited by row 2, column 2, and row 10, column 4.
 Customizing Tables—63

To conditionally set the format of cells, you can provide a conditional cell range argument.
For example, using the following 2 commands in sequence
tab1.setformat(r2c2:r10c4 if [r2c2:r10c4]<10000) g(.2)
tab1.setformat(r2c2:r10c4 if [r2c2:r10c4]<1000) g(.3)

will set the format of cells row 2, column 2, to row 10, column 4 based on their cell values.
If the cell values are less than 10000 only 2 significant digits will be displayed but if the cell
values are less than 1000, 3 significant digits will be displayed. For more information on
using table ranges and expressions see “Conditional Table Cells” on page 68.

Alternately you may provide a date format for the table cells. The command:
tab1.setformat(@all) "dd/MM/YY HH:MI:SS.SSS"

will display numeric values in the entire table using formatted date strings containing days
followed by months, years, hours, minutes and seconds, to a resolution of thousandths of a
second.

Note that changing the display format of a cell that contains a string will have no effect
unless the cell is later changed to contain a numerical value.

Justification and Indentation

The cell justification and indentation control the position of the table cell contents within
the table cell itself.

You may use the Table::setjust proc to position the cell contents in the cell. Simply use
the setjust keyword, followed by a cell range specification in parentheses, and one or
more keywords describing a vertical or horizontal position for the cell contents. You may use
the keywords auto, left, right, and center to control horizontal positioning, and top,
middle, and bottom to control vertical positioning. You may use the auto keyword to spec-
ify left justification for string cells and right justification for numeric cells.

For example,
tab1.setjust(@all) top left

sets the justification for all cells in the table to top left, while
tab1.setjust(2,B,10,D) center

horizontally centers the cell contents in the rectangle from B2 to D10, while leaving the ver-
tical justification unchanged.

In addition, you may use Table::setindent to specify a left or right indentation from the
edge of the cell for cells that are left or right justified, respectively. You should use the
setindent keyword followed by a cell range in parentheses, and an indentation unit, spec-
ified in 1/5 of a width unit. Indentation is only relevant for non-center justified cells.
64—Chapter 3.Customizing Tables

For example:
tab1.setjust(2,B,10,D) left
tab1.indent(2,B,10,D) 2

left-justifies, then indents the specified cells by 2/5 of a width unit from the left-hand side of
the cell.

It may be useful to adjust the justification based on the contents of the cell. To change verti-
cal justification based on the length of the string cell in the cell you could use a conditional
range. For example,
tab1.setjust(b2:d10 if @length([b2:d10])>15) top

will individually set the vertical justification to be top justified for cells b2 through d10 if the
cells contain a string longer than 15. For more information on using table ranges and expres-
sions see “Conditional Table Cells” on page 68.

Alternatively,
tab2.setjust(@all) center
tab2.indent(@all) 3

will set the indentation for all cells in the table to 3/5 of a width unit, but this will have no
effect on the center justified cells. If the cells are later modified to be left or right justified,
the indentation will be used. If you subsequently issue the command
tab2.indent(@all) right

the cells will be indented 3/5 of a width unit from the right-hand edges.

Fonts
You may specify font face and characteristics, and the font color for table cells using the
Table::setfont and Table::settextcolor table procs.

The setfont proc should be used to set the font face, size, boldface, italic, strikethrough
and underline characteristics for table cells. You should provide a cell range specification,
and one or more font arguments corresponding to font characteristics that you wish to mod-
ify. For example:
tab1.setfont(3,B,10,D) "Times New Roman" +u 8pt

changes the text in the specified cells to Times New Roman, 8 point, underline. Similarly,
tab1.setfont(4,B) -b +i -s

adds the italic to and removes boldface and strikethrough from the B4 cell.

To set the color of your text, use settextcolor with a cell range specification and a color
specification. Color specifications may be provided using the @RGB or @HEX settings, or
using one of the EViews predefined colors keywords:
 Customizing Tables—65

tab1.settextcolor(f2:g10) @rgb(255, 128, 0)

tab1.settextcolor(f2:g10) orange

sets the text color for the specified cells to orange.

See Table::setfillcolor for a complete description of color specifications.

One practical text coloring application is to highlight negative cell values in a table by
changing the text color. Using settextcolor, you may use a colormap (see “Value-Based
Text and Fill Coloring” on page 186 in User’s Guide I) or you can manually set the text color
with a Boolean expression.

To set the text color of negative values in your table for the cell range A1:G10, you can either
use a positive-negative colormap,
tab1.settextcolor(t=posneg, A1:G10) posclr(@RGB(0,0,0))
negclr(@RGB(255,0,0))naclr(@RGB(0,0,0))

or manually set the text color via

tab1.settextcolor(A1:G10 if [A1:G10]<0) red

For more information on using table ranges and expressions see“Conditional Table Cells” on
page 68.

(Note that both commands set negative values to red. The difference between the two meth-
ods is colormaps dynamically determines the text color during rendering. Therefore, if the
cell value is changed so will the color. Whereas when manually setting the text color, the
color becomes fixed and will not change regardless of the cell value. While the use of color-
maps is more flexible and dynamic, defining a colormap is more difficult. Manually setting
the color is easier and faster and recommended when the cell values in the table are not
expected to change.)

Background and Borders

You may set the background color for cells using the Table::setfillcolor table proce-
dure. Specify the cell range and provide a color specification using @RGB or @HEX settings
or one of the predefined color keywords. The commands:
tab1.setfillcolor(R2C3:R3C6) ltgray
tab1.setfillcolor(2,C,3,F) @rgb(192, 192, 192)

both set the background color of the specified cells to light gray.

The Table::setlines table proc may be used to draw borders or lines around specified
table cells. If a single cell is specified, you may draw borders around the cell or a double line
through the center of the cell. If multiple columns or rows is selected, you may, in addition,
add borders between cells.
66—Chapter 3.Customizing Tables

Follow the name of the table object with a period, the setlines keyword, a cell range spec-
ification, and one or more line arguments describing the lines and borders you wish to draw.
For example:
tab1.setlines(b2:d6) +a -h -v

first adds all borders (“a”) to the cells in the rectangle defined by B2 and D6, then removes
the inner horizontal (“h”), and inner vertical (“v”) borders. The command
tab1.setlines(2,b) +o

adds borders to the outside (“o”), all four borders, of the B2 cell.

You may also use the setlines command to place double horizontal separator lines in the
table. Enter the setlines keyword, followed by the name of the table, and a row number,
both in parentheses. For example,
bestres.setlines(8) +d

places a separator line in the eighth row of the table BESTRES. The command:
bestres.setlines(8) -d

removes the double separator lines from all of the cells in the eighth row of the table.

You may also apply a conditional expression when activating borders. Let’s assume we have
a table that contains quarterly data by row, whereby the first column has the date (similar to
a series spreadsheet) and we would like to visually indicate the starts and ends of years. We
will accomplish this effect by applying a conditional expression to add a bottom border to
the rows which contain the fourth quarter.

By default, quarterly workfile dates in EViews are denoted by year followed by quarter. The
fourth quarter of the 2020 would appear as ‘2020Q4’. With this information, we can use the
command:
tab1.setlines(a1:d50 if @right([a1:a50], 2)=="Q4")

This command will add, for each row from 1 to 50, a bottom border from column A to D if
the first cell in their respective row ends in “Q4”. For more information on using table ranges
and expressions see “Conditional Table Cells” on page 68.

Cell Annotation and Merging

Each cell in a table object is capable of containing a comment. Cell comments contain text
that is hidden until the mouse cursor is placed over the cell containing the comment. Com-
ments are useful for adding notes to a table without changing the appearance of the table.

To add a comment with the Table::comment table proc, follow the name of the table
object with a period, a single cell identifier (in parentheses), and the comment text enclosed
 Customizing Tables—67

in double quotes. If no comment text is provided, a previously defined comment will be

removed.

To add a comment “hello world” to the cell in the second row, fourth column, you may use
the command:
tab1.comment(d2) "hello world"

To remove the comment simply repeat the command, omitting the text:
tab1.comment(d2)

In addition, EViews permits you to merge cells horizontally in a table object. To merge mul-
tiple cells in a row or to un-merge previously merged cells, you should use the
Table::setmerge table proc. Enter the name of the table object, a period, followed by a
cell range describing the cells in a single row that are to be merged.

If the first specified column is less than the last specified column (left specified before right),
the cells in the row will be merged left to right, otherwise, the cells will be merged from
right to left. The contents of the merged cell will be taken from the first cell in the merged
region. If merging from left to right, the leftmost cell contents will be used; if merging from
right to left, the rightmost cell contents will be displayed.

For example,
tab1.setmerge(a2:d2)

merges the cells in row 2, columns 1 to 4, from left to right, while

tab2.setmerge(d2:a2)

merges the cells in row 2, columns 2 to 5, from right to left. The cell display will use the left-
most cell in the first example, and the rightmost in the second.

If you specify a merge involving previously merged cells, EViews will unmerge all cells
within the specified range. We may then unmerge cells by issuing the Table::setmerge
command using any of the previously merged cells. The command:
tab2.setmerge(r2c4)

unmerges the previously merged cells.

When modifying a characteristic of a table via command, the section of the table to be mod-
ified must be specified. This section or range can be a set of cells, rows, or columns. You
could for example the set fill color of row or column or rectangular area within the table. It
may also be desirable to set remove a row or delete a column. EViews has numerous com-
mands for customizing a table.
68—Chapter 3.Customizing Tables

Conditional Table Cells

Many EViews table customization procedures allow you to specify ranges of cells. For exam-
ple, Table::setfillcolor allows you to specify the background color for the specified
cells, while Table::setformat allows you to apply custom formatting to the contents of
the specified cells.

There are cases when you may wish to perform operations on cells in a table, but only under
certain conditions. Suppose, for example, that you have a table with annual data on each
row and you want to identify each row where there is a decrease in value in column 3 when
compared to the value for the previous row (year). The goal is to apply custom text or cell
formatting to these rows.

Fortunately, EViews allows you to identify the desired cells using a conditional target range
specification comprised of a target_range and a boolean_expression. You may specify the con-
ditional target cells using the syntax:
target_range if boolean_expression

where target_range gives the range of potential cells of interest, “if” is a keyword, and bool-
ean_expression provides indicators for which of the target_range cells to use.

Similarly, the table @find data member (“Table Data Members” on page 1073 of Object Ref-
erence) allows you to obtain a string list containing the cells in a table range that satisfy a
condition.

The syntax for @find requires a find_expression:

table_name.@find(find_expression)
where find_expression simultaneously specifies the range of cells to consider and the boolean
expression for whether each cell should be used.

Note that in contrast to the conditional target syntax above, @find does not require an
explicit target_specification since the find_expression implicitly defines the range of cells to
consider.

Target Range Specification

The target_range of potential cells to consider consists of the rectangle of cells defined by
first_cell and last_cell:
first_cell:last_cell
where first_cell and last_cell are cell identifiers (separated by “:”) specified using either a col-
umn letter and row number (e.g., “A2”), or using “R” (for row) followed by the row number fol-
lowed by “C” (for column) and the column number (e.g., “R1C2”).

You may also use the special keyword “@all” to refer to every cell in the table.
 Customizing Tables—69

It is useful to consider simple examples of an unconditional target_range in action. Suppose

that we wish to set the fill color for a collection of cells. The command
tab1.setfillcolor(A2:A7) red

will set the fill color of all the cells in the target region from A2 (top left cell) to A7 (bottom
right cell) in table TAB1 to red. In this case, the target cell range is “A2:A7” and EViews will
set the fill color for every cell from A2 to A7 to red.

Similarly,
tab1.setfillcolor(@all) red

sets the background color in all of cells of the table to red.

Boolean Expression
The boolean_expression defines a comparison producing indicators corresponding to the ele-
ments of the target_range.

Basic Comparisons
The boolean_expression syntax consists of
left_spec “operator” right_spec
where “operator” is a standard EViews comparison operator such as “>”, “<>” “<=”,
“=”, etc., and where the left_spec and right_spec consist of one of:
• a literal value, e.g., the number 37, or the string “Kansas” or “New Mexico”.
• a cell range, enclosed in “[]”, e.g. “[A1:C9]”, “[R1C1:R10C30]”.

where for purposes of the boolean comparison, the cell range is refers to the contents of the
corresponding cells in the table.

For example, for a target_range of size 5  3 we may specify the boolean_expressions:

[A1:C5] < 3
[A1:C5] = [B1:B5]
[C2] > [A1:C1]
[E1:E5] <> "Out of Stock"

where we see that the specs can be rectangles, columns, and rows of cells, literal numbers,
and literal strings.

Conceptually, EViews takes the left_spec and creates an implicit table of values that is the
same size as target_range, then compares it to a similarly constructed table of right_spec val-
ues. The pairwise comparison of the cells of the two implicit tables produces the boolean
indicators for the conditional target range.

The rules for forming the implicit tables are straightforward:

70—Chapter 3.Customizing Tables

• if the spec is a numeric or string literal, or a single cell, the value will be repeated for
each element of the implicit table
• if spec is a row of cells, it must have the same number of columns as target_range; the
values in spec will be repeated for each row of the implicit table
• if the spec is a column of cells, it must have the same number of rows as target_range;
the values in spec will be repeated for each column of the implicit table
• if the spec is a rectangle of cells, it must be of the same dimension as target_range; the
implicit table uses the values in spec

These concepts are most easily illustrated via examples, in which we assume a 5  3
target_range.

The boolean comparison,

[A1:C5] < 3

compares every element of

• the 5  3 rectangle of the values in the table cells from A1 to C5
• (an implicit 5  3 table of) the number 3

producing a TRUE if an element of the former is less than the latter, and a FALSE otherwise.
[A1:C5] = [B1:B5]

compares every element of

• the 5  3 rectangle of the values in the table cells from A1 to C5
• an implicit 5  3 table constructed by repeating horizontally the column of values in
B1 to B5

producing a TRUE if an element of the former is equal to the latter, and a FALSE otherwise.
[C2] > [A1:C1]

compares every element of

• (a 5  3 implicit table filled with the value in C2
• an implicit 5  3 table constructed by repeating vertically the row of values in A1 to
C1

producing a TRUE if an element of the former is greater than the latter, and a FALSE other-
wise.
[E1:E5] <> "Out of Stock"

compares every element of

 Customizing Tables—71

• the 5  3 implicit table filled with the column of valuesin E1 to E5 repeated horizon-
tally
• (an implicit 5  3 table of) the string value “Out of Stock”

producing a TRUE if the element of the former is not equal to the latter, and a FALSE other-
wise.

We can illustrate the use boolean expressions by modifying our earlier command that
setfillcolor using an unconditional target_range. Suppose that we add an “if” condition,
for whether the cells are decreasing in value, to the earlier command. The command
tab1.setfillcolor(A2:A7 if [A2:A7]<[A1:A6]) red

will only set the fill color to red for the target cell range, if the decreasing value condition
holds.

Comparisons using Expressions

Earlier, we saw how to use the boolean_expression to define simple comparisons of cell val-
ues and literals (“Basic Comparisons” on page 69).

EViews expression and function language can be used with the numeric and string literals in
and cell expressions in left_spec and right_spec. We may have quite complicated boolean
expressions as in:
[A1:C5]^2+log(@pi*[A1:C5]) < 3
[A1:C5]/3 = [B1:B5]
@tdist([C2], [C4]) > [A1:C1]/100
@length([E1:E5]) <> "Out of Stock"

where a function or expression involving a cell range is interpreted as applying the function
or expression to each element of the range after expansion into implicit tables.

For the most part, interpreting the expressions is straightforward, as we can simply evaluate
the expressions for each element of the implicit tables. The power of this type of evaluation
can, however, lead to potentially useful but at first glance odd specifications, as in
tab1.setfillcolor(A1:B2 if @log([A1:A2]^2+[A1:B1])/10 <
@floor(3+[C1:D2])) red

While interpreting this expression without invoking the concept of implicit tables is quite
difficult, in practice, evaluation is reasonably straightforward:
1. the target_range is “A1:B2” which defines a 2  2 target and size for the implicit
tables
2. “[A1:A2]” is a 1  2 row range which is repeated vertically to yield a 2  2 implicit
table; each element of the table is squared
72—Chapter 3.Customizing Tables

3. “[A1:B1]” is a 2  1 column range which is repeated horizontally to yield a 2  2

implicit table; each element is divided by 10
4. the results in the previous two steps are added together cell-by-cell to yield a 2  2
implicit table; the natural logarithm is taken of each cell
5. “[C1:D2] is a 2  2 range; the number 3 is added to the values in the table for this
range, forming a 2  2 implicit table; the floor function is used to find the nearest
integer less than, for each cell.
6. the elements of the two implicit tables are compared element-by-element, with TRUE
given if the element of the first is strictly less than than the element of the second.

Find Expression
The find_expression is a conditional table cell specification in which the set of cells to con-
sider is part of the boolean expression. The syntax for this expression is:
left_spec “operator” right_spec
where “operator” is a standard EViews comparison operator such as “>”, “<>” “<=”,
“=”, etc., and where the left_spec and right_spec consist of one of:
• a literal value, e.g., the number 37, or the string “Kansas” or “New Mexico”.
• a cell range, enclosed in “[]”, e.g. “[A1:C9]”, “[R1C1:R10C30]”.

Most of the discussion in “Boolean Expression” on page 69 applies here, with the only dif-
ference being that the target range will be the larger of the left_spec and right_spec ranges.

For example,
string s = tab1.@find("[b1:c15]>0.3")

returns a list of cells between B1 and C15 greater than 0.3,

string s = tab1.@find("[@all]=0.5")

returns a list of cells in the table equal to 0.5,

string s = t.@find("[b3:c5]<[d5]")

returns a list of cells between B3 and C5 less than cell D5.

Note that since the find_expression must be enclosed in double-quotes inside the @find
function, the use of string literals will require “""” escape sequences to include the actual
quotes in the comparison.
string s = tabl1.@find("[a1:e67]= ""1949q4""")

returns a list of cells between A1 and E67 matching the string “1949q4” (string comparisons
in find ignore case);
string s = t.@find("@instr([@all],""in"")")
 Exporting Tables to Files—73

returns a list of cells in the table containing the substring “in”;

Labeling Tables
Tables have a label view to display and edit information such as the graph name, last modi-
fied date, and remarks. To modify or view the label information, use the Table::label
command:
table11.label(r) Results from GMM estimation

This command shows the label view, and the “r” option appends the text “Results from
GMM estimation” to the remarks field of TABLE11.

To return to the basic table view, use the table keyword:

table11.table

All changes made in label view will be saved with the table.

Printing Tables
To print a table, use the print (p. 566) command, followed by the table object name. For
example:
print table11

The print destination is taken from the EViews global print settings.

Exporting Tables to Files

You may use the table Table::save procedure to save the table to disk as an Excel 2007
XLSX, CSV, tab-delimited ASCII text, RTF, HTML, Enhanced Metafile, LaTeX, PDF, or Mark-
down file.

You must specify a file name and an optional file type, and may also provide options to spec-
ify the cells to be saved, text to be written for NA values, and precision with which numbers
should be written. RTF and HTML files also allow you to save the table in a different size
than the current display. If a file type is not provided, EViews will write a CSV file.

For example:
tab1.save(t=csv, n="NAN") mytable

saves TAB1 in the default directory as a CSV file “Mytable.CSV”, with NA values translated
to the text “NAN”.

Alternately, the command:

tab1.save(r=B2:C10, t=html, s=.5) c:\data\MyTab2
74—Chapter 3.Customizing Spreadsheet Views

saves the specified cells in TAB1 as an HTML file to “Mytab2.HTM” in the directory
“c:\data”. The table is saved at half of the display size.

Customizing Spreadsheet Views

Several of the table procs for customizing table display may also be used for customizing
spreadsheet views of objects. You may use Series::setformat, Series::setindent,
Series::setjust, and Series::setwidth to modify the spreadsheet view of a series.
Similar procs are available for other objects with table views (e.g., alpha, group, and matrix
objects).

Suppose, for example, that you wish to set the format of the spreadsheet view for series
SER1. Then the commands:
ser1.setformat f.5
ser1.setjust right center
ser1.setindent 3
ser1.setwidth 10
ser1.sheet

sets the spreadsheet display format for SER1 and then displays the view.

Similarly, you may set the characteristics for a matrix object using the commands:
mat1.setformat f.6
mat1.setwidth 8
mat1.sheet

For group spreadsheet formatting, you must specify a column range specification. For exam-
ple:
group1.setformat(2) (f.7)
group1.setwidth(2) 10
group1.setindent(b) 6
group1.sheet

set the formats for the second series in the group, then displays the spreadsheet view.
group1.setwidth(@all) 10

sets the width for all columns in the group spreadsheet to 10.

Note that the group specified formats are used only to display series in the group and are not
exported to the underlying series. Thus, if MYSER is the second series in GROUP1, the
spreadsheet view of MYSER will use the original series settings, not those specified using the
group procs.
 Table Summary—75

Table Summary
See “Table,” on page 1072 of the Object Reference for a full listing of formatting procs that
may be used with table objects.
76—Chapter 3.Table Summary
Chapter 4. Working with Spools

The EViews spool object allows you to create sets of output comprised of tables, graphs,
text, and other spool objects. Spools allow you to organize EViews results, allowing you to
generate a log of output for a project, or perhaps to collect output for a presentation.

The following discussion focuses on command methods for working with a spool object. A
general description of the spool object, featuring a discussion of interactive approaches to
working with your spool, may be found in Chapter 18. “Spool Objects,” on page 953 of
User’s Guide I.

Creating a Spool
There are two methods you may use to create a spool. You may declare a spool using the
spool command, or you may print an object to a new spool.

To declare an empty spool, use the keyword spool followed by a name for the new spool:
spool myNewSpool

creates a new, empty spool object MYNEWSPOOL.

A new spool may also be created by printing from an object to a non-existent spool. To print
to a spool you must redirect the output of print jobs to the spool using the output com-
mand. For example, the command:
output(s) myNewSpool

instructs EViews to send all subsequent print jobs to the MYNEWSPOOL spool (see output
(p. 533)).

Once you redirect your output, you may create a spool using the print command or the “p”
option of an object view or procedure.
tab1.print

creates the spool object MYNEWSPOOL and appends a copy of TAB1. Alternately,
eq1.output(p)

appends the EQ1 equation output to the newly created spool object.

To turn off redirection, simply issue the command

output off
78—Chapter 4.Working with a Spool

Working with a Spool

Spool objects provide easy-to-use tools for working with the objects in the spool. Among
other things, you may manage (add, delete, extract, rearrange, hide) or customize (resize,
space and indent, title and comment, and edit) the spool and the individual objects in a
spool.

Adding Objects
You may add objects to a spool by printing to the spool, or by using the Spool::append
and Spool::insert procs.

Printing to a Spool
Earlier, we saw how one may redirect subsequent print jobs to the spool object using the
output (p. 533) command to change the default print destination. Once redirection is in
place, simply use the print command or the “p” option to send view or procedure output
to the spool. The following command lines:
output(s) myOldSpool
ser01.line(p)
grp01.scat(p)
eq1.wald(p) c(1)=c(2)

redirect output to the existing spool object MYOLDSPOOL, then adds a line graph of SER01,
a scatterplot of the series in GRP01, and the table output of a Wald test for equation EQ1 to
the spool, in that order.

Note that the three output objects in the spool will be named UNTITLED01, UNTITLED02,
and UNTITLD03.

To turn off redirection, simply issue the command:

output off

Appending and Inserting

You may use the Spool::append procedure to add output objects to the end of an existing
spool object. You may insert any valid EViews object view into a spool. For example,
spool01.append ser01.line

appends a line graph of SER01 to the end of SPOOL01.

The name of the object in the spool will be the next available name beginning with “UNTI-
TLED”. For example, if two objects have already been appended to SPOOL01, named UNTI-
TLED01 and UNTITLED02, then the line graph of SER01 will be named UNTITLED03.

You may append multiple EViews objects using a single append command:
 Working with a Spool—79

spool03.append ser02.line ser03

appends a line graph of SER02 and the default spreadsheet view of SER03 to the end of
SPOOL03.

The Spool::insert proc offers additional control over the location of the added object by
allowing you to specifying an integer position for the inserted object. If a position is not
specified or the specified position is greater than the number of objects already in the spool,
the object will be appended to the end. The command:
spool01.insert(loc=3) series01

inserts the default spreadsheet view of SERIES01 into SPOOL01 at position three. All existing
objects in the spool from position three and higher are pushed down in the list to accommo-
date the new object.

You may include more than one object view using a single insert command:
spool01.insert(loc=5) "eq1.wald c(1)=c(2)" series01.uroot

inserts both the results for a Wald test on EQ1, and the results for a unit root test for
SERIES01 into the spool in the fifth and sixth positions. Existing objects from the fifth posi-
tion onward will be moved down to the seventh position so that they follow the unit root
table. Note that since the Wald test command contains spaces, we require the use of double
quotes to delimit the expression.

Alternately, insert accepts an object name for the location and an optional offset keyword.
The command:
spool01.insert(loc=obj3) mycity.line

adds the line graph view of MYCITY to SPOOL01, placing it before OBJ3. You may modify
the default positioning by adding the “offset=after” option,
spool01.insert(loc=obj3, offset=after) mycity.line

so that the line graph is inserted after OBJ3.

You may use insert or append to add spool objects to a spool. Suppose that we have the
spool objects SPOOL01 and STATESPOOL. Then
spool01.insert statespool

adds STATESPOOL to the end of SPOOL01.

Subsequent insert commands may be used to place objects before, after, or inside of the
spool object. The commands
spool01.insert(loc=state) mycity.line
spool01.insert(loc=state, offset=after) mytown.hist
80—Chapter 4.Working with a Spool

inserts a line graph view of MYCITY before, and the histogram view of MYTOWN after the
STATE spool. You may also use the “offset=” option to instruct EViews to place the new
output object inside of an embedded spool:
spool01.insert(loc=state, offset=first) mycity.boxplot
spool01.insert(loc=state, offset=last) mystate.stats

places a boxplot view of MYCITY and a descriptive statistics view of MYSTATE inside of the
STATE spool object. The boxplot view is inserted at the beginning of STATE, while the
descriptive statistics view is appended to the end of STATE.

Objects within a embedded spool should be referred to using the full path description. For
example, suppose we have a spool object COUNTY which we wish to add to the end of the
previously embedded spool STATE. Then,
spool01.insert(loc=state, offset=last) county

inserts COUNTY as the last member of the spool STATE, and:

spool01.insert(loc=state/county, offset=first) mycity.bar

inserts a bar graph of MYCITY into the first position of the COUNTY spool.

Naming Objects
The default name of an object when it is inserted into a spool is UNTITLED followed by the
next available number (e.g. UNTITLED03). When using the Spool::append or the
Spool::insert procs may use the “name=” option to specify a name.

Alternately, you may use the Spool::name command to change the name of an object in
the spool. For example,
spool01.name untitled03 losangeles

renames the UNTITLED03 object to LOSANGELES. Note that names are not case-sensitive,
and that they must follow EViews’ standard naming conventions for objects. Names must
also uniquely identify objects in the spool.

To rename an object contained in an embedded spool, you should provide the full path
description of the object. For example, the command:
spool01.name untitled01/untitled02 newyork

renames the object UNTITLED02 which is contained in the spool UNITITLED01 to

NEWYORK.

Object Displaynames
The Spool::displayname proc may also be used to alter the display name of an object.
The default display name of an object is simply the uppercase version of the object name.
Display names, which are case-sensitive, not restricted to be valid object names, and need
 Working with a Spool—81

not be unique, allow you to provide a more descriptive label in the tree pane view when dis-
playing object names.

For example,
spool01.displayname untitled03 "Los Angeles"

sets the display name for UNTITLED03 object to the text “Los Angeles”. Note that since the
desired display name has spaces, we have enclosed the text in double-quotes.

Similarly,
spool01.displayname untitled01/untitled02 "New York"

sets the display name for UNTITLED02 in the spool UNITITLED01 to “New York”.

Object Comments
The Spool::displayname may be used to assign a comment to an object in the spool. Set-
ting a comment for an object is similar to setting the display name. Comments can be multi-
line; you may use “\n” to indicate the start of a new line in a comment.
Spool01.comment untitled01 "The state population of Alabama as
found\nfrom http://www.census.gov/popest/states/NST-ann-
est.html."

assigns the following comment to object UNTITLED01:

“The state population of Alabama as found
from http://www.census.gov/popest/states/NST-ann-est.html.”

Removing Objects
Use the Spool::remove proc to delete objects from a spool. Follow the remove keyword
with names of the objects to be deleted. The unique object name should be used; the display
name cannot be used as a valid argument for the remove command.
spool01.remove untitled02 untitled01 untitled03

removes the three objects UNTITLED01, UNTITLED02, UNTITLED03 from SPOOL01. Note
that the order at which objects are specified is unimportant.

Extracting Objects
Objects within a spool are not confined to spools forever; they may be extracted to other
spools using Spool::extract. An independent copy of the specified object will be made.
Note that only one object may be extracted at a time. For instance, referring to our example
above, where we have a STATE spool containing a COUNTY spool,
spool01.extract state/county

creates an untitled spool containing the objects in the COUNTY spool.

82—Chapter 4.Printing the Spool

Similarly:
spool01.extract(mycounty) state/county

Customizing the Spool

Titles and Comments
Each object in a spool has both an object name and a display name. By default, the object
name is shown. The object name is not case sensitive, while the display name can be multi-
ple words and is case sensitive.

Setting a comment for an object is similar to setting the display name. Comments can be
multiline; you may use “\n” to indicate the start of a new line in a comment.
Spool01.comment untitled01 "The state population of Alabama as
found\nfrom http://www.census.gov/popest/states/NST-ann-
est.html."

assigns the following comment to object UNTITLED01:

“The state population of Alabama as found
from http://www.census.gov/popest/states/NST-ann-est.html.”

Customizing the Appearance

General properties of a spool may be modified using the Spool::options proc. These
properties include the display of the object tree, borders, titles, comments, and the use of the
object name or display name. To change these settings, use the options keyword followed
by the characteristic you wish to change.

To turn off the tree and display titles, displaynames and comments for SPOOL01:
spool01.options -tree titles displaynames comments

creates a spool with the same objects and names it MYCOUNTY.

Printing the Spool

Printing a entire spool object is the same as printing any other object in EViews, simply use
the print (p. 566) command followed by the name of the spool:
print spool01

prints all of SPOOL01.

To print an object stored in SPOOL01, us the Spool::print proc and specify the name of
the object within the spool that you wish to print. For example,
spool01.print state/county
 Spool Summary—83

prints the COUNTY object, which is located in the STATE spool in SPOOL01. The
Spool::print proc also allows you to print multiple objects in the spool.
spool01.print state county

prints both the STATE and COUNTY objects individually.

When printing from the command window, the Print Options dialog will be displayed for
each object specified, allowing you to modify printer settings. When printing from a pro-
gram, the current printer settings will be used. To modify the current printer settings, you
may use File/Print Setup to set the global print defaults (“Print Setup,” on page 2562 of
User’s Guide I).

Spool Summary
See “Spool,” on page 904 of the Object Reference for a full listing of procedures that may be
used with spool objects.
84—Chapter 4.Spool Summary
Chapter 5. Strings and Dates

Strings
An alphanumeric string is a set of characters containing alphabetic (“alpha”) and
numeric characters, and in some cases symbols, found on a standard keyboard. Strings
in EViews may include spaces and dashes, as well as single or double quote characters.
Note also that EViews does not support unicode characters.

Strings are used in EViews in a variety of places. “Using Strings in EViews” on

page 101 offers a brief overview.

When entering alphanumeric values into EViews, you generally should enclose your
characters in double quotes. The following are all examples of valid string input:
"John Q. Public"
"Ax$23!*jFg5"
"000-00-0000"
"(949)555-5555"
"11/27/2002"
"3.14159"

You should use the double quote character as an escape character for double quotes in
a string. Simply enter two double quote characters to include the single double quote
in the string:
"A double quote is given by entering two "" characters."

Bear in mind that strings are simply sequences of characters with no special interpreta-
tion. The string values “3.14159” and “11/27/2002” might, for example, be used to rep-
resent a number and a date, but as strings they have no such intrinsic interpretation.
To provide such an interpretation, you must use the EViews tools for translating string
values into numeric or date values (see “String Information Functions” on page 90 and
“Translating between Date Strings and Date Numbers” on page 110).

Lastly, we note that the empty, or null, string (“”) has multiple interpretations in
EViews. In settings where we employ strings as a building block for other strings, the
null string is interpreted as a blank string with no additional meaning. If, for example,
we concatenate two strings, one of which is empty, the resulting string will simply be
the non-empty string.

In other settings, the null string is interpreted as a missing value. In settings where we
use string values as a category, for example when performing categorizations, the null
string is interpreted as both a blank string and a missing value. You may then choose
86—Chapter 5.Strings

to exclude or not exclude the missing value as a category when computing a tabulation
using the string values. This designation of the null string as a missing value is recognized
by a variety of views and procedures in EViews and may prove useful.

Likewise, when performing string comparisons using blank strings, EViews generally treats
the blank string as a missing value. As with numeric comparisons involving missing values,
comparisons involving missing values will often generate a missing value. We discuss this
behavior in greater detail in our discussion of “String Comparison (with empty strings)” on
page 88.

String Operators
The following operators are supported for strings: (1) concatenation—plus (“+”), and (2)
relational—equal to (“=”), not equal to (“<>”), greater than (“>”), greater than or equal
to (“>=”), less than (“<“), less than or equal to (“<=”).

String Concatenation Operator

Given two strings, concatenation creates a new string which contains the first string fol-
lowed immediately by the second string. You may concatenate strings in EViews using the
concatenation operator, “+”. For example,
"John " + "Q." + " Public"
"3.14" + "159"

returns the strings

"John Q. Public"
"3.14159"

Bear in mind that string concatenation is a simple operation that does not involve interpreta-
tion of strings as numbers or dates. Note in particular that the latter entry yields the concat-
enated string, “3.14159”, not the sum of the two numeric values, “162.14”. To obtain
numeric results, you will first have to convert your strings into a number (see “String Infor-
mation Functions” on page 90).

Lastly, we note that when concatenating strings, the empty string is interpreted as a blank
string, not as a missing value. Thus, the expression
"Mary " + "" + "Smith"

yields
"Mary Smith"

since the middle string is interpreted as a blank.

 Strings—87

String Relational Operators

The relational operators return a 1 if the comparison is true, and 0 if the comparison is false.
In some cases, relational comparisons involving null strings will return a NA.

String Ordering
To determine the ordering of strings, EViews employs the region-specific collation order as
supplied by the Windows operating system using the user’s regional settings. Central to the
tasks of sorting or alphabetizing, the collation order is the culturally influenced order of
characters in a particular language.

While we cannot possibly describe all of the region-specific collation order rules, we note a
few basic concepts. First, all punctuation marks and other non alphanumeric characters,
except for the hyphen and the apostrophe precede the alphanumeric symbols. The apostro-
phe and hyphen characters are treated distinctly, so that “were” and “we’re” remain close in
a sorted list. Second, the collation order is case specific, so that the character “a” precedes
“A”. In addition, similar characters are kept close so that strings beginning with “a” are fol-
lowed by strings beginning with “A”, ahead of strings beginning with “b” and “B”.

Typically, we determine the order of two strings by evaluating strings character-by-character,

comparing pairs of corresponding characters in turn, until we find the first pair for which
the strings differ. If, using the collation order, we determine the first character precedes the
second character, we say that the first string is less than the second string and the second
string is greater than the first. Two strings are said to be equal if they have the same number
of identical characters.

If the two strings are identical in every character, but one of them is shorter than the other,
then a comparison will indicate that the longer string is greater. A corollary of this statement
is that the null string is less than or equal to all other strings.

The multi-character elements that arise in many languages are treated as single characters
for purposes of comparison, and ordered using region-specific rules. For example, the “CH”
and “LL” in Traditional Spanish are treated as unique characters that come between “C” and
“L” and “M”, respectively.

String Comparison (with non-empty strings)

Having defined the notion of string ordering, we may readily describe the behavior of the
relational operators for non-empty (non-missing) strings. The “=” (equal), “>=” (greater
than or equal), and “<=” (less than or equal), “<>” (not equal), “>” (greater than), and
“<” (less than) comparison operators return a 1 or a 0, depending on the result of the string
comparison. To illustrate, the following (non region-specific) comparisons return the value
1,
"abc" = "abc"
"abc" <> "def"
88—Chapter 5.Strings

"abc" <= "def"

"abc" < "abcdefg"
"ABc" > "ABC"
"abc def" > "abc 1ef"

while the following return a 0,

"AbC" = "abc"
"abc" <> "abc"
"aBc" >= "aB1"
"aBC" <= "a123"
"abc" >= "abcdefg"

To compare portions of strings, you may use the functions @left, @right, and @mid to
extract the relevant part of the string (see “String Manipulation Functions” on page 92). The
relational comparisons,
@left("abcdef", 3) = "abc"
@right("abcdef", 3) = "def"
@mid("abcdef", 2, 2) = "bc"

all return 1.

In normal settings, EViews will employ case-sensitive comparisons (see “Case-Sensitive

String Comparison” on page 190 for settings that enable caseless element comparisons in
programs). To perform a caseless comparison, you should convert the expressions to all
uppercase, or all lowercase using the @upper, or @lower functions. The comparisons,
@upper("abc") = @upper("aBC")
@lower("ABC" = @lower("aBc")

both return 1.

To ignore leading and trailing spaces, you should use the @ltrim, @rtrim, and @trim func-
tions remove the spaces prior to using the operator. The relational comparisons,
@ltrim(" abc") = "abc"
@ltrim(" abc") = @rtrim("abc ")
@trim(" abc ") = "abc"

all return 1.

String Comparison (with empty strings)

Generally speaking, the relational operators treat the empty string as a missing value and
return the numeric missing value NA when applied to such a string. Suppose, for example
that an observation in the alpha series X contains the string “Apple”, and the corresponding
observation in the alpha series Y contains a blank string. All comparisons (“X=Y”, “X>Y”,
 Strings—89

“X>=Y”, “X<Y”, “X<=Y”, and “X<>Y”) will generate an NA for that observation since
the Y value is treated as a missing value.

Note that this behavior differs from EViews 4 and earlier in which empty strings were
treated as ordinary blank strings and not as a missing value. In these versions of EViews, the
comparison operators always returned a 0 or a 1. The change in behavior, while regrettable,
was necessary to support the use of string missing values.

It is still possible to perform comparisons using the previous behavior. One approach is to
use the special functions @eqna and @neqna for equality and strict inequality comparisons
without propagating NAs (see “String Information Functions” on page 90). For example, you
may use the expressions
@eqna(x, y)
@neqna(x, y)

so that blanks in string X or Y are treated as ordinary string values. Using these two func-
tions, the observation where X contains “Apple” and Y contains the “” will evaluate to 0 and
1, respectively instead of NA.

Similarly, if you specify a relational expression involving a literal blank string, EViews will
perform the test treating empty strings as ordinary string values. If, for example, you test
x = ""

or
x < ""

all of the string values in X will be tested against the string literal “”. You should contrast this
behavior with the behavior for the non-literal tests “X=Y” and “X<Y” where blank values
of X or Y result in an NA comparison.

Lastly, EViews provides a function for the strict purpose of testing whether a string value is
an empty string. The @isempty function tests whether a string is empty. The relational
equality test against the blank string literal “” is equivalent to this function.

String Lists
A string list is an ordinary string that is interpreted as a space delimited list of string ele-
ments. For example, the string
"Here I stand"

may be interpreted as containing three elements, the words “Here”, “I” and “stand”. Double
quotes may be used to include multiword elements in a list. Bearing in mind that the quote
is used as an escape character for including quotes in strings, the list
"""Chicken Marsala"" ""Beef Stew"" Hamburger"
90—Chapter 5.Strings

contains three elements, the expressions “Chicken Marsala”, “Beef Stew”, and “Hamburger”.
Notice how the escaped double quotes are used to group words into single list elements.

Interpreting a string as a list of elements allows us to make use of functions which operate
on each element in the string, rather than on each character. These methods can be useful
for string manipulation and pattern searching. For example, we may find the intersection,
union, or cross of two string lists. Additionally, we may manipulate the elements of a string
list and find the elements that match or do not match a given pattern. For example, the
string list function
@wkeep("ABC ABCC AABC", "?B*")

uses the pattern “?B*” to filter the string list “ABC ABCC AABC”. Elements with a single
character, followed by the character “B”, then followed by any number of other characters
are kept, returning: “ABC ABCC”.

String Functions
EViews provides a number of functions that may either be used with strings, or return string
values. Below, we provide a brief summary of the more commonly employed functions.

Functions that treat a string as a string list begin with a “w”. Some string functions have cor-
responding list functions with the same name, preceded by a “w”. For instance, @left
returns the leftmost characters of a string, while @wleft returns the leftmost elements of a
string list.

“String Function Summary” on page 331 offers more extensive list of string functions and
pointers to documentation with additional detail.

String Information Functions

The following is a brief summary of commonly used functions that take a string argument
and return a number.
• @length(str): returns an integer value for the length of the string str.
@length("I did not do it")
returns the value 15.
A shortened keyword form of this function, @len, is also supported.
See @length (p. 944).
• @wcount(str_list): returns an integer value for the number of elements in the string
list str_list.
@wcount("I did not do it")
returns the value 5.
See @wcount (p. 1188).
 Strings—91

• @instr(str1, str2[, int]): finds the starting position of the target string str2 in the base
string str1. By default, the function returns the location of the first occurrence of str2
in str1. You may provide an optional integer int to specify the occurrence. If the
requested occurrence of the target string is not found, @instr will return a 0.
The returned integer is often used in conjunction with @mid to extract a portion of the
original string.
@instr("1.23415", "34")
returns the value 4, since the substring “34” appears beginning in the fourth character
of the base string, so
@mid("1.23415", @instr("1.23415", "34"))
returns “3415”.
See @instr (p. 924).
• @wfind(str_list, str_cmp): looks for the string str_cmp in the string list str_list, and
returns the element position in the list or 0 if the string is not in the list.
@wfind("I did it", "did")
returns the value 2.
The @wfindnc function performs the same operation, but the comparison is not case-
sensitive.
See @wfind (p. 1196) and @wfindnc (p. 1197).
• @isempty(str): tests for whether str is a blank string, returning a 1 if str is a null
string, and 0 otherwise.
@isempty("1.23415")
returns a 0, while
@isempty("")
returns the value 1.
See @isempty (p. 926).
• @eqna(str1, str2): tests for equality of str1 and str2, treating null strings as ordinary
blank strings, and not as missing values. Strings which test as equal return a 1, and 0
otherwise. For example,
@eqna("abc", "abc")
returns a 1, while
@eqna("", "def")
returns a 0.
See @eqna (p. 873).
92—Chapter 5.Strings

• @neqna(str1, str2): tests for inequality of str1 and str2, treating null strings as ordi-
nary blank strings, and not as missing values. Strings which test as not equal return a
1, and 0 otherwise.
@neqna("abc", "abc")
returns a 0,
@neqna("", "def")
returns a 1.
See @neqna (p. 1010).
• @val(str[, fmt]): converts the string representation of a number, str, into a numeric
value. If the string has any non-digit characters, the returned value is an NA. You may
provide an optional numeric format string fmt. See “String Conversion Functions” on
page 97.
See @val (p. 1175).
• @dateval(str[, fmt]): converts the string representation of a date string, str, into a
date number using the optional format string fmt. See “String Conversion Functions”
on page 97.
See @dateval (p. 825).
• @dtoo(str): (Date TO Obs) converts the string representation of a date, str, into an
observation value for the active workfile. Returns the scalar offset from the beginning
of the workfile associated with the observation given by the date string. The string
must be a valid EViews date.
create d 2/1/90 12/31/95
%date = "1/1/93"
!t = @dtoo(%date)
returns the value !T=762.
Note that @dtoo will generate an error if used in a panel structured workfile.
See @dtoo (p. 847).

String Manipulation Functions

The following is a brief summary of some commonly used functions that take strings as an
argument and return a string.
• @left(str, int): returns a string containing the int characters at the left end of the
string str. If there are fewer than int characters, @left will return the entire string.
@left("I did not do it", 5)
returns the string “I did”.
 Strings—93

See @left (p. 942).

• @wleft(str_list, int): returns a string containing the int elements at the left end of the
string list str_list. If there are fewer than int elements, @wleft will return the entire
string list.
@wleft("I did not do it", 3)
returns the string “I did not”.
See @wleft (p. 1203).
• @right(str, int): returns a string containing the int characters at the right end of a
string. If there are fewer than int characters, @right will return the entire string.
@right("I doubt that I did it", 8)
returns the string “I did it”.
See @right (p. 1075).
• @wright(str_list, int): returns a string containing the int elements at the right end of
a string list. If there are fewer than int elements, @wright will return the entire string.
@wright("I doubt that I did it", 3)
returns the string “I did it”.
See @wright (p. 1214).
• @mid(str, int1[, int2]): returns the string consisting of the characters starting from
position int1 in the string. By default, @mid returns the remainder of the string, but
you may specify the optional integer int2, indicating the number of characters to be
returned.
@mid("I doubt that I did it", 9, 10)
returns “that I did”.
@mid("I doubt that I did it", 9)
returns the string “that I did it”.
See @mid (p. 974).
• @wmid(str_list, int1[, int2]): returns the string consisting of the elements starting from
position int1 in the string. By default, @wmid returns all remaining elements of the
string, but you may specify the optional integer int2, indicating the number of ele-
ments to be returned.
@wmid("I doubt that I did it", 2, 3)
returns “doubt you did”.
@wmid("I doubt that I did it", 4)
returns the string “I did it”.
94—Chapter 5.Strings

See @wmid (p. 1206).

• @word(str_list, int): returns the int element of the string list.
@word("I doubt that I did it", 2)
returns the second element of the string, “doubt”.
See @word (p. 1208).
• @wordq(str_list, int): returns the int element of the string list, while preserving
quotes.
@wordq("""Chicken Marsala"" ""Beef Stew""", 2)
returns the second element of the string, “Beef Stew”. The @word function would
return the same elements, but would not include quotation marks in the string.
See @wordq (p. 1209).
• @insert(str1, str2, int): inserts the string str2 into the base string str1 at the position
given by the integer int.
@insert("I believe it can be done", "not ", 16)
returns “I believe it cannot be done”.
See @insert (p. 923).
• @wkeep(str_list, "pattern_list"): returns the list of elements in str_list that match the
string pattern pattern_list. The pattern_list is space delimited, and may be made up of
any number of “?” (indicates any single character) or “*” (indicates any number of
characters).
@wkeep("ABC DEF GHI JKL", "?B? D?? *I")
keeps the first three elements of the string list, returning the string “ABC DEF GHI”.
See @wkeep (p. 1202).
• @wdrop(str_list, "pattern_list"): returns a string list, dropping elements in str_list that
match the string pattern pattern_list. The pattern_list is space delimited, and may be
made up of any number of “?” (indicates any single character) or “*” (indicates any
number of characters).
@wdrop("ABC DEF GHI JKL", "?B? D?? *I")
drops the first three elements of the string list, returning the string “JKL”.
See @wdrop (p. 1191).
• @replace(str1, str2, str3[, int]): returns the base string str1, with the replacement
str3 substituted for the target string str2. By default, all occurrences of str2 will be
replaced, but you may provide an optional integer int to specify the number of occur-
rences to be replaced.
@replace("Do you think that you can do it?", "you", "I")
 Strings—95

returns the string “Do I think that I can do it?”, while

@replace("Do you think that you can do it?", "you", "I", 1)
returns “Do I think that you can do it?”.
See @replace (p. 1070).
• @wreplace(str_list, “src_pattern”, “replace_pattern”): returns the base string list
str_list, with the replacement pattern replace_pattern substituted for the target pattern
src_pattern. The pattern lists may be made up of any number of “?” (indicates any sin-
gle character) or “*” (indicates any number of characters).
@wreplace("ABC AB", "*B*", "*X*")
replaces all instances of “B” with “X”, returning the string “AXC AX”.
@wreplace("ABC DDBC", "??B?", "??X?")
replaces all instances of “B” which have two leading characters and one following
character, returning the string “ABC DDXC”.
See @wreplace (p. 1211).
• @ltrim(str): returns the string str with spaces trimmed from the left.
@ltrim(" I doubt that I did it. ")
returns “I doubt that I did it. ”. Note that the spaces on the right remain.
See @ltrim (p. 953).
• @rtrim(str): returns the string str with spaces trimmed from the right.
@rtrim(" I doubt that I did it. ")
returns the string “ I doubt that I did it.”. Note that the spaces on the left remain.
See @rtrim (p. 1100).
• @trim(str): returns the string str with spaces trimmed from the both the left and the
right.
@trim(" I doubt that I did it. ")
returns the string “I doubt that I did it.”
See @trim (p. 1153).
• @upper(str): returns the upper case representation of the string str.
@upper("I did not do it")
returns the string “I DID NOT DO IT”.
See @upper (p. 1171).
• @lower(str): returns the lower case representation of the string str.
@lower("I did not do it")
96—Chapter 5.Strings

returns the string “i did not do it”.

See @lower (p. 951).
• @addquotes(str): returns the string str with quotation marks added to the left and
right. Given a string S1 that contains the unquoted text: I did not do it,
@addquotes(S1)
returns the quoted string “I did not do it”.
See @addquotes (p. 715).
• @stripquotes(str): returns the string str with quotation marks removed from the left
and right. Given a string S1 that contains the text: “I did not do it”,
@stripquotes(S1)
returns the unquoted string: “I did not do it”.
See @stripquotes (p. 1131).
• @stripparens(str): returns the string str with parentheses removed from the left and
right. Given a string S1 that contains the text: “(I did not do it)”,
@stripparens(S1)
returns the string: “I did not do it”.
See @stripparens (p. 1130).
• @wintersect(str_list1, str_list2): returns the intersection of str_list1 and str_list2.
@wintersect("John and Greg won", "Mark won but Greg lost")
returns the string “won Greg”.
See @wintersect (p. 1201).
• @wunion(str_list1, str_list2): returns the union of str_list1 and str_list2.
@wunion("ABC DEF", "ABC G H def")
returns the string “ABC DEF G H def”. Each new element is added to the string list,
skipping elements that have already been added to the list.
See @wunion (p. 1216).
• @wunique(str_list): returns str_list with duplicate elements removed from the list.
@wunique("fr1 fr2 fr1")
returns the string “fr1 fr2”.
See @wunique (p. 1217).
• @wnotin(str_list1, str_list2): returns elements of str_list1 that are not in str_list2.
@wnotin("John and Greg won", "and Greg")
returns the string “John won”.
 Strings—97

See @wnotin (p. 1207).

• @wcross(str_list1, str_list2[, “pattern”]): returns str_list1 crossed with str_list2,
according to the string pattern. The default pattern is “??”, which indicates that each
element of str_list1 should be crossed individually with each element of str_list2.
@wcross("ABC DEF", "1 2 3", "?-?")
returns the string list “ABC-1 ABC-2 ABC-3 DEF-1 DEF-2 DEF-3”, inserting a dash (“-”)
between each crossed element as the “?-?” pattern indicates.
See @wcross (p. 1188).
• @winterleave(str_list1, str_list2[, count1, count2]): Interleaves str_list1 with
str_list2, according to the pattern specified by count1 and count2. The default uses
counts of one.
@winterleave("A B C", "1 2 3")
interleaves “A B C” with “1 2 3” to produce the string list “A 1 B 2 C 3”.
See @winterleave (p. 1200).
• @wsort(str_list[,”D”]): Returns sorted elements of str_list. Use the “D” flag to sort in
descending order.
@wsort("fq8 Fq8 xpr1", "D")
sorts the string in descending order: “xpr1 Fq8 fq8”.
See @wsort (p. 1215).
• @wdelim(str_list, "src_delim", "dest_delim"): returns a string list, replacing every
appearance of the src_delim delimiter in str_list with a dest_delim delimiter. Delimit-
ers must be single characters.
@wdelim("Arizona, California, Washington", ",", "-")
identifies the comma as the source delimiter and replaces each comma with a dash,
returning the string “Arizona-California-Washington”.
See @wdelim (p. 1189).

String Conversion Functions

The following functions convert between numbers or date numbers and strings:
• @datestr(date1[, fmt]): converts the date number date1 to a string representation
using the optional date format string, fmt.
@datestr(730088, "mm/dd/yy")
will return “12/1/99”,
@datestr(730088, "DD/mm/yyyy")
will return “01/12/1999”, and
98—Chapter 5.Strings

@datestr(730088, "Month dd, yyyy")

will return “December 1, 1999”, and
@datestr(730088, "w")
will produce the string “3”, representing the weekday number for December 1, 1999.
See “Dates” on page 104 for additional details on date numbers and date format
strings.
See @datestr (p. 824).
• @dateval(str[, fmt]): converts the string representation of a date string, str, into a
date number using the optional format string fmt.
@dateval("12/1/1999", "mm/dd/yyyy")
will return the date number for December 1, 1999 (730088) while
@dateval("12/1/1999", "dd/mm/yyyy")
will return the date number for January 12, 1999 (729765). See “Dates,” beginning on
page 104 for discussion of date numbers and format strings.
See @dateval (p. 825)
• @str(num[, fmt]): returns a string representation of the number num. You may pro-
vide an optional numeric format string fmt.
@str(153.4)
returns the string “153.4”.
To create a string containing 4 significant digits and leading “$” character, use
@str(-15.4435, "g$.4")
The resulting string is “-$15.44”.
The expression
@str(-15.4435, "f7..2")
converts the numerical value, -15.4435, into a fixed 7 character wide decimal string
with 2 digits after the decimal and comma as decimal point. The resulting string is
“ -15,44”. Note that there is a leading space in front of the “-” character making the
string 7 characters long.
The expression
@str(-15.4435, "e(..2)")
converts the numerical value, -15.4435, into a string written in scientific notation with
two digits to the right of the decimal point. The decimal point in the value will be rep-
resented using a comma and negative numbers will be enclosed in parenthesis. The
resulting string is “(1,54e+01)”. A positive value will not have the parenthesis.
@str(15.4435, "p+.1")
 Strings—99

converts the numeric value, 15.4435, into a percentage where the value is multiplied
by 100. Only 1 digit will be included after the decimal and an explicit “+” will always
be included for positive numbers. The resulting value after rounding is “+1544.4”.
See @str (p. 1123).
• @val(str[, fmt]): converts the string representation of a number, str, into a numeric
value. If the string has any non-digit characters, the returned value is an NA. You may
provide an optional numeric format string fmt.
@val("1.23415")
See @val (p. 1175).

String Vector Functions

The following functions either take a string vector as an argument, or return a string vector:
@rows(str_vector): returns the number of rows in str_vector.
For a string vector SV01 with 10 rows,
@rows(sv01)
returns the integer 10.
• @wsplit(str_list): returns a string vector containing the elements of str_list.
If the string list SS01 contains “A B C D E F”, then
@wsplit(ss01)
returns an untitled svector, placing an element of SS01 in each row. Row one of the
svector contains “A”, row two contains “B”, etc.
See @wsplit (p. 1216).
• @wjoin(svector): returns a space delimited list containing the elements of svector.
This function is the inverse of the @wsplit function.
See @wjoin (p. 1202).

Special Functions that Return Strings

EViews provides a special, workfile-based function that uses the structure of the active
workfile page and returns a set of string values representing the date identifiers associated
with the observations.
• @strdate(fmt): returns the set of workfile row dates as strings in an Alpha series,
formatted using the date format string fmt. See “Special Date Functions” on page 122
for details.
See @strdate (p. 1128).
100—Chapter 5.Strings

In addition, EViews provides two special functions that return a string representations of the
date associated with a specific observation in the workfile, or with the current time.
• @otod(int): (Obs TO Date): returns a string representation of the date associated with
a single observation (counting from the start of the workfile). Suppose, for example,
that we have a quarterly workfile ranging from 1950Q1 to 1990Q4. Then
@otod(16)
returns the date associated with the 16th observation in the workfile in string form,
“1953Q4”.
See @otod (p. 1019).
• @otods(int): (Obs TO Date in Sample): returns a string representation of the date
associated with a single observation (counting from the start of the sample). Thus
@otods(2)
will return the date associated with the second observation in the current sample.
Note that if int is negative, or is greater than the number of observations in the cur-
rent sample, an empty string will be returned.
See @otods (p. 1020).
• @strnow(fmt): returns a string representation of the current date number (at the
moment the function is evaluated) using the date format string, fmt.
@strnow("DD/mm/yyyy")
returns the date associated with the current time in string form with 2-digit days,
months, and 4-digit years separated by a slash, “24/12/2003”.
See @strnow (p. 1132).

You may also ask EViews to report information about objects in the current workfile or data-
base, or a directory on your computer, in a form suitable for list processing:
• @wlookup(“pattern_list”[, “object_type_list”]): Returns a string list of all objects in the
workfile or database that satisfy the pattern_list and, optionally, the object_type_list.
The pattern_list may be made up of any number of “?” (indicates any single charac-
ter) or “*” (indicates any number of characters).
If a workfile contains a graph object named “GR01” and two series objects named
“SR1” and “SER2”, then
@wlookup("?R?","series")
returns the string “SR1”.
See @wlookup (p. 1204).
• @wdir(directory_str): returns a string list of all files in the directory directory_str. Note
that this does not include other directories nested within directory_str.
 Strings—101

@wdir("C:\Documents and Settings")

returns a string list containing the names of all files in the “C:\Documents and Set-
tings” directory.
See @wdir (p. 1190).

Lastly, all EViews objects have data members which return information about themselves in
the form of a string. For example:
ser1.@updatetime

returns the last update time for the series SER1

eq1.@command

returns the full command line form of the estimation command.

For lists of the relevant data members see the individual object descriptions in Chapter 1.
“Object View and Procedure Reference,” on page 3.

Using Strings in EViews

Strings in EViews are primarily used in four distinct contexts: string variables, string objects,
string vectors, or Alpha series.

String Variables
A string variable is a temporary variable used in a program whose value is a string. String
variables, which only exist during the time that your EViews program is executing, have
names that begin with a “%” symbol. For example,
%value = "value in millions of u.s. dollars"
%armas = "ar(1) ar(2) ma(1) ma(2)"

are string variables declarations that may be used in program files.

See “String Variables,” on page 145 for extensive discussion of the role that these variables
play in programming.

String Objects
A string object is an EViews workfile object that holds a string of text:
string lunch = "Apple Tuna Cookie"
string dinner = """Chicken Marsala"" ""Beef Stew"" Hamburger"

creates the string objects LUNCH and DINNER, each containing the corresponding string lit-
eral. Note that we have used the double quote character as an escape character for double
quotes.
102—Chapter 5.Strings

Since a string object is an EViews workfile object, we may open and display its views. A
string object’s view may be switched between String and Word list views. The String view
for DINNER displays the text as a single string,
"Chicken Marsala" "Beef Stew" Hamburger

while the Word list view breaks up the text by element,

"Chicken Marsala"
"Beef Stew"
Hamburger

with each element on a separate line.

We emphasize the important distinction that string objects are named objects in the workfile
that may be saved with the workfile, while string variables are temporary variables that only
exist while an EViews program is running. Thus, string objects have the advantage that they
may be used interactively, while string variables may not be used outside of programs.
String objects can, however, go out of scope when the active workfile page changes, while
string variables are always in scope.

In all other respects, strings objects and string variables may be used interchangeably in pro-
grams. Either string object or string variables can be passed into subroutines for arguments
declared as type string.

String Vectors
An svector, or string vector, is an EViews object that holds a string in each row of the vector.
A string vector can be created by specifying the number of rows in the vector and providing
a name:
svector(3) svec

If a length is not specified, a one row svector will be created.

An svector can be populated by assigning a string or string literal to each row:

svec(1) = "gdp cost total"

fills the first row of SVEC with the string “gdp cost total”. To assign the same string to all
rows, omit the row number. The command
svec = "invalid"

will assign the string “invalid” to all rows of SVEC.

A multiple row svector may be populated using the @wsplit command, which creates a
string vector from a string list. For example,
svector svec
string st = "gdp cost total"
 Strings—103

svec = @wsplit(st)

creates the string vector SVEC of default length one and a string object ST containing “gdp
cost total”. The @wsplit (p. 1216) command creates a three element svector from the ele-
ments of ST, placing the string “gdp” in the first row of the string vector, the string “cost” in
the second row, and the string “total” in the third row, and assigns it to SVEC, which is
resized accordingly.

Similarly, an svector will shrink if assigned to a smaller svector. For example,

svector svec3 = @wsplit("First Middle Last")
svector(10) svec10
svec10 = svec3

first creates the three row svector SVEC3, then assigns the strings “First”, “Middle”, and
“Last” to the first, second, and third rows, respectively. The third line creates a second ten
row svector, SVEC10. When SVEC3 is assigned to SVEC10, its values are copied over and
rows four through ten are removed from SVEC10.

An svector may also be filled by concatenating two strings or svectors. For instance,
svector s1 = @wsplit("A B C")
svector s2 = @wsplit("1 2 3")
svector ssvec = s1 + s2

creates two svectors S1 and S2, each with three rows. S1 contains the characters “A”, “B”,
and “C”, while S2 contains “1”, “2”, and “3”. The third command creates the svector SSVEC
and fills it with the concatenation of the other two svectors, producing “A1” on the first row,
“B2” on the second row, and “C3” on the third row.

More generally, any operation that can be performed on a string may be performed on ele-
ment of an svector. For example, given an svector whose first element contains the string
“Hello World” and whose second element contains “Hi there world”, the element assign-
ment statement
svector sv(3) = @left(sv(1),5) + " " + @mid(sv(2),4,5)

takes the left five characters of the first row (“Hello”), adds a space, concatenates five char-
acters from the second row, starting at the fourth character (“there”), and assigns it to the
third element of SV. Element three of SV now contains the string “Hello there”.

The row count of a string vector may be retrieved using the @rows command:
scalar sc = @rows(sv)

This is especially useful since svectors are dynamically resized when necessary.
104—Chapter 5.Dates

Alpha Series
EViews has a special series type for holding string data. An alpha series object contains a set
of observations on string values. Alpha series should be used when you wish to work with
variables that contain alphanumeric data, such as names, addresses, and other text.

Alpha series are distinguished from string vectors primarily in that their length is tied to the
length of the workfile.

See “Alpha Series,” on page 224 for discussion.

Dates
There are a variety of places in EViews where you may work with calendar dates. For most
purposes, users need not concern themselves with the intricacies of working with dates.
Simply enter your dates in familiar text notation and EViews will automatically interpret the
string for you.

Those of you who wish to perform more sophisticated operations with dates will, however,
need to understand some basic concepts.

In most settings, you may simply use text representations of dates, or date strings. For exam-
ple, an EViews sample can be set to include only observations falling between two dates
specified using date strings such as “May 11, 1997”, “1/10/1990” or “2001q1”. In these set-
tings, EViews understands that you are describing a date and will interpret the string accord-
ingly.

Date information may also be provided in the form of a date number. A date number is a
numeric value with special interpretation in EViews as a calendar date. EViews allows you
to convert date strings into date numbers which may be manipulated using a variety of
tools. These tools allow you to perform standard calendar operations such as finding the
number of days or weeks between two dates, the day of the week associated with a given
day, or the day and time 36 hours from now.

The remainder of this section summarizes the use of dates in EViews. (See Chapter 5.
“Strings and Dates,” on page 85 for reference material.) There are several tasks that are cen-
tral to working with dates:
• Translating between date strings and date numbers.
• Translating ordinary numbers into date numbers.
• Manipulating date numbers using operators and functions.
• Extracting information from date numbers.
 Dates—105

Before turning to these tasks, we must first provide a bit of background on the characteris-
tics of date strings, date numbers, and a special class of strings called date formats, which
are sometimes employed when translating between the former.

Date Strings
Date strings are simply text representations of dates and/or times. Most of the conventional
ways of representing days, weeks, months, years, hours, minutes, etc., as text are valid date
strings.

To be a bit more concrete, the following are valid date strings in EViews:
"December 1, 2001"
"12/1/2001"
"Dec/01/01 12am"
"2001-12-01 00:00"
"2001qIV”

As you can see, EViews is able to handle a wide variety of representations of your dates and
times. You may use everything from years represented in 1, 2, and 4-digit Arabic form (“1”,
“01”, “99”, “1999”), to month names and abbreviations (“January”, “jan”, “Jan”), to quar-
ter designations in Roman numerals (“I” to “IV”), to weekday names and abbreviations
(“Monday”, “Mon”), to 12 or 24-hour representations of time (“11:12 pm”, “23:12”). A full
list of the recognized date string components is provided in “Date Formats” on page 106.

It is worth noting that date string representations may be divided up into those that are
unambiguous and those that are ambiguous. Unambiguous date strings have but a single
interpretation as a date, while ambiguous date strings may be interpreted in multiple ways.

For example, the following dates may reasonably be deemed unambiguous:

"March 3rd, 1950"
"1980Q3"
"9:52PM"

while the following dates are clearly ambiguous:

"2/3/4"
"1980:2"
"02:04"

The first date string in the latter set is ambiguous because we cannot tell which of the three
fields is the year, which is the month, and which is the day, since different countries of the
world employ different orderings. The second string is ambiguous since we cannot deter-
mine the period frequency within the year. The “2” in the string could, for example, refer to
the second quarter, month, or even semi-annual in the year. The final string is ambiguous
since it could be an example of a time of day in “hour:minute” format (2:04 am), or a date
106—Chapter 5.Dates

in “year:period” notation (i.e., the fourth month of the year 2002) or “period:year” notation
(i.e., the second month of 2004).

In settings where date input is required, EViews will generally accept date string values
without requiring you to provide formatting information. It is here that the importance of
the distinction between ambiguous and unambiguous date strings is seen. If the date string
is unambiguous, the free-format interpretation of the string as a date will produce identical
results in all settings. On the other hand, if the date string is ambiguous, EViews will use the
context in which the date is being used to determine the most likely interpretation of the
string. You may find that ambiguous date strings are neither interpreted consistently nor as
desired.

These issues, and methods of getting around the problem of ambiguity, are explored in
greater detail in “Translating between Date Strings and Date Numbers” on page 110.

Date Numbers
Date information is often held in EViews in the form of a date number. A date number is a
double precision number corresponding to an instance in time, with the integer portion rep-
resenting a specific day, and the decimal fraction representing time during the day.

The integer portion of a date number represents the number of days in the Gregorian prolep-
tic calendar since Monday, January 1, A.D. 0001 (a “proleptic” calendar is a calendar that is
applied to dates both before and after the calendar was historically adopted). The first repre-
sentable day, January 1, A.D. 1 has an integer value of 0, while the last representable day,
December 31, A.D. 9999, has an integer value of 3652058.

The fractional portion of the date number represents a fraction of the day, with resolution to
the millisecond. The fractional values range from 0 (12 midnight) up to (but not including) 1
(12 midnight). A value of 0.25, for example, corresponds to one-quarter of the day, or 6:00
a.m.

It is worth noting that the time of day in an EViews date number is accurate up to a particu-
lar millisecond within the day, although it can always be displayed at a lower “precision”
(larger unit of time). When date numbers are formatted to lower precisions, they are always
rounded down to the requested precision and never rounded up. Thus, when displaying the
week or month associated with a date number, EViews always rounds down to the begin-
ning of the week or month.

Date Formats
A date format string (or date format, for short) is a string made up of text expressions that
describe how components of a date and time may be encoded in a date string. Date formats
are used to provide an explicit description of a date string representation, and may be
employed when converting between strings or numbers and date numbers.
 Dates—107

Before describing date formats in some detail, we consider a simple example. Suppose that
we wish to use the date string “5/11/1997” to represent the date May 11, 1997. The date for-
mat corresponding to this text representation is
"mm/dd/yyyy"

which indicates that we have, in order, the following components: a one or two-digit month
identifier, a “/” separator, a one or two-digit day identifier, a “/” separator, and a 4-digit year
identifier.

Alternatively, we might wish to use the string “1997-May-11” to represent the same date.
The date format for this string is
"yyyy-Month-dd"

since we have a four-digit year, followed by the full name of the month (with first letter cap-
italized), and the one or two-digit day identifier, all separated by dashes.

Similarly, the ISO 8601 representation for 10 seconds past 1:57 p.m. on this date is “1997-05-
11 13:57:10”. The corresponding format is
"yyyy-MM-DD HH:mi:ss"

Here, we have used the capitalized forms of “MM”, “DD”, and “HH” to ensure that we have
the required leading zeros.

A full description of the components of a date format is provided below. Some of the more
commonly used examples of date formats are listed in the options for the setformat object
commands (see, for example, Table::setformat (p. 1096) in the Object Reference).

Date Format Components

A date format may contain one or more of the following string fragments corresponding to
various date components. In most cases, there are various upper and lowercase forms of the
format component, corresponding either to the presence or absence of leading zeros, or to
the case of the string identifiers.

The following format strings are the basic components of a date format:

Years
Year formats use either two or four digit years, with or without leading zeros. The corre-
sponding date format strings are:
• “yyyy” or “YYYY”: four digit year without/with leading zeros.
• “yy” or “YY”: two digit year without/with leading zeros.
• “year” or “YEAR”: synonym for “yyyy” and “YYYY”, respectively.
108—Chapter 5.Dates

Semi-Annual
The semi-annual format corresponds to a single digit representing the period in the year:
• “s” or “S”: one digit half-year (1 or 2).

Quarters
Quarter formats allow for values entered in either standard (Arabic) or Roman numbers:
• “q” or “Q”: quarter number, always without leading zeros (1 to 4).
• “qr” or “QR”: quarter in Roman numerals following the case of the format string (“i”
to “iv” or “I” to “IV”.)

Months
Month formats may represent two-digit month values with or without leading zeros, three-
letter abbreviations for the month, or the full month name. The text identifiers may be all
lowercase, all uppercase or “namecase” in which we capitalize the first letter of the month
identifier. The corresponding format strings are given by:
• “mm” or “MM”: two-digit month without/with leading zeros.
• “mon”, “Mon”, or “MON”: three-letter form of month, following the case of the for-
mat string(“jan”, “Feb”, “MAR”).
• “month”, “Month”, or “MONTH”: full month name, following the case of the format
string (“january”, “February”, “MARCH”).

Weeks
Week of the year formats may be specified with or without leading zeros:
• “ww” or “WW”: week of year (with first week starting from Jan 1st) without/with
leading zeros.

Days
Day formats correspond to day of the year, business day of the year, day of the month, or
day of the week, in various numeric and text representations.
• “ddd” or “DDD”: day of year without/with leading zeros.
• “bbb” or “BBB”: business day of year without/with leading zeros (only counting
Monday-Friday).
• “dd” or “DD”: day of month without/with leading zeros.
• “day” or “DAY”: day of month with suffix, following the case of the format string
(“1st”, “2nd”, “3RD”).
• “w” or “W”: weekday number (1-7) where 1 is Monday.
 Dates—109

• “wdy”, “Wdy”, or “WDY”: three-letter weekday abbreviation, following the case of

the format string (“Mon”, “Tue”, “WED”).
• “weekday”, “Weekday”, or “WEEKDAY”: full weekday name, following the case of the
format string (“monday”, “Tuesday”, “WEDNESDAY”).

Time (Hours/Minutes/Seconds)
The time formats correspond to hours (in 12 or 24 hour format), minutes, seconds, and frac-
tional sections, with or without leading zeros and with or without the AM/PM indicator
where appropriate.
• “hh” or “HH”: hour in 24-hour format without/with leading zeros.
• “hm” or “HM”: hour in 12-hour format without/with leading zeros.
• “am” or “AM”: two letter AM/PM indicator for 12-hour format, following the case of
the format string.
• “a” or “A”: single letter AM/PM indicator for 12-hour format, following the case of the
format string.
• “mi” or “MI”: minute, always with leading zeros.
• “ss.s”, “ss.s”, “ss.ss”, or “ss.sss”: seconds and tenths, hundreths, and thousandths-of-
a-second, with leading zeros. The capitalized forms of these formats (“SS”, “SS.S”, ...)
yield identical results.

Delimiters
You may use text to delimit the date format components:
• “f” or “F”: use frequency delimiter taken from the active, regular frequency workfile
page. The delimiter corresponds to the letter associated with the current workfile fre-
quency (“a”, “m”, “q”, ..., “A”, “M”, “Q”, ...), following the case of the format string,
or the colon (“:”), as determined by the Global Options setting (Options/General
Options.../Date representation).
• “?”: when used in an input date format, skips a single character of the input string. In
an output date format “?” will be passed to the output string.
On input, the”?” delimiter is useful for ignoring part of a date string or where a delim-
iter may be variable. For example, an input string "02:83" could be interpreted using
the format "MM:YY" to capture both month and year, or the format "??:YY" to capture
just the year.
• Other alphabetical characters are errors unless they are enclosed in square brackets
e.g. “[Q]”, in which case they are passed through to the output (for example, the
“standard-EViews” quarterly format is “YYYY[Q]Q”, where we use a four digit year
110—Chapter 5.Dates

identifier, followed by a “Q” delimiter/identifier, followed by a single digit for the

quarter “1990Q2”).
• All other characters (e.g., punctuation) are passed through to the input or output
without special interpretation.

Translating between Date Strings and Date Numbers

There are times when it is convenient to work with date strings, and times when it is easier
to work with date numbers.

For example, when we are describing or viewing a specific date, it is easier to use a “human
readable” date string such as “2002-Mar-20”, “3/20/2002”, or “March 20, 2002 12:23 pm”
than the date number 730928.515972.

Alternatively, since date strings are merely text representations of dates, working with date
numbers is essential when manipulating calendar dates to find elapsed days, months or
years, or to find a specific date and time 31 days and 36 hours from now.

Accordingly, translating between string representations of dates and date numbers is one of
the more important tasks when performing advanced operations with dates in EViews.
These translations occur in many places in EViews, ranging from the interpretation of date
strings in sample processing, to the spreadsheet display of series containing date numbers,
to the import and export of data from foreign sources.

In most settings, the translations take place automatically, without user involvement. For
example, when you enter a sample command of the form
smpl 1990q1 2000q4

EViews automatically converts the date strings into a range of date numbers. Similarly,
when you edit a series that contains date numbers, you typically will enter your data in the
form of a date string such as
"2002-Mar-20"

which EViews will automatically translate into a date number.

In other cases, you will specifically request a translation by using the built-in EViews func-
tions @datestr (to convert a date number to a string) and @dateval (to convert a date
string to a date number).

For example, the easiest way to identify the date 1,000 days after May 1, 2000 is first to con-
vert the string value “May 1, 2000” into a date number using @dateval, to manipulate the
date number to find the value 1000 days after the original date, and finally to convert the
resulting date number back into a string using @datestr (p. 824). See also “Formatted Con-
version” on page 114 and “Manipulating Date Numbers” on page 119 for additional details.

All translations between dates strings and date numbers involve one of two methods:
 Dates—111

• First, EViews may perform a free-format conversion in which the date format is
inferred from the string values, in some cases other contextual information.
• Second, EViews may perform a formatted conversion in which the string representa-
tion of the dates is provided explicitly via a date format.

For the most part, you should find that free-format conversion is sufficient for most needs.
Nevertheless, in some cases the automatic handling of dates by EViews may not produce the
desired results. If this occurs, you should either modify any ambiguous date formats, or
specify an explicit formatted conversion to generate date numbers as necessary.

Free-format Conversion
EViews will perform free-format conversions between date strings and numbers whenever:
(1) there is an automatic translation between strings and numbers, or (2) when you use one
of the translation functions without an explicit date format.

When converting from strings to numbers, EViews will produce a date number using the
“most likely” interpretation of the date string. For the most part, you need not concern your-
self with the details of the conversion, but if you require additional detail on specific topics
(e.g., handling of date intervals, the implicit century cutoff for 2-digit years) see “Free-for-
mat Conversion Details” on page 124.

When converting from date numbers to strings, EViews will use the global default settings to
determine the default date format, and will display all significant information in the date
number.

Converting Unambiguous Date Strings to Numbers

The free-format conversion of unambiguous date strings (see “Date Strings” on page 105), to
numbers will produce identical results in all settings. The date string:
"March 3rd, 1950"

will be interpreted as the third day of the third month of the year A.D. 1950, and will yield
the date value 711918.0. Note that the date value is the smallest associated with the given
date, corresponding to 12 midnight.

Similarly, the date string:

"1980Q3"

is interpreted as the first instance in the third quarter of 1980. EViews will convert this string
into the date number representing the smallest date value in that quarter, 722996.0 (12 mid-
night on July 1, 1980).

If we specify a time string without a corresponding day,

"9:52PM"
112—Chapter 5.Dates

the day portion of the date is set to 0 (effectively, January 1, A.D. 1), yielding a value of
0.91111111 (see “Incomplete Date Numbers” on page 125) for details.

Consider also the following ambiguous date string:

"1 May 03"

While this entry may appear to be ambiguous since the “03” may reasonably refer to either
1903 or 2003, EViews resolves the ambiguity by assuming that if the two-digit year is greater
than or equal to 30, the year is assumed to be from the twentieth century, otherwise the year
is assumed to be from the twenty first century (see “Two-digit Years” on page 125 for discus-
sion). Consequently free-format conversion of two-digit years will produce consistent results
in all settings.

Converting Ambiguous Date Strings to Numbers

Converting from ambiguous date strings will yield context sensitive results. In cases involv-
ing ambiguity, EViews will determine the most likely translation format by examining sur-
rounding data or applicable settings for clues as to how the date strings should be
interpreted.

The following contextual information is used in interpreting ambiguous free-form dates:

• For implicit period notation (e.g., “1990:3”) the current workfile frequency is used to
determine the period.
• Choosing between ambiguous “mm/dd” or “dd/mm” formats is determined by exam-
ining the values of related date strings (i.e., those in the same series), user-specified
date/time display formats for a series or column of a spreadsheet, or by examining the
EViews global setting for date display, (Options/General Options.../Date representa-
tion).

To fix ideas, we consider a few simple examples of the use of contextual information.

If you specify an ambiguous sample string, EViews will use the context in which the sample
is used, the frequency of the workfile, to determine the relevant period. For example, given
the sample statement
smpl 90:1 03:3

and a quarterly workfile, the sample will be set from 1990q1 to 2003q3. If the workfile is
monthly, the sample will be set from January 1990 to March 2003.

Suppose instead that you are editing a series spreadsheet where your date numbers are dis-
played as dates strings using a specified format. In this setting, EViews allows you to enter
your values as date strings, instead of having to enter the underlying date numbers. In this
context, it is natural for EViews to use the current display format as a hint in interpreting
ambiguous data. For example, if the current display format is set to “Month dd, YYYY” then
an input of “2/3/4” or “@dateval("2/3/4")” will be interpreted as February the 3rd, 2004.
 Dates—113

On the other hand, if the current display format is set to “YYYY-MM-DD” then the same
input will be interpreted as the March the 4th, 2002.

In settings where an entire series is provided to an EViews procedure, EViews is able to use
all of the values in the series to aid in determining the underlying data format. For example,
when an alpha series is provided as a date identifier for restructuring a workfile, EViews will
first scan all the values of the series in order to decide on the most likely format of all of the
data before converting the string in each element into a date number. If the first observation
of the series is an ambiguous “2/3/4” but a later observation is “3/20/95” then the “2/3/4”
will be interpreted as the 3rd of February 2004 since that is the only order of year, month
and day that is consistent with the “3/20/95” observation.

Conversely, when generating new series values with a genr or series assignment statement,
EViews processes observation individually and is therefore unable to obtain contextual
information to aid in interpreting ambiguous date strings. In this case, EViews will use the
global workfile setting for the Month/Day order in dates to determine the ordering of the
days and months in the string.

For example, when the expression

series dnums = @dateval("2/3/4")

is used to generate a series containing date values, EViews will interpret the value as Febru-
ary 3, 2004, if the global setting is Month/Day/Year, and March 2, 2004, if the global setting
is Day/Month/Year.
114—Chapter 5.Dates

Converting Date Numbers to Strings

EViews provides the @datestr (p. 824) function to translate a date number to a date string.
We describe the function in detail in “Formatted Conversion” on page 114, but for now, sim-
ply note that @datestr takes an optional argument describing the date format to be used
when exporting the string. If the optional argument is not provided, EViews will perform a
free-format conversion.

In performing the free-format conversion, EViews examines two pieces of information. First,
the global default settings for the Month/Day order in dates will be used to determine the
ordering of days and months in the string. Next, EViews examines the date values to be
translated and looks for relevant time-of-day information.

If there is no relevant time-of-day information in the date numbers (e.g., the non-integer por-
tions are all zero), EViews writes the string corresponding to the date using either the date
format
"dd/mm/yyyy"

or
"mm/dd/yyyy”

with preference given to the order favored in the global settings.

If there is relevant time-of-day information, EViews will extend the date format accordingly.
Thus, if days are favored in the ordering, and relevant hours (but not minutes and seconds)
information is present, EViews will use
"dd/mm/yyyy hh"

while if hours-minutes are present, the format will be

"dd/mm/yyyy hh:mi"

and so forth.

Formatted Conversion
While the free-format conversions will generally produce the desired results, there may be
times when you want to exercise precise control over the conversion. EViews will perform a
formatted conversion between date strings and date numbers whenever you use the @dat-
eval (p. 825) or @datestr (p. 824) functions with the optional second argument specifying
an explicit date format.

To convert a date string into a date number using a date format, you should use the @dat-
eval function with two arguments. The first argument must be a valid date string, and the
second must be the corresponding date format string. If you omit the optional second argu-
ment, EViews will perform a free-format conversion.
 Dates—115

• @dateval(str[, fmt]): takes the string str and evaluates it to a date number using the
optional date format string, fmt.
See @dateval (p. 825).

A few simple examples will illustrate the wide range of string to date number conversions
that are possible using @dateval and a date format. The simplest format strings involve the
standard month/day/year date descriptions:
@dateval("12/1/1999", "mm/dd/yyyy")

will return the date number for December 1, 1999 (730088),

@dateval("12/1/1999", "dd/mm/yyyy")

returns the date number for January 12, 1999 (729765). Here we have changed the interpre-
tation of the date string from “American” to “European” by reversing the order of the parts
of the format string.

Likewise, we may find the first date value associated with a given period
@dateval("1999", "yyyy")

returns the value 729754.0 corresponding to 12 midnight on January 1, 1999, the first date
value for the year 1999.

Conversion of an broad range of date strings is possible by putting together various date for-
mat string components. For example,
@dateval("January 12, 1999", "Month dd, yyyy")

returns the date number for 12 midnight on January 12, 1999 (729765), while
@dateval("99 January 12, 9:37 pm", "yy Month dd, hm:mi am")

yields the value 729765.900694 corresponding to the same date, but at 9:37 in the evening.
In this example, the “hm:mi” corresponds to hours (in a 12 hour format, with no leading
0’s) and minutes, and the “am” indicates that there is an indicator for “am” and “pm”. See
“Date Strings” on page 105 and “Date Formats” on page 106 for additional details.

To translate a date number to a date string using a date format, you should use the @dat-
estr function with two arguments. The first argument must be a valid date number, and the
second must be a date format string describing a string representation of the date.
• @datestr(date_val[, fmt]): converts the date number into a string, using the optional
date format fmt. If a format is not provided, EViews will use a default method (see
“Converting Date Numbers to Strings” on page 114).
See @datestr (p. 824).

For example,
@datestr(730088,"mm/dd/yy")
116—Chapter 5.Dates

will return “12/1/99”,

@datestr(730088,"DD/mm/yyyy")

will return “01/12/1999”, and

@datestr(730088,"Month dd, yyyy")

will return “December 1, 1999”, and

@datestr(730088,"w")

will produce the string “3”, representing the weekday number for December 1, 1999. See
“Date Numbers” on page 106 and “Date Formats” on page 106 for additional details.

Translating Ordinary Numbers into Date Numbers

While date information is most commonly held in the form of date strings or date numbers,
one will occasionally encounter data in which a date is encoded as a (non-EViews format)
numeric value or values. For example, the first quarter of 1991 may be given the numeric
representation of 1991.1, or the date “August 15, 2001” may be held in the single number
8152001, or in three numeric values 8, 15, and 2001.

The @makedate function is used to translate ordinary numbers into date numbers. It is sim-
ilar to @dateval but is designed for cases in which your dates are encoded in one or more
numeric values instead of date strings:
• @makedate(arg1[, arg2[,arg3]], fmt): takes the numeric values given by the argu-
ments arg1, and optionally, arg2, etc. and returns a date number using the required
format string, fmt. Only a subset of all date formats are supported by @makedate.
If more than one argument is provided, the arguments must be listed from the lowest
frequency to the highest, with the first field representing either the year or the hour.
See @makedate (p. 960).

The simplest form of @makedate involves converting a single number into a date or a time.
The following are the supported formats for converting a single number into a date value:
• “yy” or “yyyy”: two or four-digit years.
• “yys” or “yyyys”: year*10 + half-year.
• “yy.s” or “yyyy.s”: year + half-year/10.
• “yyq” or “yyyyq”: year*10 + quarter.
• “yy.q” or “yyyy.q”: year + quarter/10.
• “yymm” or “yyyymm”: year*10 + month.
• “yy.mm” or “yyyy.mm”: year + month/10.
• “yyddd” or “yyyyddd”: year*1000 + day in year.
 Dates—117

• “yy.ddd” or “yyyy.ddd”: year + day in year/1000.

• “yymmdd” or “yyyymmdd”: year*10000 + month*100 + day in month.
• “mmddyy”: month*10000 + day in month*100 + two-digit year.
• “mmddyyyy”: month*100000 + day in month*10000 + four-digit year.
• “ddmmyy”: day in month*10000 + month*100 + two-digit year.
• “ddmmyyyy”: day in month*1000000 + month*10000 + four-digit year.

The following formats are supported for converting a single number into intraday values:
• “hh”: hour in day (in 24 hour units)
• “hhmi”: hour*100 + minute.
• “hhmiss”: hour*10000 + minute*100 + seconds.

Note that the @makedate format strings are not case sensitive, since the function requires
that all non-leading fields must have leading zeros where appropriate. For example, when
using the format “YYYYMMDD”, the date March 1, 1992 must be encoded as 19920301, and
not 199231, 1992031, or 1992301.

Let us consider some specific examples of @makedate conversion of a single number. You
may convert a numeric value for the year into a date number using a format string to
describe the year. The expressions:
@makedate(1999, "yyyy")
@makedate(99, "yy")

both return the date number 729754.0 corresponding to 12 midnight on January 1, 1999.
Similarly, you may convert a numeric value into the number of hours in a day using expres-
sions of the form,
@makedate(12, "hh")

Here, EViews will return the date value 0.5 corresponding to 12 noon on January 1, A.D. 1.
While this particular date value is not intrinsically of interest, it may be combined with
other date values to obtain the value for a specific hour in a particular day. For example
using date arithmetic, we may add the 0.5 to the 729754.0 value (12 midnight, January 1,
1999) obtained above, yielding the date value for 12 noon on January 1, 1999. We consider
these sorts of operations in greater detail in “Manipulating Date Numbers” on page 119.

If your number contains “packed” date information, you may interpret the various compo-
nents using @makedate with an appropriate format string. For example,
@makedate(199003, "yyyymm")
@makedate(1990.3, "yyyy.mm")
@makedate(1031990, "ddmmyyyy")
118—Chapter 5.Dates

@makedate(30190, "mmddyy")

all return the value 726526.0, representing March 1, 1990.

Cases where @makedate is used to convert more than one argument into a date or time are
more limited and slightly more complex. The arguments must be listed from the lowest fre-
quency to the highest, with the first field representing either the year or the hour, and the
remaining fields representing sub-periods. The valid date format strings for the multiple
argument @makedate are a subset of the date format strings, with components applied
sequentially to the numeric arguments:
• “yy s” or “yyyy s”: two or four-digit year and half-year.
• “yy q” or “yyyy q”: year and quarter.
• “yy mm” or “yyyy mm”: year and month.
• “yy ddd” or “yyyy ddd”: year and day in year.
• “yy mm dd” or “yyyy mm dd”: year, month, and day in month.

Similarly, the valid formats for converting multiple numeric values into a time are:
• “hh mi”: hour*100 + minute.
• “hh mi ss”: hour*10000 + minutes*100 + seconds.

For convenience, the non-space-delimited forms of these format strings are also supported
(e.g., “yymm”, and “hhmi”).

For example, the expressions,

@makedate(97, 12, 3, "yy mm dd")
@makedate(1997, 12, 3, "yyyymmdd")

will return the value 729360.0 corresponding to midnight on December 3, 1997. You may
provide a subset of this information so that
@makedate(97, 12, "yymm")

returns the value 729358.0 representing the earliest date and time in December of 1997 (12
midnight, December 1, 1997). Likewise,
@makedate(1997, 37, "yyyy ddd")

yields the value 729060.0 (February 6, 1997, the 37th day of the year) and
@makedate(14, 25, 10, "hh mi ss")

returns the value 0.600810185 corresponding to 2:25:10 pm on January 1, A.D. 1.

 Dates—119

It is worth pointing out that in the examples above, the numeric arguments are entered from
lowest frequency to high, as required. The following example, in which days appear before
months and years, is not a legal specification
@makedate(7, 10, 98, "dd mm yy")

and will generate an error reporting a “Bad date format”.

Lastly, we note that limitations on the date formats supported by @makedate imply that in
some cases, you are better off working with strings and the @dateval function. In cases,
where @makedate does not support a desired conversion, you should consider converting
your numbers into strings, performing string concatenation, and then using the richer set of
@dateval conversions to obtain the desired date values.

Manipulating Date Numbers

One of the most important reasons for holding your date information in the form of date
numbers is so that you may perform sophisticated calendar operations.

Date Operators
Since date values are simply double precision numbers, you may perform standard mathe-
matical operations using these values. While many operations such as division and multipli-
cation do not preserve the notion of a date number, you may find addition and subtraction
and relational comparison of date values to be useful tools.

If, for example, you add 7 to a valid date number, you get a value corresponding to the same
time exactly seven days later. Adding 0.25 adds one-quarter of a day (6 hours) to the current
time. Likewise, subtracting 1 gives the previous day, while subtracting 0.5 gives the date
value 12 hours earlier. Taking the difference between two date values yields the number of
days between the two values.

While using the addition and subtraction operators is valid, we strongly encourage you to
use the EViews specialized date functions since they allow you to perform arithmetic at var-
ious frequencies (other than days), while taking account of irregularities in the calendar (see
“Functions for Manipulating Dates” on page 120).

Similarly, while you may round a date number down to the nearest integer to obtain the first
instance in the day, or you may round down to a given precision to find the first instance in
a month, quarter or year, the built-in functions provide a set of simple, yet powerful tools for
working with dates.

Note further that all of the relational operators are valid for comparing date numbers. Thus,
if two date numbers are equal, the “=”, “>=”, and “<=” relational operators all return a
1, while the “<>”, “>”, and “<” comparison operators return a 0. If two date numbers
are not equal, “<>” returns a 1 and “=” returns a 0. If the first date number is less than a
second date number, the corresponding first date precedes the second in calendar time.
120—Chapter 5.Dates

Functions for Manipulating Dates

EViews provides several functions for manipulating dates that take date numbers as input
and return numeric values that are also date numbers. These functions may be used when
you wish to find a new date value associated with a given date number, for example, a date
number 3 months before or 37 weeks after a given date and time.

The functions described below all take a time unit string as an argument. As the name sug-
gests, a time unit string is a character representation for a unit of time, such as a month or a
year. The valid time unit string values are: “A” or “Y” (annual), “S” (semi-annual), “Q”
(quarters), “MM” (months), “WW” (weeks), “DD” (days), “B” (business days), “HH”
(hours), “MI” (minutes), “SS” (seconds).

There are three primary functions for manipulating a date number:

• @dateadd(date1, offset[, u]): returns the date number given by date1 offset by offset
time units as specified by the time unit string u. If no time unit is specified, EViews
will use the workfile regular frequency, if available.
Suppose that the value of date1 is 730088.0 (midnight, December 1, 1999). Then we
can add and subtract 10 days from the date by using the functions
@dateadd(730088.0, 10, "dd")
@dateadd(730088.0, -10, "dd")
which return 730098.0 (December 11, 1999) and (730078.0) (November 21, 1999).
Note that these results could have been obtained by taking the original numeric value
plus or minus 10.
The @dateadd function allows for date offsets specified in various units of time. For
example, to add 5 weeks to the existing date, simply specify “W” or “WW” as the
time unit string, as in
@dateadd(730088.0, 5, "ww")
which returns 730123.0 (January 5, 2000).
See @dateadd (p. 815).
• @datediff(date1, date2[, u]): returns the number of time units between date1 and
date2, as specified by the time unit string u. If no time unit is specified, EViews will
use the workfile regular frequency, if available.
Suppose that date1 is 730088.0 (December 1, 1999) and date2 is 729754.0 (January 1,
1999), then,
@datediff(730088.0, 729754.0, "dd")
returns 334 for the number of days between the two dates. Note that this is result is
simply the difference between the two numbers.
 Dates—121

The @datediff function is more powerful in that it allows us to calculate differences

in various units of time. For example, the expressions
@datediff(730088.0, 729754.0, "mm")
@datediff(730088.0, 729754.0, "ww")
return 11 and 47 for the number of months and weeks between the dates.
See @datediff (p. 817).
• @datefloor(date1, u[, step]): finds the first possible date number in the given time
unit, as in the first possible date value in the current quarter, with an optional step
offset.
If step is omitted, the frequency will use a step of 1 so that by default, @datefloor
will find the beginning of the period defined by the time unit.
Suppose that date1 is 730110.5 (12 noon, December 23, 1999). Then the @datefloor
values
@datefloor(730110.5, "dd")
@datefloor(730110.5, "mm")
yield 730110.0 (midnight, December 23, 1999) and 730088.0 (midnight, December 1,
1999), since those are the first possible date values in the current day and month.
Note that the first value is simply the integer portion of the original date number, but
that the latter required more complex analysis of the calendar.
Likewise, we can find the start of any corresponding period by using different time
units:
@datefloor(730098.5, "q")
@datefloor(730110.5, "y", 1)
returns 730027.0 (midnight, October 1, 1999), and 729754.0 (midnight, January 1,
1999. Notice that since the latter example used an offset value of 1, the result corre-
sponds to the first date value for the year 1999, which is the start of the year following
the actual value.
See @datefloor (p. 820).

Extracting Information from Date Numbers

Given a date number you may wish to extract numeric values associated with a portion of
the value. For example, you might wish to know the value of the month, the year, or the day
in the year associated with a given date value. EViews provides the @datepart function to
allow you to extract the desired information.
• @datepart(date1, u): returns a numeric part of a date value given by u, where u is a
time unit string.
122—Chapter 5.Dates

See @datepart (p. 823).

Consider the date1 date value 730110.5 (noon, December 23, 1999). The @datepart values
for
@datepart(730110.5, "dd")
@datepart(730110.5, "w")
@datepart(730110.5, "ww")
@datepart(730110.5, "mm")
@datepart(730110.5, "yy")

are 23 (day of the month), 1 (day in the week), 52 (week in the year), 12 (month in the
year), and 99 (year), respectively.

Note that the numeric values returned from @datepart are not themselves date values, but
may be used with @makedate to create date values.

Special Date Functions

In addition to the functions that convert strings or numbers into date values, EViews pro-
vides the following special ways to obtain one or more date values of interest.
• @now: returns the date number associated with the current time.

The remaining functions return information for each observation in the current workfile.
• @date: returns the date number corresponding to every observation in the current
workfile.
• @year: returns the four digit year in which the current observation begins. It is equiv-
alent to @datepart(@date, "YYYY")
• @quarter: returns the quarter of the year in which the current observation begins. It
is equivalent to @datepart(@date, "Q").
• @month: returns the month of the year in which the current observation begins. It is
equivalent to @datepart(@date, "MM").
• @day: returns the day of the month in which the current observation begins. It is
equivalent to @datepart(@date, "DD").
• @weekday: returns the day of the week in which the current observation begins,
where Monday is given the number 1 and Sunday is given the number 7. It is equiva-
lent to @datepart(@date, "W").
• @hour: returns the current observation hour as an integer. For example, 9:30AM
returns 9, and 5:15PM returns 17.
 Dates—123

• @minute: returns the current observation minute as an integer. For example, 9:30PM
returns 30.
• @second: returns the current observation second as an integer.
• @hourf: returns the current observation time as a floating point hour. For example,
9:30AM returns 9.5, and 5:15PM returns 17.25.
• @strdate(fmt): returns the set of workfile row dates as strings, using the date format
string fmt. See “Date Formats” on page 106 for a discussion of date format strings.

The @date function will generally be used to create a series containing the date value asso-
ciated with every observation, or as part of a series expression involving date manipulation.
For example:
series y = @date
series x = @dateadd(@date, 12, "ww")

which generates a series containing the date values for every observation, and the date val-
ues for every observation 12 weeks from the current values.

@strdate should be used when you wish to obtain the date string associated with every
observation in the workfile—for example, to be used as input to an alpha series. It is equiv-
alent to using the @datestr function on the date number associated with every observation
in the workfile.

Additional series functions involving dates may be listed in “Workfile Functions” on

page 696.

Free-format Conversion Formats

EViews supports the free-format conversion of a wide variety of date strings in which the
string is analyzed for the most likely corresponding date.

Any of the following date string types are allowed:

Day, month, year

• “"YYYY-MM-DD"” (IEEE, with the date enclosed in double quotes)
• “dd/mm/yy” (if American, “mm/dd/yy” instead)
• “dd/mm/yyyy” (if American, “mm/dd/yyyy” instead)
• “yyyy/mm/dd”
• “dd/mon/yy”
• “dd/mon/yyyy”
• “yyyy/mon/dd”
124—Chapter 5.Dates

• “ddmmyy” (if American, “mmddyy”)

• “ddmmyyyy” (if American, “mmddyyyy”)

The resulting date values correspond to the first instance in the day (12 midnight).

Month in year
• “mon/yy”
• “mon/yyyy”
• “yy/mon”
• “yyyy/mon”

The results are rounded to the first instance in the month (12 midnight of the first day of the
month).

Period in year
• “yyyy[S|Q|M|W|B|D|T|F|:]period”
• “yy[S|Q|M|W|B|D|T|F|:]period”

The date value is rounded to the first instance in the period in the year

Whole year
• “yyyy[A]”. The “A” is generally optional, but required if current WF is undated.
• “yy[A]”. The “A” is generally optional, but required if current WF is undated.

The date value is rounded to the first instance in the year (12 midnight on January 1).

Free-format Conversion Details

Note that the following conventions may be used in interpreting ambiguous free-form dates.

Dates and Date Intervals

A date in EViews is generally taken to represent a single point in calendar time. In some con-
texts, however, a date specification is used to refer to a range of values contained in a time,
which can be referred to as an interval.

When a date specification is treated as an interval, the precision with which the date is spec-
ified is used to determine the duration of the interval. For example, if a full day specification
is provided, such as “Oct 11 1980”, then the interval is taken to run from midnight at the
beginning of the day to just before midnight at the end of the day. If only a year is specified,
such as “1963”, then the interval is taken to run from midnight on the 1st of January of the
year to just before midnight on the 31st of December at the end of the year.
 Dates—125

An example where this is used is in setting the sample for a workfile. In this context, pairs of
dates are provided to specify which observations in the workfile should be included in the
sample. The pairs of dates are provided are processed as intervals, and the sample is defined
to run from the start of the first interval to the end of the second interval. As an example, if
the sample “1980q2 1980q2” is specified for a daily file, the sample will include all observa-
tions from April 1st 1980 to June 30th 1980 inclusive.

Incomplete Date Numbers

An EViews date number can be used to represent both a particular calendar day, and a par-
ticular time of day within that day. If no time of day is specified, the time of day is set to
midnight at the beginning of the day.

When no date is specified, the day portion of a date is effectively set to 1st Jan A.D. 1. For
example, the date string “12 p.m.” will be translated to the date value 0.5 representing 12
noon on January 1, A.D. 1. While this particular date value is probably not of intrinsic inter-
est, it may be combined with other information to obtain meaningful values. See “Manipu-
lating Date Numbers” on page 119

Two-digit Years
In general, EViews interprets years containing only two digits as belonging to either the
twentieth or twenty-first centuries, depending on the value of the year. If the two digit year
is greater than or equal to 30, the year is assumed to be from the twentieth century and a
century prefix of “19” is added to form a four digit year. If the number is less than 30, the
year is assumed to be from the twenty first century and a century prefix of “20” is added to
form a four digit year.

Note that if you wish to refer to a year after 2029 or a year before 1930, you must use the full
four-digit year identifier.

Because this conversion to four digit years is generally performed automatically, it is not
possible to specify years less than A.D. 100 using two digit notation. Should the need ever
arise to represent these dates, such two digit years can be input directly by specifying the
year as a four digit year with leading zeros. For example, the 3rd of April in the year A.D. 23
can be input as “April 3rd 0023”.

Implicit Period Notation

In implicit period notation (e.g., “1990:3”), the current workfile frequency is used to deter-
mine the period.

American vs. European dates

When performing a free-format conversion in the absence of contextual information suffi-
cient to identify whether data are provided in “mm/dd” or “dd/mm” format, the global
126—Chapter 5.Dates

workfile setting for the Options/Dates & Frequency Conversion.../Month/Day order in

dates (“Date Representation” on page 2552 of the User’s Guide I) will be used to determine
the ordering of the days and months in the string.

For example, the order of the months and years is ambiguous in the date pair:
1/3/91 7/5/95

so EViews will use the default date settings to determine the desired ordering. We caution
you, however, that using default settings to define the interpretation of date strings is not a
good idea since a given date string may be interpreted in different ways at different times if
your settings change. You may instead use the IEEE standard format, “YYYY-MM-DD” to
ensure consistent interpretation of your daily date strings. The presence of a dash in the for-
mat means that you must enclose the date in quotes for EViews to accept this format. For
example:
smpl "1991-01-03" "1995-07-05"

will always set the sample to run from January 3, 1991 and July 5, 1995.

Time of Day
Free-format dates can also contain optional trailing time of day information which must fol-
low the pattern:
hh[[[[[:mi:]ss].s]s]s][am|AM|pm|PM]

where “[]” encloses optional portions or the format and “|” indicates one of a number of
possibilities. In addition, either the “am” or “pm” field or an explicit minute field must be
provided for the input to be recognized as a time. An hour by itself is generally not suffi-
cient.

The time of day in an EViews date is accurate up to a particular millisecond within the day,
although any date can always be displayed at a lower precision. When displaying times at a
lower precision, the displayed times are always rounded down to the requested precision,
and never rounded up.

When both a day and a time of day are specified as part of a date, the two can generally be
provided one after the other with the two fields separated by one or more spaces. If, how-
ever, the date is being used in a context where EViews does not permit spaces between input
fields, a single letter “t” can also be used to separate the day and time so that the entire date
can be contained in a single word, e.g. “1990-Jan-03T09:53”.

Time Zones
There are a related set of functions that you may use that provide information on time-
zones: @localt (p. 946), @tz (p. 1155), @tzlist (p. 1155), @tzspec (p. 1156), and @utc
(p. 1173).
Dates—127
128—Chapter 5.Dates
Chapter 6. EViews Programming

EViews’ programming features allow you to create and store commands in programs that
automate repetitive tasks, or generate a record of your research project.

You may, for example, write a program containing commands that analyze the data from
one industry, and then have the program perform the analysis for a number of other indus-
tries. You can also create a program containing the commands that take you from the cre-
ation of a workfile and reading of raw data, through the calculation of your final results, and
construction of presentation graphs and tables.

The remainder of this chapter outlines the basics of EViews programming. If you have expe-
rience with computer programming and batch or macro processing, you will find most of the
features of the EViews language to be quite familiar. At the same time, non-programmers
should feel welcome to examine the material as you need not have any experience with pro-
gramming to take advantage of these powerful features.

Program Basics
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 win-
dow where you can type in the lines of the program. You may also open the program win-
dow 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, autow-
rap the text of the line. Autowrapping alters the appearance of the program line by display-
ing it on multiple lines, but does not change the contents of the line. While resizing the
130—Chapter 6.Program Basics

window will change the autowrap position, the text remains unchanged and is still con-
tained in a single line. You may turn off autowrapping in programs via Options/General
Options/Programs and deselecting the 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 _
y x c _
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 Uncom-
ment 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—131

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”.

If saving your program will overwrite an existing program file and you have instructed
EViews to make backup copies (“Programs,” on page 2554 of User’s Guide I), 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 “~”.

Snapshots for Programs

Managing snapshots for an EViews program is similar to workfiles (“Snapshot Backups,” on
page 67). The program window has a Snapshot button to perform a manual snapshot.

Viewing Snapshots for Programs

To view available snapshots for a program, right-click in the program window and select
Snapshots…
132—Chapter 6.Program Basics

Clicking on a previous snapshot will display a text compare view that highlights any differ-
ences between the two versions.

You can also right-click any snapshot and select Open… (or simply double-click the node)
to open the snapshot in its own program window.

Note that automatic snapshots are suspended when an EViews program is actively running.
 Program Basics—133

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 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 pro-
gram 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:
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.
134—Chapter 6.Program Basics

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 pro-
gram file, we say that you are in (non-interactive) 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.

The Run Program Dialog

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” on
page 2554 of User’s Guide I), but may be
overridden on a one-time 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.

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” on page 155 of User’s
Guide I 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 termi-
nate 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 max-
imum number of errors is reached. If it encounters a serious error that makes it impossible
 Program Basics—135

to continue, EViews will halt the program even if the maximum number of errors is not
reached. See “Execution Errors” on page 165.

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 expres-
sions. 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 Compati-
bility Notes” on page 188 and “Program Modes” on page 151 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 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 specifica-
tion and any arguments (see run (p. 581)).

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.

The default run options will be taken from the global settings (“Programs” on page 2554 of
User’s Guide I), but may be overridden using the command options. For example, you may
use the “v” or “verbose”options 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”
136—Chapter 6.Program Basics

statement in your program. See “Version 4 Compatibility Notes” on page 188 and “Program
Modes” on page 151 for additional discussion.

You may provide a list of program arguments after the name of the program. These argu-
ments will be passed on to the program as %0, %1 etc. See “Program Arguments” on
page 155 for more details.

Program options may be passed on to the program by entering them, surrounded by paren-
thesis immediately after the name of the program. See “Program Options” on page 156 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 argu-
ments. 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 pro-
gram 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” on page 167.

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 pro-
grammatically. See “EViews COM Automation Server” on page 195 and the EViews COM
Automation Server whitepaper, available from our website www.eviews.com/download/
download.html, for additional discussion.

Stopping a Program
Pressing the ESC or F1 keys halts execution of a program. It may take a few seconds for
EViews to respond to the halt command.

Programs will also stop when they encounter a stop command, when they reach the maxi-
mum number of errors, when they encounter a non-recoverable error in a program state-
ment, or when they finish processing a file that has been executed via a run statement.

If you include the exit keyword in your program, the EViews application will close.
 Program Basics—137

Running Part of a Program

You may choose to only run part of your program by highlight the lines you wish to run,
then right-clicking and selecting Run Selected. EViews will then execute only the selected
line of code as a new program.

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 pro-
gram variables (“Program Variables” on page 143) declared outside of the selected lines may
not be initialized 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.

Program Debugging
EViews offers tools for debugging to help you locate the source of problems. These tools
allow you to run programs until they hit breakpoints on specific lines and then examine the
state of your workfile at those breakpoints.

Setting and Clearing Breakpoints

Open the EViews program file and set the breakpoint by clicking to the left of the desired
line. A red dot will appear:
138—Chapter 6.Program Basics

Clicking on a red dot clears that breakpoint.

Starting a Debugging Session

To begin debugging the program, click the Debug button in the toolbar and enter any pro-
gram arguments, choose whether to Log dependencies, and if desired change the Maxi-
mum errors before halting. Click on OK.

EViews will start program execution and open the debugging pane. There are three tabs in
the pane: Breakpoints, Watch, and Callstack.

Stopping at a Breakpoint
When the program reaches an active breakpoint, the execution will pause at the red dot,
now highlighted in yellow:
 Program Basics—139

At this point you can look at the Breakpoints, Callstack, or Watch windows for more infor-
mation.
• Breakpoints shows all defined breakpoints. Toggling the checkbox next to a break-
point name inactivates or reactivates it.
• Callstack displays the current line of the active files and subroutines of the program.
• Watch presents the values of program and replacement variables.

Additionally, you may open EViews objects such as series or equations to examine their cur-
rent states.

Button Bar
Resume continues program execution until the next breakpoint is reached. Step executes
the current line. Run continues program execution to completion, ignoring any remaining
breakpoints. Stop cancels program execution.

Restrictions during Debugging

During a debugging session, you will not be able to close any windows opened by the pro-
gram since this could negatively affect its execution.

Program Dependency Logging

EViews 14 has a new feature to automatically log a program’s external dependencies: files
(as workfiles, Excel files, CSV files, etc), databases, and other programs (as includes and
execs). To use it, check the Log Dependencies checkbox in the Run Program dialog:
140—Chapter 6.Program Basics

A new Program Dependencies window will appear showing the type, filename, and path of
all the external dependencies detected during the run.
 Simple Programs—141

The above image shows the dependence on the external program files “xy.prg,” “wz.prg,”
and “z22.prg,” the workfiles “tq.wf1” and “untitled.wf1,” and the database “dbtest.edb,”
along with the line numbers producing these dependencies.

Simple Programs
The simplest program is just a list of EViews commands. Execution of the program is equiv-
alent to typing the commands one-by-one into the command window.

While you may execute the commands by typing them in the command window, you could
just as easily open a program window, type in the commands and click on the Run button.
Entering commands in this way has the advantage that you can save the set of commands
for later use, and execute the program repeatedly, making minor modifications each time.
(Note that you may combine the two methods by entering the commands in the command
window and then save them to a file as described in “Saving the Command Window” on
page 133.)

Since an EViews program is a collection of commands, familiarity with the EViews com-
mand 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
Chapter 17. “Command Reference,” beginning on page 357.
• 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-inte-
gration 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 Chapter 1. “Object View and Proce-
dure Reference,” beginning on page 3, where they are listed by object type.
• Functions may be used to create new data, either in the form of workfile objects or as
program variables.
Creating a new series that is equal to the moving 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.
Documentation for @-functions available can be found in Chapter 18. “Function Ref-
erence,” on page 679, with topical summary listings provided in Chapter 14. “String
142—Chapter 6.Simple Programs

and Date Summary,” on page 331, Chapter 15. “Matrix Language Summary,” on
page 335, and Chapter 16. “Programming Language Summary,” on page 343
• 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.
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 obser-
vation number) of the last non-NA value in the series SER01. The list of data members
available for each object is listed in the object’s section of Chapter 1. “Object View
and Procedure Reference,” on page 3.

Let’s examine a simple example (the data series are provided in the database PROGDEMO in
your EViews directory so that you can try out the program). Create a new program by typing
program myprog

in the command window. In the program window that opens for MYPROG, we are going to
enter the commands to create a workfile, fetch a series from an EViews database named
PROGDEMO, run a regression, compute residuals and a forecast, make a plot of the forecast,
and save the results.
' housing analysis
wfcreate(wf=myhouse) m 1968m3 1997m6
fetch progdemo::hsf
smpl 1968m5 1992m12
equation reg1.ls hsf c hsf(-1)
reg1.makeresid hsfres
smpl 1993m1 1997m6
reg1.forecast hsffit
freeze(hsfplot) hsffit.line
save

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 fore-
casts.
 Program Variables—143

You can run this program by clicking on Run and filling in the dialog box.

Now, suppose you wish to perform the same analysis, but for the S&P 500 stock price index
(FSPCOM). Edit the program, changing MYHOUSE to MYSP500, and change all of the refer-
ences of HSF to FSPCOM:
' s&p analysis
wfcreate(wf=mysp500) m 1968m3 1997m6
fetch progdemo::fspcom
smpl 1968m5 1992m12
equation reg1.ls fspcom c fspcom(-1)
reg1.makeresid fspcomres
smpl 1993m1 1997m6
reg1.forecast fspcomfit
freeze(fscomplot) fspcomfit.line
save

Click on Run to execute the new analysis. Click on the Save button to save your program file
as MYPROG.PRG in the EViews directory.

Since these two programs are almost identical, it seems inefficient to have two separate pro-
grams for performing the analysis. In “Program Arguments” on page 155 we describe a
method for performing these two forecasting problems using a single program. First how-
ever, we must define the notion of program variables that exist solely when running pro-
grams.

Program Variables
While you can use programs just to run, and re-run collections of EViews commands, the
real power of the EViews programming language comes from the use of program variables
and program control statements.

Program variables are variables that you may use in place of numeric or string values in
your EViews programs. Accordingly, there are two basic types of program variables: control
(numeric) variables and string variables.

In the remainder of this section we describe the use of these two types of program variables.

Control Variables
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.
144—Chapter 6.Program Variables

It is important to note that control variables do not exist outside of your program and are
automatically deleted after a program finishes. In this regard, control variables should not be
confused with scalar objects as the former are not saved when you save the workfile. You
can save the values of control variables by creating new EViews objects which contain the
values of the control variable.

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:
!x
!1
!counter

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:
!x = 7
!12345 = 0
!counter = 12
!pi = 3.14159

Once assigned a value, a control variable may appear in an expression. For example:
!counter = !counter + 1
genr dnorm = 1/sqr(2*!pi)*exp(-1/2*epsilon^2)
scalar stdx = x/sqr(!varx)
smpl 1950q1+!i 1960q4+!i

For example, the following commands:

scalar stdx = sqr(!varx)
c(100) = !length
sample years 1960+!z 1990

use the numeric values assigned to the control variables !VARX, !LENGTH, and !Z.

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.

A second unintended consequence of text substitution can arise when raising a negative
control variable to a power:
!a = -3
 Program Variables—145

!b = !a^2

When evaluating these lines, EViews will substitute the value of !A in the second line, leav-
ing the line:
!b = -3^2

Which it then evaluates as –9 (since the square operator takes precedence over the negation
operator), rather than the expected 9.

You should also take care to avoid inadvertent replacement of program variables, as outlined
in “Replacement Variables” on page 147.

String Variables
A string expression or string is text enclosed in double quotes:
"gross domestic product"
"3.14159"
"ar(1) ar(2) ma(1) ma(2)"

A string program variable is a program variable whose value is a string of text. String vari-
ables, which exist only during the time that your program is executing, have names that
begin with a “%” symbol. String variables should not be confused with “String Objects” on
page 101 which are objects that exist in a workfile.

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"
%dep = " hs"
%pi = " 3.14159"

You may use strings variables to help you build up command text, variable names, or other
string values. EViews provides a number of operators and functions for manipulating
strings; a complete list is provided in “Strings” on page 85.

Once assigned a value, a string variable may appear in any expression in place of the under-
lying string. When substituted for, the string variable will be replaced by the contents of the
string variable, enclosed in double quotes.

Here is a simple example where we use string operations to concatenate the contents of
three string variables.
!repeat = 500
%st1 = " draws from the normal"
146—Chapter 6.Program Variables

%st2 = "Cauchy "

%st3 = @str(!repeat) + @left(%st1,16) + %st2 + "distribution"

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
%st3 = "500" + " draws from the " + "Cauchy " + "distribution"

Similarly, the table assignment statement

table1(1,1) = %st3

is equivalent to entering the command

table(1,1) = "500 draws from the Cauchy distribution"

One important use for string variables is assigning string values to string objects, string vec-
tors, or Alpha series. For example, we may have the assignment statement
%z = "Ralph"
alpha full_name = %z + last_name

which is equivalent to the expression

alpha full_name = "Ralph" + last_name

We again emphasize that string variable substitution involves replacing the string variable
by its string value contents, enclosed in double quotes.

As with any string value, you may convert a string variable containing the text representa-
tion of a number into a number by using the @val function. For example,
%str = ".05"
!level = @val(%str)

creates a control variable !LEVEL=0.05. If the string cannot be evaluated to a number, @val
returns the value “NA”.

String variables are closely related to the concept of a string object (“String Objects,” on
page 101). A string object is an EViews workfile object that holds a string:
string a = "Hello World"
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.

In programming applications, string variables and string objects are sometimes defined
using string literal expressions as illustrated above. However, in most settings, string vari-
ables and objects are defined using results from string functions, or by manipulation of
string lists and string vectors. For example, you could use the @wlookup and @wsplit func-
 Program Variables—147

tions to obtain a set of strings corresponding to the names of all of the series in a workfile.
See “Strings,” on page 85 for a full discussion.

Replacement Variables
When working with EViews commands, you may wish to use a string variable, not simply to
refer to a string value, but as an indirect way of referring to something else, perhaps a com-
mand, or an object name, or portion of names for one or more items.

Suppose, for example, that we assign the string variable %X the value “GDP”:
%x = "gdp"

We may be interested, however, not in the actual string variable value “gdp”, but rather in
an EViews object named “GDP”. Accordingly, we require a method of distinguishing between
a string value and the item corresponding to the string value.

If you enclose a string variable in curly braces (“{ ” and “}”) EViews will replace the expres-
sion with the name, names, or name fragment given by the string value. In this context we
refer to the expression “{%X}” as a replacement variable since the string variable %X is
replaced in the command line by the name or names of objects to which the string refers.

Suppose we want to create the series Y and set it equal to the values in the series GDP.
Given the string variable %X defined above, the series declaration,
series y = %x

creates a numeric series Y and sets it equal to the string value “gdp”,
series y = "gdp"

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
series y = {%x}

is properly interpreted as
series y = gdp

Similarly, the program line using replacement variables,

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

would be interpreted by EViews as

equation eq1.ls gdp c gdp(-1)

Changing the contents of %X to “M1” changes the interpretation of the original program line
to
equation eq1.ls m1 c m1(-1)
148—Chapter 6.Program Variables

since the replacement variable uses the name obtained from the new value of %X.

To take another example, when trying to find the number of valid (non-missing) observa-
tions in a series named INCOME, you may use the @obs function along with the name of the
series:
@obs(income)

If you wish to use a string variable %VAR to refer to the INCOME series, you must use the
replacement variable in the @obs function, as in
%var = "income"
@obs({%var})

since you wish to refer indirectly to the object named in %VAR. Note that the expression
@obs(%var)

will return an error since @obs requires a series or matrix object name as an argument.

Any string variable may be used as the basis of a replacement variable. Simply form your
string using one or more string operations
%object = "group"
%space = " "
%reg1 = "gender"
%reg2 = "income"
%reg3 = "age"
%regs = %reg1 + %space + %reg2 + %space + %reg3

then enclose the string variable in braces. In the expression,

{%object} g1 {%regs}

EViews will substitute the names found in %OBJECT and %REGS so that the resulting com-
mand is
group g1 gender income age

It is worth noting that replacement variables may be used as building blocks to form object
names. For example, the commands
%b = "2"
%c = "temp"
series z{%b}
matrix(2, 2) x{%b}
vector(3) x_{%c}_y

declare a series named Z2, a 2  2 matrix named X2, and a vector named X_TEMP_Y.
 Program Variables—149

Up to this point, we have focused on replacement variables formed from string variables.
However, control variables may also be used to form replacement variables. For example,
the commands
!i = 1
series y{!i} = nrnd
!j = 0
series y{!j}{!i} = nrnd

are equivalent to
series y1 = nrnd
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 ambigu-
ity, 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.

While convenient, this loose interpretation of control variables can, however, lead to unex-
pected results if one is not careful. Take the following program:
!x1 = 10
series y = !x1

This program will create a series equal to the value of !X1 (i.e. 10). However if you were to
mis-type the program slightly:
!x = 10
series y = !x1

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 substituting !X into the
expression, and evaluating the result as 101.

Replacement variables may be constructed using nested evaluation of replacement variables.

Suppose we have the strings:
%str1 = "x"
%name = "%str1"

Then we can declare the series X and fill it with random normals using the command
series {{%name}} = nrnd

After evaluation of the innermost replacement variable, the expression reduces to

150—Chapter 6.Program Variables

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:

%x1 = "x"
%x2 = "y"
scalar x = 10
scalar y = 20
!y = 1
scalar r1 = {%x{!y}}
!y = 2
scalar r2 = {%x{!y}}

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 con-
struct 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.

Multiple sets of braces may be used to create various string names:

string uslabel = "USA"
string nzlabel = "New Zealand"
%a1 = "US"
%a2 = "NZ"
%b = "LABEL"
!y = 1
string label1 = {%a{!y}}{%b}
!y = 2
string label2 = {%a{!y}}{%b}

First we create two string objects, USLABEL and NZLABEL, which hold the label we wish to
assign to each country. Then we create the string variables %A1 and %A2 to hold the coun-
try abbreviations. When the control variable !Y=1, {%A{!Y}}{%B} evaluates to the object
USLABEL and when !Y=2, {%A{!Y}}{%B} evaluates to the object NZLABEL. Then the
string LABEL1 contains “USA” and LABEL2 contains “New Zealand”.
 Program Modes—151

Replacement variables may also be formed using string objects in place of string variables.
To use a string object as a replacement variable, simply surround it with curly braces (“{”
and “}”). For example,
string LAGGDP = "GDP(-1) GDP(-2) GDP(-4)"
equation eq1.ls GDP C {LAGGDP}

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 has finished, making it difficult to identify prob-
lems in their construction. Note that string objects do, however, go out-of-scope when the
active workfile page changes, while string variables are always in scope.

Lastly, while replacement variables provide you with great flexibility in referencing objects
in your programs, used carelessly, they can lead to confusion. We suggest, for example, that
you avoid using similar base names to refer to different objects. Consider the following pro-
gram:
' possibly confusing commands (avoid)
!a = 1
series x{!a}
!a = 2
matrix x{!a}

In this code snippet, it is easy to see that X1 is the series and X2 is the matrix. But in a more
complicated program, where the control variable assignment !A=1 may be separated from
the declaration by many program lines, it may be difficult to tell at a glance what kind of
object X1 represents. A better approach might be to use different names for different kinds
of variables:
!a = 1
series ser{!a}
!a = 2
matrix mat{!a}

so that the meaning of replacement variable names are more apparent from casual examina-
tion of the program.

Program Modes
Program modes describe different settings associated with the execution of your program.
You may, for example, choose to provide verbose messaging where your program will echo
152—Chapter 6.Program Modes

each command to the status line, or you may choose quiet mode. Alternately, you may wish
to run a legacy program file in Version 4 compatibility mode.

EViews provides you with the opportunity to set program execution modes at the time that
the program is first run. In addition, you may use the “MODE” statement to change the exe-
cution mode of a program from within the program itself. One important benefit to using
“MODE” statements is that the program can begin executing in one mode, and switch to a
second mode as the program executes.

To change the mode for quiet or verbose mode, simply add a line to your program reading
“MODE” followed by either the “QUIET” or the “VERBOSE” keyword, as in
mode quiet

For version 4 compatibility, you should use the keyword “VER4”:

mode ver4

as a line in the body of the program.

Multiple settings may be set in a single “MODE” line:

mode quiet ver4

and multiple mode statements may be specified in a program to change the mode as the pro-
gram runs:
mode quiet
[some program lines]
mode verbose
[additional program lines]
Note that setting the execution mode explicitly in a program overrides any settings specified
at the time the program is executed.

Program Message Logging

When executing a program in EViews, it may be useful to keep track of what is happening
during execution. Log windows allow you to determine more accurately the state of various
objects in your workfile or follow program progression.
 Program Modes—153

Log windows may be switched on using the logmode command.

The logmode command gives the ability to specify the name of the
log window and directs the messages to the window with the speci-
fied name. If no name is specified the messages are directed to a
window with the name of the program. If a program is executed
more than once and a log window has already been created, with no
name specified for the log, the log window will be cleared and all
subsequent messages will be sent to the existing log window. If you
wish to preserve a log, you may either select to append message,
save the log to a text file, or freeze it, which creates a text file object.
All of these actions can be accessed by the popup menu that appears
when right-clicking on a message log window.

The log windows appear as tabbed windows and can be rearranged

by the user. The logmode command has an option to have the log
window floating next to the program window.

There are several types of messages that can be logged: program lines, status line messages,
user log messages, and program errors. When displayed in a log message, each type will
appear in a different color, making it easier to differentiate one type from another. Program
lines are echoes of the line of code in the program currently being executed, and are dis-
played in black. Status line messages are the messages displayed in the status line and
154—Chapter 6.Program Modes

appear in blue. User log messages are custom messages created by the program via the
logmsg command and appear in green. Program errors are messages generated when a log-
ical or syntax error has occurred and appear in red.

Beginning with EViews 14, all program log windows appear as tabbed windows and may be
rearranged. Additionally, you have the ability to specify a name for the log window and
direct the messages to the log window with the specified name. If no name is specified, the
messages are directed to a window with the name of the program. This was the default
behavior in versions of EViews before EViews 10.

Logging Options
The Message settings dialog in the Programs section of the General Options dialog specifies
whether EViews runs programs in Verbose mode (the default), lists commands in the status
line as they are executed, or uses Quiet mode, which suppresses this information. EViews
will run faster in quiet mode since the status line display does not need to be updated.

This default may always be overridden from the Run Program dialog, or by using the option
"q" in the run statement, as in:
run(q) myprogram

In addition, you may modify the Logging settings to delete (Clear) or leave (Append) the
contents of the log window on program start.

See also the logmode (p. 506), logmsg (p. 509), logclose (p. 505), and logsave (p. 509)
commands, which all have additional options to specify the name of the log.
 Program Arguments—155

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 appropri-
ate. 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 argu-
ments. 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 argu-
ments 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 win-
dow, 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,
exec regress x x(-1) x(-2)

executes
equation eq1.ls y c time x x(-1) x(-2)

while the command,

156—Chapter 6.Program Options

exec 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 dupli-
cated by executing MYPROG with arguments:
exec myprog myhouse hsf

and
exec myprog mysp500 fspcom

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, @hasop-
tion("k") will return a value of 1 if the “k” option was passed into the program at run
time, or 0 if it was not.
 Control of Execution—157

@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.

For example, suppose you have the following program:

%filename = @equaloption("file")
wfcreate(wf={%filename}) m 1968m3 1997m6
fetch progdemo::{%0}
if (@hasoption("LS")=1) then
smpl 1968m5 1992m12
equation reg1.ls {%0} c {%0}(-1)
endif

If you were to run this program with:

run myprog(file=myhouse, ls) hsf

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, see “IF Statements” on page 157).

If we had run the program with just:

run myprog hsf

the workfile would not have been named (and would be given the default name of UNTI-
TLED), and the regression would not have been run.

Note that if your program name has spaces or illegal characters, it must be enclosed within
quotes in run or exec commands. In this case, program options should be included after
the closing quote without a space. For example, if we were to name our above program as
MY PROG, then the correct method to issue options is:
run "my prog"(file=myhouse, ls) hsf

Control of Execution
EViews provides you with several ways to control the execution of commands in your pro-
grams. Controlling execution in your program means that you can execute commands selec-
tively or repeatedly under changing conditions. The tools for controlling execution will be
familiar from other computer languages.

IF Statements
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 con-
dition to be met and the commands to be executed.
158—Chapter 6.Control of Execution

An IF statement starts with the if keyword, followed by an expression for the condition,
and then the word then. You may use AND/OR statements in the condition, using parenthe-
ses to group parts of the statement as necessary.

All comparisons in the IF statement follow the rules outlined in “String Relational Opera-
tors” on page 87 and in “Numeric Relational Operators” on page 198 of User’s Guide I. Note
in particular that string comparisons are case-sensitive. You may perform caseless compari-
son using the @upper or @lower string functions as in
if (@lower(%x) = "abc") then

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

If the expression is true, all of the commands until the matching endif are executed. If the
expression is false, all of these commands are skipped. For example,
if !stand=1 or (!rescale=1 and !redo=1) then
series gnpstd = gnp/sqr(gvar)
series constd = cons/sqr(cvar)
endif
if !a>5 and !a<10 then
smpl 1950q1 1970q1+!a
endif

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 state-
ments. The indentation is added for program clarity and has no effect on the execution of
the program lines.

The expression to be tested may also take a numerical value. In this case, 0 and NA are
equivalent to false and any other non-zero value evaluates to true. For example,
if !scale then
series newage = age/!scale
endif

executes the series statement if !SCALE is a non-missing, non-zero value.

An IF statement may include a matching ELSE clause containing commands to be executed

if the condition is FALSE. If the condition is true, all of the commands up to the keyword
else will be executed. If the condition is FALSE, all of the commands between else and
endif will be executed. For example:
if !scale>0 then
series newage = age/!scale
 Control of Execution—159

else
series newage = age
endif

It is worth noting that this example performs a conditional recode in which the series NEW-
AGE is assigned using one expression if a condition is true, and a different expression other-
wise. EViews provides a built-in @recode function for performing this type of evaluation;
see @recode (p. 1068).

IF statements may also be applied to string variables:

if %0="CA" or %0="IN" then
series stateid = 1
else
if %0="MA" then
series stateid=2
else
if %0="IN" then
series stateid=3
endif
endif
endif

Note that the nesting of our comparisons does not cause any difficulties.

You should note when using the IF statement with series or matrix objects that the compari-
son is defined on the entire object and will evaluate to false unless every element of the ele-
ment-wise comparison is true. Thus, if X and Y are series, the IF statement
if x<>y then
[some program lines]
endif

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 (=, >, >=, <, <=, <>)” on page 296.

If you wish to operate on individual elements of a series on the basis of element-wise condi-
tions, you should use the @recode function or use smpl statements to set the observations
you wish to change. Element-wise operations on a vector or matrix should use comparisons
of individual element comparisons
160—Chapter 6.Control of Execution

if x(3)=7 then
x(3) = 2
endif

or the element-wise matrix functions (“Matrix Element” on page 340).

The FOR Loop

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 state-
ment. Any number of commands may appear between these two statements.

The syntax of the FOR statement differs depending upon whether it uses numerical variables
or string variables.

FOR Loops with Numerical Control Variables or Scalars

To repeat statements for different values of a control variable, you should follow the for key-
word by a control variable initialization, the word to, and then an ending value. After the
ending value you may include the word step followed by a number indicating an amount to
change the control variable each time the loop is executed. If you don’t include step, the
step is assumed to be 1. Consider, for example the loop:
for !j=1 to 10
series decile{!j} = (income<level{!j})
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 ten variables LEVEL1
through LEVEL10.

We may add the step keyword and value to the FOR loop to modify the step:
for !j=10 to 1 step -1
series rescale{!j}=original/!j
next

In this example, the step is -1, and !J is used as a replacement variable in naming the ten
constructed series RESCALE10 through RESCALE1 and as a control variable scalar divisor in
the series ORIGINAL.

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 vari-
able is incremented by step and EViews compares the new control variable value to the
limit. If the limit is exceeded, execution stops.
 Control of Execution—161

One important use of FOR loops with control variables is to change the workfile sample
using a smpl command. If you add a control variable to a date in a smpl command state-
ment, you will get a new date as many observations forward as the current value of the con-
trol variable. Here is a FOR loop that gradually increases the size of the sample and
estimates a recursive regression:
for !horizon=10 to 72
smpl 1970m1 1970m1+!horizon
equation eq{!horizon}.ls sales c orders
next

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

computes the cumulative sum of the elements in the vector VEC1 and saves it in the vector
CUMSUM1.

To access an individual element of a series, you will need to use the @elem function and
@otod to get the desired element
for !i=2 to !rows
cumsum1(!i) = @elem(ser1, @otod(!i))
next

The @otod function returns the date associated with the observation index (counting from
the beginning of the workfile), and the @elem function extracts the series element associ-
ated with a given date.

You may nest FOR loops to contain loops within loops. The entire inner FOR loop is exe-
cuted for each successive value of the outer FOR loop. For example:
matrix(25,10) xx
for !i=1 to 25
for !j=1 to 10
xx(!i,!j)=(!i-1)*10+!j
next
next
162—Chapter 6.Control of Execution

You should avoid changing the control variable within a FOR loop. Consider, for example,
the commands:
' potentially confusing loop (avoid doing this)
for !i=1 to 25
vector a!i
!i=!i+10
next

Here, both the FOR assignment and the assignment statement within the loop change the
value of the control variable !I. Loops of this type are difficult to follow and may produce
unintended results. If you find a specific need to change a control variable inside the loop,
you should consider using a WHILE loop (“The WHILE Loop” on page 164) as an alterna-
tive to the FOR loop.

You may execute FOR loops with scalars instead of control variables. However, you must
first declare the scalar, and you may not use the scalar as a replacement variable. For exam-
ple,
scalar i
scalar sum = 0
vector (10) x
for i=1 to 10
x(i) = i
sum = sum + i
next

In this example, the scalar objects I and SUM remain in the workfile after the program has
finished running, unless they are explicitly deleted. When using scalar objects as the looping
variable you should be careful that the scalar is always available white the FOR loop is
active. You should not, for example, delete the scalar or change the workfile page within the
FOR loop.

FOR Loops with String Variables and String Objects

To repeat statements for different values of a string variable, you may use the FOR loop to let
a string variable range over a list of string values. You should list the FOR keyword, followed
by the name of the string program variable, followed by the list of values. For example,
for %y gdp gnp ndp nnp
equation {%y}trend.ls {%y} c {%y}(-1) time
next

executes the commands

 Control of Execution—163

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

equation gnptrend.ls gnp c gnp(-1) time
equation ndptrend.ls ndp c ndp(-1) time
equation nnptrend.ls nnp c nnp(-1) time

You may include multiple string variables in the same FOR statement—EViews will process
the string values in sets. For example, we may define a loop with list three string variables:
for %1 %2 %3 1955q1 1960q4 early 1970q2 1980q3 mid 1975q4 1995q1
late
smpl %1 %2
equation {%3}eq.ls sales c orders
next

In this case, the elements of the list are taken in groups of three. The loop is executed three
times for the different sample pairs and equation names:
smpl 1955q1 1960q4
equation earlyeq.ls sales c orders
smpl 1970q2 1980q3
equation mideq.ls sales c orders
smpl 1975q4 1995q1
equation lateeq.ls sales c orders

Both string objects and replacement variables may be used to specify a list for use in loops,
by surrounding the object name or replacement variable with curly braces (“{ }”). For
example,
string dates = "1960m1 1960m12"
%label = "year1"
for %1 %2 %3 {dates} {%label}
smpl {%1} {%2}
equation {%3}eq.ls sales c orders
next

finds the three strings for the loop by taking two elements of the string list and one element
of the string variable:
smpl 1960m1 1960m12
equation year1eq.ls sales c orders

Note the difference between using a FOR loop with multiple string variables and using
nested FOR loops. In the multiple string variable case, all string variables are advanced at
the same time, while with nested loops, the inner variable is advanced over all choices, for
each value of the outer variable. For example:
164—Chapter 6.Control of Execution

!eqno = 1
for %1 1955q1 1960q4
for %2 1970q2 1980q3 1975q4
smpl %1 %2
'form equation name as eq1 through eq6
equation eq{!eqno}.ls sales c orders
!eqno=!eqno+1
next
next

Here, the equations are estimated over the samples 1955Q1–1970Q2 for EQ1, 1955Q1–
1980Q3 for EQ2, 1955Q1–1975Q4 for EQ3, 1960Q4–1970Q2 for EQ4, 1960Q4–1980Q3 for
EQ5, and 1960Q4–1975Q4 for EQ6.

Note that you may use the exitloop command to exit a FOR loop early. See “Exiting
Loops” on page 166.

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 com-
mands, but the WHILE loop provides greater flexibility in specifying the required conditions.

The WHILE loop begins with a while statement and ends with a wend statement. Any num-
ber of commands may appear between the two statements. WHILE loops can be nested.

The WHILE statement consists of the while keyword followed by an expression involving a
control variable or scalar object. The expression should have a logical (true/false) value or a
numerical value. In the latter case, zero is considered false and any non-zero value is consid-
ered true.

If the expression is true, the subsequent statements, up to the matching wend, will be exe-
cuted, and then the procedure is repeated. If the condition is false, EViews will skip the fol-
lowing commands and continue on with the rest of the program following the wend
statement. For example:
!val = 1
!a = 1
while !val<10000 and !a<10
smpl 1950q1 1970q1+!a
series inc{!val} = income/!val
!val = !val*10
 Control of Execution—165

!a = !a+1
wend

There are four parts to this WHILE loop. The first part is the initialization of the control vari-
ables used in the test condition. The second part is the WHILE statement which includes the
test. The third part is the statements updating the control variables. Finally the end of the
loop is marked by the word wend.

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.

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
(p. 162). Note that the equivalent WHILE loop provides a much clearer program:
!i = 1
while !i<=25
vector a{!i}
!i = !i + 11
wend

Note that you may use the exitloop command to exit a WHILE loop early. See “Exiting
Loops” on page 166.

Execution Errors
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” on page 133), or by using the set-
maxerrs (p. 588) command inside a program.

Handling Errors
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 proce-
dure generated errors, or you may wish to overwrite the default EViews error with one of
your own, using the seterr (p. 587) command.

EViews offers a number of different ways to test for and handle execution errors. For exam-
ple, the @lasterrstr (p. 942) command will return a string containing the previous line's
error. If the previous line of your program did not error, this string will be empty. Alterna-
tively you could use the @errorcount (p. 877) function to check the number of errors cur-
rently encountered before and after a program line has been executed.
166—Chapter 6.Control of Execution

For example, to test whether the estimation of an equation generated an error, you can com-
pare the number of errors before and after the command:
!old_count = @errorcount
equation eq1.ls y x c
!new_count = @errorcount
if !new_count > !old_count then
[various commands]
endif

Here, we perform a set of commands only if the estimation of equation EQ1 incremented the
error count.

For additional error handling functions, see “Support Commands” on page 343 and “Sup-
port Functions” on page 345.

Stopping Programs
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:
series test = (ser1<0)
if @sum(test) <> 0 then
stop
endif

Note that if SER1 contains missing values, the corresponding elements of TEST will also be
missing. But since the @sum function ignores missing values, the program does not halt for
SER1 that has missing values, as long as there is no negative value.

Exiting Loops
Sometimes, you do not wish to stop the entire program when a condition is satisfied; you
just wish to exit the current loop. The exitloop command will exit the current for or
while statement and continue running the program.

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:
!df = 9
for !lag = 11 to 1 step -1
 Multiple Program Files—167

!pval = 1 - @cchisq(lr{!lag},!df)
if !pval<=.05 then
exitloop
endif
next
scalar lag=!lag

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.

Multiple Program Files

When working with long programs, you may wish to organize your code using multiple
files. For example, 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 run-referenced file. Thus, a pro-
gram 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, some-
thing that is difficult to do using run, since the run command ends all program exe-
cution 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
168—Chapter 6.Subroutines

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 com-
mands 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.

Subroutines
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 sub-
routines 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
 Subroutines—169

endsub

where the keyword subroutine is followed only by the name of the routine. This subrou-
tine has no arguments so that it will behave identically every time it is used. It forms the
square of the existing series Z and stores it in the new series X.

You may use the return command to force EViews to exit from the subroutine at any time.
A common use of return is to exit from the subroutine if an unanticipated error is detected.
The following program exits the subroutine if Durbin’s h statistic (Greene, 2008, p. 646, or
Davidson and MacKinnon, 1993, p. 360) for testing serial correlation with a lagged depen-
dent variable cannot be computed:
subroutine durbin_h
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
if test<=0 then
return
endif
' 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 vari-
ables. 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
2
fx  x (6.1)

where f depends upon the argument x . The argument x is merely a place holder—it’s
there to define the function and it does not really stand for anything. Then, if you want to
evaluate the function at a particular numerical value, say 0.7839, you can write f  0.7839  .
If you want to evaluate the function at a different value, say 0.50123, you merely write
f  0.50123  . By defining the function, you save yourself from writing the full function
expression every time you wish to evaluate it for a different value.

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
170—Chapter 6.Subroutines

in parentheses. Each argument is specified by listing a type of EViews object, followed by

the name of the argument. For example:
subroutine power(series v, series y, scalar p)
v = y^p
endsub

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 sub-
routines.

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.
• To make the argument a workfile object, you should use a standard EViews object
name. The object should be referred to by the argument name inside the subroutine.

Obviously, you can mix the two approaches in the definition of any subroutine.

For example, the declaration

subroutine mysub(scalar !a, string %b)

uses program variable names, while

subroutine mysub(scalar a, string b)

uses object names. In the first case you should refer to “!A” and “%B” inside the subroutine;
in the latter case, you should refer to the objects named “A” and “B”.

If you define your subroutine using program variables, the subroutine will operate on them
as though they were any other program variable. The variables, which cannot go out-of-
scope, should be referred to using the “!” or “%” argument name inside the subroutine.

If you define your subroutine using object names, the subroutine will operate on those vari-
ables as though they were scalar or string objects. The variables, which may be deleted and
may go out-of-scope (if, for example, you change the workfile page), should be referred to
using the argument names as though they were scalar or string objects.

(We discuss in detail related issues in “Calling Subroutines,” beginning on page 171.)
 Subroutines—171

You should note that EViews makes no distinction between input or output arguments in a
subroutine. Each argument may be an input to the subroutine, an output from the subrou-
tine, or both (or neither!). There is no way to declare that some arguments are inputs and
some are outputs. There is no need to order the arguments in any particular order. However
we find it much easier to read subroutine code when we stick to a convention, such as list-
ing all output arguments prior to all input arguments (or vice versa).

Calling Subroutines
Once a subroutine is defined, you may execute the commands in the subroutine by using the
call keyword. call should be followed by the name of the subroutine, and a list of any
argument values you wish to use, enclosed in parentheses and separated by commas (with
no space after the subroutine name). If the subroutine takes arguments, the arguments must
be provided in the same order as in the declaration statement. Here is an example program
file that calls subroutines:
include powers
load mywork
fetch z gdp
series x
series gdp2
series gdp3
call z_square
call power(gdp2,gdp,2)
call power(gdp3,gdp,3)

The call of the Z_SQUARE subroutine fills the series X with the value of Z squared. Next, the
call to the POWER subroutine creates the series GDP2 which is GDP squared. The last call to
POWER creates the series GDP3 as the cube of GDP.

When calling your subroutine, bear in mind that:

• When the subroutine argument is a scalar, the subroutine may be called with a scalar
object, a control variable, a simple number (such as “10” or “15.3”), a matrix element
(such as “mat1(1,2)”) or a scalar expression (such as “!y+25”).
• Subroutines with a string argument may be called with a string object, a string pro-
gram variable, simple text (such as “hello”) or an element of an svector object.
• Subroutines that take matrix and vector arguments can be called with a matrix name,
and if not modified by the subroutine, may also take a matrix expression.
• All other arguments must be passed to the subroutine with an object name referring
to a single object of the correct type.
172—Chapter 6.Subroutines

In “Subroutine with Arguments” on page 169 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)

Then for scalar and string objects F and G, and program variables !X and %Y,
scalar f = 3
string g = "hello"
!x = 2
%y = "goodbye"

you may call the subroutine using any of the following commands:
call mysub(!x, %y)
call mysub(!x, g)
call mysub(f, %y)
call mysub(f, g)

Note that changes to the scalars A and B inside the subroutine will change the correspond-
ing program variable or object that you pass into the routine.

Similarly, you may define

subroutine mysub(scalar !a, string !b)

and use the same four call statements to execute the subroutine commands.

However the subroutine is called, bear in mind that behavior inside the subroutine is depen-
dent on whether the subroutine declaration is in terms of program variables or objects, not
on the variable type that is passed into the subroutine.

Subroutine Placement
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
endsub
' start of program execution
load mywork
fetch z
 Subroutines—173

call z_square

Execution of this program begins with the load statement; the subroutine definition is
skipped and is executed only at the last line when it is “called.”

Subroutine definitions must not overlap—after the subroutine keyword, there should be
an endsub before the next subroutine declaration. Subroutines may call each other, or
even call themselves.

Alternatively, you may place frequently used subroutines in a separate program file and use
an include statement to insert them at the beginning of your program. If, for example, you
put the subroutine lines in the file “Powers.PRG”, then you may put the line:
include powers

at the top of any other program that needs to call Z_SQUARE or POWER. You can use the
subroutines in these programs as though they were built-in parts of the EViews program-
ming language.

Global and Local Variables

Subroutines work with variables and objects that are either global or local.

Global variables refer either to objects which exist in the workfile when the subroutine is
called, and to objects that are created in the workfile by a subroutine. Global variables
remain in the workfile when the subroutine finishes.

A local variable is one that is defined within the subroutine. Local variables are deleted from
the workfile once a subroutine finishes. The program that calls the subroutine will not be
able to use a local variable since the local variable disappears once the subroutine finishes
and the original program continues.

Global Subroutines
By default, subroutines in EViews are global. Global subroutine may refer to any global
object that exists in the workfile at the time the subroutine is called. Thus, 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
global matrix that has been created by another subroutine, the current subroutine may use
the matrix Y.

The rules for variables in global subroutines are:

• All objects created by a global subroutine are global and will remain in the workfile
when the subroutine finishes.
• Global objects may be used and updated directly from within the subroutine. If, how-
ever, a global object has the same name as an argument in a subroutine, the variable
name will refer to the argument and not to the global variable.
174—Chapter 6.Subroutines

• The global objects corresponding to arguments may be used and updated by referring
to the arguments.

Here is a simple program that calls a global subroutine:

subroutine z_square
series x = z^2
endsub
load mywork
fetch z
call z_square

Z_SQUARE is a global subroutine which has access to the global series Z. The new global
series X contains the square of the series Z. Both X and Z remain in the workfile when
Z_SQUARE is finished.

If one of the arguments of the subroutine has the same name as a global variable, the argu-
ment name takes precedence so that any reference to the name in the subroutine will refer
to the argument, not to the global variable. For example:
subroutine sqseries(series z, string sername)
series {sername} = z^2
endsub
load mywork
fetch z
fetch y
call sqseries(y, "y2")

In this example, there is a series Z in the original workfile and Z is also an argument of the
subroutine. Calling SQSERIES with the argument set to Y tells EViews to use the series
passed-in via the argument Z instead of the global Z series. On completion of the routine,
the new series Y2 will contain the square of the series Y, not the square of the series Z. Since
keeping track of variables can become confusing when subroutine arguments take the same
name as existing workfile objects, we encourage you to name subroutine arguments as
clearly and distinctly as possible.

Global subroutines may call global subroutines. You should make certain to pass along
required arguments when you call a subroutine from within a subroutine. For example,
subroutine wgtols(series y, series wt)
equation eq1
call ols(eq1, y)
equation eq2
 Subroutines—175

series temp = y/sqr(wt)

call ols(eq2, temp)
delete temp
endsub
subroutine ols(equation eq, series y)
eq.ls y c y(-1) y(-1)^2 y(-1)^3
endsub

can be run by the program:

load mywork
fetch cpi
fetch cs
call wgtols(cs,cpi)

In this example, the subroutine WGTOLS must explicitly pass along arguments to the sub-
routine OLS so that it uses the correct series and equation objects.

You cannot use a subroutine to change the object type of a global variable. Suppose that we
wish to declare new matrices X and Y by using a subroutine NEWXY. 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
matrix(2,2) x = 0
matrix(2,2) y = 0
endsub
load mywork
series x
call newxy

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.

Local Subroutines
If you include the word local in the definition of the subroutine, you create a local subrou-
tine. Local subroutines are most useful when you wish to write a subroutine which creates
many temporary objects that you do not want to keep.

The rules for variables in local subroutines are:

176—Chapter 6.Subroutines

• All objects created by a local subroutine will be local and will be removed from the
workfile upon exit from the subroutine.
• The global objects corresponding to subroutine arguments may be used and updated
in the subroutine by referring to the arguments.
• You may not use or update global objects that do not correspond to subroutine argu-
ments.

There is one exception to the general inaccessibility of non-argument global variables in

local subroutines. When a global group is passed as an argument to a local subroutine, all of
the series in the group are accessible to the local routine.

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 passed into the subroutine using a series argument.
Conversely, if X is passed into the subroutine, it may be modified.

Since locally created objects will vanish upon completion of the subroutine, to save results
from a local subroutine, you have to include them as arguments. For example, consider the
subroutine:
subroutine local ols_local(series y, series res, scalar ssr)
equation temp_eq.ls y c y(-1) y(-1)^2 y(-1)^3
temp_eq.makeresid res
ssr = temp_eq.@ssr
scalar se = ssr/temp_eq.@df
endsub

This local subroutine takes the series Y as input and modifies the argument series RES and
argument scalar SSR as output. Note that since Y, RES, and SSR are the only arguments of
this local subroutine, the only global variables that may be used or modified are those asso-
ciated with these arguments.The equation object TEMP_EQ and the scalar SE are local to the
subroutine and will vanish when the subroutine finishes.

Here is an example program that calls this local subroutine:

load mywork
fetch hsf
equation eq1.ls hsf c hsf(-1)
eq1.makeresid rres
scalar rssr = eq1.@ssr
series ures
scalar ussr
 Subroutines—177

call ols_local(hsf, ures, ussr)

Note that we first declare the series URES and scalar USSR before calling the local subrou-
tine. These objects are global since they are declared outside the local subroutine. Since we
call the local subroutine by passing these global objects as arguments, the subroutine can
use and update these global variables.

Object commands that require access to global variables should be used with care in local
subroutines since that the lack of access to global variables can create problems for views or
procs of objects passed into the routine. For example, a subroutine of the form:
subroutine local bg(equation eq)
eq.hettest z c
endsub

will fail because the hettest equation proc requires access to the original variables in the
equation and the global variable Z, and these series are not available since they are not
passed in as arguments to the subroutine.

Care should also be taken when using samples and local subroutines. If the workfile sample
is based upon a series in the workfile (for example “smpl @all if x>0”), most procedures
inside the local subroutine will fail unless all of the series used in the sample are passed into
the subroutine.

Local Samples
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 use-
ful 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

makes a copy of the existing sample specification. You may then change the sample as many
times as desired using the smpl statement, and the original sample specification will be
reapplied when existing from the subroutine.

You may use the global smpl statement to indicate that subsequent smpl statements will
result in permanent changes to the workfile sample. Thus, the commands:
global smpl
smpl 5 100

in a subroutine permanently change the sample.

178—Chapter 6.User-Defined Dialogs

For example, consider the following program snippet which illustrates the behavior of local
and global samples:
workfile temp u 100
call foo
subroutine foo
smpl 2 100
local smpl
smpl 10 100
endsub

Here, we create a workfile with 100 observations and an initial workfile sample of “1 100”,
then call the subroutine FOO. Inside FOO, the first smpl statement changes the workfile
sample to “2 100”. We then issue the local smpl statement which backs up the existing
sample and identifies subsequent sample changes as local. The subsequent change to the
“10 100” sample is local so that when the subroutine exits, the sample is reset to “2 100”.

If instead we define FOO to be

subroutine foo
smpl 2 100
local smpl
smpl 10 100
global smpl
smpl 5 100
local smpl
smpl 50 100
endsub

As before, first smpl statement changes the workfile sample to “2 100” and the local smpl
statement and following smpl statement set the local sample to “10 100”. The global smpl
indicates that subsequent sample statements will once again be global so the next line per-
manently changes the workfile sample to “5 100”. Note that the last local smpl and subse-
quent smpl statement change the local sample only. When we exit the subroutine the
sample will be set to the last global sample of “5 100”.

User-Defined Dialogs
EViews offers the ability to construct several types of user-interface controls, or dialogs,
within your program. These dialogs permit users to input variables or set options during the
running of the program, and allow you to pass information back to users.

There are five different functions that create dialogs in EViews:

 User-Defined Dialogs—179

• @uiprompt (p. 1166) – creates a prompt control, which displays a message to the
user.
• @uiedit (p. 1162) – creates an edit control, which lets users input text.
• @uilist (p. 1164) – creates a list control, which lets users select from a list of
choices.
• @uiradio (p. 1168) – creates a set of radio controls, which lets users select from a set
of choices.
• @uidialog (p. 1159) – creates a dialog which contains a mixture of other controls.
• @uifiledlg (p. 1163) – creates a open/save-style dialog to obtain the name of a file.

Each dialog function returns an integer indicating how the user exited the dialog:

User Selection Return Value

Cancel -1
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 with whatever settings the user has chosen. If “OK” is 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.
• if type is equal to “O”, or is omitted completely, then the dialog will only have an
“OK” button. This type of prompt dialog would typically be used to provide a message
to the user.
• if type is equal to “OC”, then the dialog will have an “OK” button and a “Cancel” but-
ton. This type of prompt dialog would be used to pass a message onto the user and let
them continue or cancel from the procedure.
180—Chapter 6.User-Defined Dialogs

• if type is equal to “YN”, then the dialog will contain a “Yes” button and a “No” button
which can be used to ask the user a question requiring an affirmative or negative
response.
• if type is equal to “YNC” the dialog will have a “Yes” button, a “No” button and a
“Cancel” button.

For example, the command:

@uiprompt("Welcome to EViews")

will display a simple dialog box with a simple welcome

message and an “OK” button, while the command
@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 user response: Cancel (-1), OK (0), Yes
(1), No (2).

See @uiprompt (p. 1166) for additional detail.

@uiedit
The @uiedit(string IOString, string prompt, scalar maxEditLen) function provides an edit
control that lets the user enter text which is then stored in the string IOString. If IOString
contains text before the @uiedit function is called, the edit box will be initialized with that
text.

The string prompt is used to specify text to be displayed above the edit box, which may be
used to provide a message or instructions to the user.

maxEditLen is an option integer scalar that specifies the maximum length that IOString can
take. If the user tries to enter text longer than maxEditLen characters, the extra characters
will be truncated. By default maxEditLen is set to 32.

Both prompt and maxEditLen may be written in-line using string literals, but IOString must
be either a program variable or a string object in your workfile.

As an example,
 User-Defined Dialogs—181

%eqname = "eq_unemp"
scalar ret = @uiedit(%eqname, "Enter a name for your equation")
equation {%eqname} unemp c gdp gdp(-1)

will display the following dialog box and then create an equation object with a name equal
to whatever was entered for %EQNAME.

The return value of the control is determined by the user response: Cancel (-1) or OK (0).

See @uiedit (p. 1162) 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 the @uilist function, one that returns the user's selection as a string
IOString,
@uilist(string IOString, string prompt, string list)

and one that stores it as an integer IOScalar representing the position of the selection in the
list,
@uilist(scalar IOScalar, string prompt, string list)

The string prompt is used to specify text to be displayed above the list box, providing a mes-
sage or instructions to the user.

The string list is a space delimited list of items that will be displayed in the list box. To spec-
ify entries with spaces, you should enclose the entry in double-quotes using double-quote
escape characters.

Both prompt and list may be provided using in-line text, but IOString or IOScalar must be
either a program variable or an object in your workfile.

If the IO variable (IOString or IOScalar) is defined before the function is called, then the list
box control will have the item defined by the variable 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.

The following program lines provide the user with a choice of robust standard errors, and
then displays that choice on the statusline:
%choice = "White"
182—Chapter 6.User-Defined Dialogs

%list = "Default White HAC"

scalar ret = @uilist(%choice, "Standard Errors Choice", %list)
statusline %list

Note that the above program could also be run with the following lines:
!choice = 2
%list = "Default White HAC"
scalar ret = @uilist(!choice, "Standard Errors Choice", %list)
%choice = @word(%list,!choice)
statusline %choice

The return value of the control is determined by the user response: Cancel (-1) or OK (0).

See @uilist (p. 1164) for details.

@uimlist
This function is similar to @uilist in that it creates a list box dialog, with a difference being
that here multiple selections from the list may be made. The form of the @uimlist function
is:
@uimlist(vector IOVector, string prompt, string list)

The string prompt is used to specify text to be displayed above the list box, providing a mes-
sage or instructions to the user.

The string list is a space delimited list of items that will be displayed in the list box. To spec-
ify entries with spaces, you should enclose the entry in double-quotes using double-quote
escape characters.

Both prompt and list may be provided using in-line text, but IOString or IOScalar must be
either a program 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.

The following program lines provide the user with a choice of robust standard errors, and
then displays those choices on the statusline:
 User-Defined Dialogs—183

vector(1) choice = 2
%list = "Default White HAC"
scalar ret = @uimlist(choice, "Standard Errors Choice", %list)
statusline %list

See @uimlist (p. 1165) for details.

@uiradio
@uiradio(scalar IOScalar, string prompt, string list) is similar to @uilist in that it pro-
vides a dialog that lets the user select from a list of choices. However rather than selecting
an item from a list box, the user must select the desired item using radio buttons. The
@uiradio function will return the user's choice in IOScalar.

The string prompt should be used to specify a message or instructions to the user to be dis-
played above the set of radio buttons.

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 text, but IOScalar must be either a pro-
gram variable or an object in your workfile.

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 example from the @uilist function,
but this time use radio buttons:
!choice = 2
%list = "Default White HAC"
scalar ret = @uiradio(!choice, "Standard Errors Choice", %list)
%choice = @word(%list,!choice)
statusline %choice
184—Chapter 6.User-Defined Dialogs

The return value of the control is determined by the user response: Cancel (-1) or OK (0).

See @uiradio (p. 1168) for additional detail.

@uidialog
The @uidialog(control_spec1[, control_spec2, ….]) function displays a dialog which may be
composed of different controls, including simple text, edit boxes, list boxes, radio buttons
and check boxes. The dialog is specified using a list of control specifications passed into the
function as arguments. Each control specification is a type keyword specifying the type of
control, followed by a list of parameters for that control.

The type keywords should be from the following list:

Keyword Control
“caption” Dialog title
“text” Plain text
“edit” Edit box
“list” List box
“radio” Radio buttons
“check” Check box
“button” OK-type button
“buttonc” Cancel-type button
“colbreak” Column break
“setoc” Set OK/Cancel text

The “edit”, “list” and “radio” controls are similar to their individual dialog functions, and
the specifications for those controls follow the same pattern. Thus the specification for an
edit box would be (“edit”, string IOString, string prompt, scalar maxEditLen).

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, yield-
ing a specification of (“caption”, string caption).
 User-Defined Dialogs—185

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 “check box” control adds a check box to the dialog. The check keyword should be fol-
lowed by a scalar, IOScalar, which stores the selection of the check box - 1 for checked, and
0 for unchecked, and then by a string prompt which contains the text to be used as a
prompt/instructions for the check box. The specification for the check box control is then:
(“check”, scalar IOScalar, string prompt).

The “button” and “buttonc” controls add a custom button to the dialog. The dialog will
close after a button has been pressed. The behavior of the button will depend on the type of
button —buttons of type “button” will behave in the same way as the “OK” button (i.e., all
variables passed into the dialog will be updated to reflect changes made to their correspond-
ing controls). Buttons of type “buttonc” will behave in the same way as the “Cancel” button
(i.e., all variables will be reset to the values that were passed into the dialog).

The return value of the dialog will correspond to the order in which buttons are placed in
the dialog. If only one button (apart from the standard “OK” and “Cancel”) is included in
the dialog, the return value for that button will be “1”. If there is more than one button, then
the first button will return a value of “1”, the second will return a value of “2” and so on.
Note that the return value is independent of whether the button was of type “button” or
“buttonc”. The specification for the button controls is (“button[c]”, “text”) where text speci-
fies the text that will be on the button.

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.

“setoc” allows you to change the text of the “OK” and “Cancel” buttons on the dialog. You
should supply two words, separated by a space as the text for “OK” and “Cancel”.

As an example, a dialog that offers a choice of covariance matrix options, plus a check box
for degree of freedom adjustment, could be made with:
!choice = 2
!doDF = 1
%list = "Default White HAC"
scalar ret = @uidialog("caption", "Covariance Options", "list",
!choice, "Covariance method", %list, "check", !doDF, "DF-
adjust")
186—Chapter 6.User-Defined Dialogs

See @uidialog (p. 1159) for details.

@uifiledlg
The @uifiledlg(string IO_Filespec, string filter, string style) displays a standard Windows
file open or save dialog so that you may obtain the path and name of a file.

@uifiledlg function will return the user's specification in file_spec.

The string IO_Filespec should be used to specify an initial location and possibly the name for
the file. IO_Filespec will also contain the file specified on return.

The string filter is used to specify the types of files to show in the dialog using the filter argu-
ment, 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.

(Note that the clicking OK on the dialog does not actually open or save the selected file, it
merely returns the name of the selected file. Thus, specifying the type argument is for cos-
metic reasons only.)

Both filter and style may be specified using in-line text, but IO_Filespec must be either a pro-
gram variable or an object in your workfile.

The displayed dialog will display both an OK and a Cancel button, and will return an inte-
ger representing the button clicked: Cancel (-1), OK (0).
string myfile = "c:\temp\"
@uifiledlg(myfile, "prg”, "open")

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

string myfile = "c:\temp"
@uifiledlg(myfile, "prg", "save")
 User-Defined Dialogs—187

will instead display a save dialog that opens in the “c:\” folder with the filename initialized
to “temp.prg” (MYFILE does not have the trailing “\”).

See also @uifiledlg (p. 1163).

Example Program
This program creates a workfile and some series, then puts up dialogs asking the user to
specify the 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
'-------------------------------------
'variable to store name of dependent variable
%dep = ""
'variable to store list of regressors. Default is "c" for a con-
stant.
%regs = "c "
'variable that will track the result of dialogs. -1 indicates user
hit Cancel. 0 Indicates user hit OK.
!result = 0
'put up an Edit dialog asking for dependent variable.
!result = @uiedit(%dep,"Enter the dependent variable")
if !result=-1 then 'if user cancelled, then stop program
stop
endif
'put up an Edit dialog asking for regressors list.
!result = @uiedit(%regs,"Enter the list of regressors")
if !result=-1 then 'if user cancelled, then stop program
stop
endif

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 user’s entry for the dependent variable. To begin, we
set this equal to an empty string. %REGS is used to store the user’s entry for the list of
188—Chapter 6.Version 4 Compatibility Notes

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.

Following the declaration of the variables, the first dialog

is brought up using the @uiedit command. This will cre-
ate an Edit dialog asking the user to “Enter the dependent
variable.” The user’s response will be stored in %DEP. Fol-
lowing the dialog command, we check whether the value
of !RESULT is equal to -1. A -1 indicates that the user
pressed Cancel in the dialog. If this is the case, the program quits, using the stop com-
mand.

The second dialog command is similar to the first, but rather than asking for the dependent
variable, it asks the user to “Enter the list of regressors,” and stores that list in %REGS. Note
that since %REGS was set equal to “C” prior to the dialog being put up, the dialog will be
pre-filled with the constant term. Users can still delete the constant or add extra regressors.

Finally, having obtained entries for both %DEP and %REGS, equation EQ1 is estimated via
least squares with the specified variables.

Version 4 Compatibility Notes

While the underlying concepts behind strings, string variables, and replacement variables
have not changed since the first version of EViews, there were three important changes in
the implementation of these concepts introduced in EViews 5. In addition, there has been an
important change in the handling of boolean comparisons involving numeric NA values,
and blank string values.

String vs. Replacement Variables

First, the use of contextual information to distinguish between the use of string and replace-
ment variables has been eliminated.

Prior to EViews 5, the underlying notion that the expression “%X” refers exclusively to the
string variable %X while the expression “{%X}” refers to the corresponding replacement
variable was modified slightly to account for the context in which the expression was used.
In particular, the string variable expression “%X” was treated as a string variable in cases
where a string was expected, but was treated as a replacement variable in other settings.

For example, suppose that we have the string variables:

%y = "cons"
%x = "income"
 Version 4 Compatibility Notes—189

When used in settings where a string is expected, all versions of EViews treat %X and %Y
as string variables. Thus, in table assignment, the command,
table1(2, 3) = %x + " " + %y

is equivalent to the expression,

table1(2, 3) = "cons" + " " + "income"

However, when string variables were used in other settings, early versions of EViews used
the context to determine that the string variable should be treated as a replacement variable;
for example, the three commands
equation eq1.ls %y c %x
equation eq1.ls {%y} c {%x}
equation eq1.ls cons c income

were all viewed as equivalent. Strictly speaking, the first command should have generated
an error since string variable substitution would replace %Y with the double-quote delim-
ited string “cons” and %X with the string “income”, as in
equation eq1.ls "cons" c "income"

Instead, EViews determined that the only valid interpretation of %Y and %X in the first
command was as replacement variables so EViews simply substituted the names for %Y and
%X.

Similarly, the commands,

series %y = %x
series {%y} = {%x}
series cons = income

all yielded the same result, since %Y and %X were treated as replacement variables in the
first line, not as string variables.

The contextual interpretation of string variables was convenient since, as seen from the
examples above, it meant that users rarely needed to use braces around string variables. The
EViews 5 introduction of alphanumeric series meant, however, that the existing interpreta-
tion of string variables was no longer tenable. The following example clearly shows the
problem:
alpha parent = "mother"
%x = "parent"
alpha temp = %x

Note that in the final assignment statement, the command context alone is not sufficient to
determine whether %X should refer to the string variable value “parent” or to the replace-
ment variable PARENT, which is an Alpha series containing the string “mother”.
190—Chapter 6.Version 4 Compatibility Notes

Consequently, in EViews 5 and later, users must now always use the expression “{%X}” to
refer to the replacement variable corresponding to the value of %X. Thus, under the new
interpretation, the final line in the example above resolves to
alpha temp = "parent"

Under the EViews 4 interpretation of the final line, “%X” would have been treated as a
replacement variable so that TEMP would contain the value “mother”.

To interpret the last line as a replacement variable in EViews 5 and later, you must now
explicitly provide braces around the string variable
alpha temp = {%x}

to resolve to the command

alpha temp = parent

String Variables in String Expressions

The second major change in EViews 5 is that text in a string expression is now treated as a
literal string. The important implication of this rule is that string variable text is no longer
substituted for inside a string expression.

Consider the assignment statements

%b = "mom!"
%a = "hi %b"
table(1, 2) = %a

In EViews 4 and earlier, the “%B” text in the string expression was treated as a string vari-
able, not as literal text. Accordingly, the EViews 4 string variable %A contains the text “hi
mom!”. One consequence of this approach is that there was no way to get the literal text of
the form “%B” into a string using a program in EViews 4.

Beginning in EViews 5, the “%B” in the second string variable assignment is treated as lit-
eral text. The string variable %A will contain the text “hi %b”. Obtaining a %A that con-
tains the EViews 4 result is straightforward. Simply move the first string variable %B outside
of the string expression, and use the string concatenation operator:
%a = "hi " + %b

assigns the text “hi mom!” to the string variable %A. This expression yields identical results
in all versions of EViews.

Case-Sensitive String Comparison

In early versions of EViews, program statements could involve string comparisons. For
example, you might use an if-statement to compare a string variable to a specific value, or
you could use a string comparison to assign a boolean value to a cell in a matrix or to a
 Version 4 Compatibility Notes—191

numeric series. In all of these settings, the string comparisons were performed caselessly, so
that the string “Abc” was viewed as equal to “ABC” and “abc”.

The introduction of mixed case alpha series in EViews 5 meant that caseless string compari-
sons could no longer be supported. Accordingly, the behavior has been changed so that all
EViews 5 and later string comparisons are case-sensitive.

If you wish to perform caseless comparison in newer versions of EViews, you can use the
@upper or @lower string functions, as in
if (@lower(%x) = "abc") then

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

Alternately, programs may be run in version 4 compatibility mode to enable caseless com-
parisons for element operations (see “Version 4 Compatibility Mode” on page 192). For
example, the if-statement comparison:
if (%x = "abc") then

will be performed caselessly in compatibility mode.

Note that compatibility mode does not apply to string comparisons that assign values into
an entire EViews series. Thus, even in compatibility mode, the statement:
series y = (alphaser = "abc")

will be evaluated using case-sensitive comparisons for each value of ALPHASER.

Comparisons Involving NAs/Missing Values

Prior to EViews 5, NA values were always treated as ordinary values for purposes of
numeric equality (“=”) and inequality (“<>”) testing. In addition, when performing string
comparisons in earlier versions of EViews, empty strings were treated as ordinary blank
strings and not as a missing value. In these versions of EViews, the comparison operators
(“=” and “<>”) always returned a 0 or a 1.

In EViews 5 and later, the behavior of numeric and string inequality comparisons involving
NA values or blank strings has been changed so that comparisons involving two variables
propagate missing values. To support the earlier behavior, the @eqna and @neqna functions
are provided so that users may perform comparisons without propagating missing values.
Complete details on these rules are provided in “String Relational Operators” on page 87 of
the Command and Programming Reference and in “Numeric Relational Operators” on
page 198 of User’s Guide I.

Programs may be run in version 4 compatibility mode to enable the earlier behavior of com-
parisons for element operations. For example, the if-statement comparison:
192—Chapter 6.References

if (!x = !z) then

will not propagate NA values in compatibility mode.

Note that compatibility mode does not apply to comparisons that assign values into an
EViews numeric or alpha series. Thus, even in compatibility mode, the statement:
series y = (x = z)

will propagate NA values from either X or Z into Y.

Version 4 Compatibility Mode

While the changes to the handling of string variables and element boolean comparisons are
required for extending the programming language to handle the new features of the EViews
5 and later, we recognize that users may have a large library of existing programs which
make use of the previous behavior.

Accordingly, EViews provides a version 4 compatibility mode in which you may run EViews
programs using the previous context sensitive handling of string and substitution variables,
the earlier rules for resolving string variables in string expressions, and the rules for caseless
string comparison and propagation of missing values in element comparisons.

There are two ways to ensure that your program is run in version 4 compatibility mode.
First, you may specify version 4 compatibility mode at the time the program is run. Compat-
ibility may be set interactively from the Run Program dialog (“Executing a Program” on
page 133) by selecting the Version 4 compatible variable substitution and program bool-
ean comparisons checkbox, or in a program using the “ver4” option (see run (p. 581)).

Alternatively, you may include “MODE VER4” statement in your program. See “Program
Modes” on page 151 for details.

References
Davidson, Russell and James G. MacKinnon (1993). Estimation and Inference in Econometrics, Oxford:
Oxford University Press.
Greene, William H. (2008). Econometric Analysis, 6th Edition, Upper Saddle River, NJ: Prentice-Hall.
Chapter 7. External Connectivity

EViews offers several methods for interacting with external applications and data:
• The EViews OLEDB driver provides an easy-to-use interface for external programs to read
data stored in EViews workfiles (WF1) and EViews databases (EDB) (“The OLEDB Driver”
on page 194).
• The EViews Excel Add-in offers a simple interface for reading data stored in EViews work-
files and databases from within Microsoft Excel (“The Excel Add-in” on page 194).
• The EViews Database Objects (EDO) Library gives you the ability to access data objects
held inside EViews databases and workfiles from within an external application (“EViews
Database Objects (EDO) Library” on page 194).
• EViews offers COM Automation server support so that external programs or scripts can
launch or control EViews, transfer data, and execute EViews commands (“EViews COM
Automation Server” on page 195).
• EViews offers COM Automation client support for MATLAB, R, and Python application
servers so that EViews may be used to launch and control the application, transfer data,
and execute commands (“EViews COM Automation Client Support (MATLAB, R, Python)”
on page 195).
• EViews offers an EViews Database Extension (EDX) interface for developers who wish to
provide EViews access to their database formats. Any external data source that imple-
ments this interface can be opened directly from within EViews just like an EViews data-
base (“EViews Database Extension Interface” on page 203).
• EViews can be used as a Jupyter kernel. EViews code can be run and the results displayed
from within a Jupyter notebook, allowing users to take advantage of all its interactive and
easy-to-use research, analysis, presentation, and record-keeping features (“Jupyter Note-
book Support” on page 205).

Reading EViews Data

EViews offers a variety of ways for you to access data stored in EViews workfiles (WF1) and
EViews databases (EDB) from external sources.

The EViews OLEDB driver provides an easy way for OLEDB-aware clients or custom programs to
read EViews data

Alternatively, the EViews Microsoft Excel Add-in allows users to fetch and link to EViews data
located in workfiles and databases. The Add-in offers an easy-to-use interface to OLEDB for read-
ing EViews data from within Excel.
194—Chapter 7.Reading EViews Data

Lastly, you may use the EViews Database Objects Library to access EViews data from within
an external application.

The OLEDB Driver

The EViews OLEDB driver is automatically installed and registered on your computer when
you install EViews. Once installed, you may use OLEDB-aware clients or custom programs
to read series, vector, and matrix objects directly from EViews workfiles and databases.

See “The OLEDB Driver” on page 175 of User’s Guide I for discussion. For additional details,
see the Using the EViews OLEDB Driver whitepaper available from our website
www.eviews.com/download/download.html.

The Excel Add-in

The EViews Excel Add-in offers a simple interface for fetching and linking to data stored in
EViews workfiles and databases from within Microsoft Excel (2000 and later).

See “The Excel Add-in” on page 172 of User’s Guide I for discussion. For additional details,
see the Using the EViews OLEDB Driver whitepaper available from our website
www.eviews.com/download/download.html.

EViews Database Objects (EDO) Library

The EViews Database Objects (EDO) Library provides access to data objects held inside
EViews databases and workfiles from within an external application.

EDO library support is not available in EViews Standard Edition.

The library consists of a set of COM objects exported by EViews that can easily be used in a
variety of development environments such as Microsoft .NET and Visual Basic for Applica-
tions (VBA).

The EDO API provides full read and write access to EViews databases, as well as read-only
access to EViews workfiles. The interface provides access to both the observation values and
the attributes of an object. In contrast, the EViews OLEDB interface “The OLEDB Driver” on
page 194 offers data reading support but not write operations nor object attributes.

The EDO library supports reading and writing of the following EViews data objects:
• Numeric series (including series containing dates)
• Alpha series (containing character data)
• Scalars
• Vectors
• Matrices
 EViews COM Automation Client Support (MATLAB, R, Python)—195

• Strings
• String Vectors

The library does not currently support access to data within structured EViews objects such
as equations or models.

For additional details, see the EViews Data Objects Library whitepaper, available from our
website www.eviews.com/download/download.html.

EViews COM Automation Server

EViews may be used as a COM Automation server so that an external program or script may
launch and control EViews programmatically. EViews COM is comprised of two class
objects: Manager and Application.

The Manager class is used to manage and create instances of the main EViews Application
class. The Application class provides access to EViews functionality and data. Most notably,
the Application class Run and a variety of Get and Put methods provide you with access to
EViews commands and allow you to obtain read or write access to series, vectors, matrix,
and scalar objects.

You may, for example, use, the pyeviews package allows you to call EViews from Python.
See the whitepaper http://www.eviews.com/download/whitepapers/pyeviews.pdf for more
information about the pyeviews package.

For a complete description of these methods, please refer to the EViews COM Automation
Server whitepaper, available from our website www.eviews.com/download/download.html.

Note that web server access to EViews via COM is not allowed. Furthermore, EViews will
limit COM access to a single instance when run by other Windows services or run remotely
via Distributed COM.

EViews COM Automation Client Support (MATLAB, R, Python)

EViews offers COM Automation client support for select external application servers. Sup-
port is currently provided for three applications: MATLAB, R, and Python.

The client support includes a set of EViews functions for exporting EViews data to the exter-
nal application, running commands and programs in the application, and importing data
back into EViews. These functions provide easy access to the powerful programming lan-
guages of MATLAB, R, and Python to create programs and routines that perform tasks not
currently implemented in EViews. The interface also offers access to the large library of sta-
tistical routines already written in the MATLAB, R, and Python languages.
196—Chapter 7.EViews COM Automation Client Support (MATLAB, R, Python)

There are nine EViews commands that control the use of external applications: xclose
(p. 668), xget (p. 668), xlog (p. 671), xopen (p. 672), xput (p. 675), xon (p. 672), xoff
(p. 671), xpackage (p. 674), and xrun (p. 677).

xopen and xclose are used to open and close a connection to the external application
(MATLAB or R). xput and xget are used to send data to and from the external application.
xrun is used to send a command to the external application, and, finally, xlog lets you
show or hide an external application log window within EViews.

Using MATLAB®
To open a connection to MATLAB, simply use the xopen(type=m) command. EViews will
then attempt to launch MATLAB on your computer. Note, your computer must have access
to MATLAB, either through a local installation, or through a network. EViews has been
tested with MATLAB release R2008a, although other versions may work as well.

Once a connection to MATLAB has been made, xput (p. 675) may be used to pass data from
EViews over to MATLAB. All numerical data is passed to MATLAB as a matrix. String data
(in the form of an alpha series or svector) will be passed to a MATLAB char if each string
contains the same number of characters. Otherwise the string data will be passed as a cell
array. Series and group objects are always filtered by the current sample unless you specify
an explicit sample in the xput command.

Note that object names in EViews are not case sensitive. Unless otherwise specified, EViews
objects that are passed into MATLAB using xput will have the same name as the EViews
objects that are being pushed, with the case determined by the case established for the COM
connection (see xopen (p. 672)).

xrun can be used to issue a single line command to MATLAB. You may, for example, use
xrun to invert a matrix or run a program in MATLAB. If you wish to run multiple com-
mands, each command must be entered with a separate xrun command. Commands should
be surrounded in quotes.

xget can be used to fetch data from MATLAB into EViews. The “type=” option lets you
specify the type of object that will be created in EViews. If no option is specified, MATLAB
matrices will be brought in as EViews matrix objects, while chars and cell arrays will be
brought in as svectors. If you use “type=series” or “type=alpha” to specify that the data is
brought in as a series or an alpha series, EViews will create a series of workfile length, and
either truncate the data, or pad with NAs, if the incoming matrix does not have the same
number of rows as there are workfile observations.

The follow program offers a simple example using MATLAB to perform a least-squares
regression (more complicated operations may be performed by using xrun to run a MATLAB
program):
'create a workfile
 EViews COM Automation Client Support (MATLAB, R, Python)—197

wfcreate u 100
'create some data
series y=nrnd
series x1=nrnd
series x2=nrnd
'group regressor data into a group
group xs c x1 x2
'open a connection to Matlab with lower-case default output names
xopen(type=m, case=lower)
'put regressors and dependent variable into Matlab
xput xs
xput y
'run a command to perform least squares as a matrix operation
xrun "beta = inv(xs'*xs)*xs'*y"
'retrieve betas back into EViews
xget beta
'perform same least squares estimation in EViews
equation e1.ls y xs
show e1
show beta
'close Matlab connection
xclose

The program first creates a new workfile, and then creates some series objects. The series
called Y is the dependent variable, and the series X1 and X2 are the regressors (along with a
constant). xopen is used to open a connection to MATLAB, and then xput is used to pass
the dependent variable and the regressors over to MATLAB. Note that the names of the
matrices and vectors will all be lower-cased in MATLAB since the connection was opened
with the “case=lower” option.

xrun is used to create a vector in MATLAB, called “beta”, equal to the least squares coeffi-
cient, using the matrix algebra formula for LSQ. beta is brought back into EViews with the
xget command, and then we estimate the same equation inside EViews and show the two
results for comparison. Finally the connection to MATLAB is closed.

Using R
R is a GNU-project software environment for statistical computing and graphics. R is free
software (under the terms of the GNU General Public License) that is readily available for
198—Chapter 7.EViews COM Automation Client Support (MATLAB, R, Python)

download from the Official R Project website: http://www.r-project.org/ and other mirror
sites.

To use the EViews external interface to R, you must have R installed on your Windows com-
puter. Once installed, you may use the commands listed above to communicate with R from
within EVIews.

EViews 14 supports R integration directly, eliminating the need for any third party software.
Install both EViews 14 and R on the same computer and use normal EViews commands,
such as XOPEN and XRUN.

Installing R
EViews was developed and tested with R version 3.2.3. You must have version 3.2.3 or
newer installed on the machine running EViews.

If you do not currently have R installed, simply go to the following site and download the
latest version:
https://cran.r-project.org

Verifying EViews R Connector

Verify that the new EViews R Connector Interface components are properly registered by
running the EViews command REGCOMPONENTS:

In the Register Components dialog, make sure that the EViews R Connector Interface objects
have been properly registered. If not, click the Yes (All) button to re-register these compo-
nents on your local machine, then re-run REGCOMPONENTS to verify the registration. Note:
 EViews COM Automation Client Support (MATLAB, R, Python)—199

Registration of these components will require local administrator rights. If you do not have
these admin rights, please contact your IT department for support.

Next, go to the External Program Interface dialog under the Options menu/General
Options/External Program Interface:

In COM ProgID group, make sure that EViewsRConn.VariantRConn is selected for R.

Next, if Home Path is blank, click the […] button and navigate to your local R installation.
Select the version-specific R folder (e.g., “R-3.2.3”) under the parent R folder as your home
directory.

Optionally, you can also select your Save Series as preference when pushing EViews series
objects into R. If you select “ts (time series)”, series objects that have a compatible R ts fre-
quency will be pushed as R ts objects. Otherwise, an R data.frame structure will be created
instead.

Now we're ready to begin using R.

Opening a Connection to R
All external program interface methods must begin with a call to XOPEN:
XOPEN(type=r)

This will begin a new session of R and, by default, an associated RConn Output log window
should appear. This log window will show any R commands we run and any output gener-
ated by R. You can also type R commands interactively into the RConn log window.
200—Chapter 7.EViews COM Automation Client Support (MATLAB, R, Python)

Now that we have an open connection to R, we can use the other 'X' methods to perform
some actions.

Sending EViews Data to R

Now that we have an open connection to R, we can send EViews object(s) to R using the
XPUT command:
XPUT(rtype=data.frame, name=vars) y x1 x2

Basic EViews object types such as series, alphas, matrices, vectors, and scalars can be
pushed successfully to R. Depending on the EViews object type, an appropriate R object will
be created when the data is sent. As our example shows, XPUT also supports grouping mul-
tiple series objects into a single R time series or R data.frame object.

Running an R Command
Now that we have some data in R, we can run R specific commands by using the XRUN com-
mand:
XRUN z<-glm(y~x1+x2, family=Gamma(link=log), data=vars)

You can also type this command directly into the bottom of the RConn log window (without
XRUN):

XON and XOFF Commands

To run multiple R commands without having to specify XRUN on each line of an EViews pro-
gram, you can use the XON and XOFF commands (introduced in EViews 10) to control exter-
nal programming mode. Once you call XON, all program lines after that will be sent to R
directly. Use XOFF (or XCLOSE) to turn this mode off.
XON 'Turn on external programming mode
z<-glm(y~x1+x2, family=Gamma(link=log), data=vars) summary(z)
XOFF 'Turn off external programming mode
 EViews COM Automation Client Support (MATLAB, R, Python)—201

Output Display
Note that our connector does not always automatically capture all of your R output. Conse-
quently, you may find that using XRUN to issue a command that displays output in R may
return only a subset of the usual output to your log window. In the most extreme case, you
may see a simple "OK" message displayed in your log window. To instruct R to show all of
the output, you should use enclose your command inside an explicit print statement in R.
Thus, to display the contents of a matrix X, you must issue the command
XRUN print(X)

instead of the more natural

XRUN X

Retrieving R Data into EViews

To retrieve data back into EViews, we will use the XGET command:
XGET(name=beta, type=vector) z$coef

Closing the R Connection

Once we've completed our R operations, we can close our connection with a simple call to
XCLOSE:
XCLOSE

Ability to Save EViews Workfile as RDATA Workspace File

EViews also has native RDATA workspace file compatibility.

This means you can save an EViews workfile (one page at a time) directly to a new RDATA
workspace file:
wfsave(type=rdata) c:\files\tq.rdata

Each simple object (series, alpha, matrix, vector, and scalar) on the current workfile page
will be converted to an appropriate R data structure and saved into the new RDATA file.

You can also open a pre-existing RDATA file as an EViews workfile, though because this
operation can only open all R objects into a single workfile page, all the objects in the
RDATA file must be the same frequency for this to work properly.

In cases where there are R objects with different frequencies, it would be better to treat the
RDATA file as an EViews Database instead.

Open RDATA Workspace File as an EViews Database

In EViews 14, you can now open an RDATA workspace file as an EViews Database:
DBOPEN(type=rdata) c:\files\data.rdata
202—Chapter 7.EViews COM Automation Client Support (MATLAB, R, Python)

This will open the RDATA file in its own EViews database window. You can view all the R
objects found in this database and individually FETCH the objects you want into your work-
file:

Note: R data structures that could have multiple columns/elements (such as data.frame, list,
and mts objects) are listed once per column/element with the appropriate R name.

As an EViews Database, you can use both FETCH and STORE to read and write data to the
RDATA file and even link EViews series objects back to their source R structure to allow for
simple data refreshes.

R Related Links
The Official R Project website: http://www.r-project.org/

Using Python
EViews allows you to use Python packages and code from within EViews to improve your
workflow. With EViews, you can send EViews data into the Python environment, execute
Python functions, and then retrieve data back into EViews with simple commands.

EViews supports Python 2 (version 2.7.15 or greater) and Python 3 (version 3.6.5 or
greater).

The syntax for the Python related xopen options is:

XOPEN(p)

or
XOPEN(type=p)
 EViews Database Extension Interface—203

We support the following Python data types:

list
tuple
dictionary
numpy.ndarray
pandas.series
pandas.dataframe

The last three lines require the prior installation of the numpy and the pandas Python pack-
ages.

The syntax for Python related xput commands is therefore:

xput(ptype=list|tuple|dictionary|ndarray|series|dataframe)

EViews Database Extension Interface

EViews offers built-in support for a handful of foreign database formats (e.g. DataStream,
Haver, FRED, etc.), providing users direct access to data in these formats via the standard
EViews database interface (“Foreign Format Databases” on page 362 of User’s Guide I).

If data reside in unsupported database formats, users can resort to ODBC (if an ODBC driver
was available) or using an intermediate file format (such as XLS, CSV or HTML) or the Win-
dows clipboard to exchange data. These approaches are less convenient than working with
the standard interface, and there are a number of limitations, including the inability to
obtain additional attributes such as source, units, etc. alongside observation values and the
fact that data brought into EViews using these approaches cannot be "linked” back to the
source to allow for automatic refreshes when a workfile is loaded.

To overcome these limitations, EViews supports the EViews Database Extension (EDX) Inter-
face which allows an external data source that implements this interface to be opened from
within EViews and used just like an EViews database.
204—Chapter 7.EViews Database Extension Interface

Programmers who implement a database extension for an external database format can
extend EViews so that:
• an EViews user can ask what objects the external database contains
• an EViews user can read data objects from the external database
• an EViews user can write data objects to the external database
• an EViews user can browse through the contents of the external database using a cus-
tom graphical interface developed specifically for the data source

Using EDX, a developer can offer EViews access to a external database that is indistinguish-
able from built-in access to data sources. Notably, EViews built-in support for connecting to
the U.S. Energy Information Administration (EIA) on-line databases was developed using an
EDX interface to the EIA API.

More precisely, EDX is a set of COM interfaces. Supporting a new format involves creating a
small library (usually housed in a DLL) that contains COM objects that implement these
interfaces. The library can be developed in many different programming environments
including native C++ and Microsoft .NET. These COM objects are used by EViews to inter-
act with the underlying database.
 Jupyter Notebook Support—205

For details and extensive examples of the EDX interface, please see the whitepaper EViews
Database Extension Interface Release x.x (available from our website www.eviews.com/
download/download.html).

Jupyter Notebook Support

Jupyter is a popular free, open-source, web-based interactive development environment that
allows users to create notebooks for documenting computational workflow. A notebook con-
sists of an ordered series of input and output cells for the organization of code, explanatory
text, and multimedia in a single document. The chronological, narrative record-keeping a
notebook allows for are useful for analysis, reporting, teaching, documentation, and many
other purposes.

The code in a notebook cell is passed to a programming language specific “kernel” on the
backend that does the code execution. EViews, starting with version 13, can be used as a
Jupyter kernel. Users can run an EViews program and display its results from within a note-
book.

Using the EViews Jupyter Kernel

After Python and Jupyter have been installed (https://jupyter.org/), make the EViews kernel
available to Jupyter by going to the main EViews menu and selecting Options/General
Options/External program interface. Click the Publish Jupyter Notebook button.
206—Chapter 7.Jupyter Notebook Support

A new EViews-specific folder will be created in the Jupyter kernels folder location, usually
found at “%AppData%/Roaming/jupyter/kernels”.

Next, run the notebook server. Depending on your installation, this can be done from a com-
mand prompt or the start menu in Windows or from Anaconda Navigator. Select the EViews
kernel by choosing it from the “New” drop-down menu in the upper-right corner of the
notebook dashboard. This will open the notebook editor, the interface where code and other
input is entered and evaluated. Type EViews commands into the cells and run them with
shift-enter (to run the current cell and select the following cell) or ctrl-enter (to run the cur-
rent cell). More information on using Jupyter can be found in the Jupyter documentation
(https://jupyter-notebook.readthedocs.io/en/stable/notebook.html).
Chapter 8. Add-ins

In Chapter 6. “EViews Programming,” beginning on page 129, we explained how you can
put commands in program files to repeat tasks, produce a record of your research project, or
augment the built-in features of EViews.

This chapter describes Add-ins, which extend the utility of the programming tools by provid-
ing seamless access to programs from the standard EViews menus and command line. Creat-
ing an Add-in is a simple procedure and involves little more than defining a command and
menu items for your existing EViews program.

Keep in mind that Add-ins aren’t just for EViews programmers. Even if you have never writ-
ten an EViews program, you may take advantage of these tools by installing prepackaged
Add-ins from the S&P EViews website or from third-parties. Once installed, Add-ins can pro-
vide you with user-defined features that are virtually indistinguishable from built-in EViews
features.

What is an Add-in?
Fundamentally, an Add-in is simply an EViews program that is integrated into the EViews
menus and command line, allowing you to execute the program using the menus or user-
defined command. In this regard, any EViews program can be used as the basis of an Add-
in.

More specifically, the Add-ins infrastructure lets you:

• add entries to EViews global or object-specific menus to offer point-and-click execu-
tion of the Add-in program.
• specify a user-defined single-word global or object-specific command which may be
used to run the Add-in program.
• display Add-in output in standard EViews object windows.

For example, suppose you have created a program to implement an econometric procedure
that prompts the user for needed input. You may turn this program into an EViews Add-in
that may be run by selecting a menu item or typing a command. Lastly, the Add-in might
display the output in the window of an existing EViews object.

Getting Started with Add-ins

The easiest way to get started with Add-ins is to download and install one of the previously
written Add-ins packages from the EViews website. Simply go to the main menu in EViews
and select Add-ins/Download Add-ins...
208—Chapter 8.Getting Started with Add-ins

EViews will open the corresponding Add-ins dialog opened to the Available tab showing
the list of Add-ins that are available for download from the EViews.com website. The list
shows the name of the Add-in, the publication date, version, and status. The status field
indicates whether the entry has not been installed (blank), has previously been installed, or
has previously been installed and is out-of-date.
 Getting Started with Add-ins—209

Select the desired entry to display additional information in the bottom of the dialog and to
enable the Install button. Clicking on Install instructs EViews to download the Add-in and
begin the installation procedure. (Alternately, you may click on the Website button and fol-
low the navigation links to the Add-ins page. Download the appropriate file to your com-
puter then open it using EViews by double-clicking on the file or dropping it onto the
EViews application window or the application icon.)

The first step in the

installation procedure is
to unpack the Add-in
files onto your computer.
By default, EViews will
put the files in a sub-
folder of your default
directory (see “Manag-
ing Add-ins” on page 220), but you may choose an alternate location if desired (you may
use the “...” button on the right-hand side to navigate to a specific directory). Click on OK to
proceed.

Note that if you manually downloaded the Add-in from the EViews website, you need not
use EViews to unpack the files. You may instead change the download file extension from
210—Chapter 8.Getting Started with Add-ins

“AIPZ” to “ZIP” and use your favorite ZIP file tools to extract the contents into the desired
directory.

Next, EViews will prompt you to run the installation program that is included in the Add-in
package.

The installation pro-

gram is a file contain-
ing EViews
commands that auto-
matically registers
the Add-in by defin-
ing menu entries and
commands for the
program.

If you click on No in response to the prompt, EViews will finish the automatic installation
procedure without running the installation program and registering the Add-in. The Add-in
program files will be on your computer but will not be integrated into the standard com-
mand or menu interface. You may, at a later time, examine and run the installation program
as you would any other EViews program, or you may manually register your programs as
described in “Registering an Add-in” on page 223.

Click on Yes to display other add-in options and to finish registering the Add-in. If there are
conflicts with existing directory names or existing Add-ins, EViews will warn you before pro-
ceeding.

After completion of the automatic installation procedure, EViews will report that the Add-in
was installed successfully:

We note that installing and running an EViews program file provided by an unknown indi-
vidual has risks. Accordingly, we recommend that care be taken when installing packages
from non-trusted sites. All of the packages provided on the EViews website have been exam-
ined to ensure that they do not include potentially harmful commands.

Once your Add-in is installed, you may wish to consult the Add-in documentation to obtain
additional information on features, options, and commands. Open the Add-ins management
 Using Add-ins—211

dialog by selecting Add-ins/Manage Add-ins... from the main EViews menu, select the Add-
in of interest and click on the Docs button to display any documentation provided by the
author:

Using Add-ins
Add-ins are integrated into the EViews menus and command line so that they work much
like built-in routines. To run an Add-in program, simply select the corresponding menu entry
or issue the appropriate command.

Beyond that, working with Add-ins menu and command entries does require some under-
standing of the difference between the two types of Add-ins: object-specific and global. As
the names suggest, object-specific Add-ins are designed to work with a single object type,
while global Add-ins are designed to work more generally with more than one object or
object type.

For example, an Add-in that computes a spline using data in a series is likely to be object-
specific, since it operates on a single series, while an Add-in that copies tables, graphs, and
spools into an RTF file would naturally be defined as global.

The menu entries and form of commands differs between the two Add-in types.
212—Chapter 8.Using Add-ins

• Global Add-ins have menu entries that appear only in the main Add-ins menu. Global
add-in commands follow the EViews command syntax:
command(options) [args]
• Object-specific Add-ins have menu entries that appear in both the main Add-ins menu
and in the menu of objects of the specified object type. Object-specific Add-in com-
mands follow the standard EViews object command syntax:
object_name.command(options) [args]
Suppose, for example, we have a global Generate time-series data Add-in with associated
command tsdgp. Since the Add-in is global, it will have a menu item in the main Add-ins
menu,

Moreover, the global command

tsdgp(diff="2", seed=100, meanconst="2", ar="0.1", ma="0.15",
varconst="0.8", arch = "0.15", garch="0.2 0.2") y

will run the Add-in program with the specified options.

Suppose, in addition, that we have two equation-specific Add-ins, Simple rolling regression
and Advanced rolling regression, with associated object-specific commands, roll and
advroll. If equation EQ1 is the active object, the main Add-ins menu will contain both the
global (Generate time series data) and the two equation-specific entries (Simple rolling
regression and Advanced rolling regression):
 Using Add-ins—213

In contrast, the EQ1 equation object will have an object Add-ins menu contains only the
two object-specific entries:
214—Chapter 8.Using Add-ins

To run the simple rolling regression Add-in you may select either the main or the equation
menu Add-ins entries, or you may enter the equation object command:
eq1.roll

in the EViews command window.

If you wish to see the available Add-ins and their types, you may click on the Add-ins/Man-
age Add-ins... entry in the main menu to display the Add-ins management dialog. EViews
will display the list of installed Add-ins with a Type column showing the type associated
with each entry:
 Add-ins Examples—215

Note that you may use the Add-in type drop-down to filter the display.

In this example, the Recshade (Add USA Recession Shading, ROLL (Simple Rolling Regres-
sion), and Advroll (Advanced Rolling Regression), Add-ins are all object-specific, while the
Tsdgp (Generate time series data) Add-in is global.

Add-ins Examples
To further illustrate the use of Add-ins, we examine two of the Add-ins currently available
for download from the EViews website. (To follow along with these examples, we recommend
that you first download and install the corresponding Add-in using the steps outlined in “Get-
ting Started with Add-ins” on page 207.)

Summarize Equation Results

Our first example is a global Add-in (EqTabs) that creates a table summarizing the results
from multiple equations. If you have not already downloaded and installed this Add-in, we
recommend that you do so now. We employ the workfile “Demo.WF1” (which may be
found in the examples subdirectory of your EViews installation directory.

To run the Add-in, go to the main EViews menu, and select Add-ins/Equation Output Table
(Summary form). EViews will display a dialog prompting you for the names of the equa-
tions you wish to summarize:
216—Chapter 8.Add-ins Examples

The default entry of “e*” is sufficient for this example since we want to summarize results
for the previously estimated equations EQ01 and EQ02. Click on OK to continue.

EViews will display a series of dialogs prompting you to specify the headers you wish to
include in the summary table, the information you wish to display, and the display format.
For example, the last dialog lets you choose the standard errors and t-statistics display for-
mats, along with the number of significant digits for coefficients and other statistics:

EViews will use the specified settings in constructing a table that summarizes the results
from all of the specified equations.
 Add-ins Examples—217

You may also launch the Add-in from the command line or via batch execution of a program
file. Simply enter the user-defined command:
eqsumtab eq*

in the command line or include it in your batch program. The command instructs EViews to
run the program, displaying the set of dialogs prompting you for additional input, and con-
structing the table accordingly.

U.S. Recession Graph Shading

Our second example uses the graph-specific Add-in (RecShade) to add shading for periods of
U. S. recession (as determined by the National Bureau of Economic Research).

We start by opening the graph object GT in the “Macromod.WF1” workfile (which may be
found in the example files subdirectory of your EViews installation directory).
218—Chapter 8.Add-ins Examples

Next, click on the Proc/Add-ins menu item in the graph toolbar to display the Add-ins we
have installed that work with graph objects. In this case, there is only a single menu item
Add US Recession Shading:
 Add-ins Examples—219

You may also access the active object menu items by clicking on the Add-ins entry in the
main EViews menu. When the graph object GT is the active object, the main Add-ins menu
shows both the global and graph specific menu items:

Selecting the Add US Recession Shading entry in either the main or graph object Add-ins
menu runs the Add-in program which adds shading to the existing graph:

For those who prefer to use a command, you may go to the command line and enter the
user-defined object command
gt.recshade

to apply the recession shading. This command may also be included in a program file for
batch execution.
220—Chapter 8.Managing Add-ins

Managing Add-ins
EViews offers a complete system for managing your Add-ins. To bring up the management
dialog, you should select Add-ins/Manage Add-ins... from the main EViews menu:

The management dialog is divided into two sections:

• The Registered Add-ins section is where you will perform most of the tasks of man-
aging your Add-ins (add, delete, edit, update, and reorder Add-in definitions, and
view the documentation file).
• The Default Add-ins directory section allows you to set the default directory for your
Add-ins.

Registered Add-ins
The top portion of the dialog shows settings for currently installed Add-ins, with each line
devoted to an Add-in.
 Managing Add-ins—221

By default, all of the installed Add-ins will be displayed. You may use the Add-in-type drop-
down menu to filter the list, showing for example only global or only equation-specific Add-
ins.

The File name column shows the name (and possibly location) of the Add-in program, and
the Type column indicates whether the Add-in is global or object-specific. The Proc column
shows the command keyword associated with the Add-in (if any), while the Menu Text col-
umn shows the text used in the user-defined menu entries. The Version column show the
version number of the Add-in.

You may use the buttons and arrows on the right-hand side of the dialog to manage your
Add-ins:
• To add a new Add-in to the list, simply click on the Add button to display the Add/
Edit Program dialog. The Add/Edit Program dialog is described in detail in “Register-
ing an Add-in” on page 223.
• To delete an Add-in, simply click on the name in the Add-ins management dialog and
press the Remove button.
• The order in which your Add-ins appear in the menus may be controlled using the up
and down arrows. If you have many Add-ins, putting the most frequently used Add-
ins first in the list may simplify menu access (see “Menu Congestion” on page 226).
In addition, the order in which Add-ins appear can have important consequences in
the event that Add-ins duplicate command names (see “Command Masking” on
page 225).
• To edit the settings of an existing Add-in, select it from the list and chick on the Edit
button to display the Add/Edit Program dialog. The Add/Edit Program dialog is
described in detail in “Registering an Add-in” on page 223.
222—Chapter 8.Creating an Add-in

• To examine the documentation file associated with an Add-in, click on the name and
press the Docs button.
• To check whether the Add-in has an updated version available, and to install the
update if available, click on the Update button.

Note you may select multiple Add-ins at the same time and click on the Remove or Update
buttons to perform the specified operation. You may also right click anywhere on the list of
Add-ins and select Update All to check for updates on all of your Add-ins.

After modifying the desired settings, click on OK to accept any changes.

Default Add-ins Directory

The bottom portion of the Add-ins dialog shows the current default Add-ins directory. The
default directory is where an Add-in will search for supplementary files if explicit directory
locations are not provided. To change the default directory, click on the button on the right
and navigate to the desired directory, or simply enter the desired folder name. Click on OK
to accept the settings.

Creating an Add-in
You can use Add-ins developed by others without ever having to create one yourself. Indeed,
many users will never need to go beyond running Add-ins downloaded from the EViews
website or other repositories.

You may find, however, that creating your own Add-ins is both useful, if only to add a menu
item or assign a one-word command for running your favorite EViews program, and easy-to-
do.

Assuming that you already have an EViews program, creating an Add-in requires at most
two steps:
• Register the program as an Add-in. Registering an Add-in is the process of defining the
Add-in type and assigning menu entry and command keywords to an EViews pro-
gram.
• (optional) Create an Add-in package for distribution. Bundling your program files into
a self-installing package file and providing a program for automatically registering the
Add-in means that others can more easily incorporate your Add-in into their EViews
environment.

While only the first step is required, you should consider the optional step of creating a self-
installing Add-in package if you wish to distribute your Add-ins more widely.
 Creating an Add-in—223

In the remainder of this section we describe the steps required to register an Add-in. In addi-
tion, we provide design tips and describe additional programming tools that will aid you in
writing sophisticated Add-in programs.

Registering an Add-in
The process of defining the Add-in type and assigning menu entry and command keywords
to an EViews program is termed registration. The Add-in registration process may also be
used to associate documentation with the Add-in.

To register an EViews program file as an new Add-in, click on the Add-ins/Manage Add-
ins... menu entry in the main EViews menu. The top portion of the management dialog
shows the list of currently registered Add-ins:

Click on the Add button to display a standard file Open dialog. Navigate to the program file
you wish to register and click on OK to continue.

EViews will display the Add/Edit Program dialog with various default settings.
224—Chapter 8.Creating an Add-in

The dialog allows you to specify a command keyword for the Add-in, to add menu items for
point-and-click access to the Add-in, and to attach documentation and descriptions.
• The Program file edit field in the dialog should be used to specify the program to be
used as an Add-in. You may enter the name of a file (with an absolute or Add-ins
directory relative path, if necessary) or you may click on the button to the right-hand
side of the edit field to navigate to the file.
• The Documentation file edit field allows you specify a PDF, Text, RTF, Microsoft
Word file, or URL containing documentation for the Add-in. Note that relative paths
are evaluated with respect to the directory of the Add-in program, not the default Add-
in directory.
• The Menu/Procedure type dropdown setting determines whether the program is a
global or an object specific Add-in. (Recall that global Add-ins are those designed to
work with multiple objects or object types, while object-specific Add-ins work with a
single object and object type.)
• If you check Assign as Command or Proc, EViews will add the specified single-word
command or proc keyword to the EViews language, so you may run the Add-in using
a global or object command. Names for the keyword must follow standard EViews
command naming convention. Global Add-ins should not be given the same name as
built-in EViews commands. (See “Command Masking” below, for additional discus-
sion.)
• If you check Include in Add-ins menu, EViews will add the specified Menu text to
the appropriate menus.
 Creating an Add-in—225

• You may use the Brief description edit field to describe the purpose of the Add-in.
• You may enter a Version number for your Add-in and an Update URL indicating
where to find the update XML file (see “XML File Specification” on page 228).

In the example above, we instruct EViews to use the file “Rtf_out.PRG”, which is located in
the default Add-ins directory, as an Add-in program. We indicate that the program is a global
Add-in that may be run from the main EViews menu by selecting the Add-ins menu item
Output to RTF or by issuing the command rtf_out. There is no documentation file.

Add-ins Design Issues

For the most part, defining commands and menu items for an Add-ins is straightforward.
There are, however, a few issues that you should bear in mind when designing your Add-in.

Command Masking
Allowing you to define user-specified Add-in command names opens up the possibility that
an Add-in will be assigned the same command as an existing EViews command, or that mul-
tiple Add-in programs will be assigned the same name. Duplicate command names will gen-
erate an error or will lead to command masking where some of the instances will be
ignored.
• If you specify a global Add-in command name that is identical to an EViews command
or a previously defined global Add-in command, EViews will issue an error message,
and will display the Add/Edit Program dialog so you can provide a different name.
EViews will not, for example, permit you to register an Add-in with the global com-
mand copy since this conflicts with the built-in command.
• EViews will not generate an error message if you provide an object-specific command
name that is identical to a built-in command, but the EViews command will mask the
user-defined command. EViews will, for example, permit you to register an equation
command with the name resid, but if you enter the equation command “eq01.resid”,
EViews will display the built-in resid view of equation EQ01, instead of running the
user-defined Add-in.
• If you specify an object-specific Add-in command name that is identical to another
object-specific command, EViews will not error. When multiple Add-ins are assigned
the same object-specific command, the first Add-in listed in the list of registered Add-
ins will be used and the remainder will be masked. To eliminate masking, you must
edit the conflicting Add-in command definitions. If you wish to retain the same com-
mand name for multiple Add-ins, you should use the Add-ins management dialog to
reorder the Add-ins list so that the desired Add-in has priority (“Managing Add-ins”
on page 220).
226—Chapter 8.Creating an Add-in

We emphasize that masking only occurs within like Add-ins. You may have a global, series,
and group Add-in that each use the same command without experience masking, but two
global Add-ins or two series Add-ins with the same name will lead to masking.

Menu Congestion
While you may define as many Add-in menu items as you like, EViews does place limits on
the number of menu items that may be displayed by default. If you have more than 10 global
menu entries or more than 10 object-specific menus of a given type, the corresponding
menus will display the first 10 entries, along with an 11th menu entry, More... Clicking on
More... displays a listbox showing the full set of entries. In such circumstances, we recom-
mend that you reorder your Add-ins so that the most used Add-ins are given priority.

Multiple Object Add-ins

You may wish to use a single program file to define Add-ins for several object types. Since it
is not possible to use a single Add-in entry to define multiple object-specific types, you must
create separate entries for each object-type which point to the single program file. For each
relevant object type, select Add-ins/Manage Add-ins... from the main EViews menu, then
navigate to and select the program file. Use the Add/Edit Program dialog to define the
object-specific entry.

Creating an Add-in Package

If you are developing Add-ins for use by others, we recommend that you create a self-install-
ing package so that users may easily incorporate your Add-ins in their EViews environment.
You can then host your package on a company intranet or perhaps submit your package to
be hosted on the EViews.com website for wide distribution.

The process of creating an Add-in package is straightforward, requiring at most two steps:
• (optional) Create a table of contents (TOC) information file and installer program file.
• Create a self-extracting Add-in package file containing the program and support files
(including the TOC and installer program file, if available).

The second step, creating the self-extracting package, is trivial. Simply create a standard ZIP
archive file containing all of the files for your Add-in, then rename the ZIP file so that it has
the extension “AIPZ”. You now have an self-extracting Add-in package file.

Opening a self-extracting package file, either automatically by a browser after completing

the download, by double clicking on the file, or by dropping it onto EViews, will prompt you
to unpack and copy the files to the location of your choice.

The Add-in will not, however, automatically be installed and registered unless you include a
table of contents (TOC) information file and installer program along with your program files.
Creating the TOC and installer program files takes only a few minutes and allows you to
 Creating an Add-in—227

automate the Add-in installation and allow for automatic updating of your Add-in as you
provide newer versions. We strongly recommend that package distributors take the time to
create these files as described below.

Table of Contents
First, you should create a table-of-contents file named “Toc.INI” for inclusion in your pack-
age. The TOC file should contain setup information which describes the directory in which
the Add-in files should be installed, and if appropriate, the name of an EViews installer pro-
gram for registering the Add-in. The format of the TOC file is:
[package]
installer = <name of installer file>
folder = <name of folder to create>

A TOC file should always begin with the line “[package]”, followed by lines which give the
directory and installer information.

The installer keyword is used to indicate the name of the EViews program file, if one
exists, that should be run to register the Add-in (see “Installer Program” on page 228). If, for
example, a registration program file named “Recession shade install.PRG” is included in
your package, you should include the line
installer = recession shade install.prg

If you include this line in your TOC, EViews will automatically run the installer program
when it opens the AIPZ package. If you do not wish to provide an installer program, you
should include the line “installer=none” in the TOC file.

The folder keyword may be used to indicate a subfolder of the default Add-ins directory
into which you will extract the packaged files. Thus,
folder = RecShade

tells EViews to extract the contents of the AIPZ file into the “RecShade” folder of the Add-ins
directory. If no folder is specified, the name of the AIPZ file will be used as the target folder
name. Additionally, you may use the special folder name “<addins>” to indicate that the
contents of the AIPZ archive should be placed in the main Add-ins directory. (Note, how-
ever, that only folders in an AIPZ archive may be written to the main Add-ins directory in
this fashion; individual files in AIPZ files must be written into subdirectories.

We emphasize that creating a TOC file and providing an installer program are not required.
In the absence of a TOC file or an installer= specification, EViews will, after unpacking
the AIPZ files, simply display a message reminding the user that the installed programs may
be registered manually using the Add-ins management dialog.
228—Chapter 8.Creating an Add-in

Nevertheless, we strongly recommend that package distributors provide both a TOC file and
installation program to facilitate use of their Add-ins. Packages hosted on the EViews web-
site must include both a TOC and an installer.

Installer Program
Next, you should create a simple EViews program that uses the addin (p. 365) command to
register the Add-in with appropriate type, menu, and command settings. Note that the TOC
file installer= specification should point to this installer program.

For example, the graph-specific Add-in described in “U.S. Recession Graph Shading” on
page 217 may be registered by including the following command in a program file:
addin(type="graph", menu="Add USA Recession Shading",
proc="recshade", docs=".\recession shade.txt", desc="Applies US
recession shading to a graph object.") ./recshade.prg

The options in this example should be self-explanatory. The command registers the program
“./recshade.PRG” as a graph-specific Add-in with menu item “Add USA Recession Shading”,
command name “recshade”, and description text “Applied US Recession shading to a graph
object”.

See addin (p. 365) for details and a complete list of options. Use of the following addin
options is highly recommended:

Documentation
We recommend that you provide documentation for your Add-in, and use the “docs=”
option to point to the documentation file.

Documentation could be anything from a simple text file with some syntax hints, to a
lengthy PDF document that describes the Add-in features in detail.

Version
EViews allows Add-ins to have a version number which allows the users of your Add-in to
use automatic updating to ensure they have the latest version of the Add-in. When a user
uses the Update button on the Manage Add-ins dialog to check for Add-in updates, EViews
will compare the hosted version number with the currently registered version number and
download the latest version if necessary.

You may use the “version=” option to specify the version number. If omitted, EViews will
assume that the Add-in version number is 1.0.

XML File Specification

One of the most useful Add-ins management features is the ability of users to automatically
update their installed Add-ins as newer versions become available. To support this feature,
 Creating an Add-in—229

EViews must know where to look to determine the most recent version of the Add-in and
where to download any updates.

This information is communicated in an XML file, typically located on the Add-ins package
hosting site. If you will be hosting this file, you should use the addin option “url=” to spec-
ify the URL for the XML file. If this option is not supplied, EViews will look for the XML file
on EViews.com.

The XML file should contain one or more item definitions, where each item contains infor-
mation on a specific Add-in. An item definition is contained in the lines between an <item>
and </item> tag. An example of the full specification of an item is as follows:
<item>
<title>BMA</title>
<path>bma\bma.prg</path>
<path>bma\bmamlogit.prg</path>
<version>1.0</version>
<description>Computes different Bayesian Model Averaging methods
including LM, GLM and Multinomial Logit models.</description>
<link>http://eviews.com/Addins/BMA.aipz</link>
<pubDate>13 Mar 2012</pubDate>
</item>

Note that the only required specifications are the <title> and <link>.

The <path> specification is used to identify the paths and file names of the main program
files used by the Add-in, with the path location specified relative to the Add-ins directory.
Automatic updating will update these files when a newer Add-in version is available. If
<path> is not specified, EViews will use the <title> specification to determine the rele-
vant Add-in proc name, and use registration information for the proc name to determine the
files to update.

When an add-in package has multiple main program files, a <path> statement is required.
You should list each file using a separate <path> entry. In the example above, the BMA Add-
in has two program files, called “bma.PRG”, and “bmalogit.PRG” that are associated with
procs. EViews will update all of the files associated with these procs when updating the
Add-in.

The <version> is used to specify the current Add-in version number. When the user checks
for updates, EViews will download the updated version if the version number they have cur-
rently installed is lower than the one given in the <version> tag.

Finally, the <link> specification contains the URL (or network file location) of the AIPZ file
containing the Add-in. This is the location from which EViews will download the updated
Add-in package should the user request an update.
230—Chapter 8.Add-ins Design Support

The <description> and <pubDate> specifications should be self-explanatory.

Add-ins Design Support

EViews offers several programming language features that will aid you in developing and
working with Add-ins.

Add-ins Registration Command

The addin command may be used to register an EViews program file as an Add-in. You may
use the command to specify the Add-in file, Add-in type, menu text, user-defined command
name, description, version number, documentation file, XML file, etc.

See addin (p. 365) for details.

The Active Object Keyword

“_this” Keyword
Central to the construction of an object-specific Add-in program is the ability to reference
the object on which the program should act. If, for example, you wish to write an Add-in
that computes a statistic based on the data in a series object, you must have a convenient
method of referring to the series.

Accordingly, EViews provides an object placeholder keyword, _this, which refers to the
currently active object upon which a program may operate. Typically the use of _this in an
EViews program indicates that it has been designed to work with a single object.

There are three ways in which the identity of the _this object may be set:
• _this refers to the active object whose window was last active in the workfile; when
used in a program, _this refers to the active object at the time the program was run.
• executing an Add-in using the object-command syntax, obj_name.proc, sets _this to
obj_name.
• _this can be set to a specific object using the “this=” option in an exec or run com-
mand.

While the above description is a bit abstract, a simple example should illustrate the concepts
that lay behind the three methods. Suppose we have the trivial (silly) program
“Myline.PRG” which consists of the command:
_this.line

First, if we register this program as a global Add-in with menu item text “Show line”, we can
display a line graph of a series or group object by opening the series or group and selecting
Show line from the Add-in menu. From the program’s point of view, the _this object is
 Add-ins Design Support—231

simply the opened series or group whose menu we are using (the last one active in the
workfile).

Alternately, if we had registered the program as a series-specific Add-in with proc name
“myl”, the command:
ser01.myl

identifies SER01 as the _this object, so that the object used by the Add-in will be the series
SER01, regardless of which object is active in the workfile.

Lastly, you may specify _this explicitly when using the exec or run command to run the
program by including the “this=” option to identify an object by name. The command:
exec(this=ser01) myline.prg

explicitly specifies SER01 as the _this object.

Custom Object Output

EViews allows you to display the contents of a table, graph, or spool object in the window of
another object. This feature will undoubtedly most often be used to mimic the behavior of
EViews views and procedures in Add-ins programs.

Suppose, for example, that your Add-in program performs some calculations and constructs
an output table TABLE_OUT. You may instruct EViews to display the contents of
TABLE_OUT in the object OBJECT_01 using the display command:
object_01.display table_out

Thus, a useful approach to constructing an object-specific Add-in involves creating a pro-

gram of the form:
[use _this to perform various calculations]
[create an output table or graph, say the table TABLE01]
’ put the output in the _this window
_this.display table01
delete table01

Note that we delete the TABLE01 after we put it in the window of _this. (You may instead
wish to employ local subroutine to enable automatic cleanup of the temporary table.)

If the above program is registered as a series-specific Add-in with the command “FOO”, then
you may run it by issuing the command
series01.foo

which will display the output in the SERIES01 window.

232—Chapter 8.Add-ins Design Support

The display object command is a documented view for each supported object. See for
example, Series::display (p. 779) in Object Reference.
Chapter 9. User Objects

As the name suggests, the EViews user object allows you to create your own object types
inside of EViews. A user object may be as simple as a storage container for other EViews
objects, or it may be a sophisticated new estimation object defined by multiple EViews pro-
grams, with views containing post-estimation tests and results, and procedures producing
output from the estimation results. Once defined, a user object is almost indistinguishable
from a built-in EViews object.

Defining a user object is quite easy—simply specify the types of data and objects stored
inside your object, and if desired, define a set of views and procedures that be accessed via
commands, menus and dialogs.

Even if you do not go to the trouble of creating your own objects, you may take advantage of
this powerful tool by using user objects downloaded from the S&P EViews website or
obtained from third-parties.

What is a User Object?

An EViews user object is a custom object that can contain data and objects and may offer
views and procedures. In its simplest form, a user object is a storage container for EViews
objects. More sophisticated user objects also provide views and procs that allow you to run
EViews programs to perform various tasks and display results. These latter objects work
almost identically to built-in EViews objects such as a series or equation.

In the discussion to follow it will be important to distinguish between user objects that are
unregistered or registered:
• Unregistered user objects are simple container objects which require virtually no
effort to create.
• Registered user objects are more powerful than unregistered user objects. Registering
a user object class is the process of describing what happens each time a new
instance of the user object is created, and defining data and a set of views and procs
available to the user object class.

A relatively complex registered user object might be a complete econometric estimator. Each
time a new instance of the estimator object is created, it could specify and perform estima-
tion, saving results inside the user object in the form of data objects such as coefficient vec-
tors and covariance matrices. The object could also offer views such as coefficient tests and
procs to perform forecasting. And like an EViews equation object, you may have multiple
instances of this estimator in the workfile, each corresponding to a different set of estimates.
234—Chapter 9.Unregistered User Objects

We note that a registered user object need not be particularly complex. For example, you
could have a simple user object called “RESULTS” that contains a collection of graphs,
tables, and estimation objects obtained from a particular form of analysis. You could define
simple views for your user object that display the stored tables or graphs, and define procs
that let you extract those tables or graphs into new EViews objects. Registering the object
allows you to have multiple results objects in your workfile.

Unregistered User Objects

To create a new, unregistered user object, select Object/New Object in the main EViews
menu.

Scroll down and select UserObj, enter a name for the object in the workfile (in this example,
MYOBJ), and click on OK. Alternately, you may enter the generic user object declaration
command
userobj myobj

to create a user object named MYOBJ in the workfile.

 Unregistered User Objects—235

Notice that MYOBJ has a black icon. A user object created in this fashion is empty, with no
user-defined views or procedures. Double-clicking on MYOBJ opens the object and displays
its contents:

As you can see, the object is empty. Clicking on the View menu of the object shows only a
single Label entry. The Proc menu is completely empty.

An empty, unregistered userobj is not particularly interesting. You may, however, use the
object as a container for EViews matrix objects (including scalars), string objects, estimation
objects, and view objects (graphs, tables, spools):
• The add (p. 1123) and drop (p. 1127) procs may be used to populate the user object
and the extract (p. 1128) proc may be employed to extract objects into the workfile.
• You may use user object data members to provide information about the contents of
the object: the @hasmember(obname) member function can be used to determine
whether obname exists inside the user object, while @members returns a space delim-
ited string listing all objects in the user object.
236—Chapter 9.Registered User Objects

See “User Object Programming Support” on page 257 for details.

The following program offers a simple example showing the use of these commands:
userobj myobj
myobj.add mygraph
myobj.add mytable
%list = myobj.@members
myobj.drop mygraph
myobj.extract mytable mynewtable

The first line creates a new, empty, user object called “MYOBJ”. The second and third lines
copy the workfile objects “MYGRAPH” and “MYTABLE” into MYOBJ. The fourth line creates
a string variable whose contents are “mygraph mytable”. The fifth line removes MYGRAPH
from MYOBJ, and the final line copies MYTABLE back into the workfile under the name
MYNEWTABLE.

Registered User Objects

While simple, unregistered user objects may only be employed as storage containers, regis-
tering a user object class creates a more powerful working environment. Note that we used
the term user object class, reflecting the fact that when you register a user object, you are not
simply declaring a single object but rather are defining the general characteristics of a type
of object.

Registering a user object class allows you to have multiple objects of a given type in your
workfile, each of which has its own data. Additionally, registering allows you, if desired, to
define views and procs that can be used by any object of that class. These views and procs
will execute a set of EViews programs that you specify as part of the registration procedure.

While not difficult, creating a registered user object class is a bit more involved than creating
an unregistered user object. Details are provided in “Defining a Registered User Object
Class” on page 251.

You may, of course, download and register user object classes created by others. Since work-
ing with example user objects provides good introduction to this powerful tool, we begin by
discussing the steps required to download an object from the EViews website.

Downloading a Registered User Object

To download and install object class definitions from the EViews website, simply select Add-
ins/Download User Objects...from the main EViews menu.
 Registered User Objects—237

EViews opens the User objects management dialog opened to the Available tab, which
shows a list of the user objects classes (in this case ResStore, Roll, and BiProbit), that are
available for download along with the date they were published, their version number, and
their status (blank for un-installed, installed, or installed but out of date):
238—Chapter 9.Registered User Objects

Selecting an entry displays a description of what the user object does below the listbox.
Clicking on the Install button downloads the selected user object and prompts you to install
the package on your the local computer. (Alternately, you may click on the Website button
and follow the navigation links to the user objects page. Download the appropriate file to
your computer then open it using EViews by double-clicking on the file or dropping it onto
the EViews application window or the application icon.)

The first step in installa-

tion is to unpack and
copy the files to your
computer. By default,
EViews will put the files
in a sub-folder of your
default directory (see
“Default User Objects
Directory” on page 251) but you may choose an alternate location if desired (you may use
the “...” button on the right-hand side to navigate to a specific directory). Click on OK to
proceed.

To unpack the files without using EViews, simply change the download file extension from
“AIPZ” to “ZIP” and use your favorite ZIP file tools to extract the contents into the desired
directory.

Next, EViews will prompt you to run and installation program that is included in the user
object package.

If you click on No in response to the installation prompt, EViews will finish the automatic
install procedure without running the installation program and registering the userobj. You
may later examine the installation program prior to running it as you would any other
EViews program, or you may manually register your object as described in “Registering a
User Object Class” on page 253.

Click on Yes to finish the installation and registration. If there are conflicts with existing
directory names or existing user objects, EViews will warn you before proceeding.

After completion of the automatic installation procedure, EViews will report the status of the
installation:
 Examples—239

We note that installing and running an EViews program file provided by an unknown indi-
vidual has risks. Accordingly, we recommend that care be taken when installing packages
from non-trusted sites.

All of the packages provided on the EViews website have been examined to ensure that they
do not include potentially harmful commands.

Working with Registered User Objects

Once you have registered your user object you may work with it much as you would any
built-in EViews object.

You can create a new instance of the object using the Object/New Object... main menu
item, or by declaring it on the command line using the name of the object and any relevant
options or arguments:
userobj_class_name(options) my_objname [args]

You may use the defined views and procs of the object using the object View or Proc menu,
or via the command line using the standard syntax:
userobj_name.view_name(options) [args]
userobj_name.proc_name(options) [args]

The user object data member @-functions may be accessed using the syntax:
[result_type] result = userobj_name.@datamember_name[(arg)]

Examples
To illustrate the use of registered user objects, we examine two of the EViews user objects
that are currently available for download from our website. (To follow along with these
examples, we recommend that you first download and install the corresponding user object
using the steps outlined in “Downloading a Registered User Object” on page 236.)

The first example uses a simple container user object (of type ResStore) that allows you to
add, extract, and display graphs, tables and estimation objects. The second example per-
forms rolling regression estimation using the Roll user object.
240—Chapter 9.Examples

Simple Container Object (ResStore)

This first example uses the ResStore user object to create a storage container for objects from
our workfile. This is a bare bones registered object that nonetheless shows the basic features
of registered user objects.

We use the workfile “Demo.WF1” (which may be found in the example files subdirectory of
your EViews installation directory) and assume that you have already installed the ResStore
object class.

You may create a new ResStore object by clicking on Object/New Object... and then select-
ing resstore in the list of object types.

Notice that while the built-in EViews objects are listed alphabetically, the two user objects
(ResStore and Roll) are simply placed at the bottom of the listbox. Select resstore and spec-
ify the name STOREDOBJECT for our new object. Click on OK to create the object. Alter-
nately, enter the command
resstore storedobject

in the EViews command line and hit ENTER.

As part of its construction, the ResStore object will display a dialog asking you to enter the
names of the workfile objects you would like to store:
 Examples—241

You may enter the names of any matrix objects (including scalars), strings objects, estima-
tion objects, or view objects (graphs, tables, spools).

Note that there is a check-box that lets you specify whether to remove the objects from the
workfile after storing them. You should selection this option if you wish to move, rather than
copy, the specified objects into the ResStore.

Once you hit OK, a new ResStore object named STOREDOBJECT will be added to your
workfile. If you open up the ResStore object, a spool view display of all objects currently
stored is shown:

You may use the View menu to access the defined views for this type of object which allow
you to show various subset types of the objects in the container:
242—Chapter 9.Examples

Similarly, the Proc menu lists procs which allow you to add, remove, and extract objects
from the storage container:

As with other EViews objects, you may use the command language to work with the ResS-
tore object. For example the defined view command,
storedobject.graphs

displays all of the graph objects in the object

storedobject.extractobjects

extracts all of the objects from STOREDOBJECT into the workfile.

The command
 Examples—243

string storednames = storedobject.@members

saves a list of the stored object names in the string object STOREDNAMES.

Rolling Regression Estimation Object (Roll)

Our second example uses the Roll user object to estimate rolling regressions. We again use
the workfile “Demo.WF1”, and we assume that you have already installed the Roll object
class.

You can create a new Roll object by clicking on Object/New Object... and then selecting roll
in the list of object types, or by entering the roll command followed by the name of a new
object in the command line:
roll myroll

As part of its creation, the Roll object will display a series of dialogs prompting you to pro-
vide information on how the object should be constructed. First, you will be asked whether
to create the new object using the specification from an existing equation or by specifying an
equation manually:

Since we will use one of the previously estimated equations in our workfile as the basis of
our rolling regression, click on OK to accept the default.

Next, you will be asked to select your base equation and to specify the basic type of rolling
regressions you wish to perform:

To obtain recursive estimates based on equation EQ01 choose EQ01 in the drop-down menu
and select Anchored at start. Click on OK to continue.

Lastly, you will be prompted to provide sample information and a step size:
244—Chapter 9.Examples

Click on OK to create the Roll object using the specified settings.

(Note that if you had chosen Manual equation specification in the first dialog or Fixed
window estimation in the second dialog, the subsequent dialogs would provide a different
set of options).

EViews estimates the rolling regression and, like built-in estimation objects, displays basic
estimation information in the object window:
 Examples—245

Roll: MYROLL
Roll type: Anchored at start
Specification: EQ01
Estimation command: ROLL(AS,STEP=1,ANCHOR=1953Q1) MYROLL
@ EQ01

Anchor point: 1953Q1

Number of subsamples: 160
Number of coefficients: 4
Step size: 1

Full sample estimation results:

Dependent Variable: LOG(M1)

Method: Least Squares
Date: 01/31/13 Time: 10:19
Sample (adjusted): 1952Q2 1992Q4
Included observations: 163 after adjustments

Variable Coefficient Std. Error t-Statistic Prob.

C 1.312383 0.032199 40.75850 0.0000

LOG(GDP) 0.772035 0.006537 118.1092 0.0000
RS -0.020686 0.002516 -8.221196 0.0000
DLOG(PR) -2.572204 0.942556 -2.728967 0.0071

R-squared 0.993274 Mean dependent var 5.692279

Adjusted R-squared 0.993147 S.D. dependent var 0.670253
S.E. of regression 0.055485 Akaike info criterion -2.921176
Sum squared resid 0.489494 Schwarz criterion -2.845256
Log likelihood 242.0759 Hannan-Quinn criter. -2.890354
F-statistic 7826.904 Durbin-Watson stat 0.140967
Prob(F-statistic) 0.000000

These basic results may be viewed at any time by selecting View/Summary in the object
view menu or by entering the object command
myroll.summary

in the command line.

Next, consider the custom views that have been defined for this object. In addition to the
summary view, you may display information on the coefficient statistics, residual statistics,
likelihood statistics, members of the object, and the standard label information view for the
Roll object:
246—Chapter 9.Examples

Clicking on View/View rolling coefficient statistics... display a dialog prompting you to

select the coefficients and statistics you wish to display. By default, the object will display
the coefficient estimates for all of the coefficients in the regression:

Click on OK to accept the default values and to display a graph of the results in the object
window:
 Examples—247

Equivalently, you could have issued the command:

myroll.rollcoefs c log(gdp) rs dlog(pr)

in the command line.

Note that you could have specified a different statistic in the dialog or add the “stat=”
option to the command to display a different coefficient statistic. For example, selecting P-
values in the dialog or entering,
myroll.rollcoefs(stat=pvals) c log(gdp) rs dlog(pr)

displays the coefficient t-statistic p-values:

248—Chapter 9.Examples

Similarly, you may click on the Proc menu to display a list of the user defined procs:

The first two entries re-initialize the Roll object using the dialogs we first encountered when
creating MYROLL. The next three menu entries extract results into the workfile. For exam-
ple, clicking on Extract rolling residual statistics... opens a dialog prompting you to iden-
tify the results you wish to extract along with the destination:
 Managing User Object Classes—249

2
Clicking on OK t saves the R statistics in the workfile in the series ROLL_R2. The com-
mand
myroll.extractresidstat(stat=r2s) roll_r2

performs an equivalent operation.

It is worth noting that behind-the-scenes in this object is a set of user programs that use
standard EViews programming tools to display dialogs, perform computations, and display
and extract results.

Managing User Object Classes

To manage your user object definitions, select Add-ins/Manage User Objects... from the
main EViews menu.
250—Chapter 9.Managing User Object Classes

EViews will display the User objects management dialog opened to the Installed tab:

The top portion of the dialog shows settings for currently registered user object classes. The
Name column shows the name of the class, the Definition file column displays the location
 Defining a Registered User Object Class—251

and file name of the definition “.INI” file for the class (see “Creating an Object Definition
File” on page 252), and the Version column shows the version number of the user object
class.

Note that you may click on the column headers in the list to sort the list by the contents of
column.

You may use the buttons on the right-hand side of the dialog to manage your classes:
• To add a new user object to the list, simply click on the Add button to display the
Add/Edit User Object dialog. The dialog settings are described in “Registering a User
Object Class” on page 253.
• To delete a class, simply click on the name in the Add-ins management dialog and
press the Remove button.
• To edit the settings of an existing user object class, select it from the list and click on
the Edit button to display the Add/Edit User Object dialog. The dialog settings are
described in “Registering a User Object Class” on page 253.
• To open and edit the INI definition file for the user object class, select it from the list
and click on the Open button.
• To examine the documentation file associated with a class, click on the name and
press the Docs button.
• To check whether the userobj class has an updated version available, and to install the
update if available, click on the Update button. Note you may select multiple classes
at the same time and click the Update button to update the set. You may also right
click anywhere on the list of user object classes and select Update All to update all of
your classes.

Default User Objects Directory

The bottom portion of the Installed tab shows the default user objects directory. The default
directory is where user objects will be installed and where the user object programs will
search for supplementary files if explicit directory locations are not provided. To change the
default directory, click on the button on the right and navigate to the desired directory, or
simply enter the desired folder name. Click on OK to accept the settings.

Defining a Registered User Object Class

To define a registered user object class, you must provide information on how to construct
(create) an instance of the object. While the constructor information is all that is required,
you may optionally specify menu items and custom command names for views and procs
that will execute EViews programs.
252—Chapter 9.Defining a Registered User Object Class

We may divide the registration procedure into two distinct steps:

• Create an object definition file which includes constructor, view, and proc definitions.
• Register the object definition file with EViews.

This discussion assumes that you have already written programs to initialize your object and
possibly to display views and execute procs. These programs will be standard EViews pro-
grams that use ordinary EViews commands. There are, however, several programming fea-
tures which are designed specifically for user object (and Add-in) program development that
you should find useful. See “Add-ins Design Support” on page 230 in the Command and Pro-
gramming Reference.

Creating an Object Definition File

The object definition file is a simple text file with a “INI” extension. This file describes how
to construct the custom object using an EViews program and optionally provides menu
items and custom command names for views and procs that will execute EViews programs.

There are three sections in the file, corresponding to the constructor, the views, and the
procs of the object.

The first section of the definition file should start with a line consisting of the text “[con-
structor]” (without the quotes). The line immediately following should contain the path and
name of an EViews program file that will be used as the constructor. The constructor pro-
gram file describes how the object should be initialized, or constructed, when you create a
new instance using the Object/New Object... menu item or the command line.

The second section contains the view definition specifications. This section should start
with a line consisting of the keyword “[views]”. Each line following this keyword will define
a view for the user object. Each view definition line should consist of the menu text, fol-
lowed by a comma, a custom command name for the view, a comma, the path and name of
the program file to be run when the view is selected from the menu or run from the com-
mand line.

The third section contains the proc definition specifications. It follows the same format as
the views section, but begins with “[procs]” rather than “[views]”.

Note that when providing the path of the programs in your definitions, the “.\” shortcut can
be used to denote the folder containing the definition INI file.

For example, the following is the definition file for the ResStore user object:
[constructor]
".\resstore construct.prg"
[views]
"View stored objects", objects, ".\viewall.prg"
 Defining a Registered User Object Class—253

"View stored equations", equations, ".\viewequations.prg"

"View stored graphs", graphs, ".\viewgraphs.prg"
"view stored tables", tables, ".\viewtables.prg"
[procs]
"Extract objects from store", extractobjects, ".\extract
objects.prg"
"Add objects to store", addobjects, ".\resstore construct.prg"
"Remove objects from store", dropobjects, ".\remove objects.prg"

The ResStore user object use a constructor program called “resstore construct.PRG” which is
called when you create a new ResStore object from the dialogs or command line.

There are four view menu items, each associated with a different EViews program. The first
view definition tells EViews that it should create a view menu item View stored objects and
object command objects, and associate both with the EViews program “viewall.PRG”
(which is located in the ResStore directory). This definition means that selecting View/View
stored objects from the object menu, or entering the object command
my_object.objects

will run the “viewall.PRG” program which displays all of the stored objects in MY_OBJECT.

Similarly, there are three proc menu items. Selecting Proc/Remove objects from store or
issuing the command
my_object.dropobjects

runs the “remove objects.PRG” program which displays a dialog prompting you for the
name of the objects to remove from MY_OBJECT.

Registering a User Object Class

To register a new user object class, select Add-ins/Manage User Objects... from the main
EViews menu to display the User objects management dialog, then click on the Add button
to display the Add/Edit Program dialog.
254—Chapter 9.Defining a Registered User Object Class

The dialog allows you to provide a name for the user object class, to specify the INI file,
attach a documentation file, and provide various object attributes:
• The Object name edit field should be used to specify the user object class name. Note
that if you provide the name of a built-in EViews object, the EViews built-in object
will take precedence.
• The Definition file edit field must be used to enter the name and path of the INI defi-
nition file. Note you may press the “...” button to navigate to and select the file.
• The Documentation file edit field allows you specify a PDF, Text, RTF, Microsoft
Word file, or URL containing documentation for the user object class. (Note that rela-
tive paths are evaluated with respect to the directory of the INI file, not the default
user object directory.)
• You may use the Brief description edit field to describe the purpose of the User
Object.
• You may enter a Version number for your user object and an Update URL indicating
where to find the update XML file (see “XML File Specification” on page 256).

You must provide an object name and a definition file to register your object. The remaining
information is recommended, but not required.

Creating a User Object Package

In “Defining a Registered User Object Class” on page 251 we showed how you can use
EViews program files and an object definition file to register a new user object class for per-
sonal use.

If you wish to distribute your custom object to others, we highly recommend that you create
a user object package. Packaging the user object allows you to bundle all of the files for dis-
 Defining a Registered User Object Class—255

tribution and, if you provide an installer program, offers automatic installation of the object
by dragging-and-dropping the package onto EViews or double clicking on the file.

The process of creating a user object package is virtually identical to packaging of an EViews
Add-in, with a few minor exceptions. We summarize briefly the main steps. Related discus-
sion may be found in.

Creating the Self-installing Package

The process of creating a user object package is straightforward, requiring only two steps:
• (optional) Create a table of contents (TOC) information file and installer program file
to allow for automatic registration and updating of the Add-in.
• Create a self-extracting user object package file containing the object definition file
and any support files (including the TOC and installer program file, if available).

To create the self-extractive file simply create a standard ZIP archive file containing all of the
files for your user object, then rename the ZIP file so that it has the extension “UOPZ”.
Opening such an file, automatically after completing the download, by double clicking on
the file, or by dropping it onto EViews, will begin the automatic installation procedure.

The user object will not, however be automatically installed and registered unless you
include a table of contents (TOC) information file and installer program along with your pro-
gram files. Creating the TOC and installer program files takes only a few minutes and allows
you to support automatic registration and updating of the user object. We strongly recom-
mend that package distributors take the time to create these files as described below.

Table of Contents
Next, you should create a table-of-contents file named “Toc.INI”. The TOC file should con-
tain setup information for the user object which describes the directory in which it should
be installed, and the name of the EViews program, if any, that should be run to register the
user object files. The format of the TOC file is:
[package]
installer = <name of installer file>
folder = <name of folder to create>

A TOC file should always begin with the line “[package]”. The “installer” keyword is used to
indicate the name of the EViews program file that should be run to register the user object.
If, for example, a registration file named “Roll install.PRG” is included in your package, you
should include the line
installer = roll install.prg

The “folder” keyword may be used to indicate the subfolder of the default user object direc-
tory into which you wish to extract the package files. Thus,
256—Chapter 9.Defining a Registered User Object Class

folder = Roll

tells EViews to extract the contents of the UOPZ file into the “Roll” folder of the User Object
directory. If no folder is specified, the basename of the UOPZ file will be used as the target
folder name.

Installer Program
If you wish to facilitate automatic registration of the user object class, you should create a
simple EViews “.PRG” program that uses the adduo command to register the User Object
class. For example, the rolling regression user object described in “Rolling Regression Esti-
mation Object (Roll)” on page 243 may be registered by including the command
adduo(name="roll", version="1.0", desc="Rolling regression
object") ./rolldef.ini

in a program file, and including a reference to this file in the package table-of-contents.

Documentation
We recommend that you provide documentation for your user object, and use the “docs=”
option to point to the documentation file. Providing some documentation for the command
line methods of initializing the object and accessing views and procs is especially important.
Documentation could be anything from a simple text file with some syntax hints, to a
lengthy PDF document that describes the user object features in detail.

Version
You may specify an version number for your user object. Version numbers allow users to use
automatic updating to ensure they have the latest version of the object class definition files.
When a user uses the Update button on the Manage User Objects dialog to check for
updates, EViews will compare the hosted version number with the currently registered ver-
sion number and download the latest version if newer.

You may use the “version=” option to specify the version number. If omitted, EViews will
assume that the user object version number is 1.0.

XML File Specification

One of the most useful user object management features is the ability of users to automati-
cally update their installed user object as newer versions become available. To support this
feature, EViews must know where to look to determine the most recent version of the user
object and where to download any up