Functions

These functions allow you to perform a whole series of operations, including:

  • string or list of strings processing,

  • text replacement,

  • object counting,

  • text file processing,

  • etc.

These functions are executed within a report line and the result of the function is printed in the report output. They can be chained (e.g. @upper(@ttitle(T1)) returns the title of the table named T1 in uppercase).

The general syntax of these functions is:

@function_name(arg1, arg2, ...)

String management

List of strings management

  • @vtake(n, list): take the first n elements of the list (or last n elements if n is negative)

  • @vdrop(n, list): drop the first n elements of the list (or last n elements if n is negative)

  • @vcount(list): return the number of elements in the list

File management

Directory management

Dates and times

Object lists

Object content

Equation content

Simulations

The following functions allow you to obtain the value of certain simulation parameters:

  • @SimEps(): returns the value of the convergence criterion used for the last simulation

  • @SimRelax(): returns the value of the relaxation parameter used for the last simulation

  • @SimMaxit(): returns the value of the maximum number of iterations used for the last simulation

The simulation results by period can be retrieved using the following functions:

  • @SimNiter(period): number of iterations required to solve the model for year period

  • @SimNorm(period): convergence threshold reached when solving the model for year period

FUNCTION @UPPER

This function converts the text passed as an argument to uppercase.

Syntax:

@upper(text)

Example:

@upper("free text")

Result:

FREE TEXT

FUNCTION @LOWER

This function converts the text passed as an argument to lowercase.

Syntax:

@lower(text)

Example:

@lower("Free Text")

Result:

free text

FUNCTION @REPLACE

This function replaces one string with another. The replacement is case-sensitive.

Syntax:

@replace(text,replace_from,replace_by)

Example:

@replace("free text",text,hugs)

Result:

free hugs

FUNCTION @FMT

Formats an integer val according to a given format fmt. The result is a string transformed to the same length as fmt. The recognized characters in the format are: X, x, 9, and 0. They mean that only at the positions of these characters will the characters resulting from formatting val be placed, in their order of appearance. Special case: the character 0 will be replaced by a 0 if the corresponding character in the formatting of val is a whitespace.

Syntax:

@fmt(val,fmt)
where val = integer value
      fmt = format

Example:

@fmt(123,0009)     ---> 0123
@fmt(123,A0000A)   ---> A00123A

Warning

Whitespaces before and after the format are included in the result.

FUNCTION @TAKE

Extracts the first n characters of a string. If n is negative, extracts the last n characters.

Syntax:

@take(n,text)

Example:

@take(3,IODE)
@take(-3,IODE)

Result:

IOD
ODE

FUNCTION @DROP

Removes the first n characters from a string. If n is negative, removes the last n characters.

Syntax:

@drop(n,text)

Example:

@drop(2,IODE)
@drop(-2,IODE)

Result:

DE
IO

FUNCTION @COUNT

Returns the number of elements in a string (these elements are separated by commas , in the string).

Syntax:

@count(list)

Example:

@count(A,B,C,E)
@count(ABC,,,B)

Result:

4
2

FUNCTION @INDEX

Returns the nth element of an IODE list.

Syntax:

@index(n,list)

Example:

@index(2,A,B,C,E)
@index(1,ABC,,,B)

Result:

B
ABC

FUNCTION @SQZ

Removes whitespaces from a string.

Syntax:

@sqz(string)

Example:

@sqz(' ABC D  ')   ---> 'ABCD'

FUNCTION @STRIP

Removes trailing whitespaces from a string.

Syntax:

@strip(string)

Example:

@strip(' ABC D  ')   ---> ' ABC D'

FUNCTION @ANSI

This function converts a string encoded in ASCII to characters encoded in ANSI. It is useful, for example, when generating output files that must be strictly encoded in ANSI (such as HTML files).

Syntax:

@ansi(text)

Example:

<TC>@ansi(Février)</TC>

Result:

<TC>Février</TC>

FUNCTION @EQUAL

Checks if two values are identical.

Syntax:

equal(a,b)
where a and b = any text

Example:

@equal(123,123)    ---> 1 (True)
@equal(123, 123)   ---> 0 (False because of the whitespace)
@equal(%i%,10)     ---> 1 or 0 (True or False depending on the value of i)

Warning

Whitespaces are counted as characters.

FUNCTION @VOID(ARGS)

Empties the text of its arguments, regardless of what the arguments are. For example, calling @chdir() returns the name of the new current directory. With @void(), this text does not appear in the output.

Example:

Here is the result of chdir()  : @chdir(..)
Here is the result with void() : @void(@chdir(..))

