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 on the ellipsis icon (
), a table constructed from the Sashelp.Company data
set is displayed. To make that 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.