PROCMAN
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;
/