Result:

Here is the result of chdir()  : \usr\iode
Here is the result with void() :

FUNCTION @VTAKE(N,VALUES)

Keeps only the first n strings from values. If n is negative, keeps the last n. The separators between the strings in values are defined by the command $vseps. By default, these are ,; and the whitespace. The result is an IODE list whose separator is the first one defined by $vseps.

Warning

The comma , is always a separator, even if it is not included in $vseps.

Syntax:

@vtake(n,values)

Example:

$show @vtake(1,A,B,C)   -> A
$show @vtake(-1,A,B,C)  -> C
$show @vdrop(-1,A,B,C)  -> A,B
$show @vdrop(2,A,B,C)   -> C
$vseps |
$show @vtake(1,A B|C)   -> A B
$show @vtake(1,"A,B"|C) -> A,B
$show @vdrop(-1,A,B,C)  -> A|B

Example:

$vseps ;
$define LIST A;B;C;D
$label next
$define ELEMENT @vtake(1, %LIST%)
   ... Some operation on element %ELEMENT% ...
$define LIST @vdrop(1,%LIST%)
$goto next @vcount(%LIST%)

FUNCTION @VDROP(N,VALUES)

See @vtake.

FUNCTION @VCOUNT(N,VALUES)

This function returns the number of elements in a list of strings.

Syntax:

@vcount({list of strings})

Example:

$vseps |
$show @vcount(A B|C)   -> 2
$show @vcount(A;B;C)   -> 1

See also @vtake.

FUNCTION @FDELETE

This function deletes a file. It does not return any result.

Syntax:

@fdelete(filename)

Example:

@fdelete(test.htm)

Result:

none -> The file test.htm is deleted.

FUNCTION @FAPPEND

This function appends strings to the content of an ASCII file. It does not return any result.

Syntax:

@fappend(filename,text|NL,text,...)
where NL indicates a line break

Example:

Report test.rep
----------------
@fappend(test.htm,"Data file",NL)
@fappend(test.htm,"Parameters:",%*%)

Call
-----
test A B C

Result:

File test.htm
----------------
Data file
Parameters:A B C

FUNCTION @GETDIR ()

Returns the current directory.

Example:

Current directory: @getdir()

Result:

Current directory: c:\usr\iode

FUNCTION @CHDIR(DIRNAME)

Changes the current directory to dirname and returns the new current directory.

Example:

Current directory: @getdir()
New directory: @chdir(..)

Result:

Current directory: c:\usr\iode
New directory: c:\usr

FUNCTION @MKDIR(DIRNAME)

Creates a new directory named dirname. Returns no value.

Example:

Current directory:         @getdir()
Creating subdir:           @mkdir(subdir)
New current directory:     @getdir()

Result:

Current directory:         c:\usr\iode
Creating subdir
New current directory:     c:\usr\iode\subdir

FUNCTION @RMDIR(DIRNAME)

Deletes the directory dirname. Returns no value.

Warning

  • The directory must be empty before it can be deleted.

  • Use with caution…

FUNCTION @DATE

This function returns the current date.

Syntax:

@date([format])
where format indicates the date format
By default, the format is dd-mm-yyyy

Example:

Today's date is @date()
Other format: @date("dd/mm/yy")

Result:

Today's date is 31-05-1999
Other format: 31/05/99

FUNCTION @TIME

This function returns the current time.

Syntax:

@time([format])
where format indicates the time format
By default, the format is hh:mm:ss

Example:

The time is @time()
Other format: @time("hh hours mm minutes")

Result:

The time is 23:12:55
Other format: 23 hours 12 minutes

FUNCTION @MONTH

This function returns the name of a month in a given language.

Syntax:

@month(month[,language])
where language is F, N or E (E by default)

Example:

The name of month number 3 is: @month(3)
In French and uppercase: @upper(@month(3,F))
In Dutch and lowercase: @lower(@month(3,N))

Result:

The name of month number 3 is: March
In French and uppercase: MARS
In Dutch and lowercase: maart

FUNCTION @CHRONORESET()

A timer has been added to allow calculation of processing durations. @ChronoReset() resets the timer to 0. See example in the function @SimEps.

FUNCTION @CHRONOGET()

Returns the elapsed time (in milliseconds) since the last call to @ChronoReset. See example in the function @SimEps.

FUNCTION @CEXPAND

This function returns the list of IODE comments whose name matches one of the strings passed as an argument.

Syntax:

@cexpand(pattern1,pattern2,...)

Example:

@cexpand(A*,B*,AE)

