Process Template v2 library (Part 1)

void Template_Main (int  (*Process_Event)(), 
---------------------------------------------

This is the Main procedure of the template; contains the loop
of the template, which waits for command messages or event data. 

It gets the addresses of the following procedures from the user 
program: 
Process_Event: is the procedure which processes the event data. 
Process_Command_Composite : is the procedure which handles the
            user defined composite commands (level 3 commands).
Process_Idle : is the procedure to be called periodically when 
                   there are no command messages or event data.

The loop is ended when a command returns a FALSE flag 
(this happens with EXIT command, of course!)

int Template_Init(char *process_name)
-------------------------------------

This is the procedure which contains all standard inits:
Shared Memories, Message Queue, Signals, etc. 

Before adding the entry to the Common Table is checked that
it is not already there and alive.

The process entry is added to the table and its variables
are written in memory.

int check_event(int (*Process_Event)())
---------------------------------------

 
Just call the Process_Event procedure if it exists. 

int check_command(void (*Process_Command_Composite)())
------------------------------------------------------

Extracts commands from the msg queue to the command list.

Process all commands in the command list.
If there is no waiting command message, return TRUE.
Process_Command_Composite is the procedure which handles the 
user defined composite (level 3) commands.

void is_there_command()
-----------------------

Puts in the command list all messages found in the message queue.
Updates the pointers to the first end last element of the list.

int Process_Command(char *string, void (*Process_Command_Composite)())
----------------------------------------------------------------------

Parses the message string, replaces the tokens, and calls the 
corresponding command procedure.
Return the value returned by the command function (FALSE if Exit).

The command might belong to either system level, process level, or 
user level (composite).
System commands procedures are defined in the following of this file,
while process and user commands must be defined in process specific
modules.

string: is the command message which contains the sender process 
name and the command string.   
Process_Command_Composite: is the procedure which handles the user
defined composite commands (level 3 commands). It can be NULL.

void idle(int timeout)
----------------------

Set an idle time in the main loop,
to be used if the Process_Idle is not implemented. 

void Update_Command(char *msg_with_head, int status)
----------------------------------------------------

Store to memory the received command 
and update last_command_status (DONE, FAULT or EXECUTING)

void Update_Command_Status(int status)
--------------------------------------

Update the status of the last received command.

int Exit(char *header, char *arg_string)
----------------------------------------

Exit - system level exit handler 
Updates the status of the process from ALIVE to DEAD, 
and detaches the MsgQ and CT.
Return FALSE to exit the main loop.
It's called with dummy arguments.

int Set(char *header, char *arg_string)
---------------------------------------

Set - system level set command 
Assigns a new value to a variable. 

arg_string: the argument of the set command, that must be    
in the form: "variable_name = value".	

int SetPar(char *header, char *arg_string)
------------------------------------------

SetPar - system level set parameter command 
Assigns new values to multiple variables. 

arg_string: the arguments of the set command, that must be    
in the form: "variable_name1=value1 ... variable_nameN=valueN".	

int Shell(char *header, char *arg_string)
-----------------------------------------

Shell - system level shell command;
processes a UNIX shell command.
arg_string: the arguments of the shell command. 

int Show(char *header, char *arg_string)
----------------------------------------

Show - system level show command;
displays the value of a variable.
header: the name of the process which sends the show command,
arg_string: the arguments of the show command.   

int Tell(char *header, char *arg_string)
----------------------------------------

Tell -  system level tell command;
arg_string: the arguments of the tell command, that must be
in the form: "proc_name command cmd_args"

int Update(char *header, char *arg_string)
------------------------------------------

Update -  system level Update command;
updates the value of one or all process variables in the sh memory.

The argument must be the name of a user or system variable.
Called with no args updates all variables. 

int send_to_single(char *dest, char *msg_with_head, int ack_flag)
-----------------------------------------------------------------

Sends "msg_with_head" to process "dest" on local node;

If the process is there and alive,  writes the message to the 
process message queue and sends a signal to that process.

If the ack_flag is set at TRUE, waits until the destination  
process accomplishes the command execution.

Note: The message should start with the name of the sending process.
This is the responsibility of the programmer who uses this routine.
 

int get_local_ack(char *process_name, char *msg_with_head)
----------------------------------------------------------

Check that the local process "process_name" has received and 
executed the command contained in message.
(first split msg_with_head in sender+command)

int Add_Header(char *raw_msg, char *message)
--------------------------------------------

Adds the name of the sending process to the beginning of 
the message.                                
raw_msg: initial message,                                   
message: message with the header.   

void GetVariable(char *arg_string, char *result_string)
-------------------------------------------------------

Take the name of a process variable as arg_string;

Return a string in the form "arg_string = value"
where the value is read from the local variable of 
the current process (not read from shared memory) 

int SetVariable(char *arg_string, char *ret_string)
---------------------------------------------------

Set the value of a variable (local variable and in shared memory).
(used by command SET)
arg_string must be in the form "variable_name=value_string"

The variable name is extracted by input string and
searched in the user vars;
1) the value is extracted by input string and assigned to 
   the local variable;
