When you first place
an extension node on a process flow diagram, SAS Enterprise Miner
initializes the macro variable, &EM_ACTION, with a value of "CREATE";
any code associated with that action is then executed. This action
occurs before run time (that is, before the process flow diagram is
run) and is the only time the Create action executes. The most common
events that can occur before run time are as follows:
-
-
registering data sets, files, catalogs,
folders, and graphs
-
You initialize properties
using the %EM_PROPERTY macro. Even though you typically provide initial
values for properties in the XML properties file, there are two good
reasons for initializing the properties using code. The first is that
the initial values that you provide in the properties file are validated
only if the process flow diagram is run from the SAS Enterprise Miner
User Interface. However, a process flow diagram can be run using the
%EM5BATCH macro that does not provide a validation mechanism for properties.
The second reason is that %EM_PROPERTY enables you to assign an action
value to each property. As described in the previous chapter, having
properties associated with actions enhances run-time efficiency. To
initialize the properties that were developed as examples in the previous
chapter, include the following in your Create action code:
%macro create;
%em_property(name="StringExample",
value="Initial Value",
action="REPORT");
%em_property(name="BooleanExample",
value="Y",
action="SCORE");
%em_property(name="Integer",
value="20",
action="TRAIN");
%em_property(name="Double",
value="20",
action="TRAIN");
%em_property(name="ChoiceListExample",
value="SEGMENT",
action="TRAIN");
%em_property(name="SASTable",
value="SASHELP.COMPANY",
action="TRAIN");
%em_property(name="Range",
value="20",
action="TRAIN");
%em_property(name="double_range",
value="0.33",
action="TRAIN");
%mend create;
Most nodes generate
permanent data sets and files. However, before you can reference a
file in your code, you must first register a unique file key using
the %EM_REGISTER macro and then associate a file with that key. When
you register a key, Enterprise Miner generates a macro variable named
&EM_USER_key. You use that macro variable in your code to associate
the file with the key. Registering a file allows Enterprise Miner
to track the state of the file, avoid name conflicts, and ensure that
the registered file is deleted when the node is deleted from a process
flow diagram. The information that you provide via %EM_REGISTER is
stored in a table on the Enterprise Miner server. You can use %EM_REGISTER
in Train, Score, or Report actions. However, registering a key involves
an I/O operation on the server, so it is more efficient if you register
all keys in your node's Create action.
In the TableEditor example
in the previous chapter, if a user clicked the ellipsis icon (
![ellipses icon](images/en_ellipses.png)
), a table constructed from the Sashelp.Company data
set is displayed. Before that can happen, you must register the key,
COMPANY (the value of the TableEditor's key attribute), and then
associate that key with the data set Sashelp.Company. That is, you
would include the following code in your Create action:
%em_register(type=data, key=COMPANY, property=Y);
data &EM_USER_COMPANY;
set sashelp.company;
run;
Registering the key,
COMPANY, causes Enterprise Miner to generate the macro variable, &EM_USER_COMPANY,
which initially resolves to the value EMWS#.node-prefix_COMPANY. After
the DATA step is executed, &EM_USER_COMPANY resolves to sashelp.company.
In the example above,
the DATA step that associates the registered key with the file is
located in the Create action. This was done so that the table would
be available to the user from the TableEditor control before run time.
That is not always the case. In most cases the registered file is
used in a Train, Score, or Report action. When you refer to registered
files in your Train, Score, or Report action, you must use the %EM_GETNAME
macro to reinitialize the macro variable &EM_USER_key. The reason
is that when a process flow diagram is closed, the macro variable
&EM_USER_key is annihilated. When you reopen the process flow
diagram and run it, the node's Create action does not execute
again, so &EM_USER_key doesn't get initialized. The registered
information still resides on the server, so you don't have to
register the key again. But you must reinitialize the macro variable
&EM_USER_key using %EM_GETNAME. You can do this just before referencing
&EM_USER_key or you can put all of your calls to %EM_GETNAME together
in a single block of code. Be aware, however, that if you are taking
advantage of actions, a call to %EM_GETNAME must be made in every
source file in which a particular &EM_USER_key is referenced.
For example, suppose that in the example above, &EM_USER_COMPANY
is referenced in both your Train action and your Report action. You
would need a call to %EM_GETNAME in both train.source and report.source.
The reason, again, is the action sequence. Suppose a user ran the
node, changed a Report property setting, and then ran the node again.
In the second run, even if you had a call to %EM_GETNAME in your Train
action, you would still need a call to %EM_GETNAME in your Report
action; the Train action would not be executed in the second run.
Therefore, if you want to put all of the calls to %EM_GETNAME in a
single block of code, it is probably best if you put them in a macro
and then call that macro in every source file in which any of the
registered keys are used.