Result:

A1;A2;BA;BCXS;AE

The line:

$Repeat "$DataDuplicateVar _ _1" @vexpand(*)

executes the $DataDuplicateVar command on all variables in the workspace (the new variables are named after the original variable with 1 as a suffix).

See also @eexpand, @iexpand, @lexpand, @sexpand, @texpand and @vexpand

FUNCTION @EEXPAND

This function returns the list of equations whose name matches one of the strings passed as an argument.

Syntax:

@eexpand(pattern1,pattern2,...)

Example:

@eexpand(X*)

Result:

All equations whose name starts with X

See also @cexpand, @iexpand, @lexpand, @sexpand, @texpand and @vexpand

FUNCTION @IEXPAND

This function returns the list of IODE identities whose name matches one of the strings passed as an argument.

Syntax:

@iexpand(pattern1,pattern2,...)

Example:

@iexpand(*_1)

Result:

All identities whose name ends with _1

See also @cexpand, @eexpand, @lexpand, @sexpand, @texpand and @vexpand

FUNCTION @LEXPAND

This function returns the list of IODE lists whose name matches one of the strings passed as an argument.

Syntax:

@lexpand(pattern1,pattern2,...)

Example:

$DataUpdateLst list1 @lexpand(_*)

creates an IODE list list1 containing all lists starting with _.

See also @cexpand, @eexpand, @iexpand, @sexpand, @texpand and @vexpand

FUNCTION @SEXPAND

This function returns the list of IODE scalars whose name matches one of the strings passed as an argument.

Syntax:

@sexpand(pattern1,pattern2,...)

Example:

@sexpand(*)

returns the list of all IODE scalars in the workspace.

See also @cexpand, @eexpand, @iexpand, @lexpand, @texpand and @vexpand

FUNCTION @TEXPAND

This function returns the list of IODE tables whose name matches one of the strings passed as an argument.

Syntax:

@texpand(pattern1,pattern2,...)

Example:

$PrintTbl 1990:5 @texpand(*)

prints all IODE tables in the workspace for the sample 1990 to 1994.

See also @cexpand, @eexpand, @iexpand, @lexpand, @sexpand and @vexpand

FUNCTION @VEXPAND

This function returns the list of IODE variables whose name matches one of the strings passed as an argument.

Syntax:

@vexpand(pattern1,pattern2,...)

Example:

$DataUpdateTbl NEWTBL TITLE;@vexpand(BE*)

creates a table NEWTBL containing all series starting with BE.

See also @cexpand, @eexpand, @iexpand, @lexpand, @sexpand and @texpand

FUNCTION @VLISTE

This function returns the list of IODE variables used in the equations whose names are passed as arguments.

Syntax:

@vliste(eq1,eq2,...)

Example:

$DataUpdateLst VARLST @vliste(@eexpand(*))

creates the list VARLST containing all series used in the equations of the workspace.

See also @sliste.

FUNCTION @SLISTE

This function returns the list of IODE scalars used in the equations whose names are passed as arguments.

Syntax:

@sliste(eq1,eq2,...)

Example:

$DataUpdateLst ScalarLST @sliste(@eexpand(*))

creates the list ScalarLST containing all IODE scalars used in the equations of the workspace.

See also @vliste.

FUNCTION @TTITLE

This function returns the titles of the tables passed as arguments.

Syntax:

@ttitle(tbl1,tbl2,...)

Example:

@ttitle(tbl)

Result:

Table title

FUNCTION @SRELAX

This function returns the relaxation parameter values of the IODE scalars passed as arguments.

Syntax:

@srelax(scl1,scl2,...)

Example:

@srelax(scl)

Result:

0.9

FUNCTION @SSTDERR

This function returns the standard deviation values of the IODE scalars passed as arguments.

Syntax:

@sstderr(scl1,scl2,...)

Example:

@sstderr(scl1)

Result:

0.001

FUNCTION @CVALUE

This function returns the text of the comments whose names are passed as arguments.

Syntax:

@cvalue(cmtname,cmtname,...)

Example:

@cvalue(CMT1,A)

Result:

Comment 1;Comment for A

FUNCTION @VVALUE

This function returns the formatted values of the variables whose names are passed as arguments.

Syntax:

@vvalue(varname,varname,...)

Example:

@vvalue(A,B)

Result:

na na 1.2342 -1.22323 1000 1001 1002 1003

FUNCTION @Sample

This function returns the current sample.

Syntax:

@sample(B|E|)
     B : first period
     E : last period
     empty : first and last periods

Example:

@sample()
@sample(B)
@sample(E)

