OxUtils Function Reference

Chapter contents:

info infoinit lockfile
unlockfile PrintMatrix setseed
size TrackInit TrackTime
TrackRoutine TrackReport

info

#include <packages/oxutils/oxutils.h> info(const it, const nofexps);
it
in: int, number of present iteration (0 for initialization, or M_NAN to use an internal count of the number of times the routine was called)
nofexps
in: int, total number of iterations, or M_NAN if unknown

Return value
1 if screen output was given, 0 otherwise.

This function prints information on the screen concerning elapsed/remaining number of iterations and time. If no separate initialization through infoinit is used, each call to info results in timing information printed on the screen. With infoinit, information is only given if a certain number of iterations or seconds has passed.

Example:
See exinfo.ox

infoinit

#include <packages/oxutils/oxutils.h> infoinit(const it, const dTime);
it
in: int, number of iterations between screen outputs, or M_NAN to check only for the time between outputs.
dTime
in: double, minimum time in seconds between screen outputs, or M_NAN to check only for the number of iterations between outputs.

No return value.

This function initializes the info routine, in such a manner that not every call to info results in screen output. If it is called as

infoinit(1000, 5); timing information is printed if it has at least been 5 seconds or 1000 iterations since the last time information was given.

Example:
See exinfo.ox

infotimer, infotimespan, infobugcheck

(deprecated)

Since version 3.10 of Ox, the bug in the timer routines is resolved, and these routines are not needed anymore.

lockfile

#include <packages/oxutils/oxutils.h> lockfile(const sFilebase);
sFilebase
in: string, base for a filename

Return value
Boolean, indicating if the file was succesfully locked

This function can be used to lock a results file, during a simulation. The routine checks for existence of a file <sFilebase>_lock.txt. If this file exists, the routine assumes that the present estimation is already being worked on by a different instance of Ox. If the file does not exist, it is created, and it may be removed afterwards using unlockfile.

Example:
See exlock.ox

unlockfile

#include <packages/oxutils/oxutils.h> unlockfile(const sFilebase);
sFilebase
in: string, base for a filename

No return value

This function deletes <sFilebase>_lock.txt, if it exists. It is meant to be used after the computations have finished, to remove the lock on the file indicated by <sFilebase>.

Example:
See exlock.ox

PrintMatrix

#include <packages/oxutils/oxutils.h> PrintMatrix(const fh, const s0, const aPrFmt, const acLabs, const arLabs, const mX, const bHLine); PrintMatrix(const fh, const s0, const aPrFmt, const acLabs, const arLabs, const mX, const bHLine, const bHLine2, const bEnvironment);
fh
in: File handle, open for writing (if 0, no writing to file)
s0
in: String, for including in upper left corner of table
aPrFmt
in: Array with printing format, see print(). No '&' needed
acLabs
in: Array with column labels
arLabs
in: Array with row labels
mX
in: Data matrix
iHLine
in: Integer, indicating if table should start and end with one or more lines
iHLine2
in: (Optional) Integer, indicating whether columns labels should be separated with one or more lines from the matrix elements
bEnvironment
in: (Optional) Boolean indicating whether begin & end tabular environment should be printed

No return value.

This function prints a LaTeX matrix to a file or to the screen.

Usage:
This function basically works similar to the standard print function, but with LaTeX '&'s included. Also matrices with more than 6 columns can be printed, or with lines longer than 80 characters. Optionally, a LaTeX tabular environment can be printed along, with horizontal lines to distinguish between different parts of the table.

Several generalizations included in the present version of this routine are programmed by Patrick Houweling.

Example:
See extable.ox.

setseed

#include <packages/oxutils/oxutils.h> setseed(iseed);
it
iseed: int, seed for ranseed (if iseed > 0), else iseed is calculated based on current time

No return value.

This function resets the seed based on the current time, if iseed <= 0. If not, iseed is passed to ranseed.

size

#include <packages/oxutils/oxutils.h> size(const ma);
it
ma: matrix of size nxk

Return value:
vX
out: 2 x 1 matrix with value <n ; k>.

This terribly simple function just reports the size of a matrix, saving the need to call rows(ma) and columns(ma) separately.

TrackInit

#include <packages/oxutils/oxutils.h> TrackInit(const asNames);
asNames
in: Array with series of names of routines, or integer. Initializes.

No return value

This routine initialises the tracking routines, by providing an array of names for the routines which are tracked. If instead of an array an integer is given, the timing of the routines is re-initialised, without changing the names.

Example:
See extrack.ox

TrackTime

#include <packages/oxutils/oxutils.h> TrackTime(const iInd);
iInd
in: Integer, index of routine which is entered.

Return value
Integer, index of routine which is left.

With TrackTime(iInd) the routine which is entered is indicated; the routine returns the routine which was left.

By adding lines calling TrackTime in a program, it is possible to profile the computations.

Example:
See extrack.ox

TrackRoutine

#include <packages/oxutils/oxutils.h> TrackRoutine(const bTrack);
bTrack
in: Boolean, indicating if a message is to be printed each time a routine is entered (default=FALSE)

No return value
Example:
See extrack.ox

TrackReport

#include <packages/oxutils/oxutils.h> TrackReport();
No return value
Print a report on the screen with the total and fraction of times spent in each of the routines

Example:
See extrack.ox

Oxutils version 1.1. Changes made on 1-May-2002 by CS Bos