OxMetrics 4 Developer's Kit

OxMetrics 4 Developer’s Kit JURGEN DOORNIK Nuffield College, Oxford OX1 1NF, UK http://www.doornik.com June 27, 2006

Contents 1 2 3 4

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . Exported C-style functions by category . . . . . . . . . . . . OxMetrics data, text and graphics functions, OxMetrics.h

1

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

2 2 3 4

OX M ETRICS D EVELOPER ’ S K IT

2

1 Introduction OxMetrics is an interactive menu-driven graphics-oriented program, which acts as the ‘front-end’ to a series of integrated software modules. These modules obtain their data from OxMetrics and return output and graphics to it. OxMetrics is the component that allows you to load, edit, and save data; transform that data using the OxMetrics calculator or algebra; create a wide variety of graphs, which can be edited, amended and saved in various formats; provide the data for other modules to analyse; receive their text output, results, and graphics; and lets you edit, amend, and save any or all of these as desired. As such, OxMetrics can be seen as an operating system for econometric and statistical modelling. Most statistical software needs such data and graphical services, but the value added is in the special techniques offered, not in these basic services. For small projects the choice is between reinventing and reimplementing the wheel, or settling for a very rudimentary interface. The former can be very costly when the relevant skills need to be acquired, the latter reduces the number of potential users. The advantages of linking to OxMetrics are obvious: no need to create that part of the program which is tedious and much work to develop, and which is tangential to the computational programming (albeit crucial to the usability of the program). Indeed, we have seen several programs which are completely outdated in interface, but implement useful techniques. Such programs could be revived quite quickly in this way. Other advantages of the modularity are: • • • •

front-end can be developed and replaced independently; reduces cost: front-end needs to be purchased only once; reduces program size in memory; increased usability: only one interface to learn.

The OxMetrics services which can be used include: • • • • • •

data input/output, data management, graphical output, text output, program licensing, console services.

Most programs, such as PcGive, access OxMetrics via Ox code using OxPack. Occasionally, programs may wish to communicate directly (TSP is an example). This can be achieved most easily by linking to oxmetrics4.dll. The oxmetrics4.dll dynamic link library hides the communications protocol that OxMetrics 4 uses (DDE under windows, but that may change to sockets at some stage). This chapter documents the functions that are exported by oxmetrics4.dll.

2 Requirements OxMetrics is written in C and C++, and operates under Windows 2000, XP or newer. The oxmetrics4.dll DLL is supplied to facilitate the interaction with OxMetrics. The required header files are installed with the Ox development kit. It is assumed that the headers and libraries for OxMetrics development have been installed in OxMetrics\dev (by default, the OxMetrics directory would be in Program Files). This includes the header and library files: • • • • •

oxmetrics.h – header file for basic services, jdtypes.h – defines some basic types, jdsystem.h – encapsulates system specific settings. gdiconst.h – constants for some graphics functions. oxmetrics4.lib – lib file to facilitate linking to oxmetrics4.dll.

OX M ETRICS D EVELOPER ’ S K IT

3 Exported C-style functions by category Init/exit/general functions ClientIsRegistered OxMetricsDLLVersion OxMetricsFinish OxMetricsInit OxMetricsStartEx OxMetricsStartAdvise OxMetricsStopAdvise SetOxMetricsBlock SetOxMetricsBlockOnShowDialog SendOxMetricsMsg Text functions BatchDone FindFirstText FocusTextWindow PrintText SetBatchCode SetOxCode SetTextMarker SetTextShowMode SetTextWindow ShowTextWindow SpoolText Database functions CreateDb GetDbSample GetDbVar GetDbVarData GetDbVarIndex GetDbVarType GetDefaultDbName GetFirstDbName GetFirstDbVarName GetNextDbName GetNextDbVarName SelectDb SetDbVar Graphics functions CloseDrawWindow DrawAdjust DrawBoxPlot DrawCorrelogram DrawDensity DrawQQ DrawSpectrum DrawZ FocusDrawWindow

3

OX M ETRICS D EVELOPER ’ S K IT

4