Result:

1960Y1 1990Y1
1960Y1
1990Y1

FUNCTION @EVALUE

This function returns the LEC formula defining an equation.

Syntax:

@evalue(eqname,eqname,...)

Example:

@evalue(EQ1)

Result:

log(EQ1) := c1 + c2 * V3 + c3 * X

FUNCTION @EQSample(EQNAME)

Returns the estimation sample of the equation eqname.

FUNCTION @EQSampleFROM(EQNAME)

Returns the FROM part of the estimation sample.

In the following example, the first estimation year of the equation ENDO1 is extracted in order to re-estimate the equation on a sample extended to the right (for example, after obtaining new observations).

Example:

$EqsEstimate @eqsamplefrom(ENDO1) 2012Y1 ENDO1

FUNCTION @EQSampleTO(EQNAME)

Returns the TO part of the estimation sample.

See example in @EqSampleFrom.

FUNCTION @EQLHS(EQNAME)

Returns the left-hand side of an equation.

FUNCTION @EQRHS(EQNAME)

Returns the right-hand side of an equation.

FUNCTION @SQLOPEN

Warning

OBSOLETE

Opens an ODBC session with a database. The name of the database (DSN name) you provide is the name with which the database is defined in your ODBC environment (Start > Settings > Control Panel > ODBC 32). For some databases, a username and password are required. On success, you get “1” as a result, otherwise “0”.

Syntax:

@SqlOpen(DSN-name[,Username,Password])

Example:

$goto continue, @SqlOpen(RSZ)
$Show  ODBC-Database not opened
$Return

$label continue
$Show  ODBC-Database opened
....

@SqlClose()

FUNCTION @SQLQUERY

Warning

OBSOLETE

This command executes an SQL query on your database. If the command succeeds, a cursor is created on the “Dynaset” which you can iterate through with SqlNext, until the end of the available data. Place the SQL command between quotes so there is no confusion if you use special characters such as , or ) in your SQL command. Also, group the entire command on one line. On success, you get the number of columns of the “Dynaset” as a result, otherwise “0”.

Warning

You must use @SqlNext() after @SqlQuery() if you want to use the fields of a record.

Syntax:

@SqlQuery("SQL-command")

Example:

$goto continue, @SqlOpen(RSZ)
$Show  ODBC-Database not opened
$Return

$label continue
$Show  ODBC-Database opened
$Show  @SqlQuery("SELECT DISTINCT TRIM FROM RSZ_bruto;")
....

@SqlClose()

FUNCTION @SQLNEXT

Warning

OBSOLETE

This command iterates through the “Dynaset” created by the last SQL command. As long as there are records available in the “Dynaset” you get “1” as a result, otherwise “0”. On success, you get “1” as a result, otherwise “0”.

Warning

You must use @SqlNext() after @SqlQuery() if you want to use the fields of a record.

Syntax:

@SqlNext()

Example:

$goto continue, @SqlOpen(RSZ)
$Show  ODBC-Database not opened
$Return

$label continue
$Show  ODBC-Database opened
$Show  @SqlQuery("SELECT DISTINCT TRIM FROM RSZ_bruto;")
@SqlNext()
$Define BFLD @SqlField(0)

$label again_date
$Show Skipping @SqlField(0)
$goto again_date, @SqlNext()
$Define EFLD @SqlField(0)

$Define BEGIN @replace(%BFLD%,/,Q)
$Define END   @replace(%EFLD%,/,Q)

$WsSample %BEGIN% %END%
....

@SqlClose()

FUNCTION @SQLFIELD

Warning

OBSOLETE

With this command you get the content of the nth field of the current record. On success, you get the content of the field, otherwise “0”.

Warning

You must use @SqlNext() before SqlField() or SqlRecord() works.

Syntax:

@SqlField(field-number)

Example:

$goto continue, @SqlOpen(RSZ)
$Show  ODBC-Database not opened
$Return

$label continue
$Show  ODBC-Database opened
$Show  @SqlQuery("SELECT DISTINCT TRIM FROM RSZ_bruto;")
@SqlNext()
$Define BFLD @SqlField(0)

$label again_date
$Show Skipping @SqlField(0)
$goto again_date, @SqlNext()
$Define EFLD @SqlField(0)

$Define BEGIN @replace(%BFLD%,/,Q)
$Define END   @replace(%EFLD%,/,Q)

$WsSample %BEGIN% %END%
....

@SqlClose()

FUNCTION @SQLRECORD

Warning

OBSOLETE

