PROCMAN

From Agri4castWiki
Jump to: navigation, search


Introduction

PROCMAN is an application, consisting of a collection of packages and datasets, to assist procedures such as CMETEO and LTA_YIELD to do their processing in heterogenous environments (db schemas with different naming conventions and structures etc.).

In PROCMAN you define a procedure, like CMETEO. Also you define processes for which CMETEO can run. Next you list datasets and other objects needed to run the procedure for each process you identified. Relevant datasets/objects can be input or output data, other datasources used to check the process, functions or packages, or even triggers used by the main procedure.

Some or even all objects may be represented by synonyms. Mostly, synonyms are useful to point to the right objects in an environment which can be different depending on the selected process (e.g. in CGMS12EU 2 processes for CMETEO are defined, indicated as Regions and AEZ to aggregated gridded weather to regions or AEZ). PROCMAN will generate the synonyms at the beginning of the run, before the main processing starts.

Also, PROCMAN checks the availability of other objects before the main processing starts. Finally PROCMAN supplies the procedure with values for some parameters needed by the procedure to initiate the process.

Objects used in PROCMAN

As explained above, PROCMAN assists procedures to run their processes in heterogeneous environments. Therefore, the interface is designed to be used primarily by the application, e.g. CMETEO, not by the operator. The user's application is designed to use the API of PROCMAN in order to prepare the environment and to initialise parameters.

PROCMAN stores the configurations in a few tables, as listed below. They are installed in the MRSMAN schema.

table remarks
PRCMN_PROCEDURES holds the procedures to be configured.
PRCMN_PROCESSES definitions of processes to be run with a procedure declared in PRCMN_PROCEDURES
PRCMN_PROCESS_OBJECTS a list, per process, of (database-)objects that are essential to run the process
PRCMN_CONFIGURATIONS per procedure, a list of all possible parameters and their default values. Also, per process, a list of parameters of which the values differs from the default.
PRCMN_PROCESS_RUNS registration of runs of the procedure. It holds the time of starting and ending of a run and some details about the environment and the process.

As the run will normally be registered in PRCMN_PROCESS_RUNS at the very beginning of it, PROCMAN also can use this registration to prevent several runs of the procedure concurrently in one schema. In this way the second run you initiate cannot disturb (i.e. changing the environment through e.g. resetting synonyms) the process running already.


PROCMAN contains the following packages, installed in the database, schema MRSMAN

package remarks
PROCMAN main package that supplies the API for the procedure to prepare the environment and to register the run.
PROCMAN_PROCESS manages some tasks (this package is only used by the package PROCMAN)
PROCMAN_INFO package that supplies the API for the procedure to initialise the parameters for the process
PROCMAN CONFIG package to easily define the parameter list of a procedure and supply default values for them. This package is also used to define parameters, per process, of which the values differs from the default.

The PROCMAN packages uses the tables as listed above, mostly via views that are not explained here. Normally the configuration is defined at the start and does not need to be updated. One can always inspects the contents, either by selecting directly from the tables or via the views.

Interface

The API of PROCMAN is listed as:

package procedure/function remarks
PROCMAN init_procedure_run based on the name of the procedure, it checks conditions. If OK, it will register the run, otherwise it raises an exception.
PROCMAN init_process based on theme and spatial resolution for the procedure, it checks and eventually initialises the environment for the procedure. If it fails an exception is raised.
PROCMAN finish_procedure_run it updates the registration of the run to finish.
PROCMAN_PROCESS not used in the API
PROCMAN_INFO parmvalue4target based on theme, spatial resolution and name of the parameter, it delivers the parameter value for your procedure
PROCMAN CONFIG set_procedure checks the procedure to be registered. If it is not in the table PRCMN_PROCEDURES it inserts the name and returns a positive sign (true). If it is there already it just returns true. If it fails a false is returned.
PROCMAN CONFIG set_process checks the process that to be registered. If it is not in the table PRCMN_PROCESSES it inserts the name and additional items and returns a positive sign (true). If it is there already it just returns true. If it fails a false is returned.
PROCMAN CONFIG configure_default_parameter checks the parameter as belonging to the defaults list of the procedure registered before. If it is not in the table PRCMN_CONFIGURATIONS it inserts the name and default value and returns a positive sign (true). If it is there already the default value may be updated also returning true. If it fails a false is returned.
PROCMAN CONFIG configure_process_parameter checks the parameter as belonging to the list of the process registered before. If it is not in the table PRCMN_CONFIGURATIONS it inserts the name and value and returns a positive sign (true). If it is there already the value may be updated also returning true. If it fails a false is returned.

Examples