IDraw3D IDrawAcf IDrawAxis, IDrawAxis3 IDrawAxisAuto, IDrawAxisAuto3 IDrawHistogram IDrawPLegend IDrawLine IDrawPline IDrawPsymbol IDrawPtext IDrawSymbol, IDrawSymbol3 IDrawText IDrawTimeVector IDrawTitle IDrawVector IDrawXVector OpenDrawWindow SaveDrawWindow SetDrawOptions SetDrawShowMode SetDrawWindow ShowDrawWindow ShowDrawWindowAdd Other functions BufferSWprintf FlushSWprintf SWprintf SWputs

4 OxMetrics data, text and graphics functions, OxMetrics.h BufferSWprintf void BufferSWprintf(bool fStartBuffering) fStartBuffering in: TRUE: start buffering; FALSE: stop buffering No return value. Description Starts buffering of SWprintf calls. Ending the buffering automatically flushes the buffer. Buffering delays sending the text to OxMetrics until the buffer is full, thus reducing the communication overhead. This function is useful when a block of output needs to be sent. When ending buffering FlushSWprintf is called to flush the buffer.

ClientIsRegistered BOOL JDCALL ClientIsRegistered(const TCHAR *sClient, int iVersion100); BOOL JDCALL ClientIsRegisteredA(const char *sClient, int iVersion100); Return value TRUE if OxMetrics has a registration for the named client.

OX M ETRICS D EVELOPER ’ S K IT

5

For example ClientIsRegistered("PcGive", 910) returns TRUE if OxMetrics has a registration for PcGive version 9 or newer (so only the major version number is checked). Call with empty client name to make OxMetrics display registration dialog.

CreateDb BOOL JDCALL CreateDb(const TCHAR *sDbName, int iFreq, int iYear1, int iPeriod1, int iYear2, int iPeriod2, int iOptions); BOOL JDCALL CreateDbA(const char *sDbName, int iFreq, int iYear1, int iPeriod1, int iYear2, int iPeriod2, int iOptions); sDbName in: name of database to create in OxMetrics iFreq in: frequency for database iYear1 in: start year iPeriod1 in: start period iYear2 in: end year iPeriod2 in: end period Return value Returns TRUE if the call succeeded, FALSE otherwise. Description Creates a database in OxMetrics with the specified frequency and sample. If the database already exists, and the frequency does not match, CreateDb will return FALSE. Otherwise, the sample period of the existing database will be extended to match the specified sample period (the sample will not be reduced).