With this command you get the content of the current record. You get all fields if you do not pass any arguments to the function, or all fields from a certain column with one argument, or all fields between two columns if you provide two arguments. On success, you get the content of the fields, otherwise “0”.

Warning

You must use @SqlNext() before SqlField() or SqlRecord() works.

Syntax:

@SqlRecord() : all fields
@SqlRecord(field1-number) : all fields from field1
@SqlRecord(field1-number,field2-number) : all fields between field1 and field2

Example:

$goto continue, @SqlOpen(RSZ)
$Show  ODBC-Database not opened
$Return

$label continue
$Show  ODBC-Database opened

$Define PIVOT RETOMA_DBF
$Define PREP  RT

$Msg  NBCOLS @SqlQuery("TRANSFORM Sum(RSZ_bruto.%PIVOT%) AS AGGR SELECT
RSZ_bruto.CODRED, NaceTbl.NACE FROM NaceTbl INNER JOIN RSZ_bruto ON
NaceTbl.FICTIF=RSZ_bruto.FICTIF GROUP BY RSZ_bruto.CODRED, NaceTbl.NACE PIVOT
RSZ_bruto.TRIM;")

$Show  @SqlNext()
$label again
$DataUpdateVar %PREP%@SqlField(0)@SqlField(1) %BEGIN% @SqlRecord(2, 8)
$goto again, @SqlNext()

...
@SqlClose()

FUNCTION @SQLCLOSE

Warning

OBSOLETE

Closes the current ODBC session. On success, you get “1” as a result, otherwise “0”.

Syntax:

@SqlClose()

Example:

$goto continue, @SqlOpen(RSZ)
$Show  ODBC-Database not opened
$Return

$label continue
$Show  ODBC-Database opened
....

@SqlClose()

FUNCTION @SIMEPS

Returns the value of the convergence criterion used for the last simulation.

The example below compares performance according to the number of sorts in the simulation algorithm.

Example:

$ Parameters
$ ----------
$define modeldir C:\iode\nemesis
$define model base_neujobs_rd
$define nbtri 5
$define simfrom 2011Y1
$define simto 2012Y1
$define simper %simfrom% %simto%
$ModelSimulateParms 0.00001 0.6 500 Both 0 No 1

$ Output file
$ -----------
$PrintDest compare.html HTML

$ Load fresh files
$ ----------------
$WsLoadVar %modeldir%\%model%
$WsLoadScl %modeldir%\%model%
$WsLoadEqs %modeldir%\%model%

$ ==== $ModelCalcSCC ===
.par1 tit_1
Comparison of performance according to the number of sorts

$ ==== Loop on Tri tests ===
$define i 0
$label nexttri

$ SCC Calculation
$ --------------
$show $ModelCalcSCC %i%
@ChronoReset()
$ModelCalcSCC %i% pre inter post
$define cpu1  @ChronoGet()

$ Simulate
$ --------
$ Reload vars for a clean start and modify exo
$show Reload Vars ...
$WsLoadVar %modeldir%\%model%
$DataUpdateVar RPOIL 2011Y1 1.20

$show $ModelSimulateSCC  %simper% pre inter post
@ChronoReset()
$ModelSimulateSCC %simper% pre inter post
$define cpu2 @ChronoGet()

$ Reporting
$ ---------
.par1 enum_1
Sorts : %i%
.par1 enum_2
SCC Calculation : %cpu1% msec
.par1 enum_2
Simulation (eps = @simeps(); maxit=@simmaxit()) : %cpu2% msec

$define j {%simfrom%}   209  $define totit 0

$label nextsimper
.par1 enum_3
{%j%@T} : conv = @simnorm({%j%@T}), niter = @simniter({%j%@T})
$define simit @simniter({%j%@T})
$define totit {%totit% + %simit%}
$define j {%j% + 1}
$goto nextsimper {%j% <= %simto%}
.par1 enum_3
Total iterations : %totit%
$define i {%i% + 1}
$goto nexttri {%i% <= %nbtri%}

FUNCTION @SIMRELAX()

Returns the value of the relaxation parameter used for the last simulation.

See example in the function @SimEps.

FUNCTION @SIMMAXIT()

Returns the value of the maximum number of iterations used for the last simulation.

See example in the function @SimEps.

FUNCTION @SIMNITER(Period)

Returns the number of iterations required to solve the model for year period.

See example in the function @SimEps.

FUNCTION @SIMNORM (Period)

Returns the convergence threshold reached when solving the model for year period.

See example in the function @SimEps.

Python equivalent functions

To get the Python equivalent of the above IODE commands, refers to the API Reference tables.