2 Initialization file

A program using the command interpreter needs an initialization file. This file may be used in two ways. The first way is to let the interpreter read it at the beginning of the execution, the second way is to include it in the executable file (this is explained with more details in section 11). The first way is better if one wants to be able to change some parameters of the program without having to recompile it. The second way is better if one wants to hide some aspects of the program or forbid any modification. This text file has several parts, which are described below. Any line in the initialization file beginning with the character  ;  is supposed to be a comment. Each part of the file (except for the last, which is a list of programs understood by the command interpreter ) begins with a line consisting of a keyword whose first character is a ! , and sometimes ends with a point.

Some sections of the initialization file are optional.
 
 

2.1 Internal parameters

This part of the initialization file must be present and must occur only once. It begins with the keyword  !param , and ends with a line consisting of a point. Between the keyword and the point are 15 lines containing a number.

The 1st number is the maximal number of programs that the interpreter can store. Don't forget to modify this number if you use a lot of programs.

The 2nd number is the maximal number of instructions that a program can have.

The 3rd number if the maximal number of commands that the interpreter can accept. Don't forget to modify this number if you add a lot of commands.

The 4th number is the maximal number of lines that the greeting message can have (cf.  section 2.8).

The 5th number is the maximal number of messages that the interpreter can store (cf. section  2.9).

The 6th number is the maximal number of files that the interpreter can hold (cf. section 8, commands read and write). Of course the user can use other files inside the program using the command interpreter.

The 7th number is the maximal number of running modes (cf. section 2.2).

The 8th number is the maximal number of programs or command files actually running. This is a kind of stack parameter.

The 9th number is the maximal number of conditions that the program can hold. There are two kinds of conditional jumps that can be used in programs understood by the command interpreter (cf.  section 3.4).

The 10th number is the maximal number of object types that the interpreter can accept (cf.  section 5).

The 11th number is the maximal number of arguments of a command.

The 12th number is the maximal number of structure types that the interpreter can accept (cf.  section 5).

The 13th number is the maximal number of labels that can be in a program understood by the interpreter (cf. section 3). Each loop in a program is counted as two labels.

The 14th number is the maximal number of string variables in question files (cf.  section 7).

The 15th number is the maximal number of preceeding commands stored by the interpreter (cf.  section 4,  and section 8, commands history and numcom).
 

Example :

!param
; maximal  number  of  stored  programs
100
; maximal  number  of  lines  in  a  program
200
; maximal  number  of  commands
250
; maximal  number  of  lines  in  the  greeting  message
20
; maximal  number  of  messages
500
; maximal  number  of  open  files
10
; maximal  number  of  running  modes
5
; maximal  number  of  voices
20
; maximal  number  of  conditions
20
; maximal  number  of  object  types
20
; maximal  number  of  function  arguments
10
; maximal  number  of  structure  types
10
; maximal  number  of  labels  in  a  program
100
; maximal  number  of  strings
10
; number  of  known  preceeding  commands
10
.
 
 

2.2 Running modes

This section of the initialization file must be present. This part of the initialization file begins by the line containing the keyword  !mode . In the next line is the prompt that will characterize this running mode. There can be several successive such pairs of lines, defining other running modes. The commands and programs understood by the interpreter, and the objects and structures too, can be defined in such a way that they can be used only in some running modes.

If there are several running modes, the first that is defined as number 0, the second number 1, etc. The actual running mode is contained in the global variable  mode_fonct_ . It controls the prompt that is printed when the program is waiting for a command, and which programs, commands, objects and structures can be used. The user must provide commands to go from a running mode to another. Such a command will change the global variable mode_fonct_  and may perform some initializations before entering the new running mode.

When the interpreter begins the running mode is the first (number 0). When several running modes are needed it is a good idea to keep this first mode empty, that is to use it only to go into the useful running modes. In this case the user should also provide an end command to leave the useful running modes and to go in mode 0.
 

Example : Here 3 running modes are defined in the initialization file :

!mode
----- Mode 0 ---->
!mode
----- Mode 1 ---->
!mode
----- Mode 2 ---->
 
 
 
 

2.3 External parameters

This section of the initialization file is optional. Several such sections can be used. The parameters are integers that can be fixed by the user if needed. For example it may be useful to give a maximal dimension that some arrays can have. This part of the initialization file begins with the keyword  !var  and ends with a line containing a point. Between the first and the last line are several pairs of lines. The first line of a pair contains a parameter name and the second and integer value, associated to the name. For example if the pair

nptx
1000

is given, the value 1000 is associated to the name  nptx . Inside a C-program using the command interpreter, the value 1000 can be recovered from the name  nptx  by something like

int   k;
k = S_convert_int("nptx");

