.. _script:

==========================================
**Run a script file and control the flow**
==========================================

.. role:: red
	  
**Interactive call**
^^^^^^^^^^^^^^^^^^^^

Mask window under menu item **Select Input File**:

.. image:: load_scriptfile_1.png
	   
Submenu **Select Scriptfile**:

.. image:: load_scriptfile_2.png

Select a script file (\*.fsl file) from the **Open exist**. **File** or **Select ScriptFile**

.. image:: load_scriptfile_3.png
	  
**Call with start of FEMAG**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Example** of call in Linux::

 xfemag64 scriptfile.fsl arg1 arg2 arg3
 
**Example** of call in Windows::

 wfemagw64.exe scriptfile.fsl arg1 arg2 arg3

The additional arguments *arg1*, *arg2*, etc. are optional. In the script, these can be accessed as needed through the arg table.

**FSL code fragment** for accessing arguments::

 Narg = table.getn(arg)
 printf("Number of arguments %d", NARG)
 for i=0,Narg do  
  printf("Element %d of table: %s", i,arg[i])
 end 


Output of the above example::
  
 Number of arguments 3
 Element 0 of table: scriptfile.fsl
 Element 1 of table: arg1
 Element 2 of table: arg2
 Element 3 of table: arg3

An argument of the FEMAG call to the left of the specified script file can be accessed with a negative index if necessary.

Example::

 i = -1
 printf("Element %d of table: %s",i,arg[i])

Output::
  
 Element -1 of table: ./path_to_femag_binary/xfemag64

**Influencing resource expenditure**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Additional arguments can be used when calling FEMAG to suppress the appearance of the mask and graphics windows.

**Example:** suppress both windows via the *-b* switch::

 xfemag64 -b scriptfile.fsl arg1 arg2 arg3

**Example:** suppress the mask window via the *-g* switch::

 xfemag64 -g scriptfile.fsl arg1 arg2 arg3

**DXF conversion:** The -c switch creates a DXF file from the node-chain definitions of an FSL file::

 xfemag64 -c scriptfile.fsl 

.. admonition:: Parameter *verbosity*

 Sets the level of output during script execution in the
 
 **Parameter**
 
  | :red:`0` Keine Rückmeldung 
  | :red:`x` Mit Wert von x zunehmender Umfang der Rückmeldung

 **Example**::

   verbosity = 3     -- default level of feedback with additional hints regarding FSL usage
   verbosity = 2     -- default level of feedback
   verbosity = 1     -- supress informativ feedback except for errors and warnings

.. _script-exe:

**Controlling script execution**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. admonition:: Parameter *exit_on_end*

 Sets the behaviour after script execution.

 **Parameter**
  | :red:`true`  FEMAG will be abandoned after script execution
  | :red:`false` FEMAG remains open for further interactive editing

.. admonition:: Parameter *exit_on_error*

 Sets the behaviour after an error during script

 **Parameter**
  | :red:`true`  FEMAG is abandoned after error
  | :red:`false` FEMAG reports errors and remains open

.. admonition:: Command: *stop()*

 Stop script execution

 **Example:**
 ::
   
  calc_field_single(1,restored,0.01)

  stop()           -- End script execution prematurely
  
  color_gradation(0,0,tot,Babs,0,2,"example_Babs.eps")
  save_model(close)

.. admonition:: Command: *error(text)*

 Cancels script execution with an error message.

 **Parameter**
  :red:`Text`  Description of the error

.. admonition:: Command: *sleep(t)*

 Pauses script execution for a specified time t.
		
 **Parameter**
  :red:`t`  Pause time in seconds
  
 **Example:**
 ::
    
  color_gradation(0,0,"tot","ur",0,0,"")
  
  sleep(2)        -- Wait for 2 seconds
  
  color_gradation(0,0,"tot","Babs",0,1500,"")