To register the run of the procedure and to prepare the environment, the following code needs be inserted, at the very beginning of your procedure:

-- initialise/mark the beginning of the run in PROCMAN using procman.procedure_run

 procman.init_procedure_run(k_procedure);  -- name of the procedure, here: 'cmeteo'

-- check and eventually initialise the environment using procman.init_process

 procman.init_process(  k_procedure    -- name of the procedure, here: 'cmeteo'
                      , p_theme        -- the theme you supplied in the call to run CMETEO, see CMETEO
                      , p_spatial      -- the spatial resolution you supplied in the call to run CMETEO, see CMETEO
                      , null);         -- not used here 

--

For each parameter needed to run CMETEO, the following code needs be executed:

-- find the value for the parameter ROI using procman_info.parmvalue4target

 g_roi_cd      := procman_info.parmvalue4target
                   (p_procedure_cd  => p_procedure  -- name of the procedure, here: 'cmeteo'
                   ,p_user_name     => l_user       -- name of the schema in which you run CMETEO, here: 'cgms12eu'
                   ,p_target        => p_theme      -- the theme you supplied in the call to run CMETEO, see CMETEO
                   ,p_region_tp     => p_spatial    -- the spatial resolution you supplied in the call to run CMETEO, see CMETEO
                   ,p_parameter     => 'roi'        -- the name of the parameter
                   );

After this preparations has been done the registered run can be released:

-- signal PROCMAN to end the run using procman.finish_procedure_run

 procman.finish_procedure_run();


As an example of use of the configuration tool next block code is presented:

declare

 le_catched  exception;
 l_grp_prc1  varchar2(30);
 l_grp_prc2  varchar2(30);
 l_grp_prc3  varchar2(30);
 l_grp_prc4  varchar2(30);
 l_errmsg    varchar2(4000);
 l_succeeded boolean;

begin

 l_succeeded := procman_config.set_procedure('cMeteo','MRSMAN','cmeteo_admin');
 if not l_succeeded
 then
   l_errmsg := 'No procedure created for: cmeteo';
   raise le_catched;  -- exception
 end if;
 l_succeeded := procman_config.set_process
                 ('cMeteo','cmeteo-cgfs14eu-his-regions','cgfs14EU'
                 ,'weather(simulated) his','Regions','cgfs-his','region',
                 );
 if not l_succeeded
 then
   l_errmsg := 'No process created for: cmeteo, cmeteo-cgfs14eu-his-regions';
   raise le_catched;  -- exception
 end if;

--

 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',,'roi', 'text', 'EUR',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',,'destination', 'text', 'weather_his_region',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',,'thresholds grid', 'set of integer', '0',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',,'event id', 'number', '-1',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',,'numeric fractions', 'set of strings'
                 ,'FRAC_AREA_TEMP_MAX,FRAC_AREA_TEMP_MIN,FRAC_AREA_PRECIPITATION,AVG_TEMP',);

--

 l_grp_prc1 := 'FRAC_AREA_TEMP_MAX';
 l_grp_prc2 := 'FRAC_AREA_TEMP_MIN';
 l_grp_prc3 := 'FRAC_AREA_PRECIPITATION';
 l_grp_prc4 := 'AVG_TEMP';

--

 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc1,'source', 'text', 'temp_max',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc2,'source', 'text', 'temp_min',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc3,'source', 'text', 'rainfall',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc4,'source', 'text', 'temp_avg',);

--

 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc1,'thresholds', 'set of number', '25,30,35,40',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc2,'thresholds', 'set of number', '0,-8,-10,-18,-20',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc3,'thresholds', 'set of number', '1,3,5,10,15,30',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc4,'thresholds', 'set of number', '0,2,4,6,8,10',);

--

 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc1,'operator', 'text', 'ge',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc2,'operator', 'text', 'le',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc3,'operator', 'text', 'ge',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc4,'operator', 'text', 'ge',);

--

 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc1,'unit type', 'text', 'unit',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc2,'unit type', 'text', 'unit',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc3,'unit type', 'text', 'unit',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc4,'unit type', 'text', 'remains',);

--

 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc1,'format fraction number', 'text', '9.99',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc2,'format fraction number', 'text', '9.99',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc3,'format fraction number', 'text', '9.99',);
 l_succeeded := procman_config.configure_process_parameter
                 ('cMeteo','cmeteo-cgfs14eu-his-regions',l_grp_prc4,'format fraction number', 'text', '99.9',);

--

 return;

exception

 when le_catched
 then
   dbms_output.put_line(l_errmsg);
 when others
 then
   l_errmsg := substr(sqlerrm,4000);
   dbms_output.put_line(l_errmsg);

end;

/