After that, the integer variable k has value 1000 (see  sections 5.3, 6.1  or  9  for a more detailed description of the function  S_convert_int).
 
 

2.4 Data, results and commands directories

This section of the initialization file must be present and can be used only once. It begins with the keyword  !rep  and ends with a line containing a point. Between these two lines are 4 lines, each containing the name of a directory. The first is the directory where the programs and command files understood by the interpreter are stored. The second is the place where results should be stored, and the last are the data directories. The names of these directories are stored in the global variables command_rep , result_rep  and  data_rep  and  data_rep2  respectively. Some commands use the directories of commands and results (see  section 8). The 4 directories can be used by the other commands provided by the user.
 

Example :

!rep
; command  directory
./commands/
; result  directory
./res/
; data  directory 1
./data/
; data  directory 2
./operators/
.
 
 
 

2.5 Definition of objects

This part of the initialization file is optional. It begins with the keyword !def and ends with a line containing a point. Between these two lines the objects types used by the interpreter are defined. See section 5 for a detailed definition of objects. An object is an array (of any number of dimensions) of integers, floating point numbers or complex numbers (in simple or double precision). A definition of an object type will create a command understood by the interpreter. With this command, objects of this type can be created. For example, if the name of the command is defobj1 , a command

defobj1  Obj_x

will create an object of this type whose name is Obj_x . Of course there is a way to recover the array from the name Obj_x , to use it (cf.  section 5). Objects can be also deleted. When an object is created, the appropriate allocations of memory are made and the name is associated to the array.

The definition of an object type begins with a line containing the name of the command that will create these objects.

In the next line is the list of running mode numbers (cf. section 2.2) where the objects will be used. If this line contains the unique number -1, the objects can be used in all the running modes.

The next line contains an integer which must be 0, 1, 2, 3, 4, 5, 6 or 7. It defines the type of data that will be contained in the objects of this type. For example, 0 means that the objects are arrays of integers (see  section 5).

The next line contains a positive integer, which is the number of dimensions of the objects (i.e. of the corresponding arrays).

The next line contains a description of the object type. It is used by the command  list  that gives the list of names of all the objects and structures that have been defined. For example this line may contain

Objects  of  type  1 :

and the command  list  will print on the screen

Objects  of  type  1 :
    Obj_x

if the object  Obj_x  of this type has been defined.

There must be then one line for each dimension of the arrays. Each line contains the name of the corresponding dimension. The way to associate an integer to a name an to recover an integer from a name is explained in section 5. A dimension name can also be one of the parameter names defined in the section !var  of the initialization file (cf. section 2.3). The dimension names must actually be associated to positive integers when a command of creation of an object is executed. This indirect way to fix the size of the objects allows two objects of the same type to be of different sizes. It is also possible to fix a size depending on the context. Of course there is a way to recover the type, number of dimensions and dimensions of an object from its name (cf.  section  5).

The last line of the set of lines describing an object type is the maximal number of objects of this type that can be defined. It can be a positive integer, or a parameter name defined in the section  !var of the initialization file (cf.  section 2.3).
 

Example :

!def
;Objects  of  type  1  (this line is a comment line, beginning with a ;)
defobj1
-1
0
2
Objects  of  type 1 :
ndim1_1
ndim1_2
nb1
;Objects  of  type  2  (comment line)
defobj2
0
2
3
Objects  of  type  2 :
ndim2_1
ndim2_2
ndim2_3
nb2
.

Here two object types are defined. The first type correspond to 2-dimensional arrays of integers, and the second to 3-dimensional arrays of double precision real numbers. The name of the command that creates objects of the first type is  defobj1 , and the name of the command that creates objects of the second type is  defobj2 .

Several such sections can appear in an initialization file.
 
 
 

2.6 Definition of structures

This section of the initialization file is optional. It begins with the keyword  !struct  and ends with a line containing a point. Between these two lines the structure types used by the interpreter are defined. See  section 5 for a detailed definition of structures.

A definition of an structure type will create a command understood by the interpreter. With this command, structures of this type can be created. For example, if the name of the command is  defstruc1 , a command

defstruc1  Struc_x

will create a structure of this type whose name is  Struc_x .

The definition of a structure type begins with a line containing the name of the command that will create the structures of this type.

In the next line in an integer which is the number of members of the structure. The members are object types or structure types previously defined.

Then there are pairs of lines, one pair for each member of the structure. The first line of a pair contains the name of the corresponding member, the second line contains the object (or structure) type of this member (i.e. the name of the command that defines objects (or structures) of this type).

The next line contains a description of the structure type. It is used by the command  list  that gives the list of names of all the objects and structures that have been defined. For example this line may contain

Structures  of  type  1 :

and the command  list  will print on the screen

Structures  of  type  1 :
Struc_x