2) the shared memory is updated with the new value.
Else the variable name is extracted by input string and
searched in the sys vars;
step 1) and 2)

int Init_Table_and_MsgQ()
-------------------------

Initializes the Common Table and the Message Queue;

void Init_hostname()
--------------------

Initializes the name of local node.

void Init_Signals()
-------------------

Initializes the signal handling.
Set signal handlers for the following signals: 
MSG_SIGNAL=SIGUSR2=17, SIGINT=2, SIGALRM=14, 
BUSY_SIGNAL=SIGQUIT=3, SIGTERM=15.

void cmd_signal_handler()
-------------------------

Handles the signal MSG_SIGNAL <==> "incoming command";
reads the new message in the queue and appends it to the
command list. 

void intr_signal_handler()
--------------------------

Handles an interrupt signal SIGINT.

void dummy()
------------

Handles the  SIGALRM.

void Busy()
-----------

Handles the BUSY_SIGNAL.
Try to change the status of the process in memory to check if it
is really ALIVE.

void Set_Interrupt()
--------------------

Handles the  SIGTERM.

int Create_MsgQ(MSG_Q_ID *msgq_id)
----------------------------------

Creates a new message queue.
msgq_id: id of the new MsgQ. 

int Delete_MsgQ(MSG_Q_ID msgq_id)
---------------------------------

Deletes a message queue.
msgq_id: message queue id of the MsgQ to be detached. 

int Write_to_MsgQ(MSG_Q_ID msgq_id, char *message)
--------------------------------------------------

Adds a string to a MsgQ. 
msgq_id  : message queue id of the MsgQ,   
message: the string that will be added to the MsgQ.  

int Read_from_MsgQ(MSG_Q_ID msgq_id, char *message)
---------------------------------------------------

Reads a string from a MsgQ.
msgq_id  : message queue id of the MsgQ, 
message: the string to where the message read will be placed. 

int Parse_Command_Sys_Part(char *string, char *header, char *arg_string)
----------------------------------------------------------------------

se_Command_Sys_Part - returns a command_code 
opsis
cription
se_Command_Sys_Part(string, header, arg_string) parses a given 
ing based on cmd_dict_sys and returns the command_code.  A sufficient
ch occurs if the given command matches the leading characters of the full
mand.  
ing: the string that will be parsed,                      
der: the name of the sender process,                      
_string : the arguments of the command.  
	 

int Parse_Command_Sys_Exact(char *string, char *header, char *arg_string)
----------------------------------------------------------------------

se_Command_Sys_Exact - returns a command_code 
opsis
cription
se_Command_Sys_Exact(string, header, arg_string) parses a given 
ing based on cmd_dict_sys and returns the command_code if the match is
ct.  
ing: the string that will be parsed,                      
der: the name of the sender process,                      
_string : the arguments of the command.  
	 				 

int Parse_Command_Usr_Part(char *string, char *header, char *arg_string)
----------------------------------------------------------------------

se_Command_Usr_Part - returns the command_code

opsis
cription
se_Command_Usr_Part(string, header, arg_string) parses a given 
ing based on cmd_dict_usr and returns the command_code.  A sufficient
ch occurs if the given command matches the leading characters of the full
mand.  
ing: the string that will be parsed,                      
der: the name of the sender process,                      
_string : the arguments of the command.  
	 

int Parse_Command_Usr_Exact(char *string, char *header, char *arg_string)
----------------------------------------------------------------------

se_Command_Usr_Exact - returns the command_code

opsis
cription
se_Command_Usr_Exact(string, header, arg_string) parses a given 
ing based on cmd_dict_usr and returns the command_code if the match is
ct.
ing: the string that will be parsed,                      
der: the name of the sender process,                      
_string : the arguments of the command.  
	 

void Parse_for_Set(char *arg_string )
-------------------------------------

se_for_Set - pick out variables which can be set from arg_string
opsis
cription
se_for_Set(arg_string) picks out the name of variables and the
ues to which they should be set from arg_string, sets them, and
urns arg_string with these variables/values removed.
_string: the string to be parsed.

int Parse_Var_Sys(char *string, char *rest)
-------------------------------------------

se_Var_Sys - returns the index of the variable
opsis
cription
se_Var_Sys(string, rest) parses a given string based on  
_dict_sys and returns the index of the variable.          
ing: the string that will be parsed,                     
t  : the rest of the string after the first word removed. 

int Parse_Var_Usr(char *string, char *rest)
-------------------------------------------

se_Var_Usr - returns the index of the variable
opsis
cription
se_Var_Usr(string, rest) parses a given string based on   
_dict_usr and returns the index of the variable.          
ing: the string that will be parsed,                      
t  : the rest of the string after the first word removed. 

void Parse(char *string, char *first, char *rest)
-------------------------------------------------

se - parses a given string 
opsis
cription
se(string, first, rest) parses a given string.            
ing: the string that will be parsed,                      
st : the first word in the string,                        
t  : the rest of the string after the first word removed.