DrawAdjust void JDCALL DrawAdjust(int iObjectNo, int iType, double d1, double d2, double d3, double d4); iObjectNo in: index of graphics object to adjust iType in: type of adjustment (constants defined in gdiconst.h No return value. Description DrawAdjust changes a graphics object. Most drawing functions return the index of the object that was created. See the documentation for DrawAdjust in the Ox book.

DrawBoxPlot void JDCALL DrawBoxPlot(int iArea, VECTOR vY, int cY, const TCHAR *sY, int iLineno); void JDCALL DrawBoxPlotA(int iArea, VECTOR vY, int cY, const char *sY, int iLineno); iArea in: area index vY in: vector with T elements cY in: T , the number of elements in vY sY in: variable name No return value. Description Draws a boxplot of the specified variable.

DrawCorrelogram void JDCALL DrawCorrelogram(int iArea, VECTOR vY, int cY, const TCHAR *sY, int iOrder, int iLineno); void JDCALL DrawCorrelogramA(int iArea, VECTOR vY, int cY, const char *sY, int iOrder, int iLineno);

OX M ETRICS D EVELOPER ’ S K IT

iArea vY cY sY cLag No return value.

in: in: in: in: in:

6

area index vector with T elements T , the number of elements in vY variable name highest lag to be used in correlogram

Description Draws a correlogram which plots the autocorrelation function.

DrawDensity void JDCALL DrawDensity(int iArea, VECTOR vY, int cY, const TCHAR *sY, BOOL fDens, BOOL fHist, BOOL fNormal, BOOL fCdf, BOOL fStand, int cBar, int iIndex); void JDCALL DrawDensityA(int iArea, VECTOR vY, int cY, const char *sY, BOOL fDens, BOOL fHist, BOOL fNormal, BOOL fCdf, BOOL fStand, int cBar, int iIndex); iArea in: area index vY in: vector with T elements cY in: T sY in: variable name fDens in: TRUE: draw estimated density fHist in: TRUE: draw histogram fNormal in: TRUE: add normal density for reference fCdf in: TRUE: draw a graph in area iArea+1 with the QQ plot of the cumulative distribution fStand in: TRUE: use the data in standardized form cBar in: 0: use default bar size; > 0: number of bars iIndex in: line index (0 is background, 1 foreground colour, first line index is 2) No return value. Description Draws the histogram and/or density of the data in the specified area. When fNormal is TRUE, a normal density with the same mean and variance as the data will be drawn.

DrawQQ void JDCALL DrawQQ(int iArea, VECTOR vY, int cY, const TCHAR *sY, int iDist, double dDf1, double dDf2); void JDCALL DrawQQA(int iArea, VECTOR vY, int cY, const char *sY, int iDist, double dDf1, double dDf2); iArea in: area index vY in: T vector cY in: T sY in: variable name iDens in: one of: QQ CHI, QQ F, QQ N, QQ T, QQ U dDf1 in: first parameter for distribution dDf2 in: second parameter for distribution No return value. Description Draws a QQ plot with the 45o line is drawn for reference. The following distributions are supported:

OX M ETRICS D EVELOPER ’ S K IT

QQ QQ QQ QQ QQ

CHI F N T U

7

χ2 (df 1), F(df 1, df 2), N(0, 1), t(df 1), Uniform(0, 1), resulting in a quantile plot.

DrawSpectrum void JDCALL DrawSpectrum(int iArea, VECTOR vY, int cY, const TCHAR *sY, int iOrder, int iLineno); void JDCALL DrawSpectrumA(int iArea, VECTOR vY, int cY, const char *sY, int iOrder, int iLineno); iArea in: area index vY in: T vector cY in: T sY in: variable name iOrder in: lag truncation parameter m No return value. Description Draws the estimated spectral density, which is a smoothed function of the autocorrelations rj .

DrawZ void JDCALL DrawZ(VECTOR vZ, int cZ, const TCHAR *sZ, int iMode, double dFac, int iIndex); void JDCALL DrawZA(VECTOR vZ, int cZ, const char *sZ, int iMode, double dFac, int iIndex); vZ in: vector with T elements cZ in: T , the number of elements in vY sZ in: variable name iMode in: type of Z variable: 1 (symbol size), 2 (draw value), 3 (draw error bar), 4 (draw error band) dFac in: bar/band factor iIndex in: line index (0 is background, 1 foreground colour, first line index is 2) No return value. Description DrawZ adds a Z component to a drawn vector. The call should come immediately after a call to IDrawTimeVector, IDrawVector or IDrawXVector.

FindFirstText int int

JDCALL FindFirstText(const TCHAR *sText, int iOption); JDCALL FindFirstTextA(const char *sText, int iOption); sText in: text to search for iOption in: currently not used

Return value Returns TRUE if the text is found. Description Searching is in the current text window, downwards from the top, and case sensitive.

FlushSWprintf void FlushSWprintf(void); No return value.

OX M ETRICS D EVELOPER ’ S K IT

8

Description Flushes the output buffer.

FocusDrawWindowFocusTextWindow void JDCALL FocusDrawWindow(void); void JDCALL FocusTextWindow(void); No return value. Description FocusDrawWindow() sets focus to OxMetrics and the default graphics window. FocusTextWindow() activates OxMetrics, and sets focus to the client’s output window (also see ShowTextWindow).

GetDbSample int

JDCALL GetDbSample(SAMPLE *pSample); pSample in: NULL, pointer to a variable of type SAMPLE out: sample period of the current database

Return value Returns the number of observations in the database, or 0 if there is no current database. Description Gets the sample of the current database.

GetDbVar GetDbVarData GetDbVarIndex, GetDbVarType,

BOOL BOOL BOOL int int int

JDCALL JDCALL JDCALL JDCALL JDCALL JDCALL sX piLag

GetDbVar(VECTOR vX, int iX, int iT1, int iT2); GetDbVarData(VECTOR vX, int cX, const TCHAR *sX, int *pcT); GetDbVarDataA(VECTOR vX, int cX, const char *sX, int *pcT); GetDbVarIndex(const TCHAR *sX, int* piLag, TCHAR *sVarNameInDb); GetDbVarIndexA(const char *sX, int* piLag, char *sVarNameInDb); GetDbVarType(int iX); in: name of variable in: pointer out: actual lag of variable sVarName in: NULL, or buffer (at least 20 characters) out: name in the database of the variable vX in: VECTOR, sufficiently large to hold the data out: data of the variable iX in: index in current database of variable iT1 in: first observation to get from database iT2 in: last observation to get from database

Return value GetDbVarIndex returns the index in the current database of the variable, or -1 of the variable cannot be found. GetDbVar returns TRUE if the data on the variable was transferred successfully, FALSE otherwise. Description GetDbVarIndex locates the named variable in the database. It can handle lags. E.g. if first variable in the database is CONS, then char sdbname[32]; int var, lag var = GetDbVarIndexA("CONS", &lag, s);

OX M ETRICS D EVELOPER ’ S K IT

9

will set var and lag to 0, s to "CONS". Whereas var = GetDbVarIndexA("CONS_1", &lag, s);

will set var to 0, lag to 1, and s to "CONS". Note that it is possible that the database has a variable called CONS 1. If CONS is also available, the function returns CONS with lag 1, otherwise CONS 1 with lag 0. Similarly, if only CONS 1 is available, and CONS 2 is requested, the function returns CONS 1 with lag 1. GetDbVar gets the actual data on a variable in the current database. The following example illustrates: int ct; VECTOR vx = NULL; ct = GetDbSample(NULL); if (ct > 0) vx = VecAlloc(ct); if (vx) GetDbVar(vx, var, 0, ct - 1); // do something free(vx);

GetDefaultDbName void JDCALL GetDefaultDbName(TCHAR *sDbNameDest); void JDCALL GetDefaultDbNameA(char *sDbNameDest); sDbNameDest in: buffer large enough to hold name (> 64 bytes) out: name of the OxMetrics’s default database No return value. Description Gets the name of OxMetrics’s default database. This can be a different database from the one the client is working on.

GetFirstDbName GetNextDbName GetFirstDbVarName GetNextDbVarName

BOOL BOOL BOOL BOOL BOOL BOOL BOOL BOOL

JDCALL JDCALL JDCALL JDCALL JDCALL JDCALL JDCALL JDCALL sDb sVar

GetFirstDbName(TCHAR *sDb); GetFirstDbNameA(char *sDb); GetNextDbName(TCHAR *sDb); GetNextDbNameA(char *sDb); GetFirstDbVarName(TCHAR *sVar); GetFirstDbVarNameA(char *sVar); GetNextDbVarName(TCHAR *sVar); GetNextDbVarNameA(char *sVar); in: buffer large enough to hold name (> 64 bytes) out: name default database loaded in OxMetrics in: buffer large enough to hold name (> 64 bytes) out: name if variable in currently selected database

Return value Returns TRUE if a name has been copied to the buffer. Description This functions can be used to get all the names of the databases loaded in OxMetrics, and within a selected database to get all the variable names. Note that database names are treated case insensitively, whereas variable names are case sensitive. For example: char sname[128];

SAMPLE sam;

if (GetFirstDbNameA(sname)) {

OX M ETRICS D EVELOPER ’ S K IT

SWprintf("first database: %s\n", sname); while (GetNextDbNameA(sname)) { SWprintf("next database: %s\n", sname); } } /* select the first database, and list the variable names */ if (GetFirstDbNameA(sname) && SelectDbA(sname, &sam)) { SWprintf("contents of: %s\n", sname); if (GetFirstDbVarNameA(sname)) { SWprintf("first variable: %s\n", sname); while (GetNextDbVarNameA(sname)) { SWprintf("next variable: %s\n", sname); } } }

IDraw3D int

JDCALL IDraw3D(int iArea, VECTOR vY, int cY, const TCHAR *sY, VECTOR vX, int cX, const TCHAR *sX, VECTOR vZ, int cZ, const TCHAR *sZ, int iType, int iPalette, int iIndex, int iMode); int JDCALL IDraw3DA(int iArea, VECTOR vY, int cY, const char *sY, VECTOR vX, int cX, const char *sX, VECTOR vZ, int cZ, const char *sZ, int iType, int iPalette, int iIndex, int iMode); iArea in: area index vY in: Y vector with n elements cY in: n, the number of elements in vY sY in: variable name vX in: X vector with k elements cX in: k, the number of elements in vX sX in: variable name vZ in: Z vector with nk or n = k elements cZ in: m = nk or m = n = k, the number of elements in vZ sZ in: variable name iType in: see below iPalette in: palette index (-1 is wireframe, 0 gray, 1 first colour, etc.) iIndex in: line index (0 is background, 1 foreground colour, first line index is 2) iMode in: 2: draw 2D-contour plot (not for raw triangulization) Return value Returns the index of the created graphics object. Description • m = n = k: 3D graph from scatter – iType= −1: raw triangulization – iType= 0: smooth approximating surface • m = nk: 3D graph from table – iType= 0: Z[n][k] stored row-wise in vZ. – iType= 1: Z[k][n] stored column-wise in vZ.

IDrawAcf

10

OX M ETRICS D EVELOPER ’ S K IT

int

JDCALL IDrawAcf(int iArea, VECTOR vY, int cT, int iLength, const TCHAR *sY, BOOL bAcf, BOOL bPacf, BOOL bErrorBand, int iLineno, BOOL fBar); int JDCALL IDrawAcfA(int iArea, VECTOR vY, int cT, int iLength, const char *sY, BOOL bAcf, BOOL bPacf, BOOL bErrorBand, int iLineno, BOOL fBar); iArea in: area index vY in: vector with T elements cY in: T , the number of elements in vY cLag in: highest lag to be used in correlogram sY in: variable name bAcf in: TRUE: plot ACF bPacf in: TRUE: plot PACF bErrorBand in: TRUE: plot errorbands iIndex in: line index (0 is background, 1 foreground colour, first line index is 2) fBar in: TRUE: use bars instead of index lines Return value Returns the index of the created graphics object. Description Draws an autocorrelation function or partial autocorrelation function using the standard definition.

IDrawAxis, IDrawAxis3, IDrawAxisAuto, IDrawAxisAuto3, IDrawPLegend

int

int

int int int

JDCALL IDrawAxis(int iArea, bool fIsXAxis, double dAnchor, double dAxmin, double dAxmax, double dFirstLarge, double dLargeStep, double dSmallStep, int iFreq); JDCALL IDrawAxis3(int iArea, int IsXAxis, double dAnchor, double dAnchor2, double dAxmin, double dAxmax, double dFirstLarge, double dLargeStep, double dSmallStep, int iFreq); JDCALL IDrawAxisAuto(int iArea, bool fIsXAxis, bool fShow, int iAnchor, double dAnchor); JDCALL IDrawAxisAuto3(int iArea, int iIsXAxis, bool fShow, int iAnchor, double dAnchor, double dAnchor2); JDCALL IDrawPLegend(int iArea, int iOffsetX, int iOffsetY, BOOL fHidden);

11

OX M ETRICS D EVELOPER ’ S K IT

iArea fIsXAxis iIsXAxis dAnchor

in: in: in: in:

dAnchor2

in:

dAxmin dAxmax dFirstLarge dLargeStep dSmallStep iFreq fShow iAnchor

in: in: in: in: in: in: in: in:

iOffsetX iOffsetY fHidden

in: in: in:

12

area index TRUE: is X axis, else Y axis 1: X axis, 0: Y axis, 2: Z axis if iAnchor=ANCHOR USER: anchor of the axis (Y location of X, X location of Y and Z axis) if iAnchor=ANCHOR USER: anchor of the 3D axis (Z location of X and Y axis, Y location of Z) axis minimum axis maximum location of first large tick step size between large ticks step size between small ticks frequency (for time series axis) TRUE: show the axis axis anchor location, 0: at minimum, 1: at minimum X pixel offset from top left Y pixel offset from top left TRUE: hide the legend

Return value Returns the index of the created graphics object. Description IDrawAxis draws an axis, fully specified. IDrawAxisAuto draws an axis with automatic design. IDrawPLegend draws the legend. The content is determined by the titles used when drawing vectors.

IDrawHistogram int

JDCALL IDrawHistogram(int iArea, VECTOR vBar, int cBar, double dMin, double dStep, int iIndex, int iColorIn); iArea in: area index vBar in: vector with T elements cBar in: T , the number of elements in vBar dMin in: first X-coordinate of histogram dStep in: bar step size iIndex in: line index (0 is background, 1 foreground colour, first line index is 2) iInside in: inside colour (-1 is default, 0 is white, first line index is 2) No return value. Description Draws an autocorrelation function or partial autocorrelation function using the standard definition.

IDrawLine, IDrawSymbol, IDrawSymbol3, IDrawText, IDrawText3, IDrawPline,

IDrawPsymbol, IDrawPtext int

JDCALL IDrawLine(int iArea, double dX1, double dY1, double dX2, double dY2, int iIndex); int JDCALL IDrawPLine(int iArea, int iX1, int iY1, int iX2, int iY2, int iIndex);

OX M ETRICS D EVELOPER ’ S K IT

int int int int int

int int

int

int int int

13

JDCALL IDrawPSymbol(int iArea, int iX1, int iY1, int iX2, int iY2, int iSymType, int iIndex); JDCALL IDrawPText(int iArea, const char *sText, int iX1, int iY1, int iFontNo, int iFontSize, BOOL fTitle); JDCALL IDrawPTextA(int iArea, const TCHAR *sText, int iX1, int iY1, int iFontNo, int iFontSize, BOOL fTitle); JDCALL IDrawSymbol(int iArea, double dX1, double dY1, double dX2, double dY2, int iSymType, int iIndex); JDCALL IDrawSymbol3(int iArea, double dX1, double dY1, double dZ1, double dX2, double dY2, double dZ2, int iSymType, int iIndex); JDCALL IDrawText(int iArea, const TCHAR *sText, double dX1, double dY1, int iFontNo, int iFontSize, BOOL fTitle); JDCALL IDrawText3(int iArea, const TCHAR *sText, double dX1, double dY1, double dZ1, int iFontNo, int iFontSize, BOOL fTitle, int iRotation); JDCALL IDrawText3A(int iArea, const char *sText, double dX1, double dY1, double dZ1, int iFontNo, int iFontSize, BOOL fTitle, int iRotation); JDCALL IDrawTextA(int iArea, const char *sText, double dX1, double dY1, int iFontNo, int iFontSize, BOOL fTitle); JDCALL IDrawTitle(int iArea, const TCHAR *sText); JDCALL IDrawTitleA(int iArea, const char *sText); iArea in: area index dX1,dY1 in: real-world coordinates dX2,dY2 in: real-world coordinates dZ1,dZ2 in: real-world Z coordinates iX1,iY1 in: pixel coordinates iX2,iY2 in: pixel coordinates iSymType in: symbol type iIndex in: line index (0 is background, 1 foreground colour, first line index is 2) iFontNo in: font number (0 for first font; use -1 for the default font) iFontSize in: font size (e.g. 300; use -1 for the default size) fTitle in: TRUE: is graph title (coordinates are ignored)

Return value Returns the index of the created graphics object. Description IDrawLine and IDrawPline draw a line between the specified coordinates. IDrawSymbol, IDrawSymbol3 and IDrawPsymbol draw a symbol. The coordinates specify the box in which the symbol is drawn. You can use symbol type PL LINE to draw a line. IDrawText and IDrawPtext write text at the specified location.

IDrawTimeVector, IDrawVector, IDrawXVector int int int int

JDCALL IDrawVector(int iArea, VECTOR vY, int cY, const TCHAR *sY, double dXfirst, double dXstep, int iSymbol, int iIndex); JDCALL IDrawVectorA(int iArea, VECTOR vY, int cY, const char *sY, double dXfirst, double dXstep, int iSymbol, int iIndex); JDCALL IDrawTimeVector(int iArea, VECTOR vY, int cY, const TCHAR *sY, int mnYear, int mnPeriod, int iFreq, int iSymbol, int iIndex); JDCALL IDrawTimeVectorA(int iArea, VECTOR vY, int cY, const char *sY, int mnYear, int mnPeriod, int iFreq, int iSymbol, int iIndex);

OX M ETRICS D EVELOPER ’ S K IT

14

int

JDCALL IDrawXVector(int iArea, VECTOR vY, int cY, const TCHAR *sY, VECTOR vX, const TCHAR *sX, int iSymbol, int iIndex); int JDCALL IDrawXVectorA(int iArea, VECTOR vY, int cY, const char *sY, VECTOR vX, const char *sX, int iSymbol, int iIndex); iArea in: area index vY in: T vector cY in: T sY in: variable name mnYear in: year of first observation mnPeriod in: period of first observation iFreq in: frequency of observations dXfirst in: X-value of first observation, x dXstep in: gap between X-values, dx vX in: T vector with x variable iSymbol in: 0: draw line, 1: draw symbols, 2: draw both iIndex in: line index. Note that index 0 is the background colour, and 1 the foreground colour. The first line index is 2 (colours and line types can be set by the OxMetrics user). Return value Returns the index of the created graphics object. Description IDrawTimeVector draws a variable in the specified area against time. IDrawVector draws a variable against an X variable, where the X variable consists of evenly spaced observations x, x + dx , x + 2dx , x + 3dx , . . .. IDrawXVector draws a y variable in the specified area against an x variable. When iSymbol equals 1, each point is marked, but the points are not linked, resulting in a cross plot.

OxMetricsFinish, OxMetricsStart OxMetricsStartEx OxMetricsDLLVersion

BOOL JDCALL OxMetricsStart(const TCHAR *sClient, int iBatchIndex); BOOL JDCALL OxMetricsStartA(const char *sClient, int iBatchIndex); BOOL JDCALL OxMetricsStartEx(const TCHAR *sClient, int iBatchIndex, int iOxMetricsVersion); BOOL JDCALL OxMetricsStartExA(const char *sClient, int iBatchIndex, int iOxMetricsVersion); void JDCALL OxMetricsFinish(); int JDCALL OxMetricsDLLVersion(void); sClient in: name of client application iBatchIndex in: −1, 0: no batch language supported; > 0 : index of batch call-back function (usually 1) < −2 : Console link, -2-iBatchIndex is index of batch call-back function iGiveWinVersion in: 2: for OxMetrics version 2. Return value OxMetricsStart returns TRUE if OxMetrics is started successfully, FALSE otherwise. OxMetricsDLLVersion returns 100 * the current version of the DLL: 200 for version 2. Description OxMetricsStart must be called to start communication with OxMetrics. The default text window is ”Results” for text and ”sClient Graphics” for graphs, where sClient is the name specified in the OxMetricsStart call. OxMetricsFinish closes the connection to OxMetrics.

OX M ETRICS D EVELOPER ’ S K IT

15

OxMetricsInit void OxMetricsInit(); No return value. Description Does not do anything. OxMetricsStart automatically calls OxMetricsInit.

SaveDrawWindow SaveDrawWindow(const sFilename); sFilename in: valid file name No return value. Description Saves the clients graphics window to the specified file. The file format for saving is derived from the extension. The following formats are supported: .eps, .ps and .gwg. Note that, unlike from within OxMetrics, only the specified type is saved. To mimic the OxMetrics operation, save the .gwg whenever an .eps or .ps is saved.

SelectDb BOOL JDCALL SelectDb(const TCHAR *sDbName, SAMPLE *pSample); BOOL JDCALL SelectDbA(const char *sDbName, SAMPLE *pSample); sDbName in: name of database to select pSample in: NULL, pointer to a variable of type SAMPLE out: sample period of the current database Return value Returns TRUE if the selection succeeded, else FALSE. Note that the current database is current to the application, not to OxMetrics. So each application will have its own current database. Description Selects a named database as the current database.

SetDbVar void JDCALL SetDbVar(VECTOR vX, int cX, int iT1, const TCHAR *sX, BOOL fQuery); void JDCALL SetDbVarA(VECTOR vX, int cX, int iT1, const char *sX, BOOL fQuery); sX in: name of variable vX in: data to store cT in: number of observations in vX iT1 in: observation index in database from where vX should be stored (0 if vX should start at the beginning of the database) fQuery in: TRUE if the named variable already exists, a dialog pops up to confirm overwriting; FALSE: an existing variable with the same name is overwritten. No return value. Description Stores a variable in the current database. If necessary, the database is extended to accomodate a variable which has observations beyond the database end.

SetDrawOptions void JDCALL SetDrawOptions(int iOption, int i1, int i2, int i3, int i4, int i5);

OX M ETRICS D EVELOPER ’ S K IT

iOption i1,. . . ,i5 No return value.

16

in: int, option to set in: int, extra arguments

Description See SetDraw in the Ox documentation.

SetDrawWindow, SetTextWindow void void void void

JDCALL JDCALL JDCALL JDCALL sTitle

SetDrawWindow(const TCHAR SetDrawWindowA(const char SetTextWindow(const TCHAR SetTextWindowA(const char in: title of window to be used

*sTitle); *sTitle); *sTitle); *sTitle);

No return value. Description Sets the window to be used for text and graphics output. If these functions are not used, the default is ”Results” for text and ”Program Graphics” for graphs, where Program is the name registered with OxMetricsStart. Also activates the output window, if the default is changed by a call to SetShowMode.

SetDrawShowMode SetTextShowMode void JDCALL SetDrawShowMode(int iMode); void JDCALL SetTextShowMode(int iMode); iMode in: one or more of: SM ACTIVATE SERVER No return value.

SM ACTIVATE VIEW,

Description Sets the default behaviour for ShowDrawWindow() and ShowTextWindow(). The first argument selects the output window for which the show mode is set; for the text: W RESULTS and graphics: W GRAPHICS. SM ACTIVATE VIEW indicates that the output window will be activated, SM ACTIVATE SERVER that OxMetrics will be activated. For example, to switch focus to the output after every show window call: SetShowMode(W_RESULTS | W_GRAPHICS, SM_ACTIVATE_VIEW | SM_ACTIVATE_SERVER);

ShowDrawWindow, ShowDrawWindowAdd, ShowTextWindow void JDCALL ShowDrawWindow(void); void JDCALL ShowDrawWindowAdd(void); void JDCALL ShowTextWindow(void); No return value. Description ShowDrawWindow() shows the graphs for the current graphics window (i.e. the result of the calls to the draw functions). Graphs are build up in memory by OxMetrics, and not displayed until this function is called. The current contents of the graphics window is cleared. The current graphics window is the window named in a call to SetDrawWindow, or else the default OxMetrics Graphics window. Also see SetShowMode. ShowTextWindow() does not directly show anything, but focus behaviour is affected by SetShowMode. Also see FocusTextWindow and FocusDrawWindow. ShowDrawWindowAdd is like ShowDrawWindow, but adds the created graph to the graphics window, without clearing it first. This function should be used with care, as there is an uppr limit on the number of graphs.

OX M ETRICS D EVELOPER ’ S K IT

17

SWprintf SWputs TCHAR * JDCALLC SWprintf(const TCHAR *, ...); void JDCALL SWputs(const TCHAR *sText); fmt in: as for the printf C function Return value Better to be ignored. Description Prints to the OxMetrics text window like the printf function. Text is automatically buffered when the string does not end in \n (use BufferSWprintf to switch buffering on for all text). Warning. The internal buffer is 16K characters long. Make sure that this is not exceeded in one SWprintf call. For writing large chunks of text use SWputs, which is unbuffered if the block is large (the buffer is automatically flushed beforehand if necessary).