Create Action

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:

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.