if the structure  Struc_x  of this type has been defined.

In the next line is the list of running mode numbers (cf. section 2.2) where the structures will be used. If the this line contains the unique number -1, the structures can be used in all the running modes. The last line of the set of lines describing a structure type is the maximal number of structures of this type that can be defined. It can be a positive integer, or a parameter name defined in the section  !var  of the initialization file (cf.  section 2.3).
 

Example :

!struct
; Structures  of  the  first  type  (this is a comment line)
defstruc1
2
member_1
defobj1
member_2
defobj2
Structures  1 :
-1
nb1
; Structures  of  the  second  type  (this is a comment line)
defstruc2
3
member_1b
defobj1
member_2b
defobj2
member_3b
defstruc1
Structures 1 :
0
nb2
.

Here two structure types are defined. The first has two members. The name of the first member is  member_1 , and it is an object of type   defobj1 . The name of the second member is  member_2 , and it is an object of type  defobj2 . The second structure has 3 members. The name of the first member is member_1b , and it is an object of type defobj1 . The name of the second member is member_2b , and it is an object of type defobj2 . The name of the third member is member_3b , and it is a structure of type defstruc1 .
 
 
 
 

2.7 Command names

This section of the initialization file must be present. It begins with a line containing the keyword  !func  and ends with a line containing a point. It contains the names of the commands that are recognized by the interpreter (commands are described more precisely in  section 4). It contains the names of the commands that are implemented by the user of the command interpreter. There are already 52 built-in commands in the library (cf. section 8). The commands defining objects or structures (cf.  sections 2.5 and 2.6) are not present here (they are already defined).

Each command consists of 3 lines.

In the first the name of the command is given.

The second line contains a positive integer, which is the minimal number of arguments of the command (including the name of the command). A command with not enough arguments will be rejected by the interpreter. But commands with a variable number of arguments are allowed. In this case the consistency of the arguments must be checked by the user in the function that realizes the command.

The third line contains a list of integers : the running modes where the command is allowed. If it contains the only integer -1, all the running modes will accept the command. This is the case of all the commands that are implemented in the library.

It is a good idea (but it is not necessary) to give the list of commands in alphabetic order. Of course two commands cannot have the same name. The program must contain somewhere the list of the functions associated to the commands, and in the same order (cf.  section 4).
 

Example : beginning of a section !func

!func
user_com1
4
-1
user_com2
4
-1
user_com3
2
-1
user_com4
4
-1

Several such sections can appear in an initialization file, for example if a program is obtained by glueing several applications of the command interpreter. The names of the built-in commands of the interpreter have not to be defined in a section  !func  (as in the version 1.1 of the command interpreter). Only the commands defined by the user are concerned.
 
 

2.8 Greeting message

This section of the initialization file must be present and unique. It begins with the keyword  !greet  and ends with a line containing a point. It contains the message that is printed on the screen in the beginning of the execution of the command interpreter. No line of this message should begin with a point. Blank lines are allowed.
 

Example :

!greet

______________________________________________
!                                                                               !
!                                                                               !
!                     Command interpreter                           !
!                                                                               !
!_____________________________________________!

.
 
 
 
 

2.9 Messages

This section of the initialization file is optional. It begins with the keyword  !message  and ends with a line containing a point. It contains messages that the user can print on screen during the execution of the program. The function  error_mess (int)  is used to do this. For example the instruction

error_mess(4);

will print the message number four (i.e. the message on the fifth line after the keyword  !message ).
 

Example :

!message
; 0  (this is a comment line, to remember the number of the message)
Message  number  0\n
; 1
Enter  a  positive  real  number :
; 2
Invalid  parameter !\n
; 3
Incorrect  object  name !\n
.

Several such sections can be used in an initialization file. Of course in the case of multiple sections  !message,  the message numbers will be determined by the order of appearance of these sections.
 
 
 

2.10 Initial program

This section of the initialization file is optional. It begins with the keyword  !init , and ends with a point. It has two lines. The first one contains an integer, and the secondthe name of a program or a command (which may have arguments). This program or command will be executed when the interpreter begins to run, and the greeting message (cf.  section 2.8) will not be printed. If the integer is zero, the program or command will run silently.
 
 
 


 

2.11 Inclusion of files

This section of the initialization file is optional. It contains only one line with the name of a new file. This file is read as a part of the current initialization file. When the new file has been read, the old one is continued.
 

Example :

!include
inc.ini
 
 
 

2.12 Programs


The end of the initialization file can contain programs understood by the interpreter. The structure of these programs is exactly the same as for programs that can be loaded during the execution (cf.  section 3). The user should put here the programs that are frequently used.
 
 
 

Main page
Chapters   1   2   3   4   5   6   7   8    9    10   11